From 95310890a3a751b0ab60ab8e12de5274f2a892b4 Mon Sep 17 00:00:00 2001 From: lanrtop Date: Sat, 4 Jul 2026 12:12:29 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent-button):=20=E5=88=A0=E9=99=A4?= =?UTF-8?q?=E8=AF=B4=E8=B0=8E=E7=9A=84=20pnpm=20test=20=E6=8C=89=E9=92=AE?= =?UTF-8?q?=EF=BC=8CCONVENTIONS=20=E5=89=8D=E7=AB=AF=E6=B5=8B=E8=AF=95?= =?UTF-8?q?=E8=A7=84=E8=8C=83=E5=8A=A0=20Tauri=20=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=B1=BB=E5=9E=8B=E9=99=90=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .blueprint/CONVENTIONS.md | 37 +++++++++++-------- AGENTS.md | 3 +- src-tauri/resources/onboarding/AGENTS.md.tmpl | 2 +- 3 files changed, 23 insertions(+), 19 deletions(-) diff --git a/.blueprint/CONVENTIONS.md b/.blueprint/CONVENTIONS.md index 641daf9..bcb6030 100644 --- a/.blueprint/CONVENTIONS.md +++ b/.blueprint/CONVENTIONS.md @@ -131,7 +131,7 @@ acceptance 是 agent 自验的唯一判断依据，必须是**可执行断言** ✅ "pnpm typecheck 无报错" ✅ "cargo test 通过（src-tauri/）" ✅ "MCP tool list_projects 返回新增项目名" -✅ "pnpm test <测试文件> 全绿" +✅ "pnpm vitest run <测试文件> 全绿"（仅适用于有纯逻辑层的项目，见前端可测试性规范） ``` 最小结构：`[载体] 调用/运行什么(参数) → 断言什么`。 @@ -696,39 +696,44 @@ mod tests { ## 前端代码可测试性规范 -> 本规范适用于**新增** TypeScript/React 代码，存量代码不强制回填。 +> **适用范围**：有独立纯逻辑层的项目（Web 服务、Node CLI 等）。 +> Tauri 桌面应用的主测试路径是 `cargo test`（Rust 层）； +> 前端大量代码是 Tauri IPC 薄包装（`invoke()` 调用），无法在 Node 环境运行，不适合 vitest。 +> 炼境自身属于 Tauri 项目，**前端暂不配置 vitest**，以下规范待引入真实纯逻辑模块时生效。 + +### 何时引入 vitest + +满足以下条件之一时才引入： + +1. 项目有可独立运行（不依赖 Tauri 运行时）的纯逻辑模块，且该模块代码量 ≥ 200 行 +2. 某个 bug 在纯逻辑层反复出现，需要回归测试固化 + +引入时配置 `vitest.config.ts`，使用 `pnpm add -D vitest`。 ### 测试文件位置 前端测试文件与源文件同目录，命名约定：`.test.ts(x)`。 ``` -src/components/MyComponent.tsx -src/components/MyComponent.test.tsx ← 同目录、同名 + .test 后缀 - src/lib/utils.ts -src/lib/utils.test.ts ← vitest 自动发现 +src/lib/utils.test.ts ← vitest 自动发现（仅纯逻辑文件） ``` -### 测试框架 - -使用 vitest + `describe`/`it`/`expect`，配置见项目根 `vitest.config.ts`。 - -### 测试要求 +### 测试要求（适用时） | 代码类型 | 测试要求 | |---------|---------| | 纯逻辑函数（数据处理、格式化、解析、校验） | M 级任务卡强制附带测试，覆盖主路径 + 空/边界 | -| React 组件（含状态管理、数据流） | M 级任务卡建议附带测试，至少覆盖关键交互路径 | -| 纯样式组件 / Tauri IPC 薄包装层 | 无需测试 | +| Tauri IPC 薄包装层（invoke 调用） | 无需测试（主路径走 cargo test） | +| React 组件 | 无需测试（UI 由人工终验） | -### 任务卡 acceptance 模板补充 +### 任务卡 acceptance 模板（适用时） -含前端纯逻辑的 M 级任务卡，acceptance 须包含： +含前端纯逻辑的 M 级任务卡： ``` - [ ] 附带 vitest 测试，覆盖主路径 + 空数据边界 -- [ ] npx vitest run 全绿 +- [ ] pnpm vitest run 全绿 ``` ### 测试写法模板 diff --git a/AGENTS.md b/AGENTS.md index 8ebfe26..881014d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -207,7 +207,7 @@ docs/templates/ 炼境接入包模板草案（设计层） | UI 呈现层 | Playwright 驱动真界面（最后手段，仅关键路径） | 3. **完成的定义**：功能实现后，由 agent 沿投影路径真实走通一次（起服务 → 调接口 → 断言行为），再交人做 UI 终验——不许绕过功能手改产物冒充验证 -4. **侦察 → 驻军**：agent 走通的关键路径，顺手固化为一条测试（vitest / cargo test）； +4. **侦察 → 驻军**：agent 走通的关键路径，顺手固化为一条测试（炼境主路径为 cargo test；vitest 仅在引入独立纯逻辑模块后按需添加）； 一次性验收不固化（少而稳 > 多而脆） 5. **acceptance 可执行化**：`/splitter` 生成任务卡时，`acceptance` 字段必须是可执行验证路径， 格式：`[载体] 调用/运行什么(参数) → 断言什么`。 @@ -220,7 +220,6 @@ docs/templates/ 炼境接入包模板草案（设计层） | 能力 | 调用方式 | 通过标准 | |------|---------|---------| | TypeScript 类型检查 | `pnpm typecheck` | 无输出，exit 0 | -| 前端单元测试 | `pnpm test` | exit 0，无 FAILED | | Rust 单元测试 | `cargo test`（src-tauri/ 目录） | 无 FAILED | | MCP 工具调用 | 见 `src-tauri/src/mcp_tools.rs` 工具列表 | 返回 JSON，无 error 字段 | | 蓝图状态读取 | 读 `.blueprint/manifest.yaml` | 文件可解析，字段完整 | diff --git a/src-tauri/resources/onboarding/AGENTS.md.tmpl b/src-tauri/resources/onboarding/AGENTS.md.tmpl index b2bfa73..a89b2a2 100644 --- a/src-tauri/resources/onboarding/AGENTS.md.tmpl +++ b/src-tauri/resources/onboarding/AGENTS.md.tmpl @@ -51,7 +51,7 @@ | UI 呈现层 | Playwright 驱动真界面（最后手段，仅关键路径） | 3. **完成的定义**：功能实现后，由 agent 沿投影路径真实走通一次（起服务 → 调接口 → 断言行为），再交人做 UI 终验——不许绕过功能手改产物冒充验证 -4. **侦察 → 驻军**：agent 走通的关键路径，顺手固化为一条测试（vitest / cargo test）； +4. **侦察 → 驻军**：agent 走通的关键路径，顺手固化为一条测试（桌面应用用 cargo test；Web 项目纯逻辑层用 vitest）； 一次性验收不固化（少而稳 > 多而脆） 5. **acceptance 可执行化**：`/splitter` 生成任务卡时，`acceptance` 字段必须是可执行验证路径， 格式：`[载体] 调用/运行什么(参数) → 断言什么`。