tg-cli

tg-cli（命令名为 tg）是一个为 AI 编码代理设计的 Telegram 桥接工具。它由两部分组成：一个由代理调用以推送更新的出站 CLI，以及一个将您的回复从手机传回运行中的代理会话的入站守护进程 tg-ctl。 出站功能：代理可发送文本、HTML 报告、照片和文件。系统会自动检测 HTML 标签，并为检测到的代理添加品牌 emoji 前缀。Markdown 文件在上传前通过 pandoc 和 headless Chrome 转换为 PDF，若转换失败则发送原文件。消息文本中提到的文件路径会通过在工作树中进行递归搜索自动检测并附加，路径保留在说明文字中。 在发送前会运行多个保护机制。如果消息过长导致需要分段发送超过六次，系统将直接拒绝并告知字符数和分段数。敏感文件永远不会被附加，包括 .env 文件、SSH 私钥、pem/key/p12/pfx/ppk、凭据 rc 文件、shell 历史记录、tfvars、credentials.json 和 kubeconfig；自动检测到的提及将被跳过，而显式的文件参数将导致硬错误。乱码令牌保护机制会拦截嵌入在拉丁或西里尔词汇中的单个 CJK 字符，以及脚本切换两次或更多的令牌，但允许真正的双语文本。截图保护机制会拒绝提及截图但未附加照片的消息。字典网关将用户维护的 JSON 文件中的禁用词与每次发送的标题、正文和说明进行匹配，且设计上没有绕过标志；格式错误的文件将导致发送失败。自动链接通过 linear CLI 解析 Linear 票据 ID，通过 gh 解析 GitHub PR/issue 编号，结果缓存一小时，失效后降级为纯文本。可以通过 no-feature 标志关闭单个功能。 入站功能：当检测到代理在 tmux 面板中进行首次出站发送时，tg-ctl 会自动启动。来自 Telegram 的纯文本回复将被注入到该代理的面板中。通过引用回复消息会附加一个命名被回答消息的引用锚点，且 tg replies 命令可以拉回完整的原始消息。/agent 命令可将消息路由到特定代理，支持窗口名称的模糊匹配（且兼容西里尔字母）；在歧义时提供按会话分组的选择按钮，在无参数调用时提供代理列表。 在 tmux 之外启动的代理没有面板，将被列为不可达并注明原因，转而通过 Stop-hook 收件箱获取第二通道，该收件箱在每次轮次结束时被读取。README 中明确指出该限制：处于空闲状态的代理仅在下次完成轮次时才会收到排队的消息。tg-ctl inbox 命令可显示排队内容。 Question-to-buttons 功能将代理的问题和权限提示作为内联按钮转发到 Telegram，因此您可以通过点击来回答，答案将直接注入回面板。它涵盖了 Claude Code 的问题和权限形式、Codex PermissionRequest 以及 opencode 的 question.asked 和 permission.asked 事件，并通过 install-hooks 命令幂等地配置，该命令会备份并保留现有设置。在问题待处理期间发送的消息将被推迟而非中断提示，超时的问题卡片仍可用纯文本回答。 命令包括 stop（中断当前轮次）、kill、status、limit（每个代理的最新使用遥测）、tasks（可过滤的任务板）、agent、daily（已交付工作报告）和 spend（令牌和成本使用情况）。从 Telegram 发送的照片和文档将被下载到本地缓存目录，并将路径注入给代理读取。来自 Claude Code statusLine、Codex 令牌计数和 Pi 会话统计的遥测数据可以在限额达到 90% 时触发去重警告。论坛主题路由为可选且处于实验阶段，关于创建主题生成代理以及重新打开活动主题不重新附加代理的注意事项已在文档中说明。控制功能可在配置文件中禁用。 安装：单行安装脚本通过 Bun 安装依赖项，将 tg 链接到 PATH 并注册代理技能；手动克隆加符号链接同样可行。配置存储在 config 目录下的 dotenv 文件中，包含 bot token 和 chat id。install-skill 子命令会写入技能文件并在检测到的 harness 文件中附加简短说明。由于检出的脚本即为运行的二进制文件，因此无需构建步骤，deploy 脚本可快速推进检出，但拒绝覆盖本地更改；守护进程代码更改需要重启，脚本可检测并报告此情况。每台机器需要一个 bot token，因为 Telegram 允许每个 token 只有一个 getUpdates 消费者。