@acedatacloud/skills 2026.714.2 → 2026.714.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.714.2",
+  "version": "2026.714.4",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/telegram/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: telegram
-description: Full personal Telegram control over MTProto (Telethon) with the user's own account — list/search chats, read & summarize history, see unread, look up contacts & chat info, download media, and send / reply / forward / edit / delete / react / send files / mark read. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading/replying/forwarding/summarizing Telegram messages, their unread Telegram, or sending a file/message on Telegram.
+description: Full personal Telegram control over MTProto (Telethon) with the user's own account — list/search chats, read & summarize history, see unread, look up contacts & chat info, list a forum group's topics, download media, and send / reply / forward / edit / delete / react / send files / mark read / join & leave groups, including posting into a forum topic thread. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading/replying/forwarding/summarizing Telegram messages, their unread Telegram, joining or leaving a Telegram group/channel, posting into a forum group's topic, or sending a file/message on Telegram.
 when_to_use: |
   Trigger for anything on the user's personal Telegram account: list recent
   conversations or just the unread ones, read / summarize a chat or group,
   search one chat or across all chats, look up a contact or a chat's info,
-  download a photo/file from a message, or take an action — send, reply,
-  forward, edit, delete, react, send a file, or mark a chat read. This drives
+  download a photo/file from a message, list a forum group's topics, or take an
+  action — send, reply, forward, edit, delete, react, send a file, mark a chat
+  read, post into a forum topic, or join / leave a group or channel. This drives
   the user's OWN account over MTProto (not a bot), so it sees everything they see.
 connections: [telegram]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.2"
+  version: "1.4"
 ---
 
 We drive **personal** Telegram over MTProto with [Telethon](https://docs.telethon.dev/) —
@@ -42,7 +43,7 @@ python3 "$TG" whoami
 ```
 
 Every state-changing command (`send`, `reply`, `send-file`, `forward`, `edit`, `delete`,
-`react`, `mark-read`) is **gated**: without a trailing `--confirm` it only DRY-RUNS (prints what
+`react`, `mark-read`, `join`, `leave`) is **gated**: without a trailing `--confirm` it only DRY-RUNS (prints what
 it would do, changes nothing). Read commands run directly. `--confirm` is honored **only as the
 last argument** so a message/caption that merely contains "--confirm" can never silently confirm.
 
@@ -67,6 +68,7 @@ https://auth.acedata.cloud/user/connections.
 | Search across ALL chats | `python3 "$TG" search-global "kw" 30` |
 | List contacts | `python3 "$TG" contacts` |
 | Info about a chat/user | `python3 "$TG" chat-info <target>` |
+| List a forum group's topics (threads) | `python3 "$TG" list-topics <target>` |
 | t.me link to a message | `python3 "$TG" message-link <target> <msg_id>` |
 
 `<target>` = numeric id (most reliable — from `list-chats`), `@username`, phone, or exact chat
@@ -100,14 +102,30 @@ argument**. Never bulk-send.
 
 ```sh
 python3 "$TG" send    <target> "text"                          # → dry_run; add --confirm to send
+python3 "$TG" send    <target> "text" --topic <top_message> --confirm  # into a forum topic thread
 python3 "$TG" reply   <target> <msg_id> "text" --confirm
 python3 "$TG" forward <from_target> <msg_id> <to_target> --confirm
 python3 "$TG" edit    <target> <msg_id> "new text" --confirm   # own messages
 python3 "$TG" delete  <target> <msg_id> --confirm              # destructive
 python3 "$TG" react   <target> <msg_id> "👍" --confirm
 python3 "$TG" mark-read <target> --confirm                     # sends read receipts
+python3 "$TG" join    <@username|t.me/link|t.me/+invite> --confirm  # join a public group/channel or a private invite
+python3 "$TG" leave   <target> --confirm                       # leave a group/channel (not private chats)
 ```
 
+`join` accepts a public `@username` / `t.me/<name>` (→ JoinChannelRequest) or a private
+invite link `t.me/+HASH` / `t.me/joinchat/HASH` (→ ImportChatInviteRequest). Joining someone
+else's group is a real membership change on the account — treat it like any other write:
+dry-run, confirm, then `--confirm`. Never auto-join then bulk-message; that gets accounts
+spam-limited.
+
+**Posting into a forum group.** Some supergroups are *forums*: messages live in topics
+(threads), and a plain `send` to the group root is rejected with `TOPIC_CLOSED`. Run
+`list-topics <target>` first, pick a topic with `"closed": false` (an open chat/offtopic
+thread — often titled `Беседка`/`Флуд`/`Chat`/`Offtopic`/`General`), then post with
+`send <target> "text" --topic <top_message> --confirm` (its `top_message` id is the thread
+anchor).
+
 The dry run returns `{"dry_run": true, "command": ..., "args": [...]}` — present that to the
 user verbatim as the confirmation prompt.
 
@@ -123,6 +141,11 @@ user verbatim as the confirmation prompt.
   scanning dialogs); names need an exact match, usernames need a leading `@`.
 - **`message-link`** only works for public channels/supergroups; private 1:1 / basic groups
   return an error (no shareable link exists).
+- **`TOPIC_CLOSED` on send** = a forum supergroup; you can't post to the root. `list-topics`,
+  pick an open (`"closed": false`) thread, and `send ... --topic <top_message>`.
+- **`ChatWriteForbiddenError` on send** = usually a channel's linked *discussion* group: you
+  must be subscribed to the parent channel (`join <parent_channel>`) before you can write in
+  its comment group, even though the group itself doesn't ban posting.
 - **`edit`/`delete`** generally only apply to the user's own messages (admins can delete others
   in groups they manage).
 

package/skills/telegram/scripts/tg.py

@@ -19,10 +19,10 @@ import tempfile
 import urllib.request
 from urllib.parse import urlparse
 
-from telethon import TelegramClient
+from telethon import TelegramClient, errors, utils
 from telethon.sessions import StringSession
 from telethon.tl import functions
-from telethon.tl.types import ReactionEmoji
+from telethon.tl.types import ReactionEmoji, User
 
 API_ID = int(os.environ["TELEGRAM_API_ID"])
 API_HASH = os.environ["TELEGRAM_API_HASH"]
@@ -35,7 +35,7 @@ CONFIRM = bool(_raw) and _raw[-1] == "--confirm"
 a = _raw[:-1] if CONFIRM else list(_raw)
 cmd = a[0] if a else "help"
 args = a[1:]
-GATED = {"send", "reply", "send-file", "forward", "edit", "delete", "react", "mark-read"}
+GATED = {"send", "reply", "send-file", "forward", "edit", "delete", "react", "mark-read", "join", "leave"}
 
 
 def out(o):
@@ -117,6 +117,19 @@ def need(n):
         raise ValueError(f"{cmd} needs {n} argument(s), got {len(args)}")
 
 
+def _pop_opt(argv, name):
+    """Extract `--name VALUE` from argv; return (value_or_None, remaining_argv).
+
+    Only a standalone `--name` token matches, so a message that merely contains
+    the flag text as part of one argument is left untouched.
+    """
+    if name in argv:
+        i = argv.index(name)
+        if i + 1 < len(argv):
+            return argv[i + 1], argv[:i] + argv[i + 2:]
+    return None, argv
+
+
 async def run():
     if cmd in GATED and not CONFIRM:
         out({"dry_run": True, "command": cmd, "args": args,
@@ -185,6 +198,18 @@ async def run():
                 pass
             out(info)
 
+        elif cmd == "list-topics":
+            # Forum-style supergroups organize messages into topics (threads).
+            # A plain send to the group root is rejected (TOPIC_CLOSED); you must
+            # post into an open topic via `send --topic <top_message>`.
+            need(1); ent = await resolve(cl, args[0])
+            limit = int(args[1]) if len(args) > 1 else 100
+            res = await cl(functions.messages.GetForumTopicsRequest(
+                channel=ent, offset_date=0, offset_id=0, offset_topic=0, limit=limit))
+            out([{"id": getattr(t, "id", None), "title": getattr(t, "title", None),
+                  "closed": getattr(t, "closed", None), "hidden": getattr(t, "hidden", None),
+                  "top_message": getattr(t, "top_message", None)} for t in res.topics])
+
         elif cmd == "message-link":
             need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
             try:
@@ -205,9 +230,15 @@ async def run():
 
         # ---- gated writes (need trailing --confirm) ----
         elif cmd == "send":
-            need(2); ent = await resolve(cl, args[0])
-            m = await cl.send_message(ent, args[1])
-            out({"sent": True, "id": m.id})
+            # `--topic <top_message>` posts into a forum topic thread (reply_to);
+            # required for forum-style supergroups where a root send is rejected.
+            topic, sargs = _pop_opt(args, "--topic")
+            if len(sargs) < 2:
+                raise ValueError("send needs <target> <text> (optional --topic <id>)")
+            ent = await resolve(cl, sargs[0])
+            kw = {"reply_to": int(topic)} if topic is not None else {}
+            m = await cl.send_message(ent, sargs[1], **kw)
+            out({"sent": True, "id": m.id, "topic": int(topic) if topic is not None else None})
 
         elif cmd == "reply":
             need(3); ent = await resolve(cl, args[0])
@@ -252,6 +283,33 @@ async def run():
             await cl.send_read_acknowledge(ent)
             out({"marked_read": True})
 
+        elif cmd == "join":
+            need(1); target = args[0]
+            # A public @username / t.me/<user> resolves + JoinChannelRequest; a
+            # private invite (t.me/+HASH, joinchat/HASH, tg://join?invite=HASH)
+            # can't be resolved without joining, so import it by hash directly.
+            link_hash, is_invite = utils.parse_username(target)
+            try:
+                if is_invite:
+                    res = await cl(functions.messages.ImportChatInviteRequest(link_hash))
+                    chat = (getattr(res, "chats", None) or [None])[0]
+                    out({"joined": True, "via": "invite",
+                         "id": getattr(chat, "id", None), "title": getattr(chat, "title", None)})
+                else:
+                    ent = await resolve(cl, target)
+                    await cl(functions.channels.JoinChannelRequest(ent))
+                    out({"joined": True, "via": "public", "id": ent.id,
+                         "title": getattr(ent, "title", None), "username": getattr(ent, "username", None)})
+            except errors.UserAlreadyParticipantError:
+                out({"joined": True, "already_member": True, "target": target})
+
+        elif cmd == "leave":
+            need(1); ent = await resolve(cl, args[0])
+            if isinstance(ent, User):
+                out({"error": "leave applies to groups/channels, not private chats"}); return
+            await cl.delete_dialog(ent)
+            out({"left": True, "id": ent.id})
+
         else:
             out({"error": f"unknown command: {cmd}"}); sys.exit(1)