@dtt_siye/atool 1.4.0 → 1.5.0

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

@@ -1,13 +1,17 @@
-# 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），产出三层文档。
+
+**核心改进**：原设计是 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 个并行，等待全部完成后派发下一批
-- **Cursor/其他**：**顺序执行**，按 importance 降序逐模块处理，每个模块完成后更新 state.json
+- **Claude Code**：使用 Agent 工具批量派发，每批最多 5 个模块并行，每模块内 Stage 1→2 串行
+- **Cursor/其他**：**顺序执行**，按 importance 降序逐模块处理（Stage 1→2 串行），每个模块完成后更新 state.json
   - *原因*：Cursor 不支持并行 sub-agent，自动降级为逐个执行
   - *判断方式*：若 Agent 工具不可用或不响应，自动切换到顺序模式
 
@@ -18,12 +22,13 @@
 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 降级规则
 
@@ -45,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 派发
+
+**使用 `prompts/understand-agent.md` 中的「Stage 1 Prompt」模板**
 
-派发前准备每个 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 内联具体指令）
+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
@@ -93,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/phase3-graph.md

@@ -15,7 +15,34 @@
 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 构建图谱。
 
 ## 步骤
 
@@ -64,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"
@@ -78,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"`