add-coder 0.1.5 → 0.1.8

package/templates/core/plans/2026-07/08/farm-agent-add-coder-npm-package-plan-v1.md

@@ -11,6 +11,7 @@
   - ADD Route: `.qoder/plans/2026-07/08/farm-agent-add-coder-npm-package-add-route-v1.md` ✅
   - Handoff: `.qoder/plans/2026-07/08/farm-agent-add-coder-npm-package-handoff-v1.md` ✅
   - Review: `.qoder/reviews/farm-agent-add-coder-npm-package-review-v1.md` ✅
+  - Review v2: `.qoder/reviews/farm-agent-add-coder-npm-package-review-v2.md` ✅ — 代码实现评审，2 条 P0（spawnSync catch 失能、ask 重复定义）
 - **ADD-7 审计策略**:
 
 | 文件 | targetType | action | beforeState | afterState | 状态 |
@@ -242,10 +243,11 @@ packages/add-coder/
 │   │   ├── skills/                     # add-paradigm/SKILL.md, session-init/SKILL.md
 │   │   ├── docs/                       # 15 个 .md 模板（plan/spec/tasks/checklist/handoff/review/add-route 等）
 │   │   ├── docs-schema/                # 15 个 .schema.json
+│   │   ├── plans/                      # 示例 plans（含 add-coder 6轮范例）
+│   │   ├── specs/                      # 示例 specs（含 add-coder spec/tasks/checklist）
 │   │   ├── rules/                      # project_rules.md, theory-practice-map.toml
 │   │   ├── vocabulary/                 # add-governance-vocabulary.md
 │   │   ├── scripts/                    # mcp-server.ts, add-coder-mcp-server.ts
-│   │   ├── prisma/                      # add.prisma（ADD 治理模型，init 时复制到用户项目）
 │   │   ├── reports/                    # 7 个 report 模板
 │   │   └── tools/                      # README.md
 │   │
@@ -273,6 +275,90 @@ packages/add-coder/
 └── README.md
 ```
 
+
+# ──── npx add-coder init 后的用户项目结构 ────
+
+```
+用户项目/
+├── .add/                               # ★ ADD 蓝图（推荐路径）
+│   ├── agents/                         # ← templates/core/agents/
+│   ├── skills/                         # ← templates/core/skills/
+│   ├── templates/                      # ← templates/core/docs/（.md 模板 + .schema.json，扁平）
+│   ├── rules/                          # ← templates/core/rules/
+│   ├── vocabulary/                     # ← templates/core/vocabulary/
+│   ├── scripts/                        # ← templates/core/scripts/
+│   ├── hooks/                          # ← templates/adapters/{target}/hooks/
+│   ├── plans/                          # ← templates/core/plans/
+│   ├── specs/                          # ← templates/core/specs/
+│   ├── reports/                        # ← templates/core/reports/
+│   ├── tools/                          # ← templates/core/tools/
+│   ├── debug-dump/                     # ← templates/shared/debug-dump/（空目录占位）
+│   ├── repowiki/                       # ← templates/shared/repowiki/（空目录占位）
+│   ├── reviews/                        # ← 用户自建（init 后空目录）
+│   ├── mcp.json                        # ← templates/adapters/{target}/mcp.json
+│   ├── settings.json                   # ← templates/adapters/{target}/settings.json
+│   └── sync-policy.json                # ← templates/adapters/qoder/sync-policy.json
+│
+├── .qoder/                             # ★ Qoder IDE 配置
+│   ├── agents/                         # ← 同 .add/agents/
+│   ├── skills/                         # ← 同 .add/skills/
+│   ├── templates/                      # ← 同 .add/templates/
+│   ├── rules/                          # ← 同 .add/rules/
+│   ├── vocabulary/                     # ← 同 .add/vocabulary/
+│   ├── scripts/                        # ← 同 .add/scripts/
+│   ├── hooks/                          # ← adapter/qoder/hooks/（Qoder 专属 matcher）
+│   ├── plans/                          # ← 同 .add/plans/
+│   ├── specs/                          # ← 同 .add/specs/
+│   ├── reports/                        # ← 同 .add/reports/
+│   ├── tools/                          # ← 同 .add/tools/
+│   ├── debug-dump/                     # ← 同 .add/debug-dump/
+│   ├── repowiki/                       # ← 同 .add/repowiki/
+│   ├── reviews/                        # ← 同 .add/reviews/
+│   ├── mcp.json                        # ← adapter/qoder/mcp.json
+│   ├── settings.json                   # ← adapter/qoder/settings.json
+│   └── sync-policy.json                # ← adapter/qoder/sync-policy.json
+│
+├── .claude/                            # ★ Claude Code 配置
+│   ├── agents/                         # ← 同 .add/agents/
+│   ├── skills/                         # ← 同 .add/skills/
+│   ├── templates/                      # ← 同 .add/templates/
+│   ├── rules/                          # ← 同 .add/rules/
+│   ├── vocabulary/                     # ← 同 .add/vocabulary/
+│   ├── scripts/                        # ← 同 .add/scripts/
+│   ├── hooks/                          # ← adapter/claude/hooks/（Claude 标准工具名）
+│   ├── plans/                          # ← 同 .add/plans/
+│   ├── specs/                          # ← 同 .add/specs/
+│   ├── reports/                        # ← 同 .add/reports/
+│   ├── tools/                          # ← 同 .add/tools/
+│   ├── debug-dump/                     # ← 同 .add/debug-dump/
+│   ├── repowiki/                       # ← 同 .add/repowiki/
+│   ├── reviews/                        # ← 同 .add/reviews/
+│   ├── mcp.json                        # ← adapter/claude/mcp.json
+│   └── settings.json                   # ← adapter/claude/settings.json
+│
+├── .vscode/                            # ★ VS Code 配置
+│   ├── settings.json                   # ← templates/adapters/vscode/settings.json
+│   ├── launch.json                     # ← templates/adapters/vscode/launch.json
+│   ├── tasks.json                      # ← templates/adapters/vscode/tasks.json
+│   └── extensions.json                 # ← templates/adapters/vscode/extensions.json
+│
+├── prisma/
+│   ├── schema.prisma                   # 用户已有或 prisma init 创建
+│   └── add.prisma                      # injectPrisma 注入（来自 npm 包内置）
+│
+└── .env.development                    # prisma init 创建，用户配置 DATABASE_URL
+```
+
+> **部署策略**：`templates/core/` 内容复制到 `.add/`、`.qoder/`、`.claude/` 三个目录。
+> IDE 只认自身的 magic path（`.qoder/` / `.claude/`），必须各自包含完整内容。
+> `.add/` 保留作为 add-coder 推荐蓝图，供未来工具链引用。
+
+> **⚠️ 改造待执行**：当前 `renderCore()` 仅输出到 `.add/`，需改造为三目录并行输出：
+> 1. `src/core/renderer.ts`：`renderCore()` 返回值改为 `Map<string, string>[]`（三份）
+> 2. `src/cli/commands/init.ts`：core 文件写入 `.add/` `.qoder/` `.claude/` 三个目标
+> 3. adapter renderers：不再单独部署 core 内容，只处理 adapter 专属文件（hooks/mcp/settings）
+> 4. 写入去重：三目录同名文件只写一次，后两次 skip（内容相同）
+
 **关键命名决策**：旧的 `templates/templates/` 嵌套命名 → 改为 `templates/core/docs/`，避免 `templates/templates/` 这种令人困惑的路径。
 
 **渲染器路径约定**：
@@ -366,6 +452,25 @@ const adapterDir = path.join(TEMPLATES_ROOT, 'adapters', target)
 > **add-coder 作为通用转录引擎**：类似 Prisma 的 `prisma generate`——读 caijue.toml，生成策略代码。
 > 引擎本身不关心 caijue.toml 的内容来源，只负责"TOML → TS"的编译时转录。
 
+#### 3.5.1 实际实现架构（偏离原 Plan §3.5.2，以 handoff §7 为准）
+
+```
+caijue.toml（索引）          *-rules.toml（规则参数）      strategies/*.ts
+─────────────────           ────────────────────        ┌──────────────────┐
+[[caijue]]                  detect-rules.toml    →      │ GENERATED (转录)  │
+  rules = "detect-rules"    prisma-rules.toml    →      │ DETECT_RULES=[]   │
+  impl = "strategies/..."   adapter-rules.toml   →      │ PRISMA_CONFIG={}   │
+                            writer-rules.toml    →      ├──────────────────┤
+                                                        │ USER CODE (手写)   │
+转录流程：                                                 │ detectIDE()       │
+npm run generate → transcribe.ts → GENERATED 区块         │ injectPrisma()    │
+                                                        └──────────────────┘
+
+- caijue.toml 只做索引，不耦合规则逻辑
+- *-rules.toml 定义规则参数，transcribe.ts 产出 GENERATED 区块
+- USER CODE 手写业务逻辑，npm run generate 不覆盖
+```
+
 #### 3.5.1 裁决点清单
 
 | 裁决点 | 当前位置 | 决策内容 | 归入 caijue |
@@ -525,6 +630,8 @@ packages/add-coder/
 
 **验收**：在空白 Prisma 项目中执行 `prisma migrate dev --schema=prisma/` 成功创建 DevOperation 和 AuditLog 表
 
+> **Review v2 回流（P0-1）**：`prisma-injector.ts` 中 `spawnSync` 返回状态须检查 `r.status`，不可依赖 try/catch。迁移失败时 `add.prisma` 回滚删除。
+
 #### Task 1: 清理硬编码 + 参数化 core 模板
 
 **范围**：`packages/add-coder/templates/` 下所有文件（共 ~70 个文件）
@@ -741,6 +848,9 @@ packages/add-coder/
 
 **回流机制**：
 - Review 发现的 P0/P1 问题回写至 Plan 对应章节
+  - Review v2 P0-1（spawnSync catch 失能）：已在 Task 0 补充验收项
+  - Review v2 P0-2（ask 重复定义）：已记录至 Task 1（CaijueHub 重构时一并提取到 utils）
+  - Review v2 P1-1/2/3（unlinkSync 缺口、gitignore）：已记录至 CI 基建清单
 - 回流完成后方可进入 Step 1 实施
 - P2 问题在 Step 3 实施前解决或记录为 Known Issue
 

package/templates/core/scripts/mcp-server.ts

@@ -23,9 +23,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod"
 import { readFile, readdir, stat, mkdir, writeFile } from "fs/promises"
-import { join, relative, basename } from "path"
+import { join, relative } from "path"
 import { existsSync } from "fs"
-import { execSync } from "child_process"
+import { spawnSync } from "child_process"
 import { PrismaClient, Prisma } from "@prisma/client"
 
 const prisma = new PrismaClient({
@@ -51,6 +51,31 @@ async function readFileSafe(filePath: string): Promise<string | null> {
   }
 }
 
+// ── ADD 文档模板校验（共享函数，供 create_plan / check_add_compliance / check_spec_sync 等复用）──
+
+interface GuardResult { ok: boolean; issues: string }
+
+async function validateDocWithGuard(filePath: string): Promise<GuardResult> {
+  const guardScript = join(PROJECT_ROOT, MAGIC_DIR, "hooks", "doc-format-guard.sh")
+  if (!existsSync(guardScript)) return { ok: true, issues: "" }
+  const content = await readFileSafe(filePath)
+  if (!content) return { ok: false, issues: "文件无法读取" }
+  const guardInput = JSON.stringify({
+    tool_input: { file_path: filePath, file_content: content },
+  })
+  const guard = spawnSync("/bin/bash", [guardScript], {
+    input: guardInput,
+    encoding: "utf-8",
+    timeout: 15000,
+    cwd: PROJECT_ROOT,
+    env: { ...process.env, MAGIC_DIR },
+  })
+  if (guard.status === 2 || guard.stderr?.includes("校验不通过")) {
+    return { ok: false, issues: guard.stderr || guard.stdout || "校验失败" }
+  }
+  return { ok: true, issues: "" }
+}
+
 /** 递归读取目录下所有文件（扁平化返回），支持 ${MAGIC_DIR}/plans/2026-06/05/ 等分层结构 */
 async function readdirRecursive(dir: string): Promise<string[]> {
   const results: string[] = []
@@ -2080,7 +2105,9 @@ server.registerTool(
         return errorResponse(`未找到匹配的 Plan 文件（关键词: ${args.planKeyword}）`)
       }
       const planPath = join(plansDir, planMatch)
+      const planGuard = await validateDocWithGuard(planPath)
       lines.push(`Plan: ${planMatch}`)
+      if (!planGuard.ok) lines.push(`  ⚠️ 模板校验: ${planGuard.issues.split("\n")[0]}`)
 
       // 2. 从 Plan 中提取关联的 spec 目录名
       const planContent = await readFileSafe(planPath)
@@ -2387,9 +2414,10 @@ server.registerTool(
       // 5. Git diff 统计
       let changedFiles: string[] = []
       if (isEnabled("gitDiff")) {
-        const { execSync } = await import("child_process")
+        const { spawnSync } = await import("child_process")
         try {
-          const diffStat = execSync("git diff --name-only", { cwd: PROJECT_ROOT, encoding: "utf-8", timeout: 5000 })
+          const diff = spawnSync("git", ["diff", "--name-only"], { cwd: PROJECT_ROOT, encoding: "utf-8", timeout: 5000 })
+          const diffStat = diff.stdout || ""
           changedFiles = diffStat.trim().split("\n").filter(Boolean)
         } catch {
           lines.push("Git diff: 无法获取（可能无 git 仓库或无暂存变更）")
@@ -2576,6 +2604,9 @@ server.registerTool(
         return errorResponse(`add-route 完整性扫描失败：无法读取文件 ${matchedFile}`)
       }
 
+      // 模板格式校验
+      const routeGuard = await validateDocWithGuard(filePath)
+
       const lines = content.split("\n")
 
       // === 3. 解析 Step 结构和勾选状态 ===
@@ -2681,6 +2712,7 @@ server.registerTool(
         "",
         `整体完成度: ${globalChecked}/${globalTotal} (${completionRate}%)`,
         `状态: ${isComplete ? "✅ complete — add-route 完整闭环" : "⚠️ incomplete — 存在未勾选 Step"}`,
+        `模板校验: ${routeGuard.ok ? "✅ 通过" : `⚠️ ${routeGuard.issues.split("\n")[0]}`}`,
         "",
       ]
 
@@ -3198,8 +3230,9 @@ server.registerTool(
       let scopeScore = 100
       let changedFiles: string[] = []
       try {
-        const { execSync } = await import("child_process")
-        const diffStat = execSync("git diff --name-only", { cwd: PROJECT_ROOT, encoding: "utf-8", timeout: 5000 })
+        const { spawnSync } = await import("child_process")
+        const diff = spawnSync("git", ["diff", "--name-only"], { cwd: PROJECT_ROOT, encoding: "utf-8", timeout: 5000 })
+        const diffStat = diff.stdout || ""
         changedFiles = diffStat.trim().split("\n").filter(Boolean)
       } catch { /* ignore */ }
 
@@ -3240,12 +3273,13 @@ server.registerTool(
       // ====== 维度二：类型安全（权重 20%） ======
       let typeScore = 100
       try {
-        const { execSync } = await import("child_process")
-        const tscOut = execSync("npx tsc --noEmit 2>&1 || true", {
+        const { spawnSync } = await import("child_process")
+        const tsc = spawnSync("npx", ["tsc", "--noEmit"], {
           cwd: PROJECT_ROOT,
           encoding: "utf-8",
           timeout: 30000,
         })
+        const tscOut = (tsc.stdout || "") + (tsc.stderr || "")
         // 统计 error TS 行数
         const errorLines = tscOut.split("\n").filter(l => l.includes("error TS")).length
         typeScore = Math.max(0, 100 - errorLines * 10)
@@ -3431,20 +3465,28 @@ server.registerTool(
 
       // 写入 Plan 文件
       await writeFile(filePath, content, "utf-8")
+
+      // 写后校验
+      const guard = await validateDocWithGuard(filePath)
+      if (!guard.ok) {
+        try { await import("fs/promises").then(m => m.unlink(filePath)) } catch { }
+        return errorResponse(`Plan 模板校验不通过，拒绝写入：\n${guard.issues}`)
+      }
+
       parts.push(`✅ Plan 文件已创建: ${relativePath}`)
 
       // 更新 index.md
       const indexScript = join(PROJECT_ROOT, "scripts", "gen-plan-index.sh")
       if (existsSync(indexScript)) {
-        try {
-          const result = execSync(`/bin/bash "${indexScript}"`, {
-            cwd: PROJECT_ROOT,
-            encoding: "utf-8",
-            timeout: 10000,
-          })
-          parts.push(`📋 index.md 已更新: ${result.trim()}`)
-        } catch (indexErr) {
-          parts.push(`⚠️ index.md 更新失败（将在 crontab 或下次调用时自动更新）: ${indexErr instanceof Error ? indexErr.message : String(indexErr)}`)
+        const result = spawnSync("/bin/bash", [indexScript], {
+          cwd: PROJECT_ROOT,
+          encoding: "utf-8",
+          timeout: 10000,
+        })
+        if (result.status === 0) {
+          parts.push(`📋 index.md 已更新: ${result.stdout?.trim() || "ok"}`)
+        } else {
+          parts.push(`⚠️ index.md 更新失败: ${result.stderr?.trim() || result.error?.message || "unknown"}`)
         }
       } else {
         parts.push(`⚠️ gen-plan-index.sh 不存在，index.md 将在 crontab 自动更新`)

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

@@ -17,7 +17,7 @@
 
 | 轮次 | 变更概要 | 涉及文件 |
 |:--:|------|------|
-| 1 | Prisma 模型准备 + 清理硬编码 | `templates/core/prisma/add.prisma`、`src/cli/prisma-injector.ts`、`templates/` 下约 70 个文件 |
+| 1 | Prisma 模型准备 + 清理硬编码 | `src/cli/prisma-injector.ts`（add.prisma 内置在 npm 包）、`templates/` 下约 70 个文件 |
 | 2 | 模板目录重组 + 适配器架构搭建 | `templates/core/`、`src/adapters/`、`src/core/`、旧 `templates/` 迁移 |
 | 3 | 三端适配器实现（Claude → Qoder → VS Code 串行） | 见下方 Hook 清单 |
 | 4 | 配置系统（Zod schema）+ CLI 重写 | `src/config/`、`src/cli/`、`bin/add-coder.js`、`tsup.config.ts` |
@@ -171,6 +171,17 @@
 - **WHEN** 重复执行 `add-coder init`
 - **THEN** `prisma migrate dev` 不报错（已应用的迁移自动跳过）
 
+#### Scenario: 三目录部署（core 内容同步到 IDE magic path）
+
+- **WHEN** 执行 `init` 渲染 core 模板后
+- **THEN** `templates/core/` 的所有文件 SHALL 同时写入 `.add/`、`.qoder/`、`.claude/` 三个目标目录
+- **AND** adapter renderers SHALL 只处理 adapter 专属文件（hooks/mcp.json/settings.json/sync-policy.json），不再单独渲染 core 内容
+
+**改造步骤**：
+1. `src/core/renderer.ts`：`renderCore()` 返回值改为输出三份文件的映射（`.add/` + `.qoder/` + `.claude/`）
+2. `src/cli/commands/init.ts`：写入阶段对三目录同名文件去重（内容相同则 skip）
+3. `src/adapters/{claude,qoder,vscode}/renderer.ts`：删除 core 渲染逻辑，只保留 hooks + mcp + settings 等 adapter 专属文件
+
 ---
 
 ### Requirement: 适配器三层架构
@@ -317,10 +328,15 @@
 
 系统 SHALL 在空白项目中通过完整的 init 流程验证。
 
-#### Scenario: 零配置可用
+#### Scenario: 空项目 init
 
 - **WHEN** 在空白项目中执行 `npx add-coder init`
-- **THEN** 零配置生成完整 ADD 模板（skills/agents/templates/rules/hooks 自动就位）
+- **THEN** `.add/` `.qoder/` `.claude/` 三目录均含完整 ADD 内容（agents/skills/templates/rules/vocabulary/scripts/hooks/plans/specs/reports/tools），`.vscode/` 含 IDE 配置
+
+#### Scenario: plans/specs 示例
+
+- **WHEN** 用户首次 init
+- **THEN** `.qoder/plans/` 含 add-coder 6轮范例，`.qoder/specs/` 含 spec/tasks/checklist 范例
 
 #### Scenario: 三端兼容