详细设计说明

用三层架构把产品入口、运行时协同和内核治理分开

这份文档明确 Tier 1 应用层、Tier 2 协同运行时、Tier 3 执行内核三层的边界与协作契约。评审重点是每层"承担什么 / 不承担什么"是否能在版本演进中保持稳定，让上层产品可替换、运行时可演进、内核保持治理底线。

1. 定位与概念

1.1 总体架构图

下图按 Tier 1 / Tier 2 / Tier 3 三条横向带组织，每条带列出该层的主要模块；顶部是终端用户与外部系统入口，底部是基础设施依赖；右侧贯穿三层的纵列是横切关注点（治理、可观测、隔离），它们不属于任何单层，但渗透每一层。点击任一层标签跳到对应章节。

1.2 跨层调用时序图

下图把一次完整任务拆开来看：从用户在 Tier 1 发出请求，经 Tier 2 协同运行时派单，到 Tier 3 内核执行单次 Run，再原路返回 Tier 1。点击顶部任一 lifeline 色块跳到对应章节。这张图也是后续每个模块设计文档的"坐标系"。

1.3 为什么三层

"产品入口、运行时、内核"听起来像 MVC，但三层架构要解决的是变化频率不一致带来的工程问题。下表是不分层时的具体缺口：

三层架构解决的具体问题：

1. 把变化频率不同的关注点拆开——T1 跟业务变、T2 跟协作模式变、T3 跟治理与合规变，互不干扰
2. 给"多 Agent 协作"一个独立运行时——T2 是 Coordinator 的家，机制（fan-out / sequential / lead-driven）和承载实体（Team / Session）都在这层
3. 让治理沉到内核——状态机、Policy、HITL、Trace 不再每个产品自己实现一遍，T3 提供统一基线
4. 让基础设施可替换——LLM、沙箱、向量库走 Provider 抽象，业务代码不感知具体后端
5. 让跨层只通过契约通信——T1 不读 RunState 内部字段、T2 不读 RunContext 私有结构，避免内核演进锁死

1.4 三层契约定位

2. Tier 1 · 应用层

2.1 模块清单

2.2 与下层的接口定位

应用层不直接执行任务，所有需要"跑一次 Agent"的能力都通过提交 Job下沉到 Tier 2。具体接口位置：

• 提交任务——把用户消息、上下文、Persona / Team 引用、必要的 caller_extra（团队 ID、风险标签等）打包成 Job，投递到 T2 队列
• 查询状态——通过 RunTrace / DelegationTrace 的只读视图展示进度，不直接读 T2/T3 内部数据结构
• 响应 HITL——审批工作台收到 T3 的审批请求，把决策结果回传给 T2，由 T2 通知 T3 继续
• 治理配置下发——HITL 阈值、成本预算、Skill 白名单等在 T1 编辑后，通过配置广播让 T2/T3 在下一次 Run 生效，不修改正在跑的 Run

2.3 设计原则

1. UI 状态归 T1——草稿、表单、编辑器状态属于产品层；运行时不持有这些
2. 实体的真值在 T1——Persona / Team / Skill 的配置定义归 T1，T2/T3 只读这些定义的快照
3. 不要在 T1 拼协作逻辑——只要涉及"派给多个 Agent / 串接多步"，立刻下沉 T2，避免 T1 长成第二个运行时

3. Tier 2 · 协同运行时

3.1 模块清单

3.2 与上下层的接口定位

• 对 T1 暴露——投递 Job 接口、查询 RunTrace / DelegationTrace 的只读视图、HITL 决策回调入口
• 对 T3 调用——为每个 Agent 创建一次 Run，传入 RunConfig 与 caller_extra；接收 RunResult 后再做汇总；把 T3 的 HITL 请求转回 T1 审批工作台
• 不感知——产品 UI 状态、组织实体定义；不直接读 T3 内部的 RunState 内部字段

3.3 设计原则

1. 机制 ≠ 产品——T2 不知道用户在做什么业务，只知道协作模式。新业务通过组合现有协作模式落地，不要在 T2 加业务分支
2. 多 Agent 协作的承载实体在 T2——Team 在 T1 定义但 T2 用它驱动协作；AgentSession 完全在 T2，T1 只是消费它的快照
3. 共享记忆 scope 由 T2 管——T3 的单 Run 不知道"团队级"概念，所有 scope 路由都在 T2 完成
4. 策略缺失回退默认——任何 team / persona 级配置缺失时回退到全局默认，不让 T3 看到空值

4. Tier 3 · 执行内核

4.1 模块清单

详见 Harness Kernel 设计文档。本章只标定它在三层架构里的位置与边界。

4.2 与上下层的接口定位

• 对 T2 暴露——create_run（接收 RunConfig + caller_extra）、ResultSink（输出 RunResult + 终态）、HITL 请求/回调通道
• 对外部依赖——LLM Provider、Sandbox Provider 通过抽象层调用，可在不修改内核代码的前提下替换具体后端
• 不感知——多 Agent 协作、Team、Session、Job；T3 只看到自己被指派的一次 Run

4.3 设计原则

1. 单 Run 纯粹——内核只跑一次 Run，不知道这个 Run 是 child 还是 root、属不属于某个 team
2. 所有终态必经 Trace——SUCCEEDED / REJECTED / FAILED / TIMEOUT 在写入终态前必须先写 Trace，这是治理底线
3. Policy 与 HITL 双守门员——结构 / 权限 / 成本 / 安全四类规则在 ⑤ 自动判断；不可逆动作必须经 ⑦ 人工审批
4. Provider 抽象——LLM 与 Sandbox 走 Provider，OpenClaw 非必须、可替换为 Hermes Agent / K8s 等
5. 内核稳定优先于功能堆叠——内核演进遵循"打基础"节奏，不为短期产品需求破坏边界

5. 横切关注点

5.1 治理

治理是"谁可以做什么、在什么预算 / 风险 / 合规边界内、出了问题如何追责"。三层各自的落点：

5.2 可观测

可观测是"任何一次 Run 都要可回溯、可解释、可重放"。三层各自的落点：

5.3 隔离

隔离是"租户 / 组织 / 团队 / 个人 / 凭据 / 沙箱执行边界"在三层都要保持一致，任何一层泄漏都意味着治理失败。三层各自的落点：

6. 跨层契约

6.1 T1 ↔ T2 契约

6.2 T2 ↔ T3 契约

6.3 契约稳定性原则

1. caller_extra 是透传通道——T2 想给 T3 任何上下文都通过 caller_extra；T3 不解析这些字段，只在 Trace 留痕
2. 禁止跨层私有结构——T1 不读 RunState 内部字段、T2 不读 RunContext 私有结构；只通过上述契约通信
3. 新增字段向后兼容——契约新增字段必须可选（带默认值），下层旧版本能忽略不识别的字段
4. HITL 审批跨两条契约——T3 发审批请求 → T2 转 T1 → T1 用户决策 → T2 回传 T3，途中不能丢、超时要降级到拒绝
5. Trace 是单向写——只有 T3 写、T2 串接、T1 读，没有反向调用