初识pi-intercom:AI编程助手pi的多会话1对1通信扩展全景解析
初识pi-intercom:AI编程助手pi的多会话1对1通信扩展全景解析
pi-intercom 是为 AI 编程助手 pi 打造的多会话 1 对 1 通信扩展:它让同一台机器上的多个 pi 会话之间可以直接互相发消息、共享上下文、委托任务——无论是你手动编排多个会话,还是让 agent 之间自主协作,都能像"内部对讲机"一样精准触达指定会话。
🎯 它解决什么问题?
实际开发中,你常常同时跑着好几个 pi 会话:一个负责调研,一个负责执行,一个负责审查。但默认情况下,会话之间是"信息孤岛"——想传递一个结论或一个需求,只能靠复制粘贴。
pi-intercom 带来三个核心能力:
| 能力 | 说明 |
|---|---|
| 用户驱动编排 | 把调研会话的结论直接发给执行会话 |
| Agent 协作 | 一个 agent 需要帮助或想分享结果时,可主动联系另一个会话 |
| 会话感知 | 实时看到哪些 pi 会话在运行、当前状态如何 |
💡 与 pi-messenger(多 agent 共享聊天室)不同,pi-intercom 强调定向的 1:1 通信——你来指定收信人。
🚀 一分钟安装:一条命令搞定
安装只需一行命令,然后重启 Pi 即可:
pi install npm:pi-intercom
扩展启动后会自动连接本地 broker(消息中转进程),并注册内置的 pi-intercom skill,提供可直接套用的协作模式示例。
官方建议把 README.md 中的协作说明片段追加到项目的 AGENTS.md,帮助 agent 理解"何时该跨会话协作":同代码库的并行工作适合发 send 通知;只有真正被阻塞、等待输入时才用 ask。
⌨️ 第一次通信:按 Alt+M 打开会话列表
最直观的上手方式是键盘操作:
- 按下 Alt+M(或输入
/intercom),打开会话列表浮层 - 用方向键选择目标会话
- 在编写浮层中输入消息,按 Enter 发送,Escape 取消
会话列表由 ui/session-list.ts 实现,消息编写由 ui/compose.ts 负责。另外,在列表中按 h 可以直接把当前会话"移交"给高亮的那个会话(详见下文 handover 工作流)。
小提醒:会话列表只显示已连接 intercom 的会话,而不是机器上所有 Pi 进程。用 /alias <name> 给当前会话起个名字(例如 /alias worker),其他会话就能按名字找到它。
📨 两种发消息:send 与 ask
Agent 侧通过 intercom 工具通信,工具定义入口在 index.ts。两个核心动作值得分清:
send:即发即忘。投递后立即返回,适合任务委托、进度通知ask:阻塞等待回复(默认 10 分钟超时),答案直接作为工具结果返回,agent 在同一轮对话中带着完整上下文继续工作
典型交互长这样:
// 列出所有已连接的会话
intercom({ action: "list" })
// 给 worker 发送任务(不等待)
intercom({ action: "send", to: "worker", message: "Task-3: 给 API client 加重试逻辑" })
// worker 遇到歧义,提问并等待答案
intercom({ action: "ask", to: "planner", message: "重试应该覆盖所有端点,还是只覆盖幂等端点?" })
收到消息时会内联渲染在聊天流中(由 ui/inline-message.ts 负责显示),并附带回复提示,例如:
**From planner** (~/projects/api)
To reply, use the intercom tool: intercom({ action: "reply", message: "..." })
只对 GET/PUT/DELETE 重试,绝不对 POST 重试。最多 3 次,指数退避从 100ms 开始。
这样接收方 agent 无需手动构造 ID,直接用 intercom({ action: "reply", ... }) 即可回复。空闲会话会被立即唤起;忙碌中的会话则会在下一个安全边界排队处理,不会打断正在进行的运行。
🤝 Planner-Worker:最经典的双会话协作模式
pi-intercom 最有代表性的用法是把任务拆给两个会话——一个掌握全局(planner),一个动手干活(worker)。推荐节奏如下:
| 场景 | 使用动作 | 原因 |
|---|---|---|
| 任务委托 | send |
即发即忘,planner 不需要等确认 |
| 请求澄清 | ask |
worker 需要答案才能继续,阻塞等待 |
| 发现意外问题 | ask |
改变方向前需要批准 |
| 完工汇报 | ask |
planner 可能有后续指令或下一个任务 |
配套模式可直接参考内置技能文档 skills/pi-intercom/SKILL.md。
🔄 /handover:把整个会话"交接"给另一个会话
当你把工作从一个会话转移到另一个会话时,/handover 能让新会话继承旧会话学到的东西,不必重新摸索:
/handover
/handover mcp-worker 把 schema 修复移植到 adapter
单独输入 /handover 会打开一个会话选择器(ui/handover-picker.ts):列出本机其他会话(按最近活跃排序),显示目录、模型、状态和上下文占用,占用 80% 以上的会高亮提醒。还可以从列表跳到其他机器的会话。
命令会让当前模型基于本会话的完整对话生成一份结构化交接摘要:下一步任务、关键决策与被否决的方案、相关文件与仓库、当前状态和待解问题(核心逻辑见 handover.ts)。发送前会打开编辑器供你审阅修改,保存即发送。
🏗️ 底层架构:一个超轻量的本地 Broker
pi-intercom 的通信架构非常干净:每个加载了扩展的 pi 会话通过本地 IPC(macOS/Linux 用 Unix socket,Windows 用命名管道)连接到一个小型 broker 进程,broker 负责维护会话注册表并把消息按名字或会话 ID 路由给目标。
关键设计决策:
- 纯本地 IPC,不开网络端口:同机通信,免端口管理
- 自动拉起 + 自动退出:第一个会话需要时自动启动 broker(文件锁防止重复拉起,见 broker/spawn.ts),最后一个会话断开后 5 秒退出,没有需要守护的进程
- 心跳保活:客户端和 broker 双向心跳,防止进程崩溃后留下"半开连接"导致会话永远掉线
ask留在客户端:broker 只负责路由普通消息,请求-响应逻辑在客户端完成- 自动重连:broker 消失后客户端会持续重试,直到它回来
核心实现分布在 broker/broker.ts(broker 进程)、broker/client.ts(IntercomClient 客户端类)和 broker/framing.ts(4 字节长度前缀 + JSON 的分帧协议)。
⚙️ 常用配置与 CLI 脚本接入
用户配置位于 ~/.pi/agent/intercom/config.json,由 config.ts 加载。几个值得关注的选项:
| 配置项 | 默认值 | 作用 |
|---|---|---|
inboundTrigger |
"always" |
收到消息时自动触发的策略:always / replies / never |
busyDelivery |
"steer" |
忙碌会话的投递方式;human-first 让人类输入优先 |
confirmSend |
false |
发送前是否弹确认框 |
enabled |
true |
总开关 |
replyHint |
true |
收到消息时附带回复提示 |
除了会话内使用,pi-intercom 还带一个最小化 CLI 客户端(入口 cli.mjs),方便脚本、cron 钩子和 CI 接入:
# 查看会话列表
pi-intercom list
# 即发即忘消息
pi-intercom send --to worker --text "build failed — 请看看 src/api"
# 阻塞式提问,打印回复后退出
pi-intercom ask --to planner --text "用哪个 API 版本?" --timeout-ms 180000
配合 SSH,CLI 还能桥接跨机器会话:ssh remote-host 'pi-intercom ask --to worker ...',远端 broker 依然只监听本地,无需开放任何网络监听。跨机器发送还支持 reviewer@workstation 这类 名字@机器 寻址(传输逻辑见 cross-machine-transport.ts),并附带结构化的来源元数据——注意该身份基于 SSH 断言,不做密码学校验。
⚠️ 使用前的限制须知
了解边界,避免踩坑:
- 仅限同一台机器:基于本地 socket/管道,无原生网络传输(跨机靠 SSH 中继)
- 没有独立的 intercom 日志:消息保存在 Pi 会话历史中,没有单独的收件箱
- 列表只显示已连接会话:未加载扩展或未注册 broker 的 Pi 进程不会出现
- broker 是临时进程:空闲即退出,首次使用时自动拉起
📌 写在最后
pi-intercom 用一套极轻量的本地架构,解决了"多个 AI 编程会话如何高效协作"这个真实痛点:Alt+M 打开列表、send 传上下文、ask 等答案、/handover 交接进度——整个通信链路不依赖任何外部服务。如果你经常同时运行多个 pi 会话,这个扩展值得花一分钟装上试试。更多细节请阅读 README.md 全文,项目以 MIT 协议开源(见 package.json)。
