从单兵到流水线：为什么需要主从 Agent 架构

DeepSeek Harness 的 v0.1 版本已经暴露出一个清晰的信号：单一 Agent 面对真实工程任务时，很快就会在上下文管理和工具调用深度上触顶。想象一个典型的代码审查场景——你需要理解项目结构、检查编码规范、分析潜在漏洞、评估测试覆盖率，最后汇总成可执行的修改建议。如果全部塞进一个 Agent 的上下文窗口，要么信息过载导致推理质量下降，要么反复触发工具调用让 Token 账单失控。

Harness 的解决思路是"编排即插件"。基于 Cordis 元框架，每个 Agent 实例都是独立加载的插件，拥有隔离的会话上下文和工具视图。主 Agent 作为调度中枢，负责任务拆解与结果汇聚；子 Agent 则专注各自子任务，彼此通过 Cordis 的事件总线通信而非直接共享内存。这种架构让复杂流水线变得可维护，也为 Trajectory 日志的逐层追溯提供了天然基础。

场景搭建：自动化代码审查流水线

我们以一个具体的四阶段流水线为例，展示 Harness 中多 Agent 协作的完整链路。

阶段一：主 Agent 的任务拆解与分发

主 Agent 的核心职责不是"干活"，而是"分活"。当收到"审查这个 PR"的指令时，它首先通过文件系统工具扫描变更范围，然后按模块拆分为独立子任务。在 Harness 的标准模式下，主 Agent 会生成类似这样的调度意图：

子任务 1：检查 src/auth/ 目录下的权限校验逻辑（安全专家 Agent）
子任务 2：评估新增 API 的测试覆盖率（测试分析 Agent）  
子任务 3：核对是否符合项目编码规范（风格检查 Agent）
子任务 4：汇总以上结果，生成可执行的修改建议（报告聚合 Agent）

这里的关键设计是延迟绑定。主 Agent 并不直接创建子 Agent 实例，而是向 Cordis 事件总线投递 agent:dispatch 事件，携带任务描述、所需工具集和预期输出格式。Cordis 的依赖注入机制会根据当前运行模式，将事件路由到对应的子 Agent 工厂插件。这意味着同样的调度逻辑，在标准模式下可能启动四个独立进程，而在极简模式下则可能复用同一进程的不同上下文——切换只需改配置，无需动代码。

阶段二：子 Agent 的上下文隔离机制

每个子 Agent 在 Harness 中都是一个独立的 Cordis 插件实例，拥有私有的 ctx 上下文对象。这种隔离体现在三个层面：

隔离维度	具体表现	实际影响
会话历史	仅追加写入各自的 Trajectory 日志	子 Agent 的"思考过程"不会污染主 Agent 的上下文
工具视图	通过 ctx.tools 按需注册子集	安全专家 Agent 可访问 AST 解析器，风格检查 Agent 则不行
模型配置	独立绑定模型适配器插件	复杂子任务可用更强的模型，简单任务换轻量模型节省 Token

这种隔离的代价是信息传递的显式化。子 Agent 不能"偷看"其他实例的内存，所有中间结果必须通过事件或返回值提交。在代码审查场景中，安全专家 Agent 发现潜在 SQL 注入后，会触发 agent:report:finding 事件，携带漏洞位置、严重等级和修复建议——而不是让主 Agent 去翻它的内部状态。

阶段三：Cordis 事件驱动的跨 Agent 通信

Cordis 的事件机制是多 Agent 协作的"神经系统"。与直接函数调用不同，事件通信天然支持异步和解耦。在我们的流水线中，实际运行的事件流大致如下：

1. 主 Agent 发布 review:started 事件，携带 PR 元数据
2. 三个子 Agent 并行订阅该事件，各自启动分析
3. 子 Agent 完成时发布 review:partial:done 事件
4. 报告聚合 Agent 订阅上述事件，收到全部三个结果后触发 review:completed
5. 主 Agent 捕获最终事件，格式化输出

Harness 的 Trajectory 视图会完整记录这一事件序列。你可以按来源过滤，看到安全专家 Agent 在 14:23:07.342 触发了 agent:tool:use（调用 AST 解析器），又在 14:23:15.891 发布了 agent:report:finding。这种细粒度追溯在排查"为什么子 Agent 没响应"时 invaluable——可能是事件订阅配置错误，也可能是某个子 Agent 在工具调用时抛异常导致提前退出。

阶段四：结果汇聚与最终报告

报告聚合 Agent 的设计体现了 Harness 的"模式组合"思想。它本身不绑定固定模型，而是根据上游子 Agent 的输出格式动态选择解析策略。如果安全专家返回的是结构化 JSON，测试分析 Agent 返回的是 Markdown 表格，它会通过 ctx.llm 服务请求一次轻量转换，统一为预定义的审查报告模板。

这里有个实用技巧：在 Trajectory 中搜索 context:injection 标签，可以快速定位主 Agent 合并各子结果时的上下文组装点。你会发现 Harness 自动记录了每次上下文注入的 Token 开销——这正是下一节要讨论的优化重点。

Trajectory 中的子 Agent 调度记录解读

Harness 的 Trajectory 机制不是简单的操作日志，而是可回放的事件流。在多 Agent 场景下，理解其记录结构对调试至关重要。

一个典型的子 Agent 调度记录包含三层嵌套：

[14:23:07] agent:dispatch {id: "security-01", task: "audit auth module", parent: "main-01"}
  [14:23:07] context:injection {tokens: 2847, source: "system-prompt"}
  [14:23:08] llm:completion {model: "deepseek-v4-pro", tokens_in: 3120, tokens_out: 487}
    [14:23:09] tool:use {name: "ast_parse", args: {...}}
    [14:23:10] tool:result {output: "...", tokens: 156}
  [14:23:15] agent:report:finding {severity: "high", ...}
[14:23:15] agent:dispatch:complete {id: "security-01", duration: 8123ms}

关键观察点：

• agent:dispatch 与 agent:dispatch:complete 的间隔：反映子 Agent 实际执行时长，若远超过模型推理时间，需检查工具调用延迟
• context:injection 的 Token 数：Harness 会自动注入系统提示词和父上下文摘要，这部分开销常被低估
• 嵌套层级：子 Agent 内部是否又触发了孙 Agent？v0.1 版本允许理论上无限嵌套，但深度超过 3 层时 Cordis 的依赖解析可能触发循环检测

Trajectory 的"分叉"功能在这里特别有用。当你发现某个子 Agent 的结果异常时，可以从其 agent:dispatch 事件创建独立回放，无需重跑整个流水线。这在调试"仅特定输入下才失败"的偶发问题时，能节省大量时间和 API 费用。

Token 消耗膨胀的优化思路

多 Agent 架构的隐性成本在于上下文重复。每个子 Agent 都需要独立加载系统提示词和项目背景，当子 Agent 数量增加时，这部分固定开销线性增长。基于 Harness 的实测经验，分享三个有效的优化方向。

上下文摘要而非全量传递

主 Agent 向子 Agent 分发任务时，默认会注入完整的父上下文。对于代码审查场景，通常只需传递"变更文件列表 + 相关依赖图"而非整个项目结构。Harness 允许在 agent:dispatch 时指定 context: "summary" 模式，主 Agent 会先通过一次轻量 LLM 调用生成压缩摘要，再将摘要作为子 Agent 的上下文注入。实测在 10 万 Token 级别的项目中，这能减少 35%-50% 的重复开销。

模型分级策略

并非所有子 Agent 都需要最强模型。在我们的流水线中：

• 风格检查 Agent → 极简模式 + 轻量模型（规则驱动，无需复杂推理）
• 测试分析 Agent → 标准模式 + 中等模型（需要理解覆盖率数据）
• 安全专家 Agent → 标准模式 + 最强模型（漏洞分析需要深度推理）

Harness 的 Cordis 架构让这种分级变得透明——每个子 Agent 独立声明依赖的 llm 服务实现，主 Agent 无需关心底层模型切换。

结果缓存与复用

对于重复性子任务，Harness 支持基于 Trajectory 哈希的结果缓存。当检测到相同的任务描述和输入文件哈希时，可直接复用历史结果而非重新调用模型。在代码审查的增量更新场景中（如修复上一轮评论后重新审查），这能避免大量重复劳动。

v0.1 版本的现实考量

需要坦诚面对的是，Harness 目前处于开发者预览阶段，多智能体 API 的稳定性尚不成熟。过去两周的社区反馈中，以下问题较为集中：

• 事件顺序的非确定性：高并发场景下，子 Agent 的 agent:report:* 事件到达顺序可能与预期不符，建议业务层显式携带序列号或时间戳做排序校验
• 上下文注入的 Token 上限：当前版本在子 Agent 上下文超过 16K Token 时可能触发截断，但截断策略未完全文档化，需通过 Trajectory 实际验证
• 插件热加载的边界：Cordis 支持动态卸载插件，但子 Agent 实例的状态清理存在延迟，频繁创建销毁可能导致内存增长

建议在生产环境使用前，先用 Trajectory 的"回放"功能对完整流水线做压力测试，观察 10 次以上重复运行下的 Token 消耗稳定性和内存基线。Harness 的 GitHub 仓库更新频繁，关注 agent-orchestration 标签下的 issue 能获取第一手的接口变更信息。

从单 Agent 到多 Agent 流水线，Harness 提供的不仅是技术实现，更是一种"把复杂任务拆解为可组合、可观测、可优化单元"的工程思维。在 v0.1 的"毛坯房"里，已经能窥见这种架构的潜力——前提是愿意花时间去理解 Cordis 的事件语义，以及 Trajectory 背后那份"一切运行皆有迹可循"的设计坚持。