Pi-Harness 多 Agent 编排原理:任务调度、Worktree 隔离与冲突检测的完整指南

原创2026-10-18 12:38:551,835 阅读

Pi-Harness 多 Agent 编排原理:任务调度、Worktree 隔离与冲突检测的完整指南

Pi-Harness 是 Pi Coding Agent 的运维超集——它不仅完整继承 Pi 的核心能力,更内置了一套成熟的多 Agent 编排引擎:通过任务调度决定"谁先干活",用 Git Worktree 隔离保证各 Agent 互不干扰,再用冲突检测提前暴露多人改同一文件的合并风险。本文将带你用最短的时间看懂这套机制的实现之道。

Pi-Harness 多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 用一组纯函数完成依赖数学:

  1. 环检测(DFS):用访问栈找出所有循环依赖,环上任务直接标记为 blocked,避免死锁;
  2. 就绪/阻塞计算:依赖全部达到终态(completed / cancelled)的任务进入 ready,否则带原因列入 blocked;特别地,依赖若处于 failed 状态,会被标记为不可自愈,需要人工介入重试;
  3. 拓扑分层:把任务分成"并行波次",同一层可安全并行,用于 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 只能写自己的沙箱,从机制上杜绝了并行写入互相踩踏。

Pi-Harness Git分支管理与提交历史界面

任务完成后,产物可以留在各自的 worktree 分支里,由用户决定如何合并——隔离不是一次性的,而是贯穿整个生命周期。

冲突检测:只预警,绝不自动合并

即使有了 worktree,同一个文件仍可能被多个 Agent 修改。ConflictService.detect() 的思路非常朴素但有效:

  1. 收集所有 Agent 产出的文件类产物(Artifacts),按文件路径分组;
  2. 若某路径被 2 个及以上 Agent 修改,就记为一条冲突,记录涉及的文件路径、Agent 列表和任务列表;
  3. 输出结构化的 HarnessConflictReport 报告。

关键设计哲学写在源码注释里:Detection only — the harness surfaces the risk and the user decides。也就是说,Pi-Harness 只暴露风险、从不自动合并。最终评估(buildFinalEvaluation)会把文件冲突作为一个检查项:0 个冲突记 passed,否则记 warning 并列出所有冲突文件,交由人类裁决。

Reconcile 循环:一次事件驱动的全局对账

调度不是独立运行的,而是嵌在 reconcile() 这个"对账循环"里。每当有运行事件(run 开始/结束、策略拦截等)触发,循环就按固定顺序执行五步:

  1. 推导任务状态:重算 ready/blocked,状态变化即发出事件;
  2. 用量汇总:从真实 run 累加 token 与成本,而不是相信任何自报数据;
  3. 预算强制:超过 token/成本上限时把整个编排暂停(paused 而非杀死),并记录暂停原因;
  4. 完成检查:所有任务到达终态后,生成确定性最终评估并收尾;
  5. 调度下一波: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 协作的关键一跃。🚀

登录后查看全文
pi-harness