pi-wechat

English | 简体中文

pi-wechat 是一个给 pi 使用的 TypeScript 扩展，用来把微信 iLink Bot 的消息桥接到 pi 会话里。

它可以：

• 通过二维码登录微信 iLink Bot
• 在后台长轮询微信消息
• 把每条微信消息注入到当前 pi 会话
• 等整个 agent loop 完成后，把最终回复发回微信
• 在 pi 工作期间同步微信输入态

这是什么

这个项目是一个 pi 扩展，不是独立运行的聊天机器人进程。

桥接方式是把微信消息直接送进“当前 pi 会话”。这样实现更贴近 pi 的扩展模型，也更简单，但代价是这个会话会承载所有桥接上下文。

推荐用法：

• 为微信桥接单独开一个 pi 会话
• 不要在同一个会话里混用本地终端聊天和实时微信流量

当前能力：

• 稳定的文本消息桥接
• 登录凭证持久化
• 重试和 session 过期处理
• 输入态支持

当前限制：

• 图片、语音、视频、文件消息目前会转成占位文本
• 这不是多用户路由服务
• 目前不会为每个微信会话自动拆分独立的 pi session

安装

使用 pi 从下面两种来源之一安装扩展。

方式 A：从 npm 安装

pi install npm:pi-wechat

方式 B：从 GitHub 安装

pi install git:github.com/yangyang0507/pi-wechat

重新加载 pi 资源

如果 pi 已经启动：

/reload

快速开始

在 pi 里执行：

/wechat-login
/wechat-start

然后：

1. 用微信扫描 pi 中显示的二维码
2. 在手机上确认登录
3. 从微信给 bot 发消息
4. 等 pi 完整跑完 agent loop
5. 在微信里收到最终回复

使用教程

登录

执行：

/wechat-login

扩展会请求微信 iLink Bot 的二维码，在 pi 界面里渲染出来，并等待你确认登录。

凭证默认保存到：

~/.pi-wechat/credentials.json

如果要强制重新扫码：

/wechat-login --force

启动桥接

执行：

/wechat-start

这会启动长轮询循环。收到的微信消息会按顺序排队，再逐条注入当前 pi 会话。

停止桥接

执行：

/wechat-stop

这会停止轮询，并清空内存中的桥接状态。

查看状态

执行：

/wechat-status

可以看到桥接是否运行、凭证是否已加载、当前是否有排队消息等信息。

清除本地凭证

执行：

/wechat-logout

这会停止桥接，并删除本地保存的凭证文件。

Slash Commands

• /wechat-login - 二维码登录
• /wechat-login --force - 强制重新登录
• /wechat-start - 启动桥接
• /wechat-stop - 停止桥接
• /wechat-status - 查看桥接状态
• /wechat-logout - 删除凭证并停止桥接

回复是怎么发回微信的

当一条微信消息到来时：

1. 扩展从 iLink Bot API 收到消息
2. 消息正文作为用户消息注入 pi
3. 微信回复约束通过隐藏的 before_agent_start system prompt 注入
4. pi 跑完整个 agent loop，必要时可以调用工具
5. 在 agent_end 后，扩展提取最终 assistant 文本
6. 这段最终文本被发回微信

这里故意选 agent_end 而不是 turn_end，因为如果 assistant 中间调用了工具，turn_end 很容易把中间结果过早发回微信。

开发

安装依赖：

npm install

执行基础校验：

npm run check

发布

如果后面要发布到 npm：

npm run check
npm login
npm publish --access public

调试日志

默认情况下，扩展会尽量减少 UI 噪音；如果 pi 已经能显示通知，就不会额外输出大量 console 日志。

如果需要打开桥接调试日志：

PI_WECHAT_DEBUG=1 pi

参考

• pi 扩展运行时：badlogic/pi-mono
• 微信协议 SDK 参考：epiral/weixin-bot
• Agent 桥接设计参考：wong2/weixin-agent-sdk