pi-mesh 全家桶详解：单机多智能体协同的四件套

pi 是我们日常用的编码智能体宿主。单开一个终端时它是个安静的助手；但同时开三四个终端、每个里面一个 agent 抢同一个仓库时，问题就来了：谁在线？谁在改哪个文件？消息发出去了对方到底看没看见？半夜跑着的构建谁有权停？

围绕 pi-mesh 长出来的一族小工具把这层协同做成了基建。它们各管一摊，咬合成套：

一、pi-mesh：通信骨干

pi-mesh 是一条本机总线：一个脱离会话存活的 broker（NDJSON 帧走 unix socket），每个 pi 终端以别名成为 peer，加入房间（room）。消息 < 50ms 到达，零运行时依赖，Node ≥ 20。

它最值得称道的是诚实状态模型：delivered（写进了对方套接字）≠ read（注入了对方会话）≠ answered（拿到了显式回复）——三者永不混淆，没有一个是”完成”的意思。配套的持久台账是 hash-only 的：消息正文永不落盘，重启后能审计”谁在何时给谁发过什么”，但看不到内容。这个自我约束后来成了整个工具族的设计公理：mesh 只做路由器，永不做数据库。

协同刚需有三个都在骨干里：

• mesh_reserve 路径预约：改文件前先预约，其他 peer 的 edit/write 工具在该路径上直接被拦——并发编辑靠机制防，不靠喊话。
• mesh_claim 任务租约：单写者锁，带 epoch:fence（broker 重启即作废旧围栏）；提交信息里写 Mesh-Lease: task#leaseId#epoch:fence，配套 commit-msg 钩子直接拒绝过期围栏的提交。
• 能力路由 cap:：mesh_send({ "to": "cap:deploy", ... }) 把任务发给任意一个空闲且自报该能力的 peer，而不是等忙着的队友。消息优先级三档：normal 排队、urgent 插队、force 先中止对方当前回合再送达（force 属管控类，必须带 reason）。

另有 mesh_wait_all 做群裁（一次收回“谁答了、谁没答”的名单）、mesh_status 看 peer 忙闲（● 干活 / ○ 空闲 / ✕ 卡死）、pimesh CLI 支持无会话接入（pimesh attach 能收养死掉会话的身份）。跨机部署也支持：一台起 broker，其余机器做客户端。

诚实的颗粒度细到退出码：CLI 里 3 表示 expired——晚到的答复仍会送达，只是你等起见超时了；5 表示租约已过期，commit-msg 钩子据此把提交拒之门外。甚至 ESC 清空消息队列这种宿主边界也考虑到了：批量注入若撞上回合中止，broker 会在该回合结束后经中止安全通道重投（有界重试），状态页能看到“中止清除恢复重投”计数。

二、pi-board：团队记忆板

消息是易逝的，台账是 hash-only 的，那”我们学到了什么”存哪？pi-board 补上这层。五种类型化条目：

• OBSERVED——看到了什么（不承诺）
• FACT——验证过的事实
• FAIL——一条被证伪的路（价值最高：全队不必再烧第二次预算）
• CLAIM——认领声明，与 mesh_claim 租约配对（板只记录，从不执行）
• PATCH_SUMMARY——落了什么改动

设计上处处是“有界与诚实”：append-only 本地存储、refuse-not-evict（超限拒绝写入而非静默淘汰）、条目默认短小、长文 detail 只能按 id 展开、布尔检索（, = OR，& = AND）覆盖全史而 board_read 只看近期窗口；检索无果时返回诚实的空，绝不猜一条充数。写入以普通广播帧发进房间，turn 边界有新 FAIL 摘要行；房间角色 member / observer 沿用 mesh 语义，只读 peer 永远不会在重连后被误升为写者。它以普通 peer 身份入房——存储全在板自己家里，broker 里零持久化。附带的 piboard CLI 五个动词一把梭：join（member / observer）/ watch / write / read / grep，一动词一动作，无会话的终端也能进房只读围观。这套类型学与”小条目+按需展开+近期记忆/全史检索”的分工直接来自学术论文(血统故事见下一篇)。

三、pi-jobd：后台作业守护

bash 会阻塞当前回合，/reload 会杀进程。pi-jobd 把长命令放进独立进程组，由 per-user 守护监管：~150ms 返回，作业存活于会话之外。什么时候用它？三条判据：命令预计超过 60-90 秒；你必须边跑边干别的；或者它得扛过 /reload 和会话结束——以及”别的 agent 应该能停它”这一条：mesh_job_control 让任一授权 peer 远程 stop/pause/resume 别人的后台作业。

状态机同样诚实：running / paused / stopped / exited / failed，外加一个 lost——守护重启后无法证明 pid 归属时，宁可拒绝 stop 也绝不信号一个来路不明的进程。这个包还有个巧思：装包不够，模型还得知道什么时候用——它靠 prompt 快照、七个工具上的决策守则和一份按需加载的 skill 三层把使用时机喂给模型。

四、pi-subagents：worker 控制

pi-subagents 管的是进程内子代理：前台子代理流式跑在对话里，后台子代理活在独立的 runner 进程中随时可查。装完即用，不需要学斜杠命令——直接说”用 reviewer 审这个 diff”就行。它预置了 scout（侦察）、reviewer（审查）这类常用角色，也支持保存的工作流和并行审查。与 mesh 的接口是 mesh_run_control：远程 stop 或 steer 一个 peer 的 RPC worker。

五、四件套的一次合奏

六、上手五分钟

安装各一行：mesh 与 subagents 走 pi 包管理——pi install npm:pi-mesh-extension、pi install npm:pi-subagents；pi-board 还没发 npm，源码三步（clone、npm ci、npm run build），且可 CLI 独立用（不需要 mesh 也能读写本地板）；pi-jobd 同样源码构建，pijob run / list / log / stop 开箱即用。装完在同一目录开两个 pi 会话，就是两个 peer，mesh_status 互相可见——协同基建的“零配置”不是口号。

对话走 mesh，记忆上 board，长活交 jobd，排他靠租约——四个包各司其职，没有任何一个越界。这个博客的重设计期就是这套东西的实战场：两个 mesh 终端（op-gitea、op-artalk）与主线并行，一天 19 连发；发布链中断的修复窗口里，主线预约了 build.sh 紧急处置，另一边赶去补刀的编辑被预约机制正确拦下——撞车靠规则防住，不靠谁手快。

四件套加起来没有一个数据库、没有一个中心大脑，却把”谁在线、谁在干啥、学到过啥、长活谁看着”四件事全部钉死。小工具、硬边界、诚实状态——这套哲学比任何一个具体包都值得抄。