初识pi-intercom:AI编程助手pi的多会话1对1通信扩展全景解析

原创2026-11-14 23:27:561,878 阅读

初识pi-intercom:AI编程助手pi的多会话1对1通信扩展全景解析

pi-intercom 是为 AI 编程助手 pi 打造的多会话 1 对 1 通信扩展:它让同一台机器上的多个 pi 会话之间可以直接互相发消息、共享上下文、委托任务——无论是你手动编排多个会话,还是让 agent 之间自主协作,都能像"内部对讲机"一样精准触达指定会话。

pi-intercom AI编程助手pi多会话1对1通信扩展横幅

🎯 它解决什么问题?

实际开发中,你常常同时跑着好几个 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 打开会话列表

最直观的上手方式是键盘操作:

  1. 按下 Alt+M(或输入 /intercom),打开会话列表浮层
  2. 用方向键选择目标会话
  3. 在编写浮层中输入消息,按 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)。

登录后查看全文
pi-intercom