pi-telegram-mux

Pi 编码助手的 Telegram 论坛超级群多路复用插件。让你通过 Telegram 查看电脑上 Pi 助手的任务结果、发送新任务和中止执行。

English | 简体中文

---

功能

• 双向交互：在电脑上提问，提示词与最终回复同步到手机；在手机话题中发送文字，交给电脑上的 Pi 执行。
• 多会话管理：多个 Pi 实例共享一个 Telegram Bot，每个会话对应一个独立话题，无需额外部署服务。
• 自动连接与生命周期：新会话首次提问时自动创建话题，恢复会话时继续使用原话题；也可关闭新会话自动连接，改为手动控制。
• 远程控制：在手机查询会话状态，或中止正在执行的任务。
• 指定用户访问：只接收配置的 Telegram 用户发来的任务。

同步内容为提示词和助手最终文本回复，不包含实时工具输出或附件。

安装

需要 Node.js 22.19 或更新版本，以及 Pi 0.85.0 或更新版本。本插件用于 Pi 的交互式终端。

从 npm 安装（推荐）

全局安装（所有项目可用）：

pi install npm:pi-telegram-mux

若仅安装到当前项目，添加 -l 参数：

pi install -l npm:pi-telegram-mux

其他安装方式

也可以直接从 Git 仓库安装：

pi install git:github.com/hkfires/pi-telegram-mux

或者从本地项目目录安装：

pi install /path/to/pi-telegram-mux

仅安装到当前项目时添加 -l；临时加载可使用：

pi -e /path/to/pi-telegram-mux/extensions/index.ts

首次配置

1. 准备 Telegram

1. 向 @BotFather 发送 /newbot，按提示创建 Bot 并获取 Bot Token。
2. 创建群组，在群组设置中开启 Topics（话题）。
3. 将 Bot 加入群组并设为管理员，授予管理话题和发送消息的权限。
4. 获取群组的 Chat ID（通常以 -100 开头）和你自己的 用户 ID。可借助 @RawDataBot 查看群组消息信息，向 @userinfobot 私聊查询自己的用户 ID。

2. 在 Pi 中配置

在 Pi 中运行以下命令，打开设置菜单：

/tg-setup

选项	作用
Connection settings（连接配置）	设置 Bot Token、群组 Chat ID 和允许使用的用户 ID
Auto-close topics（自动关闭话题）	离开会话时自动关闭话题，默认关闭
Auto-connect new sessions（新会话自动连接）	新建且未绑定的会话自动连接并创建话题，默认开启；关闭后仅在运行 /tg-connect 时连接并创建话题。已绑定的已有会话及等待替代话题的会话仍会正常重连。

配置默认保存在 ~/.pi/agent/pi-telegram-mux/config.json。如果设置了 PI_CODING_AGENT_DIR，则使用该目录。

日常使用

1. 在电脑上的空白 Pi 会话中提问，例如“分析这个项目的目录结构”。
2. 默认情况下，插件会自动创建类似 Pi: my-project [a1b2c3] 的 Telegram 话题，并同步提示词。若关闭 Auto-connect new sessions（新会话自动连接），会话会保持本地状态，直到运行 /tg-connect；此前不会连接 Telegram 或创建话题。
3. 任务完成后，在手机话题中查看最终回复。
4. 在该话题直接发送文字，即可提交下一项任务。电脑上的 Pi 需要保持运行。

已有历史但未绑定话题的会话，使用 /tg-connect 手动连接。

如果原话题已被删除，恢复会话时会收到提醒。插件会等到你在 Pi 中发送下一条提示词后再创建新话题，并同步这次提示词和回复；仅恢复、查看会话或运行 /tg-connect 不会立即重建。如果在输出同步时发现话题已删除，本次失败的输出会被丢弃，状态会变为 tg: topic deleted，下一次在 Pi 中发送提示词会自动创建替代话题。等待重建的状态会保存在会话中，退出后再次恢复也不会重新使用已删除的话题。

图片输入

在绑定的 Telegram 话题中发送照片、图片文件或相册（最多 10 张），并在附言中写下任务说明（无附言时不添加默认提示词）。

注意事项：

• 使用 /model 选择支持视觉的模型，并保持 read 工具可用。支持 JPEG、PNG、GIF、WebP。
• 相册中任一张图片失败时，整组不执行。
• 图片保存在本地（默认 ~/.pi/agent/pi-telegram-mux/media/），不会自动删除，请按需手动清理。

升级后请重启所有 Pi 实例，避免新旧版本混用。

手机端命令

在话题中直接发送文字即可提交任务。以下命令会自动出现在授权用户的 Telegram / 菜单中，选择即可使用：

命令	用途
/model	点击按钮选择模型，支持翻页
/thinking	点击按钮选择思考量
/inputmode	点击按钮选择忙时输入模式（Follow-up 排队或 Steering 插入）
/status	查看会话状态
/stop	中止当前任务

Pi 终端命令

命令	用途
/tg-setup	配置 Telegram 插件
/tg-status	查看连接状态、当前话题和错误信息
/tg-connect	创建话题、恢复已有绑定，或在同步异常后重新连接
/tg-disconnect	停止当前会话的同步，保留群内话题

状态栏

显示	含义
tg: unconfigured	尚未配置，运行 /tg-setup
tg: ready	已就绪，空白会话首次提问时可创建话题
tg: topic deleted	原话题已被删除，发送下一条提示词后自动创建新话题
tg: connected (…)	当前会话已连接话题
tg: disconnected	已手动断开同步
tg: offline / tg: reconnecting	离线或正在重连
tg: 429 · …	触发限流，冷却结束后自动继续发送
tg: conflict (409)	其他程序正在使用同一个 Bot 接收消息
tg: error	连接或同步异常，运行 /tg-status 查看原因

遇到同步异常，先查看 /tg-status，处理提示的问题后运行 /tg-connect；需要修改配置时运行 /tg-setup。如果提示任务或话题创建“结果未知”，请先检查电脑上的会话和群内话题，再决定是否重试。

提示词和回复会发送并保存在 Telegram，Pi 也会保存自身会话记录；插件不额外保存聊天副本。

使用限制

Pi 0.85 的普通输入接口缺少入队确认和来源追踪，因此忙时的 Follow-up、Steering 改用扩展消息队列，避免误报接收成功或状态错配。消息在 Pi 中显示为 Telegram 消息，不经过其他扩展的输入转换，也不出现在普通待发送文本队列中；空闲输入不受影响。

许可证

MIT