add-coder 0.1.0

package/templates/core/templates/handoff-single-round-template.md

@@ -0,0 +1,145 @@
+# {项目名} — {变更描述} 交接手册
+
+> **适用场景**：单轮变更——Plan 内只有 1 个轮次级闭包，所有文件在一次闭包内完成，无跨轮文件边界问题。如简单 Bug 修复、单文件改动。
+>
+> **注意**：如果涉及多个独立文件边界（如类型定义 + 调用方修复），即使"用户能用"也需要拆为多轮，应使用 `handoff-multi-round-template.md`。
+
+---
+
+## 1. 交接前状态
+
+{描述当前数据/文件分布、系统现状}
+
+---
+
+## 2. 交接后状态（目标）
+
+{描述目标布局、变更完成后的系统状态}
+
+---
+
+## 3. 改动清单
+
+| # | 文件 | 操作 | 内容 |
+|---|------|------|------|
+| 1 | `{文件路径}` | {新建/修改/删除} | {一句话描述改了什么} |
+
+---
+
+## 4. 回滚方案
+
+### 代码回滚
+
+```bash
+git reset --hard <commit>
+```
+
+### 数据回滚
+
+{如有数据迁移，描述回滚操作}
+
+---
+
+## 5. 执行前置检查
+
+- [ ] {检查项1}
+- [ ] {检查项2}
+- [ ] `npx tsc --noEmit` + `eslint` 当前无 error
+
+---
+
+## 6. 执行 Task 摘要
+
+```text
+{依赖图 — ASCII 图，│ ├ ▼ 表达依赖关系}
+
+Step 1 ── {描述}
+            │
+            ▼
+Step 2 ── {描述}
+            │
+            ├──────────────┐
+            ▼              ▼
+Step 3 ── {描述}         Step 4 ── {描述}
+            │              │
+            └──────┬───────┘
+                   ▼
+Step 5 ── {描述}
+```
+
+---
+
+## 7. 关键风险点
+
+| 风险 | 影响 | 缓解 |
+|------|------|------|
+| {风险描述} | {影响说明} | {缓解措施} |
+
+---
+
+## 8. 恢复上下文审计查询（新 AI Session 首次启动必读）
+
+> **给后续 AI 助手的说明**：以下每个 `query_audit_logs(...)` 都是 MCP 工具调用，AI 助手在自己的对话中**直接复制粘贴这些参数调用工具即可**，不需要写 SQL。共 {N} 条审计记录可恢复完整开发上下文。
+
+### 总体一键恢复
+
+```text
+query_audit_logs({ keyword: "{汇总关键词}" })
+```
+→ 预期返回 {N} 条记录
+
+### 逐任务/逐文件审计查询
+
+```text
+query_audit_logs({ targetId: "{文件路径1}" })
+→ 预期返回 {ACTION_1}: {描述}
+
+query_audit_logs({ targetId: "{文件路径2}" })
+→ 预期返回 {ACTION_2}: {描述}
+
+query_audit_logs({ keyword: "{ACTION_3}" })
+→ 预期返回 {N} 条: {描述}
+```
+
+### SQL 管理员验证
+
+```sql
+SELECT action, "targetType", "targetId", reason, "createdAt"
+FROM "AuditLog"
+WHERE action IN (
+  '{ACTION_1}',
+  '{ACTION_2}',
+  '{ACTION_3}'
+)
+ORDER BY "createdAt" DESC;
+```
+
+### 恢复判定标准
+
+- action 命中数 ≥ {N}
+- grep 验证命令：
+
+```bash
+grep -R "{关键字}" .qoder/specs/
+```
+
+---
+
+## 9. 后置确认
+
+- [ ] `npx tsc --noEmit` + `eslint` 通过
+- [ ] 所有文件改动已记录 ADD-7 审计（`query_audit_logs` 可回查）
+- [ ] {确认项3}
+- [ ] {确认项4}
+
+---
+
+### 脱敏要求
+
+Handoff 文档中 **禁止出现** 以下类型的硬编码值：
+- 数据库密码（`POSTGRES_PASSWORD`）
+- Chroma auth token（`CHROMA_AUTH_TOKEN`）
+- JWT 密钥（`JWT_SECRET`）
+- API Key（`OPENAI_API_KEY_*`）
+
+所有凭据值应通过 `${ENV_VAR}` 引用，并标注"值见 `.env.development` / `.env.production`"。

package/templates/core/templates/handoff-single-round.schema.json

@@ -0,0 +1,92 @@
+{
+    "template": "handoff-single-round-template.md",
+    "sections": [
+        {
+            "id": "1.prestate",
+            "heading": "## 1. 交接前状态",
+            "required": true
+        },
+        {
+            "id": "2.poststate",
+            "heading": "## 2. 交接后状态（目标）",
+            "required": true
+        },
+        {
+            "id": "3.changes",
+            "heading": "## 3. 改动清单",
+            "required": true
+        },
+        {
+            "id": "4.rollback",
+            "heading": "## 4. 回滚方案",
+            "required": true
+        },
+        {
+            "id": "5.precheck",
+            "heading": "## 5. 执行前置检查",
+            "required": true
+        },
+        {
+            "id": "6.steps",
+            "heading": "## 6. 执行步骤摘要",
+            "required": true
+        },
+        {
+            "id": "7.risks",
+            "heading": "## 7. 关键风险点",
+            "required": true
+        },
+        {
+            "id": "8.audit",
+            "heading": "## 8. 恢复上下文审计查询",
+            "required": true,
+            "subsections": [
+                {
+                    "id": "8.1",
+                    "heading": "### 总体一键恢复"
+                },
+                {
+                    "id": "8.2",
+                    "heading": "### 逐任务/逐文件审计查询"
+                },
+                {
+                    "id": "8.3",
+                    "heading": "### SQL 管理员验证"
+                },
+                {
+                    "id": "8.4",
+                    "heading": "### 恢复判定标准"
+                }
+            ]
+        },
+        {
+            "id": "9.confirm",
+            "heading": "## 9. 后置确认",
+            "required": true
+        },
+        {
+            "id": "desensitize",
+            "heading": "### 脱敏要求",
+            "required": true
+        }
+    ],
+    "placeholders": [
+        "{项目名}",
+        "{变更描述}",
+        "{文件路径}",
+        "{新建/修改/删除}",
+        "{检查项1}",
+        "{检查项2}",
+        "{N}",
+        "{汇总关键词}",
+        "{关键字}",
+        "{ACTION_1}",
+        "{ACTION_2}",
+        "{ACTION_3}"
+    ],
+    "forbidden_terms": [
+        "Phase",
+        "Round",
+        "轮次"
+    ]
+}

package/templates/core/templates/index.md

@@ -0,0 +1,60 @@
+# ADD 模板索引
+
+> 选模板看选型指南，查 schema 看下方索引表。
+
+## 选型指南
+
+**我要做…** | **用这个模板** | **为什么**
+--|--|--
+| 新建开发任务（需要架构设计） | `standard-plan-template.md` | 含方案选型、架构设计、依赖图，适合复杂改动（**默认**）
+| 新建开发任务（简单修复） | `simple-plan-template.md` | 内联 Handoff，无需独立 spec 文件（仅小修改/用户主动提）
+| 定义功能需求 | `spec-template.md` | Why/What/Impact/Requirements
+| 拆分执行任务 | `tasks-template.md` | Task 扁平排列
+| 写验收清单 | `checklist-template.md` | [T]/[E]/[H]/[R] 分类
+| 生成执行路线图 | `add-route-template.md` | 轻量项目
+| 生成执行路线图（重型） | `add-route-template-heavyweight.md` | 后端/多层管线项目
+| 写交接文档（单轮） | `handoff-single-round-template.md` | Bug 修复、API 改动
+| 写交接文档（多轮） | `handoff-multi-round-template.md` | 管线演进、架构重构
+| 方案评审 | `review-template.md` | 问题复现 → 方案对比 → 决策
+| 实现评审 | `review-implementation-template.md` | 跨仓库契约、框架兼容性
+| 运行时评审 | `review-runtime-template.md` | 发现列表、流程改进
+| 写代码审查报告 | `report-template.md` | Issue 总览、分类统计
+| 写运行时异常报告 | `runtime-report-template.md` | 发现列表、关联 Issue
+| 写修复验证报告 | `fix-verification-template.md` | 逐条对照、修复趋势
+
+## 模板→Schema 索引
+
+| 模板 | Schema |
+|------|------|
+| `standard-plan-template.md` | `standard-plan-template.schema.json` |
+| `simple-plan-template.md` | `simple-plan-template.schema.json` |
+| `spec-template.md` | `spec-template.schema.json` |
+| `tasks-template.md` | `tasks-template.schema.json` |
+| `checklist-template.md` | `checklist-template.schema.json` |
+| `handoff-single-round-template.md` | `handoff-single-round.schema.json` |
+| `handoff-multi-round-template.md` | `handoff-multi-round.schema.json` |
+| `add-route-template.md` | `add-route-template.schema.json` |
+| `add-route-template-heavyweight.md` | `add-route-template.schema.json` |
+| `review-template.md` | `review-template.schema.json` |
+| `review-implementation-template.md` | `review-implementation-template.schema.json` |
+| `review-runtime-template.md` | `review-runtime-template.schema.json` |
+| `report-template.md` | `report-template.schema.json` |
+| `runtime-report-template.md` | `runtime-report-template.schema.json` |
+| `fix-verification-template.md` | `fix-verification-template.schema.json` |
+
+## 守卫流程
+
+```
+doc-format-guard.sh → 读上表匹配 schema → 读 schema.json
+  → 缺 required section → exit 2
+  → 含未替换占位符 → exit 2
+  → 含禁止词 → warning
+```
+
+## 标题层级
+
+| 层级 | 标记 |
+|:--:|------|
+| 1 | `##` |
+| 2 | `###` |
+| 3 | `####` |

package/templates/core/templates/report-template.md

@@ -0,0 +1,126 @@
+# {项目名称} 代码审查报告
+
+> 生成时间：{YYYY-MM-DD}
+> 来源：{触发方式: 全量扫描 / 增量审查 / 运行时反馈 / 人工 review}
+> 关联文档：[边界划分](../reports/boundary-runtime-report.md) | [工作流](../reports/REPORT-WORKFLOW.md)
+
+---
+
+## Issue 总览
+
+| ID | 分类 | 严重度 | 文件 | 状态 | 运行时验证 |
+|----|------|--------|------|:----:|:----------:|
+| RPT-{YYYYMMDD}-01 | {分类} | {P0-P3} | [`{file}`](file://{path}#L{line}) | ❌ | — |
+| RPT-{YYYYMMDD}-02 | {分类} | {P0-P3} | [`{file}`](file://{path}#L{line}) | ✅ | ✅ 已验证 |
+
+> 状态：✅ 已修复 / ⚠️ 部分修复 / ❌ 仍存在
+> 运行时验证：✅ 已验证 / ❌ 回退 / — 未关联运行时
+
+---
+
+## 分类统计
+
+| 分类 | P0 | P1 | P2 | P3 | 合计 |
+|------|:--:|:--:|:--:|:--:|:----:|
+| 安全风险 | 0 | 0 | 0 | 0 | 0 |
+| 代码重复 / 架构 | 0 | 0 | 0 | 0 | 0 |
+| 健壮性 / 边界 | 0 | 0 | 0 | 0 | 0 |
+| 代码整洁 | 0 | 0 | 0 | 0 | 0 |
+| 基础设施 / 运维 | 0 | 0 | 0 | 0 | 0 |
+| **合计** | **0** | **0** | **0** | **0** | **0** |
+
+---
+
+## 一、安全风险
+
+### RPT-{YYYYMMDD}-{seq}: {问题标题}
+
+- **文件**: [`{file}:{line}`](file://{path}#L{line})
+- **严重度**: {P0/P1/P2/P3}
+- **分类**: 安全风险
+- **状态**: ❌ 仍存在
+- **运行时网关关联**: `{{projectName}}-runtime-report/gateway.md#L{line}` (Gateway 运行时发现 {n} 次)
+
+**现象**:
+
+{描述问题的具体表现}
+
+**根因**:
+
+```typescript
+// {file}:{line}
+{问题代码片段}
+```
+
+**影响**:
+
+1. {影响1}
+2. {影响2}
+
+**建议**:
+
+{修复方案}
+
+**验证方式**:
+
+- [ ] {验证操作1}
+- [ ] {验证操作2}
+
+---
+
+## 二、代码重复 / 架构问题
+
+<!-- 同上格式，每个 Issue 一条 -->
+
+---
+
+## 三、健壮性 / 边界条件
+
+<!-- 同上格式，每个 Issue 一条 -->
+
+---
+
+## 四、代码整洁
+
+<!-- 同上格式，每个 Issue 一条 -->
+
+---
+
+## 五、基础设施 / 运维
+
+<!-- 同上格式，每个 Issue 一条 -->
+
+---
+
+## 修复优先级
+
+| 优先级 | Issue | 说明 |
+|--------|-------|------|
+| P0 立即 | {ID列表} | 安全风险，影响生产 |
+| P1 尽快 | {ID列表} | 健壮性，可能导致故障 |
+| P2 计划 | {ID列表} | 架构问题，技术债务 |
+| P3 债务 | {ID列表} | 代码整洁，长期优化 |
+
+---
+
+## 修复趋势
+
+| 维度 | 上次 | 本次 | 变化 |
+|------|:----:|:----:|:----:|
+| 安全 | {n} | {n} | {+n/-n} |
+| 架构 | {n} | {n} | {+n/-n} |
+| 健壮性 | {n} | {n} | {+n/-n} |
+| 整洁 | {n} | {n} | {+n/-n} |
+| 运维 | {n} | {n} | {+n/-n} |
+| **合计** | **{n}** | **{n}** | **{+n/-n}** |
+
+---
+
+## 运行时反馈
+
+> 以下 Issue 来自 Gateway 运行时自动捕获，已进行人工 triage。
+
+| Issue | 运行时来源 | 首次发生 | 次数 | Triage 结果 |
+|-------|-----------|---------|:----:|------------|
+| {ID} | `{{projectName}}-runtime-report/gateway.md` | {ts} | {n} | 确认为 Bug → P1 |
+| {ID} | `{{projectName}}-runtime-report/gateway.md` | {ts} | {n} | 环境问题 → 关闭 |

package/templates/core/templates/report-template.schema.json

@@ -0,0 +1,69 @@
+{
+    "template": "report-template.md",
+    "sections": [
+        {
+            "id": "overview",
+            "heading": "## Issue 总览",
+            "required": true
+        },
+        {
+            "id": "stats",
+            "heading": "## 分类统计",
+            "required": true
+        },
+        {
+            "id": "security",
+            "heading": "## 一、安全风险",
+            "required": true
+        },
+        {
+            "id": "duplication",
+            "heading": "## 二、代码重复",
+            "required": true
+        },
+        {
+            "id": "robustness",
+            "heading": "## 三、健壮性",
+            "required": true
+        },
+        {
+            "id": "cleanliness",
+            "heading": "## 四、代码整洁",
+            "required": true
+        },
+        {
+            "id": "infra",
+            "heading": "## 五、基础设施",
+            "required": true
+        },
+        {
+            "id": "priority",
+            "heading": "## 修复优先级",
+            "required": true
+        },
+        {
+            "id": "trend",
+            "heading": "## 修复趋势",
+            "required": false
+        },
+        {
+            "id": "runtime",
+            "heading": "## 运行时反馈",
+            "required": false
+        }
+    ],
+    "placeholders": [
+        "{项目名称}",
+        "{YYYY-MM-DD}",
+        "{触发方式",
+        "{P0-P3}",
+        "{n}",
+        "{ID列表}",
+        "{ID}",
+        "{ts}"
+    ],
+    "forbidden_terms": [ "Phase", 
+        "阶段",
+        "步骤"
+    ]
+}

package/templates/core/templates/review-implementation-template.md

@@ -0,0 +1,66 @@
+# {标题}
+
+## Review 元信息
+
+- **Review 对象**: {被评审的代码变更 / 跨仓库集成}
+- **关联方案 review**: {前置方案 review 文档路径}
+- **Review 时间**: {YYYY-MM-DD}
+- **Review 类型**: 实现 review（ADD 0.1.2）
+- **前置阅读**: {关联的 plan / spec / checklist}
+
+---
+
+## 1. 跨仓库格式契约
+
+列出所有跨系统 API，逐对验证请求/响应格式：
+
+| API | 发送方 | 期望类型 | 接收方 | 实际类型 | 匹配? |
+|-----|--------|---------|--------|---------|:---:|
+| {端点1} | {客户端文件:行} | {格式} | {服务端文件:行} | {格式} | ✅/❌ |
+
+- [ ] 所有字段名和嵌套结构一致（如 `data.messages[].role`）
+- [ ] 响应 Content-Type 匹配客户端解析器（JSON vs `text/event-stream` vs NDJSON）
+
+---
+
+## 2. 框架版本兼容性
+
+- [ ] `cat package.json | jq .dependencies.next` 确认主版本号
+- [ ] 查该版本的 breaking changes
+- [ ] 编译产物 mtime 晚于源码（如 `.next/server/middleware.js` ≥ `src/proxy.ts`）
+
+---
+
+## 3. 数据模型约束
+
+- [ ] Prisma `create()` / `update()` 的外键字段对应表中有记录
+- [ ] `@unique` 字段无重复插入风险
+- [ ] 非外键但语义上引用其他表的字段（如 `userId: "system"`）是真实存在的 ID
+
+---
+
+## 4. 环境变量加载链
+
+- [ ] 列出 `npm run` 命令 → `--mode` → `.env.*` → 每个变量的实际值
+- [ ] 三套环境（dev/local/prod）指向正确后端地址
+
+---
+
+## 5. 多 API 场景匹配
+
+- [ ] 模块导出多个功能相似函数时，确认调用方选的是场景匹配的
+- [ ] 检查：chat/SSE 场景不能用同步版 API，批处理场景不能用流式版 API
+
+---
+
+## 6. E2E 逐端点 curl
+
+- [ ] 用有效凭证对每个端点 curl，检查 HTTP 状态码 + 响应 body 格式
+- [ ] OPTIONS 预检返回正确的 CORS 头
+
+---
+
+## 7. 关联 Checklist
+
+- 本 review 的检查项与 `{checklist 文档路径}` 的"跨项目联调检查"章节一一对应
+- [ ] checklist 全部通过后，流转至运行时验证

package/templates/core/templates/review-implementation-template.schema.json

@@ -0,0 +1,58 @@
+{
+    "template": "review-implementation-template.md",
+    "sections": [
+        {
+            "id": "meta",
+            "heading": "## Review 元信息",
+            "required": true
+        },
+        {
+            "id": "contract",
+            "heading": "## 1. 跨仓库格式契约",
+            "required": true
+        },
+        {
+            "id": "framework",
+            "heading": "## 2. 框架版本兼容性",
+            "required": true
+        },
+        {
+            "id": "datamodel",
+            "heading": "## 3. 数据模型约束",
+            "required": true
+        },
+        {
+            "id": "env",
+            "heading": "## 4. 环境变量加载链",
+            "required": true
+        },
+        {
+            "id": "api",
+            "heading": "## 5. 多 API 场景匹配",
+            "required": true
+        },
+        {
+            "id": "e2e",
+            "heading": "## 6. E2E 逐端点 curl",
+            "required": true
+        },
+        {
+            "id": "checklist",
+            "heading": "## 7. 关联 Checklist",
+            "required": true
+        }
+    ],
+    "placeholders": [
+        "{标题}",
+        "{被评审的代码变更",
+        "{前置方案 review 文档路径}",
+        "{YYYY-MM-DD}",
+        "{关联的 plan",
+        "{端点1}",
+        "{checklist 文档路径}"
+    ],
+    "forbidden_terms": [ "Phase", 
+        "阶段",
+        "步骤"
+    ]
+}

package/templates/core/templates/review-runtime-template.md

@@ -0,0 +1,73 @@
+# {标题}
+
+> 运行时验证纠偏文档。在 checklist 通过、代码部署后，通过用户反馈或运行时日志发现的遗漏问题。
+
+## Review 元信息
+
+- **关联方案 review**: {前置方案 review 文档路径}
+- **关联实现 review**: {前置实现 review 文档路径}
+- **关联 checklist**: {前置 checklist 文档路径}
+- **Review 时间**: {YYYY-MM-DD}
+- **触发方式**: {用户报告 / 运行时日志 / E2E 测试}
+
+---
+
+## 1. 发现列表
+
+> 序号延续前置 review 的最后一条发现编号。
+
+### 发现 #N: {问题标题}
+
+**现象**：
+
+{用户报告或日志中的错误信息}
+
+**根因（git 追溯）**：
+
+```
+commit {hash} ({日期}, "{提交信息}")
+  - {变更内容}
+  - {出错的具体代码}
+```
+
+**后果链**：
+
+1. {操作1}
+2. {操作2}
+3. {最终用户可见的影响}
+
+**修复方向**：{修复方案描述}
+
+#### 为何前置 review 遗漏
+
+{分析前置 review 未捕获此问题的结构性原因}
+
+---
+
+### 发现 #N+1: {问题标题}
+
+{同上结构}
+
+---
+
+## 2. review 流程改进项
+
+| 检查项 | 具体操作 | 触发时机 |
+|--------|---------|---------|
+| {改进项1} | {操作描述} | {时机} |
+| {改进项2} | {操作描述} | {时机} |
+
+> 上述改进项应回流至 `review-implementation-template.md` 或 `checklist-template.md`，确保下次项目自动继承。
+
+---
+
+## 3. 已运行时修复项
+
+{已完成的临时修复方案编号列表}
+
+---
+
+## 4. 回流确认
+
+- [ ] 流程改进项已写入对应模板（`review-implementation-template.md` / `checklist-template.md`）
+- [ ] 修复项已记录审计日志（`record_dev_operation`）