← 返回主页

Agent Leader

多 Agent 开发与可信交付 ｜ 2026.05 — 2026.07
Python 3.11 · FastAPI · LangGraph · Pydantic v2 · Typer · SQLite · Git Worktree · pytest

一、业务理解

业务定义

Agent Leader 是一个跑在开发者本机的多 Agent 开发和交付平台。 它接入原生的 Codex CLI、Claude Code CLI、Qwen、Kimi Code CLI，把这些 Coding Agent CLI 纳入到以 Coding Agent 为生产主体的软件工程流程中， 并实现流程内交付的可信任、可审批、可回溯、可回滚。

服务用户

同时用多个 Coding Agent CLI 的开发者。

为什么会混用：实际工作里，不同任务对模型能力的要求差别很大。做架构设计、产品方案时，需要推理能力最强的模型； 改复杂 bug 时，需要上下文窗口大、对项目理解深的模型；而大量模式固定的重复性工作，让便宜的模型严格按写好的规范执行就够了。 所以团队里一定是多个 Coding CLI 混着用。

用户痛点

碎片化 Claude Code、Codex、Qwen、Kimi 各开一个终端混着用，上下文、日志、会话 Session 都不共享，手动切换成本高。
使用模板化 Coding Agent 的使用过于依赖人：怎么写提示词、什么时候校正、什么时候开新窗口，已经成了固定流程。既然是固定流程，就不该每次重来一遍，不如纳入上层软件自动执行。
交付内容不可信　·　主要攻关难点 能写代码，但无法验证是否完成了任务。自我汇报不可信任，自我评审过于宽松，业务交付上存在最后一公里问题。
交付过程黑盒 很难追溯每次改动是谁、什么时候改的；同样的需求想在相同条件下做对照复现也做不到，流程混乱，依赖人的对话式手动编排。
交付效果难评测 没法量化每个 Agent 在对应场景下的业务表现，开发时的 Agent 选型依赖经验而不是实际数据。

业务主流程

主流程分两个层次：可变的流程（workflow）编排，和不变的 Stage 生命周期。以一个 Workflow 为例：

  1. 用户半自由式交互提交 query 用户通过 CLI / TUI / Dashboard / API 四种入口中的任意一种，按交互提示输入命令（如 muxdev dev / fix / design）或一句自然语言任务描述。 守护进程收到后建立一条 Run 记录，写入 SQLite，并返回 run_id。
  2. 规则引擎映射编排决策 编排器依据三样东西做判断：可正则解析的交互指令、任务文本里风险词（认证、支付、迁移）的命中、以及仓库特征（测试目录、语言、项目标记）。 按规则从规则集中选取本次的 workflow.yaml：划分 Stage、设定依赖、标出只读阶段和人工关卡、设定修复循环上限。 路由器再查 Provider（Agent）评分卡为每个 Stage 分配 Agent——编码 Agent 与评审 Agent 强制来自不同 provider。
  3. worktree 分支隔离 执行引擎为本次 Run 建立 git worktree（独立分支 agent-leader/<run_id>）。后续所有改动只发生在这个副本里，主工作区不受影响； 非 git 仓库时退化为复制目录并补一个基线提交，保证 diff 和回滚照常可用。
  4. 调用 Agent 逐阶段执行 执行引擎按 workflow.yaml 的依赖顺序推进 Stage，每个 Stage 都走同一套流程： 写上下文包 → 记快照 → 调用 provider 完成对应开发任务 → 解析输出 → 再记快照 → 写证据。 执行中有三种分支：
    • 碰到审批点（plan / write / shell / merge）→ 暂停，等人 approve / deny。审批绑定被审内容的 hash，内容一变，旧审批作废，重新挂起。
    • 外部 CLI 卡住（要登录、被限流、在等 yes/no）→ 记一条 ProviderAction，等人到对应 CLI 里处理完，回来点「已处理」后继续。
    • review 有阻塞 → 回到 fix 修复，最多 1～2 轮；仍不通过则标记 blocked，等人介入。
  5. 判定器收尾 判定器读取整条证据事件流，依次完成证据评估（ready / reviewable / risky / blocked）、交付门禁、盲评审， 产出 final_report.md、diff.patch，以及每个阶段的回滚快照。
  6. 最终交付 开发者看完报告后决定：合并——再走一次 merge 审批，通过后把 worktree 的改动应用回主工作区； 回滚——回退到指定阶段的快照；继续——处理完待办后，从断点阶段接着跑。

关键业务拆解：可信交付的功能性要求

  1. Agent 自报和事实不一致时，系统要拦截。
    • 汇报改动某某文件，实际没改；
    • 自述测试了，实际没有测试；
    • 自述测试成功，实际没有成功；
    • 为了让测试成功，自己修改或跳过了测试。
  2. Agent 越权时，系统要识别并拦截。
    • 只读阶段（评审、设计）偷偷改代码；
    • 开发阶段自己把测试写了；
    • 开发阶段把 Spec 文档或开发计划改了；
    • 接到另一个 Agent 的交接文档时把交接文档改了；
    • 把记忆改了。
  3. 正常任务的交付结论能事后复核。
  4. 出问题能回滚到任意阶段之前。

二、技术理解

准则与重心

步步落库，步步校验，关键信息人工介入。

业务主要重心是可信交付，其它业务功能都必须为此让步。

可信交付怎么实现

它不是单点功能，而是一整套系统化机制，由六个层面协同实现：编排、证明、持久化、权限、隔离、运行时行为，最后由评测驱动迭代。

技术闭环

编排决定谁在什么时候做什么；隔离和权限限制 Agent 能动哪些东西；运行时由判定层亲自取证，形成证据； 持久化保证证据和代码状态不丢失、可回滚；评测从证据中统计每个 Agent 和每种流程的表现，再反过来调整规则引擎的映射集的调整和编排。

2.1　多 Agent 编排协作

去中心化协商　vs　中心化编排

可选方案有两大类：

  • 去中心化：多个 Agent 各自提出方案，互相讨论，最终商定一个。
  • 中心化：由一个中心编排器决定 Agent 怎么工作。又分三种做法——静态规则引擎、动态 Agent 调度、混合式（由 Agent 规划 workflow，其余部分按 workflow 调度）。

选择中心化的静态规则引擎。动态 Agent 调度难以审计，同样的任务可能走出不同的调度路径，出了问题没法定位到是哪个 Agent 的责任； 由 Agent 规划 workflow 有同样的毛病，同一任务每次生成的 workflow 不同，难以复现。

代价灵活性差。规则覆盖不到的任务只能落到默认模板，规则集需要持续维护。

2.2　证据体系

SLSA / in-toto　vs　轻量哈希链
  • SLSA：供应链安全标准。v1.0 定义了 Build 轨道的 L0～L3，等级越高，对构建来源证明（provenance）和构建平台的要求越严格。
  • in-toto：由项目负责人签名的布局文件定义供应链步骤；每一步由执行者用自己的密钥签名记录输入和输出；验证时检查签名、步骤顺序和产物哈希。

这两者都是为 CI/CD 构建流水线设计的，依赖密钥分发和签名基础设施，对「本地跑一次 Agent 任务」来说太重。

选择借用它们的思想——每一步留下证明、产物用哈希串联——实现得更轻：

  • 每一步的事实写入 append-only 的事件流，每条事件带上一条的哈希，形成哈希链；
  • 每个可写阶段结束后提交一次 git commit，代码状态由 git 固化；
  • 交付结论由确定性规则从事件流推导，不采用 Agent 的自述。

局限哈希链没有签名时，只能发现局部篡改，有写权限的人可以整条重写。改进方向是对链尾签名，并把哈希写入 git notes。

2.3　持久化

Temporal / DBOS / LangGraph checkpointer　vs　SQLite + git commit
  • Temporal：把执行过程记录为 Event History，worker 崩溃后通过重放恢复到断点。生产部署需要独立服务端；开发模式可以单进程跑、用 SQLite 落盘，但官方说明不用于生产。
  • DBOS：库形态，默认使用 SQLite，不需要独立服务。
  • LangGraph checkpointer：按线程保存图的状态，有内存、SQLite、Postgres 等实现。

选择SQLite 记录 Run 和 Stage 的状态与事件，每个可写阶段结束提交 git commit，恢复粒度定在 Stage。 原因是 Stage 内部是一次外部 CLI 进程调用，本身无法重放，失败了只能整阶段重跑；在这个粒度上，记录每个 Stage 的完成状态和 commit 就足够， 不需要引入重放语义，也不需要额外部署服务。

2.4　权限机制

单 CLI 权限规则　vs　多 Provider 控制面

参考对象是 Claude Code 的权限规则：分 allow / ask / deny 三类，按 deny → ask → allow 的顺序判定；也可以通过 PreToolUse hook 在工具调用前加入检查。 在此基础上做了三件事：

  • 审批绑定内容哈希：审批对象是 spec、patch 等内容的哈希，内容一变，旧审批作废。防的是「先拿一个无害的方案通过审批，再换成别的内容执行」。
  • 受保护路径：spec、开发计划、已提交的测试和测试配置、交接文档、记忆文件都列为受保护路径。每个阶段结束后，判定层检查 diff 是否触及受保护路径，触及即判越权——对应上面第二条要求里列出的越权行为。
  • 外部阻塞单独建模：外部 CLI 的登录、限流、确认提示记为 ProviderAction，不和平台审批混在一起，平台也不替用户回答。这是同时管理多个 CLI 才会遇到的问题，单个 CLI 工具没有这一层。

2.5　隔离机制

Docker 容器 / OS 级沙箱　vs　git worktree
  • Docker 容器：进程、文件系统、网络都能隔离，强度最高。但需要安装 Docker，Windows 上还依赖 WSL2 或 Hyper-V，启动也慢。
  • OS 级沙箱：Claude Code 自带的 Bash 沙箱支持 macOS、Linux、WSL2，原生 Windows 上不可用。
  • git worktree：git 自带，创建快（小仓库实测约 10 ms），天然支持分支、diff 和回滚。

选择默认使用 git worktree：每个 Run 一个独立分支，主工作区不受影响； 只读阶段使用用完即删的副本，并比对阶段前后的 tree id，有改动即判违规。

边界worktree 隔离的是「改动」，不是安全沙箱，Agent 进程仍以用户身份运行。所以它要配合 provider 自带的权限模式使用，高风险任务可以切换到容器执行。

2.6　评测

SWE-bench 二值信号　vs　完成度 + 过程指标

SWE-bench 把补丁应用到真实仓库中运行测试，要求原本失败的测试变为通过（FAIL_TO_PASS），原本通过的测试不能变坏（PASS_TO_PASS）， 最终给出一个通过 / 不通过的结果。我们和它一样，以真实执行结果为准，不看模型自述。 但单一的通过 / 不通过结果存在「蒙对也算过」的问题，所以评测除了完成度，还统计过程指标。

做法同一批任务用三种方式运行——直接调用 CLI、muxdev 单 Agent 编排、muxdev 多 Agent 编排—— 对比完成度、质量、证据完整度、可靠性、人工介入次数、成本和耗时。总分中确定性指标占 80%，LLM 评委占 20%，评委可以关闭。

指标直接调用 CLImuxdev 编排
总分0.830.999
证据置信度0.491.0
缺失证据3 项0 项

在 mock provider 上跑 3 个任务的结果。

怎么看这组数它说明的是机制能区分「有证据」和「没证据」的交付。 另外，过程分对编排模式设了 0.55 的下限，对直接调用 CLI 只有 0.25，总分差距里有一部分是这个设定带来的—— 看结论时应以证据置信度和缺失证据数为主。