📚 编程进阶教程站

第 21 章 · 多会话协作：pi-intercom 与 pi-messenger ​

本章目标：掌握 pi 生态中两个多会话协作扩展——pi-intercom（点对点定向消息）与 pi-messenger（多智能体聊天室），理解各自的适用场景与选型依据，并动手搭建三终端协作工作流。

21.1 多会话协作概述 ​

当你同时运行多个 pi 会话——一个做调研、一个写代码、一个做审查——它们之间如何共享发现和协调行动？pi 的答案不是内置子代理，而是通过扩展生态提供两种互补的协作模式：

维度pi-intercompi-messenger
通信模型点对点 1:1 定向消息共享聊天室（广播）
主要用途用户编排自己的多个会话多智能体自主协同
发现机制Broker 进程（实时注册）基于文件的注册表
消息可见性私密，仅收发双方广播给所有在线 agent
持久化存入 Pi 会话历史共享协调文件
基础设施本地 IPC socket/管道纯文件系统，无 daemon

两者不互斥：你可以用 pi-messenger 让一群 worker 自主分工跑 Crew 任务，同时用 pi-intercom 在两个特定会话之间传递精确指令。

安装

两个包均通过 pi 包管理器安装：

bash
pi install npm:pi-intercom
pi install npm:pi-messenger

安装后重启 Pi 即生效。

21.2 pi-intercom：点对点消息 ​

架构原理 ​

每个加载了 pi-intercom 的 Pi 会话连接到一个轻量本地 broker 进程。Broker 维护在线会话注册表，将消息路由到你指定的目标（按名称或 session ID）。通信使用 Unix domain socket（macOS/Linux）或命名管道（Windows），长度前缀 JSON 协议。

Broker 按需自动启动（首次连接时 spawn），最后一个连接断开后 5 秒退出。无需手动管理 daemon。心跳机制检测半开连接，broker 异常重启后客户端自动重连。

安装与配置 ​

bash
# 安装扩展
pi install npm:pi-intercom

# 重启 Pi 后自动连接 broker 并注册 pi-intercom 技能

# 可选：在项目 AGENTS.md 中添加协作指引

推荐在项目的 AGENTS.md 中加入以下片段，帮助智能体理解何时跨会话协调：

xml
<pi-intercom>
Coordinate with other local pi sessions on related codebases.
Use `/skill:pi-intercom` for patterns.

**When:** Same codebase (parallel work), reference codebase (consulting patterns).
**Not when:** Unrelated codebases, trivial questions, or when you can proceed independently.

**Principle:** Prefer `send` for notifications; `ask` only when blocked waiting for input.
</pi-intercom>

高级配置文件位于 ~/.pi/agent/intercom/config.json：

json
{
  "confirmSend": false,
  "inboundTrigger": "always",
  "enabled": true,
  "replyHint": true,
  "status": "researching"
}

核心工具用法 ​

intercom 工具支持八种 action，覆盖完整的点对点通信场景：

typescript
// 列出所有在线会话（含当前会话标记）
intercom({ action: "list" })
// → • executor (20d43841) — ~/projects/api [self, idle]
// → • research (6332faab) — ~/projects/api [same cwd, thinking]

// 只列同工作目录的对端
intercom({ action: "list-cwd" })

// 发送即忘消息——通知类场景用 send
intercom({
    action: "send",
    to: "research",
    message: "Check if UserService.validate() handles null input."
})

// 发送阻塞询问——需要回复才能继续的场景用 ask
intercom({
    action: "ask",
    to: "planner",
    message: "Should retry apply to all endpoints or just idempotent ones?"
})
// → Reply from planner: Only GET/PUT/DELETE — never POST. Max 3 retries.

// 回复最近一条入站 ask
intercom({ action: "reply", message: "Task-3 done. All tests passing." })

// 查看待处理的入站 ask
intercom({ action: "pending" })

// 取消已发送的消息
intercom({ action: "cancel", messageId: "abc123" })

send vs ask 的关键区别：

  • send 即发即忘，工具立即返回。如果目标恰好有一条待处理 ask，send 会自动推断这是它的回答并关联 replyTo；
  • ask 要求目标在线，发送后阻塞等待回复（默认 10 分钟超时，可通过 PI_INTERCOM_ASK_TIMEOUT_MS 调整），回复作为 tool result 返回，agent 无需中断当前 turn 即可继续。

用户侧快捷键：按 Alt+M 或输入 /intercom 打开会话选择浮层，方向键选目标、Enter 发送、Esc 关闭。

Planner-Worker 编排模式 ​

最自然的用法是将任务拆分到两个终端：

bash
# 终端 1                          # 终端 2
/name planner                     /name worker

Planner 用 send 下发任务（不需要等待确认），Worker 遇到歧义时用 ask 向 planner 提问并等待回复，拿到答案后继续实现——全程不丢上下文。

通信模式动作原因
任务委派planner 用 send即发即忘，planner 不等 ack
歧义澄清worker 用 ask需要答案才能继续
发现升级worker 用 ask改变方案前需审批
完工报告worker 用 askplanner 可能有后续指示

与 pi-subagents 集成：contact_supervisor 工具 ​

当同时安装了 pi-subagents 扩展时，由其派生的子代理会额外获得一个 contact_supervisor 工具（普通会话看不到它）。该工具支持三种 reason：

typescript
// 阻塞式决策请求——子代理遇到歧义或需要审批
contact_supervisor({
    reason: "need_decision",
    message: "Auth service returns 403 instead of 401 for expired tokens. Treat as re-auth trigger or hard failure?"
})

// 结构化访谈——一次获取多个机器可读的答案
contact_supervisor({
    reason: "interview_request",
    message: "Please answer these before I continue the migration.",
    interview: {
        title: "API migration choices",
        questions: [
            { id: "api", type: "single", question: "Which API?", options: ["Stable", "Experimental"] }
        ]
    }
})

// 非阻塞进度更新——有意义的进展或改变计划的发现
contact_supervisor({
    reason: "progress_update",
    message: "Discovered the bug is in the retry wrapper, not the API client."
})

不要用 contact_supervisor 做日常完工交接——正常返回结果即可，只有当答案会影响任务契约或需要 owner 审批时才用它。

21.3 pi-messenger：多智能体聊天室 ​

架构与理念 ​

pi-messenger 的核心理念是"不同终端共享同一文件夹的多个 agent 像聊天室一样对话"。它完全基于文件系统协调——无 daemon、无 server、纯文件读写。

Agent 加入后获得一个主题化随机名称（如 SwiftRaven、LunarDust），状态栏显示在线人数：msg: SwiftRaven (2 peers) ●3。

安装与快速上手 ​

bash
# 安装
pi install npm:pi-messenger

# 查看/安装预置的 Crew agents
npx pi-messenger --crew-install

# 移除扩展
npx pi-messenger --remove

加入后即可使用六种基础协调 action：

typescript
// 加入 mesh
pi_messenger({ action: "join" })

// 锁定文件路径防止其他 agent 写入冲突
pi_messenger({ action: "reserve", paths: ["src/auth/"], reason: "Refactoring auth module" })

// 定向私聊
pi_messenger({ action: "send", to: "GoldFalcon", message: "auth is done" })

// 广播全员
pi_messenger({ action: "broadcast", message: "API contract updated, please review." })

// 释放锁定
pi_messenger({ action: "release" })

// 离开 mesh
pi_messenger({ action: "leave" })

文件锁定机制通过拦截 tool_call 钩子实现：其他 agent 尝试写入被 reserve 的路径时会收到阻止消息，提示它与哪个 agent 协调。锁定在 leave 或进程退出时自动释放。

Crew：从 PRD 到并行执行 ​

Crew 是 pi-messenger 最强大的功能——将 PRD 文档转化为带依赖关系的任务图，然后以波次（wave）方式并行执行：

typescript
// 规划阶段——分析代码库，生成依赖图任务
pi_messenger({ action: "plan" })

// 执行阶段——单次调用执行一波就绪任务
pi_messenger({ action: "work" })

// 自主模式——连续执行直到所有任务完成或阻塞
pi_messenger({ action: "work", autonomous: true })

// 审查指定任务的实现
pi_messenger({ action: "review", target: "task-1" })

波次执行的依赖调度逻辑：

text
Wave 1:  task-1 (无依赖)  ─┐
         task-3 (无依赖)  ─┤── 并行执行
Wave 2:  task-2 (→task-1) ─┤── task-1 完成, task-2 解锁
         task-4 (→task-3) ─┘── task-3 完成, task-4 解锁
Wave 3:  task-5 (→task-2,4)── 全部依赖完成

每个完成的任务自动触发 reviewer 审查——SHIP 保持完成态，NEEDS_WORK 重置并附带反馈重试，MAJOR_RETHINK 阻塞。

Crew Agents 与 Skills ​

Crew agents 以 .md 文件形式定义（含 frontmatter 指定模型和 thinking level），存放在扩展的 crew/agents/ 目录下。要为单个项目定制，复制到 .pi/messenger/crew/agents/ 编辑即可。

默认四个角色及模型分配：

Agent角色默认模型
crew-plannerplanneranthropic/claude-opus-4-6
crew-workerworkeranthropic/claude-haiku-4-5
crew-reviewerrevieweranthropic/claude-opus-4-6
crew-plan-syncanalystanthropic/claude-haiku-4-5

Crew skills 是领域知识的按需加载单元，放在 .pi/messenger/crew/skills/ 目录下：

markdown
---
name: our-api-patterns
description: REST API conventions for this project — auth, pagination, error shapes.
---

# API Patterns

Always use Bearer token auth. Paginate with cursor-based `?after=` params.
Error responses use `{ error: { code, message, details? } }` shape.

Planner 会看到技能索引并可将其标注到相关任务；Worker 执行时按需读取，零 token 浪费。

配置与成本控制 ​

Crew 会并行启动多个 LLM 会话——token 消耗可能很大。建议先用廉价模型验证流程再升级。配置文件 ~/.pi/agent/pi-messenger.json：

json
{
  "autoRegister": true,
  "nameTheme": "nature",
  "stuckThreshold": 900,
  "crew": {
    "concurrency": { "workers": 2 },
    "models": { "worker": "claude-haiku-4-5" },
    "review": { "enabled": true, "maxIterations": 3 },
    "work": { "maxAttemptsPerTask": 5, "maxWaves": 50 }
  }
}

模型字符串支持 provider/model 格式和 :level 后缀控制思考深度（如 openrouter/anthropic/claude-sonnet-4:high）。

Team Layer：可选的团队层 ​

Team 是 Crew 之上的可选层，添加项目级角色、章程、持久记忆和高风险审批门控。大多数用户直接用自然语言交互即可：

text
Use the review squad for this cleanup.
Use a migration team and pause before risky database changes.
Approve the auth API task.

内置三个示例 profile 可立即激活：

typescript
pi_messenger({ action: "team.setup", name: "migration-squad" }) // 含审批门控
pi_messenger({ action: "team.setup", name: "review-squad" })    // 审查流
pi_messenger({ action: "team.setup", name: "research-squad" })  // 研究优先流

21.4 选型对比 ​

场景推荐工具理由
你手动驱动两个会话（研究→执行）pi-intercom点对点精确控制，send/ask 分离
一群自主 agent 分工做一个大任务pi-messenger (Crew)波次并行 + 自动审查 + 依赖调度
子代理需要向父代理请示决策pi-intercom + pi-subagentscontact_supervisor 三种 reason
团队级角色/审批/记忆pi-messenger (Team)内置 migration/review/research squad
快速传递一段代码片段pi-intercom send + attachments支持 file/snippet/context 类型
长期运行的多项目 agent 群pi-messenger文件持久化，重启后可恢复

一句话原则：需要精确控制发给谁就用 intercom；需要一群 agent 自主协同就用 messenger。

21.5 实战：三终端协作开发一个功能 ​

假设你要为 Web 应用添加暗色主题。用三个终端分别承担规划、前端实现和测试审查角色：

终端 1 — Planner（规划者）：

bash
/name planner
pi install npm:pi-intercom
pi install npm:pi-messenger

用 pi-messenger 启动 Crew 规划：

typescript
pi_messenger({ action: "plan", prompt: `
Add dark mode to this app:
1. CSS variables for theme colors (--bg-color, --text-color)
2. System preference detection (prefers-color-scheme)
3. Manual toggle button with localStorage persistence
4. Update all existing components to use variables
` })
// 自动启动 workers 执行

终端 2 — Frontend Worker（前端实现）：

bash
/name frontend-worker
pi install npm:pi-messenger

Worker 通过 Crew 自动接收任务，或手动认领：

typescript
pi_messenger({ action: "join" })
pi_messenger({ action: "reserve", paths: ["src/styles/", "src/theme.ts"] })
pi_messenger({ action: "work" })  // 执行分配的任务

遇到设计歧义时用 intercom 向 planner 提问：

typescript
intercom({
    action: "ask",
    to: "planner",
    message: "Should dark mode default to system preference or manual toggle on first visit?"
})

终端 3 — Reviewer（测试审查）：

bash
/name reviewer
pi install npm:pi-intercom
pi install npm:pi-messenger

监听完工报告并审查：

typescript
pi_messenger({ action: "join" })
pi_messenger({ action: "status" })   // 查看 crew 进度

// 或用 intercom 直接向 worker 询问
intercom({
    action: "ask",
    to: "frontend-worker",
    message: "Are all CSS variables defined in a single theme.ts? Show me the variable names."
})

三终端各司其职，通过两种协作通道无缝衔接——这就是 pi 扩展生态"组合优于内置"的设计哲学。

本章小结 ​

  • pi-intercom 提供本地点对点消息：send（即发即忘）/ ask（阻塞等待回复）/ reply / cancel；
  • pi-subagents 子代理额外获得 contact_supervisor 工具，三种 reason 对应决策/访谈/进度；
  • pi-messenger 是基于文件的聊天室：join/reserve/send/broadcast，文件锁定防冲突；
  • Crew 将 PRD 转化为依赖图任务，波次并行执行 + 自动审查循环；
  • Team layer 添加角色、章程、记忆和审批门控；
  • 选型原则：精确控制用 intercom，群体自主用 messenger。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. pi-intercom 中 send 和 ask 的核心区别是什么？

2. pi-messenger 的 reserve action 主要解决什么问题？

3. Crew 的波次（wave）执行是如何调度任务的？

4. 什么场景应该选择 pi-intercom 而非 pi-messenger？

🛠️ 动手实践 ​

  1. 安装 pi-intercom，打开两个终端分别命名为 planner 和 worker，用 intercom({ action: "list" }) 确认互相可见，然后用 send/ask 完成一轮任务委派。
  2. 安装 pi-messenger 并加入 mesh，创建一个包含 3 个任务的 PRD 文件，用 plan + work autonomous:true 跑通完整 Crew 流程。
  3. 在项目中创建 .pi/messenger/crew/skills/deploy-checklist.md 技能，内容为你的部署检查清单，然后观察 planner 是否将其标注到相关任务上。

返回课程导学