@kunlv/atdc 1.0.0

package/prompts/X-review.md

@@ -0,0 +1,417 @@
+# prompts/X-review · 代码级 Review
+
+横向命令，基于 **CRG (code-review-graph)** + **CodeGraph** 双图引擎进行精准代码 review。
+
+---
+
+## 目标
+
+不是 review 全部代码，而是 review **变更的 blast radius**：只读受影响的文件，只查受影响的测试，只追踪受影响的用户流程。
+
+---
+
+## Phase 0：判断子模式
+
+检查参数：
+
+| 参数      | 模式           | 执行                              |
+| ------- | ------------ | ------------------------------- |
+| 无参数     | 全量 review    | Phase 1 → 2（含2d慢查）→ 3 → 4 → 5 → 6 |
+| `delta` | 仅变更 review   | Phase 1 → 2（含2d慢查）→ 5 → 6      |
+| `pr`    | PR/分支 review | Phase 1（base=master）→ 2（含2d慢查）→ 5 → 6 |
+| `gaps`  | 仅测试缺口        | Phase 1 → 3 → 6                 |
+| `flows` | 仅受影响流程       | Phase 1 → 4 → 6                 |
+| `arch`  | 架构健康检查       | Phase 1 → 4b → 6                |
+| `crg`   | CRG 深度分析     | Phase 1 → 2b → 3b → 4c → 6      |
+
+---
+
+## Phase 1：检测变更文件 + 图状态
+
+### 1a. PR 模式：合并 origin/master 最新代码（仅 `pr` 模式）
+
+对于 `pr` 模式分支 review，必须先确保要 review 的分支已包含 `origin/master` 最新代码，避免 review 出与 master 无差异的冗余内容：
+
+```bash
+git fetch origin master && git merge origin/master --no-edit
+```
+
+> 此步骤必须在任何 diff 检测之前执行。
+
+### 1b. 确保图数据目录就绪
+
+```bash
+~/.claude/scripts/link-crg.sh
+```
+
+脚本自动处理：
+- 主仓库 → 保持真实目录
+- worktree → 软链到主仓库的 `.code-review-graph/`
+- 已有软链 → 跳过（幂等）
+
+### 1c. 检查图状态
+
+```
+get_minimal_context_tool(task="code review")
+```
+
+如果返回 "Last updated: never" 或节点数为 0：
+```
+build_or_update_graph_tool(full_rebuild=true)
+```
+
+### 1d. 检测变更文件
+
+**优先使用 CRG**：
+```
+detect_changes_tool(
+  base="HEAD~1",          # delta 模式
+  // base="origin/master",         # pr 模式
+  detail_level="standard"
+)
+```
+
+CRG 返回：
+- 变更文件列表（自动从 git diff 获取）
+- 每个文件的**风险评分**
+- 受影响的函数列表
+- **优先级排序**（高风险在前）
+
+如果 CRG 不可用（图未构建），回退到 git diff：
+```bash
+git diff --name-only HEAD~1       # delta
+git diff --name-only master...HEAD   # pr
+git diff --name-only HEAD          # 工作区
+```
+
+无变更文件 → 输出"无变更，无需 review"并退出。
+
+### 1e. Ponytail Review（可选，推荐执行）
+
+```bash
+# 在 CRG review 基础上，叠加 Ponytail 模式检查
+atdc ponytail scan --diff 2>/dev/null || echo "[Ponytail review skipped]"
+```
+
+> Ponytail 检查结果合并到最终 review 报告：
+> - 发现新模式 → 列为 "过度工程化风险" 项
+> - 无发现 → 标注 "Ponytail clean"
+
+---
+
+## Phase 2：Risk Score — 风险评分
+
+### 2a. CRG 风险评分（首选）
+
+CRG 的 `detect_changes_tool` 已内置风险评分。直接使用其输出：
+
+```
+get_review_context_tool(
+  include_source=true,
+  max_lines_per_file=200,
+  max_depth=2
+)
+```
+
+返回：
+- 变更函数的源码片段
+- 影响半径（哪些函数/文件受影响）
+- 社区结构（是否跨模块）
+- 建议的 review 优先级
+
+### 2b. 逐符号 blast radius（补充深度）
+
+对 CRG 标记为**高风险**的符号，用 CodeGraph 深挖：
+
+```
+codegraph_impact "<SymbolName>" depth=2
+```
+
+收集：
+- **影响深度**：blast radius 涉及几跳
+- **影响广度**：受影响的调用方数量
+- **跨模块**：是否跨越了不同的目录/包
+
+### 2c. 综合风险评分
+
+结合 CRG 风险评分和 CodeGraph blast radius：
+
+| 维度 | 低风险 (1分) | 中风险 (2分) | 高风险 (3分) |
+|------|-------------|-------------|-------------|
+| CRG 风险 | low | medium | high |
+| 影响广度 | ≤3 个调用方 | 4-10 个 | >10 个 |
+| 跨模块 | 无 | 2 个模块 | ≥3 个模块 |
+| 测试覆盖 | 变更函数全部有测试 | 部分有测试 | 多数无测试 |
+| 变更类型 | 新增/日志/配置 | 修改逻辑 | 改签名/删代码 |
+
+**总分** = 各维度之和（5-15 分）
+
+**风险等级**：
+- 5-8 分 → 🟢 低风险：增量验证即可
+- 9-11 分 → 🟡 中风险：需关注，review 重点
+- 12-15 分 → 🔴 高风险：必须全量测试 + 人工确认
+
+---
+
+## Phase 2d：慢查校验 — DB 索引与 SQL 分析
+
+### 触发条件
+
+检查变更代码中是否包含 DB 操作：
+- GORM 原生 SQL：`Raw()`, `Exec()`
+- GORM 链式查询：`Table()`, `Where()`, `Select()`, `Scan()`, `Find()`, `Create()`, `Update()`, `Delete()`
+- 包含 `FROM`, `JOIN`, `WHERE`, `INSERT`, `UPDATE`, `DELETE` 等 SQL 关键字
+- 引用 `commonModel.GetSlaveDBConn()` 或 `GetDBConn()`
+
+**若未检测到 DB 操作 → 跳过此步骤，标注 "无 DB 操作"。**
+
+### 检测到 DB 操作时
+
+**暂停**并向用户请求表结构：
+
+```
+检测到以下 SQL 查询，需要分析慢查风险，请提供对应表的建表 DDL：
+
+1. models/ticket/celebrity.go — FindSingerPerfDetailsByCelebrityIDsSlave
+   涉及表: ticket_performance_celebrity, ticket_performance
+   
+2. models/ticket/celebrity.go — CountSingerPerfByCelebrityIDsSlave
+   涉及表: ticket_performance_celebrity, ticket_performance
+
+3. models/ticket/show.go — FindShowTimesByPerformanceIDsSlave
+   涉及表: ticket_show
+
+请提供以上表的 `CREATE TABLE` 语句。
+```
+
+### 用户提供 DDL 后
+
+对每条 SQL 逐句分析索引命中情况：
+
+1. 列出 WHERE / JOIN / ORDER BY 条件
+2. 匹配表上的索引
+3. 标注：✅ 走索引 / ⚠️ 部分覆盖 / ❌ 无索引 → filesort / temp table
+4. 给出 EXPLAIN 预估（Using index / Using temporary / Using filesort）
+5. 汇总风险等级和缓存缓解
+
+**输出格式**：
+
+```
+### Query N: <函数名>
+
+索引命中分析：
+| 条件 | 索引 | 说明 |
+|------|------|------|
+| ... | idx_xxx ✅ | ... |
+| ... | ⚠️ 无索引 | ... |
+
+EXPLAIN 预估: Using index condition; Using filesort
+
+慢查风险: 🟢 低 / 🟡 中 / 🔴 高
+缓解: Redis 缓存 / LIMIT 等
+
+---
+
+### 慢查总评
+| Query | 风险 | 原因 | 缓解 |
+|-------|------|------|------|
+| ... | ... | ... | ... |
+```
+
+## Phase 3：Test Gaps — 测试缺口检测
+
+### 3a. CRG 测试缺口（首选）
+
+```
+get_knowledge_gaps_tool()
+```
+
+CRG 自动检测：
+- 孤立节点（断连的代码）
+- 瘦弱社区（< 3 成员）
+- **未测试的热点**（高度连接但无测试覆盖的节点）
+- 单文件社区
+
+### 3b. 逐函数覆盖检查（补充）
+
+对变更文件中的关键函数，用 CodeGraph 精确验证：
+
+```
+codegraph_callers "<FunctionName>"
+```
+
+检查返回的调用方中是否有测试文件：
+
+- **有测试调用方** → ✅ 已覆盖
+- **无测试调用方** → ❌ 测试缺口
+
+### 3c. CRG 结构化测试查询
+
+```
+query_graph_tool(pattern="tests_for", target="<SymbolName>")
+```
+
+输出：
+```
+📊 测试覆盖情况
+
+✅ 已覆盖：N 个函数
+❌ 未覆盖：M 个函数
+
+| 函数 | 文件 | 调用方数 | 测试状态 | CRG 覆盖 |
+|------|------|---------|---------|---------|
+| loginHandler | auth.go | 3 | ✅ TestLoginHandler | ✅ |
+| validateToken | token.go | 0 | ❌ 无测试 | ❌ hotspot |
+```
+
+---
+
+## Phase 4：Affected Flows — 受影响流程追踪
+
+### 4a. CRG 受影响流程（首选）
+
+```
+get_affected_flows_tool(changed_files=["..."])
+```
+
+CRG 直接返回：
+- 受影响的执行流列表
+- 每个流的入口点和关键步骤
+- 流的文件覆盖范围
+
+### 4b. 架构健康检查（`arch` 模式）
+
+```
+get_architecture_overview_tool(detail_level="minimal")
+get_bridge_nodes_tool(top_n=10)
+get_hub_nodes_tool(top_n=10)
+get_surprising_connections_tool(top_n=15)
+```
+
+输出：
+- 模块耦合度分析
+- 桥接节点（断连风险点）
+- 枢纽节点（高影响变更点）
+- 异常耦合（跨模块的意外依赖）
+
+### 4c. CodeGraph 端到端追踪（补充深度）
+
+对 CRG 标记的高风险流，用 CodeGraph 追踪完整调用链：
+
+```
+codegraph_trace from="<HandlerName>" to="<关键下游>"
+```
+
+### 4d. 映射用户流程
+
+综合 CRG + CodeGraph 结果，映射到用户可理解的流程：
+
+```
+🔄 受影响的用户流程
+
+| 流程 | 入口函数 | 变更影响点 | 风险 | 数据源 |
+|------|---------|-----------|------|--------|
+| 用户登录 | POST /login | token 验证逻辑变更 | 🟡 中 | CRG+CG |
+| 密码重置 | POST /reset | 共用 validateToken | 🟡 中 | CRG |
+| 用户注册 | POST /register | 无直接影响 | 🟢 低 | CG |
+```
+
+---
+
+## Phase 5：获取 Review 上下文（CRG 专用）
+
+此 Phase 在 `crg` 深度模式下执行，利用 CRG 的 token 高效特性获取完整上下文：
+
+```
+get_review_context_tool(
+  include_source=true,
+  max_lines_per_file=300,
+  max_depth=2,
+  detail_level="standard"
+)
+```
+
+CRG 自动聚合：
+- 变更文件 → 受影响函数 → 源码片段 → 社区归属 → 测试状态
+
+一次调用替代多次 Read + grep，token 消耗降低 60-80%。
+
+---
+
+## Phase 6：输出 Review 报告
+
+```
+📋 Code Review 报告
+
+## 变更概要
+- 变更文件：N 个
+- 变更函数：M 个
+- 风险等级：🔴 高 / 🟡 中 / 🟢 低
+- 图引擎：CRG (5458 nodes) + CodeGraph
+
+## Risk Score: <分数>/15
+<风险评分详情>
+
+## Blast Radius
+<受影响的文件和函数列表，标注 CRG 社区归属>
+
+## 测试覆盖
+- 已覆盖：N 个 ✅
+- 未覆盖：M 个 ❌
+- CRG 热点：K 个 ⚠️
+<缺口详情>
+
+## 受影响流程
+<流程列表及风险>
+
+## 架构洞察（如有异常耦合或桥接风险）
+<surprising connections + bridge nodes>
+
+## 建议行动
+1. <针对高风险项的建议>
+2. <针对测试缺口的建议>
+3. <针对受影响流程的验证建议>
+4. <针对架构耦合的优化建议>
+```
+
+报告**必须**保存到项目根目录的 `docs/report/` 下，命名规则：
+```
+docs/report/code-review-<分支名或change号>-<YYYY-MM-DD>.md
+```
+
+示例：
+- `docs/report/code-review-TASK-231233-getMultiPerfBySingerId-2026-06-23.md`
+- `docs/report/code-review-fix-token-idor-2026-06-23.md`
+
+> 命名前缀固定为 `code-review-`，日期为 review 执行当天的日期。
+> 不再保存到 `openspec/changes/` 下，4-verify 改为从 `docs/report/` 查找最近的 review 报告。
+
+---
+
+## 工具选择速查表
+
+| 场景 | CRG 工具 | CodeGraph 工具 |
+|------|---------|---------------|
+| 变更检测 | `detect_changes_tool` | — |
+| Review 上下文 | `get_review_context_tool` | — |
+| Blast radius | `get_impact_radius_tool` | `codegraph_impact` |
+| 受影响流程 | `get_affected_flows_tool` | `codegraph_trace` |
+| 测试覆盖 | `query_graph_tool(tests_for)` | `codegraph_callers` |
+| 符号搜索 | `semantic_search_nodes_tool` | `codegraph_search` |
+| 架构分析 | `get_architecture_overview_tool` | — |
+| 异常耦合 | `get_surprising_connections_tool` | — |
+| 死代码 | `refactor_tool(dead_code)` | — |
+| 大函数 | `find_large_functions_tool` | — |
+| 符号详情 | `query_graph_tool(file_summary)` | `codegraph_node` |
+| 图状态 | `get_minimal_context_tool` | `codegraph_status` |
+
+**原则**：CRG 适合 review/架构/变更分析场景；CodeGraph 适合单符号精确查询和端到端 trace。两者互补，不互斥。
+
+---
+
+## 与其他阶段的联动
+
+- **4-verify**：自动检测是否有 review 报告，有则引用风险评分决定验证严格度
+- **2-qa**：受影响流程分析作为质疑的新维度
+- **3-impl**：执行中可随时调用 `/atd review gaps` 检查当前任务的测试覆盖
+- **flow health**：`arch` 模式的架构洞察作为健康巡检的输入

package/prompts/X-search.md

@@ -0,0 +1,74 @@
+# prompts/X-search · Semble 代码搜索
+
+横向命令，任意时刻可触发：`/atdc:search <query>`
+
+---
+
+## 用途
+
+- 用自然语言描述功能 → 找到对应代码实现
+- 查找相似的实现模式（替代 grep -rn 的正则匹配）
+- Ponytail B5 L2-L5 检测加速（找项目内已有实现）
+
+## 降级链
+
+```
+Semble MCP（首选，原生工具调用）→ Semble CLI → CodeGraph → grep
+```
+
+- Semble 可用：返回语义匹配的代码片段，无需 Read 文件
+- Semble 不可用：降级到 CodeGraph 结构化搜索
+- CodeGraph 无结果：降级到 grep（最后兜底）
+
+---
+
+## 搜索模式
+
+### 语义搜索（search）
+
+用自然语言或符号名搜索代码：
+
+```bash
+# 自然语言查询
+semble search "authentication flow" . --top-k 5
+semble search "whitelist filter pattern" . --top-k 5
+
+# 符号/标识符查询（Semble 自动识别并加权词法匹配）
+semble search "BuildWhitelistExcludeSet" . --top-k 5
+```
+
+MCP 模式：直接调用 `mcp__semble__search` 工具（参数：query, repo_path, top_k）
+
+### 相似代码发现（find-related）
+
+给定已知位置（文件路径 + 行号），找到语义相似的代码：
+
+```bash
+semble find-related src/auth.py 42 .
+```
+
+MCP 模式：直接调用 `mcp__semble__find_related` 工具
+
+---
+
+## 常用场景
+
+| 场景 | 命令 |
+|------|------|
+| Ponytail L2 | `semble search "slices.Contains" .` → 检查是否已有 stdlib 用法 |
+| Ponytail L3 | `semble search "cenkalti backoff retry" .` → 检查 go.mod 依赖用法 |
+| Ponytail L4 | `semble search "callRPC pattern" .` → 找项目已有 RPC 调用模式 |
+| Ponytail L6 | `semble search "filter by whitelist" .` → 检测 ≥3 处相似代码 |
+| R5 blast radius | `semble find-related <file> <line> .` → 找到语义相似但无直接调用的代码 |
+
+---
+
+## 优先级规则
+
+```
+1. 找"怎么做" → Semble search（语义理解，直接返回代码）
+2. 找"谁调用了 X" → CodeGraph callers（结构化精确查询）
+3. 找"X 会影响到什么" → codegraph_impact（调用边追踪）
+4. 找语义相似但结构无关的代码 → Semble find_related（补影响分析盲区）
+5. 纯文本/正则匹配 → grep（最后兜底）
+```

package/prompts/X-strategy.md

@@ -0,0 +1,95 @@
+# prompts/X-strategy · 产品策略锚点
+
+横向命令，创建或更新 `STRATEGY.md`。
+
+---
+
+## 目标
+
+生成/维护项目根目录的 `STRATEGY.md` — 一个短小精悍的策略锚点文档，让后续所有 brainstorm、plan、impl 有统一的方向约束。
+
+---
+
+## Phase 0：判断状态
+
+```bash
+cat STRATEGY.md 2>/dev/null && echo "---EXISTS---" || echo "---NOT_FOUND---"
+```
+
+- **不存在** → Phase 1（首次创建）
+- **存在 + 用户指定了某节** → Phase 2（定向更新指定节）
+- **存在 + 无指定** → Phase 3（全局审视更新）
+
+---
+
+## Phase 1：首次创建（交互式问答）
+
+逐一提问，每次只问一个问题，用 `AskUserQuestion` 或文字等待回答：
+
+1. **Target Problem**：这个产品解决什么问题？为谁解决？（一句话）
+2. **Approach**：用什么方式解决？核心机制是什么？
+3. **Persona**：目标用户是谁？他们的角色、场景、技术水平？
+4. **Key Metrics**：怎么衡量成功？1-3 个关键指标（名称 + 含义）
+5. **Tracks**：当前在推进哪些工作轨道？按优先级排（每条 1-2 行）
+6. **Out of Scope**：当前明确不做的事？
+
+问完后参考 `@atdc/templates/strategy.md` 生成 `STRATEGY.md`。
+
+**原则**：
+- 推 weak answers，不放过模糊回答
+- 短即是优势。添加章节的成本比看起来高，push back expansion
+- 策略是锚点不是计划。Features 归 proposal，排期归 issue tracker
+
+---
+
+## Phase 2：定向更新
+
+用户指定了某个 section（如 `strategy metrics` 或 `strategy approach`）：
+
+1. 读取当前 `STRATEGY.md`
+2. 只针对指定节提问（1-2 个问题）
+3. 更新该节，保留其余内容不变
+4. 输出 diff 让用户确认
+
+---
+
+## Phase 3：全局审视更新
+
+无特定 section 指定，且 STRATEGY.md 已存在：
+
+1. 读取当前 `STRATEGY.md`
+2. 逐节审视，标记 stale 或 weak 的部分：
+   - **Stale**：与当前实际方向明显不符
+   - **Weak**：模糊、过于宽泛、缺少量化指标
+3. 输出审视结果：
+
+```
+📊 STRATEGY.md 审视结果：
+
+| 节 | 状态 | 建议 |
+|----|------|------|
+| Target Problem | ✓ | 保持 |
+| Approach | ⚠ | <为什么 weak，建议怎么改> |
+| Metrics | ⚠ | <缺少什么指标> |
+| Tracks | 🔴 | <明显过时，需要更新> |
+
+需要更新哪些节？（可多选，或说 "全部"）
+```
+
+4. 用户选择后，只更新选中的节
+5. 更新 `STRATEGY.md` 的 "上次更新" 日期
+
+---
+
+## Phase 4：完成
+
+输出：
+
+```
+✅ STRATEGY.md 已更新
+
+<简要说明更新了什么>
+
+后续 1-spec（需求澄清）和 brainstorm 将自动读取此文件作为方向约束。
+可随时重新运行 /atd strategy 更新。
+```

package/prompts/X-table2xlsx.md

@@ -0,0 +1,46 @@
+# prompts/X-table2xlsx · DDL → Excel 模板
+
+横向命令，任意时刻可触发：`/atdc:table2xlsx <schema.sql>`
+
+---
+
+## 执行步骤
+
+### 1. 确定输入
+
+检查用户提供的参数：
+- 如果提供了 DDL 文件路径 → 直接使用
+- 如果用户粘贴了 DDL 内容 → 写入临时文件 `/tmp/atd_table2xlsx_ddl.sql`
+
+### 2. 调用工具
+
+```bash
+# 文件输入
+${ATDC_DIR}/tools/table2xlsx <ddl_file> -o <output_file>
+
+# stdin 输入
+cat <ddl_file> | ${ATDC_DIR}/tools/table2xlsx -o <output_file>
+```
+
+### 3. 输出
+
+- 默认输出到当前目录的 `{table_name}_template.xlsx`
+- 用户可用 `-o` 指定输出路径
+
+### 4. 错误处理
+
+| 错误 | 处理 |
+|------|------|
+| 文件不存在 | 提示用户提供正确路径 |
+| 非 CREATE TABLE DDL | 提示"未找到 CREATE TABLE 语句" |
+| openpyxl 未安装 | `pip install openpyxl` |
+
+### 5. 使用示例
+
+```bash
+# AI 执行
+/atdc:table2xlsx schema.sql
+
+# 等价于
+${ATDC_DIR}/tools/table2xlsx schema.sql -o membership_product_sku_template.xlsx
+```