Back to Details

telegram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
We drive personal Telegram over MTProto with Telethon — this acts as the user's own account (a "userbot"), so unlike the Bot API it can read full history, list every conversation, and act on anyone the user can reach.
Credentials are injected as env vars by the connector:
  • TELEGRAM_API_ID
    — app id
  • TELEGRAM_API_HASH
    — app hash — secret, never echo
  • TELEGRAM_SESSION_STRING
    — Telethon 
    StringSession
    = full account access. Never log, echo, or print it. Treat it like the account password.
我们通过Telethon基于MTProto驱动个人Telegram——它以用户自有账号的身份运行（即“userbot”），因此与Bot API不同，它可以读取完整的消息历史、列出所有对话，并对用户可接触到的任何对象执行操作。
凭证由连接器作为环境变量注入：
  • TELEGRAM_API_ID
    — 应用ID
  • TELEGRAM_API_HASH
    — 应用哈希 — 保密，绝不能回显
  • TELEGRAM_SESSION_STRING
    — Telethon的
    StringSession
    = 完整账号访问权限。绝不能记录、回显或打印。 请将其视为账号密码。

CLI

命令行界面（CLI）

The skill ships 
scripts/tg.py
 — self-contained (the only third-party dep is 
telethon
, preinstalled in the sandbox). Point a var at the shipped path and call it; no heredoc to re-create per turn, so a multi-step flow (dry-run → confirm) can't lose the helper between calls:
sh
TG="$SKILL_DIR/scripts/tg.py"
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 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.
本技能附带了
scripts/tg.py
——独立运行（唯一的第三方依赖是
telethon
，已预先安装在沙箱中）。将变量指向该文件路径并调用它；无需每次重新创建 heredoc，因此多步骤流程（试运行→确认）不会在调用之间丢失辅助工具：
sh
TG="$SKILL_DIR/scripts/tg.py"
python3 "$TG" whoami
所有会改变状态的命令（
send
、
reply
、
send-file
、
forward
、
edit
、
delete
、
react
、
mark-read
）都有权限控制：如果没有在末尾添加
--confirm
，则仅执行试运行（打印将要执行的操作，但不做任何修改）。读取类命令直接运行。
--confirm
仅在作为最后一个参数时生效，因此消息/说明文字中即使包含“--confirm”也不会意外触发确认。

Verify the connection first

先验证连接

sh
python3 "$TG" whoami
sh
python3 "$TG" whoami

→ {"id": 8367450178, "username": "GermeyAce", "name": "Germey", "phone": "..."}

→ {"id": 8367450178, "username": "GermeyAce", "name": "Germey", "phone": "..."}


On an auth/session error the stored session is dead — tell the user to reconnect at
https://auth.acedata.cloud/user/connections.

如果出现认证/会话错误，说明存储的会话已失效——请告知用户前往https://auth.acedata.cloud/user/connections重新连接。

Read recipes

读取操作指南

GoalCommand
Recent conversations
python3 "$TG" list-chats 20
Only chats with unread (ranked)
python3 "$TG" unread
A chat's history (oldest→newest)
python3 "$TG" get-messages <target> 50
Search inside one chat
python3 "$TG" search <target> "kw" 30
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>
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 name. In message rows, 
out:true
= sent by the user; 
media:true
= has an attachment.
Summarize-unread pattern: 
unread
→ pick the chats that matter → 
get-messages <id> N
on each → summarize. Don't dump 20k messages; sample the most-unread / most-relevant.
目标命令
最近的对话
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>
消息的t.me链接
python3 "$TG" message-link <target> <msg_id>
<target>
可以是数字ID（最可靠——来自
list-chats
的结果）、
@用户名
、手机号或精确的聊天名称。在消息行中，
out:true
表示该消息由用户发送；
media:true
表示消息包含附件。
未读消息总结流程：
unread
→ 选择重要的聊天 → 对每个聊天执行
get-messages <id> N
→ 总结内容。不要直接导出20000条消息；优先选择未读数量最多/最相关的消息样本。

Media

媒体文件操作

sh
undefined
sh
undefined

Download an attachment from a message → returns the saved path

下载消息中的附件 → 返回保存路径

python3 "$TG" download-media <target> <msg_id> ./tg_downloads
python3 "$TG" download-media <target> <msg_id> ./tg_downloads

Send a local file OR an http(s) URL (optional caption) — GATED

发送本地文件或http(s) URL（可选添加说明文字）——需权限确认

python3 "$TG" send-file <target> /path/or/https-url "caption" --confirm

An `http(s)` URL is downloaded to a real local file first (with the right
extension from the URL / `Content-Type`) and then uploaded, so a remote image
lands as a **photo** — not a document, and not a silent failure. This is the
reliable way to "发图": pass the CDN URL straight to `send-file`.

To hand a downloaded file back to the user as a link, upload it to the CDN (see the
`cos-upload` skill) after `download-media`.
python3 "$TG" send-file <target> /path/or/https-url "caption" --confirm

http(s) URL会先被下载为真实的本地文件（根据URL或`Content-Type`获取正确的扩展名），然后再上传，因此远程图片会以**照片**形式发送——而不是文档，也不会静默失败。这是“发图”的可靠方式：直接将CDN URL传给`send-file`即可。

如果要将下载的文件以链接形式返回给用户，请在`download-media`之后使用`cos-upload`技能将其上传到CDN。

Write recipes — all GATED (dry-run unless trailing 
--confirm
)

写入操作指南 — 所有操作需权限确认（未在末尾添加--confirm则仅试运行）

Sending/editing/deleting acts as the real user. Always run the dry run first, show the user exactly what will happen, get an explicit "yes", then re-run with 
--confirm
as the last argument. Never bulk-send.
sh
python3 "$TG" send    <target> "text"                          # → dry_run; add --confirm to send
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
The dry run returns 
{"dry_run": true, "command": ..., "args": [...]}
— present that to the user verbatim as the confirmation prompt.
发送/编辑/删除操作将以真实用户身份执行。请始终先运行试运行，向用户准确展示将要执行的操作，获取明确的“确认”后，再重新运行并将
--confirm
作为最后一个参数添加。切勿批量发送消息。
sh
python3 "$TG" send    <target> "text"                          # → 试运行；添加--confirm以发送
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   # 仅可编辑自己的消息
python3 "$TG" delete  <target> <msg_id> --confirm              # 破坏性操作
python3 "$TG" react   <target> <msg_id> "👍" --confirm
python3 "$TG" mark-read <target> --confirm                     # 发送已读回执
试运行会返回
{"dry_run": true, "command": ..., "args": [...]}
——请将该内容原封不动地呈现给用户作为确认提示。

Gotchas — surface before the user is surprised

注意事项 — 在用户遇到问题前提前告知

  • This is the user's real account. Confirm before any write; reading exposes private chats.
  • FloodWaitError
    : Telegram rate-limits userbots. On a flood-wait of N seconds, tell the user to retry after N — never loop/retry aggressively (escalates toward a ban).
  • Dead session: revoked from Telegram → Settings → Devices, or ~6-month inactivity. On 
    AuthKeyError
    /unauthorized, reconnect the connector (don't retry).
  • Never print 
    TELEGRAM_SESSION_STRING
    / 
    TELEGRAM_API_HASH
     — full-account secrets.
  • Targets: prefer the numeric 
    id
    from 
    list-chats
    (the helper recovers its access hash by 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).
  • edit
    /
    delete
     generally only apply to the user's own messages (admins can delete others in groups they manage).
  • 这是用户的真实账号。执行任何写入操作前请确认；读取操作会暴露私人聊天内容。
  • FloodWaitError
    ：Telegram对userbot有速率限制。如果出现需等待N秒的限流提示，请告知用户N秒后重试——切勿频繁循环/重试（可能导致账号被封禁）。
  • 会话失效：在Telegram设置→设备中撤销了会话，或账号闲置约6个月。如果出现
    AuthKeyError
    /未授权错误，请重新连接连接器（不要重试）。
  • 绝不能打印
    TELEGRAM_SESSION_STRING
    / 
    TELEGRAM_API_HASH
    ——这些是完整账号的保密信息。
  • 目标对象：优先使用
    list-chats
    返回的数字
    id
    （辅助工具会通过扫描对话恢复其访问哈希）；名称需要完全匹配，用户名需要以
    @
    开头。
  • **
    message-link
    **仅适用于公开频道/超级群组；私人一对一聊天/基础群组会返回错误（无可分享的链接）。
  • **
    edit
    /
    delete
    **通常仅适用于用户自己的消息（管理员可在其管理的群组中删除他人消息）。

Record the output

记录输出结果

After you successfully publish and obtain the live result URL, call the built-in 
publish_artifact
tool ONCE so the user can track this deliverable in My Outputs:
publish_artifact(kind="message", channel="telegram", title="<title>", url="<the REAL returned URL>", status="delivered")
Use the real returned URL — never fabricate one. Call it once per published item, only after delivery is confirmed; skip it (or use 
status="failed"
) if publishing failed. See 
_shared/artifacts.md
.
成功发布并获取实时结果URL后，请调用内置的
publish_artifact
工具一次，以便用户在“我的输出”中跟踪该交付物：
publish_artifact(kind="message", channel="telegram", title="<title>", url="<the REAL returned URL>", status="delivered")
请使用真实返回的URL——切勿伪造。每个发布项仅调用一次，且仅在确认交付完成后调用；如果发布失败，请跳过调用（或使用
status="failed"
）。详情请查看
_shared/artifacts.md
。