在 AI 编码工具快速演进的今天，协议层（如 MCP、skills）已经建立了 agent 与外部系统交互的标准，但一个根本性的工程挑战始终未得到充分解决：如何对 AI 编码行为进行结构化、可重复的评估？当模型对同一问题产生不同路径的执行结果时，如何建立确定的测评框架？Archon 作为首个开源的 AI 编码 harness builder，给出了一套以 YAML 为核心的工程化解法。

为什么需要专门的 AI 编码 Harness

传统的软件测试框架（如 pytest、Jest）针对的是确定性代码 —— 给定相同输入，必然产生相同输出。然而，AI 编码 agent 的行为具有内在的概率性：同一模型对「修复这个 bug」的请求，可能跳过规划阶段、忘记运行测试、或者生成的 PR 描述不符合团队规范。这种非确定性使得传统的测试范式难以直接套用。

Archon 的核心洞察在于：AI 编码需要一种工作流引擎，将开发过程的结构化与 AI 执行的灵活性分离。它借鉴了 Dockerfiles 对基础设施的抽象以及 GitHub Actions 对 CI/CD 的抽象，用类似的思想为 AI 编码工作流建立标准化的 harness 框架。通过预先定义工作流的阶段、验证门控和产出物，AI 在每个步骤中填充智能，但整体结构由用户拥有且保持确定性。

架构分层：五个核心组件

Archon 的架构采用清晰的五层设计，每一层承担独立的职责，共同构成完整的 harness 基础设施。

平台适配器层位于系统最顶端，负责接收来自不同入口的请求。Archon 支持 Web UI、命令行、Slack、Telegram、Discord 以及 GitHub Webhook 等多种接入方式。这意味着团队可以在习惯的协作环境中触发 AI 编码工作流，而无需改变现有工作习惯。所有的外部请求最终都被转换为统一的内部消息格式，送入编排层处理。

** 编排器（Orchestrator）** 是整个系统的中枢，负责消息路由与上下文管理。它维护着会话状态、管理上下文窗口，并且在多个并发工作流之间进行资源调度。当用户提交一个请求时，编排器决定使用哪个工作流、如何分配 AI 节点与确定性节点的执行顺序、以及何时需要暂停等待人类介入。

** 工作流执行器（Workflow Executor）** 是 Archon 的核心创新所在。它解析 YAML 定义的有向无环图（DAG），按照依赖关系调度节点执行。每个节点可以是确定性的（如 bash 脚本、测试运行），也可以是 AI 驱动的（如代码生成、代码审查）。更关键的是，执行器支持循环节点，允许 AI 重复执行直到满足特定条件 —— 例如「所有任务完成」或「测试通过」。

AI 助手客户端层负责与具体的 AI 模型交互。目前 Archon 原生支持 Claude Code 和 OpenAI Codex 两个主流 AI 编码助手。通过统一的客户端接口，工作流执行器可以切换不同的 AI 后端，而无需修改工作流定义。这种设计为多模型评估提供了基础设施支持 —— 同一工作流可以使用不同模型执行，结果具有可比性。

持久化层采用 SQLite 或 PostgreSQL 存储七张核心表，分别管理代码库信息、会话记录、工作流运行历史、隔离环境、消息历史以及工作流事件日志。这一层不仅提供了完整的审计追踪能力，也为后续的评估分析奠定了数据基础。

YAML 工作流的设计哲学

Archon 工作流采用 YAML 格式定义，这种选择有几方面的工程考量。YAML 声明式的语法使得工作流定义易于版本控制、代码审查和团队共享 —— 你可以像管理代码一样管理 AI 开发过程。以下是一个典型的工作流示例结构：

nodes:
  - id: plan
    prompt: "探索代码库并创建实现计划"
  - id: implement
    depends_on: [plan]
    loop:
      prompt: "阅读计划，实现下一个任务，运行验证"
      until: ALL_TASKS_COMPLETE
      fresh_context: true
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"
  - id: review
    depends_on: [run-tests]
    prompt: "根据计划审查所有变更，修复任何问题"
  - id: approve
    depends_on: [review]
    loop:
      prompt: "展示变更供审查，处理反馈"
      until: APPROVED
      interactive: true
  - id: create-pr
    depends_on: [approve]
    prompt: "推送变更并创建拉取请求"

这个示例展示了 Archon 的几个关键设计原则。首先是阶段分离：规划、实现、验证、审查、批准、PR 创建形成清晰的流水线，每个阶段有明确的入口条件和产出物。其次是确定性与 AI 的混合：run-tests 节点是纯确定性的 bash 命令，而 implement 和 review 节点则调用 AI 模型。AI 仅在真正需要判断力的环节发挥作用，这既控制了成本，也提高了可预测性。第三是循环与条件：loop 节点允许 AI 迭代执行，适合需要多次尝试才能完成的任务（如修复测试直到通过）。第四是人机协作门控：approve 节点设置 interactive: true，强制工作流暂停等待人类批准，这为关键决策保留了人工介入点。

可重复性的工程实现

实现 AI 编码的可重复性需要从多个维度入手，Archon 在架构层面提供了系统性支持。

环境隔离是首要保障。每次工作流运行都基于独立的 git worktree，这意味着多个并行任务之间不会产生文件冲突。你可以让五个 AI agent 同时修复五个不同的 bug，每个 agent 在隔离的分支和目录中工作，最终的 PR 合并也是确定性的。

模型与版本 pinning是另一关键机制。在 YAML 节点中可以指定使用的 AI 客户端和模型版本，这使得同一工作流在不同时间的执行使用相同的模型配置。配合环境变量的版本锁定，整个执行堆栈可以完整复现。

可观测性与审计通过持久化层的七张表实现。每次工作流运行都会记录完整的执行轨迹：哪些节点被执行、每个节点的输入输出、耗时、是否成功、产生了哪些产物（如 PR 链接、测试报告）。这些数据不仅支持事后分析，也为评估不同模型或不同工作流策略提供了量化基础。

评估框架的关键维度

基于 Archon 的架构特性，可以建立以下评估维度来衡量 AI 编码 harness 的有效性。

架构清晰度与模块化程度关注节点是否成为可组合、可复用的单元。理想的 harness 应该能够通过组合现有节点类型来表达新的工作流，而无需修改核心引擎。Archon 的 YAML DAG 设计正是这一理念的体现。

确定性保障是核心指标。需要验证：给定相同输入（问题描述、代码库状态、模型版本），工作流是否产生相同的执行路径和最终产物。可以通过多次运行同一工作流并对比执行轨迹来量化这一指标。

编排模型的丰富度决定了 harness 能否表达复杂的开发流程。支持并行执行、失败重试、退避策略、依赖感知的调度，这些都是工程化 harness 的必备能力。Archon 目前支持基础的 DAG 调度和循环节点，但在高级调度策略（如条件分支、动态重规划）方面仍有发展空间。

人机协作机制的成熟度影响实际落地。Archon 通过 interactive 节点支持人类审批门控，但更细粒度的交互（如在执行过程中插入问题澄清、要求选择实现策略）可能需要进一步的节点类型支持。

环境保真度决定了测试结果的可迁移性。如果在本地开发环境通过的工作流在 CI 环境中失败，说明环境差异引入了不确定性。Docker 容器化和依赖锁定是当前的缓解手段。

实践建议与落地参数

对于希望在团队中引入 Archon 的工程实践，建议从以下参数开始：

首先，工作流文件统一放在仓库的 .archon/workflows/ 目录下，与代码一起版本管理。这确保了整个团队共享同一套开发流程定义，每次代码审查都可以同时评审相关的 AI 工作流变更。

其次，初期可以选择 3 到 4 个节点类型的最小可行工作流进行验证，例如「问题分类 → 代码实现 → 测试验证 → PR 创建」的线性流程。在此基础上逐步增加循环节点、审查节点和多人审批门控。

第三，建立模型版本管理制度。在工作流中明确指定使用的 AI 客户端和模型名称，并通过环境变量管理 API 密钥。重要特性上线前，建议在不同模型版本间进行 A/B 测试，量化评估效果差异。

第四，充分利用 Archon 的 17 个内置工作流作为学习起点。这些预置工作流覆盖了从问题修复到全面代码审查的常见场景，理解它们的实现方式是掌握 Archon 设计模式的最快途径。

小结

Archon 作为首个开源的 AI 编码 harness builder，提供了一种结构化、工程化的方式来定义和执行 AI 编码工作流。通过 YAML 驱动的 DAG 编排、确定性节点与 AI 节点的混合设计、git worktree 环境隔离以及完整的事件日志，它为 AI 编码的可重复性评估奠定了基础设施层面的基础。虽然当前的编排能力仍处于起步阶段（主要支持线性流程和简单循环），但其核心架构思路 —— 将 AI 的创造力约束在确定性的工作流骨架中 —— 为建立可靠的 AI 编码评估体系指明了方向。随着更多评估维度的量化指标和更丰富的节点类型加入，harness 层有望成为 AI 软件工程基础设施的关键拼图。

参考资料