Pi-Harness 多 Agent 编排原理:任务调度、Worktree 隔离与冲突检测的完整指南
Pi-Harness 多 Agent 编排原理:任务调度、Worktree 隔离与冲突检测的完整指南
Pi-Harness 是 Pi Coding Agent 的运维超集——它不仅完整继承 Pi 的核心能力,更内置了一套成熟的多 Agent 编排引擎:通过任务调度决定"谁先干活",用 Git Worktree 隔离保证各 Agent 互不干扰,再用冲突检测提前暴露多人改同一文件的合并风险。本文将带你用最短的时间看懂这套机制的实现之道。
为什么多 Agent 编排需要"治理层"
让多个 AI Agent 并行写代码,听起来很爽,但真实场景有三个绕不开的难题:
| 难题 | Pi-Harness 的答案 |
|---|---|
| 谁先执行、谁后执行? | 确定性的任务调度器(TaskScheduler) |
| 多个 Agent 同时改代码会互相覆盖吗? | 每个 Agent 独立 Git Worktree 沙箱 |
| 改完文件怎么知道会不会冲突? | 基于产物的文件冲突检测,只预警不自动合并 |
整个编排核心代码集中在 src/main/harness/orchestrator/ 目录,设计不变量非常清晰:编排器只负责调度和观测,绝不伪造执行状态——每个 Agent 都跑在真实的 Pi 会话里。
任务调度:三种策略 + 优先级队列
调度器 task-scheduler.ts 的 plan() 方法根据编排运行(Orchestration Run)的策略字段做确定性派发,共有三种模式(定义见 HarnessOrchestrationStrategy):
- manual(手动):每个任务都等用户显式启动,适合需要人盯每一步的场景;
- sequential(串行):同一时刻只跑一个任务,按优先级排序后取第一个,简单可控;
- dependency(依赖驱动):所有"就绪"任务按优先级并行派发,但受双重上限约束——
maxConcurrentAgents(同时工作的 Agent 数)与maxConcurrentRuns(同时在飞的运行数),且同一 Agent 一次只跑一个任务。
优先级是四级权重制:critical: 4 > high: 3 > normal: 2 > low: 1(见 PRIORITY_WEIGHT),同优先级按创建时间排队。
值得强调的是:这里没有任何 AI 参与排程。调度是纯粹基于声明状态的确定性计算,可复现、可测试——这正是"运维超集"与"让 LLM 自己决定"的本质区别。
依赖解析:环检测与拓扑分层
任务可以声明 dependencies(前置任务 ID 列表)。dependency-resolver.ts 用一组纯函数完成依赖数学:
- 环检测(DFS):用访问栈找出所有循环依赖,环上任务直接标记为
blocked,避免死锁; - 就绪/阻塞计算:依赖全部达到终态(
completed/cancelled)的任务进入ready,否则带原因列入blocked;特别地,依赖若处于failed状态,会被标记为不可自愈,需要人工介入重试; - 拓扑分层:把任务分成"并行波次",同一层可安全并行,用于 UI 渲染依赖大纲。
任务状态(pending ⇄ ready ⇄ blocked)永远是由依赖推导出来的,不允许手工设置——这条规则让状态机不会出现"看起来在跑,其实依赖没满足"的假象。
Worktree 隔离:给每个 Agent 一个独立沙箱
这是 Pi-Harness 多 Agent 能力中最巧妙的一环。每个 Agent 有两种工作区模式(AgentDefinition 的 workspaceMode 字段):
- shared(共享):直接工作在编排根目录,适合只读分析类任务;
- worktree(隔离):为 Agent 单独创建一个 Git Worktree 分支。
当 Agent 首次被派发任务时,prepareWorkspace 会自动准备沙箱:
分支命名规则:pi-harness/{角色名}/{Agent短ID}
例如: pi-harness/refactorer/a1b2c3d4
底层由 WorktreeService.create() 执行 git worktree add -b,工作树统一放在 <仓库根>-worktrees/ 目录下,并把新分支名中的非法字符(/ : * ? 等)清洗为连字符。会话启动后,bindSession 会把该 Agent 的 Pi 会话权限精确绑定到自己的 worktree 路径——每个 Agent 只能写自己的沙箱,从机制上杜绝了并行写入互相踩踏。
任务完成后,产物可以留在各自的 worktree 分支里,由用户决定如何合并——隔离不是一次性的,而是贯穿整个生命周期。
冲突检测:只预警,绝不自动合并
即使有了 worktree,同一个文件仍可能被多个 Agent 修改。ConflictService.detect() 的思路非常朴素但有效:
- 收集所有 Agent 产出的文件类产物(Artifacts),按文件路径分组;
- 若某路径被 2 个及以上 Agent 修改,就记为一条冲突,记录涉及的文件路径、Agent 列表和任务列表;
- 输出结构化的 HarnessConflictReport 报告。
关键设计哲学写在源码注释里:Detection only — the harness surfaces the risk and the user decides。也就是说,Pi-Harness 只暴露风险、从不自动合并。最终评估(buildFinalEvaluation)会把文件冲突作为一个检查项:0 个冲突记 passed,否则记 warning 并列出所有冲突文件,交由人类裁决。
Reconcile 循环:一次事件驱动的全局对账
调度不是独立运行的,而是嵌在 reconcile() 这个"对账循环"里。每当有运行事件(run 开始/结束、策略拦截等)触发,循环就按固定顺序执行五步:
- 推导任务状态:重算
ready/blocked,状态变化即发出事件; - 用量汇总:从真实 run 累加 token 与成本,而不是相信任何自报数据;
- 预算强制:超过 token/成本上限时把整个编排暂停(paused 而非杀死),并记录暂停原因;
- 完成检查:所有任务到达终态后,生成确定性最终评估并收尾;
- 调度下一波:
tick()调用scheduler.plan()派发就绪任务。
此外,HandoffService 负责"交接记账":当下游任务消费上游任务的产物时,会记录一条 Handoff 并标记产物已被消费——"谁把什么交给了谁"永远可追溯。而 TaskContextBuilder 为每个 Agent 构造上下文隔离的提示词:只注入任务描述、依赖结果预览和显式交接的产物,绝不倾倒跨会话历史。
Pi-Harness 工作区多Agent任务协作视图
源码速查清单
| 模块 | 路径 | 职责 |
|---|---|---|
| 调度器 | task-scheduler.ts | 三种策略的派发规划 |
| 依赖解析 | dependency-resolver.ts | 环检测、就绪计算、拓扑分层 |
| 编排服务 | orchestrator-service.ts | reconcile 循环、预算与评估 |
| Agent 管理 | agent-manager.ts | 生命周期与 worktree 准备 |
| 冲突检测 | conflict-service.ts | 多 Agent 同文件修改预警 |
| 交接服务 | handoff-service.ts | 产物交接与消费记录 |
| Worktree | worktree-service.ts | 创建/列举/移除 git worktree |
| 类型定义 | types/harness.ts | 任务、优先级、策略等数据模型 |
总结
Pi-Harness 的多 Agent 编排给业界提供了一个清醒的范本:确定性调度 + 物理隔离 + 保守的冲突暴露。调度层是纯函数可测试的,worktree 层从文件系统层面消灭了写入竞争,冲突层则把合并决策权牢牢留给人。这套"任务调度、Worktree 隔离、冲突检测"三件套,正是 Pi Coding Agent 从单兵作战走向可靠多 Agent 协作的关键一跃。🚀

