企业官网建设流程全解析

本文基于 learn-harness-engineering 课程第 10 讲（为什么端到端测试改变结果）的配套示例review-feedback-to-rule.md，讲解如何把反复出现的代码审查意见转化为 harness 中可自动执行、agent 可读懂的规则。读完本文，你将掌握"审查反馈提升"（Review Feedback Promotion）的完整落地方法：从一条 review 评论出发，拆解出 lint/导入检查与修复指导两个构件，并借助仓库内真实的check-architecture.sh、分层架构文档与端到端测试示例，在 harness 中建立自动修正的反馈闭环。

从一个真实的 Review 反馈开始

第 10 讲配套代码示例review-feedback-to-rule.md记录了一条典型的、反复出现的审查意见，以及它被提升为 harness 规则后的产物：

审查意见（Review 评论）：不要在 renderer 里使用文件系统工具，请使用 preload 桥。

提升后的 harness 规则包含两个部分：

• 添加一条 lint 规则或导入检查，禁止在 renderer 代码中使用fs；
• 添加一段修复说明（remédiation）文本，解释 preload 边界应当如何使用。

这条示例虽短，却浓缩了 harness 工程中一个极其重要的机制：把"靠人反复提醒"的审查意见，转变成"每次提交自动拦截"的机器检查。它与第 10 讲讲稿正文（见index.md）中的"审查反馈提升"概念一一对应，也是讲稿中第二个流程图的直接落地。

为什么"人肉 Review"在 agent 工作流中必然失效

在传统开发中，代码审查由资深工程师执行，意见可以被口头传递。但在 AI 编码 agent 的工作流中，这条路径有两个结构性缺陷：

1. agent 会复制仓库中的既有模式。正如讲稿引用的 OpenAI 经验：agent 会复制仓库中已有的模式，即使这些模式是不均匀或次优的。如果架构边界只写在文档里，agent 每次会话都会引入新的偏差，而不会主动查阅文档。
2. review 反馈是一次性的、不可复用的。每次新会话都是一个新的上下文，上一次 review 中给出的教训不会自动传承。没有机器检查兜底，同一个"renderer 直接 import fs"的错误会在不同会话中反复出现。

因此，讲稿给出的判断是：架构约束必须是第一天就建立的早期前置条件，而不是等团队规模变大后再考虑的事情。而把审查反馈提升为规则，正是把"人的判断"沉淀为"机器的检查"，让 harness 随着每次 review 自动变强——这正是review-feedback-to-rule.md示例所演示的动作。

提升规则的两个构件：可执行检查 + 修复指导

从示例可以看出，一条 review 反馈提升为规则，需要同时产出两个构件，缺一不可：

仅做检查、不给修复指导，agent 只会看到一行模糊的报错，无法自主修正；仅写文档、不做检查，则又回到了"写在纸上等人来看"的老路。两者结合，才能把架构规则变成自动修正的闭环。

讲稿中用了一个生动的比喻：合唱指挥不会只说"你唱错了"，而是会说"你这里快了半拍，听中音部的节奏，在第 32 小节进"。同理，面向 agent 的错误消息必须包含修复指令。

仓库源码印证：真实的分层边界与检查脚本

这条规则在仓库中有完整的真实实现。第 5 个实战项目（projects/project-05/README.md）的 starter 中，架构边界由三份文件共同定义：

• docs/ARCHITECTURE.md：定义四层分层架构（Renderer → Preload → Main Process → Services → Persistence），明确每层的职责与禁止事项；
• scripts/check-architecture.sh：把架构约束翻译成可执行检查；
• AGENTS.md：要求 agent 在提交前运行检查，并把"check-architecture.sh 零违规"列为完成的定义之一。

check-architecture.sh正是"审查反馈提升"思想的机械执行版本，它检查三类边界违规：

# 检查 1：renderer 不得 import Node.js 核心模块（fs/path/os/child_process） RENDERER_FILES=$(find src/renderer -name '*.ts' -o -name '*.tsx' 2>/dev/null || true) if [ -n "$RENDERER_FILES" ]; then while IFS= read -r file; do if grep -qE "import.*\b(fs|path|os|child_process)\b" "$file" 2>/dev/null; then echo " VIOLATION: $file imports Node.js core module" VIOLATIONS=$((VIOLATIONS + 1)) fi done <<< "$RENDERER_FILES" fi # 检查 2：services 不得 import Electron IPC # 检查 3：services/main 不得 import React

脚本以退出码区分结果：exit 0表示全部通过，exit 1表示存在违规，从而可以被 CI、pre-commit hook 或 agent 的验证流程直接调用。这与讲稿中的命令示例一脉相承：

# 检查渲染进程是否直接调用 Node.js API grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"

注意其中的差异：讲稿示例用一条grep完成检查，仓库实现则用find+grep -qE的正则匹配，能同时覆盖import ... from 'fs'与ipcMain、BrowserWindow等更多违规形态。这说明从一条 review 反馈到规则，是一个可以逐步加强、持续迭代的过程——每发现一种新的违规形态，就往检查里加一个模式。

而ARCHITECTURE.md中对应的边界约束是：

• Renderer 层不得importfs、path、os、child_process等 Node.js 核心模块，不得直接访问 Electron API，所有数据访问必须经由 preload 桥（window.knowledgeBase）；
• Preload 层不得包含业务逻辑，仅通过contextBridge.exposeInMainWorld暴露类型化 API；
• Services 层不得import Electron 或 React，所有文件系统访问必须经过PersistenceService。

这些约束与第 10 讲配套的architecture-rules.md完全一致，后者以四条规则形式总结了 Electron 应用的架构边界：renderer 不能直接访问文件系统、preload 是 renderer 与 main 之间的唯一桥、数据抓取与索引逻辑位于 service 模块而非 UI 组件、日志必须结构化且从服务边界输出。

设计面向 agent 的错误消息：三要素

检查脚本负责"发现违规"，但让 agent 能自主修正，靠的是错误消息本身。讲稿给出了面向 agent 的错误消息三要素——什么出了问题、为什么、怎么修：

ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12 WHY: Renderer process has no access to Node.js APIs for security FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()

对照示例中的规则产物，"添加一段修复说明文本"正是这条消息里的FIX部分。消息中同时给出：违规位置（src/renderer/App.tsx:12）、违规原因（渲染进程出于安全原因无权访问 Node.js API）、以及具体修法（把文件操作移到src/preload/file-ops.ts，通过window.api.readFile()调用）。这正是 OpenAI 在 Codex 工程实践中强调的原则：为 agent 写的错误消息必须包含修复指导，把测试失败变成自我修正的反馈循环。

把反馈提升固化进验证层级

要防止 agent 在单测通过后过早宣布完成，讲稿建议在 harness 的验证流程中显式定义验证层级：

## 验证层级 - 层级 1: 单元测试 (必须通过) - 层级 2: 集成测试 (必须通过) - 层级 3: 端到端测试 (涉及跨组件修改时必须通过) - 跳过任何必须层级的任务 = 未完成

"跳过任何必须层级 = 未完成"是关键条款：它把"跑完整流程"从可选项变成完成的前置条件，直接对抗 agent 倾向于只跑最快测试就宣告完成的习惯。与之呼应，AGENTS.md中的 Definition of Done 明确列出：目标行为已实现、必需的验证确实运行过、证据已记录在最终总结中、scripts/check-architecture.sh零违规通过。

审查反馈提升的五步流程

结合示例与讲稿，把一条 review 反馈提升为 harness 永久防线的完整流程如下：

1. 识别重复问题：在代码审查中发现某类错误反复出现（如"renderer 直接 import fs"）；
2. 提炼检查规则：把它变成可执行的 lint 或导入检查（grep、find + grep -qE、eslint 插件均可）；
3. 编写修复指导：在报错消息中加入FIX指令，告诉 agent 正确路径与调用方式；
4. 加入 harness：把检查接入 CI 或 pre-commit 验证流程，使每次提交自动执行；
5. 持续加强：下个会话若出现新违规形态，扩展检查模式，harness 自动变强。

正如讲稿所说：每次发现重复问题就加一条规则，一个月后 harness 会比月初强得多；每个被捕获的缺陷类别都变成一条永久防线。

端到端测试：让提升后的规则真正改变结果

review 反馈提升与端到端测试是同一枚硬币的两面。第 10 讲讲稿的核心论点是：单元测试对组件边界缺陷系统性盲视——接口不匹配、状态传播错误、资源生命周期问题、环境依赖这四类缺陷，单测因隔离设计几乎必然漏掉，只有端到端测试能证明系统级缺陷不存在。

配套的e2e-runner.ts用三个用例演示了这一现象（npx tsx可直接运行）：导入文档并提问、删除文档并验证移除、多用户并发访问。每个用例中，所有步骤的单元测试都标记为PASS，但端到端模拟的"真实行为"却因维度不匹配、索引残留、用户隔离缺失而失败——最终输出False confidence count: 3 of 3，即单元测试全部通过而端到端全部失败。

讲稿给出的实战案例同样印证：在一个 Electron 文件导出功能中，端到端测试捕获了接口不匹配、状态传播、资源泄漏、权限问题、错误传播共 5 个缺陷，单元测试一个都没发现，代价仅是测试时间从 2 秒增加到 15 秒——在 agent 工作流中完全可接受。

因此，审查反馈提升的最终目标不只是"有检查"，而是让检查与端到端验证协同：规则负责在编码阶段拦截已知违规，端到端测试负责在系统层面捕获未知的组件交互缺陷。两者共同构成 harness 中从"预防"到"验证"的完整防线。

概念速查

• 审查反馈提升（Review Feedback Promotion）：把反复出现的代码审查意见转化为自动化检查，每次发现重复问题就加一条规则，harness 自动变强；
• 架构边界执行规则：把架构文档中的规则（如"渲染进程不能直接访问文件系统"）变成可执行、自动化的检查，从"写在纸上"变成"跑在 CI 里"；
• 面向 agent 的错误消息：失败信息不只说"出了什么问题"，还要包含WHY与FIX，让 agent 能够自主完成修正；
• 组件边界缺陷：组件 A、B 各自单测通过，但交互产生错误行为，是端到端测试最擅长捕获的问题类型；
• 测试充分性梯度：单元测试可检测缺陷 ≤ 集成测试 ≤ 端到端测试，每往上一层检测能力增强。

关键要点

• 一条 review 反馈提升为规则，需要"可执行检查 + 修复指导"两个构件同时落地，缺一不可；
• 架构规则必须可执行：每次提交自动检查，而不是写进文档等人来看；
• 错误消息要面向 agent 设计：用ERROR/WHY/FIX三要素把测试失败变成自我修正闭环；
• 端到端测试不仅检测缺陷，还改变 agent 的编码行为，迫使其考虑组件交互、尊重架构边界、处理错误路径；
• 仓库中check-architecture.sh、ARCHITECTURE.md与AGENTS.md构成了这套机制的可运行参考实现，可直接在项目 5 的 starter 中bash scripts/check-architecture.sh验证其行为。