Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
refactor: 统一第六至十一讲语调,去除"而不是/而是"句式,改为教材式直接叙述
sanbuphy6bfd2332becf
diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdindex 6245079..a89ca57 100644--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -5,11 +5,11 @@# 第六讲. 让 agent 每次工作前先初始化-你开了一个新的 agent 会话,让它"帮我加个搜索功能"。它上来就开始改代码,精神可嘉。改了 20 分钟发现测试框架没配好,又花 10 分钟搞测试框架,然后发现数据库迁移脚本格式不对,又折腾了一会儿。最后搜索功能倒是加了,但整个会话的效率很低,大部分时间花在了"搞清楚这个项目怎么运作"上,而不是写搜索功能本身。+在使用 AI 编码 agent 时,一个常见的低效模式是:让 agent 直接开始做功能,它上来就写代码,但很快会发现测试框架没配好、环境有问题、项目结构不清晰,大量时间花在了"搞清楚这个项目怎么运作"上面,真正用于写功能的时间反而很少。-更好的做法是,在让 agent 开始干活之前,先用一个独立的阶段把基础环境搭好、验证命令跑通、项目结构搞清楚。初始化工作不应该和功能实现挤在一起,它们是两种性质完全不同的任务。+更好的做法是,在让 agent 开始干活之前,先用一个独立的阶段把基础环境搭好、验证命令跑通、项目结构搞清楚。初始化工作应该和功能实现分开,它们是两种性质完全不同的任务。-这节课要讨论的就是,为什么初始化必须是独立的阶段,不能跟实现混在一起。+这节课要讨论的,就是为什么初始化必须是独立的阶段,不能跟实现混在一起。## 两种不同的工作@@ -111,7 +111,7 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"**热启动策略**:不要从空目录开始。用一个项目模板(create-react-app、fastapi-template 等)预置好标准的目录结构、依赖配置和测试框架。把通用的初始化步骤预置到模板里,只留下项目特有的初始化工作。-**初始化的完成条件**:不是"写了多少代码",而是启动就绪清单的四个条件都满足了:能启动、能测试、能看进度、能接手下一步。用这个检查清单验收初始化:+**初始化的完成条件**:启动就绪清单的四个条件全部满足——能启动、能测试、能看进度、能接手下一步。用这个检查清单验收初始化:```markdown## 初始化验收清单@@ -135,10 +135,10 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"## 核心要点- 初始化和实现的优化目标不同,混在一起只会互相拖后腿。-- 初始化的产出不是业务代码,而是基础设施:可运行的环境、可验证的测试、启动就绪清单、任务分解。+- 初始化的产出是基础设施:可运行的环境、可验证的测试、启动就绪清单、任务分解。- 用"启动就绪清单"的四个条件验收初始化:能启动、能测试、能看进度、能接手下一步。- 热启动优于冷启动,用项目模板预置标准化的基础设施。-- 初始化投入的时间会在后续 3-4 个会话中完全收回,这不是额外的成本,而是前期投资。+- 初始化投入的时间会在后续 3-4 个会话中完全收回,这是前期投资,不是额外成本。## 延伸阅读diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdindex 6035d95..792f7fe 100644--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -5,15 +5,15 @@# 第七讲. 给 agent 划清每次任务的边界-你让 Claude Code "给这个项目加上用户认证功能",结果它同时开始改数据库 schema、写路由、改前端组件,还顺手重构了错误处理中间件。两个小时后一看,12 个文件被修改,800 行新代码,但没有一个功能是端到端跑通的。+Agent 经常会越界,同时做太多事情。在一个典型场景中,你让它给项目加上用户认证功能,结果它同时开始改数据库 schema、写路由、改前端组件,还顺手重构了错误处理中间件。两个小时后一看,12 个文件被修改,800 行新代码,但没有一个功能是端到端跑通的。Agent 天生就有"多做一点"的冲动:看到相关的事情就顺手一起做了。问题是,同时做太多事情,结果往往每一件都做不好。-Anthropic 在 "Effective harnesses for long-running agents" 工程博客中明确指出:当提示太宽泛时,agent 倾向于"同时启动多件事"而非"先做完一件事"。OpenAI 在 Codex 工程实践中也发现,没有显式范围控制的任务,完成率会暴跌。这不是模型的问题,而是你没有在 harness 里给它划清边界。+Anthropic 在 "Effective harnesses for long-running agents" 工程博客中明确指出:当提示太宽泛时,agent 倾向于"同时启动多件事"而非"先做完一件事"。OpenAI 在 Codex 工程实践中也发现,没有显式范围控制的任务,完成率会暴跌。这本质上是一个 harness 设计问题:没有给 agent 划清边界。## 注意力是有限的资源-这不是比喻,是数学。假设 agent 的上下文容量为 C,同时激活 k 个任务,每个任务平均获得 C/k 的推理资源。当 C/k 低于完成单个任务所需的最小阈值时,所有任务都做不完。+这本质上是一个数学问题。假设 agent 的上下文容量为 C,同时激活 k 个任务,每个任务平均获得 C/k 的推理资源。当 C/k 低于完成单个任务所需的最小阈值时,所有任务都做不完。Claude Code 的真实行为很说明问题。你让它"添加用户注册功能",它很可能这样做:@@ -52,7 +52,7 @@ flowchart TB## 核心概念-- **过度延伸(Overreach)**:agent 在一次会话中激活的任务数量超过最优值。这不是主观判断,而是可以量化的:同时做 5 个功能但 0 个跑通,就是 overreach。+- **过度延伸(Overreach)**:agent 在一次会话中激活的任务数量超过最优值。这是可以量化的:同时做 5 个功能但 0 个跑通,就是 overreach。- **不足完成(Under-finish)**:已启动的任务中,通过端到端验证的比例低于阈值。写了代码但没跑通测试,就是 under-finish。- **WIP 限制(Work-in-Progress Limit)**:来自 Kanban 方法论,核心思想是限制同时在进行的任务数量。对于 agent,WIP=1 是最安全的默认值,做完一个再做下一个。- **完成证据(Completion Evidence)**:一个任务从"进行中"变成"已完成"必须满足的可验证条件。没有这个,agent 会用"代码看起来没问题"代替"行为通过测试"。@@ -61,7 +61,7 @@ flowchart TB## Overreach 和 Under-finish 是一对难兄难弟-这两个问题不是独立的,而是互相加剧。overreach 导致注意力分散,注意力分散导致 under-finish,under-finish 留下的半成品代码又增加了系统复杂度,进一步导致下一个任务的 overreach,形成恶性循环。+这两个问题互相加剧。overreach 导致注意力分散,注意力分散导致 under-finish,under-finish 留下的半成品代码又增加了系统复杂度,进一步导致下一个任务的 overreach,形成恶性循环。用 Kanban 的语言说:Little 法则告诉我们 L = lambda * W。如果在制品数量 L 过大(同时做太多事),每个任务的前置时间 W 必然增加。对 agent 来说,这意味着每个功能从开始到验证通过的时间被拉长,失败概率被放大。@@ -82,7 +82,7 @@ flowchart TB### 2. 给每个任务定义显式的完成证据-完成不是"代码写完了",而是"行为验证通过了"。在你的功能列表里,每个条目都要有验证命令:+完成指的是"行为验证通过了"。在你的功能列表里,每个条目都要有验证命令:```F01: 用户注册diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdindex 5622a7a..a73f20d 100644--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -5,9 +5,9 @@# 第八讲. 用功能清单约束 agent 该做什么-你让 agent 做一个电商网站,跑完之后它告诉你"做完了"。你打开代码一看,用户认证有了,但购物车的结算按钮点了没反应,支付流程根本没接上。问题出在哪?你从来没告诉它"做完"的标准是什么,所以它用自己的标准来判断,"代码写了不少,看起来挺完整"。+一个常见的场景:让 agent 做一个电商网站,跑完之后它告诉你"做完了"。但你打开代码一看,用户认证有了,但购物车的结算按钮点了没反应,支付流程根本没接上。问题的根源在于:没有告诉过它"做完"的具体标准,所以它用自己的标准来判断——"代码写了不少,看起来挺完整"。-功能清单(feature list)在很多人眼里就是个备忘录,写下来怕忘了,写完扔在一边。但在 harness 的世界里,功能清单不是给人看的备忘录,而是整个 harness 的基础结构。调度器靠它选任务,验证器靠它判完成,交接器靠它生成报告。没有它,这些组件就没有可以依赖的共识。+功能清单(feature list)在很多人眼里就是个备忘录,写下来怕忘了,写完扔在一边。但在 harness 的世界里,功能清单是整个 harness 的基础结构。调度器靠它选任务,验证器靠它判完成,交接器靠它生成报告。没有它,这些组件就没有可以依赖的共识。Anthropic 和 OpenAI 都强调:**工件必须外部化**。功能状态必须是仓库里机器可读的文件,不能是对话里的非结构化描述。@@ -54,7 +54,7 @@ flowchart LR## 核心概念-- **功能清单是 harness 原语**:它不是"可选的规划工具",而是其他所有 harness 组件依赖的基础数据结构。调度器、验证器、交接器都要读取它才能工作。+- **功能清单是 harness 原语**:它是所有 harness 组件依赖的基础数据结构。调度器、验证器、交接器都要读取它才能工作。- **三元组结构**:每个功能项包含三个要素:`(行为描述, 验证命令, 当前状态)`。行为描述告诉 agent 做什么,验证命令告诉它怎么算做完,状态告诉它现在到哪了。缺了任何一项,这个功能项就不完整。- **状态机模型**:每个功能项有四种状态:`not_started`、`active`、`blocked`、`passing`。状态转移由 harness 控制,不是 agent 想改就能改。- **通过状态门控**:功能从 `active` 变成 `passing` 的唯一方式是验证命令执行成功。这个转移是不可逆的,`passing` 了就不能退回去。diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdindex d6bd486..b235714 100644--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -5,9 +5,9 @@# 第九讲. 防止 agent 提前宣告完成-你让 agent 实现"密码重置"功能。它改了数据库 schema、写了 API 端点、加了邮件模板,跑了单元测试全部通过,然后自信地告诉你"做完了"。你实际一跑才发现:密码重置链接发不出去,邮件服务配置缺失;数据库迁移半途失败,schema 不一致;端到端流程根本没走过一遍。+Agent 有一个系统性倾向:过早宣称任务完成。举例来说,你让它实现"密码重置"功能,它改了数据库 schema、写了 API 端点、加了邮件模板,跑了单元测试全部通过,然后告诉你"做完了"。但实际一跑才发现:密码重置链接发不出去,邮件服务配置缺失;数据库迁移半途失败,schema 不一致;端到端流程根本没走过一遍。-这不是偶然事件。Guo 等人 2017 年在 ICML 上的经典论文证明:**现代神经网络系统性地过度自信**,模型自报的置信度显著高于实际准确率。AI 编码 agent 也一样,它"觉得"做完了,但实际上差得远。你的 harness 必须用外部化的、基于执行的验证来替代 agent 的"感觉"。+Guo 等人 2017 年在 ICML 上的经典论文证明:**现代神经网络系统性地过度自信**,模型自报的置信度显著高于实际准确率。AI 编码 agent 也一样,它"觉得"做完了,但实际上差得远。harness 必须用外部化的、基于执行的验证来替代 agent 的"感觉"。## 滑坡效应@@ -99,7 +99,7 @@ Anthropic 在 2026 年的研究中发现了一个更深层的失败模式:**### 3. 给 agent 提供可操作的错误反馈-OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写的错误消息要包含修复指导**。不要只告诉它"错了",而是明确指出哪里错了、应该怎么改。不要用 `"Test failed"`,而用 `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` 这种具体的、可操作的反馈让 agent 能自我修正,而不需要人类介入。+OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写的错误消息要包含修复指导**。要明确指出哪里错了、应该怎么改,不要只说"错了"。 例如不要用 `"Test failed"`,而用 `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` 这种具体的、可操作的反馈让 agent 能自我修正,不需要人类介入。### 4. 捕获运行时信号@@ -124,7 +124,7 @@ OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写- **agent 系统性地过度自信**,置信度校准偏差是客观存在的。代码写完了不代表做对了。- **完成判定必须外部化**,harness 独立验证,不信任 agent 的"感觉"。- **三层校验缺一不可**:语法通过、行为通过、系统通过,层层递进。-- **错误消息要包含具体修复步骤**,让 agent 能自我修正,而不是只告诉它"错了"。+- **错误消息要包含具体修复步骤**,让 agent 能自我修正,只说"错了"不够。- **核心功能验证通过之前不许重构**,完成优先级约束是防止过早优化的关键。## 延伸阅读diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdindex ba68713..d869f0d 100644--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -5,7 +5,7 @@# 第十讲. 跑通完整流程才算真正验证-你让 agent 给 Electron 应用加一个文件导出功能。它写了渲染进程组件、预加载脚本、服务层逻辑,每个组件的单元测试都通过了。agent 说"做完了"。你实际一点击导出按钮,文件路径格式不对、进度条没反应、大文件导出时内存泄漏。5 个组件边界缺陷,单元测试一个都没发现。+单元测试通过后,agent 经常会说"做完了",但端到端运行时才会暴露真正的问题。举例来说,让 agent 给 Electron 应用加一个文件导出功能,它写了渲染进程组件、预加载脚本、服务层逻辑,每个组件的单元测试都通过了。agent 说"做完了"。实际点击导出按钮时:文件路径格式不对、进度条没反应、大文件导出时内存泄漏。5 个组件边界缺陷,单元测试一个都没发现。每个部分单独看都"对"了,但拼在一起就出了问题。Google 的测试金字塔告诉我们,大量单元测试是基础,但如果你止步于此,就会系统性地漏掉组件交互问题。对于 AI 编码 agent 来说,这个问题更严重,因为 agent 倾向于只跑最快的测试然后宣告完成。**只有端到端测试能证明系统级缺陷不存在**。@@ -25,7 +25,7 @@这是很多人没意识到的一点:当 agent 知道它的工作要过端到端测试时,它的编码行为会改变。-1. **考虑组件交互**:写代码时会想"这个接口和上游怎么对接",而不是只关注单个函数。+1. **考虑组件交互**:写代码时会想"这个接口和上游怎么对接",不只关注单个函数。2. **尊重架构边界**:有架构约束的系统里,端到端测试迫使 agent 遵守边界规则。3. **处理错误路径**:端到端测试通常包含故障场景,迫使 agent 考虑异常处理。@@ -75,7 +75,7 @@ OpenAI 的经验:**对 agent 生成的代码库,架构约束必须是第一OpenAI 采用了"分层领域架构",每个业务领域被分成固定的层:Types → Config → Repo → Service → Runtime → UI。依赖方向严格向前,跨领域关注点通过显式的 Providers 接口进入。任何其他依赖都是禁止的,并且通过自定义 lint 机械执行。-关键原则:**执行不变量,不微管实现。** 比如要求"数据在边界解析",但不规定用哪个库。错误消息要包含修复指导,不只是说"违规了",而是告诉 agent 具体怎么改。+关键原则:**执行不变量,不微管实现。** 比如要求"数据在边界解析",但不规定用哪个库。错误消息要包含修复指导,要告诉 agent 具体怎么改,不只说"违规了"。> 来源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)@@ -136,7 +136,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea- **单元测试对组件边界缺陷系统性盲视**:它们的隔离设计恰好使其无法检测交互问题。- **端到端测试不仅检测缺陷,还改变 agent 的编码行为**:让它更关注集成和边界。-- **架构规则必须可执行**:不是写在文档里等人来看,而是每次提交自动检查。+- **架构规则必须可执行**:每次提交自动检查,不能只写在文档里等人来看。- **错误消息要面向 agent 设计**:包含"怎么修"的具体步骤,形成自我修正闭环。- **审查反馈提升让 harness 自动变强**:每个被捕获的缺陷类别都变成永久防线。diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdindex 72d63a7..671ec31 100644--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -5,9 +5,9 @@# 第十一讲. 让 agent 的运行过程可观测-你让 agent 做一个功能,它跑了 20 分钟,改了一堆文件,然后告诉你"做完了但有两个测试失败"。你问它为什么失败,它说"不太确定,可能是时序问题"。你问它改了哪些关键路径,它说"让我看看代码……"。+Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆文件,然后告诉你"做完了但有两个测试失败"。你问它为什么失败,"不太确定,可能是时序问题"。你问它改了哪些关键路径,"让我看看代码……"。-这种情况很常见,根源不在 agent 的能力,而在 harness 缺乏可观测性。agent 执行任务时,如果看不到运行时的实际状态,就只能凭猜测做决策。+这种情况的根源在 harness 缺乏可观测性。agent 执行任务时,如果看不到运行时的实际状态,就只能凭猜测做决策。**没有可观测性,agent 在不确定状态中做决策,评估变成主观判断,重试变成盲目摸索。** OpenAI 和 Anthropic 都将可靠性定义为证据问题,harness 必须以可指导下一步决策的形式暴露运行时行为和评估信号。@@ -137,7 +137,7 @@ Anthropic 在 2026 年 3 月发布了一项系统性的 harness 实验。他们三个 agent 各司其职,每个都有明确的可观测性角色:-**Planner(规划者)**:接收一段 1-4 句话的用户需求,扩展成完整产品规格。被要求"大胆设定范围"并且"专注于产品上下文和高层技术设计,而不是详细的技术实现"。原因是:如果 planner 过早指定了粒度技术细节且搞错了,错误会级联到下游实现。更好的做法是约束交付物,让 agent 在执行中自己找到路径。+**Planner(规划者)**:接收一段 1-4 句话的用户需求,扩展成完整产品规格。被要求"大胆设定范围"并且"专注于产品上下文和高层技术设计,而不深入详细的技术实现"。原因是:如果 planner 过早指定了粒度技术细节且搞错了,错误会级联到下游实现。更好的做法是约束交付物,让 agent 在执行中自己找到路径。**Generator(生成者)**:按 sprint 逐个功能实现。每个 sprint 前和 evaluator 协商一份 sprint 合同,约定这个功能块"做完"的标准。然后按合同实现,自评后交给 QA。@@ -151,7 +151,7 @@ Evaluator 不是一开始就这么强。早期版本会识别出合理的问题## 核心要点-- **可观测性是 harness 的架构属性**:不是事后添加的功能,而是设计时必须考虑的核心能力。+- **可观测性是 harness 的架构属性**:它是设计时必须考虑的核心能力,不应只作为事后添加的功能。- **双层可观测性缺一不可**:运行时信号解释"发生了什么",过程工件解释"为什么这样做"。- **冲刺合同前置对齐工作**:防止"生成者做了评估者因可预见原因立即拒绝的东西"。- **评分标准让评估可复现**:不同评估者对同一输出产生相似评分。