docs(test): define value-based testing rules

AGENTS.md

@@ -28,15 +28,14 @@
 
 ## 测试
 
-- 测试文件位置：与单个业务模块强相关的单元测试应就近放在被测文件同目录，命名为 `*.test.ts` / `*.test.js`；跨模块、集成、E2E、测试工具或不明显归属某个业务文件的测试放在根目录 `tests/`；某个 app/package 专属测试放在对应的 `apps/*` 或 `packages/*` 内，遵循该子项目现有约定
-- 测试目标：测试应优先覆盖用户数据安全、数据库迁移、导入解析、权限/认证、AI 工具权限、配置/API key 迁移、跨端共享逻辑和已发生过的回归；不要为了提高数量给低风险 getter、常量、样式或纯展示细节机械补测
-- 必须加测试：修复会影响用户数据、业务逻辑、异步任务、缓存状态、跨端共享 service、公开 API 契约、导入解析、去重逻辑、权限认证、AI 工具 allowlist、配置/API key 迁移或数据库 schema/迁移的行为 bug 时，必须先加能失败的回归测试；修改上述高风险模块时也必须加或更新测试
-- 可以不加测试：只改 UI 文案、i18n key/翻译、样式、类型声明、日志、注释、无行为变化的小重构，或修复低风险展示细节时，可以不新增测试，但仍需运行相关类型检查、lint 和 format；不要为了低价值页面文案或源码字符串扫描新增脆弱测试
-- 低风险文档、示例、README、SKILL.md、`.docs`、package `files` 列表等说明/分发类改动，不要新增测试，也不要为了锁定文案、示例命令或文件存在性写脆弱测试；只做格式化、相关构建或必要静态检查。只有涉及用户数据、业务逻辑、导入解析、跨端 service、公开 API、权限/auth、数据库迁移、AI 工具 allowlist 或异步任务时，才新增或更新回归测试。
-- 测试分层：纯函数、解析/格式化、权限判断、参数规范化、错误分支优先写单元测试；SQL 行为、数据库迁移、文件迁移、导入写库、Fastify route、跨包 service 优先写集成测试；Electron、真实浏览器、真实 LLM、真实网络仅用于少量关键 E2E/Smoke，并默认通过环境变量显式启用
-- 避免重复测试：新增测试前先搜索同类断言；如果下层单测已覆盖算法，上层只测调用链是否接通，不重复枚举算法细节；如果测试只锁定实现写法、失败后不指向用户可见风险，应合并、改写或删除；优先写能覆盖全量场景的通用断言，而非针对单个条目的专项断言——若通用断言已完整覆盖，单个断言是冗余的
-- 测试替身选择：涉及 SQL、数据库迁移、Fastify route 或跨包 service 时，优先使用轻量内存 SQLite / 临时文件 fixture 验证真实行为；只有在测试纯适配边界时才使用 mock/fake。避免用大量 `sql.includes(...)` 一类字符串匹配来模拟数据库行为
-- 适配层测试边界：CLI/Electron/Web route、IPC adapter、tool adapter 只验证参数传递、权限过滤、错误映射和返回契约；core 已覆盖的算法矩阵不要在入口层重复展开
+- 价值门槛：新增测试前，必须先说明它防止哪一种用户可见回归。测试应验证行为、数据或公开契约；**如果测试失败不能说明产品行为出错，就不应该新增。**
+- 必须新增：修复真实的行为 Bug，或修改用户数据、数据库迁移、导入解析、去重、权限认证、配置/API Key 迁移、公开 API、跨端共享 service 等高风险逻辑时，应优先补充能在修改前失败的回归测试。已有测试完整覆盖时不重复新增。
+- 通常不新增：文案、样式、类型、日志、注释、文档、常量、简单 getter、文件列表和无行为变化的重构。只运行相关类型检查、lint、format、构建或现有测试。
+- 避免机械测试：不要通过扫描源码字符串、匹配完整 SQL、断言私有函数调用顺序、锁定日志文案或枚举每个常量来证明功能正确。Mock 调用次数只用于 adapter 的参数传递或权限边界，不用于锁定内部实现。
+- 提高信息密度：同一规则的多个输入优先使用表驱动测试或通用断言；下层已覆盖算法时，上层只验证调用链和返回契约。修改相关模块时，应搜索并合并或删除重复、过期和低价值测试。
+- 测试分层：纯函数和参数规范化使用单元测试；SQL、迁移、导入写库、Fastify route 和跨包 service 优先使用轻量真实依赖或临时数据库；真实 Electron、浏览器、LLM 和网络只用于少量显式启用的 Smoke/E2E。
+- 测试位置：模块单元测试放在被测文件附近；跨模块、集成、E2E 和测试工具放在根目录 `tests/` 或对应 app/package 的既有测试目录。
+- Review 判断：缺少测试本身通常不是严重 Bug。Reviewer 必须指出具体未覆盖的用户风险；只有数据安全、迁移、权限、公开契约等高风险行为缺少必要验证时，才应阻塞当前 PR。
 
 ## 命令与验证