Harness Delivery：多 Agent 协同交付系统深度解析

一、Harness 是什么

Harness Delivery 是一个基于多 Agent 协同的 AI 驱动软件交付系统。它不是简单的 AI 编程助手，而是一套完整的、可扩展的、面向企业级研发场景的智能交付基础设施。

在传统的软件开发流程中，需求分析、技术设计、编码实现、测试验证、项目管理等环节往往依赖人工协调，信息在不同角色之间传递时容易失真或遗漏。Harness 的核心理念是：用一组专业化的 AI Agent 分别承担不同环节的职责，通过共享的记忆总线实现无缝协同，从而让整个交付链路自动化、智能化。

Harness 的本质是一套「数字研发团队」——每个 Agent 扮演一个专业角色，GAIA 充当团队的共享知识库和沟通中枢。

系统由两个层次构成：

• 子 Agent 层：包含 oracle（知识检索 / 需求分析）、forge（编码实现 / 验证 / 交付）、alfred（项目管理 / 迭代规划）、reveries（Skill 自优化闭环）四个专业化 Agent
• 基础设施层：由 GAIA 担任组织记忆同步层，作为所有 Agent 共享的记忆总线

graph TB
    subgraph 子Agent层["🤖 子 Agent 层 — 专业分工"]
        oracle["oracle
知识检索 / 需求分析"]
        forge["forge
编码实现 / 验证 / 交付"]
        alfred["alfred
项目管理 / 迭代规划"]
        reveries["reveries
Skill 自优化闭环"]
    end

    subgraph 基础设施层["🏗 基础设施层 — 记忆中枢"]
        gaia[("gaia
组织记忆同步层
所有模块共享读写")]
    end

    oracle -->|write| gaia
    forge -->|write| gaia
    alfred -->|write| gaia
    reveries -->|read| gaia
    gaia -->|注入上下文| oracle
    gaia -->|注入上下文| forge
    gaia -->|注入上下文| alfred
    

二、整体架构：两层五模块

Harness 采用清晰的分层架构，将「业务逻辑」与「记忆管理」彻底解耦。这种设计并非偶然——它是从单体过渡到微服务化过程中提炼出的最佳实践在 AI Agent 系统中的投射。

2.1 为什么选择分层

在早期探索中，Harness 曾尝试将所有能力塞入一个超大的 Agent 中。但很快发现，单一 Agent 承担过多职责会导致以下问题：

• 上下文窗口爆炸：需求分析 + 编码 + 项目管理的上下文混合在一起，很快耗尽 Token 预算
• 职责边界模糊：同一个 Agent 既要做技术决策又要写代码，决策质量下降
• 难以独立迭代：修改编码逻辑可能意外影响需求分析行为

分层架构的核心价值在于关注点分离（Separation of Concerns）：子 Agent 专注业务逻辑，GAIA 专注记忆基础设施，各司其职，互不干扰。

2.2 三区数据划分

GAIA 将项目数据按性质划分为三个区域，每个区域使用最合适的存储后端：

2.3 外部依赖体系

Harness 通过 MCP（Model Context Protocol）服务桥接外部系统，形成完整的工具链：

三、四大子 Agent 深度解析

每个子 Agent 都是高度专业化的「数字角色」，拥有独立的 Skill 定义文件（SKILL.md）、执行协议和职责边界。下面逐一剖析其设计哲学和工作方式。

3.1 Oracle —— 知识检索与需求分析师

Oracle 是 Harness 的「大脑前额叶」，负责最耗费认知资源的需求理解和分析工作。

核心职责

• 需求发现与分类：接收用户输入的需求描述（TAPD Story URL 或自然语言），识别任务类型（[DEV]、[SKILL-OPT]、[RESEARCH] 等），判断子类型（NEW / ENHANCE / FIX）
• 信息采集：从 iWiki 获取架构文档，从 Git 获取代码上下文，从 TAPD 获取需求详情和相关评论
• 需求充分性评估：按照标准化维度（目标清晰度、AC 覆盖度、边界定义、依赖可达性、技术可行性等）对需求进行打分
• SPEC 确认：输出结构化的规格确认列表（SPEC-1、SPEC-2 ...），作为后续开发的权威依据
• 仓库范围评估：分析涉及哪些代码仓库，评估接口兼容性和拆分建议

工作流程示例

当 Oracle 接收到一个 [SKILL-OPT] 类型的增强需求时，它会依次执行：

## Oracle 输出示例：SPEC 确认

SPEC-1: harness.md 包含系统总览 ASCII 架构图(7 个子模块)
SPEC-2: harness.md 包含核心仓库索引表(7 行 x 6 字段)
SPEC-3: harness.md 包含 Mermaid 模块协同关系图(6 层 subgraph)
SPEC-4: harness.md 包含 7 个模块的详细职责定义
SPEC-5: harness.md 包含仓库定位决策树(含过渡期注意事项)
SPEC-6: harness.md 顶部包含单体过渡期架构状态章节
SPEC-7: SKILL.md workspace_id=70206324 且含过渡架构提示
SPEC-8: 项目地图含维护说明

综合判定: 通过(无 HIGH 风险维度)
回顾: 2 条 P2 改进意见待后续迭代排入

3.2 Forge —— 编码工程师与交付引擎

Forge 是 Harness 的「双手」，负责将需求转化为可运行的代码，并完成验证和交付全流程。

核心职责

• 编码实现：基于 Oracle 提供的 SPEC 决策生成高质量代码
• 三层 Forger 匹配：通过 forge-creator 生成 specific-forger（特定领域编码器），匹配不到时逐级降级到通用 forger
• 代码验证：自测 + 审查，确保代码符合规范
• 双写交付：同时向 Git 提交代码、向 TAPD 更新进度
• 调研执行（forge-researcher 子模块）：Phase R 调研协议，覆盖三类信息源，两级审查机制

Forger 三层匹配架构

Forge 内部采用精巧的三层 Forger 架构来应对不同类型的编码任务：

graph TD
    A[ForgeTrigger 到达] --> B{Layer 1: Specific Forger}
    B -->|命中| C["specific-forger
针对特定领域的编码器
(如 React Forger, Go Forger)"]
    B -->|未命中| D{Layer 2: 通用 Forger}
    D -->|命中| E["通用 forger
覆盖主流语言和框架"]
    D -->|未命中| F{Layer 3: Fallback}
    F -->|兜底| G["Default Reject
返回无法处理"]

    C --> H[代码生成]
    E --> H
    

数据流约束

Forge 有一个关键的设计约束：orchestrator 只传递 ForgeTrigger，forge 所有业务数据读写均通过 GAIA，无隐式直传。这意味着 Forge 不依赖任何来自调用方的隐式上下文，所有需要的信息都从 GAIA 记忆总线中显式获取。

3.3 Alfred —— 项目经理与迭代规划师

Alfred 是 Harness 的「项目经理」，负责将宏观目标拆解为可执行的 Sprint 和 Task。

核心职责

• Sprint 规划：根据 Oracle 的规模评估和 SPEC 列表，制定合理的迭代计划
• 任务拆解：将大型需求拆分为可独立验收的小任务
• 进度追踪：监控各 Phase 的完成情况，识别阻塞风险
• 资源协调：协调 Oracle、Forge 的工作优先级和依赖关系
• Phase 评论落盘：在每个 Phase 完成时，将里程碑信息写入 Flow Zone 评论

写入权限与最小权限原则

Alfred 对 GAIA 拥有写入权限，但其写入的内容严格限定在迭代规划和项目管理领域。这种设计遵循最小权限原则——防止非相关领域的 Agent 污染记忆数据。

3.4 Reveries —— 自优化学习引擎

Reveries 是 Harness 的「元认知层」，负责让整个系统越用越聪明。

核心职责

• Skill 自优化：分析各 Agent 的历史表现数据，自动调整 Skill 配置和执行策略
• 模式学习：从成功和失败的案例中提取模式，更新最佳实践库
• 反馈闭环：收集用户反馈和系统指标，驱动持续改进

独特的只读定位

与其他三个 Agent 不同，Reveries 对 GAIA 只有读取权限。它从所有历史数据中学习优化模式，但不直接参与业务数据的写入。这个设计是有意为之——避免自优化逻辑意外污染业务数据。

四、GAIA：记忆总线的艺术

如果说四个子 Agent 是 Harness 的四肢和大脑，那么 GAIA 就是它的神经系统和长期记忆。GAIA 的设计是整个系统最精妙的部分之一。

4.1 解决的核心问题

在引入 GAIA 之前，多 Agent 系统面临三大痛点：

1. Agent 间缺乏共享记忆：Oracle 分析需求做出的决策，Forge 无法直接获取，导致重复分析和潜在的决策偏差
2. 上下文无法跨会话保持：会话中断后，新会话需从头开始，之前的进度和上下文全部丢失
3. 知识分散在不同存储后端：项目信息散落在 TAPD、iWiki、Git 等多个系统，缺乏统一的访问入口

4.2 六大核心特性

特性一：统一接口

所有 Agent 通过统一的语义接口访问记忆读写。gaia 对调用方和后端存储均透明——Oracle 写入「评论」和 Forge 读取「上下文」使用的是同一套语义接口，底层如何路由、如何序列化完全封装在 GAIA 内部。

特性二：后端透明

支持多种存储后端（TAPD、iWiki、Git Issue、本地文件）按需切换。存储后端的具体实现细节对 Agent 不可见，适配器模式封装了不同后端的差异。今天用 TAPD，明天切到 Git Issue，Agent 代码无需任何改动。

特性三：双层持久化

这是 GAIA 最具创新性的设计之一：

Phase 级持久化像「正式出版的书籍」，记录经过深思熟虑的结论；Sub-Phase 级持久化像「草稿纸」，保存临时的思考碎片。两者配合使用，兼顾权威性和便利性。

特性四：权威层级

当多个数据源存在冲突时，GAIA 依据严格的权威层级进行裁决：

graph TD
    A["Flow Zone 评论
Phase 级权威"] -->|可覆盖| B["远端索引表
Hot Context 层"]
    B -->|可覆盖| C["本地 Memory 文件
便利快照"]
    C -.->|"禁止反向操作"| A

    style A fill:#dbeafe,stroke:#2563eb
    style B fill:#fef3c7,stroke:#eab308
    style C fill:#f0fdf4,stroke:#22c55e
    

特性五：生命周期管理

Memory 文件有明确的创建、更新、归档、清理规则，避免存储无限膨胀：

• 创建：首次 flush 触发时创建
• 更新：后续 flush 覆盖文件内容
• 删除：Task 完成时删除（[DEV] Phase 7 发布完成，[SKILL-OPT] Phase 6 MR 创建完成）
• 过期清理：30 天内保留活跃文件，30-90 天归档，超过 90 天删除

特性六：格式契约

所有数据遵循标准化的格式契约，确保跨后端的一致性。例如索引表统一使用 5 区块 Schema（Checkpoint、Decisions、Open TODOs、Constraints、Identifiers），Memory 文件统一使用 6 段式 Markdown 结构。

五、核心设计原则

Harness 的架构设计遵循四条核心原则，每一条都在灵活性与约束之间做出了深思熟虑的权衡。

这四条原则并非相互独立，而是相互制约的。追求极致的可扩展性可能会损害接口稳定性，强调数据一致性可能降低灵活性。优秀的架构设计正是在这些张力之间找到平衡点。

六、协议分层：抽象与实现的博弈

GAIA 最具工程深度的设计是其协议分层架构，实现了「业务逻辑与存储实现分离」的目标。

6.1 分层模型

graph TB
    subgraph 抽象层["📐 抽象层协议（存储后端无关）"]
        context["context.md
Context 恢复与写入协议"]
        lifecycle["context-lifecycle.md
Context 生命周期管理"]
    end

    subgraph 实现层["⚙️ 实现层协议（存储后端特定）"]
        tapd["tapd-description-schema.md
TAPD 后端实现"]
        memory["memory-protocol.md
本地文件后端实现"]
        gitissue["git-issue-schema.md
Git Issue 后端实现（示例）"]
    end

    tapd -->|引用规则| context
    memory -->|引用规则| context
    gitissue -->|引用规则| context
    lifecycle -->|适用于| agents["所有 Agent"]

    style abstract fill:#eff6ff,stroke:#2563eb
    style implementation fill:#f0fdf4,stroke:#22c55e
    

6.2 抽象层协议

定义存储后端无关的通用规则，代表性协议包括：

• context.md（Context 恢复与写入协议）：定义 AUTHORITY（权威层级）、INDEX-SCHEMA（索引表抽象格式）、MERGE（区块合并规则）、RESTORE（恢复协议优先级）
• context-lifecycle.md（Context 生命周期管理）：定义裁剪规则、按需检索策略、Phase 边界快照

6.3 实现层协议

定义具体后端的数据格式、解析规则和更新逻辑：

• tapd-description-schema.md：TAPD description 字段的 HTML schema、索引表/非索引表的划分规则、解析和回写逻辑
• memory-protocol.md：本地 6 段式 Markdown 存储规范、Flush 触发条件、生命周期管理

6.4 设计模式

协议分层综合运用了两种经典设计模式：

• 策略模式（Strategy Pattern）：抽象层定义统一接口，不同的实现层提供具体的存储策略
• 适配器模式（Adapter Pattern）：实现层封装了不同后端的 API 差异，向上提供一致的语义接口

七、双层持久化与上下文恢复

跨会话上下文恢复是 GAIA 最实用的能力之一，也是用户感知最强的功能。它的实现依赖于精心设计的四步恢复流程。

7.1 四步恢复流程详解

graph TD
    A["会话启动"] --> B["步骤 1: 检查本地 Memory 文件"]
    B --> C{"Memory 存在且
30 天内修改过?"}
    C -->|是| D["加载热上下文"]
    C -->|否| E["步骤 2: 检查远端索引表"]
    E --> F{"索引表存在?"}
    F -->|是| G["解析 5 个区块"]
    F -->|否| H["步骤 3: 完整评论恢复"]
    H --> I["解析 Phase 标记"]
    I --> J["重建进度索引"]
    D --> K{"步骤 4: 交叉验证"}
    G --> K
    J --> K
    K --> L{"数据一致?"}
    L -->|是| M["使用 Memory 上下文"]
    L -->|否| N["丢弃冲突段落
Flow Zone 为权威"]
    N --> O["输出警告"]
    M --> P["输出恢复摘要"]
    O --> P
    

7.2 Memory 文件的 6 段式结构

# Memory: 1070206324133267421
> Last flushed: 2026-04-06 14:30:00
> Phase: 3 - Sprint Planning

## Context Snapshot    # 当前状态摘要
当前处于 Phase 3 Sprint Planning 阶段...

## Decisions           # 本 Phase 决策
- SPEC-1~8 全部确认通过
- 仓库范围锁定为单仓 harness-delivery-oracle

## Open TODOs          # 待办事项
- [ ] 用户确认 Sprint 计划
- [ ] 开始 Phase 4 实现

## Constraints         # 活跃约束
- 维持单体过渡期架构
- 所有 TAPD 写入必须使用 HTML 格式

## Pending User Asks   # 待回答问题
- 是否需要增加性能基准测试?

## Identifiers         # 关键 ID
- story_id: 1070206324133267421
- workspace_id: 70206324
- branch: feature/harness-map-enhance

7.3 索引表的 5 区块 Schema

远端索引表是跨会话恢复的 Hot Context，包含五个标准区块：

7.4 Flush 触发条件

Memory 文件的写入（Flush）不是随意的，只在以下关键时刻触发：

• Sprint 计划等待审批
• Sprint 边界确认
• 验证失败需要决策
• 用户显式暂停或对话结束
• 上下文接近耗尽（Token 预警）

八、端到端协作流程

理解单个组件之后，让我们看看它们如何在真实场景中协同工作。以一个典型的 [DEV] 类型需求交付为例。

8.1 完整交付流水线

sequenceDiagram
    participant User as 用户
    participant Orchestrator as Orchestrator
    participant Oracle as oracle
    participant Gaia as gaia
    participant Forge as forge
    participant Alfred as alfred

    User->>Orchestrator: 提交需求 (TAPD URL / 自然语言)
    Orchestrator->>Oracle: 分发需求分析任务

    Note over Oracle: Phase 0-1: Discovery + Analysis
    Oracle->>Gaia: 读取项目上下文
    Gaia-->>Oracle: 返回历史决策/约束
    Oracle->>Oracle: 信息采集 + 需求评估
    Oracle->>Gaia: 写入 Phase 1 评论
(SPEC 决策列表)

    Orchestrator->>Alfred: 请求 Sprint 规划
    Alfred->>Gaia: 读取 SPEC + 规模评估
    Alfred->>Alfred: 制定 Sprint 计划
    Alfred->>Gaia: 写入 Sprint 计划

    Note over Forge: Phase 3-7: 编码与交付
    Orchestrator->>Forge: 发送 ForgeTrigger
    Forge->>Gaia: 获取上下文 (SPEC 决策)
    Gaia-->>Forge: 返回决策上下文
    Forge->>Forge: Forger 匹配 + 代码生成
    Forge->>Forge: 自测 + 审查
    Forge->>Gaia: 写入代码变更记录
    Forge-->>Orchistrator: 交付完成通知

    Note over Alfred: Phase 6-7: 收尾
    Alfred->>Gaia: 更新 Phase 状态
    Alfred->>User: 交付报告
    

8.2 关键交互细节

Oracle → Forge 的知识传递

这是最常见的跨 Agent 协作场景。Oracle 分析需求后做出 N 个 SPEC 确认决策，Forge 需要根据这些决策进行编码实现。

没有 GAIA 时，Forge 需要「重新阅读」需求文档并自己做出技术判断，这不仅浪费时间，还可能导致与 Oracle 的决策不一致。有了 GAIA，Forge 直接消费 Oracle 已经验证过的决策结论。

项目路由机制

GAIA 通过三条路径定位目标项目，按优先级依次尝试：

1. URL 解析路径（最高优先级）：扫描输入中的 TAPD URL，提取 workspace_id 匹配项目
2. 关键词激活路径：将输入与 project-map.md 中的激活词匹配
3. 默认项目路径（最低优先级）：URL 和关键词均未命中时使用全局默认配置

九、典型应用场景

9.1 场景一：跨 Agent 知识共享

背景：Oracle 分析一个 [SKILL-OPT] 需求后做出 8 个 SPEC 确认决策，Forge 需要根据这些决策进行编码实现。

执行路径：

1. Oracle 完成需求分析，将 8 个 SPEC 决策写入 GAIA 的 Flow Zone 评论
2. GAIA 同时更新远端索引表，提取决策摘要用于快速查看
3. Orchestrator 触发 Forge 执行编码任务
4. Forge 从 GAIA 获取上下文，直接拿到 Oracle 已确认的 SPEC 列表
5. Forge 基于 SPEC 决策生成实现代码，无需重复分析需求

价值：消除重复劳动，保证决策一致性，将 Oracle→Forge 的交接时间从分钟级降至秒级。

9.2 场景二：跨会话上下文恢复

背景：Phase 2 Sprint 计划完成后用户暂停工作，三天后恢复会话继续 Phase 3。

恢复过程：

1. 检查本地 Memory 文件 → 发现存在且 3 天内修改过 → 加载热上下文
2. Memory 文件包含：Phase 2 已完成的 Checkpoint、已确认的 Decisions、待办的 TODOs
3. 交叉验证：对比 Memory 文件的 current_phase 与远端索引表 → 一致
4. 输出恢复状态：「Recovered from local Memory file (last flushed: 2026-04-06), Phase: 2 - Sprint Planning, Pending: Sprint 计划需用户确认」

价值：用户无需回忆之前讨论了什么、做到哪里了，系统能够自动恢复到正确的上下文状态。

9.3 场景三：存储后端平滑迁移

背景：某团队决定从 TAPD 迁移到 Git Issue 作为项目管理系统。

迁移步骤：

1. 新增实现层协议：创建 git-issue-schema.md，定义 Git Issue 的数据格式、解析规则、更新逻辑
2. 保持抽象层协议不变：context.md 的权威层级、合并规则、恢复优先级完全复用
3. 配置切换：修改 setting.md 的项目管理信息章节，指向 Git Issue 后端
4. 零代码改动：Oracle、Forge、Alfred 的所有记忆操作接口保持不变

价值：迁移成本极低，团队可以根据实际需求灵活选择项目管理工具，不被任何单一平台绑定。

9.4 场景四：组织记忆沉淀

背景：项目过程中产生的决策、TODOs、约束等需要长期保留，作为团队知识库供新成员参考。

持久化机制：

• Flow Zone 评论：每次 Phase 完成时记录决策结论，作为权威的历史记录
• 远端索引表：从评论中摘要关键信息（Phase 状态、决策、TODOs、约束），便于快速浏览
• 本地 Memory 文件：临时记录细粒度状态，完成后自动清理

查询机制：

• 快速查看：通过索引表获取项目当前状态（Phase 进度、关键决策、待办事项）
• 详细追溯：通过 GAIA 读取 Flow Zone 评论，获取完整的决策过程和讨论历史
• 按需加载：context-lifecycle 定义的按需检索策略，只在需要时加载详细内容，保持上下文精简

十、总结与展望

10.1 架构精髓

Harness Delivery 的架构设计可以凝练为几个关键词：分层、协议化、可恢复。

• 分层：子 Agent 层专注业务逻辑，基础设施层专注记忆管理，清晰的两层架构让系统易于理解和演化
• 协议化：通过抽象层/实现层的协议分层，将「做什么」和「怎么做」彻底解耦，后端切换成本极低
• 可恢复：双层持久化 + 四步恢复流程 + 权威层级，保证了在任何中断场景下都能快速回到工作状态

10.2 与传统方案对比

10.3 设计权衡与取舍

没有完美的架构，只有合适的取舍。Harness 在设计中做出的主要权衡包括：

• 初始复杂度 vs 长期收益：协议分层和 GAIA 基础设施增加了初期搭建成本，但在后期迭代和迁移中节省了大量时间
• 粒度 vs 开销：双层持久化和频繁的 flush 操作带来一定的 I/O 开销，但换来了精细的恢复能力
• 约束 vs 灵活性：Magic Words 行为约束（如 A1-A4, C1, E6-E7）限制了 Agent 的自由度，但保证了系统的安全性和可预测性

10.4 未来方向

Harness 仍在快速演进中，以下几个方向值得关注：

1. GAIA 拆分：当前 GAIA 以单体形式运行，未来可能根据用户指令拆分为独立服务
2. 更多 Agent 类型：测试专员（tester）、运维专家（ops）、安全审计员（auditor）等专业角色的加入
3. 更丰富的后端：Jira、Asana、Linear 等更多项目管理平台的实现层协议
4. Reveries 增强：从被动学习进化为主动建议，实现真正的自愈和自适应

在 AI Agent 系统的设计中，最重要的不是让单个 Agent 变得更聪明，而是让多个 Agent 之间的协作变得更顺畅。GAIA 记忆总线正是这一理念的最好诠释。