add-coder 0.1.0

package/templates/core/skills/session-init/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: "session-init"
+description: "会话上下文恢复（稀疏推理）。每次新对话启动时，必须执行本 SKILL 恢复之前的开发上下文。这是 AI 助手的强制性初始化流程，不可跳过。"
+---
+
+# 会话初始化：稀疏推理上下文恢复
+
+## 为什么必须执行本 SKILL
+
+每次新对话启动时，AI 助手对之前的开发活动处于"零知识"状态。
+通过查询 `AuditLog` 表，可以稀疏地恢复之前的开发脉络。
+
+**不执行本 SKILL 的后果**：
+- 无法知道之前改了什么代码
+- 无法知道 API 合约发生了什么变化
+- 可能做出冲突的修改
+- 需要用户重复说明历史背景
+- **遗漏未关闭的运行时发现**——部署后暴露但未被追踪的异常会持续累积
+
+---
+
+## Step 0：前置条件检查
+
+在执行本 SKILL 之前，确保：
+
+- [ ] `query_audit_logs` MCP 工具可用（MCP Server 已连接）
+- [ ] `record_dev_operation` MCP 工具可用
+- [ ] `get_project_context` MCP 工具可用
+- [ ] 数据库正在运行（`npm run db:status`）
+
+如果 MCP 工具不可用，**必须提示用户先启动 MCP Server**，不能跳过。
+
+---
+
+## Step 1：扫描运行时纠偏文档（ADD-11 证据的不可再生性）
+
+**在查询审计日志之前，先检查是否存在未关闭的运行时发现。** 这些是部署后暴露的问题，优先级高于任何新的开发需求。
+
+### 1.1 搜索 review-runtime.md 文件
+
+```bash
+find .qoder/reviews/ -name "*review-runtime*" -type f 2>/dev/null
+```
+
+### 1.2 逐文件检查未关闭发现
+
+对每个 `review-runtime.md` 文件：
+- 读取全文
+- 检查 §1 发现列表中是否有标记为"未修复"或状态为 `[ ]` 的发现
+- 检查是否存在未标记的发现（现象明确但无修复记录）
+
+### 1.3 汇总未关闭发现
+
+将未关闭发现整理为：
+
+```markdown
+## ⚠️ 运行时未关闭发现
+
+| 文件 | 发现# | 现象摘要 | 状态 |
+|------|-------|---------|------|
+| {{projectName}}-review-runtime.md | #1 | Chat 格式断裂 (SSE vs JSON) | 未修复 |
+| ... | ... | ... | ... |
+```
+
+如果存在未关闭发现 → **告知用户并询问优先级**（先修还是继续前次任务）
+如果不存在 → 进入 Step 2
+
+---
+
+## Step 2：查询开发操作审计日志
+
+调用 `query_audit_logs` 工具，按以下优先级组合查询：
+
+### 2.1 查最近 2 小时的全部记录（快速恢复）
+
+```
+query_audit_logs({})
+```
+
+**预期产出**：
+- 最近的全部开发操作列表（action, targetType, targetId, beforeState, afterState）
+- 如果非空 → 直接进入 Step 3
+- 如果为空 → 进入 2.2
+
+### 2.2 如果 2.1 为空，放宽时间范围
+
+```
+query_audit_logs({ sinceMinutes: 1440 })   // 最近 24 小时
+```
+
+### 2.3 如果仍然为空，按目标类型查询
+
+```
+query_audit_logs({ targetType: "API_ROUTE" })
+query_audit_logs({ targetType: "COMPONENT" })
+query_audit_logs({ targetType: "SCHEMA" })
+query_audit_logs({ action: "RUNTIME_ERROR" })          // ADD-11: 运行时异常应优先持久化证据
+```
+
+### 2.4 加载 Plan 索引（L2 操作惯性 — index.md 预载）
+
+```
+读取 .qoder/plans/index.md
+```
+
+**预期产出**：
+- 所有活跃 Plan 的列表（按日期分组）
+- plan / handoff / add-route 文件路径和主题描述
+- 如文件不存在 → 跳过，不阻断流程
+
+### 2.5 获取 ADD 工作流状态（L2 操作惯性 — ADD 状态预载）
+
+```
+get_project_context({ scope: "add-state" })
+```
+
+**预期产出**：
+- 当前活跃的 ADD Plan 名称和路径
+- 当前所处的 ADD Step（从 add-route 推断）
+- 待执行的 ADD 操作清单
+- 如 MCP 工具不可用 → 跳过，不阻断流程
+
+---
+
+## Step 3：分析审计日志 + Plan 索引 + ADD 状态推断上下文
+
+根据 Step 2 返回的审计记录、Step 2.4 的 Plan 索引、Step 2.5 的 ADD 状态，交叉分析：
+
+### 3.1 推断进行中的工作
+
+| 审计记录特征 | 推断 |
+|-------------|------|
+| 最近有 `API_PAGINATION_ENABLED` | 文档列表分页功能正在进行中 |
+| 最近有 `COMPONENT_VIRTUAL_LIST_ADDED` | 虚拟列表渲染正在实施 |
+| 最近有 `SCHEMA_FIELD_ADDED` | 数据库 Schema 刚被修改 |
+| 最近有 `DEPENDENCY_ADDED` | 新依赖已安装 |
+
+### 3.2 推断文件改动范围
+
+```
+根据 action 推断：
+  targetType=API_ROUTE  → 检查 src/app/api/ 下对应文件
+  targetType=COMPONENT  → 检查 src/components/ 下对应文件
+  targetType=SCHEMA     → 检查 prisma/schema.prisma
+  targetType=DEPENDENCY → 检查 package.json
+  targetType=DOC        → 检查 docs/ 下对应文档文件
+```
+
+### 3.4 推断 ADD 状态与活跃 Plan 拓扑
+
+根据 Step 2.4（index.md）和 Step 2.5（get_project_context）的结果：
+
+```
+从 index.md 提取:
+  - 最近的 Plan 列表（按日期倒序，最近 7 天）
+  - 每个 Plan 的类型（plan / handoff / add-route）和主题
+
+从 get_project_context 提取:
+  - 当前活跃 Plan 名称
+  - 当前 ADD Step
+  - 待执行操作清单
+
+交叉推断:
+  - 如 get_project_context 有活跃 Plan → 优先定位
+  - 如 get_project_context 为空 → 从 index.md 最近日期推断最可能的活跃 Plan
+  - 如 audit log 有最近操作 → 与 Plan 交叉验证一致
+```
+
+---
+
+## Step 4：构建上下文摘要
+
+将 Step 3 的分析结果整理成以下格式：
+
+```markdown
+## 🔄 稀疏推理上下文恢复
+
+**检测到的开发活动**：
+- 正在进行的 Plan: `{plan-name}` (如果有)
+- 当前 ADD Step: {Step N}（从 get_project_context 或 add-route 推断）
+- 活跃 Plan 列表（最近 7 天）:
+  - {date}: {plan-name} — {主题}
+  - {date}: {plan-name} — {主题}
+- 已修改的文件: {file1}, {file2}, ...
+- 已完成的改动: {action1}, {action2}, ...
+- 待完成的改动: {action3}, {action4}, ...
+
+**Plan 拓扑**（从 index.md 提取）:
+- 最近 Plan: {links}
+- 待执行 ADD 操作: {从 get_project_context 提取}
+
+**建议下一步**：
+- {根据审计记录、Plan 拓扑和 ADD 状态推断的下一步操作}
+```
+
+将此摘要作为当前会话的「上下文基准」告知用户。
+
+---
+
+## Step 5：开始正常对话
+
+上下文恢复完成后，进入正常的 ADD 流程：
+- 如果用户提出需求 → 按 `add-paradigm` SKILL 执行
+- 如果用户要求修改 → 按 `add-paradigm` SKILL 执行
+- 修改完成后 → 调用 `record_dev_operation` 记录
+
+---
+
+## 本 SKILL 的执行检查清单
+
+- [ ] Step 1: 已扫描 `.qoder/reviews/*review-runtime*` 并汇总未关闭发现
+- [ ] Step 2: 已调用 `query_audit_logs({})`（含 `RUNTIME_ERROR` 查询）
+- [ ] Step 3: 已分析审计日志推断上下文
+- [ ] Step 4: 已构建上下文摘要
+- [ ] Step 5: 已向用户展示恢复的上下文（含未关闭运行时发现，如有）

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

@@ -0,0 +1,125 @@
+# Checklist: add-coder npm 包工程化
+
+> **证据规范**：每项 [x] 必须附带可验证证据。不得空勾选、不得推测通过。
+> - `[T]` = 编译期验证 — 证据: 命令+结果（如 `tsc=0` / `vitest 9/9`）
+> - `[R]` = 运行时验证 — 证据: 部署后确认（如 `npx add-coder init` 端到端）
+> - `[E]` = 静态检查 — 证据: grep/diff 输出
+> - `[H]` = 人工审阅 — 证据: 审阅结论 + 关注点（**无法自动化，必须读代码**）
+>
+> **审计链（证据→devlog→checklist）**:
+> - 初验规则: 先找证据（命令+结果）→ 调 `record_dev_operation` 落库 → 将返回的真实 cuid 写入 checklist。**禁止抄写 `cmq...` 占位符**。
+> - 复验规则: 先查 checklist 是否已有真实审计 ID → 重新验证证据 → 证据一致则不复写 devlog，不一致则追写新 devlog（新 cuid）
+
+---
+
+## 一、编译与 Lint 门禁 [T]（命令确认，一票否决）
+
+- [x] [T] `npx tsc --noEmit` 零错误（`packages/add-coder/` 目录） — 证据: `tsc=0` (退出码 0)|审计: (待填写)
+- [x] [T] `tsup` 构建成功（ESM + CJS 双格式） — 证据: `DTS ⚡️ Build success`|审计: (待填写)
+- [x] [E] `dist/` 目录包含 `cli/index.js` + `core/renderer.js` + `adapters/*/renderer.js` — 证据: tsup 产出确认|审计: (待填写)
+
+---
+
+## 二、模板硬编码清理 [E]（grep 确认，零残留）
+
+- [x] [E] `grep -r "farm.agent\|farm_secure_pass\|大田精准\|/home/xmm\|/Users/milkytea" templates/` 返回空 — 证据: grep 返回空|审计: (待填写)
+- [x] [E] `grep -r "farm.agent\|大田" dist/` 返回空 — 证据: 已确认|审计: (待填写)
+- [ ] [E] `grep -r "process.env.*||" dist/` 返回空（基建变量无兜底值） — 证据: (待填写)|审计: (待填写)
+- [x] [E] 所有 `{{placeholder}}` 占位符在 `src/core/renderer.ts` 中有对应的替换逻辑 — 证据: `renderCore()` 遍历模板文件执行 replace|审计: (待填写)
+
+---
+
+## 三、适配器正确性 [T]/[E]（三端 init 命令确认）
+
+- [ ] [T] `npx add-coder init --adapter claude` 生成正确的 `.claude/` 目录 — 证据: (待填写)|审计: (待填写)
+  - [ ] [E] `.claude/settings.json` 含 hook 配置，matcher 使用标准工具名（`Write`, `Edit`, `Bash`）
+  - [ ] [E] `.claude/mcp.json` 存在且格式正确
+  - [ ] [E] `.claude/hooks/` 下 12 个脚本存在且可执行
+- [ ] [T] `npx add-coder init --adapter qoder` 生成正确的 `.qoder/` 目录 — 证据: (待填写)|审计: (待填写)
+  - [ ] [E] `.qoder/settings.json` matcher 使用双套工具名（`Write|write_to_file`, `Edit|edit_file`, `Bash`）
+  - [ ] [E] `.qoder/hooks/` 下 12 个脚本 + `lib/` 存在
+- [ ] [T] `npx add-coder init --adapter vscode` 生成正确的 `.vscode/` 目录 — 证据: (待填写)|审计: (待填写)
+  - [ ] [E] `.vscode/settings.json`、`launch.json`、`tasks.json`、`extensions.json` 存在
+
+---
+
+## 四、Prisma 数据库注入 [T]
+
+- [ ] [T] `prisma migrate dev --schema=prisma/` 成功创建 DevOperation + AuditLog 表 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] 重复执行 `prisma migrate dev` 幂等（不报错） — 证据: (待填写)|审计: (待填写)
+- [ ] [E] 用户无 User 模型时 `init` 报错提示（而非静默失败） — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `prisma migrate dev` 失败时回滚 `add.prisma` — 证据: (待填写)|审计: (待填写)
+- [ ] [E] 已有 `add.prisma` 时交互三选一（跳过/覆盖/diff+备份） — 证据: (待填写)|审计: (待填写)
+
+---
+
+## 五、构建产物 [T]
+
+- [ ] [T] `npm pack` 产出 tarball 包含 `dist/` + `templates/` + `bin/` — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `npm pack` 产出 tarball 不包含 `src/` — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `package.json` 中 `"private": false` — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `"type": "module"` — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `"exports"` 多入口（`.`、`./config`、`./renderer`、`./adapters/*`） — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `"engines": { "node": ">=20" }` — 证据: (待填写)|审计: (待填写)
+- [ ] [E] `"packageManager": "pnpm@11.9.0"` — 证据: (待填写)|审计: (待填写)
+
+---
+
+## 六、集成测试 [T]
+
+- [ ] [T] `npx add-coder init` 在空白项目中零配置生成完整 ADD 模板 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `--yes` 模式：跳过已有文件，只创建新文件 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `--force` 模式：已有文件直接覆盖 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `--dry-run` 模式：只预览，不写入 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `--force` 和 `--yes` 互斥，同时指定时报错 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `add-coder sync` 只同步缺失文件 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `add-coder status` 检查完整性 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] 已有 `.qoder/settings.json` 时 `init` 不覆盖，展示 diff 并交互确认 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] 单元测试：`renderer.ts`、`config-loader.ts`、`detect.ts`、`writer.ts` 全部通过 — 证据: (待填写)|审计: (待填写)
+
+---
+
+## 七、CaijueHub 裁决层 [T]/[E]
+
+- [x] [T] `caijue.toml` 可被正确解析（smol-toml 解析无报错） — 证据: `npm run generate` 4 策略全部产出|审计: (待填写)
+- [x] [E] `detect.ts`/`prisma-injector.ts`/`writer.ts`/`init.ts` 均从 caijue/strategies 读取决策 — 证据: grep 确认 4 条 import|审计: (待填写)
+
+---
+
+## 八、ADD Report 体系验证（替代传统 E2E）
+
+> ADD 用双层报告替代传统 E2E：代码审查报告（review-implementation.md + review-runtime.md）覆盖实现质量，
+> Runtime Report 体系（gateway.md + boundary-runtime-report.md）覆盖边界合约持续监测。
+> 参考: `policy-update-loop.ts` 的持续反馈闭环模式 + `.qoder/reports/REPORT-WORKFLOW.md`。
+
+- [ ] [T] `review-implementation.md` 已生成，覆盖全部 9 个 Task 的变更范围 — 证据: (待填写)|审计: (待填写)
+- [ ] [T] `review-runtime.md` 已生成（含本 checklist 全部 `[R]` 项清单） — 证据: (待填写)|审计: (待填写)
+- [ ] [R] `npm pack` 后 `npm install` 成功 — 证据: (待填写)|审计: (待填写)
+- [ ] [R] 安装后在空白项目中 `npx add-coder init` 端到端通过 — 证据: (待填写)|审计: (待填写)
+- [ ] [R] `add-coder.config.ts` 可覆盖项目名、源码目录、日志目录等 — 证据: (待填写)|审计: (待填写)
+- [ ] [R] 无效配置在 Zod 校验时报错 — 证据: (待填写)|审计: (待填写)
+- [ ] [R] `check-boundary-report` 无新增未闭合发现 — 证据: (待填写)|审计: (待填写)
+
+---
+
+## 八、ADD 规则合规检查 [E]
+
+- [x] [E] ADD-7：每个文件修改已记录 `record_dev_operation` — 证据: `query_audit_logs({ planKeyword: "add-coder-npm-package" })` 命中 20 条|审计: (待填写)
+- [ ] [E] Plan/Spec 一致性 — 证据: `check_spec_sync` 结果|审计: (待填写)
+- [ ] [E] Plan/Spec 修订记录 — 证据: `record_dev_operation` 审计 ID|审计: (待填写)
+- [ ] [E] 无新增依赖（模板引擎等） — 证据: `git diff package.json` 无新增 dependency|审计: (待填写)
+- [ ] [E] 不改 farm-agent 业务代码 — 证据: 仅改动 `packages/add-coder/`|审计: (待填写)
+- [ ] [E] 审计日志记录完整 — 证据: `query_audit_logs` 回查确认|审计: (待填写)
+
+---
+
+> **流程衔接（AI 执行指令）**：
+>
+> 当所有 `[T]` 和 `[E]` 编译期检查项均为 `[x]` 时（`[R]` 和 `[H]` 项可保持 `[ ]`），AI 必须执行：
+>
+> 1. **读取** `review-implementation-template.md`，逐项填写实现审查内容
+> 2. **读取** `review-runtime-template.md`，复制为 `.qoder/reviews/{project}-review-runtime.md`
+>    - 替换占位符（标题、关联文档路径）
+>    - §1 发现列表初始化为 "尚无运行时发现"
+>    - §1 末尾自动插入本 checklist 中所有 `[R]` 项的清单，标记为 "待运行时验证"
+> 3. **提示用户**："review-runtime.md 已就绪，包含 N 项运行时验证。部署后 `npm run dev` 启动时会扫描此文件。"

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

@@ -0,0 +1,343 @@
+# add-coder npm 包工程化 Spec
+
+## Why
+
+当前 `packages/add-coder/` 是一个不可发布的半成品：
+
+1. **模板硬编码**：`templates/` 下所有文件直接来自 farm-agent 项目，包含数据库密码、项目名、特定路径等不可移植内容
+2. **CLI 纯搬运**：`bin/add-coder.js`（113 行 CommonJS）只有 `init/sync/status` 三个命令，全是 `fs.copyFileSync`，无参数化渲染、无配置合并
+3. **无适配层抽象**：`.qoder` 和 `.vscode` 是两套独立静态模板，无共享逻辑。加 Claude 适配需要再复制一套
+4. **VS Code 无 hook 层**：`.vscode/` 只有 MCP 配置，缺少 Qoder 的 11 个 hook 等价物
+5. **不可发布**：`"private": true`，`"type": "commonjs"`，无构建流程，无测试
+6. **极客不可调**：用户要么全接受模板，要么全不用，没有配置入口、没有 override 机制
+
+## What Changes
+
+将 ADD 范式做成一个真正可用的 npm 包，6 轮迭代（11 个子项）：
+
+| 轮次 | 变更概要 | 涉及文件 |
+|:--:|------|------|
+| 1 | Prisma 模型准备 + 清理硬编码 | `templates/core/prisma/add.prisma`、`src/cli/prisma-injector.ts`、`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` |
+| 5 | 集成测试 + 文档 + devlog | 测试文件、`README.md`（关联 [codein2027](https://github.com/xiaomingming92/codein2027) 里的"本ADD范式和工作流对不同ai幻觉的或者不遵守情况还不能有效抑制" npm 包即为其落地产物）、`package.json` |
+| 6 | CaijueHub 裁决层 | `src/caijuehub/caijue.toml`、`src/caijuehub/caijue.ts`、`src/caijuehub/transcribe.ts`、`templates/core/caijue/` |
+
+
+### 轮次 3 Hook 清单
+
+**Qoder 适配器**（`templates/adapters/qoder/hooks/`，12 个脚本）：
+
+| 脚本 | 事件 | 说明 |
+|------|------|------|
+| `pre-tool-use.sh` | PreToolUse | 工具调用前门禁，文档路径校验 |
+| `post-tool-use.sh` | PostToolUse | 工具调用后审计，`record_dev_operation` 自动落库 |
+| `session-start.sh` | SessionStart | 会话启动上下文恢复 |
+| `pre-compact.sh` | PreCompact | 上下文压缩前检查 |
+| `stop-check.sh` | Stop | 停止前合规检查 |
+| `notification.sh` | Notification | 通知事件处理 |
+| `permission-gate.sh` | PermissionRequest | 权限请求门禁 |
+| `prompt-submit.sh` | UserPromptSubmit | 用户输入提交前检查（ADD 关键词兜底） |
+| `post-tool-failure.sh` | PostToolFailure | 工具失败后处理 |
+| `subagent-guard.sh` | SubagentStop | 子代理停止前检查 |
+| `review-checklist.sh` | — | Review 检查清单校验 |
+| `doc-format-guard.sh` | — | 文档格式守卫 |
+| `lib/` | — | 共享库（`context-inject.sh`、`state-detect.sh`、`vocabulary.sh`） |
+
+**Claude 适配器**（`templates/adapters/claude/hooks/`，与 Qoder 一一对应）：
+
+| 脚本 | Claude Code 事件 | 与 Qoder 差异 |
+|------|------|------|
+| `pre-tool-use.sh` | PreToolUse | matcher 使用标准工具名（`Write`、`Edit`、`Bash`） |
+| `post-tool-use.sh` | PostToolUse | 同上 |
+| `session-start.sh` | SessionStart | 事件名一致，无差异 |
+| `pre-compact.sh` | PreCompact | 事件名一致，无差异 |
+| `stop-check.sh` | Stop | 事件名一致，无差异 |
+| `notification.sh` | Notification | 事件名一致，无差异 |
+| `permission-gate.sh` | PermissionRequest | 事件名一致，无差异 |
+| `prompt-submit.sh` | UserPromptSubmit | 事件名一致，无差异 |
+| `post-tool-failure.sh` | PostToolFailure | 事件名一致，无差异 |
+| `subagent-guard.sh` | SubagentStop | 事件名一致，无差异 |
+| `review-checklist.sh` | — | 逻辑一致，参考 Qoder 实现 |
+| `doc-format-guard.sh` | — | 逻辑一致，参考 Qoder 实现 |
+
+**共享库**（`templates/shared/hooks-lib/`）：
+
+| 脚本 | 说明 |
+|------|------|
+| `common.sh` | 退出码常量（`EXIT_PASS=0`、`EXIT_BLOCK=2`）+ stdin JSON 解析封装 |
+
+**VS Code 适配器**（`templates/adapters/vscode/`）：
+
+无 hook 脚本（VS Code 不支持原生 hook），仅提供 `settings.json`、`launch.json`、`tasks.json`、`extensions.json`。
+
+## Impact
+
+- Affected specs: 无（本 Plan 为全新举措）
+- Affected code: `packages/add-coder/`（约 90 个文件变更），不修改 farm-agent 业务代码
+- 父 Plan: `.qoder/plans/2026-07/08/farm-agent-add-coder-npm-package-plan-v1.md`
+- 依赖: 无
+- 后续依赖: 无
+
+## Boundaries
+
+- 本次只改造 `packages/add-coder/` 目录，不修改 farm-agent 业务代码
+- 本次不新增 AgentAuditPhase 字面量（npm 包工程化，无业务逻辑审计点）
+- 审计通过 `record_dev_operation`（ADD-7）落库 DevOperation 表
+- 模板引擎不引入第三方依赖（Handlebars/EJS 等），用 TypeScript 原生字符串替换
+- 构建工具选 `tsup`，ESM + CJS 双格式产出
+- 配置校验选 Zod，类型安全 + 运行时校验
+
+---
+
+## Requirements
+
+### Requirement: CaijueHub 裁决层
+
+系统 SHALL 提供基于 `caijue.toml` 的内部裁决配置，将 IDE 检测、Prisma 注入、Writer 写入等 CLI 决策逻辑从硬编码改为 TOML 驱动。caijue.toml 内置在 npm 包中，不部署到用户项目。
+
+#### Scenario: caijue.toml 解析
+
+- **WHEN** 启动 `init` 命令
+- **THEN** 读取 npm 包内置的 `caijue.toml`，CLI 标志（`--yes`/`--force`/`--dry-run`）覆盖对应裁决项
+
+#### Scenario: IDE 检测优先级可配置
+
+- **WHEN** 修改 `caijue.toml` 中 `[detect].priority` 顺序
+- **THEN** IDE 检测行为随之改变，无需修改 `detect.ts` 代码
+
+#### Scenario: Prisma 注入行为可配置
+
+- **WHEN** 修改 `caijue.toml` 中 `[prisma].on_missing` 为 `"ask"`
+- **THEN** 无 Prisma 时不再阻断退出，改为交互式提示
+
+#### Scenario: Writer 模式可配置
+
+- **WHEN** 修改 `caijue.toml` 中 `[writer]` 段
+- **THEN** 文件写入行为随之改变，无需修改 `writer.ts` 代码
+
+---
+
+### Requirement: 模板参数化（硬编码清理）
+
+系统 SHALL 将 `templates/` 下所有文件中的 farm-agent 硬编码替换为 `{{placeholder}}` 占位符。
+
+#### Scenario: 占位符语法
+
+- **WHEN** 模板文件包含项目特定值
+- **THEN** 使用 `{{projectName}}` 双花括号语法，而非 `${var}` 以避免与 Markdown 代码块中的 JS 模板字符串冲突
+
+#### Scenario: 硬编码清零
+
+- **WHEN** 执行 `grep -r "farm.agent\|farm_secure_pass\|大田精准\|/home/xmm\|/Users/milkytea" templates/`
+- **THEN** 返回空（0 条匹配）
+
+#### Scenario: Init-time 与 Runtime 变量分离
+
+- **WHEN** 模板变量为项目名、路径等 init 时确定的值
+- **THEN** 使用 `{{placeholder}}` 占位符（init 时由渲染器替换）
+- **WHEN** 模板变量为数据库连接串、API 密钥等敏感值
+- **THEN** 使用 `process.env.X`（Runtime 环境变量），**无兜底值**，缺失时 `throw Error`
+
+---
+
+### Requirement: Prisma 模型注入
+
+系统 SHALL 在 `npx add-coder init` 时自动将 ADD 治理模型（DevOperation + AuditLog）注入用户项目的 Prisma 目录。
+
+#### Scenario: 正常注入
+
+- **WHEN** 用户项目已有 Prisma（`prisma/` 目录 + `schema.prisma`）且包含 `User` 模型（`id: String`）
+- **THEN** 复制 `templates/core/prisma/add.prisma` → 用户 `prisma/` 目录，执行 `prisma migrate dev --name add_workflow_init --schema=prisma/`，执行 `prisma generate`
+
+#### Scenario: 无 User 模型
+
+- **WHEN** 用户项目缺少 `User` 模型（`id: String`）
+- **THEN** 报错退出，提示"需要 `User` 模型（id: String），请先创建后重试"
+
+#### Scenario: 迁移失败回滚
+
+- **WHEN** `prisma migrate dev` 执行失败
+- **THEN** 删除已复制的 `add.prisma`，输出错误信息
+
+#### Scenario: 已有 add.prisma
+
+- **WHEN** 用户 `prisma/` 目录已存在 `add.prisma`
+- **THEN** 交互三选一：跳过(s) / 覆盖(o) / diff 确认(d)；选 d 时先备份用户文件为 `add.prisma.bak`，再展示 diff
+
+#### Scenario: 迁移幂等
+
+- **WHEN** 重复执行 `add-coder init`
+- **THEN** `prisma migrate dev` 不报错（已应用的迁移自动跳过）
+
+---
+
+### Requirement: 适配器三层架构
+
+系统 SHALL 实现 `core/ + adapters/{claude,qoder,vscode}/` 三层架构，Claude Code（第一公民）、Qoder、VS Code 各自独立适配。
+
+#### Scenario: Adapter 接口签名
+
+- **WHEN** 调用任意 adapter 的 `render` 方法
+- **THEN** 签名 SHALL 为 `render(config: AddCoderConfig, targetDir: string, dryRun: boolean): Map<string, string>`
+
+#### Scenario: Claude 适配器
+
+- **WHEN** 执行 `npx add-coder init --adapter claude`
+- **THEN** 生成正确的 `.claude/` 目录，hook 配置 matcher 使用标准工具名（`Write`, `Edit`, `Bash`）
+
+#### Scenario: Qoder 适配器
+
+- **WHEN** 执行 `npx add-coder init --adapter qoder`
+- **THEN** 生成正确的 `.qoder/` 目录，hook 配置 matcher 适配双套工具名（`Write|write_to_file`, `Edit|edit_file`, `Bash`）
+
+#### Scenario: VS Code 适配器
+
+- **WHEN** 执行 `npx add-coder init --adapter vscode`
+- **THEN** 生成正确的 `.vscode/` 目录，在 README 中诚实声明能力边界（无原生 hook，仅模板 + MCP）
+
+#### Scenario: Hook 共享逻辑
+
+- **WHEN** 编写 Claude 或 Qoder 的 hook 脚本
+- **THEN** 共享逻辑（退出码常量、stdin JSON 解析）放在 `templates/shared/hooks-lib/common.sh`，各 adapter 的 hook 脚本 `source` 引用
+
+---
+
+### Requirement: CLI 命令
+
+系统 SHALL 提供 `init`、`sync`、`status` 三个命令，用 TypeScript + `commander` 实现。
+
+#### Scenario: init 命令
+
+- **WHEN** 执行 `npx add-coder init [--adapter auto|claude|qoder|vscode] [--config <path>] [--yes] [--force] [--dry-run]`
+- **THEN** 按七步流程执行：检测 IDE → 加载配置 → 渲染 core 模板 → 渲染 adapter 模板 → Prisma 注入 → 智能写入 → 输出摘要
+
+#### Scenario: sync 命令
+
+- **WHEN** 执行 `npx add-coder sync`
+- **THEN** 只同步缺失文件，不更新已有文件
+
+#### Scenario: status 命令
+
+- **WHEN** 执行 `npx add-coder status`
+- **THEN** 检查 ADD 模板完整性，列出缺失/过时文件
+
+#### Scenario: 配置加载优先级
+
+- **WHEN** 执行 `init` 加载配置
+- **THEN** 按优先级链：交互式问答 > `add-coder.config.ts` > 自动检测（package.json / .env / 目录扫描）> 内置默认值
+
+#### Scenario: 非交互模式
+
+- **WHEN** 执行 `init --yes` 或 `init --non-interactive`
+- **THEN** 跳过交互式问答，自动检测 + 默认值填充
+
+---
+
+### Requirement: Writer 四种写入模式
+
+系统 SHALL 支持四种文件写入模式，通过 CLI 标志控制。
+
+#### Scenario: 交互模式（默认）
+
+- **WHEN** 无 `--yes`、`--force`、`--dry-run` 标志
+- **THEN** 已有文件展示 diff，用户确认（y/n/skip）
+
+#### Scenario: --yes 模式
+
+- **WHEN** 指定 `--yes` 标志
+- **THEN** 跳过已有文件，只创建新文件；`--force` 和 `--yes` 互斥，同时指定时报错
+
+#### Scenario: --force 模式
+
+- **WHEN** 指定 `--force` 标志
+- **THEN** 已有文件直接覆盖，不交互；`--force` 和 `--yes` 互斥，同时指定时报错
+
+#### Scenario: --dry-run 模式
+
+- **WHEN** 指定 `--dry-run` 标志
+- **THEN** 只打印会做什么，不实际写入
+
+#### Scenario: JSON 合并
+
+- **WHEN** 用户已有 `.qoder/settings.json` 或 `.vscode/settings.json`
+- **THEN** deep merge，已有 `hooks` 数组追加新 hook 而非全量替换
+
+---
+
+### Requirement: 配置系统
+
+系统 SHALL 提供 Zod schema 定义 `AddCoderConfig`，支持 `add-coder.config.ts` 覆盖默认值。
+
+#### Scenario: Zod schema
+
+- **WHEN** 定义配置类型
+- **THEN** `schema.ts` 包含 `projectName`、`sourceDir`、`docsDir`、`logDir`、`mcpServerCommand`、`adapters`、`overrides` 字段
+
+#### Scenario: 配置校验
+
+- **WHEN** 用户提供无效的 `add-coder.config.ts`
+- **THEN** Zod 校验报错，输出具体违规字段和原因
+
+---
+
+### Requirement: 构建与发布
+
+系统 SHALL 产出可发布的 npm 包，通过 `tsup` 构建。
+
+#### Scenario: 构建产出
+
+- **WHEN** 执行 `npm pack`
+- **THEN** tarball 包含 `dist/` + `templates/` + `bin/`，不包含 `src/`
+
+#### Scenario: TypeScript 编译
+
+- **WHEN** 执行 `npx tsc --noEmit`
+- **THEN** 零类型错误
+
+#### Scenario: package.json
+
+- **WHEN** 发布配置完成
+- **THEN** `"private": false`，`"type": "module"`，`"files": ["dist/", "templates/", "bin/"]`，`"exports"` 多入口（`.`、`./config`、`./renderer`、`./adapters/*`），`"engines": { "node": ">=20" }`，`"packageManager": "pnpm@11.9.0"`
+
+#### Scenario: 模板无硬编码残留
+
+- **WHEN** 执行 `grep -r "farm.agent\|大田" dist/`
+- **THEN** 返回空
+
+#### Scenario: 基建变量无兜底值
+
+- **WHEN** 执行 `grep -r "process.env.*||" dist/`
+- **THEN** 返回空
+
+---
+
+### Requirement: 端到端验收
+
+系统 SHALL 在空白项目中通过完整的 init 流程验证。
+
+#### Scenario: 零配置可用
+
+- **WHEN** 在空白项目中执行 `npx add-coder init`
+- **THEN** 零配置生成完整 ADD 模板（skills/agents/templates/rules/hooks 自动就位）
+
+#### Scenario: 三端兼容
+
+- **WHEN** 分别执行 `npx add-coder init --adapter claude`、`--adapter qoder`、`--adapter vscode`
+- **THEN** 三端均正确生成对应目录
+
+#### Scenario: 已有配置不覆盖
+
+- **WHEN** 用户已有 `.qoder/settings.json` 时执行 `init`
+- **THEN** 不覆盖已有配置，展示 diff 并交互确认
+
+#### Scenario: Prisma 迁移幂等
+
+- **WHEN** 重复执行 `add-coder init`
+- **THEN** Prisma 迁移幂等，不报错
+
+#### Scenario: 集成测试通过
+
+- **WHEN** 执行集成测试（在临时目录中 `init` → 验证生成的文件结构）
+- **THEN** 全部通过