From 538cc1b7fdc32a245920ce1c436d2a5b818e87cf Mon Sep 17 00:00:00 2001 From: 7418 <7418@openclaw.ai> Date: Wed, 4 Mar 2026 21:08:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B7=A5=E7=A8=8B=E8=B4=A8=E9=87=8F?= =?UTF-8?q?=E4=BF=9D=E9=9A=9C=E4=BD=93=E7=B3=BB=E6=89=A7=E8=A1=8C=E8=AE=A1?= =?UTF-8?q?=E5=88=92=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新建 completed/engineering-quality-assurance.md：记录 Harness Engineering 全部 5 个已完成 Phase 和 4 个未实现 Phase 的详细内容 - 更新 exec-plans/README.md 索引 Co-Authored-By: Claude Opus 4.6 --- docs/exec-plans/README.md | 4 +- .../engineering-quality-assurance.md | 179 ++++++++++++++++++ 2 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 docs/exec-plans/completed/engineering-quality-assurance.md diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md index c64f42e..a77f385 100644 --- a/docs/exec-plans/README.md +++ b/docs/exec-plans/README.md @@ -48,4 +48,6 @@ ### Completed -（暂无） +| 文件 | 主题 | 完成日期 | +|------|------|----------| +| completed/engineering-quality-assurance.md | 工程质量保障体系（Harness Engineering）— 验证闭环、AI 文档、CDP、执行计划 | 2026-03-04 | diff --git a/docs/exec-plans/completed/engineering-quality-assurance.md b/docs/exec-plans/completed/engineering-quality-assurance.md new file mode 100644 index 0000000..f75d527 --- /dev/null +++ b/docs/exec-plans/completed/engineering-quality-assurance.md @@ -0,0 +1,179 @@ +# 工程质量保障体系（Harness Engineering） + +> 灵感来源：OpenAI _Harness Engineering_ 文章 +> 创建时间：2026-03-04 +> 最后更新：2026-03-04 +> 版本：v0.25.1 + +## 状态 + +| Phase | 内容 | 状态 | 备注 | +|-------|------|------|------| +| Phase 1 | 验证闭环：pre-commit hook + CI gate + npm scripts | ✅ 已完成 | commit `99c4931` | +| Phase 2 | AI 可读文档：CLAUDE.md 路由化 + ARCHITECTURE.md | ✅ 已完成 | commit `e0c38af` | +| Phase 3 | 执行计划体系 + 技术债务追踪 | ✅ 已完成 | commit `62dbecd` | +| Phase 4 | CDP 视觉验证：chrome-devtools MCP 集成 | ✅ 已完成 | commit `a7104aa` | +| Phase 5 | 品牌一致性审查 | ✅ 已完成 | commit `935e3d0` | +| Phase 6 | ESLint 存量错误修复 | 📋 未实现 | 4 个 error，CI 用 `continue-on-error` 兜底 | +| Phase 7 | Smoke 测试实际验证 | 📋 未实现 | spec 已写好，未在 CI 中启用（需 dev server） | +| Phase 8 | E2E 测试覆盖核心流程 | 📋 未实现 | Playwright 框架就绪，无业务流程用例 | +| Phase 9 | PR 自动预览 + CDP 截图对比 | 📋 未实现 | 需 CI 环境启 dev server + headless Chrome | + +## 决策日志 + +- **2026-03-04**: 全部 5 个 Phase 一次性完成，随 v0.25.1 发布 +- **2026-03-04**: CI lint 步骤设 `continue-on-error: true`——存量 4 个 ESLint error 暂不修复，避免阻塞 CI +- **2026-03-04**: Smoke 测试不纳入 CI——需要 dev server 运行，当前 CI 矩阵无此环境 +- **2026-03-04**: `.mcp.json` 直接签入仓库——确保所有开发者和 AI 会话自动加载 CDP + +--- + +## Phase 1：验证闭环 + +**目标：** 建立三层自动验证（pre-commit → CI gate → 手动扩展测试），确保每次改动通过基线检查。 + +### 已实现 + +| 层级 | 机制 | 内容 | +|------|------|------| +| 本地 | pre-commit hook (`.husky/pre-commit`) | `lint-staged` → `tsc --noEmit` → `tsx --test` 顺序执行 | +| 本地 | npm scripts | `test` = typecheck + unit；`test:smoke` / `test:e2e` 按需运行 | +| CI | `lint-test` job (`.github/workflows/build.yml`) | lint → typecheck → unit test，所有 build job `needs: [lint-test]` | +| CI | PR 触发 | 新增 `pull_request: branches: [main]` 触发器 | + +### 文件变更 + +- `package.json` — 新增 6 个 scripts + `lint-staged` 配置 + `husky`/`lint-staged`/`tsx` devDependencies +- `.husky/pre-commit` — 新建 +- `.github/workflows/build.yml` — 新增 `lint-test` job + PR 触发 + `needs` 依赖 +- `src/__tests__/e2e/smoke.spec.ts` — 新建 Playwright @smoke 测试（5 个核心路由） + +### 未实现 + +- **ESLint 存量修复**（Phase 6）：`MessageItem.tsx` hooks 条件调用（L348, L355）、`ChatView` impure render（L521）、`GalleryDetail` setState in effect（L74）。CI lint 步骤用 `continue-on-error: true` 绕过。 +- **Smoke 测试纳入 CI**（Phase 7）：spec 已就绪但 CI 环境未配置 dev server。需在 CI 中添加 `npm run dev &` + `wait-on` 步骤，或改用 Next.js `start` 模式。 +- **E2E 覆盖**（Phase 8）：Playwright 框架和 helpers 就绪（`goToChat`、`goToPlugins` 等），但没有覆盖业务核心流程（发送消息、创建会话、插件管理等）的测试用例。 + +--- + +## Phase 2：AI 可读文档 + +**目标：** 让 AI 每次进入项目时能快速理解架构，减少重复探索的 token 浪费。 + +### 已实现 + +| 文档 | 作用 | +|------|------| +| `CLAUDE.md` | 路由层——规则、流程、自检命令，指向各专题文档 | +| `ARCHITECTURE.md` | 架构全景——目录结构、数据流、数据库 schema、技术栈、新功能触及点 | + +### 设计原则 + +- **CLAUDE.md 是入口**：只放规则和流程，不放架构细节（避免膨胀） +- **ARCHITECTURE.md 是地图**：一次性给 AI 全局视角，减少 Glob/Grep 探索 +- **自检 checklist**：i18n → db → types → docs 四项，防止遗漏 + +### 未实现 + +- **组件文档自动生成**：没有为 `src/components/` 各子目录生成 props/用法说明 +- **API 路由文档**：52 个 REST 端点没有 OpenAPI/Swagger 描述 + +--- + +## Phase 3：执行计划体系 + +**目标：** 中大型功能有据可查，进度可追踪，技术债务可见。 + +### 已实现 + +| 产物 | 路径 | 内容 | +|------|------|------| +| 执行计划规范 | `docs/exec-plans/README.md` | 模板、索引、使用指南 | +| 首个执行计划 | `docs/exec-plans/active/context-storage-migration.md` | 从 research 迁移而来，标注各 Phase 状态 | +| 技术债务清单 | `docs/exec-plans/tech-debt-tracker.md` | 4 项已知债务 | +| CLAUDE.md 规则 | CLAUDE.md "执行计划" 区块 | 强制 AI 对中大型功能先写计划再开工 | + +### 未实现 + +- **计划审批流程**：当前靠 CLAUDE.md 文字规则约束 AI，没有技术手段阻止 AI 跳过计划直接开工 +- **进度自动同步**：计划状态需手动更新，没有与 git commit/PR 自动关联 + +--- + +## Phase 4：CDP 视觉验证 + +**目标：** AI 修改 UI 后能自动截图验证，不依赖人工肉眼检查。 + +### 已实现 + +| 产物 | 说明 | +|------|------| +| `.mcp.json` | chrome-devtools MCP server 配置，签入仓库 | +| CLAUDE.md 规则 | "UI 改动必须用 CDP 验证" 区块：截图、console 检查、点击模拟、响应式验证 | + +### CDP 能力 + +- 页面截图（`mcp_screenshot`） +- DOM 查询和点击（`mcp_click`, `mcp_evaluate`） +- 设备模拟（viewport 尺寸切换） +- Console 日志读取 + +### 未实现 + +- **CI 中自动 CDP 截图**（Phase 9）：当前仅在本地 AI 会话中使用。理想状态是 PR 触发后自动启动 dev server → 截图关键页面 → 与基线对比 → 差异过大则阻止合并。需要： + - CI 环境安装 Chrome/Chromium + - dev server 启动和健康检查 + - 基线截图存储和对比工具（如 Percy、Playwright visual comparison） + - 差异阈值和 PR comment 集成 +- **截图基线管理**：没有建立各页面的"正确"截图基线供对比 + +--- + +## Phase 5：品牌一致性 + +**目标：** 应用自身的 UI 文案使用 "CodePilot" 而非 "Claude"（Claude Code 连接部分除外）。 + +### 已实现 + +- `src/i18n/en.ts`：`Claude Chat` → `CodePilot Chat`，`conversation with Claude` → `conversation with CodePilot` +- `src/i18n/zh.ts`：`Claude 对话` → `CodePilot 对话`，`与 Claude 对话` → `与 CodePilot 对话` + +### 保留 "Claude" 的场景（正确用法） + +- `claude-client.ts` / `claude-session-parser.ts` — 指 Claude Code CLI +- `chatList.importFromCli: 'Import from Claude Code'` — 指导入 Claude Code 会话 +- `settings.claudeApiKey` — 指 Anthropic API key +- `nav.claudeCodeSettings` — 指 Claude Code 本身的设置 + +### 未实现 + +- **i18n key 重命名**：`messageList.claudeChat` 这个 key 名称本身仍含 "claude"，但因为 key 不面向用户且改名需同步所有引用，暂不处理 +- **应用标题栏 / Electron 窗口标题**：未审查 Electron `main.ts` 中的窗口标题是否使用了正确品牌名 +- **README / GitHub 仓库描述**：未审查面向外部的项目描述文案 + +--- + +## 总结 + +### 已建立的保障机制 + +``` +开发者/AI 改动代码 + → pre-commit: lint-staged + typecheck + unit test（~5s） + → CDP 截图验证（UI 改动时） + → git push → CI lint-test job + → PR 合并门槛（lint + typecheck + unit 全过） + → 中大型功能有执行计划跟踪 + → 技术债务可见可追溯 +``` + +### 未来可改进方向 + +| 方向 | 优先级 | 说明 | +|------|--------|------| +| 修复 4 个 ESLint 存量 error | 中 | 去掉 CI `continue-on-error`，让 lint 真正成为门槛 | +| CI 启 dev server + smoke test | 中 | 补全 CI 中的冒烟测试覆盖 | +| E2E 测试覆盖核心业务流程 | 中 | 发消息、创建会话、插件管理等 | +| PR 自动截图对比 | 低 | 需要 CI Chrome + 基线管理 + 对比工具 | +| 组件/API 文档自动生成 | 低 | 降低新人和 AI 理解成本 | +| 执行计划与 PR 自动关联 | 低 | commit message 引用计划编号 → 自动更新状态 |