init

2026-05-04 23:12:53 +03:00 · 2026-05-04 23:12:53 +03:00 · 343169a973
commit 343169a973
8 changed files with 1783 additions and 0 deletions
--- a/skill/skill.md
+++ b/skill/skill.md
@ -0,0 +1,118 @@
+---
+name: telegram-reader
+description: Read-only access to Telegram via tg-proxy API. Use when the user asks about recent messages, wants to search chats, or needs inbox summary.
+---
+
+# Telegram Reader
+
+Read-only interface to wzray's Telegram via `https://tg-proxy.wzray.com`.
+
+## Endpoints
+
+Base URL: `https://tg-proxy.wzray.com`
+
+### 1. Get Chats
+```bash
+curl -s "https://tg-proxy.wzray.com/chats?limit=50&offset=0"
+```
+Returns: `{"items": [{id, title, type, chat_type, muted, archived, folder_id, folder_ids, pinned, ...}], "limit", "offset", "has_more", "remaining_count"}`
+
+Supported query params:
+- `limit`
+- `offset`
+- `archived=true|false`
+- `chat_type=direct|bot|group|channel`
+- `folder_id` — filter chats by Telegram folder/dialog filter id (get list from `/folders`)
+
+### 2. Get Folders
+```bash
+curl -s "https://tg-proxy.wzray.com/folders"
+```
+Returns: `[{id, title, type, icon_emoji, pinned_chat_ids, include_chat_ids, exclude_chat_ids, contacts, non_contacts, groups, broadcasts, bots, exclude_muted, exclude_read, exclude_archived, has_my_invites}]`
+
+### 3. Get Messages in Chat
+```bash
+curl -s "https://tg-proxy.wzray.com/chats/{chat_id}/messages?limit=50&offset=0"
+```
+Returns: `{"chat": {...}, "items": [{id, date, text, from_user, chat_id, from_me, is_outgoing, reply_to_message_id, quoted_text, reply_snippet, edited_at, is_read, attachments}], "limit", "offset", "has_more"}`
+
+### 4. Get Messages Delta
+```bash
+curl -s "https://tg-proxy.wzray.com/chats/{chat_id}/delta?since=2026-02-16T06:00:00Z&limit=50&offset=0"
+```
+Returns: `{"chat": {...}, "items": [...], "limit", "offset", "has_more", "remaining_count"}`
+
+Notes:
+- `since` is required for `delta`
+- `delta` returns messages in chronological order
+- `offset` is applied inside the filtered `since` window
+- `remaining_count` is present where the server can compute it cheaply and accurately
+- `null` fields are omitted from JSON output
+- responses are pretty-printed JSON
+
+## State
+
+State stored in: `runtime/telegram-reader/state.json` (gitignored, persists locally)
+
+```json
+{
+  "last_check": "2026-02-16T10:30:00Z",
+  "watched_chats": [-1003680985286, ...],
+  "watched_names": {"-1003680985286": "is-tech-y28", ...},
+  "last_message_ids": {}
+}
+```
+
+## JS Client
+
+`skills/scripts/telegram-reader/tg-client.js` — удобный CLI для API:
+
+```bash
+# List folders
+node skills/scripts/telegram-reader/tg-client.js get-folders
+
+# List chats
+node skills/scripts/telegram-reader/tg-client.js get-chats --limit 50
+
+# Only archived groups
+node skills/scripts/telegram-reader/tg-client.js get-chats --archived true --chat-type group
+
+# Filter chats by folder
+node skills/scripts/telegram-reader/tg-client.js get-chats --folder-id 2
+
+# Filter chats (client-side)
+node skills/scripts/telegram-reader/tg-client.js filter-chats --active-last-week --not-muted --type=direct
+
+# Get delta
+node skills/scripts/telegram-reader/tg-client.js delta 5880803391 "2026-02-16T00:00:00Z"
+```
+
+## Behavior
+
+### On Heartbeat (hourly)
+1. Load state
+2. For each watched chat, get delta since `last_check`
+3. Filter important messages:
+   - Mentions (@wzray)
+   - Keywords: "важно", "срочно", "deadline", "сегодня"
+   - Unread DMs
+4. Summarize and notify if significant
+5. Update `last_check` to now
+
+### When User Asks
+- "Что нового?" → run delta since last_check, summarize
+- "Что писал [кто-то]?" → search in recent messages
+- "Покажи чаты" → list chats from API
+
+## Priority Filters
+
+For heartbeat summaries, prioritize:
+1. DMs with unread/unanswered messages
+2. Messages mentioning user
+3. Messages with urgency keywords
+4. Pinned/important chats
+
+Ignore:
+- Channels (unless user explicitly watches them)
+- Muted chats
+- Large groups with high traffic (unless mentioned)