koishi-plugin-pi-bridge

koishi-plugin-pi-bridge

把 Koishi 机器人的输入输出绑定到本机运行的 pi-coding-agent(CLI 命令 pi),让聊天里的消息直接交给本地编码代理处理。

使用流程

1. 用户发送 pi bind → 机器人为发起者绑定一个本地 pi 会话(独立 workspace);
2. 绑定期间,该用户后续每条消息都转发给 pi agent,结果回发到聊天;
3. 发送 pi unbind → 解绑,恢复普通 Koishi 模式。

安装

前置条件(宿主机):

• 已安装 pi:npm i -g @earendil-works/pi-coding-agent,并能正常跑 pi "hi";
• Node.js ≥ 22(pi 的要求;插件会用当前 node 直接运行 pi 的 cli.js);
• 已配置 pi 的模型/认证(pi /login 或 ~/.pi/agent/auth.json,插件会把子进程 HOME 固定到真实用户目录,自动读取该认证);
• Windows 需要 Git Bash(pi 的 bash 工具依赖)。

在 Koishi 项目里:

npm i koishi-plugin-pi-bridge

零配置使用

• piExecutable 留空(默认)即可:插件自动探测全局安装的 pi,并用当前 node 直接运行其 cli.js(绕过 shebang/PATH 依赖),同时自动注入子进程的 HOME(auth 目录)与 PATH(node/npm)。
• 因此部署时不需要手写 wrapper、不需要指定绝对路径、不需要管 systemd/桌面版的环境变量差异——yarn/npm add 装上、pi 装好、认证配好就能用。

配置项

key	默认	说明
piExecutable	""(自动探测)	留空自动探测全局安装的 pi 并用当前 node 直接运行 cli.js，无需任何 wrapper/路径配置；也可指定命令名或绝对路径
nodeExecutable	自动探测	指定 node 绝对路径(worker 内置旧版 node 时可手动指定)
extraArgs	[]	附加启动参数,如 --model、--thinking high
workspaceRoot	~/.pi-bridge/workspaces	每用户 workspace 根目录(agent 的 cwd)
timeoutMs	600000	单轮处理超时,超时自动中断
chunkSize	1500	回复分片长度(字符)
maxReplyChunks	20	回复最大分片数,超出截断
thinkingHint	🤔 正在交给 pi agent 处理…	开始处理时的提示,留空关闭
restartOnCrash	true	进程崩溃自动重启并重试一次
excludeTools	[]	禁用的 pi 工具,如 ["bash"]
noContextFiles	true	禁用 AGENTS.md / CLAUDE.md 发现
allowedUsers	[]	白名单 "platform:userId",留空不限制

安全提示

• 绑定后,聊天消息会驱动宿主机上一个带 bash 等工具的编码代理,相当于远程执行环境,请谨慎授权;
• 建议在配置中设置 excludeTools: ["bash"] 或 allowedUsers 白名单;
• 每用户使用独立 workspace,插件默认禁用 AGENTS.md 发现,降低误伤面;
• 更严格的环境请将 Koishi 与 pi 放入容器/VM 运行。

工作原理

采用 pi 的 RPC 模式(pi --mode rpc)常驻子进程,JSONL over stdio 双向通信:

• 每绑定用户一个独立进程 + workspace + 固定 --session-id(重启可续会话);
• 中间件拦截绑定用户的普通消息 → RPC prompt → 聚合流式事件提取最终文本 → 分片回发;
• 支持多轮记忆、超时中断、崩溃自动重启、输出分片。

License

MIT