在 Coding Agent 的实践过程中，我时常在想：

• 有了必要的知识、workspace、skill、tool 等，Coding Agent 是否就足够了呢？
• 人在面对同样的需求的时候，又是怎么开发的呢？

恰好，最近发现上海人工智能实验室发表了论文 Harness of Harness:Multi-Day Autonomous Software Development with Continual Improvement，在论文中，研究者们利用 HoH 在无人工干预的情况下，花了 6 天时间、历经 70 多次 Loop 完成了一个 FPS 游戏。

给 Agent 一个大需求，然后呢？

在 HoH 的论文中，作者把这个现象称作：repetitive local repairs。

论文中的 Harness of Harness 的核心思想其实就是借鉴了人类工程师开发过程中的小步快跑的迭代思想，并把这套思想抽象成了一层工程 Harness 层。

与其说是HoH，倒不如说是：围绕现有 Coding Agent 的能力（Codex、Claude Code……），对软件开发需求组织持续的规划、开发与测试，让一轮的结果能够指导下一轮，并最终完成需求。

HoH 的具体应用案例

• continual improvement capabilities：软件功能的持续增加和迭代
• autonomous：全自主的开发过程

上海人工智能实验室团队用 HoH，用时 6 天，迭代了 70 多次，在无人接管的情况下完成一个可玩的 FPS 游戏。

图：作者官网的 Fusepoint 实机展示封面。打开官网视频。

整个迭代的过程如下图所示：

• 横轴是迭代次数，纵轴是尚未关闭的问题数量
• 横轴上方的蓝色、紫色标记分别表示新发现问题和已关闭问题
• 曲线与浅色点展示问题数量的趋势与记录值
• 截图与标签标示开发成果，从初始原型、地图和武器，逐步扩展到音效、界面、动画、战斗 AI 和可玩版本。

在迭代 70 个 Loop 之后，作者发现：开发并非单调改善，验证过的行为仍可能会因为后续的修改而破坏（人类工程师也存在这个问题）。

• 81 个问题中关闭了 65 个，仍有 16 个未解决
• 有 17 个问题曾因回归测试而重新打开

对如上的图的分析，我们可以得到如下的结论：

1. 问题数量上升不能直接等同于质量下降。 一个尚未运行的空项目可能“没有已知问题”，但不代表质量高。新增功能扩大了可测试范围，也会暴露更多缺口。因此，应结合功能完成情况一起解读曲线。

2. 问题关闭也不等于永久解决。 长期迭代需要保留验证历史，并持续检查回归。否则，下一轮可能在不知道的情况下破坏上一轮成果。

HoH 管的是整个开发过程

HoH 负责的其实是整个开发过程，也就是整个敏捷迭代过程中的非开发部分：

• 拆分目标任务
• 评估具体整体目标的差距
• 独立验收
• ……

%%{init: {"flowchart": {"nodeSpacing": 35, "rankSpacing": 25}, "themeVariables": {"fontSize": "16px"}}}%%flowchart TB    subgraph C["第一层：Codex"]        direction LR        CG["目标
执行当前交付的
具体任务"]        CP["执行能力
理解任务、读取项目、调用工具
编写代码、运行测试、检查结果"]        CO["交付结果
代码变更、执行结果
或分析报告"]        CG --- CP --- CO    end    subgraph H["第二层：HoH"]        direction LR        HG["目标
通过多轮迭代
逐步实现整体需求"]        HP["组织过程
拆分目标 → 开发 → 独立验收
根据证据规划下一轮"]        HS["持续保留
当前软件、验证证据
未解决问题"]        HG --- HP --- HS    end    C -->|"返回结果，支持验收与下一轮决策"| H    H -->|"下达本轮任务与上下文"| C    style H fill:#F2EDFC,stroke:#8064AD,stroke-width:2px    style C fill:#E8F4F1,stroke:#318575,stroke-width:2px

$$(A_{t-1}, \mathcal{E}_{t-1}) \xrightarrow{\text{loop } t \text{ under } \mathcal{S}} (A_t, \mathcal{E}_t)$$

• $A_t$ denote the software artifact state after loop $t$
• $\mathcal{E}_t$ denote the execution evidence state obtained by evaluating $A_t$
• $\mathcal{S}$ denote the software specification, PRD

整个 HoH 的流程如下图所示：

左上需求 → 上方 Planner → 右下 Developer → 左下 QA → 返回 Planner。

可以用“执行环境”和“项目组织”来理解两层分工：

1
2
3
4
5
6

第二层：HoH
决定本轮目标 → 安排开发 → 组织验收 → 根据结果重新规划
                         │
                         ▼
第一层：已有 coding harness
读文件、使用工具、修改代码、运行与检查程序

图中央的 harness 是执行基础，外圈负责组织其参与整个项目。三个角色可以使用同一个模型，分别承担规划、开发与验收职责。

HoH 通过三个角色组织每轮迭代的开发：

Project Planner 从之前的迭代证据中生成本轮计划：

因此，开发计划不只是待办清单，还必须写“保留什么”和“怎么验收”。

Throughout this process, HoH specifies the artifacts and evidence that agents must deliver, but does not prescribe a rigid workflow for producing them.

实际开发中，我们是怎么迭代的？

这个需求可以按“玩家能完成什么行为”拆成可验证的增量迭代开发。

第一轮：先有一个能走通的小流程

目标可以很简单：

1
2
3

目标：玩家可以移动、跳跃，并从起点走到终点。
范围：单个测试关卡、基础碰撞、终点检测。
验收：从启动游戏到到达终点，实际操作跑通一次。

RD 做完后，QA 验收：

这里最重要的变化是：下一轮接收到具体问题和已验证行为，不必只依赖一句“基本完成”。

第二轮：修复问题，同时补齐一段用户体验

根据上轮证据更新计划：

1
2
3
4
5
6
7
8
9
10

本轮任务：
- 修复平台边缘穿透。
- 到达终点后显示胜利界面。

保留约束：
- 已验证的左右移动和跳跃继续有效。

验收：
- 重放平台边缘跳跃路径。
- 实际到达终点，确认胜利界面出现。

整体画面美化可以留到后续轮次，当前范围聚焦于碰撞修复和胜利反馈。

小增量的价值是让变化和结果能够对应。 如果一轮同时改碰撞、菜单、存档和地图，失败时就很难知道是哪一部分造成的。

第三轮：把“可见”补齐为“可用”

下一轮目标可以变成：进入胜利状态后停止角色输入，增加重新开始，并恢复初始状态。

验收需要连续执行：

1

启动 → 移动与跳跃 → 到达终点 → 胜利 → 重开 → 再次移动

三轮之后，发生了什么？

需求仍是原来的需求，但实现顺序会随着观察结果调整。这就是“大需求逐步完成”最容易理解的过程。

实验：结构化循环比简单续跑好吗？

先看主结果

论文比较了三种 harness–model 配置。官方结果表：

最关键的追问：是不是因为多花了 token？

下面是论文对 Codex 的开发次数对照，均使用 GameCraft 质量分。论文表 2

我们可以借鉴什么？

从工程分类上，可以把 HoH 理解为面向软件开发的一种具体循环设计。它的启发在于：为每轮规定清楚输入、交付和证据，让后续工作有可靠依据。

• 这一轮做什么？ 从整体需求和实际缺口中选择有限、完整的目标。
• 哪些旧功能不能坏？ 把已验证行为写入保留约束。
• 拿什么证明完成？ 用运行结果和可复查的证据支持验收。

代码与证据共同积累，下一轮规划时，根据上一轮的迭代信息、整体的目标信息综合规划，而不仅仅是 TO-DO List。

谷歌刚发布的关于 WikiSkill: Compiling Agent Experience into Persistent Knowledge for Skill Evolution 的论文值得认真的研究一下。

很多人都会说：这里面提到的好多观点我之前就提出过了。但是更为重要的是：谷歌没有停留在观点的浅薄层面，而是从实证的角度给出了可实践的理论支撑。

论文中的两个分离蛮值的思考的：

1. 在 Skills 进化的过程中，把原始执行路径、知识库、Skills 进化分离开来；
2. 在 Skills 进化的过程中，把 Skills 发现 与 Skills 执行这两个阶段分离开来；

同时，论文中提出的：Skills 进化与 LLM Scaling 的互补性、Skills 进化的可迁移性也是我们在 Agent 自进化过程中特别需要关注的地方。

术语

• Self-evolved skills：模型 A 从自己的轨迹中演化 Skill，模型 A 再使用这个 Skill 执行任务。
• Ablation studies（消融研究）：刻意去掉模型或系统中的某个组件、模块、特征、损失项，观察性能下降多少，以此证明这个组件是否有用、贡献有多大。简单来说，就是拿掉一部分，观察效果相差多少，从而验证它的价值。
• Procedural knowledge：操作、流程、步骤、技能和执行序列；告诉 Agent 如何完成一件事，是一种可执行的知识。

Abstract

Agent skills package specialized knowledge and workflows into reusable resources that extend AI agent capabilities. Recent work automatically discovers such skills from agent experience, which enables agents to progressively adapt through interaction. However, the insights that guide skill development typically remain scattered across optimization histories, limiting their systematic reuse across iterations.

• Insights：并非泛指所有运行日志，而是从成功或失败中得到的、对未来有用的认识。原始轨迹是事实，Insight 则是从事实中抽象出的可复用规律。例如：
  • Agent 为什么失败；
  • 哪种操作顺序更可靠；
  • 哪类错误反复出现；
  • 某个 Skill 规则为什么有效；
  • 某个修改为什么被拒绝；
  • 某个方案只适用于小模型，还是具有普遍性。

1
2
3
4
5
6
7
8
9

表面现象：
Agent 重复拿起、检查、放回同一个物品。

Insight：
Agent 没有记录“某个物品已经执行过哪些操作”，
所以它会把同一状态误判成新的任务进展。

可执行规则：
每种操作对同一物品最多执行一次。

• Scattered across optimization histories：指 Skill 经历多轮迭代优化后，有用信息可能散落在不同地方。例如：

1
2
3
4
5
6
7
8
9
10
11

第 1 轮失败轨迹：发现 Agent 会重复操作
  → 信息位于 trace

第 2 轮分析日志：怀疑缺少状态追踪
  → 信息位于分析器输出

第 3 轮 Skill 提案：加入一个抽象的“面向目标行动”规则
  → 信息位于 Skill diff

第 3 轮验证记录：该规则没有提高成绩，被拒绝
  → 信息位于拒绝记录

We introduce WikiSkill, a framework that co-evolves agent skills with a persistent knowledge base (wiki). At a high level, WikiSkill separates raw execution experience, accumulated knowledge, and executable skills, while continuously consolidating experience into the wiki, which subsequent skill updates can build on.

flowchart LR    A[原始执行轨迹] -->|持续沉淀整合| B[Wiki 知识库]    C[可执行的 Skill] -->|产生执行轨迹| A    B -->|为后续 Skill 升级提供基础| C    subgraph WikiSkill        A        B        C    end

We find that skill evolution complements model scaling: larger models generally benefit more from evolved skills, while smaller models with skills can outperform substantially larger models without them.

Skill 演化与模型 Scaling 之间具有互补关系，而非替代关系：更大的模型通常能从不断进化的 Skill 中获得更多收益。同时，具有优质 Skill 的小模型，也可能超过没有对应 Skill、参数规模更大的模型。对于 LLM + Skills 范畴下的 Agent，其能力提升可以表示为：

$$\text{Agent\_Capability} = \text{LLM\_Scaling} \times \text{Skills\_Evolution}$$

模型越大，越能释放 Skill 的能力。经验越丰富的工程师，越能理解条件、组合步骤并处理异常。因此，面对同样的操作手册时，他们更可能取得优秀的结果。

We also find that evolved skills transfer effectively across models and model families, and skills evolved by other models can outperform self-evolved skills.

Skill 不是模型内部参数的一部分，而是一种可以独立保存、共享和复用的外部程序性知识。因此，Skill 演化表现出较好的跨模型迁移能力。“跨模型迁移”意味着 Skill 学到的不只是某个模型的临时行为，而是模型无关、任务相关的程序性知识。

其他模型演化出的 Skill 可能更好，这意味着：对于大模型而言，“发现知识”和“执行知识”是两种不同的能力。最优秀的操作手册作者和最优秀的操作人员不一定是同一个人。

因此，在实际应用中，我们更应该将“Skill 演化”和“Skill 执行”区分开：用更适合知识发现的模型实现“Skill 演化”，用具备更强理解和执行能力的模型“执行 Skill”。

flowchart LR    A["模型 A
发现经验"] --> B["提炼 Skill"]    B --> C["模型 B
执行 Skill"]    C --> D["完成任务"]    E["不必是同一个模型"]    E -.-> B    E -.-> C    style B fill:#e8f3ff,stroke:#4285f4    style C fill:#e9f7ef,stroke:#34a853    style E fill:#f3e8fd,stroke:#9334e6

Finally, our ablation studies confirm that persistent knowledge accumulation in the wiki is critical for effective skill evolution.

Introduction

Developing effective skills, however, remains challenging. Most agent skills are manually authored, which requires anticipating the procedural knowledge and workflows that an agent will need. This challenge motivates recent work that iteratively develops agent skills by executing agents on training tasks, analyzing successful and failed trajectories, and refining skills based on the resulting experience.

从人工编写 Skill 转向基于训练任务自动生成 Skill。

A key design question is how to preserve and organize what an agent learns throughout skill evolution. However, these methods do not maintain what has been learned as a separate, evolving knowledge representation.

• EvoSkill
• Trace2Skill
• SkillOpt

Can agent experience be similarly compiled into persistent knowledge to support long-term skill evolution? We introduce WikiSkill, which adds a structured knowledge layer between raw experience and executable procedures. WikiSkill organizes the agent workspace into three layers: a Raw Layer that stores immutable execution traces, a Wiki Layer that maintains structured knowledge, and a Skill Layer that contains evolving procedural knowledge.

These results suggest that skill discovery and skill execution are distinct capabilities.

2026 年 5 月，北京大学与启元科技的研究团队发布了论文 Harness-Bench: Measuring Harness Effects across Models in Realistic Agent Workflows，用于研究并评测不同 Harness 对 Agent 实际执行能力的影响。在论文中，作者提出了 Harness-Bench——一个包含 106 个沙箱化离线任务、用于在统一任务环境下比较不同 Model–Harness 配置的评测基准。论文发现，Agent 表现不仅取决于 LLM，也取决于 Harness 的执行机制。

恰好最近在研究 Agent 评测，于是对这篇论文进行了精度，并做了如下的摘要。

术语

• oracle-checkability（预言机可检验性 / 自动真值可验证性）：计算机科学、软件测试以及当前 AI Agent 评测与强化学习（RL）领域中最核心的概念之一。一个任务或问题，是否存在一个确定的、自动化的程序（Oracle / 预言机），能够客观、无歧义、无需人工介入地判定 Agent 的输出究竟是对还是错。
• execution alignment（推理与执行对齐）：智能体的推理、实际观察到的环境状态、通过工具采取的行动，以及评估器最终检查的成功条件之间，是否始终保持一致。
• fixtures（测试固件 / 预置测试环境）：预先准备好的测试资源集合，包括初始化数据、配置文件、数据库快照、沙箱状态、依赖文件、环境上下文。作用是让每个测试任务都从完全一致的初始状态开始运行，保证评测可复现。
• agent-computer interface（ACI）：指的是专门为 AI 智能体设计的一组观察方式、操作方式和反馈格式，使智能体能够理解计算机当前状态，并对计算机采取行动。就像 GUI 帮助人类用户操作计算机一样，ACI 帮助 AI 完成与计算机的交互。$\text{ACI} = \text{智能体能看到什么} + \text{智能体能做什么} + \text{计算机如何反馈}$

Abstract

Each run records final artifacts, execution traces, usage statistics, and validator outputs, enabling analysis beyond final completion.

Our analysis further identifies recurring execution-alignment failures, where plausible reasoning becomes decoupled from tool feedback, workspace state, evidence, or verifiable output contracts.

Agent 的推理过程看起来合理、流畅，甚至“知道应该做什么”，但 Agent 随后执行的操作和最终的产物却没有持续忠实地反映：工具返回的信息、工作区的真实状态、证据、任务规定的验收条件。

在 Agent 执行任务时，“想明白”不等于“完成任务”。Agent 必须确保每一步推理都由当前环境状态和证据支撑，工具结果会改变后续行动，而且最终意图会落实为符合验收规则、能够被独立验证的产物。

1. 与工具反馈脱节：Agent 调用工具后，工具返回了错误或异常结果，但 Agent 没有根据异常信息调整执行计划，依旧沿着原来的推理继续执行。

   1 2 3

   Agent：接下来我会读取配置文件。 工具：文件不存在。 Agent：接下来我将修改这个配置文件。

2. 与工作区状态脱节：Agent 认为某个文件已经创建、修改或保存，但实际工作区中并没有发生对应变化，或者文件内容与 Agent 所说的不一致。

3. 与证据脱节：Agent 给出了一个结论，但没有获取实际的执行日志、实际的测试结果来支持这个结论，甚至忽略了与结论相矛盾的证据。

   1 2	Agent：测试已经通过，问题已解决。 实际测试执行：测试用例根本就没有执行。

4. 与可验证的输出契约脱节：用户规定了明确的输出格式、文件结构或验收条件，Agent 生成的结果虽然内容大致合理，但却依旧不满足这些要求。

   1 2	任务明确要求输出格式：{"answer": "...", "confidence": 0.9} Agent 输出：我的答案是……我对此比较有信心。

Introduction

In such executable workflows, practical performance depends not only on the underlying model, but also on the system layer that turns model capability into executable action. We refer to this layer as a harness: the mechanism that organizes context, tools, state, permissions, constraints, and recovery to mediate between model outputs and external actions.

模型层是推理能力；其他层是执行能力。目前测评测集涵盖了：模型的静态推理、Agent 在可执行环境下的最终表现、以及标准工作流下的表现。但是，对于其他层（Harness）层的单独覆盖目前依然是缺失的。

Harnesses are therefore central to agent system design: they shape how model capability is exposed, constrained, and realized, affecting completion, cost, safety, robustness, and auditability.

However, existing efforts typically evaluate a particular agent system, standardize evaluation infrastructure, or compare heterogeneous agent stacks, rather than systematically varying harness configurations across shared task environments and model backends.

Rather than forcing all systems into an identical internal implementation, Harness-Bench fixes the task environment, budget, timeout, and evaluator while preserving each harness’s native execution behavior.

The resulting measurements should therefore be interpreted as configuration-level diagnostics of model–harness pairings, not as causal decompositions of individual harness mechanisms. Each run records execution evidence, enabling analysis beyond final completion scores.

Harness-Bench 能告诉我们“哪一种 Model—Harness 组合整体表现更好”，但不能直接告诉我们“究竟是哪一个 Harness 机制导致了这种差异”。

因此，比较的实际上是类似：

$(\text{GPT-5.4},\text{NanoBot 配置}) \quad\text{vs.}\quad (\text{GPT-5.4},\text{Hermes 配置})$

• Harness-Bench 可以评估出：在这套任务和实验条件下，GPT-5.4 + NanoBot 的整体表现优于 GPT-5.4 + Hermes。
• 但不能进一步断言：NanoBot 更好，是因为它的状态管理机制贡献了 8 分，错误恢复机制贡献了 5 分。

Harness-Bench 是一台“整机检测仪”，能够比较不同“模型 + harness”整机配置的表现，并根据执行轨迹诊断其失败症状；但它不是一套“因果实验”，不能仅凭这些结果确定某个提示词、工具接口或状态管理机制单独造成了多少性能变化。

Harness-Bench 的整体框架如下所示：

Harness-Bench 的三大贡献：

flowchart LR    A["① Benchmark Asset
基准资源

106 个沙箱化离线任务
真实的端到端工作流
任务清单 · 测试材料
评估器 · 执行轨迹"]    B["② Evaluation Protocol
评估协议

固定外部任务条件
固定预算 · 超时 · 评估器
保留 Harness 原生执行行为
比较 Model–Harness 配置"]    C["③ Diagnostic Analysis
诊断分析

5,194 条执行轨迹
完成度 · 过程质量
执行效率 · 反复出现的失败症状"]    A -->|"提供统一测试基础"| B    B -->|"产生可比较的执行证据"| C    classDef asset fill:#E8F1FF,stroke:#3973C6,color:#14243A,stroke-width:2px;    classDef protocol fill:#E9F8F1,stroke:#2A9365,color:#142E24,stroke-width:2px;    classDef analysis fill:#FFF2E2,stroke:#D77B22,color:#382313,stroke-width:2px;    class A asset;    class B protocol;    class C analysis;

Related Work

LLM evaluation has progressed from static language and reasoning benchmarks to executable agent benchmarks

executable 不仅指 LLM 可以调用工具，更为重要的是：Agent 可以改变环境中的对象、改变环境的状态、并且结果具备可验证性。

LLM 评估已经从测试模型“能否用文本答对问题”，逐渐发展到测试 Agent “能否在真实或模拟环境中采取行动并完成任务”。

More recent workflow-agent benchmarks, including AgentBench, GAIA, and Claw-Eval, further emphasize multi-step execution, external state, traceability, safety, robustness, and cost-aware evaluation.

ClawMark pushes this direction to long-horizon, multimodal coworker settings, coupling multi-turn and multi-day tasks with persistent tool-backed services and drifting external state.

These benchmarks are essential for measuring model or end-to-end agent capability, but they do not directly evaluate the harness as the variable of interest: they either abstract away execution, evaluate a complete submitted agent stack, or hold the execution setup fixed to compare models.

目前的评测要么仅评测模型能力，要么仅评测 Agent 的端到端能力，并没有对 Agent 的 harness 层进行直接评测。

Harness-Bench is complementary: it controls external task conditions while varying harness configurations, enabling diagnostic comparison of completion, token cost, execution safety, robustness, and traceability.

Harness-Bench 的实验结构可以表示为：

$$\underbrace{\text{相同任务、环境、预算、评估器}}_{\text{受控的外部条件}} + \underbrace{\text{不同 Harness 配置、Model}}_{\text{实验中变化的部分}}$$

Work on agent-computer interfaces, tool-use protocols such as the Model Context Protocol, stateful and multi-agent frameworks, tracing, guardrails, memory, budget control, and recovery mechanisms reflects growing attention to the infrastructure that turns model outputs into external actions.

不同的 Agent 对 ACI 中的不同部分具有不同的实现策略。

The Harness-Bench Benchmark

Harness-Bench is a diagnostic benchmark for studying model–harness configurations in executable agent workflows. Each evaluation consists of a task, a model backend, a harness configuration, a sandboxed environment, and an evaluator. The benchmark fixes external task conditions while varying the harness surrounding the model, and records both final artifacts and execution traces.

We use harness to denote the system layer that conditions model calls and turns model outputs into actions in an external workspace. A harness may include prompt templates, action formats, context construction, tool invocation, workspace access, permissions, budget control, tracing, and recovery.

Harness-Level Evaluation Setting

For each task and model backend, Harness-Bench fixes the user-facing task, initial sandbox state, budget, timeout, and evaluator, while varying the harness configuration.

We do not force all systems into a common internal policy or runtime. Instead, each harness runs with its native execution behavior under the same task resources and evaluation protocol.

The resulting measurements should therefore be interpreted as configuration-level diagnostics of model–harness pairings, not as causal decompositions of individual harness mechanisms.

Harness-Bench 可以评测不同的“LLM + harness”配置的整体表现，并根据执行轨迹诊断其失败症状，但无法评测 Agent 整体表现的“实际归因”。Harness-Bench 无法给出究竟是 Agent 中的哪些部分导致了最终的结果。

Task Suite Design and Validation

Harness-Bench contains 106 local, sandboxed tasks designed to evaluate end-to-end agent workflows rather than isolated tool calls. Each task requires a deliverable and is paired with an oracle or rubric that checks completion from the final workspace state and, when needed, the execution trace.

评测样本的任务清单组织结构如下：

1
2
3
4
5
6
7
8
9
10
11
12

task_id: "006-access-bilibili"
title: "Access A Local Bilibili-Style Mock Page"
class: "Workspace, Tool Use & Multimodal Operations"
prompt_file: "prompt.txt"
fixtures_dir: "fixtures"
oracle_module: "oracle_grade.py"
hooks_module: "hooks.py"
timeout_sec: 900
tags:
  - "browser"
  - "local-http"
  - "web-extraction"

Harness-Bench 中覆盖的 8 个 Agent 场景：

Each candidate task is manually reviewed before inclusion. We retain tasks only when they satisfy four criteria:

Realism, reflecting a plausible user workflow;
Solvability, meaning the task can be completed using the provided sandbox resources;
Oracle-checkability, meaning success can be verified by deterministic checks or a specified rubric;
Integrity, meaning agents cannot obtain credit by reading hidden answers, modifying protected fixtures, or bypassing constraints.

每个任务都必须经过人工审核才能加入到评测集中，每个任务都必须满足 4 个条件：真实；可解决；可判别；正直诚实。

Run Protocol and Evidence Collection

Each run produces four sources of evidence: the final workspace state, execution trace, usage statistics, and validator outputs. These support completion scoring, process diagnostics, cost analysis, permission checks, and failure analysis.

每个任务的执行都会做如下的操作：

$$R = \mathrm{Run}(M, H, E, T), \quad \mathrm{TaskScore} = \mathrm{Eval}(R; J)$$

where $M$ is the model, $H$ is the harness configuration, $E$ is the sandboxed environment, $T$ is the task, $R$ is the final results, and $J$ is the evaluator.

Scoring and Metrics

For task $i$, the overall score is:

$$\begin{equation}\mathrm{TaskScore}_i = \mathrm{Security}_i \cdot \mathrm{Completion}_i \cdot \mathrm{Process}_i,\end{equation}$$

$$\begin{equation}\mathrm{Process}_i = \frac{\mathrm{Robustness}_i + \mathrm{ToolUse}_i + \mathrm{Consistency}_i}{3}\end{equation}$$

where $\mathrm{Security}_i \in \{0,1\}$ and all non‑binary scores are normalized to $[0,1]$.

Harness Dependence

We use harness dependence to describe how much a model backend’s performance varies across harness configurations under otherwise shared benchmark conditions.

This pattern suggests that stronger models may be more tolerant of differences in prompting, tool interfaces, state management, and recovery behavior.

更强大的模型，对于不同 Harness 之间的兼容性更好。

在 是时候了解一下 Git worktree 了 一文中，我们介绍了如何在 Codex、Claude Code 等 Coding Agent 中利用 Git worktree 实现并行开发。不过，那篇文章聚焦于单仓库场景。当我们尝试将 worktree 应用于采用多仓库架构的 LLM Arena 平台时，又遇到了一系列新问题。

本文记录我们如何为多仓库场景设计面向 Coding Agent 的 worktree 工作流，以及如何处理子模块初始化、需求编号冲突和多 Agent 编排等问题。

1. 多仓库架构

在 如何利用 Harness “一句话交付产品功能”？ 一文中，我们介绍过 LLM Arena 平台 的多仓库架构：使用 Git Submodule 管理多个代码仓库。

flowchart LR    subgraph ParentRepo["versus 父仓库"]        direction TB        Root["versus/"]        Config[".gitmodules"]        subgraph ServerPath["versus-server/"]            direction TB            ServerRepo["Gitlink：
记录子仓库 commit"]        end        subgraph FrontendPath["versus-fe/"]            direction TB            FrontendRepo["Gitlink：
记录子仓库 commit"]        end        Root -.->|"定义子模块路径和子仓库的 URL"| Config        Root --> ServerRepo        Config -.->|"path = versus-server
url = server repository"| ServerRepo        Config -.->|"path = versus-fe
url = frontend repository"| FrontendRepo        Root --> FrontendRepo    end    Server[versus-server
 独立 Git 仓库]    Frontend[versus-fe
独立 Git 仓库]    FrontendRepo --> Frontend    ServerRepo --> Server

在这种架构下，仅在 versus 父仓库中执行 git worktree add，并不能得到可直接开发的完整环境。父仓库的 worktree 只会创建 versus 的工作目录；其中的 Submodule 仍需单独初始化，并根据父仓库记录的 Gitlink 检出对应的子仓库 commit。

假设要同时开发两个需求：

• REQ-001
• REQ-002

并希望形成如下的目录结构：

1
2
3
4
5
6
7
8
9
10

.
├── versus/          # 主仓库
│     ├── versus-server/
│     └── versus-fe/
├── versus-REQ-001/  # REQ-001 的 worktree
│     ├── versus-server/
│     └── versus-fe/
└── versus-REQ-002/  # REQ-002 的 worktree
      ├── versus-server/
      └── versus-fe/

1.1 为父仓库创建 worktree

1
2
3
4
5
6
7
8
9
10
11

cd versus

git worktree add \
  -b req-001 \
  ../REQ-001 \
  origin/master

git worktree add \
  -b req-002 \
  ../REQ-002 \
  origin/master

此时，每个父仓库的 worktree：

• 有独立工作目录
• 有独立索引和当前分支
• 共享父仓库的 Git 对象库
• 可以由不同的 Coding Agent 并行操作
• 但此时子模块目录可能还是空的，或者尚未初始化

1.2 在 worktree 中初始化子模块

1
2
3
4

cd ../REQ-001

git submodule sync --recursive
git submodule update --init --recursive

上述命令可以完成子模块初始化，但每次手动执行都很烦琐。如果让 Coding Agent 临时推理并生成操作步骤，不仅会消耗额外的 token，还容易因上下文差异产生不稳定行为。因此，我们编写了 wt.sh，将 worktree 创建、子模块初始化、端口分配和环境配置固化为确定性流程。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# wt.sh - Versus 多需求并行开发 worktree 管理脚本
#
# 设计目标:
#   - 每个需求一个独立 Git worktree，代码任务真正并行、互不干扰
#   - 每个 worktree 分配独立端口（后端 9000+N / 前端 4000+N），接口测试可并行
#   - 数据库共享 dev，不隔离；E2E 手动 / 顺序执行
#   - 不改入库业务代码：端口与代理只在 worktree 内本地改 + assume-unchanged
#   - 代码提交复用 scripts/commit.sh（百度 iCode Gerrit 评审流程）
#
# 用法:
#   ./scripts/wt.sh new <id>                         # 创建 worktree（id 如 req-030 / REQ-030 / 030）
#   ./scripts/wt.sh list                             # 列出所有 worktree + 端口 + 状态
#   ./scripts/wt.sh go <id>                          # 切换到 worktree（需 shell-init 的 function）
#   ./scripts/wt.sh remove <id> [--keep-branch]      # 删除 worktree（默认连带本地分支）
#   ./scripts/wt.sh info <id>                        # 查看单个 worktree 详情
#   ./scripts/wt.sh current                          # 查看当前目录属于哪个 worktree

flowchart TD    WT["wt.sh
worktree 编排器"]    Pull["pull-all.sh
代码更新"]    Dev["dev.sh
固定端口启动服务"]    Status["status.sh
代码库状态"]    Commit["commit.sh
代码库提交"]    WT --> |实现 wt pull| Pull    WT --> |实现 wt start/stop| Dev    WT --> |实现 wt status| Status    WT --> |实现 wt submit| Commit

2. 构建 worktree-manager Agent

在 如何利用 Harness “一句话交付产品功能”？ 的“4.2 Harness 闭环设计”一节中，我们使用 6 个 Sub-Agent 实现需求开发闭环。

现在，我们还需要把 worktree 管理能力加入整个 Harness 闭环。为此，我们新增了 worktree-manager Agent。

每个需求都有一个贯穿开发流程的唯一 REQ-ID。引入 worktree-manager 后，REQ-ID 的生成也需要从需求设计阶段前移到 worktree 创建阶段。

2.1 定义 worktree-manager

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

---
name: "worktree-manager"
description: "Use this agent when a new requirement or modification task needs to be started and a dedicated worktree should be created for isolated development. This agent should be triggered BEFORE the requirement-designer agent in the collaboration pipeline, ensuring that each requirement gets its own isolated Git Worktree with independent ports and runtime environment. This is essential for parallel development of multiple requirements without code or port conflicts."
---

## Operational Procedures
### Step 1: Check Existing Worktrees
Before creating anything, check if a worktree already exists for the given requirement:

```bash
# Check current worktree status（在项目根目录执行）
bash scripts/wt.sh list
```

Also verify with git:
```bash
git worktree list
```
......

如上所示，worktree-manager 本质上是对 wt.sh 的 Agent 化封装：Agent 负责理解意图和编排步骤，脚本负责执行确定性的底层操作。

2.2 调整 Sub-Agent 编排流程

在原有流程前增加 worktree-manager，具体编排如下：

flowchart LR    A0["0. worktree-manager
创建隔离 worktree"]    A1["1. requirement-designer
生成 PRD"]    A2["2. go-api-implementer
实现后端 API"]    A3["3. frontend-engineer
实现前端功能"]    A4["4. test-case-designer
设计测试用例"]    A5["5. integration-test-runner
执行 API 测试"]    A6["6. e2e-test-executor
执行 E2E 测试"]    A0 --> A1    A1 --> A2    A2 --> A3    A3 --> A4    A4 --> A5    A5 --> A6

接下来，我们开启两个 Session，通过不同的 worktree 并行开发两个需求。

3. REQ-ID 冲突

当我们真正利用 worktree 并行开发多个需求时，新问题出现了：两个 Session 分别进入不同的 worktree，却生成了相同的 REQ-ID。

当 docs/requirements/ 中最新的需求目录为 REQ-30 时，两个 Coding Agent 都读取到相同状态，并将下一个编号计算为 REQ-31。

单独看每个需求，两者都能继续开发；但当代码合并回 versus 父仓库时，相同的需求目录和文件路径必然产生冲突。

很多实践看起来简单，真正落地时却会暴露一连串问题，而解决这些问题正是创新的一部分。

这是一个典型的并发竞争：多个进程读取相同状态，各自计算出相同的下一个编号，然后尝试写入结果。它与数据库中的“丢失更新”问题具有相似结构。

我们的解决思路是复用 Git 已有的互斥保护，而不是另外实现一套锁：

• 所有 worktree 共享同一个 Git 引用空间。
• git worktree add -b <branch> 会创建新分支；如果该分支已经存在，命令默认失败。
• Git 也默认禁止同一个本地分支同时被多个 worktree 检出。

因此，我们让 REQ-ID 同时参与分支命名，把创建 feat/<REQ-ID> 分支作为编号预占操作。即使两个进程计算出相同的 REQ-ID，也只有一个能成功创建对应分支；失败的一方重新扫描并分配新编号。

同时，wt.sh 会在主仓库的 .wt 目录中记录已分配的 REQ-ID。后续分配先扫描这些元数据，再尝试通过 Git 创建分支完成最终确认。

1
2
3
4
5
6
7
8

ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
WT_ROOT="${WT_ROOT:-$ROOT_DIR/..}"  # worktree 存放根目录，默认为主仓库父目录
WT_META_DIR="$ROOT_DIR/.wt"         # 注册表目录（.gitignore 已忽略）

write_meta() {
    local id=$1 path=$2 branch=$3 be=$4 fe=$5 req_id=${6:-}
    echo "WT_REQ_ID=$req_id" > "$WT_META_DIR/$id.meta"
}

创建 worktree 时，脚本使用 feat/$id 作为分支名。若同名分支已经存在，-b 会拒绝覆盖，脚本便终止本次创建。上层 Agent 识别出同名分支冲突后，再重新分配编号并重试；其他错误则直接上报，避免无意义重试。

1
2
3
4
5
6
7

id=$(allocate_req_id)

info "[1/6] 创建 Git Worktree（基于 master）..."
if ! git -C "$ROOT_DIR" worktree add -b "feat/$id" "$wt_path" master 2>&1; then
    error "创建 worktree 失败"
    exit 1
fi

整体流程如下所示：

flowchart LR    START["Coding Agent 创建 worktree"] --> SCAN["扫描主仓库 .wt/*.meta
读取 WT_REQ_ID"]    SCAN --> ALLOC["计算候选 REQ-ID"]    ALLOC --> BRANCH["生成 feat/REQ-ID 分支名"]    BRANCH --> CREATE{"git worktree add -b"}    CREATE -- "成功" --> META["写入 .wt/<worktree>.meta
记录 REQ-ID 和 worktree 信息"]    META --> DONE["新 worktree"]    CREATE -- "分支已存在" --> RETRY["重新分配编号"]    RETRY --> SCAN

下面，我们启动两个 Coding Agent 会话，并行执行两个需求。从实际结果看，两个 Agent 分别获得 REQ-42 和 REQ-43，并成功创建了对应的 worktree 与需求分支。

4. 多 worktree 并行开发

LLM Arena 平台已经能够满足基本评测需求，但仍有一些交互体验问题需要优化，例如：

• 分类管理页面缺少分页；创建分类时，父分类 ID 仍需手动填写，操作不够友好。
• 模型效果页面滑动到底部后，媒体资源卡片可能无法对齐，页面会出现大块空白。

过去，我们使用 Harness Engineering 串行处理这些需求。将其升级为 worktree 模式后，不同需求可以在相互隔离的环境中并行推进。

当 Coding Agent 能够在不同且相互隔离的 worktree 中并行开发时，多个独立需求不必再排队等待，整体开发吞吐量得到显著提升。

5. /teamwork-preview 编排

最初，7 个 Sub-Agent 的编排规则都定义在 versus/CLAUDE.md 中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

## 自动化工作流

### 流水线概览

```
用户: "开启 7 个 Agent 协作实现 XXX 需求"
│
▼
[0] worktree-manager       →  创建隔离 worktree + 分配端口
│
▼ status=completed（主会话 EnterWorktree(path=...) 切换）
[1] requirement-designer   →  产出 PRD.md + 分配需求 ID
│
▼ status=awaiting_review
⏸ 人工审核 PRD（用户确认后继续）
│
▼ 用户确认 → status=completed
[2] go-api-implementer     →  产出 Go 代码 + api-summary.md
│
▼ status=completed（自动流转）
[3] frontend-engineer      →  产出 React 代码
│
▼ status=completed（自动流转）
[4] test-case-designer     →  产出 api-test-cases.json + e2e-test-cases.json
│
▼ status=completed（自动流转，串行启动）
[5] integration-test-runner (worktree端口)  →  [6] e2e-test-executor (worktree端口+1)
│                                           │
▼                                           ▼
status=has_bugs → Bug修复循环               status=all_passed → 流水线完成
```

每次启动流程时，我们都要重复输入相同的指令：

开启 7 个 Agent 协作，实现：……

这条指令虽然不长，但仍暴露出一个问题：工作流依赖用户记住并重复输入约定，而不是由系统提供稳定入口。恰好，7 月 14 日，Google Antigravity 发布了 Agent Teams 的演示：运行 /teamwork-preview，即可启动一个由专业 Sub-Agent 组成的动态团队，在后台协调、规划、构建并验证复杂任务。

受此启发，我们也实现了 /teamwork-preview，用一条稳定指令启动完整协作流程：

/teamwork-preview ……

在 Claude Code 中，可以通过 Skill 封装这类工作流。于是，我们把 CLAUDE.md 中的 Sub-Agent 编排规则迁移到 teamwork-preview Skill，将触发方式、执行顺序、状态流转和异常恢复集中管理。

因此，/teamwork-preview 本质上是一个基于 Skill 编排 Sub-Agent 的工作流：

• 使用 Skill 组织领域知识和操作流程，降低重复上下文的成本。
• 使用外部状态文件记录执行进度，增强主 Agent 的任务恢复能力。
• 使用管理类 Skill 编排工作流，使用能力类 Skill 增强各个 Sub-Agent。

6. 总结

Coding Agent 提升了代码生成和任务执行的速度，却不会让并发竞争、状态一致性和资源隔离等经典工程问题自动消失。Agent 越多、并行度越高，这些问题反而越容易暴露。

这次实践最终沉淀出三个原则：

• 将推理与执行分离。 Agent 负责理解需求和编排流程，脚本负责执行可重复、可验证的底层操作。
• 优先复用已有约束。 使用 Git 分支创建的失败保护完成本地互斥，比另行维护一套脆弱的锁机制更简单。
• 明确方案边界。 本地 Git 引用只能协调单机并发；跨机器场景需要真正的全局协调机制。

AI 可以替我们完成更多操作，但不能替我们理解系统。恰恰因为开发速度更快、并行规模更大，我们更需要掌握底层原理，并用清晰的架构约束 Agent 的行为。

在 如何利用 Harness “一句话交付产品功能”？ 一文中，我们已经讨论过如何在单个 clone 仓库里借助 Harness Engineering 自动完成需求开发。但问题也随之出现：当这个目录正在被 Coding Agent 执行任务、修改代码、运行测试时，我们能做的往往只剩下等待。

如果还想并行开发另一个功能，最直观的办法是重新 clone 一份仓库到新目录。这个方案能用，但并不优雅：重复下载、重复安装依赖、重复同步分支，最后还要在多个副本之间来回合并。我们需要一种更轻、更原生、更适合并行开发的方案。于是，git worktree 重新进入了视野。

git worktree 是 Git 中一个长期被低估的能力。它随 Git 2.5 在 2015 年发布，至今已经存在十多年^[1]，但依旧鲜为人知。如果不是 AI Coding Agent 的告诉发展，git worktree 很可能仍然仅仅停留在更新日志中。

Git Worktree 简介

根据 Git 官方文档^[2]，git worktree 用于在同一个仓库之上管理多个工作目录。

在传统 Git 工作流中，我们通常有两种并行方式：在同一个目录里不断切换分支，或者为同一个仓库创建多个 clone。前者会频繁打断当前上下文，尤其是在工作区还存在未提交修改时；后者虽然隔离性更好，但每个克隆都拥有独立的 Git 数据，需要额外同步远端、分支和提交。

git worktree 提供了第三种选择：为现有仓库创建一个新的工作目录。这个目录看起来像一个独立仓库，有自己的文件树和当前分支；但它并不是一份完整克隆，而是复用主仓库背后的 Git 对象、引用和历史记录。在 linked working tree 中，.git 通常不是目录，而是一个指向主仓库 Git 元数据的普通文件。

Linked Working Tree

理解 git worktree，需要先区分两个概念：

• 主工作目录（Main Working Tree）：通过 git clone 或 git init 创建的原始仓库目录。它包含完整的 .git 目录，是其他链接工作目录共享 Git 数据的基础。
• 链接工作目录（Linked Working Tree）：通过 git worktree add 创建的额外工作目录。它拥有独立的代码文件和工作区状态，但通过 .git 文件关联到主仓库的 Git 元数据。

换句话说，worktree 不是“再克隆一份仓库”，而是在同一个仓库历史之上打开多个互相隔离的工作现场。

创建 Worktree

假设我们正在 feature 分支上开发一个功能，这时线上突然出现一个需要基于 main 紧急修复的 Bug。如果不使用 worktree，通常需要这样操作：

1. 暂存 feature 分支上的所有改动，并让工作区恢复干净状态
2. 切换到 main 分支，再创建新的 hotfix 分支
3. 在 hotfix 分支上修复 Bug 并提交
4. 切回 feature 分支，并恢复之前暂存的改动

1
2
3
4
5
6

git stash
git checkout main
git checkout -b hotfix
# 修复 Bug，提交修复
git checkout feature
git stash pop

这个流程并不复杂，但很容易打断思路。如果 stash pop 发生冲突，原本只想修一个小 Bug，最后可能变成上下文切换和冲突处理。

使用 worktree 可以把这个过程变成一次目录创建：

1

git worktree add ../project-hotfix -b hotfix main

执行后，我们会得到两个工作目录：

1
2

project/            # 继续开发 feature
project-hotfix/     # 专门处理 hotfix

两个目录共享同一份 Git 历史，但工作区彼此独立。我们可以在 project 中继续开发功能，在 project-hotfix 中修复线上问题，不需要来回 checkout，也不需要临时清空当前工作现场。

查看 Worktree

若要查看当前仓库关联的所有 worktree，可以使用 git worktree list：

1

git worktree list

这个命令会列出每个工作目录的本地路径、当前提交哈希，以及该目录正在检出的分支或 HEAD 状态。对于同时处理多个任务的项目来说，它相当于一张本地并行工作区清单。

删除 Worktree

为了保持本地目录整洁，完成任务后应及时删除不再需要的 worktree。例如，当 hotfix 修复完成并提交后，可以执行：

1

git worktree remove ../project-hotfix

这条命令会完成两件事：

1. 删除该 worktree 目录下的代码文件
2. 从仓库的 worktree 注册表中清除对应记录

如果目标工作目录中仍有未提交修改，Git 默认会拒绝删除，以避免误删本地工作。确实需要删除时，可以追加 --force：

1

git worktree remove --force ../project-hotfix

和所有 -f / --force 参数一样，执行前务必确认里面没有需要保留的修改、未跟踪文件或本地提交。

Worktree 与 Branch

git branch 和 git worktree 不是同一层面的概念^[3]。

• branch 是一条版本线，本质上是指向某个提交的引用。它解决的是“基于哪个版本继续演进”的问题。
• worktree 是一个工作目录，它把某条版本线检出到独立目录中。它解决的是“如何同时打开多个工作现场”的问题。

1
2
3
4
5
6
7
8

Git 仓库
├── branch: main
├── branch: feature/1
├── branch: fix/bug-123
└── worktree:
    ├── 当前目录        -> main
    ├── ../f1-dev      -> feature/1
    └── ../bugfix      -> fix/bug-123

何时使用 Worktree

在 AI Coding Agent 普及之前，工程师通常只会并行推进一个或少数几个任务，branch 已经足够。但当我们需要同时处理多个任务，尤其是三个以上彼此独立的任务时，worktree 的优势会非常明显：

• 一个目录继续主需求开发
• 一个目录修复线上 Bug
• 一个目录验证依赖升级
• 一个目录复现或审查 Pull Request
• 一个目录交给 Coding Agent 跑长期任务

worktree 的关键价值不是“多一个 Git 命令”，而是把研发现场从单线程切换升级成多工作区并行。

Coding Agent 中的 Worktree

在 Coding Agent 场景下，worktree 的价值会进一步放大。Agent 不只是帮我们写几行代码，它往往会执行一个完整任务链：阅读代码、修改文件、安装依赖、运行测试、分析失败、继续修复。如果多个 Agent 或多个任务挤在同一个工作目录里，文件修改、未提交变更、依赖状态和本地服务都很容易互相干扰。

因此，Codex 和 Claude Code 都把 worktree 作为并行编码的重要基础设施。简单来说：

• 对人来说，worktree 是多个独立的工作现场。
• 对 Coding Agent 来说，worktree 是多个互不干扰的任务沙箱。

Codex 中的 Worktree

Codex 中的 worktree 主要用于让 Codex 在同一个项目里并行执行多个独立任务，同时不影响我们正在使用的本地工作目录。Codex 文档把这个本地目录称为 Local checkout，也就是我们自己创建并日常使用的仓库；Codex 从它创建出来的后台工作目录则称为 Worktree^[4]。

可以把这个模型理解为：

1
2
3
4

Local checkout   # 前台工作区：我们正在 IDE、终端、开发服务器中使用
Worktree A       # 后台任务：Codex 实现 feature-a
Worktree B       # 后台任务：Codex 修复 bug-b
Worktree C       # 后台任务：Codex 处理代码评审反馈

在 Codex 中创建新线程时，可以选择让线程运行在 Worktree 中。Codex 会基于我们选择的起始分支创建一个 Git worktree。这个起始分支可以是 main / master，也可以是某个功能分支，甚至可以是当前带有未暂存改动的分支。默认情况下，Codex 会在 detached HEAD 状态下工作；当我们确认这条任务值得保留时，再在该 worktree 上创建分支、提交代码、推送远端并创建 Pull Request。

Codex 还有一个关键概念：Handoff。Handoff 用于在线程的 Local 和 Worktree 之间移动任务。也就是说，当 Codex 在后台 worktree 中完成一批修改后，如果我们想用熟悉的 IDE 和本地开发服务器继续检查，可以把这个线程 handoff 到 Local；反过来，如果一个任务最初在 Local 中启动，但希望放到后台继续执行，也可以 handoff 到 Worktree。

这个机制解决的是 Git 的一个天然限制：同一个分支不能同时被 checkout 到多个 worktree 中。Codex 的 Handoff 会处理必要的 Git 操作，避免我们手动搬运修改、切换分支和处理由此引入的冲突。对于使用者来说，真正需要决定的是：这个任务现在应该留在前台，还是交给后台环境继续推进。

Codex 的 worktree 特别适合这些场景：

• 让 Codex 在后台实现一个功能，同时我们继续在 Local 中开发另一个功能。
• 把自动化任务运行在独立 worktree 中，避免影响当前工作目录。
• 在 worktree 中完成修改后，创建分支并提交 PR。
• 将 worktree 中的任务 handoff 到 Local，用日常 IDE 和开发服务器做最终检查。

需要注意的是：worktree 是一个新的 checkout，所以 .gitignore 中忽略的文件默认不会自动出现在 worktree 中，例如 .env、.env.local、本地密钥配置等。如果 Agent 任务依赖这些文件，就需要额外处理。Codex 支持通过 .worktreeinclude 把指定的已忽略文件复制到本地托管的 worktree 中。

Claude Code 中的 Worktree

Claude Code 对 worktree 的支持更偏 CLI 工作流。它提供 --worktree / -w 参数，用于在独立 worktree 中启动一个 Claude Code 会话^[5]：

1
2

claude --worktree feature-auth
claude --worktree bugfix-123

默认情况下，Claude Code 会在仓库根目录下的 .claude/worktrees/<name>/ 创建 worktree，并创建名为 worktree-<name> 的分支。例如：

1
2
3
4

.claude/
└── worktrees/
    ├── feature-auth/   # branch: worktree-feature-auth
    └── bugfix-123/     # branch: worktree-bugfix-123

这样，我们可以在多个终端中同时启动多个 Claude Code 会话。一个会话实现认证功能，另一个会话修复线上 Bug；它们分别修改不同目录中的文件，因此不会互相覆盖。

Claude Code 默认从仓库的默认远端分支 origin/HEAD 创建新的 worktree，这意味着每个任务通常会从一个干净的远端状态开始。如果希望新的 worktree 基于当前本地 HEAD 创建，可以在设置中配置 worktree.baseRef 为 "head"：

1
2
3
4
5

{
  "worktree": {
    "baseRef": "head"
  }
}

这个设置适合一种常见场景：我们已经在本地完成了一部分改动或提交，希望 Claude 的子任务基于当前进度继续拆分，而不是从远端默认分支重新开始。

Claude Code 还支持将子代理（subagent）隔离到 worktree 中。我们可以要求 Claude “use worktrees for your agents”，也可以在自定义 subagent 的 Front Matter 中配置 isolation: worktree。这样，每个子代理都会获得自己的临时 worktree，适合并行探索多个方案、拆分多个模块，或者让不同代理分别修复不同测试失败。

同样需要注意 .gitignore 文件。Claude Code 支持在仓库根目录创建 .worktreeinclude 文件，用 .gitignore 语法声明哪些已被 Git 忽略的本地文件需要复制进新 worktree。例如：

1
2
3

.env
.env.local
config/secrets.json

这对前端项目、后端服务，以及依赖本地密钥的测试环境尤其重要。否则 Agent 在 worktree 中运行测试或启动服务时，可能会因为缺少环境变量而失败。

在清理策略上，Claude Code 会根据 worktree 中是否存在未提交修改、未跟踪文件或新提交来决定是否自动清理。没有变更的临时 worktree 可以被自动删除；有变更的 worktree 会提示保留或删除；非交互式 claude -p --worktree 创建的 worktree 不会自动清理，需要使用 git worktree remove 手动删除。

二者的共同点与差异

Codex 和 Claude Code 使用 worktree 的目标是一致的：让多个 Agent 任务在同一个仓库中并行运行，并隔离文件修改。二者的差异更多体现在产品形态上：

这也解释了为什么 AI Coding Agent 让 git worktree 重新变得重要：过去使用 worktree，主要是为了让人类工程师并行开发；现在使用 worktree，是为了让人和多个 Agent 能够同时在同一个仓库里协作，而不互相污染工作现场。

参考文献

对 Agent Skills 的认知与思考 这篇文章对 Agent Skills 做了详细介绍。自 Anthropic 发布 Agent Skills 以来，Skills 已经逐渐成为 Agentic 系统构建中的一种共识范式。无论是公开的 Skills Marketplace、OpenClaw 的 ClawHub，还是团队内部沉淀的专用能力库，Skills 的数量都在快速增长。

Skills Marketplace 平台已经托管了 172W+ 的 Agent Skills；而在年初红极一时的 OpenClaw 的 ClawHub 平台也已经托管了 7W+ 的 Agent Skills；在我们内部，也已经积累了成千上百的 Skills。

随着 Agent 加载的 Skills 越来越多，我们也开始观察到一个新问题：不同 Skills 之间会发生冲突、覆盖和干扰，导致 Agent 的行为更难预测，调试成本也随之上升。

同时，当我们更新某个 Skill 之后，往往很难判断这次修改是否破坏了原有能力，也很难证明它真的带来了优化。

问题不再是“能不能写一个 Skill”，而是“能不能知道这个 Skill 什么时候有效、什么时候失效、什么时候应该回滚”。

于是，我们认为，Skill 的快速评估与测试是保障 Agent 系统可控的必要手段。

重新认识 Skill

Anthropic 的官方文档 Extend Claude Code^[1] 对相关概念之间的区别进行了如下阐述：

在上面的描述中，Skills 就是：

• 可复用的知识
• 可调用的工作流

“invocable workflows” 是一个很容易被误读的描述：它可能让人误以为 Skills 是可以独立运行的操作单元。

但更准确地说，“invocable workflows” 是一套可被按需调用的结构化操作步骤，是被封装好的行动方案。它赋予 Agent “怎么做”的能力，而具体执行仍然由 Agent 按照工作流中描述的路线与外部世界交互完成。

此处的 “invocable” 更合理的理解是“可以被 Agent 调用”，而不是“可以独立运行”。即便某个 Skill 包含可执行的 scripts 脚本，真正的运行顺序也是：Agent 读取 Skill 中的说明，再按需调用指定脚本。Skill 本身不能自主执行，必须由 Agent 在真实环境中按照其定义的流程完成任务。

1
2
3
4
5
6

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

如果从这个角度理解 “invocable workflows”，它本质上就是一种特殊形式的知识。

Agent VS. Skills

因此，我们不但需要重新认识 Skills，也需要重新认识 Agent 与 Skills 之间的关系。

正如 Extend Claude Code^[1:1] 中所述：

重新认识知识

谷歌发布的 Context Engineering: Sessions & Memory^[2] 白皮书中的 Types of information 这一节，对知识进行了分类：

从这个层面来看，“invocable workflows” 其实就是 Procedural Knowledge，即一种用于存储操作步骤、执行流程和动作技能的程序性知识。

一个 API 文档会以普通知识的形式告诉模型接口相关信息：

1
2
3

登录接口是 POST /api/login
请求字段包含 username、password
返回字段包含 token、expireTime

而一个 API 测试 Skill 则会告诉模型：

1
2
3
4
5
6
7
8

当用户要求验证 API 是否符合 PRD 时，必须按照以下流程执行：
1. 读取 PRD；
2. 读取 API 文档；
3. 生成主路径、异常路径、边界路径测试用例；
4. 执行或规划 API 测试；
5. 解析测试结果；
6. 输出 api_test_report.json；
7. 失败时标记 suspected_owner，并给出 next_action。

Skill 本身虽然不会自主执行，但作为 Procedural Knowledge，它会直接影响 AI 的执行路径和输出质量。

• 如果 Skill 写得不清楚，后续 Agent 执行就会不稳定；
• 如果 Skill 的产物契约不明确，Hook 和 Workflow 就无法做自动判断；
• 如果 Skill 缺少失败处理策略，多 Agent 闭环就会在失败处停住。

Agent VS. Skills VS. Knowledge

Agent、Skills、Knowledge 三者之间的关系如下所示：

Skill 究竟要测什么？

既然 Skills 在本质上是一种特殊的知识，那么 Skill 测试的目的就不是验证“模型知道了什么”，而是验证：Skills 提供的程序性知识能不能稳定指导模型完成一类任务。

更进一步，Skill 测试不是“跑业务功能”，而是“测试方法是否可靠”。它的目的不是验证真实业务最终是否成功，而是验证：

• Skill 是否在正确场景下被触发；
• 模型是否理解 Skill 的执行流程；
• 输出产物是否符合约定；
• 信息缺失、失败、边界场景下是否处理合理；
• Skill 输出是否能被 Agent、Hook 或 Workflow 后续消费；
• ……

根据上面的描述，我们可以得到 Skills 测试的边界：

1
2
3
4
5
6
7

1. 触发是否准确；
2. 流程是否完整；
3. 输出契约是否稳定；
4. 边界处理是否合理；
5. 失败信息是否可回流；
6. 是否避免幻觉和越权行为；
7. ……

例如，测试 api-test-flow Skill，不是要真的启动服务跑接口测试，而是验证模型：

1
2
3
4
5
6
7
8
9

1. 是否会在相关 Query 下加载该 Skill
2. 是否会按照该 Skill 的要求：
    1. 读取 PRD；
    2. 读取 API 文档；
    3. 生成 API 测试用例；
    4. 规划或执行 API 测试；
    5. 解析测试结果；
    6. 输出 api_test_report.json；
    7. 失败时给出 suspected_owner 和 next_action；

Skills 测试更像单元测试：它可以不依赖真实业务环境，而是验证 Skill 是否能稳定提供正确的方法、步骤和约束。这与 Agent 测试不同。Agent 测试的目标是验证 Agent 是否能在真实环境中正确完成任务。

例如，测试 coding-agent 时，就必须准备一个代码仓库，让 coding-agent 修复一个明确的编译错误，并期望结果是：

1
2
3
4
5

正确修改错误代码；
编译通过；
测试用例通过；
没有修改无关文件；
……

Skills 测试规范

根据上面的描述，在 Skills 测试中，一般需要覆盖如下场景^[3]：

我们可以用 YAML 文件组织一个 Skill 的测试用例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

version: "1.0"

skill:
  name: "api-test-flow"
  description: "验证 API 测试类 Skill 的触发、计划和输出契约"

cases:
  - id: "plan_001"
    type: "plan"
    title: "API 测试 Skill 应给出正确执行计划"
    query: >
      请根据 PRD 验证登录接口是否符合预期。
    inputs:
      files:
        - "examples/login_prd.md"
        - "examples/login_api_doc.md"
    expected:
      skill:
        should_use: "api-test-flow"
        should_not_use: []
      must_include:
        - "读取 PRD"
        - "读取 API 文档"
        - "生成 API 测试用例"
        - "执行或规划 API 测试"
        - "解析测试结果"
        - "输出 api_test_report"
      must_not_include:
        - "直接修改业务代码"
        - "调用 UI 验收流程"
    assertions:
      - "selected_skill == 'api-test-flow'"

更详细的 Skills 测试规范可以参考 Skill Test Case Specific。

Skill 测试实践

我们把上面描述的 Skill 测试规范封装到了 skill-testing Skill 中。你可以直接将 skill-testing 安装到 Codex 或 Claude Code 中，用它来测试其他 Skills。

下面继续以 对 Agent Skills 的认知与思考^[4] 这篇文章中的 pdf-case-converter 为例，展示如何使用 skill-testing 测试 pdf-case-converter。

pdf-case-converter/tests/skill_cases.yaml 的内容如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

version: "1.0"

skill:
  name: "pdf-case-converter"
  description: "pdf-case-converter 的测试用例"

defaults:
  mode: "dry-run"
  execution: "no_tool_call"
  output_format: "markdown"

cases:
  - id: "trigger_001"
    type: "trigger"
    title: "PDF 大小写转换场景应触发 Skill"
    query: "请把 example/test.pdf 文档中的大写英文字母转换成小写"
    inputs:
      files: []
      context: {}
    expected:
      skill:
        should_use: "pdf-case-converter"
        should_not_use: []
      must_include: []
      must_not_include: []
      artifacts: []
      routing: {}
    assertions:
      - "selected_skill == 'pdf-case-converter'"
    tags:
      - "trigger"
      - "positive"

  - id: "trigger_002"
    type: "trigger"
    title: "图片生成场景不应触发 Skill"
    query: "请生成一张夏季的海边风景的图片，并转换为 pdf 格式"
    inputs:
      files: []
      context: {}
    expected:
      skill:
        should_use: ""
        should_not_use:
          - "pdf-case-converter"
      must_include: []
      must_not_include: []
      artifacts: []
      routing: {}
    assertions:
      - "selected_skill != 'pdf-case-converter'"
    tags:
      - "trigger"
      - "negative"

1. 在当前 Codex 中安装 skill-testing 和 pdf-case-converter 两个 Skill。
2. 在 Codex 中输入测试提示词：请测试 skill: pdf-case-converter。
   
3. Codex 会根据 skill-testing 中的说明，加载 pdf-case-converter/tests/skill_cases.yaml 中的测试用例，生成 dry-run 测试响应，并对响应进行评分。
   
4. 最后生成测试报告。
   

总结

Skill 是一种 Procedural Knowledge。它不是普通文档知识，也不是可独立执行的 Agent，而是模型完成某类任务时需要遵循的方法、流程和契约。只有明确 Skills 与 Agents 之间的区别，认识到 Skills 的本质，才能将 Skills 从一份提示词文档升级为可测试、可维护、可复用的 AI 工程资产。

当然，我们的实践还刚刚开始。当 Skills 变成 Agent 系统的基础设施，评估能力就不再是可选项，而是让 Agent 工程可维护、可回归、可扩展的前提。

参考文献

为了更快的发布 大模型评测平台，我们借鉴 OpenAI 的思路搭建了一套 Harness 模式，之前需要 1 天开发完的功能，现在基本上 2 个小时左右就可以完成。

1. 背景

在 我让 OpenClaw 🦞 管理大模型评测任务 中提到，我们通过自建的 Side-by-Side 平台来实现多模态大模型的偏好打分以及对抗榜单结果。在 2026 年 2 月平台刚上线的时候，还只支持最基本的 Side-by-Side 的功能，比如只支持生图大模型的评测，并且对于图生图大模型而言，仅支持参考图片为单图的评估场景……因此，我们的评测平台属于是一个功能不断丰富、扩展的状态。平台功能的升级一方面来自参与到实际评估中的用户的真实反馈，另一方面来自我们对平台功能点的规划。

在实现上，平台由 React 的前端服务 versus-fe 和 Go 的后端服务 versus-server 构成，并且对于前后端的这 2 个服务，我们分别安排了一个同学来负责。整体看，这个系统也属于：麻雀虽小、五脏俱全。

2. Vibe Coding

最开始的时候，我们的前后端开发人员各自使用 DUCC 通过 Vibe Coding 的方式来编码前后端服务，然后再进行联调测试，最后再利用我们内部的上线平台发布新功能。

flowchart LR  A[新功能] --> B[FE 模块]  A --> C[Server 模块]  B --> D[Vibe Coding]  C --> E[Vibe Coding]  D --> F[联调]  E --> F  F --> G[功能发布]

可以看到，Vibe Coding 模式下，开发过程中的唯一的变化就是代码的实现由人变成了 AI。而新功能的拆解，模块之间的联调，代码的迭代调整还都是人来驱动的，不同的是，人的产物不再是代码，而是自然语言。我们最开始并不太懂 React，但是整个平台在 AI 的帮助下，也就这么构建起来了。无疑，Vibe Coding 极大地降低了产品开发的门槛。

graph    %% 新模式 下半区    subgraph 新AI开发模式        N1[人] --自然语言--> N2[DUCC]        N2 -- 代码 --> N3[产品]    end            %% 旧模式 上半区    subgraph 旧开发模式        A[人] -- 代码 --> B[产品]    end

慢慢地，我们发现，虽然我们在 CLAUDE.md 中补充了很多的知识，虽然 Vibe Coding 确实提升了我们的开发效率，但是有时候我们总是会为了调整页面的某个元素而浪费几十分钟的时间，而人去改动这些代码可能只需要几分钟。更让人接受不了的是，整个的改动过程会出现越改越糟的问题，这实在是令人抓狂。

当提示词比较长的时候，我们希望增加一个展开全部的功能，避免过长的提示词占据屏幕的整个区域，从而提升打分过程的交互体验。就是这么一个小小的改动，我们来来回回和 DUCC 沟通了 2 个多小时，中途多少次我都萌生了亲自去写这块代码的冲动……后来，/clear 了上下文，还原了所有的代码改动，重新给新的提示词，才完成了最后的效果。

麻了，我再也不想和 AI 废话了，我不想写代码，同时我也不想和 AI 来来回回的聊天了。在我用 Harness Engineering 来进行书籍翻译工作之后，我想，是时候让 Harness 发挥更大的价值了。

3. 对 Harness 的思考

最开始有这个想法的时候，我的心里也犯嘀咕：

• 项目架构并不复杂，有必要搞 Harness 吗？

• Harness 还并没有跑出一套可复制的成功路线，有必要探索吗？

• Harness 真的靠谱吗？

• ……

但是，在再次精读了 OpenAI 的 Harness engineering: leveraging Codex in an agent-first world 与 Anthropic 的 Harness design for long-running application development 后，我认为这个事情有搞头。

• 在 OpenAI 的 Case 中，他们也是基于内部的一个工具来实验的，这个和我们的平台的发展阶段类似。

• 从 UI 交互复杂性而言，我们的平台不涉及特别复杂的交互，因此在 Harness 的校验闭环中，更具备可操作性。

• 对于如此轻量级架构的工程，如果 Harness 都无法胜任，那么 Harness 也不可能胜任更复杂的系统。

4. Harness 初探

4.1 构建单仓代码库

有了基本的判断之后，我们小组 4 个同学凑到了一起开始讨论具体的技术路线。我们采用了 OpenAI 的：“代码库作为 Agent 的唯一知识来源” 的思路来构建我们的 Harness，当我们发现 Agent 行为出现偏差的时候，我们就在对应的地方补充适当的约束来对 Agent 进行限制。

From the agent’s point of view, anything it can’t access in-context while running effectively doesn’t exist. Knowledge that lives in Google Docs, chat threads, or people’s heads are not accessible to the system. Repository-local, versioned artifacts (e.g., code, markdown, schemas, executable plans) are all it can see.

但是，与 OpenAI 从一个空代码库开始构建不同，我们的系统已经拆分为 versus-fe 和 versus-server 两个代码仓库了，并且我们已经把代码库的相关知识写入了各自的 CLAUDE.md 文件中。而对于两个仓库之间的知识，则存储在了人的经验中，而这恰好是 Agent 无法访问到的知识。而暴力地把两个已经存在的代码库强制合并到一个仓库中，又涉及到比较大的改动：

• 目录结构的调整

• CI 任务的调整

• 上线方式的调整

正如 Peter Pang 在文章 Why Your “AI-First” Strategy Is Probably Wrong 中所述：

I had to unify all the code into a single monorepo. One reason: so AI could see everything.

理念是个好理念，但是具体实施起来，看起来有点麻烦。我们想改，但是又不想花费太大的力气。

最终，我们采用 Git Submodule 的方式实现了代码仓库的 AI-First 重构。我们首先建了一个主仓库 versus，versus-fe 和 versus-server 仓库则以子模块的形式整合到主仓库中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

versus/                    # 父仓库
├── versus-server/         # 服务端子模块 (Go + Gin)
|   └── CLAUDE.md              # 服务端 Claude Code 项目指令
├── versus-fe/             # 前端子模块 (React + Vite)
|   └── CLAUDE.md              # 前端 Claude Code 项目指令
├── scripts/               # 管理脚本
│   ├── setup.sh               # 初始化开发环境
│   ├── pull-all.sh            # 拉取所有子模块
│   ├── status.sh              # 查看仓库状态
│   └── sync-user-config.sh    # 同步用户配置
├── .claude/               # Claude Code 配置与 Agent 定义
│   ├── settings.json          # Agent 与 MCP 插件全局配置
│   ├── settings.local.json    # 本地工具权限授权（不入库）
│   ├── agents/                # 6 个协作 Agent 定义文件
│   │   ├── requirement-designer.md
│   │   ├── go-api-implementer.md
│   │   ├── frontend-engineer.md
│   │   ├── test-case-designer.md
│   │   ├── integration-test-runner.md
│   │   └── e2e-test-executor.md
│   └── agent-memory/          # Agent 跨会话记忆
│       ├── requirement-designer/MEMORY.md
│       ├── go-api-implementer/MEMORY.md
│       ├── frontend-engineer/MEMORY.md
│       ├── test-case-designer/MEMORY.md
│       ├── integration-test-runner/MEMORY.md
│       └── e2e-test-executor/MEMORY.md
├── docs/                  # 项目文档与需求产物
│   ├── system-architecture.md           # 系统架构说明
│   ├── 6-agent-collaboration-summary.md # 6-Agent 协作流水线总结
│   └── requirements/                    # 各需求流水线产物（按 REQ-ID 组织）
│       ├── REQ-001/      
│       ├── REQ-CASE-RESOURCE/ 
│       ├── REQ-VIDEO-TYPES/   
│       ├── REQ-020/      
│       └── REQ-ERROR-CODE/
├── .gitmodules            # 子模块配置（已被 .gitignore 忽略）
├── .gitignore             # Git 忽略规则
├── CLAUDE.md              # 项目整体知识
├── dev.sh                 # 一键启动前后端服务
├── README.md              # 项目说明
└── FEATURES.md            # 功能清单

• versus 目录下的 CLAUDE.md 主要存放跨前后端、跨 Agent、跨需求都需要知道的全局知识，相当于整个项目的作战地图 + 协作规则 + 产品背景 + 全局约束。

• AI Coding 和 AI Testing 过程中需要的相关 Agent、产生的需求文档、测试用例列表、测试执行结果均存储于 versus 的主仓库目录下，从而真正实现了“一切皆在代码库，代码库之外，别无他物”的目标。

• versus-fe 和 versus-server 目录下的 CLAUDE.md 则存放前端和服务端相关的知识，包括架构、约束、编码规范等知识。

• Git Submodule 增加了仓库操作的复杂性，比如拉取主仓库代码时，需要递归拉取各子仓库的代码；而当子仓库的代码有修改需要提交时，也需要同时提交主仓库以更新主仓库对子仓库的版本索引。因此，为了降低仓库的操作复杂度，我们同时让 DUCC 帮我们实现了一系列的仓库管理脚本，从而实现通过自然语言交互就能稳定实现相关功能的目的。

4.2 Harness 闭环设计

Anthropic 的 Harness design for long-running application development 博客中提到当前的模型具备如下的问题：

• 上下文焦虑：当模型感知到即将达到自身上下文上限时，就会出现模型提前结束任务的现象。

• 自视甚高：当智能体评价自己完成的工作时，即便这些产出在人类看来平平无奇时，他们也会自信地大加夸赞。

为了解决如上的问题，我们按照软件开发的端到端流程拆分了 6 个基本的 Sub-Agent。

通过如上 6 个 Sub-Agent 的全流程自动流转和验证，形成完整的、自我完善的 Harness 开发闭环。

整个的闭环流程，除了 PRD 阶段需要人工审核以外，其他阶段均不需要人工介入。尤其是在前、后端开发过程中，Harness 避免了前后端 RD 之间的沟通与协作成本，极大地提升了开发的效率。

flowchart TD  A[用户触发: 启动 6 个 Agent 协作实现需求] --> B[1. requirement-designer\n产出 PRD.md, 分配 REQ-ID]  B --> C[人工审核 PRD\n唯一的用户确认节点]  C -->|用户确认通过| D[2. go-api-implementer\n产出 Go 后端代码 + api-summary.md]  D -->|status=completed 自动流转| E[3. frontend-engineer\n产出 React 前端代码]  E -->|status=completed 自动流转| F[4. test-case-designer\n产出 api-test-cases.json + e2e-test-cases.json]  F --> G[5. integration-test-runner\n端口: 8899/3000\nAPI 接口测试]  F --> H[6. e2e-test-executor\n端口: 8901/3001\n浏览器 E2E 测试]  G -->|has_bugs| I[后端 Bug]  H -->|has_bugs| J[前端 Bug]  I --> D  J --> E  G -->|all_passed| K[编码任务完成]  H -->|all_passed| K

以我们的一个实际的需求——为视频大模型增加评估任务类型——为例，具体的操作如下所示：

4.3 Agent Handoff 协议

采用 Sub-Agent 的方式可以解决单 Agent 中存在的“上下文焦虑”和“自视甚高”的问题，但也带来了新的问题：如何在不同的 Sub-Agent 之间安全、结构化地转移“控制权”与“上下文状态”？如果无法有效地解决 Sub-Agent 之间的交接，那么 Agent 之间就成了 “哑巴交流”——任务断连、状态错乱、故障恢复、链路追溯——都将导致异常灾难，最终完全失去了 Sub-Agent 分布式协作的价值。

为此，我们实现了一个简洁的 Agent Handoff 协议：当上一个 Agent 完成任务后，它会通过 Handoff 协议将任务状态、已收集的信息以及下一步的执行意图，规范地传递给下一个 Agent。

每个 Agent 在结束之前，必须附加如下所示的 Handoff 块，以完成任务的交接：

1
2
3
4
5
6
7
8
9
10
11

---AGENT-HANDOFF---
requirement-id: REQ-001
status: completed | awaiting_review | has_bugs | all_passed
output: 产出的文件路径
next-step: 下一步动作描述
next-step-prompt: 启动下一个 Agent 时使用的 prompt
after-approval-next-step: 审核通过后的动作（仅 awaiting_review）
after-approval-prompt: 审核通过后的 prompt（仅 awaiting_review）
bugs: Bug 列表（仅 has_bugs）
review-message: 审核提示（仅 awaiting_review）
---END-HANDOFF---

1
2
3
4
5
6
7
8
9

---AGENT-HANDOFF---
requirement-id: REQ-021
status: awaiting_review
output: docs/requirements/REQ-021/PRD.md
next-step: wait_for_human_approval
after-approval-next-step: launch go-api-implementer
after-approval-prompt: \"根据需求 REQ-021 的 PRD 实现后端接口。PRD路径: docs/requirements/REQ-021/PRD.md\"
review-message: \"PRD 已生成，请审核 docs/requirements/REQ-021/PRD.md，确认无误后回复'继续'启动后端实现\"
---END-HANDOFF---

Handoff 协议中各状态的含义如下：

当测试报告结果为 has_bugs 状态时：

1. 主会话解析 bugs 列表，确定 Bug 类型（后端/前端）；

2. 根据 Bug 类型分发给对应的 Agent 进行缺陷修复：

• 后端 Bug → go-api-implementer

• 前端 Bug → frontend-engineer

3. 修复完成后，重新启动对应的测试 Agent 来验证修复结果

4. 循环如上过程，直到所有测试用例全部通过，测试报告达到 all_passed 状态为止。

主 Agent 通过 Handoff 协议来调度各 Sub-Agent 的自动化执行。

4.4 测试用例生成

如前所述，在我们的工程中，我们把工程用到的所有的 Agent 描述都放在了 versus/.claude/agents 目录下，作为团队资产公用。test-case-designer Agent 的描述如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

---
name: test-case-designer
description: |
  Use this agent when you need to generate comprehensive test cases for a feature based on requirement documents, technical specifications, API implementations, and frontend implementations. This agent designs both API interface test cases and end-to-end (E2E) web test cases in JSON format. It does NOT execute tests - it only creates test case specifications.
---

You are an elite Software Quality Assurance Engineer and Test Architect with deep expertise in software testing methodologies, test case design, and quality engineering. You specialize in creating comprehensive, well-structured test cases that ensure software reliability and quality.

## Your Core Mission

You design test cases for features based on:
- Requirement documents (需求文档)
- Technical specifications (技术方案)
- API implementations (接口实现)
- Frontend implementations (前端实现)

You produce two types of test cases:
1. **API Interface Test Cases** (接口测试用例)
2. **End-to-End Web Test Cases** (端到端测试用例)

**IMPORTANT**: You ONLY design test cases - you do NOT execute them. Your output is JSON-formatted test case specifications.

## 产物规范

### 输入
- PRD 文档：`docs/requirements/{REQ-ID}/PRD.md`（由 requirement-designer 产出）
- API 摘要：`docs/requirements/{REQ-ID}/api-summary.md`（由 go-api-implementer 产出）
- 后端代码：`versus-server/` 目录（由 go-api-implementer 产出）
- 前端代码：`versus-fe/` 目录（由 frontend-engineer 产出）

### 输出
- API 测试用例：**必须**保存到 `docs/requirements/{REQ-ID}/api-test-cases.json`
- E2E 测试用例：**必须**保存到 `docs/requirements/{REQ-ID}/e2e-test-cases.json`

### 下游触发
测试用例设计完成后，提示主会话**并行启动** integration-test-runner 和 e2e-test-executor，传入需求 ID。

## Handoff 输出（MUST）

测试用例设计完成后，你 MUST 在输出末尾输出以下格式的 Handoff 块：

```
---AGENT-HANDOFF---
requirement-id: {当前REQ-ID}
status: completed
output: docs/requirements/{REQ-ID}/api-test-cases.json, docs/requirements/{REQ-ID}/e2e-test-cases.json
next-step: launch integration-test-runner AND e2e-test-executor in parallel
next-step-prompt-integration: "启动服务(后端8899/前端3000)并执行需求 {REQ-ID} 的 API 集成测试。测试用例路径: docs/requirements/{REQ-ID}/api-test-cases.json"
next-step-prompt-e2e: "启动服务(后端8901/前端3001)并执行需求 {REQ-ID} 的浏览器 E2E 测试。测试用例路径: docs/requirements/{REQ-ID}/e2e-test-cases.json"
---END-HANDOFF---
```
...
...

最终生成的接口测试用例如下所示：

4.5 E2E 浏览器测试

我们使用 Chrome DevTools MCP 来实现端到端的浏览器自动化测试。直接在 DUCC 的对话框输入：

安装 https://github.com/ChromeDevTools/chrome-devtools-mcp 插件

就可以完成 Chrome DevTools MCP 的安装。关于 Chrome DevTools MCP 更详细的介绍可以参见：通过 Chrome DevTools MCP 增强 Agent 的浏览器操控能力。

E2E 测试中使用的 Chrome DevTools MCP 工具分为三类：

• 导航与页面管理

  • navigate_page：导航到指定 URL

  • new_page：打开新标签页

  • list_pages：列出所有打开的页面

  • select_page：选择当前操作的页面

  • close_page：关闭页面

• 页面内容获取

  • take_snapshot：获取页面 a11y 树文本快照（含元素 uid）

  • take_screenshot：截取页面或元素截图

  • list_console_messages：列出控制台消息

  • list_network_requests：列出网络请求

  • get_network_request：获取网络请求详情

  • evaluate_script：在页面中执行 JavaScript

• 页面交互

  • click：点击页面元素

  • fill：在输入框中填写内容

  • hover：悬停在页面元素上

  • press_key：按键或组合键操作

  • type_text：在当前焦点输入框中输入文本

e2e-test-executor Agent 的执行过程分为三个阶段：

• 环境准备：Agent 首先在独立端口（后端 8901、前端 3001）上构建并启动前后端服务，确保与集成测试环境互不干扰。服务就绪后，通过 Chrome DevTools MCP 建立与浏览器的连接。

• 逐用例执行：对每个测试用例，Agent 按以下步骤操作——先 navigate_page 导航到目标页面，再 take_snapshot 获取页面 a11y 树快照以定位元素，然后按用例定义的步骤逐步执行交互操作（click、fill、type 等）。每执行完一步，会调用 take_screenshot 截图留存，最后对比实际页面状态与预期结果，并分析用例执行结果。

• 结果判定与反馈：所有用例执行完毕后，若无用例执行失败则生成 summary.md 并对截图进行归档，流水线以 all_passed 结束。若存在执行失败的用例，则根据 Bug 类型分发给对应的 Coding Agent 修复（后端 Bug → go-api-implementer，前端 Bug → frontend-engineer），修复后重新启动服务并重跑失败用例，循环直到全部通过。

整体过程如下所示：

flowchart TD    A["e2e-test-executor 启动"] --> C["启动前、后端服务"]    C --> D["通过 Chrome DevTools MCP 控制浏览器"]    D --> E    subgraph E ["对每个测试用例"]        direction LR        E1["1. 进入指定页面"] --> E2["2. take_snapshot 获取页面"]        E2 --> E3["3. 按步骤执行"]        E3 --> E4["4. 截图"]        E4 --> E5["5. 验证并记录结果"]    end    E --> G{"是否有失败用例?"}    G -->|全部通过| F["生成 summary.md + 截图归档
status=all_passed"]    G -->|存在失败| H{"Bug 类型?"}    H -->|后端 Bug| I["go-api-implementer 修复"]    H -->|前端 Bug| J["frontend-engineer 修复"]    I --> K["重新启动服务 & 重跑失败用例"]    J --> K    K --> E

5. 文档更新

随着项目不停的迭代，新增加的功能越来越多，对旧需求的修改也越来越多。慢慢地，项目代码库中的文档知识就开始出现“熵增”的问题了。例如：我们已经把平台的登录系统由 UUAP 升级到了 Passport，但是 versus/CLAUDE.md 中的描述却没有及时更新，这将严重影响 Agent 后续的执行性能。

这是一个比较合适的 /goal 应用场景，于是，我打开了 Codex CLI，并输入了如下的检查要求：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

/goal 执行一次“文档与代码一致性同步”任务，直到满足完成条件。

  目标：
  检查并更新 CLAUDE.md、README.md、docs/**/*.md 以及其他 Markdown 文档，使其与当前代码、测试、配置、脚本、类型定义、API 路由、CLI 命令、环境变量和实际目录结构保持一致。

  事实源优先级：
  1. 当前代码实现
  2. 测试用例
  3. package.json / Makefile / CI 配置 / 脚本
  4. 类型定义、API schema、路由定义、配置 schema
  5. .env.example 或配置示例
  6. 实际目录结构

  硬性约束：
  - 只允许修改 Markdown 文档文件，包括 CLAUDE.md、README.md、docs/**/*.md、*.md、*.markdown。
  - 不允许修改业务代码、测试、配置文件、lock 文件、生成文件或二进制文件。
  - 不要为了匹配文档而修改代码；代码是事实源，文档是派生物。
  - 不要重写整篇文档，只做最小必要修改。
  - 不确定的内容不要编造，列入最终报告的“需要人工确认”。
  - 禁止修改 .claude 目录下的任何内容。

  执行步骤：
  1. 建立项目事实清单：包管理器、启动命令、构建命令、测试命令、lint/typecheck 命令、目录结构、主要模块、API/路由/CLI、环境变量。
  2. 扫描所有 Markdown 文档，排除 .claude 目录，识别与代码事实不一致的地方。
  3. 对有明确事实依据的不一致，只更新 Markdown 文档。
  4. 修改后运行：
     - git diff --name-only
     - 如存在子模块，也运行 git -C <submodule> diff --name-only
  5. 如发现非 Markdown 文件被修改，立即回滚这些非文档变更。
  6. 输出最终报告。

  完成条件：
  - 所有有明确代码事实依据的文档不一致都已修复。
  - 父仓库和所有子模块的实际文件级 diff 只包含 Markdown 文件。
  - 最终报告必须列出：
    1. 修改了哪些文档
    2. 每个文档修正了什么
    3. 每项修正依据的代码/配置/脚本事实
    4. 哪些内容仍需要人工确认
    5. 确认没有修改非文档文件

最终，经过了 8 分钟多的检查，消耗了大约 435W 的 token，Codex 完成了文档与代码的一致性升级。

文档与代码的一致性校验目前尚未整合到当前的 Harness 自闭环流程中，后续我们也会像 OpenAI 的操作一样：起一个后台服务来周期性地进行清理，并自动合并到代码仓库中。

6. 真的是完美的吗？

如上的 Harness 过程确实帮我们实现了 “一句话实现产品功能” 的目标，也确实避免了不同角色之间的沟通，提升了开发的效率，但是我们也在实践中发现我们的 Harness 模式并不是 100% 完美的，它也有它的问题存在。

6.1 E2E 测试的检测能力相对较弱

通过如下的一个真实功能在不同阶段的耗时分布，我们发现：用例执行阶段的耗时是最长的，并且 E2E 测试决定着用例执行时间。但是在我们的实践中：E2E 测试很少报告缺陷，大部分 90%+ 的缺陷均是由 API 接口测试发现。

是真的没有样式 BUG 吗？修改视频任务分类之后，我们确实也发现了前端样式的 BUG：在任务名比较长的时候，任务类型出现了元素遮挡的问题。

目前，我们的 E2E Testing Agent 对于质量的把控能力相较于人工测试而言还存在差距，一方面测试 Agent 对 Bug 的认定比人类宽松，一方面测试 Agent 缺少对布局、美感等的评判（当然，我们也没有对这方面进行限定）。因此，当前的 Harness 能力只保证功能的可用性，并不保证页面符合人类的审美。不过，对于我们这样的非复杂交互的系统而言，这样已经足以满足要求了。

6.2 需求改动存在遗漏

在视频任务分类拆分的升级中，我们还发现 Agent 在实现任务的过程中遗漏了“模型管理”这个页面的改动。我们重新 Review 了对应的 PRD，发现在 PRD 中就已经存在遗漏了。虽然我们会对 Agent 生成的 PRD 内容进行审核，但是确实在审核的时候也发生了遗漏，毕竟一次审核 600+ 行的文本内容成本确实有点大。

7. 总结

尽管当前的 Harness 实践在 E2E 测试环节仍有局限，但其带来的 ROI 已极其可观。根据我们在 4 个功能升级上的数据统计，当前的 Harness 已经让我们的功能发布效率提升了 4 倍，虽然与 OpenAI 博客中的 10 倍相比还有不少差距，但是已经让我们成功从“人工调优代码”跨越到“治理 Agent 流水线”，彻底打破了前后端联调的沟通壁垒。

为了强化对某项特定技术的理解与实践，我经常会利用空余时间阅读并翻译该技术领域的相对较前沿的英文书籍，自从 ChatGPT 发布以来，翻译外文书籍越来越方便。即便如此，翻译一本书还是需要非常多的繁杂的规则，例如：交叉引用、公式编号、字体使用规范、图片引用规范、排版规范……这些规范在我翻译书籍的过程中往往占据了大量的时间。

恰好最近在研究 Harness Engineering，突然我想：写代码与翻译在本质上不都是生成吗？Transformer 架构最初不也是为机器翻译而提出的吗？于是我就想把 Harness Engineering 的思想应用到书籍翻译上来，并依此来分析一下 Harness Engineering 的效果。

Harness Engineering

2026 年 2 月 5 日，Mitchell Hashimoto 在他的博客 My AI Adoption Journey^[1] 中提出了 Harness Engineering 这个概念。

I don’t know if there is a broad industry-accepted term for this yet, but I’ve grown to calling this “harness engineering”.

It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again. I don’t need to invent any new terms here; if another one exists, I’ll jump on the bandwagon.

这就是 Harness Engineering 最初的含义：当你发现 Agent 犯错的时候，需要采用系统化的方案来确保 Agent 不再犯类似的错误。

然后，Cursor、OpenAI、Anthropic 先后发布了各自在 Agent-First 软件开发上的实践报告^[2][3][4]。这三篇实践报告均指向了 Mitchell Hashimoto 文章中的一个术语：Harness Engineering，从而引爆了 Harness Engineering 的浪潮。

于是一个混乱的时代到来了，就像我在 什么是微服务 里提到的那样：虽然我们是在讨论同一个术语，但是实际上我们却是在讨论不同的东西。

仔细阅读 Cursor、OpenAI、Anthropic 的实践报告之后，我发现，虽然他们都提到了 Harness Engineering，虽然这三篇文章的读者群高度重叠，虽然用的术语高度一致，但各自回答的工程问题截然不同^[5]:

• 时间维度：Anthropic 研究的是如何让 Agent 更长时间的自主运行。
• 空间维度：Cursor 研究的是如何让几百个 Agent 能并行自主工作。
• 协作维度：OpenAI 研究的则是当 Agent 的产出速度远超人类的注意力时，人应该通过什么方式来控制整个系统。

后来，我想了好久，终于想通了——其实理解 Harness Engineering 可以从多个维度切入：

• 从问题空间来看：它主要解决智能体重复犯相同错误、自主运行时长有限、输出结果不符合预期等问题。
• 从解决空间来看：它为大模型系统性地构建约束空间、引导模型沿着有限路径、高效朝着预设目标推进。
• 从最终效果来看：它实现了智能体自主化、长时程、可管控的稳定运行。

所以，Harness Engineering 也可以看作是一种面向失败、面向不稳定性开发的有效实践范式。

翻译书籍的复杂性

在 Chat 模式时，大模型可以帮助我完成从英文到中文的初步翻译过程，这个过程也就仅仅是把内容从英文变成中文，除此之外剩下的大部分的工作还需要我来处理：

• 字体样式的统一
• 交叉引用的统一
• 翻译术语的前后统一
• ……

如果涉及到数学公式，还需要做更多的工作……

仔细分析，就会发现，这些复杂性恰好是 Harness Engineering 最开始要解决的问题：

当你发现 Agent 犯错的时候，需要采用系统化的方案来确保 Agent 不再犯类似的错误

只要告诉 Agent，在翻译过程中需要遵循什么样的规范，遇到图要怎么处理、遇到公式要怎么处理、遇到交叉引用要怎么处理…… Agent 自己就可以按照这个规范生成正确的内容。

想想我自己的翻译过程，也是如此：当我间隔很长时间没有翻译的时候，在继续翻译的时候我也会翻一下之前的规则，来保障整本书的统一。Harness Engineering 只是把我脑子中的那些规则固化下来而已，从而解决了 Agent 重复犯错的问题。

我的实践

为了验证我的想法，我找到了 2 年前的一个翻译项目：Introduction to Probability and Statistics for Engineers and Scientists(Sixth Edition)。这本书从 2025 年 2 月开始就没有持续翻译了，也算是一个有着历史包袱的遗留项目，要在这种项目上引入 Harness Engineering 并让 Agent 继续工作下去，说实话，心里确实没底。

说干就干，开搞。我用到的所有的内容如下：

• GitHub 仓库
• Gemini CLI（模型选择gemini-3.1-pro-preview）
• chrome-devtools-mcp 工具
• 英文原版 PDF 书籍（book_en.pdf）

花若盛开，蝴蝶自来

在与 AI 协作的时候，我们有时候表现得就像我们讨厌的 “老登” 一样，我们会没有任何依据的先给 AI 灌输一堆的知识、信息，并号称 AI 需要这些知识，否则他就没法生成符合预期的结果。这听起来非常有道理的样子……

但是，我比较懒，在重新翻译的时候，因为中间隔了 1 年之久了，我也不想再去翻看之前的翻译、去回忆总结那些规则作为知识并灌输给 AI……

我甚至都不想告诉 Gemini CLI 需要怎么分页，用什么工具可以分页……

我坚信，不试试怎么知道 Gemini CLI 会不会呢？在不探测别人的能力时强行输入一堆知识确实像一个 “老登”，还好，这次我忍住了想当一个 “老登” 的欲望。

我在 Gemini CLI 中输入的如下的内容，我仅仅给出了任务描述，没有提前输入任何的额外的知识：

按照要求，翻译 @book_en.pdf 的 14.2 的内容。

我观察到，在没有输入任何知识的时候，Gemini CLI 自己会去搜索我翻译的其他章节的内容，并从中自己提炼相关的规则。

效果非常惊艳，我只是给了明确的任务，Gemini CLI 大概花了 40 分钟的样子自己完成了所有的工作，中间我没有做任何的修改和提示。

• 自己读取 PDF 的内容，并非常精准地提取了 14.2 节的原内容
• 自己去回顾我翻译过的历史章节内容，提取对应的规则

最终的效果参见 14.2 失效率函数，完全符合预期。

保存 AI 总结的知识

翻译整本书不是一个 session 就能解决的，如果明天我重新打开 Gemini CLI 开始新的任务时，我可不想让 Gemini 再浪费时间去学习那些规则，是时候记住一些东西了。于是，我在 Gemini CLI 中先让 Gemini 自己反思一下：

从这次翻译过程中，你学习到了哪些项目的规范，请逐一列举，不要遗漏。

除非必须，绝不多嘴

然后，我继续让 Gemini CLI 来翻译 14.3 节，但是这一节中增加了很多上一节中不存在的规则，例如：

• 图的处理
• 有的习题题目和答案是放在一起的，没有区分 练习 部分和 答案 部分
• 复杂公式

我不想做 “老登”，我只在观察到 AI 明显犯错的时候才系统化地给出知识和规则，于是在和 Gemini 交互了多次后，GEMINI.md 中的知识也不断地丰富了起来。

随着规则越来越多，我与 Gemini CLI 的交互也越来越少，Gemini CLI 可以更长时间的自主翻译。对于 14.4 和 14.5 章节的翻译，我只是给出了任务，中间没有做过任何的干预，Gemini CLI 的翻译产出已经能够做到 PASS@1。 现在 GEMINI.md 的内容如下所示：

## 开发规范（翻译与排版约定）### 1. 文件组织- **章节主文件**：每个章节的主文件（如 `14.qmd`）的一级标题应翻译为中文，并保留锚点（如 `# 寿命测试 ｛#sec-14}`）。- **小节标题层级**：在子章节文件（如 `14_2.qmd`）中，小节标题使用 `##`，更深层级依次递增。### 2. 术语翻译- **中英对照**：专业术语首次出现或定义时，使用 **中文加粗** 后接 (*英文斜体*) 括号标注。示例：**失效率函数**（*hazard rate function*）。- **关键术语**：正文中提到的核心概念应使用加粗。保持全书一致性，如 **最大似然估计量** (*maximum likelihood estimator*)。### 3. 交叉引用与锚点- **标题锚点**：每个标题后需紧跟 ID 锚点，格式为 `｛#sec-章节号_小节号}`。- **公式锚点**：公式需编号，格式为 `｛#eq-章节号_小节号_序号}`。- **定理锚点**：定理需编号，格式为 `｛#thm-章节号_小节号_序号}`。- **定义锚点**：定义需编号，格式为 `｛#def-章节号_小节号_序号}`。- **推论锚点**：推论需编号，格式为 `｛#cor-章节号_小节号_序号}`。- **表格锚点**：表格需编号，格式为 `｛#tbl-章节号_小节号_序号}`。- **图形锚点**：图形需编号，格式为 `｛#fig-章节号_小节号_序号}`。- 示例锚点：习题与解答成对出现时，习题编号为 `｛#exr-章节号_小节号_序号}`。- 示例答案锚点：习题与解答成对出现时，解答编号为 `｛#sol-章节号_小节号_序号}`。- 独立示例锚点：只有习题或例题（无独立解答块）时，使用 `｛#exm-章节号_小节号_序号}`。- 引用语法：使用 `@sec-ID`、`@eq-ID`、`@thm-ID`、`@def-ID`、`@cor-ID`、`@exr-ID`（习题）、`@sol-ID`（解答）、`@exm-ID`（独立示例）、`@tbl-ID`（表格）、`@fig-ID`（图形）等进行自动交叉引用。**禁止使用纯文本“示例 X.X”进行引用**。### 4. 示例与解答格式- **专用块 ID**：示例（Example）和解答（Solution）必须包裹在 Quarto 自定义块中：    - 习题与解答配对：        - 习题：`::: ｛#exr-章节号_小节号_序号}`        - 解答：`::: ｛#sol-章节号_小节号_序号}`    - 独立示例（无独立解答块）：        - 示例：`::: ｛#exm-章节号_小节号_序号}`### 5. 数学公式与排版- **独立定界符**：行外公式的 `$$` 定界符必须**各自独占一行**。- **对齐环境**：复杂推导优先使用 `\begin{align} ... \end{align}`，且必须包裹在 `$$ ... $$` 中以确保公式编号正常显示，示例：  
1
2
3
4
5
$$
\begin{align}
公式内容...
\end{align}
$$ ｛#eq-ID}
- **符号约定**：    - 均值：`\overline{X}` 或 `\bar{x}`    - 分布：`\sim`    - 正态分布：`\mathcal{N}`- **中西文间距**：中文与行内公式 `$ ... $` 之间应保持一个半角空格。### 6. 绘图规范 (R Graphics)- **代码绘图**：原书中的示意图（如时间轴、分布图等）应优先使用 R 代码块（`ggplot2`）生成，而非使用静态图片。- **标签语言**：R 代码块生成的图形中，所有文本标签（label）、轴标题（axis title）和数学符号应**保持英文**。- **图形引用**：需配置 `#| label: fig-ID` 并使用 `@fig-ID` 引用。### 7. 语言风格与校对- **语气**：保持严谨、客观的学术叙述风格。- **标点**：正文使用全角中文标点；数学环境内使用西文标点。- **OCR 校验**：严格审查 OCR 识别导致的同音错别字（如将“贝叶斯”识别为“贝育”）。

自动校验与评估

Anthropic 的博客中提到了模型 自我评价失灵 的问题，也就是说：当我们要求模型评价自己的作品时，即便这些作品非常一般，Agent 也倾向于自信地赞美。

A second issue, which we haven’t previously addressed, is self-evaluation. When asked to evaluate work they’ve produced, agents tend to respond by confidently praising the work—even when, to a human observer, the quality is obviously mediocre. This problem is particularly pronounced for subjective tasks like design, where there is no binary check equivalent to a verifiable software test. Whether a layout feels polished or generic is a judgment call, and agents reliably skew positive when grading their own work.

但是，当 Gemini CLI 翻译完之后，我也不想去 Review 翻译的内容对不对、格式对不对、图对不对……

于是，我想让 Gemini CLI 在完成编译之后自动触发 gemini-3-flash-preview 模型来进行自动校验，如果存在不符合规范的地方，Gemini CLI 再自动修正……

flowchart LR  A[启动 Gemini CLI 翻译] --> B1[加载 GEMINI.md]  B1 --> B[gemini-3.1-pro-preview 完成翻译]  B --> C[Hooks 自动触发 gemini-3-flash-preview 校验（skills）]  C --> D{是否符合规范?}  D -->|不符合| E[自动修正内容]  E --> C    D -->|符合| F[继续翻译]

关于 Hooks 和 Skills 的详细内容，可以参见 GitHub 代码仓库：

• Hooks：settings.json
• Skills：translation-reviewer
• Script：validate_edit.sh

模式的转变

在 Harness Engineering 的模式下，确实如 OpenAI 的博客中所述的 Humans steer. Agents execute 那样，我真的：

• 再也没有手动翻译过任何的一个单词
• 再也没有手动把原书中的图转换成 R 代码
• 再也没有手动处理过任何一个 LaTeX 公式
• ……

在翻译过程中，我所做的工作变成了：

• 在必要的时候给 Gemini CLI 提供知识与规则
• 构建自动化评估的机制
• 编写评估所用的 Skill（其实 Skill 本身也是 Gemini 生成的）
• 给 Gemini CLI 明确的任务
• ……

当然，与 AICoding 相比，AITranslating 的复杂度确实低很多，但是模式是那么的相似、目标也是那么的一致：Humans steer. Agents execute。

更理想的状态应该是构造完知识、规则、环境与工具后，把一本英文的 PDF 书籍丢给 Gemini CLI，Agent 自己就会拆解为多个子任务（按照章节粒度翻译），然后按照如上的流程逐章节进行翻译并自动校验。于是，一个更长程的翻译任务也就跑起来了。

参考文献

10 年前，也就是 2016 年，为了解决 VS Code 多语言支持重复开发的问题，微软团队基于 TypeScript Server 的通信机制，开始设计通用协议，以解决编辑器与语言服务解耦。^[1] 同年的 6 月 27 日，微软在 DevNation 大会上正式宣布开源 LSP，从而解决了“针对同一语言，每个编辑器都要重写一遍智能提示”的噩梦，也标志着现代 IDE 进入了新的时代。^[2]

多年以后，同样的情况出现在了 AI Coding Agent 的领域——2025 年 8 月 27 日，Zed Industries 在博客 Bring Your Own Agent to Zed — Featuring Gemini CLI 中正式公开 ACP 协议，并推出 Zed 中整合的 Gemini CLI 作为首个 ACP 的参考实现。^[3]

为什么需要 ACP？

截至目前，市面上已有至少 17 款成熟的 AI Coding Agent（Claude Code、Cursor、Codex CLI、Gemini CLI、Windsurf、Cline、goose、Kimi CLI、OpenCode……）。同时，至少有 6~7 款主流的编码 IDE（VS Code、IntelliJ/JetBrains、Zed、Neovim、Cursor……）。

每一个 AI Coding Agent 都需要与不同的 IDE 进行集成。如果想在 JetBrains 中使用 Claude Code？JetBrains 团队就得在 JetBrains IDE 中开发适配 Claude Code。想在 Neovim 中使用 Claude Code？不好意思，也得重新适配。

这种重复的集成工作，反反复复地出现在整个工具链生态，不仅造成了厂商锁定效应，还拖慢了创新步伐。

而 ACP 协议就是为了解决这个问题而提出，它的作用和 10 年前的 LSP 协议一样，都是为了建立一套通用标准，从而实现 AI Coding Agent 与 IDE 之间的解耦。

ACP 的时间节点

2025 年初，Zed Industries 团队正在优化 “agentic editing” 功能，恰在此时，谷歌方面联系到他们，希望与 Zed 探讨如何在 Zed 中更深度地集成 Gemini CLI。尽管当时 Zed 已经可以在其嵌入式终端中运行 Gemini CLI 了，但通过 ANSI 转义码进行通信的方式，无法满足现代 IDE 丰富交互的需求。

正如 Zed 在博客中说的那样^[3:1]：“我们需要一种比 ANSI 转义码更结构化的通信方式。” 这促成了 ACP 的诞生——一个极简的 JSON-RPC 框架，它允许任意 Client 通过定义完善的 schema 与任意 Agent 进行通信。

After shipping agentic editing earlier this year, the next big task on our roadmap was making that experience extensible.

As luck would have it, that’s around the time when Google decided to reach out. The Gemini CLI team was having a great experience using their agent in Zed’s integrated terminal, and they wanted to explore what deeper integration could look like.

Command-line agents are cool because their simplicity makes them easy to run anywhere—including as a subprocess of another application. Zed was already running Gemini CLI inside our embedded terminal emulator, but we needed a more structured way of communicating than ANSI escape codes.

So we defined a minimal set of JSON-RPC endpoints to relay user requests to the agent and render its responses. The result is the Agent Client Protocol, a lean framework that lets any client talk to any agent, as long as they follow the schema.

ACP 协议于 2025 年 8 月推出，以 Gemini CLI 作为参考实现，同年 9 月便迅速集成了 Claude Code，同年 10 月又迅速集成了 Codex……

如今，ACP 是一款采用 Apache 2.0 开源许可协议的项目，背后有 Zed、谷歌、JetBrains 等行业巨头以及日益壮大的 IDE 插件开发者社区提供支持。我们可以在 ACP 协议的官网查看目前所有的 Clients 和 Agents。

ACP 协议简介

ACP 是一种 JSON-RPC 2.0 协议，其核心原则简单明了：

• Client：各类编辑器，如 Zed、JetBrains、VS Code 等，主要负责管理用户的编程环境
• Agent：各类 AI Coding Agent，如 Claude Code、Gemini CLI、OpenClaw 等，主要负责思考与工具执行
• Client 与 Agent 之间通过标准输入输出流通信（智能体以子进程形式运行），或通过 HTTP 协议通信（远程智能体）

关于 ACP 协议的详细内容，此处不再过多介绍了，具体可以参见：ACP 协议的官网。

ACP 中的核心概念与流程

IDE 与 Agent 的 ACP 通信

flowchart LR  subgraph ClientEditor ["Client (Editor)"]      Editor["Zed / JetBrains / Neovim"]  end  subgraph AgentAI ["Agent (AI)"]      Agent["Claude Code / Gemini CLI"]  end  Editor -- "session/prompt" --> Agent  Agent -- "session/update" --> Editor  Agent -- "fs/read_text_file" --> Editor  Agent -- "terminal/create" --> Editor  Agent -- "request_permission" --> Editor

ACP 的全生命周期图

sequenceDiagram  participant User  participant Client as Client (Zed)  participant Agent as Agent (Gemini CLI)  participant LLM  Note over Client, Agent: 1. Initialization  Client->>Agent: initialize  Agent-->>Client: capabilities + version  Note over Client, Agent: 2. Session Setup  Client->>Agent: session/new  Agent-->>Client: sessionId  Note over Client, Agent: 3. Prompt Turn  User->>Client: "Run tests and fix failures"  Client->>Agent: session/prompt  Agent->>LLM: Process prompt  LLM-->>Agent: Response + tool calls  Agent->>Client: session/update (plan)  Agent->>Client: session/update (tool_call: pending)  Note over Client, Agent: 4. Tool Execution  Agent->>Client: terminal/create  Client-->>Agent: terminalId  Agent->>Client: session/update (tool_call: in_progress)  Note left of Client: Shows live terminal output  Agent->>Client: terminal/output  Client-->>Agent: output + exitStatus  Agent->>Client: session/update (tool_call: completed)  Note over Client, Agent: 5. File Operations  Agent->>Client: fs/read_text_file  Client-->>Agent: file content  Agent->>Client: session/request_permission  Client-->>Agent: allowed  Agent->>Client: fs/write_text_file  Client-->>Agent: success  Agent->>Client: session/update (diff)  Note over Client, Agent: 6. Completion  Agent-->>Client: session/prompt response (end_turn)

Terminals 命令的时序图

sequenceDiagram  participant Agent  participant Client  Agent->>Client: terminal/create  Note right of Client: command: "npm test"
args: ["--coverage"]
cwd: "/project"  Client-->>Agent: { terminalId: "term_001" }  Agent->>Client: session/update  Note left of Agent: tool_call_update
status: in_progress
content: [terminal embed]  Note right of Client: Displays live output  Agent->>Client: terminal/wait_for_exit  Note right of Client: Command runs...  Client-->>Agent: { }  Agent->>Client: terminal/output  Client-->>Agent: { output: "...", exitStatus: { exitCode: 0 } }  Agent->>Client: terminal/release  Client-->>Agent: { }

权限请求时序图

sequenceDiagram  participant Agent  participant Client  participant User  Agent->>Client: session/request_permission  Note right of Client: toolCall: { title: "Delete old_file.txt" }
options: [allow_once, allow_always, reject]  Client->>User: Show permission dialog  User-->>Client: Click "Allow"  Client-->>Agent: { outcome: "selected", optionId: "allow_once" }  Note left of Agent: Proceeds with tool execution

ACP 协议的优点

1. 摆脱厂商绑定

还记得我们当初不得不在 Cursor、VS Code 或是特定终端代理之间艰难抉择的情况吗？有了 ACP 协议，我们完全可以根据自己的喜好选择最趁手的编辑器，再根据当前的任务需求选择最合适的代理：

• 开发复杂功能：选用擅长架构设计和逻辑推理的代理。
• 调试疑难杂症：切换到更擅长解析堆栈追踪和日志信息的代理。
• 编写测试用例：选择专攻测试驱动开发的专业代理。

我们的编辑器对此毫无感知，所有的底层交互均由 ACP 协议统一处理，真正实现了工具链的自由组合。

2. 适配任务的最佳工具

LLM 的迭代速度极快，往往快到令人应接不暇。昨天还表现最优的模型，可能短短一周后就被新的模型所超越。如果采用专属的集成方案，我们只能被动等待编辑器厂商的支持。

而借助 ACP，我们获得了前所未有的敏捷性：

• 即插即用：新智能体发布 → 接入 ACP → 即可在我们的编辑器中无缝使用。
• 零等待成本：无需等待插件更新，无需更换编辑器，更无需重新适应操作习惯。

3. 提升团队协作的灵活性

在实际的开发团队中，我们经常会看到这样的场景：前端开发者钟爱 Claude Code，后端工程师对一款针对技术栈微调的定制化 Agent 深信不疑，而运维人员则习惯于另一套完全不同的工具。

ACP 协议能够确保无论个人偏好如何，所有人都能顺畅协作。每个人都可以使用自己得心应手的编辑器和信赖的 Agent。这同时也让团队的入职流程变得更加简便——新开发者加入时，只需告诉他们：“用你最顺手的编辑器就行，这些是我们团队在用的智能代理，它们全都兼容可用。”

4. 面向未来的前瞻性设计

我们正处于智能体时代的早期阶段，新功能和新范式每周都在不断涌现。未来的智能体不仅能写代码，还能够实现：

• 复杂的浏览器自动化操作
• 深度的数据库查询与分析
• 执行跨系统的复杂工作流
• 与其他智能体进行多模态协同工作

参考文献

当我们用类似 Claude Code、Codex、Gemini CLI 等 AICoding Agent 写完代码，然后让它自动生成测试计划、自动调起浏览器来测试刚刚生成的代码，并根据反馈结果重新优化代码。在这个循环中，不需要人手动干预，完全依赖 AICoding Agent 自主操控，这不是一件非常美妙的事情吗？

这不就是当下爆火的 Harness Engineering 吗？正如 Harness Engineering: Why the Best AI Engineers in 2026 Stopped Writing Code 中说的那样^[1]：

A researcher tested the same AI model on the same coding benchmark twice. The first time, it scored 42%. The second time, it scored 78%. Same model. Same test. Same everything.

如上的框架的核心点在于：AICoding Agent 可以有效的操控浏览器。 本文将介绍三种浏览器控制方案：Playwright、Browser-use 以及伴随 Chrome M144 推出的最新利器 Chrome DevTools MCP，并通过多维度的对比，为大模型应用的架构选型提供参考。

一个简单的例子

我们可以把如上提到的 Harness Engineering 的过程简化成如下的流程图：

graph TD    Start([需求输入]) --> A        subgraph 规划与编码        A[Codex 编写/修改目标代码] --> B[解析代码 & 生成测试计划]        B --> C[构建可执行测试脚本]    end        subgraph 自动化执行与环境交互阶段        C --> D[环境调度与协议打通]        D -->|通过 CDP/MCP 控制本地 Mac 或远程集群浏览器| E[自动执行测试 / UI 交互]    end        subgraph 反馈与自我进化循环        E --> F[捕获运行时反馈]        F -->|提取控制台日志、DOM 状态、截图、网络抓包等| G{大模型结果评估}        G -->|测试通过指标达标| H([任务完成 / 代码合入])        G -->|测试失败 / 发现缺陷| I[AI 深度剖析错误根因]        I -->|生成代码优化与修复策略| A    end        %% 定义节点样式    classDef aiNode fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px;    classDef envNode fill:#fff3e0,stroke:#ff9800,stroke-width:2px;    classDef evaluateNode fill:#fce4ec,stroke:#e91e63,stroke-width:2px;        class A,B,C,I aiNode;    class D,E,F envNode;    class G evaluateNode;

当然，现实中，很多的应用并非全部都依赖浏览器来做校验。比如：iOS、Android 等的客户端的开发还需要驱动对应的模拟器或者真机来调试。但是，本文主要介绍的还是 AI Coding Agent 与浏览器的交互。

Playwright

Playwright 原本是微软开源的现代 Web 自动化测试框架。在 Agent 爆发的早期，它成为了几乎所有 LLM 控制浏览器的底层“发动机”。大模型输出 Python 或 Node.js 代码，由 Playwright 翻译为底层的 WebSocket 指令发送给浏览器。

Playwright 的设计哲学是隔离与确定性。默认情况下，它每次启动都会拉起一个全新、无头的沙盒浏览器实例。

Playwright 的优势：

极高的执行速度和并发能力。由于是纯代码驱动，它在执行预定义好的大批量测试流水线时，稳定性无可匹敌。它提供了完善的 Cookie 注入、网络拦截等底层 API。

但是，在 AI 辅助场景下，Playwright 存在致命的问题：

• “登录墙”噩梦： 当我们希望 Agent 帮我们排查内部系统或抓取受保护的数据时，Playwright 拉起的干净实例会被瞬间挡在登录页外。面对复杂的扫码或滑块验证码，AI 几乎束手无策。
• UI 脆弱性： 一旦网页的 DOM 结构或 CSS 选择器发生微小变动，底层生成的 Playwright 代码就会直接报错崩溃，容错率极低。
• 高昂的通信延迟： 传统的 Python -> Node.js Server -> 浏览器 架构，在需要高频次拉取几万个 DOM 节点供 LLM 分析时，会产生严重的 IPC（进程间通信）延迟。

辅助场景下，Playwright 是流水线上的“无情机器”，适合确定性的 E2E 测试和后台爬虫，但不适合作为需要与人类环境共享上下文的“AI 副驾驶”。

Browser-use

Browser-use 是目前开源社区极具代表性的高层 Agent 框架。值得注意的是，从 0.6.0 版本开始，Browser-use 作了一次重大底层重构：彻底抛弃了 Playwright，全面转向直接使用纯 CDP (Chrome DevTools Protocol) 与浏览器进行通信，以追求更极致的性能。

Browser-use 的核心哲学是视觉驱动。它不关心网页底层用了什么前端框架，而是直接对网页进行截图，提取出可交互元素的边界框（Bbox），并将这些带有坐标标签的图片喂给具备视觉能力的大模型（如 Claude 3.5 Sonnet）。大模型像人类一样“看”网页，然后输出诸如“点击带有购物车图标的按钮”的自然语言指令。

Browser-use 的优势：

极强的鲁棒性（抗干扰）： 网页改版、按钮换位置、甚至底层的 React 状态乱了都没关系，只要人眼能看懂，模型就能看懂并操作。

开发门槛极低： 开发者无需编写复杂的 DOM 选择器代码，完全通过自然语言 Prompt 驱动复杂的探索性任务。

Browser-use 的劣势：

Token 成本与延迟双高： 每执行一步操作，都需要向多模态大模型传输庞大的图像 Token，这在进行大规模自动化评测或高频系统调度时，成本是难以接受的。

浅层交互限制： 它只能看到网页的“表象”。如果页面由于底层跨域问题加载失败，或者 JavaScript 抛出了深层的堆栈错误，Browser-use 是无法察觉的。

Browser-use 是灵活的“AI 司机”，非常适合处理面向消费者的非结构化网页任务（如机票比价、数据探索），但在企业级深水区显得有些昂贵且不够深入。

Chrome DevTools MCP

根据谷歌的开发者文档^[2]：

We shipped an enhancement to the Chrome DevTools MCP server that many of our users have been asking for: the ability for coding agents to directly connect to active browser sessions.

使用该特性，我们的 AI Coding Agent 可以实现如下的功能：

• 复用现有的 Chrome 浏览器会话：AI Coding Agent 可以直接访问当前的浏览器会话，直接使用当前会话中的登录信息，而不需要在自动化测试的过程中增加额外的登录操作。
• 访问正在使用浏览器控制台会话：当在 Chrome DevTools 网络面板中发现一个失败的网络请求时，可以直接选择该请求并让 AI Coding Agent 进行分析，这种 AI Coding Agent 与 人之间无缝协同的新能力让我感到非常兴奋。

如上的功能主要受益于谷歌 在 Chrome M144（beta）版本中新增的一项远程调试的功能：该功能允许 Chrome DevTools MCP 服务器接受远程调试请求。默认情况下，Chrome 会禁用远程调试连接，可以通过 chrome://inspect#remote-debugging 来启用该功能。

Gemini CLI 控制 Chrome

1.开启远程调试

在 Chrome 中访问 chrome://inspect#remote-debugging 并启用远程调试功能。

2.安装 Chrome DevTools MCP

1

gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest

3.修改配置文件
打开 ~/.gemini/settings.json 文件，修改 chrome-devtools 配置，在 args 中增加 --autoConnect 参数，这样 Gemini 就可以打开你当前正在使用的 Chrome 浏览器。如果不增加 --autoConnect 参数，Gemini 会打开一个新的 Chrome 浏览器实例。

1
2
3
4
5
6
7
8
9

"mcpServers": {
  "chrome-devtools": {
    "command": "npx",
    "args": [
      "chrome-devtools-mcp@latest",
      "--autoConnect"
    ]
  }
}

如果指定 --autoConnect 参数，Chrome DevTools MCP 将自动连接到由 channel 参数标识的、本地运行的 Chrome 浏览器（channel 默认为 stable）。

4.自动连接与授权
当 Gemini 认为需要操作 Chrome 时，Chrome DevTools MCP 会自动检测并连接到正在运行的 Chrome 实例，并弹出一个请求远程调试权限的对话框。用户授权后，Agent 便可获得当前浏览器会话的控制权。此时，浏览器会显示一个“Chrome 正由自动化测试软件控制”的横幅，以提示用户。

打开 github 网站，并进入到我的个人页面。

Gemini Code Assist 利用 Chrome DevTools MCP 操控 Chrome 浏览器的整体的流程如下所示：

sequenceDiagram    participant User as 用户    participant Agent as Gemini Code Assist    participant MCPServer as Chrome DevTools MCP Server    participant Chrome as Chrome 浏览器    User->>Chrome: 启用远程调试 (chrome://inspect)    User->>Agent: "打开 github 网站，并进入到我的个人页面，并分析加载性能"    Agent->>MCPServer: 启动并传入 --autoConnect    MCPServer->>Chrome: 请求连接到活跃会话    Chrome-->>User: 弹出授权对话框    User->>Chrome: 同意授权    Chrome-->>MCPServer: 建立调试会话    MCPServer-->>Agent: "连接已建立，可以开始调试"    Agent->>MCPServer: 调用工具 (例如：network.getRequests)    MCPServer->>Chrome: 通过 CDP 执行指令    Chrome-->>MCPServer: 返回网络请求数据    MCPServer-->>Agent: 返回网络请求数据    Agent->>Agent: 分析数据并定位问题

Chrome DevTools MCP 的优势：

• 复用活跃会话: 这是真正的杀手锏。当你在 Mac 上已经登录了公司内部的复杂集成系统或评测看板时，Agent 可以直接通过 MCP 连入你当前正在使用、带有完整 Cookie 和身份态的浏览器标签页。无需让 AI 去学习如何登录，实现了人类与 Agent 之间调试工作的无缝切换。

• 深达内核的数据获取: 你的 Agent 可以直接调用底层协议，抓取 Network 面板的失败请求、读取 Console 报错日志、查看 Elements 面板的 DOM 树、甚至执行性能审计。这使得 AI 具备了高级前端工程师的排错能力。

• 极简且安全的架构: 不依赖庞大的中间层，且每次连接都会有系统级的安全授权弹窗，非常契合企业对权限隔离的严格要求。

Chrome DevTools MCP 的劣势：

对大模型的逻辑推理和代码编写能力要求极高，因为它操作的不再是直观的 UI，而是底层的 JSON 数据和 JS 运行时。

整体看，Chrome DevTools MCP 配合 AI Coding Agent 是构建大模型自动化评测流水线、进行复杂集群环境调试的首选协议层方案。

不同方式之间的对比

3 月 29 日，OpenClaw 的作者 Peter Steinberger 发了一篇推文，推文中也提到：

The Chrome extension has been removed since Google added native access in 144+, which is simpler, but yes, it does require a one-time setting change.

参考文献

虽然 LLM 的能力现在已经非常强大，但是对于多模态大模型的评测而言，仍然需要进行大量的人工评测工作。所以，我们也会看到，类似 Arena 平台的这种基于人类偏好打分的榜单，依然是我们评估大模型性能的有效参考。

我们参考 LMArena 团队开源的榜单算法 Arena Rank 构建了自己的大模型 Side-by-Side 评测系统，来满足我们对大模型评测的需求。

Side-by-Side 评测系统

与 LMArena 不同，我们 Side-by-Side 评测系统的样本是预先准备好的，而非用户上传。在我们的系统中，我们会把待用户打分的样本组织成一个任务，同时我们会招募打分用户为这个任务打分。

以文生图任务为例，平台的打分过程如下图所示：

当用户打分完成之后，我们会利用 Arena Rank 算法来更新所有模型的评分与榜单信息。

所以，在我们的系统中，一个评测任务的基本流程如下：

graph LR    A[创建评估任务] --> B[发布招募信息]    B --> C[用户报名]    C --> D[创建群聊]    D --> E[群聊中发布任务链接]    E --> F[定期跟进进度]    F --> G[计算 Elo 排序]    style A fill:#f9f9f9,stroke:#333,stroke-width:2px    style B fill:#f9f9f9,stroke:#333,stroke-width:2px    style C fill:#f9f9f9,stroke:#333,stroke-width:2px    style D fill:#f9f9f9,stroke:#333,stroke-width:2px    style E fill:#f9f9f9,stroke:#333,stroke-width:2px    style F fill:#f9f9f9,stroke:#333,stroke-width:2px    style G fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px

在 OpenClaw 出现之前，评测任务的创建、发布、招募、跟进和计算等全流程都需要专人负责。有时候，我们一天也会创建多个评测任务，这个时候负责管理评测任务的同学就会焦头烂额。

在用了一段时间的 OpenClaw 之后，我发现 OpenClaw 具备如下的四大特性，这四大特性让 OpenClaw 非常适合用来管理大模型的评测任务。

• 更强大的记忆能力（跨天级别长程任务）
• 更强大的主机控制能力（系统管理员级别）
• 更强大的交互能力（多端 IM 触达，随时、随地的触达）
• 更强大的 Agent 蜂群能力（多 Agent 协同）

于是，我们心动了，我们决定用技术手段来解决我们评测专员的烦恼，我们决定让 OpenClaw 来管理我们的评测任务。

OpenClaw 的基本能力

这是一个典型的 pipeline skill ^[1]。在开始之前，我们需要梳理 agent 所需的能力以及 OpenClaw 能提供的支持，以便于后续的 skill 开发。

Workspace 文件加载时机

OpenClaw 的行为主要由 workspace 文件而非隐藏的 prompt 文件定义。正确设置 SOUL.md、AGENTS.md、USER.md、MEMORY.md 以及 TOOLS.md 等文件以及了解每个文件的作用及其加载时机，对于实现我们的目标至关重要。

OpenClaw 会在 session 启动的时候去读取 ~/.openclaw/workspace/ 下的相关文件，具体的区别和作用如下所示^[2]：

因此，如果我们想在群聊启动时、或者在群聊中通过 /new 命令创建一个新的群聊 session 的时候，让群聊能够记起之前的内容，那么最好不要把记忆放在 MEMORY.md 文件中。TOOLS.md 文件是一个不错的选择。

跨 session 通信能力

在 OpenClaw 中，默认情况下，所有的 “私聊（DM）” 共用一个“主会话（main session）”，以保证对话的连贯性；而不同的 “群聊（Group）” 或者 “频道” 则会拥有各自的“独立会话（isolated sessions）”。^[3]

如果你的 OpenClaw 可以接收来自多个用户的私信消息，此时，所有用户将共享相同的“主会话”上下文，这会导致用户之间的私人信息泄露，进而带来安全风险。比如我的 OpenClaw 授权给了我的很多同事，他们每天都会和我用同一个 🦞 来私聊并处理工作上的事情，而我不想让其他的同事知道我和 🦞 都聊了什么。

这个时候，就需要使用 session.dmScope 来控制私聊会话的隔离范围，保证不同用户之间的会话隔离。^[3:1]

1
2
3
4
5
6
7

// ~/.openclaw/openclaw.json
{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}

1
2
3
4

* main (default): all DMs share the main session for continuity.
* per-peer: isolate by sender id across channels.
* per-channel-peer: isolate by channel + sender (recommended for multi-user inboxes).
* per-account-channel-peer: isolate by account + channel + sender (recommended for multi-account inboxes). 

当多个私聊和群聊以独立的 session 运行时，如何让这些相互隔离的 session 保持必要的信息互通，就成了一个需要解决的问题。整个评测的过程是在不同的私聊、群聊中不停的切换，没有一定的跨 session 能力，🦞 就会给人一种暂时性失忆的印象。

是的，有时候就是这么矛盾，既要保证信息隔离，又要保证一定的信息互通。

文件读写能力

文件操作的基础是文件路径的访问能力，根据 OpenClaw 的 官方文档：agent 的 workspace 目录就是当前 agent 的默认 CWD，在 agent 的 context 中，所有的 相对路径 均基于 workspace 进行解析。当然，绝对路径可以访问主机的其他位置。^[4][5][6]

OpenClaw uses a single agent workspace directory (agents.defaults.workspace) as the agent’s only working directory (cwd) for tools and context.

The workspace is the default cwd, not a hard sandbox. Tools resolve relative paths against the workspace, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled.

Workspace note: each agent’s workspace is the default cwd, not a hard sandbox. Relative paths resolve inside the workspace, but absolute paths can reach other host locations unless sandboxing is enabled.

这一点非常重要，因为接下来我们在写 skill 的时候，会经常涉及到文件路径的解析问题：

• 在 SKILL.md 中引用其他参考文件；
• 在 SKILL.md 中执行 scripts 路径下的某个脚本；
• ……

从 3.2 版本开始，为解决安全问题，OpenClaw 加强了对工具调用的权限控制。默认情况下，禁止对主机文件系统进行写或执行操作，如需此类权限，要在配置文件中显式授权。^[7]

1
2
3

"tools": {
  "profile": "full"
}

多 Agent 协同能力

整个评估过程核心分为三个阶段：发起任务、跟进状态和销毁任务。虽然单个 Agent 可以完成所有阶段，但拆分为多个 Agent 更易于维护。

• 每次任务都会重新执行 Main Agent，Main Agent 只负责发起任务并生成 Status Agent（跟进任务） 和 Killer Agent（销毁任务）
  • 每一次评估任务都会创建单独的 Status Agent 来跟踪当前的评估任务状态
  • 如果 Killer Agent 已经存在了就不需要重新创建
  • Main Agent 完成任务后就退出了
• Status Agent 和 Killer Agent 会周期性的醒来并执行相应的任务。
• 当 Killer Agent 检测到任务完成时，会终止相应的 Status Agent，以释放资源。

OpenClaw 中的 Cron 即是调度器、更是一个非常强大的 Agent Spawn 工具^[8]。

Cron is the Gateway’s built-in scheduler. It persists jobs, wakes the agent at the right time, and can optionally deliver output back to a chat.

当我们使用 --session isolated 和 --message 创建定时任务时，OpenClaw 会以 --message 指定的内容作为提示词创建一个新的 Agent，并以 --cron 中指定的调度周期定期唤醒该 Agent。

1
2
3
4
5
6

openclaw cron add \
--name "${job-name}" \
--cron "*/3 * * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "${MESSAGE}"

此时，每次定时任务触发，OpenClaw 都会强制生成一个全新的 Session ID（以 cron:<job.id> 作为 Session Key），并且完全不会复用之前的闲置会话，从而避免任务多次执行过程中的上下文污染。

工程实现

长短期记忆分离

整个评估流程是相对固定的、需要长期记住的。但是每个评估任务是一个相对短期的概念，评测任务结束之后，OpenClaw 不需要对这个任务有任何的记忆。在这种场景下：

• 长期记忆是整个业务流程，不依赖任何短期状态
• 短期记忆是任务的状态，当 Status Agent、Killer Agent 唤醒时，需要依赖任务的状态来保持任务的连续性

于是，在我们的设计中：长期记忆以 SKILL.md 的形式存在，而需要在多 sessions/Agents 之间通信的短期任务状态信息，我们放在一个共享文件中——类似多进程架构中的共享内存。

SKILL.md 中详细描述了评测业务流程，并包含了构建 Status Agent 和 Killer Agent 的策略。

于是，整体的目录结构就成了如下的样子：

1
2
3
4
5
6
7
8
9

llm-evals/
├── eval_tasks.json  # 短期的任务状态文件，在 Skill 首次执行时创建
├── SKILL.md # Main Agent
├── status-sub-agent.md  # Status Agent
├── killer-sub-agent.md  # Killer Agent
└── scripts/ # CLIs
    ├── check_eval_progress_tool.py 
    ├── create_im_group_tool.py
    └── trigger_report_tool.py

Main Agent(SKILL.md)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

---
name: llm-evals-skill
description: 当用户提供任务参数时，使用此技能初始化一个新的 LLM 评估任务。它会持久化任务状态、发布招募消息，并创建子代理 sub_agent 执行任务。
---

# LLM 评估代理

## 何时使用
当用户提供新盲测或评估任务的参数时（例如，评估类型、评估链接、目标人数、奖励描述和截止日期），立即触发此技能。**请勿使用此技能来检查进度。**

有关如何创建 *status-sub-agent* 并为其配置 cron 任务的详细信息，请参阅 `./skills/llm-Arena/status-sub-agent.md`。

有关如何创建 *killer-sub-agent* 并为其配置 cron 任务的详细信息，请参阅 `./skills/llm-Arena/killer-sub-agent.md`。

## eval_tasks.json 文件格式
执行此技能时，请确保已从用户提示中提取以下参数：
- `task_id`: 任务的唯一标识符,必填。
- `creator`: 任务的创建人，即用户的用户名，必填。
- `platform_task_id`: 评估平台任务的 ID，例如 `1234567`，可后继更新。
- `status`: 任务状态，`INIT`——任务创建初始化, `RECRUITING`——招募众测用户, `EVALUATING`——评估打分中, `DONE`——任务完成，必填且只能是这 4 项。
……

## 指令

严格按顺序执行以下步骤：
1. **创建 Killer Agent**
  请检查是否存在 `./skills/llm-Arena/llm-Arena/eval_tasks.json` 文件，如果文件不存在，则做如下的操作：
  - 创建一个新的文件 `./skills/llm-Arena/llm-Arena/eval_tasks.json`，其内容为 "{}"
  - 使用 cron 命令创建一个新的 Killer Agent，**openclaw cron 命令** 如下：

   ```bash
      FILE_CONTENT=$(cat "./skills/llm-Arena/killer-sub-agent.md")
      MESSAGE="请严格执行如下任务流程： $FILE_CONTENT"
      openclaw cron add \
      --name "任务名称" \
      --cron "*/3 * * * *" \
      --tz "Asia/Shanghai" \
      --session isolated \
      --message "$MESSAGE"
   ```

2. **持久化任务状态**：
   - 打开本地状态文件 `./skills/llm-Arena/llm-Arena/eval_tasks.json`。
   - 为此 `task_id` 创建一个新的 JSON 对象，不要覆盖之前的对象，要在之前的对象基础上追加一个新的对象。
   - 将初始 `status` 设置为 `"INIT"`。
   - 将必须的输入保存到此对象中。
   - 将更新后的 JSON 安全地写回磁盘。
   - 汇报已经成功持久化此次任务状态文件给任务创建人，即给我发一条创建成功的消息，并给出状态文件内容。

3. **创建 Status Agent**
   - **定时任务创建**
     1. 执行下面 `openclaw cron命令` 创建定时任务，注意，需要把 `task_id` 替换成本次任务的ID。
     # …… <其他的限制条件>

   - **openclaw cron命令**

   ```bash
      FILE_CONTENT=$(cat "./skills/llm-Arena/status-sub-agent.md")
      MESSAGE="当前任务ID 为 task_id, 请为这个任务严格执行如下任务流程： $FILE_CONTENT"
      openclaw cron add \
      --name "任务名称" \
      --cron "*/3 * * * *" \
      --tz "Asia/Shanghai" \
      --session isolated \
      --message "$MESSAGE"
   ```
   - **openclaw cron命令行执行之后的返回信息**
    1. `openclaw cron` 命令如果执行成功后会返回显示类似如下格式的 json 信息：
         ```json
               {
                  "id": "b818d9ca-3cea-48de-805e-2b42c9ae0d60",
                  "name": "test-cron-wukong",
                  "enabled": true,
                  "createdAtMs": 1773210163484,
                  "updatedAtMs": 1773210163484,
                  "schedule": {
                     "kind": "cron",
                     "expr": "0 10 * * *",
                     "tz": "Asia/Shanghai"
                  },
                  "sessionTarget": "isolated",
                  "wakeMode": "now",
                  "payload": {
                     "kind": "agentTurn",
                     "message": "test message"
                  },
                  "delivery": {
                     "mode": "announce",
                     "channel": "last"
                  },
                  "state": {
                     "nextRunAtMs": 1773280800000
                  }
               }
         ```
    2. **关键返回字段说明** id任务唯一ID（后续编辑/删除需要用到, name任务名称, enabled是否启用, createdAtMs创建时间（毫秒时间戳）, schedule调度配置（cron 表达式 + 时区）, sessionTarget运行模式（main 或 isolated）, payload任务内容（message 即你要执行的指令）, delivery交付方式, state.nextRunAtMs下次执行时间。


4. **发布招募消息**：
   - 根据 `theme` 和 `reward_desc` 撰写一条吸引人的招募消息，注意，务必带上本次任务的ID`task_id` 信息。
   - **请勿在消息中包含 `eval_link` 信息**。相反，请指示感兴趣的用户通过回复消息或遵循特定的行动号召来报名。
   - 将此消息发送到 `im_recruit_group_id`。
   - 修改任务状态为 `RECRUITING` 招募中。

## 约束与边界情况
1. **错误反馈**:
   - 如果出现任何失败, 需要立刻通知用户, 并说明失败原因。

eval_tasks 文件

Status Agent

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 评估生命周期心跳

本文档是评测任务生命周期任务 Status Agent 的指导说明文档。
使用本文档作为系统提示词，来控制评测任务的整体生命周期和状态，包括检查报名情况、创建 IM 群组、向待处理用户发送提醒、生成报告。

## 何时使用
维护评测任务的生命周期时需要严格按照本文档指导执行任务。它需要一个 `task_id` 来知道需要推进哪个评估任务的状态机。 所有任务相关的信息都在这个文档中：`./skills/llm-Arena/eval_tasks.json`。

## 指令

1. **读取任务状态**：
   ……

2. **处理 `RECRUITING` 状态**：
   ……

3. **处理 `EVALUATING` 状态**：
   ……

4. **处理 `DONE` 状态**:
   - 保持静默，不再处理任何操作。

## 约束与边界情况
- **幂等性**：切勿多次创建 IM 群组。在创建之前始终验证 `im_sub_group_id` 是否为 null。
- **数据隔离**：确保仅查询和发送消息给与传递给此技能的特定 `task_id` 相关的用户。不要在不同任务之间交叉污染数据。
……

Killer Agent

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Killer Agent

使用本文档来对 Status Agent 任务完成情况进行检测，当 Status Agent 对应的任务完成时，就需要结束对应的 Status Agent 任务。

## 指令

1. **读取任务状态**：
   ……

2. **处理 `DONE` 状态**：
   从 `./skills/llm-Arena/eval_tasks.json` 中提取 `cron_task_id`，使用如下的命令删除对应的 Status Agent 任务。

   ```bash
   openclaw cron rm cron_task_id
   ```

报名消息处理

默认情况下，当用户在群聊中 @OpenClaw 报名时，OpenClaw 会自动回复，这并非理想的交互体验。我们希望它能默默记录报名信息而无需回复。

由于创建任务和招募打分人员是在不同的会话，所以这两个对话的上下文是割裂的，因此如果仅在 SKILL.md 中定义规则（私聊发布任务时加载）无法满足我们的需求。如前所述，我们可以把对应的指令放在 TOOLS.md 文件中：

1
2
3
4
5
6
7
8
9

## LLM 评估任务创建与用户报名处理规范

当用户在群聊中回复"报名"、"+1"或其他表示有空参与的消息时：
1. **不需要回复** - 用户的报名消息不需要回复
2. **判断用户参加的任务id** - 根据上下文对话信息，` 中的以及 `./skills/llm-Arena/eval_tasks.json任务记录，判断用户参加的是哪个任务，用于更新对应任务的记录。
3. **默默更新**
   - 将用户ID以 list 形式写入 `./skills/llm-Arena/eval_tasks.json` 的 `participants` 字段
   - 格式：`"participants": ["user1", "user2"]`
4. **禁止操作** - 禁止修改 `./skills/llm-Arena/eval_tasks.json` 中任何一个任务的 `status` 字段。

最终效果

一句话驱动评测流程，全程不再需要我们的评测专员人工盯盘了。

写好 Skill 真不容易

编写 Skill 比写代码更具挑战，入门虽易，精通却难。

我们在开发如上的 Skill 的时候，其实只花了不到半个小时就写好了最初版本的 Skill，但是调试、优化却花了 3 天多的时间。

调试 Skill 与调试代码不同，过程更为繁琐。代码的语法错误能通过编译立即发现，而 Skill 的逻辑错误则需要更长的反馈路径才能识别，因为即使模型能运行，结果也可能不符合预期。

此外，不同模型对 Skill 的理解和支持粒度各异，导致在某个模型上运行良好的 Skill，在其他模型上可能失效。

因此，调试 Skill 时，不能只关注最终结果，还需仔细检查和分析所有中间过程（如工具调用、执行结果等），以寻找优化空间。

在调试过程中，我们可以利用 OpenClaw 的 WEBUI 查看每次对话的详细信息，以观察其在任务执行过程中的具体行为。

后记

后来，在学习 Anthropic 的 Harness design for long-running application development 时，里面对解决模型所面临的上下文窗口焦虑问题时所提到的方案^[9]：

Context resets—clearing the context window entirely and starting a fresh agent, combined with a structured handoff that carries the previous agent’s state and the next steps—addresses both these issues.
A reset provides a clean slate, at the cost of the handoff artifact having enough state for the next agent to pick up the work cleanly.

这与我们在 Main Agent 中通过 Cron 来定期创建新的 Status Agent 有异曲同工之处。

参考文献

在 我让 OpenClaw 🦞 为我当 OP 这篇文章中，我介绍了我是如何让 OpenClaw 帮我管理服务器集群的。

过了几天，我就开始想搞一点更复杂的事情。既然 OpenClaw 都可以帮我管理服务器集群了，那为什么不能让它帮我部署模型呢？反正我每次部署模型不也是先登录 GPU 服务器，然后在上面执行各种 CLI 操作（下载模型、配置虚拟环境、下载依赖……）？并且每次遇到部署问题时，我也是截个图直接丢给大模型……

调教之旅

于是，我开始了我的调教 OpenClaw 并让它帮我部署模型之旅。整体的体验过程还是非常不错的。

虽然 LLMs 能力对 Linux 命令很熟悉，对模型部署的流程也很熟悉，对部署报错的排查也很熟悉……但是它对我服务器集群的细节并不熟悉。

于是我先开始告诉 OpenClaw 我的服务器集群的细节，包括：

• 如何在远程服务器上执行命令
• 服务器的初始环境配置都有哪些：比如 Conda 配置、网络代理配置、可用的 vllm 环境……

但是，在告诉它这些信息的时候，我没有把这些信息一股脑直接丢给 OpenClaw，我讨厌“填鸭式”教学，我也不想我的 🦞 接受这种方式的知识灌输。

1. 我先从一个问题开始了我的调教之旅：

1

给你一台 8 卡的 A100 机器，你会部署一个 qwen3.5 的模型吗？

你看，虽然我给他的输入还有错别字，但是它已经可以理解我的意思了，并且开始尝试回答了。然后它根据自己的知识，给了我一个部署流程。

2. 输入服务器知识，让 🦞 优化部署步骤：

1
2
3
4
5

1. 机器上是多人共用的，所以为了避免影响其他人，我们用conda工具为每个带部署的模型提供一个conda 虚拟环境。
2. 我们采用vllm的方式来部署模型。
3. 模型文件，我们采用modelscope下载到本地的方式，下载根路径统一放在 /home/work/models/ 中。

请根据这些信息重新整理一下模型部署的步骤。

3. 在执行中提供更多信息：
部署流程对不对，得执行一下才知道，然后我让 OpenClaw 去目标服务器执行它写的部署流程，然后我再根据执行的结果不听的告诉它其他的额外信息。

就像下面要讲到的端口占用的问题一样，OpenClaw 自己就可以解决掉，根本不需要我多嘴。

就这样，经过几次尝试，大概 30 分钟之后，OpenClaw 就在和我的聊天中，帮我把 QWen3.5-0.8B 部署到了我的服务器。而我在整个过程中，除了和 OpenClaw 聊天外，我什么也没做。我没有登录我的服务器，我也没有手写任何的命令，连部署之后的服务可用性测试都是 OpenClaw 帮我做的。

沉淀成 Skill

虽然我的 🦞 又获得了一项新技能，但是对于没有经过类似调教的 OpenClaw 来说，再经过一次类似的过程还是比较麻烦的。如果能把模型部署的 SOP 沉淀为 Skill，别的 🦞 挂载上这个 Skill，就会即刻拥有模型部署的能力。

在 MCP is dead. Long live the CLI 这篇文章中，作者提到：

The best tools are the ones that work for both humans and machines. CLIs have had decades of design iteration. They’re composable, debuggable, and they piggyback on auth systems that already exist.

MCP tried to build a better abstraction. Turns out we already had a pretty good one.

我们已经看到，越来越多的框架或者产品都开始弃用 MCP 转而支持 CLI：

• OpenClaw 不支持 MCP
• Pi 也不支持 MCP
• 甚至连卖 MCP 服务器的 Perplexity 也不再支持 MCP

3月11日，Perplexity 的联合创始人兼 CTO Denis Yarats 在自家开发者大会上说，公司内部已经不用 MCP 了，转向了 API 和 CLI。

所以，在我和 OpenClaw 的聊天过程中，我就让他把部署的流程写成了一个 shell 脚本，实际执行部署时执行的就是那个部署脚本。于是，当我让 OpenClaw 根据聊天内容生成模型部署 Skill 时，生成的 Skill 本就是一个 业务流说明 + CLI 的组合。

我也不想给他一系列的接口文档和命令说明，让他在运行时实时写代码并执行，而是直接给他一个它自己写的 CLI 脚本，让它直接执行。这样，可控性和稳定性会更高。

于是，我让 OpenClaw 帮我生成了一个模型部署的 Skill：

1
2
3

你能把刚才咱们的过程整理成一个模型部署的skill吗？
把shell作为改shell的一个脚本文件。
把整理好的skill放在/home/work/wangwei17/model-deploy目录

并且，很快，OpenClaw 就生成了一个模型部署的 Skill：

我稍加修改，就得到了一个可以直接使用的模型部署的 Skill——model-deploy。

备注：该 Skill 在 MiniMax-M2.5 上测试通过，可以点击 链接 获取该 Skill 的代码。或者使用 clawhub search model-deploy、clawhub install model-deploy 来安装该 Skill。

我把该 Skill 挂载到我的 OpenClaw 实例上，然后让它帮我部署模型。为了避免大模型使用 Session 会话中的对话历史获取知识，而没有从 model-deploy 技能获取知识，我首先用 /new 指令创建了一个新的对话 Session。

🦞 能够知道它可以用 model-deploy 技能来部署模型，并且当部署过程中遇到 GPU 内存不足时，他还会问我怎么处理……
整个过程，除了给 🦞 发布部署任务外，我就只和它通信了一次：告诉他在卡 2 上部署，仅此而已。

思考与总结

当然，model-deploy 这个 Skill 并不是完美的，它只能在 vLLM 推理引擎上部署 Qwen 系模型，但是这已经是一个非常有趣的开端了。

只能控制一台服务器的 🦞 再厉害也仅仅是一个玩具。链接即智能，当 🦞 可以控制更大规模的集群的时候，它才能释放出无限的潜能，给与我们更大的想象空间。

实践之后我发现：Skill 是看起来简单，但是要写好是一件非常难的事情。虽然，我在文章中说：

我稍加修改，就得到了一个可以直接使用的模型部署的 Skill。

但是，说实话，我还是花了一些时间来修改这个 Skill 的，并没有像我说的那样那么轻松、简单。

另外，这个 Skill 我也仅仅在 MiniMax-M2.5 模型上测试通过，还没有在更大范围的模型上测试，有可能换个模型该 Skill 就不能用了。

所以，如何构建出一个可用的、稳健的、好用的 Skill 是一个值得深入探讨的问题，还需要做更多的尝试。正如谷歌在 SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks 中发现的那样：

our evaluation yields four key findings:
(1) curated Skills provide substantial but variable benefit (+16.2 percentage points average, with high variance across domains and configurations);
(2) self-generated Skills provide negligible or negative benefit (–1.3pp average), demonstrating that effective Skills require human-curated domain expertise;

正如我在 为 OpneClaw 增加 Browser 工具 中提到的那样：

在整个的部署过程中，遇到了太多的坑，每遇到一个坑，我就让 Gemini 帮我解决。

突然，我意识到：目前 LLMs 对于 Linux 系统的理解应该比人类要强得多，对 Linux 系统的各种命令操作也应该比人类要强得多。

既然如此，为什么不让 OpenClaw 帮我解决 Linux 系统的运维呢？恰好，我有一个 3 台机器的小集群，每天都要登录上去做一些手工操作，我不想再这样继续下去了。我想做出一些改变，于是，我决定让 OpenClaw 来当 OP，帮我管理集群。我要做的就是：通过 IM 下发指令。

1. 搭建集群

说干就干，LFG，🦞。

于是，我又找了一台机器作为 Manager Node，并且在 Manager Node 安装了 OpenClaw。然后，我为我的 IM 配置了 OpenClaw 的 Webhook，这样，我就可以通过 IM 发送指令给 OpenClaw。最后，通过 ssh-copy-id 命令，在 Manager Node 上配置了 Worker Node 的免密登录。

于是，我的 🦞 看起来是如下的样子：

现在，我们可以让 🦞 帮我管理集群了，比如我要查看 Node-1 机器的 CPU 负载信息，🦞 就会在 Manager Node 上执行如下的命令，并返回结果。

1

ssh user@Node-1 "uptime"

2. 告诉 🦞 如何管理集群

我希望 🦞 可以知道它现在可以管理的机器列表，并且当有新的机器节点加入集群时，🦞 也能够知道如何处理新增加的机器。于是，我通过 IM 把这些知识以聊天的方式告诉了它：

1
2
3
4
5
6

悟空，你现在可以在受信任的机器上通过给定账号执行命令，从而实现集群管理的目的。
但是现在有个问题：别人不知道究竟有那些收信任的机器可以管理，
所以你需要通过配置的方式把受信任的机器和账号以username:host的格式存储起来。
当别人问你类似：你可以管理哪些机器的时候，你就从这个配置里告诉他就可以。
当别人让你在某个 host 上执行命令时，如果不提供 username，那么就默认用配置中的配置的用户执行。
把这些内容存入你的记忆中，永远记下来。

看起来，一起都非常的完美。现在，🦞 已经知道如何管理集群了，同时它也确实具备了管理集群所需要的所有的能力了。

3. 测试 🦞 的集群管理能力

现在，我想知道我的集群中的机器的负载情况。之前，我必须登录到每台机器上，然后执行 uptime 命令。好麻烦。即便是在中控机执行命令，我也得手动写命令。

现在，我不需要登机器、甚至不需要登中控机，我只需要打开 IM 并告诉 🦞：

查看下这三台机器的cpu负载，并进行对比分析。务必简要，可以用表格来呈现。

就可以了，剩下的所有的事情，🦞 都会自动完成。

4. 安全风险的思考

赋予 AI root 权限，是一件便利但是却极其危险的事情。就像 Elon Musk 的 推文 中描述的那样：

Giving people agentic AI be like …

在实践中，当 OpenClaw 为我们提供便利的同时，我们必须严格控制安全风险，务必采用最小权限原则：
绝对不要直接让 OpenClaw 使用 root 权限，更高级别的权限，必须掌控在我们自己手中。创建一个专用的 openclaw_ops 用户，只赋予其执行特定运维命令的 sudo 权限。尤其是对于像 rm -rf / 这样的毁灭性命令，必须物理禁止。

好在是，我们总会有办法来控制 OpenClaw 的权限，只要我们想这样做。

5. 理想的未来

3 台机器的集群虽小，但它却验证了一个宏大的架构路径。基于 GitOps 和 Agentic Memory 的理念，我们完全可以对未来做进一步的畅想：

• 分布式联邦记忆（Distributed Federated Memory）：
  在更大的团队中，可以有多个 OpenClaw 实例在不同的数据中心或业务集群中工作。它们可以通过 GitOps 架构，定期将自己的本地记忆 Push 到同一个中央 Git 仓库，并 Pull 其他 Agent 的新记忆。通过大模型的 语义融合（Semantic Fusion） 能力，实现整个组织经验的全局共享和异地演进。

• 从 Passive Ops 到 Proactive Ops：
  未来的 OpenClaw 将不再是被动等待指令或告警，而是可以通过连接 Prometheus 等监控系统实时分析性能趋势。在磁盘空间即将耗尽前，它能主动根据沉淀的 SOP 执行无害日志清理；在业务高峰来临时，它能自动根据历史经验执行云端扩容操作……

• 沉淀团队真正的灵魂：
  服务器硬件和模型肉体都是暂时的，唯有在一次次碰撞和纠错中沉淀下来的版本化知识，才是个人、团队、组织的灵魂。当新成员加入团队时，他们不再需要翻阅过时的文档，只需要坐在 OpenClaw 旁边，OpenClaw 会带着团队所有的历史经验，辅助他完成新的任务。

在 OpenClaw 初体验 中，我在阿里云的 ECS 主机上部署了 OpenClaw，并用它做了些初步的尝试。有时候，可能想浏览某些网页，但是这些网页在手机上的浏览体验又不好，所以此时就可以通过 IM 软件让 OpenClaw 调用 Chrome 浏览器来帮我们打开页面并截图。

我想每天上班的时候扫一眼 Github Trending 的内容（我在手机上没法直接访问这个页面，当然也有方法，但是我嫌麻烦），这个时候就可以通过 OpenClaw 调用 Chrome 浏览器来打开这个页面并截图发给我了。

在纯净的 Ubuntu 22.04 云主机上以 root 用户安装 Chrome 浏览器并配置 OpenClaw 时，我遇到了不少的坑。本文将详细记录在云主机上从零配置 OpenClaw + Chrome 环境的全过程，避免大家遇到那些让人抓狂的“权限坑”。

1. Chrome 安装避坑

我在 Ubuntu 22.04 上安装 Chrome 时最开始的方式是执行：apt install chromium-browser。务必立刻停止这个操作！

deb to snap transition：

• 从 Ubuntu 19.10 开始，Canonical 将 chromium-browser 做成了过渡包（transitional package），该包并不包含真正的 DEB 程序，仅包含包装脚本、桌面文件和依赖声明，并明确依赖 snapd 和 chromium Snap 包。^[1]

• 因此 apt install chromium-browser 命令安装的 Chrome 实际上是 Snap 版本的 Chrome。若系统未安装 snapd，该过渡包会先通过 apt 安装 snapd，再从 Snap Store 拉取 Chromium。

而 Snap 拥有极其严苛的 AppArmor 沙箱隔离^[2]，其默认规则就是：禁止访问任何系统敏感目录和其他用户目录。/root 目录是超级用户目录，属于最高敏感路径，因此，AppArmor 会直接拦截对其目录下的文件访问请求^[3]：

• 读：deny
• 写：deny
• 执行：deny
• 列出文件：deny

2. 配置 OpenClaw

安装完 Chrome 浏览器后，必须在 OpenClaw 的网关配置中为 Browser 工具开放权限，并解决云主机 root 运行的核心安全冲突。

2.1 开启 browser 工具权限

OpenClaw 从 3.2 版本开始对工具调用实施了更严格的权限控制，从而希望有效解决饱受诟病的安全问题。针对工具调用的安全控制能力，OpenClaw 3.2 版本增加了：精细化的工具访问控制、执行环境隔离、运行时行为约束等安全策略^[4]。

另外，根据 OpenClaw 官方文档的描述^[5]：

OpenClaw can run a dedicated Chrome/Brave/Edge/Chromium profile that the agent controls.
It is isolated from your personal browser and is managed through a small local control service inside the Gateway (loopback only).

OpenClaw 支持在 openclaw.json 中通过 tools.allow、tools.deny 全局配置工具的黑白名单，并且黑名单优先级高于白名单，从而阻止没有权限的工具发送给模型，进而避免无权限的工具的执行。

因此，需要首先在全局配置文件 ~/.openclaw/openclaw.json 中把 browser 工具加入白名单：

1
2
3
4
5
6
7
8
9

{
  "agents": {
    "defaults": {
      "tools": {
        "allow": ["exec", "shell", "browser", "web_fetch"] 
      }
    }
  }
}

2.2 关闭沙箱（No-Sandbox）限制

沙箱是 Chrome 的核心安全机制。当 Chrome 打开一个网页时，它会把网页里的 HTML 渲染、JavaScript 执行等操作，全都关进一个“隔离的 Sandbox” 里运行。^[6]

而在 Linux 的世界中，root 是拥有绝对权限的超级用户，如果以 root 身份运行 Chrome，这就产生了一个巨大的安全悖论：

沙箱的存在是为了限制权限，但 root 账号却偏偏拥有无限权限

因此，在 Chrome 中，有一条硬性规定：检测到当前用户是 root 账号时，浏览器会直接退出，绝不在 root 下带着沙箱运行，没有意义。^[7]

Running as root without --no-sandbox is not supported.

但是对于 docker 容器来说，容器已经对安全性做了控制与隔离，因此在容器内以 root 用户运行 Chrome 是没有问题的。此时可以使用 --no-sandbox 参数来关闭沙箱，从而以 root 用户身份运行 Chrome。

同样的，当在 root 账号下用 OpenClaw 控制浏览器时，也必须在 OpenClaw 配置中显式关闭沙箱限制：

1

openclaw config set browser.noSandbox true

2.3 重启网关

配置完成后，重启 OpenClaw 网关服务：

1

openclaw gateway restart

3. snapshot 与 screenshot

可以用如下的命令来验证浏览器工具是否可用：

1
2
3
4

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://www.baidu.com
openclaw browser --browser-profile openclaw snapshot

• Snapshot 提取结构化文本：如果需要提取页面的可读内容，我们可以执行 snapshot 动作。这个操作会返回当前网页完整的 HTML 字符串、JSON 格式的 DOM 树结构，非常适合让 LLM 对其进行总结与分析。

  1	openclaw browser --browser-profile openclaw snapshot

• Screenshot 截取视觉画面：如果需要真实的网页截图，需要执行 screenshot 动作。该动作会在底层执行截屏，并返回一个包含媒体路径的图像块（image block + MEDIA:）。执行命令后，控制台会返回图片在服务器上的绝对路径，我们可以通过 cp 命令将其拷贝并下载查看。

  1	openclaw browser --browser-profile openclaw screenshot

参考文献

2026 年初，除了基础大模型争相斗艳之外，在技术圈，一个名叫 OpenClaw 的 个人 AI 助手火出了天际，引爆了新一轮的 Agent 热潮。OpenClaw 的核心理念是让 AI 直接接管系统的读写与执行权限，并通过 Telegram、Discord 或 WhatsApp 等 IM 软件接收自然语言指令，然后再服务器上自动执行代码编写、文件管理、收发邮件等任务。通过 IM 软件下达任务，OpenClaw 会自己分析任务，然后自动执行任务，并返回执行结果。这才是我们一直在苦苦追求的 AI 个人助理。

1. 什么是 OpenClaw

OpenClaw 是奥地利程序员 Peter Steinberger 在 2025 年 11 月发布的开源项目。项目的最初命名为 Clawdbot，是一个能连通各种 API 和本地 Shell 的轻量级对话机器人原型。2026 年 1 月，Clawbot 在 GitHub 上突然爆火出圈，同时也顺便带火了 Mac mini，甚至有用户一口气买了 40 台 Mac mini，全部用来运行 Clawdbot。

就在 Clawdbot 爆发式增长的时候，Peter 收到了 Anthropic 的律师函：因为 Clawdbot 与 Anthropic 的大语言模型 Claude 太像，因此涉嫌商标侵权。2026 年 1 月 27 日，Peter 在 Discord 频道里召集社区成员进行头脑风暴，并最终为项目改名为 Moltbot。

3 天后，Peter 觉得 Moltbot 读音感觉像是嘴里含了块石头，同时为了彻底规避未来的版权争议并彰显开源和自由的属性，再次为项目更名为 OpenClaw 并沿用至今。改名后的 OpenClaw 像火箭一样起飞：

• 1 月底：2K GitHub stars
• 2 月初：突破 100K stars
• 2 月中旬：突破 180K stars
• 2 月底：突破 200K stars

2 月 4 日，Founder Park 搞了一场闭门活动，聚集了 130 多位 AI 创业者，来自 AI 游戏、AI Coding、Agent Memory、AI 硬件、AI 语音等不同赛道，分享了他们在上手用 Clawdbot 的感受和思考。^[1]

Clawdbot 带来了一些和聊天不一样的「增量」。它的本质，是为你配了一台「云电脑」。第一次可以真正地指挥一个 AI 去增、删、改、查文件。这让 AI 从一个信息工具，变成了一个执行工具。

2 月 14 日，Peter 宣布加入 OpenAI，领导“下一代个人代理”的开发，OpenClaw 则转由开源基金会维护，确保项目永远自由和独立。^[2]

直到今天，OpenClaw 的热度依然不减：在 Google Trends 上，搜索趋势热度依然在 60 以上；微信公众号上关于 OpenClaw 的文章也多如牛毛。

即便如此，我想，依然有非常多的人和我一样，对 OpenClaw 的了解和认知还主要在别人的讨论中，依然没有亲自上手、真正体验。纸上得来终觉浅，绝知此事要躬行。

于是，在春节前的几天，我花了一些时间，亲自上手部署了 OpenClaw，并记录下了整个体验过程。

2. 为什么选择 ECS

1. 首先，我个人并不喜欢云厂商提供的一键部署服务，相反，我更喜欢在一台干净的服务器上，从零开始搭建自己的环境。
2. 其次，在 在阿里云上部署 Vui 语音模型 这篇文章中，我介绍了我在阿里云的 PAI-DSW 上部署 Vui 模型的经验，那时我就被阿里云的使用体验所折服。
3. 然后，对于新用户而言，阿里云提供了 价值 300 元的免费 ECS 额度。
4. 最后，阿里旗下的钉钉机器人已经有 Channel 插件支持通过钉钉和 OpenClaw 交互。

因此，当我决定要亲自体验一下 OpenClaw 的时候，我选择了阿里云的 ECS。

3. 在 ECS 上部署 OpenClaw

3.1 申请 ECS 主机

根据自己的需求选择合适的 ECS 实例配置，我选择了 2 核 4G 的 Ubuntu 22.04 作为 ECS 实例，在创建 ECS 实例时，阿里云会提供对应的公网 IP，这极大方便了后续的部署和访问。

点击 远程链接 按钮，可以配置登录方式，我选择使用 SSH 密钥对登录并设置了登录的 root 密码。通过提供的公网 IP 和设置的密码，就可以通过 SSH 登录到 ECS 实例了。

3.2 配置 ECS 的安全组

OpenClaw 运行依赖两个核心端口——18789 和 80：

• 18789 端口为网关通信与控制界面访问端口
• 80 端口用于部分 IM 平台的回调通信

因此，为了保障 OpenClaw 的可用性，ECS 主机启动后，需要在 网络与安全组 中对这两个端口进行配置，避免因端口拦截导致服务不可用。

3.3 安装 Node 环境

1
2

snap install node --classic
npm config set registry https://registry.npmmirror.com

3.4 安装 OpenClaw

根据 OpenClaw 官方文档 安装 OpenClaw：

1
2

npm install -g openclaw@latest
openclaw onboard --install-daemon

向导程序 会安装 OpenClaw 的网关守护进程（launchd/systemd 用户服务），并使其保持运行状态。在安装过程中，向导程序 会让我们配置各种参数：例如 IM 平台、所用的大模型、安装的插件……根据自己的需求进行配置即可。

安装完成之后，可以通过 openclaw status 查看 OpenClaw 的运行状态。

3.5 配置 SSH 本地端口转发

为了方便本地访问 OpenClaw 的控制界面，可以通过 SSH 的本地端口转发功能，将 ECS 实例的 18789 端口转发到本地。

1

ssh -L 18789:localhost127.0.0.1:18789 root@<ECS公网IP>

3.6 配置大模型

在阿里云的百炼平台申请对应模型的 API-KEY，在 openclaw.json 中增加大模型配置。

1.在 models 字段中增加大模型配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

"models": {
  "providers": {
    "alibaba-cloud": {
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "apiKey": "<your-api-key>",
      "api": "openai-completions",
      "models": [
        {
          "id": "qwen3-coder-plus",
          "name": "Qwen Coder",
          "reasoning": false,
          "input": [
            "text"
          ],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        },
        {
          "id": "qwen3-vl-plus",
          "name": "Qwen Vision",
          "reasoning": false,
          "input": [
            "text",
            "image"
          ],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

2.在 agents 字段中增加大模型配置：

1
2
3
4
5
6
7
8
9
10
11
12
13

"agents": {
  "defaults": {
    "model": {
      "primary": "alibaba-cloud/qwen3-coder-plus"
    },
    "models": {
      "alibaba-cloud/qwen3-coder-plus": {
        "alias": "qwen"
      },
      "alibaba-cloud/qwen3-vl-plus": {}
    },
  }
}

3.7 配置钉钉机器人

根据 阿里云 ECS 云服务器部署OpenClaw（Clawdbot）详细步骤流程 中的 钉钉对接流程 部分创建钉钉机器人并进行配置。

根据 openclaw-channel-dingtalk 中的说明安装 DingTalk Channel 插件，并重启 OpenClaw 服务。

1