@dtt_siye/atool 1.2.1 → 1.3.1

package/skills/project-analyze/phases/{phase5-synthesis.md → archive/phase5-synthesis.md}

@@ -83,6 +83,26 @@ Phase 5 incremental flow:
    g. Generate .atool-docs/visualization/index.html (Cytoscape.js)
 ```
 
+> ⚠️ **可视化生成硬性指令（step 6.g）**：必须通过 Bash 工具执行，禁止用 AI/LLM 直接生成 HTML。
+>
+> 前置检查：
+> ```bash
+> jq '.nodes | length' .atool-docs/knowledge-graph.json
+> ```
+> 如果返回 0 → 可视化跳过（knowledge-graph.json 格式错误或数据缺失），在 Phase 6 报告此问题。
+>
+> 生成可视化：
+> ```bash
+> source lib/generate-visualization.sh
+> generate_visualization "$DOCS_DIR"
+> ```
+>
+> 验证输出：
+> ```bash
+> test -f .atool-docs/visualization/index.html && echo "OK" || echo "MISSING"
+> wc -c < .atool-docs/visualization/index.html  # 应 > 10KB
+> ```
+
 #### COMPONENT.md 增量标记
 
 使用标记包裹每个模块段落，恢复时只替换对应标记内容：

package/skills/project-analyze/phases/phase1-setup.md

@@ -0,0 +1,182 @@
+# Phase 1: SETUP（纯 Bash，无 AI）
+
+**目标**：检测技术栈、统计文件、运行 pre-scan（语法提取）、获得用户确认分析参数。
+
+**执行时间目标**：< 30秒（纯 bash）
+
+## 前置检查
+
+1. 检查 `.atool-docs/analysis-state.json` 是否存在
+2. 如果存在且 `phases.phase1_setup == "completed"` → 跳过 Phase 1，直接进入 Phase 2
+3. 如果不存在或状态非 completed → 继续执行
+
+## 步骤
+
+### 1.1 技术栈检测
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> mkdir -p "$DOCS_DIR"
+> source lib/detect-stack.sh 2>/dev/null || true
+> STACK=$(detect_stack "$PROJECT_ROOT" 2>/dev/null || echo "unknown")
+> FILE_COUNT=$(find "$PROJECT_ROOT" -type f \
+>   ! -path "*/node_modules/*" ! -path "*/.git/*" \
+>   ! -path "*/target/*" ! -path "*/dist/*" \
+>   ! -path "*/build/*" ! -path "*/vendor/*" \
+>   ! -path "*/.atool-docs/*" ! -path "*/atool-analysis/*" \
+>   | wc -l | tr -d ' ')
+> echo "Stack: $STACK | Files: $FILE_COUNT"
+> ```
+
+### 1.2 规模评估
+
+根据 FILE_COUNT 确定 SCALE：
+
+| 文件数 | SCALE | 默认深度 |
+|--------|-------|---------|
+| 1-50 | TINY | L3 |
+| 51-200 | SMALL | L2 |
+| 201-500 | MEDIUM | L2 |
+| 501-1500 | LARGE | L2 |
+| 1501-5000 | XLARGE | L2 |
+| 5001+ | MEGA | L2 |
+
+### 1.3 Pre-Scan（语法提取）
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> mkdir -p "$DOCS_DIR/pre-scan"
+> source lib/pre-scan.sh 2>/dev/null
+> pre_scan_project "$PROJECT_ROOT" "$DOCS_DIR/pre-scan" 2>/dev/null
+> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+>   echo "Pre-scan OK: $(jq '.modules | length' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '?') modules"
+> else
+>   echo "WARNING: Pre-scan failed or manifest.json not created. Phase 2 will fall back to full AI read."
+> fi
+> ```
+>
+> **成功验证**：`$DOCS_DIR/pre-scan/manifest.json` 存在且非空。
+> **失败处理**：记录 warning，继续。Phase 2 sub-agents 将自动降级为全量 AI 读取。
+
+### 1.4 模块发现与重要性评分
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+>   # 从 pre-scan manifest 提取模块列表
+>   MODULES=$(jq -r '.modules[].slug' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null)
+>   echo "Discovered modules:"
+>   echo "$MODULES"
+>   MODULE_COUNT=$(echo "$MODULES" | wc -l | tr -d ' ')
+>   echo "Total: $MODULE_COUNT modules"
+> else
+>   echo "No manifest — modules will be detected from directory structure"
+> fi
+> ```
+
+### 1.4a 扫描已有文档（用户已有的 PRD/README 等）
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> # 扫描项目中的已有文档（排除 aTool 产物和 node_modules）
+> EXISTING_DOCS=$(find "$PROJECT_ROOT" -maxdepth 3 -type f \
+>   \( -name "*.md" -o -name "PRD*" -o -name "SRS*" -o -name "API*" \) \
+>   ! -path "*/node_modules/*" ! -path "*/.atool-docs/*" \
+>   ! -path "*/atool-analysis/*" ! -path "*/.git/*" \
+>   2>/dev/null | head -50)
+> if [ -n "$EXISTING_DOCS" ]; then
+>   echo "Found existing docs:"
+>   echo "$EXISTING_DOCS"
+>   DOC_COUNT=$(echo "$EXISTING_DOCS" | wc -l | tr -d ' ')
+>   echo "Total: $DOC_COUNT existing documents"
+> else
+>   echo "No existing documentation found"
+> fi
+> ```
+>
+> 将结果写入 `analysis-state.json` 的 `existing_docs` 字段（在 §1.6 初始化时）。
+> Phase 2 sub-agent 将使用此信息检测文档与代码的差异并补齐缺失内容。
+
+### 1.4b 重要性评分
+
+如果 `lib/compute-importance.sh` 可用，运行重要性评分：
+> **执行命令（可选）：**
+> ```bash
+> source lib/compute-importance.sh 2>/dev/null && \
+>   compute_importance_batch "$DOCS_DIR/pre-scan/manifest.json" "$PROJECT_ROOT" 2>/dev/null && \
+>   echo "Importance scoring done" || echo "Importance scoring skipped"
+> ```
+
+### 1.5 用户确认
+
+向用户展示分析预览，等待确认：
+
+```
+📊 项目分析预览
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+技术栈：{STACK}
+文件数：{FILE_COUNT}（已排除 node_modules/build/.git 等）
+规模等级：{SCALE}
+识别模块：{MODULE_LIST}
+
+分析深度选项：
+  L1  结构扫描    ~5分钟   ~10K tokens   目录树+技术栈识别
+  L2  架构分析    ~20分钟  ~50K tokens   架构图+模块文档（推荐）
+  L3  深度实现    ~40分钟  ~100K tokens  核心函数+设计决策
+  L4  函数级      ~80分钟  ~200K tokens  调用链+性能+安全
+  L5  跨模块推断  ~120分钟 ~350K tokens  时序图+状态机+数据血缘
+
+请选择深度 (L1-L5) 或直接回车选择推荐值：
+```
+
+### 1.6 初始化 analysis-state.json
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> DEPTH="${DEPTH:-L2}"  # 用户确认的深度，默认 L2
+> STACK="${STACK:-unknown}"
+> SCALE="${SCALE:-MEDIUM}"
+>
+> # 从 manifest 提取模块列表，fallback 为空数组
+> MODULES_JSON=$(jq -c '[.modules[].slug]' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '[]')
+>
+> # 构建 module_status 初始值
+> MODULE_STATUS=$(echo "$MODULES_JSON" | jq -c '[.[] | {key: ., value: {phase2: "pending"}}] | from_entries' 2>/dev/null || echo '{}')
+>
+> cat > "$DOCS_DIR/analysis-state.json" << STATEEOF
+> {
+>   "version": "5.1",
+>   "project_root": "$PROJECT_ROOT",
+>   "stack": "$STACK",
+>   "depth": "$DEPTH",
+>   "scale": "$SCALE",
+>   "modules": $MODULES_JSON,
+>   "phases": {
+>     "phase1_setup": "completed",
+>     "phase2_understand": "pending",
+>     "phase3_graph": "pending",
+>     "phase4_synthesize": "pending",
+>     "phase5_export": "pending"
+>   },
+>   "module_status": $MODULE_STATUS,
+>   "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+> }
+> STATEEOF
+> echo "State initialized: $(jq -c '.phases' "$DOCS_DIR/analysis-state.json")"
+> ```
+
+## 完成条件
+
+- `.atool-docs/pre-scan/manifest.json` 存在（或 warning 已记录）
+- `.atool-docs/analysis-state.json` 已写入且 `phases.phase1_setup = "completed"`
+- 用户已确认分析深度

package/skills/project-analyze/phases/phase2-understand.md

@@ -0,0 +1,114 @@
+# Phase 2: UNDERSTAND（AI Sub-Agents）
+
+**目标**：每个模块派发 1 个 sub-agent，产出三层文档（业务/技术/数据），直接写入 `atool-analysis/modules/`。
+
+**并发上限：5 个 sub-agent**
+
+## 前置检查
+
+1. 读取 `.atool-docs/analysis-state.json`
+2. 确认 `phases.phase1_setup == "completed"` — 否则先执行 Phase 1
+3. 如果 `phases.phase2_understand == "completed"` → 跳过
+4. 加载模块列表 `state.modules[]`
+
+## 输入数据
+
+- Pre-Scan 数据：`.atool-docs/pre-scan/{module-slug}.json`（如存在）
+- 技术栈规则：`rules/{STACK}.md`（优先），fallback `rules/generic.md`
+
+### Pre-scan 降级规则
+
+当 pre-scan 数据缺失时（Phase 1 pre-scan 失败），sub-agent prompt 自动降级：
+- `{prescan_data}` → 替换为 `"⚠️ Pre-scan data NOT available. Read ALL source files to extract structural information first."`
+- Sub-agent 必须先读取模块内所有源文件，自行提取结构信息，然后进行深度分析
+
+## 执行流程
+
+### 2.1 加载分析规则
+
+读取技术栈规则文件：
+1. 优先：`rules/{STACK}.md`（如 `rules/java-spring.md`、`rules/web-react.md`）
+2. Fallback：`rules/generic.md`
+
+### 2.2 模块排序（按重要性降序）
+
+如果 Phase 1 运行了 importance scoring：
+> **执行命令（可选）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+>   jq -r '.modules | sort_by(-.importance) | .[].slug' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null
+> fi
+> ```
+
+否则按 `state.modules[]` 原始顺序。
+
+### 2.3 批量派发 Sub-Agents
+
+**规则**：
+- 每批最多 5 个 sub-agent 并行（使用 Agent 工具）
+- 等待当前批次**全部完成**后再派发下一批
+- 每个 sub-agent 完成后立即更新 `module_status`
+
+**每个 sub-agent 使用 `prompts/understand-agent.md` 模板**
+
+派发前准备每个 sub-agent 的变量：
+1. `{module_name}` — 模块名（slug）
+2. `{module_path}` — 模块在项目中的路径
+3. `{prescan_data}` — 读取 `.atool-docs/pre-scan/{module-slug}.json` 的内容（或降级消息）
+4. `{stack_rules}` — 读取的技术栈规则内容
+5. `{depth_instructions}` — 当前深度级别的追加指令（L2 留空，L3/L4/L5 内联具体指令）
+
+### 2.4 Sub-Agent 输出路径
+
+每个 sub-agent 写入以下文件：
+```
+atool-analysis/modules/{module-name}/README.md       # 层1: 业务摘要
+atool-analysis/modules/{module-name}/api.md          # 层2a: 接口文档
+atool-analysis/modules/{module-name}/data-model.md   # 层2b: 数据模型（如有实体）
+atool-analysis/modules/{module-name}/dev-guide.md    # 层2c: 开发指引
+.atool-docs/modules/{module-name}/data.json          # 层3: 机器数据（供 Phase 3）
+```
+
+### 2.5 Checkpoint 写入
+
+每个模块完成后：
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> MODULE_SLUG="{module-slug}"  # 替换为实际模块名
+> jq --arg mod "$MODULE_SLUG" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.module_status[$mod].phase2 = "completed" | .module_status[$mod].phase2_at = $ts | .updated_at = $ts' \
+>   "$DOCS_DIR/analysis-state.json" > "$DOCS_DIR/analysis-state.json.tmp" \
+>   && mv "$DOCS_DIR/analysis-state.json.tmp" "$DOCS_DIR/analysis-state.json"
+> ```
+
+### 2.6 断点续传
+
+如果从中断恢复：
+1. 读取 `module_status`，找到 `phase2 != "completed"` 的模块
+2. 只对未完成模块派发 sub-agent
+3. 已完成模块跳过
+
+## 完成条件
+
+- 所有模块的 `module_status.{slug}.phase2 == "completed"`
+- 每个模块至少 5/6 核心文件存在（data-model.md 可选）：
+  - `atool-analysis/modules/*/README.md` ✓ 必须
+  - `atool-analysis/modules/*/api.md` ✓ 必须
+  - `atool-analysis/modules/*/dev-guide.md` ✓ 必须
+  - `atool-analysis/modules/*/prd.md` ✓ 必须
+  - `atool-analysis/modules/*/test-cases.md` ✓ 必须
+  - `atool-analysis/modules/*/data-model.md` ○ 可选（无实体时可不存在）
+- `.atool-docs/modules/*/data.json` 全部存在
+- 更新 state：`phases.phase2_understand = "completed"`
+
+> **执行命令：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.phases.phase2_understand = "completed" | .updated_at = $ts' \
+>   "$DOCS_DIR/analysis-state.json" > "$DOCS_DIR/analysis-state.json.tmp" \
+>   && mv "$DOCS_DIR/analysis-state.json.tmp" "$DOCS_DIR/analysis-state.json"
+> ```

package/skills/project-analyze/phases/phase2.5-refine.md

@@ -0,0 +1,284 @@
+# Phase 2.5: REFINE（精炼链 — AI sub-agents ≤5 并行）
+
+**目标**：对 Phase 2 生成的模块初稿，串联 requirements-writer 和 software-architecture 的 Refine Mode 进行精炼，将初稿升级为专业级交付文档。
+
+**并发上限**：最多 5 个模块同时精炼。每个模块内部串行（PRD 精炼 → 架构精炼）。
+
+---
+
+## 前置检查
+
+1. `analysis-state.json` 中 `phases.phase2_understand == "completed"`
+2. 读取 `detected_stack` 用于 conventions 加载
+3. 如果 `phases.phase2_5_refine == "completed"` 且非 `--force`，跳过本 Phase
+4. 如果 `--skip-refine`，跳过本 Phase
+
+## 输入数据
+
+| 来源 | 文件 |
+|------|------|
+| Phase 2 模块文档 | `atool-analysis/modules/*/README.md`, `api.md`, `data-model.md`, `dev-guide.md`, `prd.md`, `test-cases.md` |
+| Phase 2 结构化数据 | `.atool-docs/modules/*/data.json` |
+| Conventions | `~/.claude/skills/{stack}-conventions/SKILL.md`（仅 Architecture + API Design 节） |
+
+## 执行流程
+
+### 2.5.1 加载 Conventions 上下文
+
+```bash
+# 从 state.json 读取技术栈
+STACK=$(jq -r '.detected_stack // "generic"' .atool-docs/analysis-state.json)
+```
+
+从对应 conventions SKILL.md 中提取以下章节内容（不加载全文，控制在 ~200 行）：
+- `## Architecture` 或 `## 架构` 章节
+- `## API Design` 或 `## API 设计` 章节
+
+存为 `{conventions_context}` 变量。如果对应 conventions skill 不存在，`{conventions_context}` 为空字符串。
+
+### 2.5.2 构建模块精炼队列
+
+```bash
+# 读取模块列表，按重要性降序排列
+MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-scan/manifest.json)
+```
+
+**断点续传检查**：对每个模块读取 `refine_status.{module}`：
+
+| 状态 | 行为 |
+|------|------|
+| `arch_refine == "completed"` | 跳过该模块 |
+| `prd_refine == "completed"` 且 `arch_refine != "completed"` | 加入队列，从架构精炼开始 |
+| `prd_refine != "completed"` | 加入队列，从 PRD 精炼开始 |
+| `degraded == true` | 跳过（除非 `--force`） |
+
+### 2.5.3 Gate 1: 初稿完整性检查（Hard Gate）
+
+**对每个待精炼模块执行**：
+
+检查项：
+- `atool-analysis/modules/{name}/prd.md` 存在且 ≥ 30 行
+- `atool-analysis/modules/{name}/README.md` 存在
+- `.atool-docs/modules/{name}/data.json` 存在且是合法 JSON
+
+**失败处理**：该模块不进入精炼队列，记录 `refine_status.{name}.gate1 = "failed"`，打印警告，其他模块继续。
+
+### 2.5.4 批量派发精炼 Sub-Agents
+
+**每批最多 5 个模块并行**，每个模块的精炼链为串行两步。等待当前批次全部完成后再派发下一批。
+
+---
+
+#### Step A: requirements-writer Refine（PRD 精炼）
+
+为每个模块派发 sub-agent，prompt 模板：
+
+```
+你是 requirements-writer 的精炼模式（Refine Mode）。
+
+## 任务
+将以下模块的 PRD 初稿精炼为标准 8 节结构。
+
+## 模块信息
+- 模块名：{module_name}
+- 模块路径：{module_path}
+- 技术栈：{detected_stack}
+
+## 输入文件（必须全部读取）
+- atool-analysis/modules/{module_name}/prd.md — Phase 2 初稿
+- atool-analysis/modules/{module_name}/api.md — 接口定义
+- atool-analysis/modules/{module_name}/data-model.md — 数据模型（可能不存在，跳过）
+- .atool-docs/modules/{module_name}/data.json — 结构化数据
+
+## 编码规范约束
+{conventions_context}
+
+## 精炼规则
+参考 requirements-writer SKILL.md 的 "Refine Mode（精炼模式）" 章节，严格按照其中的精炼逻辑执行：
+1. 保留初稿 §1-§3 和原 §4 非目标（移至 §6）
+2. 补全 §4 数据需求、§5 跨模块依赖、§7 风险与假设、§8 需求追溯矩阵
+3. 增强 §2 加 FR-{MOD}-NNN 编号 + Given-When-Then AC + UI 交互表；§3 加 NFR-{MOD}-NNN 编号，标注 [待系统级确认]
+4. 输出必须包含完整 8 节结构
+
+## 输出
+原地覆盖 atool-analysis/modules/{module_name}/prd.md
+
+## 禁止行为
+- 不做交互式问答
+- 不修改 README.md / api.md / data-model.md / dev-guide.md / test-cases.md
+- 不创建新文件
+```
+
+完成后立即写入 checkpoint：
+
+```bash
+jq --arg mod "{module_name}" \
+   '.refine_status[$mod].prd_refine = "completed"' \
+   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+---
+
+#### Gate 2: PRD 覆盖率门禁（Hard Gate）
+
+**对每个模块的精炼后 prd.md 执行**：
+
+检查项（每项 20 分，满分 100）：
+
+| 检查项 | 验证方式 | 分值 |
+|--------|---------|------|
+| 8 节结构完整 | `grep -c "^## [0-9]"` ≥ 8 | 20 |
+| FR 编号存在 | `grep -c "FR-"` ≥ 1 | 20 |
+| Given-When-Then AC | `grep -c "Given\|When\|Then"` ≥ 3 | 20 |
+| NFR 编号存在 | `grep -c "NFR-"` ≥ 1 | 20 |
+| 数据需求填充 | §4 非空（> 3 行） | 20 |
+
+**通过**（≥ 70 分）→ 记录分数到 `refine_status.{name}.prd_coverage`，进入 Step B
+
+**失败**（< 70 分）→ 提供恢复选项：
+
+```
+❌ Gate 2 失败：模块 {module_name} PRD 覆盖率 {score}%（需 ≥ 70%）
+   缺失项：{列出具体未通过的检查项}
+
+   恢复选项：
+   [A] 重跑该模块的 PRD 精炼（自动重试 1 次）
+   [B] 手动编辑 prd.md 后输入 "继续" 
+   [C] 降级：跳过精炼，使用 Phase 2 初稿（标记 [未精炼]）
+```
+
+选择 A 时：重新派发 Step A sub-agent（仅 1 次重试，再失败则自动降级）
+选择 C 时：`refine_status.{name}.degraded = true, degraded_reason = "PRD coverage {score}% below threshold"`
+
+```bash
+# Gate 2 通过时写入
+jq --arg mod "{module_name}" --argjson score {score} \
+   '.refine_status[$mod].prd_coverage = $score | .refine_status[$mod].prd_gate = "passed"' \
+   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+---
+
+#### Step B: software-architecture Refine（架构精炼）
+
+仅对通过 Gate 2 的模块执行。为每个模块派发 sub-agent，prompt 模板：
+
+```
+你是 software-architecture 的精炼模式（Refine Mode）。
+
+## 任务
+在以下模块的 dev-guide.md 基础上追加架构章节。
+
+## 模块信息
+- 模块名：{module_name}
+- 模块路径：{module_path}
+- 技术栈：{detected_stack}
+
+## 输入文件（必须全部读取）
+- atool-analysis/modules/{module_name}/dev-guide.md — 当前内容（保留全部，在末尾追加）
+- atool-analysis/modules/{module_name}/prd.md — 精炼后的标准 PRD（8 节）
+- atool-analysis/modules/{module_name}/api.md — 接口定义
+- atool-analysis/modules/{module_name}/data-model.md — 数据模型（可能不存在，跳过）
+- atool-analysis/modules/{module_name}/README.md — 模块概述
+- .atool-docs/modules/{module_name}/data.json — 结构化数据（含 refine_hints）
+
+## 编码规范约束
+{conventions_context}
+
+## 精炼规则
+参考 software-architecture SKILL.md 的 "Refine Mode（精炼模式）" 章节，严格按照其中的精炼逻辑执行：
+1. 在现有 dev-guide.md 内容末尾追加（不删除原有内容）
+2. 追加 B-subset 组件设计（分层表 + 边界 + 依赖方向）
+3. 追加 C-subset 数据与交互设计（数据所有权 + 同步/异步边界 + API 契约）
+4. 追加至少 1 个 ADR（使用 7 节 ADR 模板：Status/Context/Decision/Options/Consequences/NFR Impact/Related）
+5. NFR 对齐：标注 [待系统级确认]
+
+## 输出
+原地覆盖 atool-analysis/modules/{module_name}/dev-guide.md
+
+## 禁止行为
+- 不删除 dev-guide.md 的原有内容
+- 不修改 prd.md / api.md / data-model.md / README.md / test-cases.md
+- 不创建新文件
+- 不生成项目级文档（A/D/E/F）
+```
+
+完成后写入 checkpoint：
+
+```bash
+jq --arg mod "{module_name}" \
+   '.refine_status[$mod].arch_refine = "completed"' \
+   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+---
+
+#### Gate 3: 架构精炼门禁（Hard Gate）
+
+**对每个模块的精炼后 dev-guide.md 执行**：
+
+检查项：
+- 包含 "组件设计" 或 "Component Design" 章节标题（`grep -c "组件设计\|Component Design"`）
+- 包含 "ADR" 或 "架构决策" 标题（`grep -c "ADR\|架构决策"`）
+- ADR 中包含 "Status" + "Decision" + "Consequences"（或中文等价 "状态" + "决策" + "影响"）
+
+**通过** → 记录 `arch_gate = "passed"`
+**失败** → 同 Gate 2 的三选项恢复机制（A 重试 / B 手动 / C 降级）
+
+```bash
+# Gate 3 通过时写入
+jq --arg mod "{module_name}" \
+   '.refine_status[$mod].arch_gate = "passed"' \
+   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+### 2.5.5 完成 Checkpoint
+
+每个模块完成全部精炼（或降级）后，写入完整状态：
+
+```bash
+jq --arg mod "{module_name}" \
+   --argjson score {prd_score} \
+   --arg conv "{conventions_skill}" \
+   '.refine_status[$mod] = {
+     "prd_refine": "completed",
+     "prd_coverage": $score,
+     "prd_gate": "passed",
+     "arch_refine": "completed",
+     "arch_gate": "passed",
+     "conventions_loaded": $conv,
+     "degraded": false,
+     "degraded_reason": null
+   }' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+### 2.5.6 跨 IDE 降级
+
+| IDE | 检测方式 | 行为 |
+|-----|---------|------|
+| Claude Code | Agent tool 可用 | 完整并行（≤5 模块同时） |
+| Cursor | Agent tool 不可用 | 顺序执行（每次 1 个模块） |
+| Kiro | 无 Agent tool + 无 sub-agent | 跳过 Phase 2.5（与 Phase 2 一样） |
+
+检测逻辑沿用 SKILL.md 的 Cross-IDE Adaptation 章节。
+
+---
+
+## 完成条件
+
+- 所有非降级模块的 `refine_status.{name}.arch_gate == "passed"`
+- 降级模块已记录 `degraded = true` 和 `degraded_reason`
+- 更新 state：
+
+```bash
+jq '.phases.phase2_5_refine = "completed"' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+- 打印精炼摘要：
+
+```
+✅ Phase 2.5 REFINE 完成
+   精炼模块：{M}/{N}（{M} 个精炼完成，{D} 个降级）
+   平均 PRD 覆盖率：{avg_score}%
+   降级模块：{list}（如有，标注降级原因）
+```

package/skills/project-analyze/phases/phase3-graph.md

@@ -0,0 +1,77 @@
+# Phase 3: GRAPH（纯 Bash，无 AI）
+
+**目标**：从 Phase 2 的 data.json 构建知识图谱 + 五维分析。全部通过 bash 库函数执行，禁止 AI 生成。
+
+**执行时间目标**：< 30秒
+
+## 前置检查
+
+1. 读取 `.atool-docs/analysis-state.json`
+2. 确认 `phases.phase2_understand == "completed"` — 否则先完成 Phase 2
+3. 如果 `phases.phase3_graph == "completed"` → 跳过
+4. 确认 `.atool-docs/modules/*/data.json` 至少有 1 个文件存在
+
+## 步骤
+
+### 3.1 构建知识图谱
+
+> ⚠️ **必须通过 Bash 工具执行 — 禁止 AI 直接生成 knowledge-graph.json**
+> AI 生成的 JSON 格式与 `generate-visualization.sh` 和 aTool Monitor 期望的 `nodes`/`edges` 格式不兼容。
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> cd "$PROJECT_ROOT"
+> source lib/knowledge-graph.sh 2>/dev/null
+> assemble_enhanced_graph "$DOCS_DIR" "$PROJECT_ROOT" 2>/dev/null
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+>   NODES=$(jq '.nodes | length' "$DOCS_DIR/knowledge-graph.json" 2>/dev/null || echo 0)
+>   EDGES=$(jq '.edges | length' "$DOCS_DIR/knowledge-graph.json" 2>/dev/null || echo 0)
+>   echo "Knowledge graph built: $NODES nodes, $EDGES edges"
+> else
+>   echo "WARNING: knowledge-graph.json not created. Phase 4 will skip graph-dependent docs."
+> fi
+> ```
+>
+> **成功验证**：`$DOCS_DIR/knowledge-graph.json` 存在且包含 `nodes` 和 `edges` 字段。
+> **失败处理**：记录 `phases.phase3_graph = "failed"`，继续 Phase 4（Phase 4 检测此标记后跳过图谱相关文档）。
+
+### 3.2 五维分析
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> cd "$PROJECT_ROOT"
+> source lib/multi-dimensional-analysis.sh 2>/dev/null
+> run_multi_dimensional_analysis "$DOCS_DIR" 2>/dev/null
+> if [ -f "$DOCS_DIR/multi-dimensional-analysis.json" ]; then
+>   echo "Multi-dimensional analysis complete"
+> else
+>   echo "WARNING: multi-dimensional-analysis.json not created"
+> fi
+> ```
+
+### 3.3 更新 State
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+>   STATUS="completed"
+> else
+>   STATUS="failed"
+> fi
+> jq --arg status "$STATUS" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.phases.phase3_graph = $status | .updated_at = $ts' \
+>   "$DOCS_DIR/analysis-state.json" > "$DOCS_DIR/analysis-state.json.tmp" \
+>   && mv "$DOCS_DIR/analysis-state.json.tmp" "$DOCS_DIR/analysis-state.json"
+> echo "Phase 3 status: $STATUS"
+> ```
+
+## 完成条件
+
+- `.atool-docs/knowledge-graph.json` 存在（或 state 标记为 "failed"）
+- `.atool-docs/multi-dimensional-analysis.json` 存在（可选，失败不阻断）
+- `phases.phase3_graph` 已更新为 `"completed"` 或 `"failed"`