add-coder 0.1.0

package/templates/core/specs/farm-agent-add-coder-npm-package/tasks.md

@@ -0,0 +1,203 @@
+# Tasks: add-coder npm 包工程化
+
+## Preconditions
+
+- [x] Plan 已生成
+- [x] ADD Route 已生成
+- [x] Review 已生成
+- [x] Handoff 已创建
+
+## Forbidden
+
+- 禁止修改 farm-agent 业务代码（`src/`、`docs/` 等）
+- 禁止引入第三方模板引擎（Handlebars/EJS 等）
+- 禁止在模板代码中保留 `process.env.X || "兜底值"` 反模式
+
+---
+
+## 第1轮：基础准备
+
+- [x] Task 1.0: Prisma 模型准备 — 验证: `prisma migrate dev --schema=prisma/` 成功创建 DevOperation + AuditLog 表
+  - [x] 从 `prisma/main.prisma` 提取 DevOperation 和 AuditLog 模型定义
+  - [x] 写入 `templates/core/prisma/add.prisma`（模型定义，无参数化）
+  - [x] 实现 `src/cli/prisma-injector.ts`：
+    - [x] 检测用户项目是否已有 Prisma（`prisma/` 目录 + `schema.prisma`）→ 无则报错
+    - [x] 检测 User 模型是否存在（`id: String`）→ 无则报错
+    - [x] 复制 `add.prisma` → 用户 `prisma/` 目录
+    - [x] 执行 `prisma migrate dev --name add_workflow_init --schema=prisma/`（幂等）
+    - [x] 执行 `prisma generate`
+    - [x] 迁移失败时回滚 `add.prisma`（删除已复制文件）
+    - [x] 已有 `add.prisma` 时：交互三选一（跳过/覆盖/diff+备份）
+
+- [x] Task 1.1: 清理硬编码 + 参数化 core 模板 — 验证: `grep -r "farm.agent\|farm_secure_pass\|大田精准\|/home/xmm\|/Users/milkytea" templates/` 返回空
+  - [x] 15 个 `.md` 模板（plan/spec/tasks/checklist/handoff/review/add-route 等）：`docs/大田精准耕播智能决策系统/` → `{{docsDir}}/`、`farm-agent-*` → `{{projectName}}-*`
+  - [x] 15 个 `.schema.json`：检查确认无硬编码
+  - [x] `skills/add-paradigm/SKILL.md`：`/home/xmm/ai/farm-agent/` → `{{projectRoot}}/`
+  - [x] `skills/session-init/SKILL.md`：`farm-agent-*` → `{{projectName}}-*`
+  - [x] `agents/add-flow-guardian.md`：检查确认
+  - [x] `agents/add-orchestrator.md`：检查确认
+  - [x] `rules/project_rules.md`：`farm-agent` → `{{projectName}}`、`src/agents/` → `{{sourceDir}}/agents/`
+  - [x] `rules/theory-practice-map.toml`：检查确认
+  - [x] `vocabulary/add-governance-vocabulary.md`：检查确认
+  - [x] `scripts/mcp-server.ts`：`DATABASE_URL || "postgresql://..."` → `process.env.DATABASE_URL`（无兜底值）、`.env.development` → `{{envFilePath}}`
+  - [x] `scripts/add-coder-mcp-server.ts`：同上
+  - [x] `.qoder/settings.json`：hook 脚本绝对路径 → `{{projectRoot}}/.qoder/hooks/`
+  - [x] `.qoder/mcp.json`：`DATABASE_URL` 硬编码密码 → `process.env.DATABASE_URL`
+  - [x] `.qoder/sync-policy.json`：检查确认
+  - [x] `.qoder/hooks/` 下 14 个 `.sh` + `lib/`：项目名提取逻辑 → 使用 `$CLAUDE_PROJECT_DIR` 或 `{{projectRoot}}`
+  - [x] `.vscode/` 下 4 个文件：MCP 配置中的项目特定路径 → `{{projectRoot}}`
+  - [x] `reports/` 下 7 个文件：`farm-agent`、绝对路径 → `{{projectName}}`、`{{projectRoot}}`
+  - [x] `tools/README.md`：检查确认
+  - [x] 创建 `src/core/renderer.ts`：接收 config 对象，执行 `"{{key}}".replace("{{key}}", config.key)`
+
+---
+
+## 第2轮：架构搭建
+
+- [x] Task 2.0: 模板目录重组 + 适配器架构搭建 — 验证: 新目录结构符合 §3.2，`find templates/ -name "*.ts" | wc -l` 返回 0
+  - [x] 迁移 `agents/` → `templates/core/agents/`
+  - [x] 迁移 `skills/` → `templates/core/skills/`
+  - [x] 迁移 `templates/*.md`（15 个） → `templates/core/docs/`（去嵌套）
+  - [x] 迁移 `templates/*.schema.json`（15 个） → `templates/core/docs-schema/`
+  - [x] 迁移 `templates/index.md` → `templates/core/docs/index.md`
+  - [x] 迁移 `templates/TERMINOLOGY.md` → `templates/core/docs/TERMINOLOGY.md`
+  - [x] 迁移 `rules/` → `templates/core/rules/`
+  - [x] 迁移 `vocabulary/` → `templates/core/vocabulary/`
+  - [x] 迁移 `scripts/` → `templates/core/scripts/`
+  - [x] 迁移 `reports/` → `templates/core/reports/`
+  - [x] 迁移 `tools/` → `templates/core/tools/`
+  - [x] 迁移 `.qoder/hooks/`（14 个 .sh + lib/） → `templates/adapters/qoder/hooks/`
+  - [x] 迁移 `.qoder/settings.json` → `templates/adapters/qoder/settings.json`
+  - [x] 迁移 `.qoder/mcp.json` → `templates/adapters/qoder/mcp.json`
+  - [x] 迁移 `.qoder/sync-policy.json` → `templates/adapters/qoder/sync-policy.json`
+  - [x] 迁移 `.vscode/`（4 个文件） → `templates/adapters/vscode/`
+  - [x] 迁移 `debug-dump/`、`repowiki/` → `templates/shared/`（空目录占位）
+  - [x] 创建 `templates/adapters/claude/` 目录（空壳）
+  - [x] 创建 `templates/shared/hooks-lib/common.sh`（退出码常量 + stdin JSON 解析）
+  - [x] 创建 `src/adapters/{claude,qoder,vscode}/` 目录，各含 `renderer.ts` 骨架
+  - [x] 定义 Adapter 接口：`render(config: AddCoderConfig, targetDir: string, dryRun: boolean): Map<string, string>`
+  - [x] 删除旧 `templates/` 扁平目录
+
+---
+
+## 第3轮：适配器实现（串行：Claude → Qoder → VS Code）
+
+- [x] Task 3.0: Claude 适配器实现 — 验证: `npx add-coder init --adapter claude` 生成正确的 `.claude/` 目录
+  - [x] 创建 `templates/adapters/claude/settings.json` 模板（hook 配置，matcher 用标准工具名 `Write`, `Edit`, `Bash`）
+  - [x] 创建 `templates/adapters/claude/mcp.json` 模板
+  - [x] 创建 12 个 hook 脚本（参考 Qoder 实现，差异仅在 matcher 工具名映射）：
+    - [x] `pre-tool-use.sh`（matcher: `Write`, `Edit`, `Bash`）
+    - [x] `post-tool-use.sh`（matcher: 同上）
+    - [x] `session-start.sh`
+    - [x] `pre-compact.sh`
+    - [x] `stop-check.sh`
+    - [x] `notification.sh`
+    - [x] `permission-gate.sh`
+    - [x] `prompt-submit.sh`
+    - [x] `post-tool-failure.sh`
+    - [x] `subagent-guard.sh`
+    - [x] `review-checklist.sh`
+    - [x] `doc-format-guard.sh`
+  - [x] 实现 `src/adapters/claude/renderer.ts`
+
+- [x] Task 3.1: Qoder 适配器实现 — 验证: `npx add-coder init --adapter qoder` 生成正确的 `.qoder/` 目录
+  - [x] 确认 `templates/adapters/qoder/` 下文件已清理 hardcode（第1轮 Task 1.1 已做）
+  - [x] `settings.json` 的 matcher 适配：`Write|write_to_file|create_file|CreateFile` 等双套工具名
+  - [x] 实现 `src/adapters/qoder/renderer.ts`
+
+- [x] Task 3.2: VS Code 适配器实现 — 验证: `npx add-coder init --adapter vscode` 生成正确的 `.vscode/` 目录
+  - [x] 确认 `templates/adapters/vscode/` 下文件已就位
+  - [x] 补充 `tasks.json` 的 hook 模拟（文件保存时触发检查等）
+  - [x] 在生成的 README 中诚实声明 VS Code 的能力边界（无原生 hook，仅模板 + MCP）
+  - [x] 实现 `src/adapters/vscode/renderer.ts`
+
+---
+
+## 第4轮：配置 + CLI
+
+- [x] Task 4.0: 配置系统 — 验证: `add-coder.config.ts` 的类型提示完整，无效配置在 Zod 校验时报错
+  - [x] `src/config/schema.ts`：Zod schema 定义 `AddCoderConfig`（`projectName`, `sourceDir`, `docsDir`, `logDir`, `mcpServerCommand`, `adapters`, `overrides`）
+  - [x] `src/config/defaults.ts`：合理默认值
+
+- [x] Task 4.1: CLI 重写 — 验证: `npx add-coder init` 在空白项目中成功生成完整 ADD 模板
+  - [x] `src/cli/index.ts`：主入口（commander）
+  - [x] `src/cli/commands/init.ts`：init 命令（七步流程：检测 IDE → 加载配置 → 渲染 core → 渲染 adapter → Prisma 注入 → 写入 → 摘要）
+  - [x] `src/cli/commands/sync.ts`：sync 命令（只同步缺失文件）
+  - [x] `src/cli/commands/status.ts`：status 命令（检查完整性）
+  - [x] `src/cli/detect.ts`：IDE 环境检测（扫描 `.qoder/` `.claude/` `.vscode/` 存在性）
+  - [x] `src/cli/config-loader.ts`：配置加载 + Zod 校验 + 优先级合并（交互式 > 配置文件 > 自动检测 > 默认值）
+  - [x] `src/cli/writer.ts`：智能写入（四种模式：交互 / `--yes` / `--force` / `--dry-run`）
+  - [x] `bin/add-coder.js` 改为加载 `dist/cli/index.js`
+  - [x] `tsup.config.ts`：构建配置（ESM + CJS 双格式）
+  - [x] `tsconfig.json`：TypeScript 编译配置
+
+---
+
+## 第5轮：测试 + 发布
+
+- [x] Task 5.0: 集成测试 + 文档 + devlog — 验证: 9/9 测试通过 + `npm pack` 产出正确
+  - [x] 单元测试：`renderer.ts`、`config-loader.ts`、`detect.ts`、`writer.ts`
+  - [x] 集成测试：在临时目录中执行 `init` → 验证生成的文件结构
+  - [x] 三端集成测试：`init --adapter claude`、`--adapter qoder`、`--adapter vscode`
+  - [x] 更新 `README.md`（关联 [codein2027](https://github.com/xiaomingming92/codein2027)，标注本 npm 包为第 8 轮架构合流闭包落地产物）
+  - [x] 更新 `package.json`：`"private": false`，`"type": "module"`，`"files"` 字段，`"bin"` 字段，`"exports"` 多入口，`"engines": { "node": ">=20" }`，`"packageManager": "pnpm@11.9.0"`
+  - [x] 调用 MCP `record_dev_operation` 落库 ADD 开发日志到 DevOperation 表
+
+---
+
+## 第6轮：裁决层
+
+- [x] Task 6.0: CaijueHub 核心 — 验证: `caijue.toml` 可被正确解析，CLI 标志覆盖裁决项
+  - [x] 创建 `src/caijuehub/caijue.toml`：内置默认裁决（detect/config/prisma/writer/adapters 五段）
+  - [x] 创建 `src/caijuehub/caijue.ts`：TOML 读取 + CLI 标志覆盖 + 审计
+
+- [x] Task 6.1: 重构现有模块读 caijue — 验证: 修改 `caijue.toml` 中 `[detect].priority` 顺序后 IDE 检测行为改变
+  - [x] `detect.ts`：IDE 检测优先级从 `[detect]` 段读取
+  - [x] `config-loader.ts`：配置加载优先级链从 `[config]` 段读取
+  - [x] `prisma-injector.ts`：阻断/交互行为从 `[prisma]` 段读取
+  - [x] `writer.ts`：写入模式从 `[writer]` 段读取
+  - [x] `init.ts`：adapter 选择从 `[adapters]` 段读取
+
+---
+
+## Task Dependencies
+
+```
+第1轮: 基础准备
+  Task 1.0: Prisma 模型准备 ──┐
+  Task 1.1: 清理硬编码 ────────┘ 可并行，互不依赖
+           │
+           ▼
+第2轮: 架构搭建
+  Task 2.0: 适配器架构搭建
+           │
+           ▼
+第3轮: 适配器实现
+  Task 3.0: Claude → Task 3.1: Qoder → Task 3.2: VS Code（串行）
+           │
+           ▼
+第4轮: 配置 + CLI
+  Task 4.0: 配置系统 → Task 4.1: CLI 重写（依赖 Task 1.0 + Task 4.0）
+           │
+           ▼
+第5轮: 测试 + 发布
+  Task 5.0: 集成测试 + 文档 + devlog（依赖全部前序 Task）
+           │
+           ▼
+第6轮: 裁决层
+  Task 6.0: CaijueHub 核心 → Task 6.1: 重构模块读 caijue
+```
+
+## Verification
+
+- [x] `npx tsc --noEmit` 通过
+- [x] `grep -r "farm.agent\|大田" dist/` 返回空
+- [x] `grep -r "process.env.*||" dist/` 返回空
+- [x] `npx add-coder init` 在空白项目中零配置生成完整 ADD 模板
+- [x] `npx add-coder init --adapter claude` 生成 `.claude/` 目录
+- [x] `npx add-coder init --adapter qoder` 生成 `.qoder/` 目录
+- [x] `npx add-coder init --adapter vscode` 生成 `.vscode/` 目录
+- [x] `npm pack` 产出包含 `dist/` + `templates/` + `bin/`，不包含 `src/`
+- [x] `prisma migrate dev --schema=prisma/` 成功创建 DevOperation + AuditLog 表
+- [x] 重复执行 `add-coder init` 时 Prisma 迁移幂等
+- [x] 集成测试全部通过

package/templates/core/templates/01-/346/236/266/346/236/204//343/200/212ADD/345/274/200/345/217/221/345/267/245/344/275/234/350/267/257/345/276/204/344/270/216/346/226/207/346/241/243/345/215/217/345/220/214/350/247/204/350/214/203/343/200/213.md

@@ -0,0 +1,386 @@
+# ADD 开发工作路径与文档协同规范
+
+> ⚠️ **偏差声明**：
+> - 审计 API 使用 `agentAudit("PHASE", message, extra)`（event-based），需实现三通道输出（console + file + AuditLog 表）。add-coder 配套示例项目提供了审计日志器参考实现，见 `docs/{{projectName}}/knowledge/02-规范/《ADD可审计开发范式案例参考》.md`。
+
+本文档定义了 ADD 范式下从需求到交付的完整工作流、目录结构、文件命名规范及各角色的文档协同方式。
+
+---
+
+## 一、ADD 工作流全景
+
+ADD 不是"写代码时顺便打日志"，而是一套覆盖全开发周期的标准化流程。每个需求走一次完整闭环（Step 0 ~ Step 9）：
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  ADD 开发工作流（每个人类需求 = 一次完整闭环，Step 0 ~ Step 9）                  │
+├────────────┬─────────────────────────────────────────────────────────────────┤
+│  Step 0    │  文档先行（Documentation First）                                  │
+│  需求对齐   │  0.1 分析变更影响范围 → 0.2 搜索相关文档 → 0.3 阅读文档            │
+│            │  0.4 更新项目文档 → 0.5 生成 add-route → 0.6 确认文档合约一致性    │
+│            │  🚪 0.6.5 Review 结论回流至 Plan 与 Specs（强制卡位）               │
+│            │  🚪 0.7 原子闭包判定（Plan 级 + 轮次级）                           │
+│            │  产物：docs/*/knowledge/ 下的规划说明书、架构文档、规范文档           │
+│            │        .qoder/plans/{需求域名}-plan-v{n}.md                        │
+│            │        .qoder/plans/{需求域名}-add-route-v{n}.md                   │
+│            │        .qoder/reviews/{需求域名}-review-v{n}.md                    │
+│            │  阈值：check_dps（DPS ≥ 85 方可进入 Step 1）                        │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 1    │  功能分析与审计阶段定义                                            │
+│  审计定义   │  分析业务阶段 → 扩展 AgentAuditPhase 联合类型 → 确认审计通道        │
+│            │  产物：审计日志器中新增的阶段字面量类型（AgentAuditPhase 联合类型扩展）   │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 2    │  审计基础设施实现                                                  │
+│  基础设施   │  确认 agentAudit() 三通道可用（console + file + AuditLog 表）        │
+│            │  确认 agentAuditNodeStart/End/Error 等语义化封装函数可用             │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 3    │  业务逻辑实现与审计植入（审计点与功能实现同步进行）                     │
+│  代码实现   │  🚪 3.0 add-route 前置守卫（check_add_route_status）                │
+│            │  3.1 服务层审计植入（agentAudit 打点）                                │
+│            │  3.2 API Route 审计植入（traceId + 完整包裹）                        │
+│            │  🚪 3.6 add-route 闭环自检（check_add_route_completeness）           │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 3.5  │  实现审查（ADD-10 意图与实现的语义鸿沟）                              │
+│  实现审查   │  运行 spec checklist [T] 项 → 跨项目联调检查                         │
+│            │  产物：.qoder/reviews/{需求域名}-review-implementation-v{n}.md       │
+│            │        .qoder/reviews/{需求域名}-review-runtime-v{n}.md              │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 4    │  审计数据验证                                                      │
+│  审计验证   │  运行功能 → 收集审计数据 → check_phase_symmetry → check_failure_path │
+│            │  🚪 RAHS 闸门（check_rahs，RAHS ≥ 90 方可继续）                      │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 5    │  AI 自动合规检查                                                   │
+│  合规检查   │  读取审计日志 → 执行 5 项合规检查 → 生成合规报告 → AI 根据报告调整行为  │
+│            │  检查：阶段对称性 / 最小可观测单元 / 失败路径信息密度 / 三通道 / 回写     │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 6    │  从审计数据定位问题（仅 Step 4 发现异常时）                            │
+│  定位问题   │  分析日志文件 → 分析数据库审计字段 → 从数据推断根因                    │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 7    │  修复并验证（仅 Step 6 定位到根因时）                                 │
+│  修复验证   │  修复问题 → 重新运行验证 → 审计数据对比确认修复效果                     │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 8    │  收敛判断                                                          │
+│  收敛       │  全部收敛条件满足 → 执行验收闭环（回到 Step 0 第二阶段复核架构文档）      │
+│            │  → 生成 handoff 交接手册 → 记录 ADD-7 审计                            │
+│            │  🚪 RAHS 最终核定（RAHS ≥ 90 方可收敛）                               │
+│            │  未收敛 → 回到 Step 6 继续定位修复                                    │
+├────────────┼─────────────────────────────────────────────────────────────────┤
+│  Step 9    │  Report Closure（条件性：仅 runtime-fix plan 执行）                    │
+│  关闭发现   │  读取 report-handoff 模板 → 在 handoff 中追加 Report Closure 章节     │
+│            │  → 在 gateway.md 中追加 - [x] 标记 → 验证关闭                         │
+└────────────┴─────────────────────────────────────────────────────────────────┘
+```
+
+### 关键卡位（不可跳过）
+
+ADD 流程中有四个强制卡位，在任何情况下都不可跳过：
+
+| 卡位 | 位置 | 作用 | 跳过后果 |
+|------|------|------|---------|
+| **0.6.5 Review 回流** | Step 0 末尾 | Review 的 P0/P1 问题写回 Plan 和 Specs，防止"Review 发现了问题但 Plan 没改"的漂移 | 下游 AI 读到的 Plan 仍是未修正版本，等于没做 Review |
+| **0.7 原子闭包判定** | Step 0 末尾 | 确认 Plan 级闭包（单一业务功能）和轮次级闭包（文件边界独立、互不跨轮修改） | 同一文件被多轮反复修改，handoff 失去"可独立恢复"的基础 |
+| **3.0 add-route 前置守卫** | Step 3 入口 | check_add_route_status 校验 add-route 存在且 Step 闭环 | 无路线图直接写代码，实现必然偏离设计 |
+| **3.6 add-route 闭环自检** | Step 3 出口 | check_add_route_completeness 扫描所有 Step 产出项勾选状态 | 代码写完但遗漏 Step 3.5/4/5/8 的文档闭环 |
+
+### 关键设计要点
+
+| 设计原则 | 说明 |
+|---------|------|
+| **每轮原子闭包** | 不是按文件数量拆分，而是按"可独立提交、验证、审计、恢复"的最小业务闭包拆分 |
+| **人类评审节点** | 每轮 spec 必须经过人类 review（spec-review.md），AI 不擅自越过评审进入代码实现 |
+| **三件套不可跳过** | spec.md + tasks.md + checklist.md 三者齐备才能开始写代码 |
+| **日志代理用户 ID** | 所有 `AuditLog` 写入及业务表 `createdBy`/`createdById` 字段统一使用项目日志代理用户 ID 函数（禁止硬编码 `"system"` 等字符串）。详见 `.qoder/rules/project_rules.md` ADD-4 §日志代理用户 ID |
+| **四层审查** | 方案审查（ADD-9 方向验证）→ 实现审查（ADD-10 语义对齐）→ 运行时纠偏（ADD-11 证据持久化）→ 验收闭环（ADD-12 漂移校准），四道关卡覆盖全生命周期 |
+| **检查项 [T]/[R] 分拆** | checklist 中 [T] = 编译期可验证（AI 直接检查），[R] = 运行时验证（部署后确认，自动流转到 review-runtime.md）。[T] 全部通过时自动生成 review-runtime.md |
+| **跨对话接续** | 下一轮通过 `query_audit_logs` 恢复上游审计上下文，无需人类复述 |
+| **收敛判定** | 不只看编译通过，还要看 checklist 全覆盖 + 阶段对称性 + 失败路径审计等价 + RAHS ≥ 90 |
+| **双质量闸门** | DPS（上游文档精确度，Step 0 末尾）和 RAHS（下游执行健康度，Step 4/8）量化阻断注意力衰减链。详见 [§八](#八双质量闸门dps-与-rahs) |
+
+### 什么时候该用 ADD？
+
+ADD 不是万能范式。用错了阶段反而拖慢迭代速度。
+
+```
+项目周期：
+  ┌──────────┐    ┌──────────────┐    ┌──────────────────┐
+  │  MVP     │ →  │  MVP 收尾    │ →  │  持续迭代         │
+  │  SOLO    │    │  ADD 预埋    │    │  ADD 全流程       │
+  └──────────┘    └──────────────┘    └──────────────────┘
+```
+
+| 阶段 | 模式 | 做什么 | 为什么不早/不晚 |
+|------|------|--------|----------------|
+| **MVP 早期** | SOLO | 快速验证想法，一个人加一个 AI 足以跑通核心链路 | 需求还在漂移，今天写的规则明天就改——播种前先圈地 |
+| **MVP 收尾** | ADD 预埋 | 核心功能收敛后，做三件事：① 写架构文档 ② 收敛类型定义 ③ 定义核心接口合约 | 功能已经稳定到可以说清楚边界了。此时不预埋，持续迭代时 AI 会在散落的 if 上继续贴 if，债务不可逆 |
+| **持续迭代** | ADD 全流程 | 每个需求走完整闭环：Plan → Review → Handoff → Spec → 代码+审计 → 收敛判断 | 系统复杂度超过人脑容量，没有裁决层和审计链路就是盲飞 |
+
+> **一句话判断**：如果你还在"这个功能到底要不要做"的阶段，用 SOLO 快跑；如果你已经到了"核心链路跑通了，接下来要稳着加功能"的阶段，ADD 预埋；如果你已经在修复"改了这里那里爆"的问题，ADD 晚了，但赶紧上还来得及止损。
+
+---
+
+## 二、目录结构与可见性
+
+| 目录 | 内容 | 可见性 |
+|------|------|--------|
+| `docs/哲学理论/` | 哲学理论基础文章 | 公开 |
+| `{{docsDir}}/` | 项目文档（需求/架构/规范） | 公开 |
+| `TODO/` | 开源协作 TODO，与 docs/ 平级 | 公开 |
+| `.qoder/plans/` | 需求方案 + 任务拆分 + 轮间交接手册 | 开发内部 |
+| `.qoder/reviews/` | 方案评审 + 逐轮 spec 评审 | 开发内部 |
+| `.qoder/specs/` | 每轮 spec + tasks + checklist（三件套） | 开发内部 |
+| `.qoder/rules/` | 项目规则文件（权威约束） | 开发内部 |
+| `.qoder/skills/` | SKILL 行为定义（AI 助手的标准行为模式） | 开发内部 |
+| `.qoder/scripts/` | 工具脚本 + MCP 服务器 | 开发内部 |
+
+### 目录层级决策原则
+
+```
+公开可见 = docs/  + TODO/
+          ↑ 面向社区、贡献者、学术引用者
+
+开发内部 = .qoder/
+          ↑ 面向 AI 助手 + 核心开发者（不影响外部用户克隆体验）
+```
+
+- `TODO/` 与 `docs/` 平级而非嵌套在 `docs/` 下：TODO 是**行动清单**（"我们计划做什么"），docs 是**知识资产**（"我们做了什么、是什么"），语义不同不应混放
+- `plans/` + `reviews/` + `specs/` 三者都在 `.qoder/` 下：它们是 ADD 开发流程的产物，面向 AI 和开发者，不属于公开文档
+- `plans/` 下同时放 plan + add-route + handoff：三者属于"需求理解与任务拆分"这个完整的大阶段，放在同一个目录保证阶段内文件的连续性
+
+---
+
+## 三、文件命名规范
+
+### 格式
+
+```
+{需求域名}-{本轮核心内容}-{产物类型}-v{版本号}
+```
+
+### 组成部分说明
+
+| 部分 | 说明 | 约束 |
+|------|------|------|
+| 需求域名 | 本次需求的唯一标识，必须与对应的需求/功能保持一致 | 一个需求的所有文件共享同一需求域名前缀 |
+| 本轮核心内容 | 该文件描述的本轮/本阶段核心工作（中文） | 简介明了，能从文件名判断文件用途 |
+| 产物类型 | 该文件的工作流角色（英文关键词） | `plan` / `add-route` / `handoff` / `review` / `spec-review` |
+| 版本号 | 递增数字 | `v1`, `v2`, ... |
+
+### 命名示例
+
+```
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-plan-v1.md
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-7轮原子事务拆分-add-route-v1.md
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-7轮原子事务交接-handoff-v1.md
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-方案评审-review-v1.md
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-round1-类型收敛-thinkingLevel路由-spec-review-v1.md
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-round2-响应策略裁决-spec-review-v1.md
+{{projectName}}-多轮对话能力专家链路优化统一状态管理-round3-专家注册分析上下文-spec-review-v1.md
+```
+
+### 命名带来的好处
+
+1. **可追溯**：从文件名直接回答"什么需求、第几轮、什么工作、第几版本"
+2. **可聚合**：`ls {{projectName}}-*` 一条命令捞出全部关联文件
+3. **可交接**：给下一个开发者/AI 的文件路径即包含完整上下文
+
+---
+
+## 四、specs 目录命名
+
+格式：`{需求域名}-{闭包名}-v{版本号}`
+
+| 目录 | 对应的工作 |
+|------|-----------|
+| `{{projectName}}-type-convergence-v1` | 第1轮：类型收敛 + thinkingLevel 路由 |
+| `{{projectName}}-response-strategy-v1` | 第2轮：响应策略裁决 |
+| `{{projectName}}-expert-registry-v1` | 第3轮：专家注册 + 分析上下文 |
+| `{{projectName}}-pipeline-integration-v1` | 第4轮：管线集成 |
+| `{{projectName}}-semantic-cache-v1` | 第5轮：语义缓存 |
+| `{{projectName}}-evolution-loop-v1` | 第6轮：演化闭环 |
+| `{{projectName}}-audit-pipeline-v1` | 第7轮：审计管线 |
+
+---
+
+## 五、工作流三大阶段与目录映射
+
+```
+需求理解 + 任务拆分  →  .qoder/plans/      （plan + add-route + handoff）
+    │
+    ↓
+评审                  →  .qoder/reviews/    （plan-review + roundN-spec-review）
+    │
+    ↓
+Spec 执行             →  .qoder/specs/       （三件套：spec + tasks + checklist）
+```
+
+每个阶段的产物只放在一个目录下，不在多个目录重复存放。
+
+---
+
+## 六、实际案例：{{projectName}} 7 轮原子事务
+
+完整流程见：
+
+| 阶段 | 文件 | 说明 |
+|------|------|------|
+| 需求方案 | `.qoder/plans/{{projectName}}-多轮对话能力专家链路优化统一状态管理-plan-v1.md` | 总体设计 |
+| 拆分拓扑 | `.qoder/plans/{{projectName}}-多轮对话能力专家链路优化统一状态管理-7轮原子事务拆分-add-route-v1.md` | 7 轮依赖拓扑 |
+| 方案评审 | `.qoder/reviews/{{projectName}}-多轮对话能力专家链路优化统一状态管理-方案评审-review-v1.md` | 可行性验证 |
+| 交接手册 | `.qoder/plans/{{projectName}}-多轮对话能力专家链路优化统一状态管理-7轮原子事务交接-handoff-v1.md` | 轮间输入输出 |
+| 第1轮 spec | `.qoder/specs/{{projectName}}-type-convergence-v1/` | 类型收敛三件套 |
+| 第1轮评审 | `.qoder/reviews/{{projectName}}-多轮对话能力专家链路优化统一状态管理-round1-类型收敛-thinkingLevel路由-spec-review-v1.md` | spec 人工 review |
+| ... | ... | 第2-7 轮同理 |
+
+---
+
+## 七、规范出处
+
+本文档内容同时体现在：
+
+- **`.qoder/rules/project_rules.md`** 中的 ADD-8 规则（权威约束，AI 助手强制执行）
+- **`README.md`** 中的三、ADD 编程范式章节（面向外部读者的简明版本）
+- **本文档**（面向开发者的完整版本，包含案例和决策说明）
+
+---
+
+## 八、双质量闸门：DPS 与 RAHS
+
+> **引入背景**（2026-06-11）：ADD 流程中，从 Plan → Review → Specs → 代码实现，存在一条注意力衰减链——Plan 概括度越高，Review 需脑补越多，注意力越稀释，导致 Specs 结构性遗漏，最终引发实现偏差与敷衍式返工。DPS 和 RAHS 分别在上游和下游设置量化闸门，用数字阻断这条衰减链。
+
+### 8.1 问题根因：上游概括度决定下游漂移量
+
+```
+Plan 粗粒度
+  ↓
+Review 需自行展开细节 → 注意力被多维度稀释
+  ↓
+Review 只覆盖部分维度 → 缺口进入 Specs
+  ↓
+Specs 基于不完整的 Review 生成 → Requirements 缺失或模糊
+  ↓
+Step 3 实现时发现缺口 → 临时补 → 敷衍 → 与 Plan 脱节
+```
+
+**核心命题**：Plan 概括不是美德，是债务。Plan 每缺一个细节，下游就要脑补一次，注意力就被稀释一分。
+
+#### 8.1.1 Plan 与 Spec 的职责边界
+
+"DPS 要求 Plan 不能太概括"与"Plan 不能膨胀成 Spec"是同一枚硬币的两面。边界由**信息的目的**而非**信息的详细程度**决定：
+
+| 维度 | Plan（架构意图） | Spec（实现规格） |
+|------|------------|------------|
+| **定位** | 回答"改什么、为什么改、改哪里" | 回答"怎么改、改到什么程度算完成" |
+| **接收方** | Review（人评审方向是否对）→ 生成 Specs（AI 展开为规格） | Step 3 代码实现（AI 按规格写代码）+ Step 4 验证 |
+| **文件粒度** | 精确到**文件路径**：`src/agents/nodes/retrieval.ts` | 精确到**函数签名**：`searchKnowledgeDocuments(query, topK, opts?: SearchOptions)` |
+| **类型定义** | 描述**接口形状的意图**："新增 GroundingStatus 类型，含 ready/documentCount/lastSyncedAt/indexHealth 四个字段" | 给出**完整类型定义**：`interface GroundingStatus { ready: boolean; ... }` |
+| **数据流** | 描述**方向和节点**："retrieval → grounding.ready() → collection 检索 / where 降级" | 给出**精确的控制流**：WHEN-THEN 场景、分支条件、审计点位置 |
+| **验收标准** | Phase 级别的**业务验收**："3 个 Expert collection 创建且文档数 ≥ 预期" | Task 级别的**可执行验证**：`expert_pest_risk.count() ≥ 5` |
+| **禁止项** | 架构级**设计约束**："禁止删除全局 {{projectName}} collection" | 实现级**操作禁止**："禁止一次性迁移超过 3 个 Expert" |
+
+**一句话边界**：
+
+> Plan 写到让 Review 能判断"方向对不对，有没有遗漏维度"的程度；Spec 写到让 AI 能直接写代码、人能直接打钩验收的程度。
+
+**反例**：Plan 里写 `searchKnowledgeDocuments() 签名扩展` 而不给新签名——这就是概括导致的注意力稀释，Review 必须脑补签名才能判断覆盖度。应该在 Plan 的 Phase 描述中给出签名意图（参数从两个变一个 options 对象），但不在 Plan 中写完整 TypeScript 类型定义——那留给 Spec。
+
+**DPS 的 Plan 粒度检查正是按此边界设计的**：
+- ✅ DPS 要求 Plan 中每个 Task 指定文件路径（属于"改哪里"）
+- ✅ DPS 要求 Plan 中每个 Phase 有独立验收标准（属于"改到什么程度"的架构表述）
+- ❌ DPS 不要求 Plan 包含完整函数签名（那是 Spec 的职责）
+- ❌ DPS 不要求 Plan 包含 WHEN-THEN 场景（那是 Spec 的职责）
+
+### 8.2 DPS：Documentation Precision Score（上游文档质量）
+
+在 Step 0 完成后、进入 Step 1 前调用 `check_dps`，量化 Plan → Review → Specs 三级文档的精确度。
+
+| 维度 | 权重 | 检查内容 |
+|------|:----:|------|
+| Plan 可执行粒度 | 30% | 每个 Phase 是否有独立验收标准；每个 Task 是否指定具体文件；是否含占位词（"待定"/"TBD"） |
+| Review 覆盖完备度 | 35% | Review 是否覆盖 Plan 的全部架构维度——数据模型、API 签名、错误路径、数据迁移、兼容性、性能、存储 |
+| Specs 精确度 | 35% | Specs Requirements 数与 Plan Phase 数是否 1:1 映射（缺失的 Phase 意味着无形式化验收标准） |
+
+**判定阈值**：
+
+| DPS | 判定 | 动作 |
+|-----|:--:|------|
+| ≥ 85 | 🟢 | 进入 Step 1 |
+| 70–84 | 🟡 | 回退补齐短板（补 Review 缺失维度 / Specs 缺失 Requirement） |
+| < 70 | 🔴 | 回退细化 Plan 本身——粒度不足是下游漂移的根因 |
+
+### 8.3 RAHS：Round Attention Health Score（下游执行健康度）
+
+在 Step 4（审计数据验证）和 Step 8（收敛判断）调用 `check_rahs`，量化本轮代码实现的注意力漂移程度。
+
+| 维度 | 权重 | 量化方式 | 设计理由 |
+|------|:----:|------|------|
+| 范围保真度 | 30% | `|plannedFiles ∩ modifiedFiles| / |plannedFiles|` | 文件扩散是注意力漂移最直接的信号 |
+| 类型安全 | 20% | `max(0, 100 − tscErrors × 10)` | 渐进扣分而非二元 pass/fail |
+| 审计完整度 | 25% | `recordCount / plannedFileCount` | ADD-7 是防漂移的制度兜底 |
+| Spec 合规 | 15% | `check_spec_sync` 通过/失败 | 文档-代码一致性 |
+| 阶段对称性 | 10% | `check_phase_symmetry` 通过/失败 | 审计阶段标记完整性 |
+
+**判定阈值**：
+
+| RAHS | 判定 | 动作 |
+|------|:--:|------|
+| ≥ 90 | 🟢 | 进入下一 Step |
+| 70–89 | 🟡 | 自检：范围扩散？审计漏记？类型错误？ |
+| < 70 | 🔴 | 注意力漂移严重，强制返工 Step 3 |
+
+### 8.4 DPS → RAHS 管道关系
+
+两个闸门不是孤立的——上游 DPS 直接影响下游 RAHS：
+
+```
+DPS（上游文档质量）          RAHS（下游执行质量）
+─────────────────          ─────────────────
+Plan 粒度 ──→ Review 覆盖度 ──→ Specs 精确度 ──→ 范围保真度
+                                       │              │
+                                       └──→ 审计完整度 ←┘
+                                                 │
+                                         阶段对称性
+                                         类型安全
+                                         Spec 合规
+```
+
+- DPS 高 → Specs 无结构性遗漏 → Step 3 实现时不需脑补 → RAHS 大概率健康
+- DPS 低 → Specs 有缺口 → Step 3 临时补 → 范围扩散 + 审计漏记 → RAHS 必然漂移
+
+**因此**：DPS 是 RAHS 的先决条件。DPS 不过，不要指望 RAHS 能过——不要进入 Step 3。
+
+### 8.5 在 ADD 管线中的卡位
+
+```
+Step 0 文档先行
+  │
+  ├─ specs 三元组生成
+  ├─ Plan Review 生成
+  │
+  └─ 🚪 DPS 闸门（§0.8 of add-route）
+       │  check_dps({ planKeyword: "..." })
+       │
+Step 1 → Step 2 → Step 3（代码实现）
+                       │
+Step 4 审计数据验证
+  │
+  └─ 🚪 RAHS 闸门（§4.6 of add-route）
+       │  check_rahs({ planKeyword: "..." })
+       │
+Step 5 → Step 6/7（仅异常时）
+              │
+Step 8 收敛判断
+  │
+  └─ 🚪 RAHS 最终核定
+       │  check_rahs(...) → RAHS ≥ 90 方可收敛
+```
+
+### 8.6 MCP 工具与策略配置
+
+| 工具 | 调用时机 | 对应 sync-policy 项 |
+|------|---------|-------------------|
+| `check_add_route_status` | Step 3 前（前置守卫） | `"add_route_exists": { "enabled": true, "severity": "block" }` |
+| `check_add_route_completeness` | Step 3 代码完成后自检 | `"add_route_completeness": { "enabled": true, "severity": "block" }` |
+| `check_dps({ planKeyword })` | Step 0 末尾（进入 Step 1 前） | `"dps": { "enabled": true, "severity": "block", "threshold": 85 }` |
+| `check_rahs({ planKeyword })` | Step 4 末尾 + Step 8 收敛 | `"rahs": { "enabled": true, "severity": "block", "threshold": 90 }` |
+
+策略文件位于 `.qoder/sync-policy.json`，重型 add-route 模板已内置对应的 §0.8 / §4.6 闸门段落。