@dtt_siye/atool 1.3.1 → 1.5.0

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

@@ -1,20 +1,34 @@
-# Phase 2: UNDERSTAND（AI Sub-Agents）
+# Phase 2: UNDERSTAND（AI Sub-Agents — 两阶段执行）
 
-**目标**：每个模块派发 1 个 sub-agent，产出三层文档（业务/技术/数据），直接写入 `atool-analysis/modules/`。
+**目标**：每个模块派发 2 个串行 sub-agent（Stage 1 → Stage 2），产出三层文档。
 
-**并发上限：5 个 sub-agent**
+**核心改进**：原设计是 1 个 sub-agent 产出 7 个文件（425 行 prompt，AI 遵循度低）。新设计拆为 2 个 stage：
+- **Stage 1**：产出 `data.json` + `README.md`（~150 行 prompt）
+- **Stage 2**：基于 data.json 产出 `api.md` + `data-model.md` + `dev-guide.md` + `prd.md` + `test-cases.md`（~120 行 prompt）
+
+---
+
+## IDE 适配（执行前检查）
+
+- **Claude Code**：使用 Agent 工具批量派发，每批最多 5 个模块并行，每模块内 Stage 1→2 串行
+- **Cursor/其他**：**顺序执行**，按 importance 降序逐模块处理（Stage 1→2 串行），每个模块完成后更新 state.json
+  - *原因*：Cursor 不支持并行 sub-agent，自动降级为逐个执行
+  - *判断方式*：若 Agent 工具不可用或不响应，自动切换到顺序模式
+
+---
 
 ## 前置检查
 
 1. 读取 `.atool-docs/analysis-state.json`
 2. 确认 `phases.phase1_setup == "completed"` — 否则先执行 Phase 1
 3. 如果 `phases.phase2_understand == "completed"` → 跳过
-4. 加载模块列表 `state.modules[]`
+4. 加载模块列表 `state.modules[]`（优先使用聚合后的 `aggregated_modules`）
 
 ## 输入数据
 
 - Pre-Scan 数据：`.atool-docs/pre-scan/{module-slug}.json`（如存在）
 - 技术栈规则：`rules/{STACK}.md`（优先），fallback `rules/generic.md`
+- Prompt 模板：`prompts/understand-agent.md`（包含 Stage 1 和 Stage 2 两个模板）
 
 ### Pre-scan 降级规则
 
@@ -36,43 +50,112 @@
 > **执行命令（可选）：**
 > ```bash
 > DOCS_DIR="$(pwd)/.atool-docs"
-> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+> # 优先使用聚合后的模块列表
+> if jq -e '.aggregated_modules' "$DOCS_DIR/pre-scan/manifest.json" &>/dev/null; then
+>   jq -r '.aggregated_modules | sort_by(-.importance) | .[].slug' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null
+> else
 >   jq -r '.modules | sort_by(-.importance) | .[].slug' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null
 > fi
 > ```
 
 否则按 `state.modules[]` 原始顺序。
 
-### 2.3 批量派发 Sub-Agents
+### 2.3 两阶段批量派发 Sub-Agents
 
 **规则**：
-- 每批最多 5 个 sub-agent 并行（使用 Agent 工具）
+- 每批最多 5 个模块并行
+- 每个模块内部严格串行：先 Stage 1，确认 data.json 生成后，再 Stage 2
 - 等待当前批次**全部完成**后再派发下一批
-- 每个 sub-agent 完成后立即更新 `module_status`
 
-**每个 sub-agent 使用 `prompts/understand-agent.md` 模板**
+#### Stage 1 派发
 
-派发前准备每个 sub-agent 的变量：
+**使用 `prompts/understand-agent.md` 中的「Stage 1 Prompt」模板**
+
+派发前准备变量：
 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 内联具体指令）
+6. `{project_name}` — 项目名
+7. `{module_list}` — 所有模块名列表
+
+#### Stage 1 验证（硬性）
+
+**在 Stage 1 sub-agent 完成后立即验证**：
+
+```bash
+DOCS_DIR="$(pwd)/.atool-docs"
+MODULE_SLUG="{module-slug}"
+# 验证 data.json 存在且是合法 JSON
+if [ -f "$DOCS_DIR/modules/$MODULE_SLUG/data.json" ] && jq empty "$DOCS_DIR/modules/$MODULE_SLUG/data.json" 2>/dev/null; then
+  # 验证必需字段存在
+  HAS_APIS=$(jq 'has("exposed_apis")' "$DOCS_DIR/modules/$MODULE_SLUG/data.json")
+  HAS_ENTITIES=$(jq 'has("data_entities")' "$DOCS_DIR/modules/$MODULE_SLUG/data.json")
+  HAS_DEPS=$(jq 'has("dependencies")' "$DOCS_DIR/modules/$MODULE_SLUG/data.json")
+  if [ "$HAS_APIS" = "true" ] && [ "$HAS_DEPS" = "true" ]; then
+    echo "✅ Stage 1 PASS: $MODULE_SLUG data.json valid"
+  else
+    echo "⚠️ Stage 1 WARNING: $MODULE_SLUG data.json missing fields (apis=$HAS_APIS deps=$HAS_DEPS)"
+  fi
+else
+  echo "❌ Stage 1 FAIL: $MODULE_SLUG data.json missing or invalid"
+fi
+# 验证 README.md 存在且行数 < 300
+if [ -f "atool-analysis/modules/$MODULE_SLUG/README.md" ]; then
+  LINES=$(wc -l < "atool-analysis/modules/$MODULE_SLUG/README.md" | tr -d ' ')
+  if [ "$LINES" -gt 300 ]; then
+    echo "⚠️ Stage 1 WARNING: $MODULE_SLUG README.md too long ($LINES lines, should be <150)"
+  fi
+else
+  echo "❌ Stage 1 FAIL: $MODULE_SLUG README.md missing"
+fi
+```
+
+**如果 Stage 1 验证失败**：该模块不进入 Stage 2，标记为 "failed"，打印错误信息，其他模块继续。
+
+#### Stage 2 派发
+
+**使用 `prompts/understand-agent.md` 中的「Stage 2 Prompt」模板**
+
+变量（比 Stage 1 少，因为数据已从 data.json 获取）：
+1. `{module_name}` — 模块名（slug）
+2. `{module_path}` — 模块路径
+3. `{stack}` — 技术栈
+4. `{project_name}` — 项目名
+
+#### Stage 2 验证（硬性）
+
+```bash
+MODULE_SLUG="{module-slug}"
+# 验证核心文件存在
+MISSING=""
+for f in api.md dev-guide.md prd.md test-cases.md; do
+  [ ! -f "atool-analysis/modules/$MODULE_SLUG/$f" ] && MISSING="$MISSING $f"
+done
+if [ -z "$MISSING" ]; then
+  echo "✅ Stage 2 PASS: $MODULE_SLUG all docs generated"
+else
+  echo "❌ Stage 2 FAIL: $MODULE_SLUG missing:$MISSING"
+fi
+```
 
 ### 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）
+atool-analysis/modules/{module-name}/README.md       # Stage 1: 业务摘要（<150行）
+atool-analysis/modules/{module-name}/api.md          # Stage 2: 接口文档
+atool-analysis/modules/{module-name}/data-model.md   # Stage 2: 数据模型（如有实体）
+atool-analysis/modules/{module-name}/dev-guide.md    # Stage 2: 开发指引
+atool-analysis/modules/{module-name}/prd.md          # Stage 2: 模块 PRD
+atool-analysis/modules/{module-name}/test-cases.md   # Stage 2: 测试用例
+.atool-docs/modules/{module-name}/data.json          # Stage 1: 机器数据
 ```
 
 ### 2.5 Checkpoint 写入
 
-每个模块完成后：
+**只有 Stage 1 + Stage 2 都验证通过后**才写入 checkpoint：
 
 > **执行命令（必须通过 Bash 工具）：**
 > ```bash
@@ -84,31 +167,59 @@ atool-analysis/modules/{module-name}/dev-guide.md    # 层2c: 开发指引
 >   && mv "$DOCS_DIR/analysis-state.json.tmp" "$DOCS_DIR/analysis-state.json"
 > ```
 
+**重要**：不再在每个 sub-agent 完成后立即写入 checkpoint。只在两个 stage 都验证通过后才写入。
+
 ### 2.6 断点续传
 
 如果从中断恢复：
 1. 读取 `module_status`，找到 `phase2 != "completed"` 的模块
 2. 只对未完成模块派发 sub-agent
 3. 已完成模块跳过
+4. 对 in_progress 的模块，检查 data.json 是否存在：
+   - 存在 → 从 Stage 2 继续
+   - 不存在 → 从 Stage 1 重新开始
 
 ## 完成条件
 
 - 所有模块的 `module_status.{slug}.phase2 == "completed"`
-- 每个模块至少 5/6 核心文件存在（data-model.md 可选）：
-  - `atool-analysis/modules/*/README.md` ✓ 必须
-  - `atool-analysis/modules/*/api.md` ✓ 必须
+- 每个模块至少满足以下（data-model.md 可选）：
+  - `atool-analysis/modules/*/README.md` ✓ 必须（行数 < 300）
+  - `atool-analysis/modules/*/api.md` ✓ 必须（或 README.md 注明无 API）
   - `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"`
+- `.atool-docs/modules/*/data.json` 全部存在且是合法 JSON
+- **硬验证**（必须通过 Bash 执行）：
 
 > **执行命令：**
 > ```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"
+> FAIL_COUNT=0
+> for slug in $(jq -r '.module_status | keys[]' "$DOCS_DIR/analysis-state.json" 2>/dev/null); do
+>   DATA_JSON=".atool-docs/modules/$slug/data.json"
+>   README="atool-analysis/modules/$slug/README.md"
+>   # 检查 data.json
+>   if ! jq empty "$DATA_JSON" 2>/dev/null; then
+>     echo "❌ FAIL: $slug — data.json missing or invalid"
+>     FAIL_COUNT=$((FAIL_COUNT + 1))
+>     continue
+>   fi
+>   # 检查核心文档
+>   for f in README.md dev-guide.md prd.md test-cases.md; do
+>     if [ ! -f "atool-analysis/modules/$slug/$f" ]; then
+>       echo "❌ FAIL: $slug — $f missing"
+>       FAIL_COUNT=$((FAIL_COUNT + 1))
+>     fi
+>   done
+> done
+> if [ "$FAIL_COUNT" -eq 0 ]; then
+>   echo "✅ All modules validated"
+>   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"
+> else
+>   echo "❌ $FAIL_COUNT validation failures — Phase 2 NOT completed"
+> fi
 > ```

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

@@ -9,7 +9,7 @@
 ## 前置检查
 
 1. `analysis-state.json` 中 `phases.phase2_understand == "completed"`
-2. 读取 `detected_stack` 用于 conventions 加载
+2. 读取 `stack` 用于 conventions 加载
 3. 如果 `phases.phase2_5_refine == "completed"` 且非 `--force`，跳过本 Phase
 4. 如果 `--skip-refine`，跳过本 Phase
 
@@ -27,7 +27,7 @@
 
 ```bash
 # 从 state.json 读取技术栈
-STACK=$(jq -r '.detected_stack // "generic"' .atool-docs/analysis-state.json)
+STACK=$(jq -r '.stack // "generic"' .atool-docs/analysis-state.json)
 ```
 
 从对应 conventions SKILL.md 中提取以下章节内容（不加载全文，控制在 ~200 行）：
@@ -94,11 +94,13 @@ MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-sc
 {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 节结构
+**必须读取并遵循**：`~/.claude/skills/requirements-writer/SKILL.md` 中的 **Refine Mode（精炼模式）** 章节。该章节定义了标准的 PRD 精炼流程和输出格式。按照其中的精炼规则逐条执行。
+
+补充说明（与 Refine Mode 保持一致）：
+- 保留初稿 §1-§3 和原 §4 非目标（移至 §6）
+- 补全 §4 数据需求、§5 跨模块依赖、§7 风险与假设、§8 需求追溯矩阵
+- 增强 §2 加 FR-{MOD}-NNN 编号 + Given-When-Then AC + UI 交互表；§3 加 NFR-{MOD}-NNN 编号，标注 [待系统级确认]
+- 输出必须包含完整 8 节结构
 
 ## 输出
 原地覆盖 atool-analysis/modules/{module_name}/prd.md
@@ -109,12 +111,13 @@ MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-sc
 - 不创建新文件
 ```
 
-完成后立即写入 checkpoint：
+完成后立即写入 checkpoint（使用唯一临时文件避免并发竞争）：
 
 ```bash
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}"
 jq --arg mod "{module_name}" \
    '.refine_status[$mod].prd_refine = "completed"' \
-   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ---
@@ -151,10 +154,11 @@ jq --arg mod "{module_name}" \
 选择 C 时：`refine_status.{name}.degraded = true, degraded_reason = "PRD coverage {score}% below threshold"`
 
 ```bash
-# Gate 2 通过时写入
+# Gate 2 通过时写入（使用唯一临时文件）
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.gate2"
 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
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ---
@@ -186,12 +190,14 @@ jq --arg mod "{module_name}" --argjson score {score} \
 {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 对齐：标注 [待系统级确认]
+**必须读取并遵循**：`~/.claude/skills/software-architecture/SKILL.md` 中的 **Refine Mode（精炼模式）** 章节。该章节定义了标准的架构设计精炼流程和输出格式。按照其中的精炼规则逐条执行。
+
+补充说明（与 Refine Mode 保持一致）：
+- 在现有 dev-guide.md 内容末尾追加（不删除原有内容）
+- 追加 B-subset 组件设计（分层表 + 边界 + 依赖方向）
+- 追加 C-subset 数据与交互设计（数据所有权 + 同步/异步边界 + API 契约）
+- 追加至少 1 个 ADR（使用 7 节 ADR 模板：Status/Context/Decision/Options/Consequences/NFR Impact/Related）
+- NFR 对齐：标注 [待系统级确认]
 
 ## 输出
 原地覆盖 atool-analysis/modules/{module_name}/dev-guide.md
@@ -203,12 +209,13 @@ jq --arg mod "{module_name}" --argjson score {score} \
 - 不生成项目级文档（A/D/E/F）
 ```
 
-完成后写入 checkpoint：
+完成后写入 checkpoint（使用唯一临时文件）：
 
 ```bash
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.archrefine"
 jq --arg mod "{module_name}" \
    '.refine_status[$mod].arch_refine = "completed"' \
-   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ---
@@ -226,17 +233,19 @@ jq --arg mod "{module_name}" \
 **失败** → 同 Gate 2 的三选项恢复机制（A 重试 / B 手动 / C 降级）
 
 ```bash
-# Gate 3 通过时写入
+# Gate 3 通过时写入（使用唯一临时文件）
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.gate3"
 jq --arg mod "{module_name}" \
    '.refine_status[$mod].arch_gate = "passed"' \
-   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ### 2.5.5 完成 Checkpoint
 
-每个模块完成全部精炼（或降级）后，写入完整状态：
+每个模块完成全部精炼（或降级）后，写入完整状态（使用唯一临时文件）：
 
 ```bash
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.final"
 jq --arg mod "{module_name}" \
    --argjson score {prd_score} \
    --arg conv "{conventions_skill}" \
@@ -249,7 +258,7 @@ jq --arg mod "{module_name}" \
      "conventions_loaded": $conv,
      "degraded": false,
      "degraded_reason": null
-   }' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+   }' .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ### 2.5.6 跨 IDE 降级

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

@@ -2,14 +2,47 @@
 
 **目标**：从 Phase 2 的 data.json 构建知识图谱 + 五维分析。全部通过 bash 库函数执行，禁止 AI 生成。
 
-**执行时间目标**：< 30秒
+**执行时间目标**：< 30秒（大型项目 < 60秒）
+
+**性能特点**：
+- Pure bash + jq（无 AI 开销）
+- 线性时间复杂度：O(M*E)，M=模块数，E=边数
+- 内存消耗：~50MB per 100 modules（jq slurp）
+- 中断保护：超过 120 秒自动停止，记录为 "failed"
 
 ## 前置检查
 
 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 个文件存在
+4. **data.json 存在性硬验证（必须通过 Bash 执行）**：
+
+> **执行命令：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> VALID_COUNT=0
+> INVALID_COUNT=0
+> for f in "$DOCS_DIR/modules/"*/data.json; do
+>   [ -f "$f" ] || continue
+>   if jq empty "$f" 2>/dev/null; then
+>     VALID_COUNT=$((VALID_COUNT + 1))
+>   else
+>     MODULE=$(basename "$(dirname "$f")")
+>     echo "⚠️ Invalid JSON: $MODULE/data.json"
+>     INVALID_COUNT=$((INVALID_COUNT + 1))
+>   fi
+> done
+> echo "Valid data.json: $VALID_COUNT | Invalid: $INVALID_COUNT"
+> if [ "$VALID_COUNT" -eq 0 ]; then
+>   echo "❌ BLOCKED: No valid data.json files found. Phase 2 must complete successfully first."
+>   echo "   Run Phase 2 to generate data.json files before proceeding."
+> else
+>   echo "✅ Pre-check passed: $VALID_COUNT modules have valid data"
+> fi
+> ```
+>
+> **如果 VALID_COUNT == 0**：**终止 Phase 3**，将 `phases.phase3_graph` 标记为 `"blocked"`，告知用户需要先完成 Phase 2。
+> **如果 VALID_COUNT > 0 但有 INVALID_COUNT**：记录 warning，仅使用 valid data.json 构建图谱。
 
 ## 步骤
 
@@ -58,7 +91,7 @@
 > **执行命令（必须通过 Bash 工具）：**
 > ```bash
 > DOCS_DIR="$(pwd)/.atool-docs"
-> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ] && jq -e '.nodes and .edges' "$DOCS_DIR/knowledge-graph.json" &>/dev/null; then
 >   STATUS="completed"
 > else
 >   STATUS="failed"
@@ -72,6 +105,7 @@
 
 ## 完成条件
 
-- `.atool-docs/knowledge-graph.json` 存在（或 state 标记为 "failed"）
+- 前置检查通过（至少 1 个有效 data.json）
+- `.atool-docs/knowledge-graph.json` 存在**且**包含 `nodes` 和 `edges` 字段
 - `.atool-docs/multi-dimensional-analysis.json` 存在（可选，失败不阻断）
-- `phases.phase3_graph` 已更新为 `"completed"` 或 `"failed"`
+- `phases.phase3_graph` 已更新为 `"completed"` 或 `"failed"` 或 `"blocked"`

package/skills/project-analyze/phases/phase4-synthesize.md

@@ -2,10 +2,26 @@
 
 **目标**：以 Phase 2.5 精炼后的模块文档 + 知识图谱为数据源，**聚合**为项目级交付物。Phase 4 不再从零生成模块级内容，而是聚合、补全项目级独有文档、并生成 PROJECT-DELIVERABLE.md 总览入口。
 
+---
+
+## IDE 适配（执行前检查）
+
+- **Claude Code**：主 Agent 单条线执行 Phase 4 逻辑（无额外并行）
+- **Cursor/其他**：同 Claude Code（Phase 4 本身是单 Agent，无 sub-agent 并行需求）
+
+**注**：Phase 4 与 Phase 2/4 不同，本身不使用 sub-agents，仅为单条线聚合逻辑，故无 IDE 差异。
+
+---
+
 ## 前置检查
 
 1. 确认 `phases.phase2_understand == "completed"`（必须）
-2. 检查 `phases.phase3_graph`：
+2. 检查 `phases.phase2_5_refine`（必须）：
+   - `"completed"` → 使用精炼后的 prd.md、dev-guide.md（含 ADR、架构设计）
+   - `"skipped"` 或 `"failed"` → **警告用户并询问是否继续**
+     - 若继续：使用 Phase 2 初稿（内容可能不完整）
+     - 若中止：建议用户重新执行 Phase 2.5
+3. 检查 `phases.phase3_graph`：
    - `"completed"` → 可使用图谱数据生成完整文档
    - `"failed"` → 跳过图谱相关输出（data-flow.mmd、module-dependencies.mmd），其余正常生成
 

package/skills/project-analyze/phases/phase5-export.md

@@ -79,7 +79,7 @@
 >   "module_count": $MODULE_COUNT,
 >   "file_count": $FILE_COUNT,
 >   "analyzed_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
->   "analysis_version": "5.1.0",
+>   "analysis_version": "5.2.0",
 >   "atool_analysis_schema": "1.0"
 > }
 > EOF
@@ -101,7 +101,44 @@
 > fi
 > ```
 
-### 5.4 生成 EXPORT-FULL.md（可选）
+### 5.4 生成 Cytoscape.js 可视化（可选）
+
+**触发条件**：分析完成时，生成交互式 HTML 可视化
+
+> **执行命令（通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+>
+> # 检查 knowledge-graph.json 是否存在
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+>   # 调用 generate-visualization.sh
+>   if [ -f "$PROJECT_ROOT/lib/generate-visualization.sh" ]; then
+>     source "$PROJECT_ROOT/lib/generate-visualization.sh"
+>     generate_visualization "$DOCS_DIR"
+>     if [ -f "$DOCS_DIR/visualization/index.html" ]; then
+>       echo "✅ Visualization generated: $DOCS_DIR/visualization/index.html"
+>       du -h "$DOCS_DIR/visualization/index.html" | awk '{print "Size: " $1}'
+>     fi
+>   else
+>     echo "⚠️ lib/generate-visualization.sh not found — skipping visualization"
+>   fi
+> else
+>   echo "⚠️ knowledge-graph.json not found — cannot generate visualization"
+> fi
+> ```
+
+**输出**：
+- `.atool-docs/visualization/index.html` — 完整交互式可视化
+  - Cytoscape.js + dagre 布局
+  - 14 节点类型着色，24 边类型线型
+  - G1-G5 缩放控件
+  - 搜索、影响分析、邻域查询
+  - 离线可打开（JS 库缓存到 `~/.atool/cache/visualization/`）
+
+---
+
+### 5.5 生成 EXPORT-FULL.md（可选）
 
 **触发条件**：用户使用 `--export` 参数，或在完成摘要中选择导出。
 
@@ -111,7 +148,8 @@
 OUTPUT="atool-analysis/EXPORT-FULL.md"
 
 # 1. 标题 + 元信息
-echo "# $(jq -r '.project' .atool-docs/analysis-state.json) — 完整项目交付文档" > "$OUTPUT"
+PROJECT_NAME=$(jq -r '.project // (.project_root | split("/") | last)' .atool-docs/analysis-state.json)
+echo "# $PROJECT_NAME — 完整项目交付文档" > "$OUTPUT"
 echo "" >> "$OUTPUT"
 echo "> 自动生成于 $(date '+%Y-%m-%d %H:%M') | 单文件导出版" >> "$OUTPUT"
 echo "" >> "$OUTPUT"
@@ -164,7 +202,7 @@ jq -r '.refine_status | to_entries[] | "| \(.key) | \(.value.prd_coverage // "N/
 jq '.deliverable_status.export_single_file = "completed"' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
 ```
 
-### 5.5 更新 State + 打印完成摘要
+### 5.6 更新 State + 打印完成摘要
 
 > **执行命令（必须通过 Bash 工具）：**
 > ```bash