telegram

我们通过 Telethon 使用 MTProto 操作个人 Telegram — 这会以用户自己的账号（“userbot”）运行，因此与 Bot API 不同，它可以读取完整历史记录、列出每段对话，并与用户能够联系的任何人互动。

连接器会将凭据注入为环境变量：

• TELEGRAM_API_ID — 应用 ID
• TELEGRAM_API_HASH — 应用哈希 — 机密，绝不可回显
• TELEGRAM_SESSION_STRING — Telethon StringSession = 完整账号访问权限。绝不可记录、回显或打印。 将其视为账号密码。

CLI

此技能附带 scripts/tg.py — 独立运行（唯一的第三方依赖是沙盒中已预装的 telethon）。将变量指向附带脚本的路径并调用即可；无需每轮都用 heredoc 重新创建脚本，因此多步流程（试运行 → 确认）不会在两次调用之间丢失辅助脚本：

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block below).
TG="$SKILL_DIR/scripts/tg.py"; [ -f "$TG" ] || TG=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tg.py' 2>/dev/null | head -1)
[ -f "$TG" ] || { echo "telegram script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TG" whoami

所有会更改状态的命令（send、reply、send-file、forward、edit、delete、 react、mark-read、join、leave）都需要确认：如果末尾没有 --confirm，则只会试运行（打印将要执行的操作，不会做任何更改）。读取命令会直接运行。只有当 --confirm 是最后一个参数时才会生效，因此即使消息或说明文字中仅包含“--confirm”，也绝不会导致意外确认。

首先验证连接

python3 "$TG" whoami
# → {"id": 100000000, "username": "<the connected handle>", "name": "<display name>", "phone": "..."}

如果出现身份验证或会话错误，则存储的会话已失效 — 请告知用户前往 https://studio.acedata.cloud/console/connectors 重新连接。

读取操作示例

目标	命令
最近的对话	python3 "$TG" list-chats 20
仅显示有未读消息的聊天（按优先级排序）	python3 "$TG" unread
某个聊天的历史记录（从最早到最新）	python3 "$TG" get-messages <target> 50
在单个聊天中搜索	python3 "$TG" search <target> "kw" 30
搜索所有聊天	python3 "$TG" search-global "kw" 30
列出联系人	python3 "$TG" contacts
查看聊天或用户信息	python3 "$TG" chat-info <target>
列出论坛群组的主题（话题串）	python3 "$TG" list-topics <target>
获取消息的 t.me 链接	python3 "$TG" message-link <target> <msg_id>

<target> = 数字 ID（最可靠，可从 list-chats 获取）、@username、电话号码或聊天的准确名称。在消息行中，out:true = 用户发送；media:true = 有附件。

汇总未读消息的流程：运行 unread → 选出需要关注的聊天 → 对每个聊天运行 get-messages <id> N → 汇总。不要倾倒 2 万条消息；抽取未读最多或最相关的内容。

媒体

# Download an attachment from a message → returns the saved path
python3 "$TG" download-media <target> <msg_id> ./tg_downloads
# Send a local file OR an http(s) URL (optional caption) — GATED
python3 "$TG" send-file <target> /path/or/https-url "caption" --confirm

会先将 http(s) URL 下载为实际的本地文件（根据 URL / Content-Type 使用正确的扩展名），然后再上传，因此远程图片会作为照片发送 — 而不是文档，也不会无声失败。这是“发图”的可靠方式：将 CDN URL 直接传给 send-file。

若要将下载的文件作为链接交还给用户，请在运行 download-media 后将其上传到 CDN（参见 cos-upload 技能）。

编写操作指南 — 全部受控（除非末尾带有 --confirm，否则均为试运行）

发送、编辑或删除操作都将以真实用户的身份执行。始终先运行试运行，准确展示将要执行的操作，取得明确的“是”后，再将 --confirm 作为最后一个参数重新运行。切勿批量发送。

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 接受公开的 @username / t.me/<name>（→ JoinChannelRequest），或私密邀请链接 t.me/+HASH / t.me/joinchat/HASH（→ ImportChatInviteRequest）。加入他人的群组会实际更改账号的成员身份——应像处理其他写操作一样处理：试运行、确认，然后使用 --confirm。切勿自动加入后再批量发送消息；这会导致账号受到垃圾信息限制。

在论坛群组中发帖。 有些超级群组是论坛：消息位于话题（线程）中，直接向群组根目录执行普通 send 会被拒绝，并返回 TOPIC_CLOSED。先运行 list-topics <target>，选择 "closed": false 的话题（开放的聊天/闲聊线程——通常名为 Беседка/Флуд/Chat/Offtopic/General），然后使用 send <target> "text" --topic <top_message> --confirm 发帖（其 top_message id 是线程锚点）。

试运行会返回 {"dry_run": true, "command": ..., "args": [...]}——将其原样展示给用户，作为确认提示。

注意事项 — 在用户遇到意外前说明

• 这是用户的真实账号。 任何写操作前都必须确认；读取操作会暴露私密聊天。
• FloodWaitError：Telegram 会对用户机器人进行限流。遇到 N 秒的 flood-wait 时，告知用户 N 秒后重试——切勿循环或激进地重试（这会加大被封禁的风险）。
• 失效的会话：会话可能已在 Telegram → Settings → Devices 中被撤销，或因约 6 个月未活动而失效。遇到 AuthKeyError/unauthorized 时，重新连接连接器（不要重试）。
• 切勿打印 TELEGRAM_SESSION_STRING / TELEGRAM_API_HASH——它们是完整账号的机密信息。
• 目标：优先使用 list-chats 返回的数字 id（助手会扫描对话并找回其 access hash）；名称必须完全匹配，用户名必须以 @ 开头。
• message-link 仅适用于公开频道/超级群组；私密的一对一聊天/普通群组会返回错误（不存在可分享的链接）。
• 发送时出现 TOPIC_CLOSED = 这是一个论坛超级群组；无法向根目录发帖。运行 list-topics，选择一个开放的（"closed": false）线程，然后执行 send ... --topic <top_message>。
• 发送时出现 ChatWriteForbiddenError = 通常是频道关联的讨论群组：必须先订阅所属频道（join <parent_channel>），才能在其评论群组中发言，即使该群组本身并未禁止发帖。
• edit/delete 通常只能操作用户自己的消息（管理员可以删除其管理的群组中的他人消息）。

记录输出

成功发布并获取实际结果 URL 后，调用一次内置的 publish_artifact 工具，让用户可以在 My Outputs 中跟踪此交付内容：

publish_artifact(kind="message", channel="telegram", title="<title>", url="<the REAL returned URL>", status="delivered")

使用实际返回的 URL——切勿捏造。每个已发布内容仅调用一次， 且仅在确认交付后调用；如果发布失败，则跳过（或使用 status="failed"）。 请参阅 _shared/artifacts.md。