后续通用 Agent 协作控制平面架构

目的

定义一个通用的 Agent 协作控制平面。它不绑定任何具体项目或产品名称，适用于把多个 coding agent 组织成可分配、可追踪、可恢复、可审查、可治理工作系统的场景。

前提是人类工作已经具备最小闭环。没有任务、Driver、Approver、scope、验收标准、证据和 approval 的人类流程，不应该直接接入 Agent。闭环总纲见 03-人类闭环总纲-human-closure-principles.md。

这类系统不应该从提示词开始设计。提示词是执行层的一部分，真正决定系统能否稳定运行的是控制平面：

工作对象模型
-> 协调策略
-> 持久执行
-> runtime adapter
-> 上下文协议
-> 证据与审查
-> 治理与成本
-> 事件和数据基础设施

分层架构

0. Work Surface
   人类创建任务、查看 run、审查 artifact、做 approval。

1. Product Facts
   Workspace、AgentProfile、WorkItem、TaskRun、RunMessage、Artifact、ApprovalRequest、CostEvent。

2. Coordination
   Direct assignment、planner、manager-worker、handoff、workflow graph。

3. Durable Execution
   Queue、claim、lease、heartbeat、state machine、retry、resume、watchdog。

4. Runtime and Adapters
   Runtime daemon、agent adapter registry、sandbox/worktree、secret grant、provider integration。

5. Context Protocol
   Context packer、scope policy、workspace rules、skills、output contract。

6. Evidence and Governance
   Logs、tool trace、diff、tests、screenshots、PR、budget、audit、human approval。

7. Data and Events
   Postgres、event bus、SSE/WebSocket、object storage、audit log。

关注优先级

1. 工作对象模型

系统要先定义什么是事实。不要把 provider session、聊天历史或 agent 的内部推理当作平台事实。

对象	作用
`Workspace`	团队、仓库、runtime、策略和审计边界
`AgentProfile`	受控执行者，包含 provider、角色、工具、runtime 绑定和策略
`WorkItem` / `Task`	可分配的工作单元，来自 issue、手动输入、automation 或 review request
`TaskScope`	允许修改的 repo/path/module 范围
`TaskRun`	一次 agent 执行尝试
`RunMessage`	append-only 的执行证据流
`Artifact`	patch、日志、截图、报告、diff、PR、测试结果
`ApprovalRequest`	人类决策点
`CostEvent`	token、模型、provider、运行成本记录

2. 持久执行和状态机

这是多 agent 系统和 demo 的分水岭。

必须回答：

谁可以 claim 任务？
如何防止两个 agent 做同一个任务？
claim 后 agent 掉线怎么办？
run 失败、超时、卡住后怎么恢复？
哪些状态允许 retry？
哪些动作必须人工批准？
日志、diff、artifact 怎么绑定到 run？

推荐最小状态机：

Task: backlog -> queued -> running -> in_review -> done
                         -> blocked
                         -> failed
                         -> cancelled

Run: queued -> claimed -> running -> succeeded
                            -> failed
                            -> blocked
                            -> timed_out
                            -> cancelled

3. Agent 协调机制

协调方式比“agent 之间聊天”更重要。

模式	说明	适用阶段
Direct assignment	人把任务分配给一个 agent	MVP
Manager-worker	lead agent 拆任务，人确认后分给 worker agent	MVP+
Workflow graph	plan 编译成 DAG，有 step、dependency、review、retry	V2
Org chart	agent 有上下级、预算、岗位、长期目标	后期

协调必须落到平台事实，而不是隐藏对话：

Lead agent plan
-> WorkItem / child TaskRun
-> Scope
-> Acceptance criteria
-> Artifact
-> Review
-> Merge or retry

4. 消息通讯和语义协议

技术通讯只是管道，语义协议才是核心。

层	关注点
技术通讯	REST、SSE、WebSocket、MCP、daemon heartbeat、Redis/event bus
语义协议	task context、claim payload、run message、artifact ref、approval decision、cost usage

关键协议：

RuntimeHeartbeat
RuntimeClaimRequest
TaskClaimPayload
RunMessageAppend
ArtifactCreated
RunCompleted
RunFailed
ApprovalRequested
ApprovalDecided

5. 上下文协议

提示词应该被放进上下文协议里，而不是作为单独核心。

每次 run 的输入应该由系统拼装：

System policy
+ workspace rules
+ task title and acceptance criteria
+ repo scope
+ recent relevant comments
+ previous run handoff
+ allowed tools
+ secrets grant summary
+ output contract

重点不是写一个很长的 prompt，而是稳定控制：

agent 看什么。
不看什么。
哪些是低信任输入。
哪些是安全策略。
结果必须用什么结构返回。
handoff 给下一位 agent 时保留哪些上下文。

6. 证据、审查和人工介入

Agent 协作控制平面的核心价值是让人不需要盯着终端，但仍然能负责。

UI 必须优先展示：

当前 run 在哪里。
最近有用动作是什么。
产出了什么 artifact。
哪些文件变了。
哪些测试跑过。
哪些风险没解决。
下一步需要谁决定。

一个好的 TaskHandoff 至少应该包含：

Summary
Files changed
Commands run
Tests passed / failed
Known risks
Suggested next action

学习检查清单

读任何 agent 协作系统时，按这个顺序问：

系统的 durable facts 是什么？
task/run 状态机是什么？
agent 如何 claim 工作？
runtime 如何 heartbeat？
run 的输入上下文从哪里来？
agent 输出如何结构化？
失败、超时、卡住怎么恢复？
artifact 和 evidence 怎么存？
human approval 在哪里介入？
budget、secrets、scope、tool policy 怎么执行？

如果一个系统只能回答“prompt 怎么写”，但不能回答以上问题，它还不是可靠的 agent 协作控制平面。

下一步阅读

读完或填完这份文档后，通常继续看：

90-Agent就绪-agent-readiness.md：架构设计前后都要回到就绪清单，确认人类闭环是否稳定。