@liuchen64/pi-im-bridge

Pi 扩展——把即时通讯工具变成当前 pi 会话的移动端入口。离开电脑后，在 IM 里给机器人发消息即可继续操作当前项目。

一个 IM 用户 ↔ 一个 pi 会话。内置微信通道（微信 iLink Bot）。

架构

核心与具体 IM 解耦，新增 IM 只需实现 ImChannel 接口并注册：

src/
├── core/                     # 与具体 IM 无关
│   ├── channel.ts            # ImChannel / ChannelSession / ChannelLoginHooks / ChannelAuthError / 注册表
│   ├── bridge.ts             # ImBridge：轮询循环、注入会话、回复回传、状态栏
│   ├── usage-report.ts       # 用量/余额播报文案
│   ├── queue.ts              # 静默窗口消息合并
│   ├── text.ts               # 模型侧文本提取 / Markdown 降噪 / 分段
│   ├── session-lock.ts       # 通道级排他锁
│   └── config.ts             # autoStart / mirrorTuiInput / defaultChannel
├── channels/
│   ├── index.ts              # 内置通道注册（新增 IM 在此追加）
│   └── wechat/               # 微信通道：iLink Bot 协议 + 适配器
└── commands/index.ts         # /im 命令

运行链路：

IM  ⇄  通道适配器（poll / sendText）  ⇄  ImBridge  ⇄  pi 会话（模型 + 工具）

安装

pi install npm:@liuchen64/pi-im-bridge

本地开发：

pi --no-extensions -e ./packages/im-bridge/src/index.ts

使用

/im login     # 扫码登录（二维码全屏面板展示，按 Esc 取消）
/im start     # 启动桥接

然后在微信里给机器人发消息即可。

TUI 命令

命令	说明
/im login [通道] [--force]	登录，--force 强制重新登录
/im start [通道]	启动桥接（会记住所选通道）
/im stop	停止桥接并释放连接锁
/im status [通道]	查看运行状态、绑定用户与配置
/im logout [通道]	清除本地凭证并停止
/im autostart [on|off]	会话开始时自动启动
/im mirror [on|off]	是否把 TUI 输入镜像到 IM

通道参数省略时使用唯一的已注册通道；当前内置通道：wechat（微信）。

行为说明

• 用量与余额播报：订阅 @liuchen64/pi-plugin-events 事件总线，把 footer-status 广播的用量快照与余额变化转发到 IM（桥接未运行时静默丢弃）。用量口径与 footer 一致，见下节示例。
• 消息合并：800ms 静默窗口内的多条消息合并成一次提问，适配"一句话分几条发"的习惯。
• 排队：模型正在执行时，IM 消息以 followUp 方式排队，不打断进行中的工具调用。
• 分段回复：超过 1500 字符的回复按行切分成多条发送；Markdown 会做降噪（去掉代码围栏、标题符号、加粗标记）。
• 排他锁：同一时间只允许一个 pi 实例持有某个通道的连接，锁按通道隔离，进程退出后自动失效。
• 单通道桥接：同一时刻只桥接一个通道，切换需先 /im stop。

用量与余额播报

对话完全停止（agent_settled）时发一条用量播报，余额数值变化时发一条余额播报：

📊 轮次 3 · 本次 ¥0.0231 · 总计 ¥1.23
输入 12.5k · 输出 3.2k · 缓存 8.1k (64.80% 命中) · 上下文 32.4% (41.5k/128.0k)

💰 余额 42.50 CNY（deepseek）

只转发，不采集：数据由 footer-status 采集并广播，未安装 footer-status 时不会收到播报。

当前 provider 未收录单价（现为 deepseek 以外的提供商）时，快照的金额两档为 null，用量播报会省略「本次 / 总计」段，只报轮次与 token。

支持的消息类型

微信通道当前仅支持文字。图片、文件、语音收到后会回执提示暂未接入。

状态与文件

状态栏显示 微信 ✓ 已连接 / 微信 ✓ 待处理 N。

~/.pi/agent/im-bridge/            # 目录权限 700
├── config.json                   # 自动启动、镜像开关、默认通道（600）
├── debug.log                     # 调试日志
└── wechat/                       # 各通道独立目录
    ├── credentials.json          # 登录凭证（600）
    ├── cursor.json               # 长轮询游标（600）
    ├── seen-ids.json             # 消息去重记录（600）
    ├── context-token.json        # 回复上下文令牌（600）
    └── session.lock              # 排他锁

Windows 上 chmod 不生效，权限保护依赖用户目录自身的访问控制。

调试日志默认关闭，设置 PI_IM_BRIDGE_DEBUG=1 开启。

微信通道说明

基于微信 iLink Bot 接口（ilinkai.weixin.qq.com）扫码登录，长轮询收消息，无需公网 IP、无需自建服务端。

安全边界：

• 只接受扫码登录时绑定的那个微信用户，其他来源的消息一律丢弃
• 微信消息等同于本机操作指令，请勿把登录凭证或状态目录分享给他人
• 登录态失效会停止桥接并提示重新登录

新增一个 IM 通道

1. 在 src/channels/<id>/ 实现 ImChannel（id / label / hasCredentials / login / logout / connect）
2. connect() 返回的 ChannelSession 实现 poll()（可长轮询）与 sendText()
3. 凭证失效时抛 ChannelAuthError，桥接核心会停止并提示重新登录
4. 在 src/channels/index.ts 调用 registerChannel()

命令层与桥接核心无需改动。

开发

pnpm --filter @liuchen64/pi-im-bridge test

许可证

MIT