@dtt_siye/atool 1.3.1 → 1.5.0

package/skills/ci-feedback/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: ci-feedback
+description: "Use after modifying source files to run local build/test and get automated feedback. 在修改源码后使用 — 运行本地构建/测试获取自动化反馈，失败时自动进入调试流程."
+version: 0.1.0
+category: quality
+---
+
+# CI Feedback — Local Build & Test Automation
+
+Automatically runs project build and test commands, parses results, and feeds them back into the AI workflow. Creates a tight feedback loop without requiring CI/CD infrastructure.
+
+## When to Use
+
+- After modifying source files (auto-suggested by doc-sync-reminder or task-state-tracker)
+- Before claiming a task complete (invoked by verification-before-completion)
+- When the user says "run the tests" or "check if it builds"
+- When debugging (auto-triggered by systematic-debugging after fix attempts)
+
+## How It Works
+
+### Step 1: Detect Build Commands
+
+Read build/test commands from the project's CLAUDE.md `## Build & Run` section. If not found, auto-detect from project files:
+
+| Project File | Build Command | Test Command |
+|-------------|---------------|--------------|
+| `pom.xml` | `mvn compile -q` | `mvn test -q` |
+| `build.gradle` / `build.gradle.kts` | `gradle compileJava` | `gradle test` |
+| `package.json` | `npm run build` | `npm test` |
+| `Cargo.toml` | `cargo build` | `cargo test` |
+| `go.mod` | `go build ./...` | `go test ./...` |
+| `pyproject.toml` / `setup.py` | `python -m compileall .` | `pytest` |
+| `pubspec.yaml` | `flutter build` | `flutter test` |
+| `Makefile` | `make build` | `make test` |
+
+### Step 2: Run Build
+
+Execute the build command and capture:
+- Exit code (0 = success)
+- stdout (warnings)
+- stderr (errors)
+
+```
+Build Result:
+- Status: PASS / FAIL
+- Duration: {time}
+- Warnings: {count} (list if < 10)
+- Errors: {count} (list all)
+```
+
+If build FAILS → go to Step 4 (Auto-debug).
+
+### Step 3: Run Tests
+
+Execute the test command and capture:
+- Exit code
+- Test summary (passed/failed/skipped)
+- Specific failure details
+
+```
+Test Result:
+- Status: PASS / FAIL
+- Tests: {passed} passed, {failed} failed, {skipped} skipped
+- Duration: {time}
+- Failures:
+  - {test_name}: {error_message} (file:line)
+```
+
+If tests FAIL → go to Step 4 (Auto-debug).
+
+### Step 4: Auto-debug on Failure
+
+When build or tests fail:
+
+1. **Parse the error output** — extract file paths, line numbers, error messages
+2. **Classify the error**:
+   - Compilation error → syntax/type mismatch
+   - Test assertion → logic error
+   - Missing dependency → configuration error
+   - Timeout → performance issue
+3. **Invoke /systematic-debugging workflow**:
+   - Identify root cause (NOT symptoms)
+   - Propose targeted fix
+   - Re-run only the failed tests (if possible)
+4. **Track in task-state.json**:
+   ```json
+   {
+     "last_build_status": "FAIL",
+     "last_build_errors": 2,
+     "auto_debug_attempts": 1,
+     "pending_actions": ["fix_build_error", "update_docs"]
+   }
+   ```
+
+### Step 5: Update Task State
+
+On success, update `.claude/task-state.json`:
+```json
+{
+  "verification_passed": true,
+  "last_build_status": "PASS",
+  "last_test_status": "PASS",
+  "pending_actions": ["update_docs"]
+}
+```
+
+On failure, the state tracks retry attempts and remaining errors.
+
+## Integration Points
+
+### With task-state-tracker
+Reads `.claude/task-state.json` to know which files were modified, then runs targeted tests if the framework supports it.
+
+### With verification-before-completion
+`/verification-before-completion` invokes ci-feedback as part of its gate check: "tests pass" is a hard requirement.
+
+### With systematic-debugging
+On build/test failure, automatically enters the systematic-debugging workflow rather than blindly retrying.
+
+### With architecture-guard
+After a successful build, optionally runs architecture-guard to check for structural violations.
+
+## Output Format
+
+```
+## CI Feedback Report
+
+### Build
+| Metric | Value |
+|--------|-------|
+| Status | PASS |
+| Duration | 3.2s |
+| Warnings | 1 (unused import in UserService.java) |
+
+### Tests
+| Metric | Value |
+|--------|-------|
+| Status | PASS |
+| Total | 47 |
+| Passed | 47 |
+| Failed | 0 |
+| Duration | 12.5s |
+
+### Summary
+All checks passed. Task state updated.
+Remaining: update docs before completion.
+```
+
+## Retry Strategy
+
+When auto-debugging:
+1. Fix the identified root cause
+2. Re-run ONLY the failing tests (if framework supports file-specific tests)
+3. If fix introduces new failures → stop and report to user
+4. Maximum 3 auto-debug cycles before escalating to user
+
+## Skill 协作
+
+| 协作 Skill | 触发条件 | 交互方式 |
+|-----------|---------|---------|
+| verification-before-completion | Before claiming done | 作为验证步骤执行构建+测试 |
+| systematic-debugging | Build/test failure | 自动进入调试流程 |
+| task-state-tracker | State file available | 读取修改文件列表，更新验证状态 |
+| architecture-guard | Build success | 可选执行架构检查 |
+| {stack}-conventions | Test framework detection | 使用栈级测试命令 |

package/skills/project-analyze/SKILL.md

@@ -78,10 +78,23 @@ Pipeline 中 AI 与 bash 工具的分工遵循核心原则：**确定性操作
 ### 6-Phase 架构
 
 ```
-Phase 1: SETUP      → phases/phase1-setup.md        (bash only, no AI, ~30秒)
-Phase 2: UNDERSTAND → phases/phase2-understand.md   (AI sub-agents ≤5并行)
+Phase 1: SETUP      → phases/phase1-setup.md        (bash + AI模块聚合, ~30秒)
+  ├─ 技术栈检测 (bash)
+  ├─ Pre-scan 语法提取 (bash)
+  ├─ 模块发现 + 聚合 (AI, rules/{STACK}.md 聚合规则)
+  └─ 用户确认分析参数
+
+Phase 2: UNDERSTAND → phases/phase2-understand.md   (AI sub-agents ≤5并行, 两阶段执行)
+  ├─ Stage 1: data.json + README.md (结构化提取)
+  ├─ Stage 1 验证 (bash, data.json 合法性 + README 行数)
+  ├─ Stage 2: api.md + data-model.md + dev-guide.md + prd.md + test-cases.md
+  └─ Stage 2 验证 (bash, 核心文档存在性)
+  注: 每个 sub-agent 内部 Stage 1→2 串行, checkpoint 仅在两阶段都验证通过后写入
+
 Phase 2.5: REFINE   → phases/phase2.5-refine.md     (AI sub-agents ≤5并行，串联 requirements-writer + software-architecture Refine Mode)
 Phase 3: GRAPH      → phases/phase3-graph.md        (bash only, no AI, ~30秒)
+  └─ 前置检查: data.json 存在性硬验证, VALID_COUNT=0 时 BLOCKED
+
 Phase 4: SYNTHESIZE → phases/phase4-synthesize.md   (main agent, 聚合模式)
 Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文件)
 ```
@@ -94,7 +107,10 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文
 4. **Phase 2 并发上限 5 个 sub-agent**，超出部分按 importance 降序分批排队
 5. **Phase 3 bash 调用失败时**：在 state.json 记录 `phase3_graph: "failed"`，继续 Phase 4（跳过图谱相关文档，Phase 4 检查此标记）
 6. **断点续传**：先读 state.json，跳过 `status: "completed"` 的 phase
-7. Phase 2.5 在 Phase 2 完成后自动执行；`--skip-refine` 可跳过；`--refine-threshold N` 自定义门禁阈值（默认 70）
+7. **Phase 2.5 参数识别**（无需 bash 解析，直接在用户消息中匹配）：
+   - `--skip-refine`：用户消息中包含此字符串 → Phase 2.5 标记为 "skipped"，跳过精炼链，直进 Phase 3
+   - `--refine-threshold N`：用户消息中包含此模式 → 提取 N 作为 Gate 1/2/3 门禁阈值（默认 70）
+   - 例：用户说"分析项目 --skip-refine"→ 立即检测到 --skip-refine 字符串，跳过 Phase 2.5
 
 ### 状态管理（简化版）
 
@@ -103,7 +119,8 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文
 {
   "version": "5.2.0",
   "project": "...",
-  "detected_stack": "java-spring",
+  "project_root": "...",
+  "stack": "java-spring",
   "depth": "L2",
   "phases": {
     "phase1_setup": "completed",
@@ -139,7 +156,7 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文
 }
 ```
 
-status 枚举值：`"pending"` | `"in_progress"` | `"completed"` | `"failed"` | `"skipped"`
+status 枚举值：`"pending"` | `"in_progress"` | `"completed"` | `"failed"` | `"skipped"` | `"blocked"`
 
 ### HARD GATE — bash Phase 执行验证
 
@@ -186,24 +203,72 @@ Modules processed in importance order, one at a time. Progress line per module.
 ## State Management & Checkpoint/Resume
 
 ### Checkpoint Write Timing
-After each sub-agent completes a module analysis, immediately write checkpoint to `analysis-state.json`:
+Phase 2 checkpoint **仅在 Stage 1 + Stage 2 都验证通过后**写入（详见 phase2-understand.md §2.5）。
+Phase 3 checkpoint 在 data.json 前置检查通过且 knowledge-graph.json 生成后写入。
+其他 Phase 完成后立即写入 checkpoint。
+
+```
+Phase 2 每模块:
+  Stage 1 完成 → 验证 data.json → 通过 → Stage 2
+  Stage 2 完成 → 验证 5 个核心文档 → 通过 → 写入 checkpoint
+  任一阶段失败 → 不写 checkpoint, 标记为 "failed"
+
+Phase 3:
+  data.json 前置检查失败 → 标记 "blocked", 不继续
+  knowledge-graph.json 生成成功 → 标记 "completed"
+```
+
+### Resume Flow（断点恢复决策树）
+
+**入口**：执行 Phase 1 setup 时自动检测恢复状态
+
 ```
-state.modules[module_slug].{phase}_status = "completed"
-state.modules[module_slug].{phase}_completed_at = now()
-state.checkpoint = { last_completed_phase, last_completed_module, next_pending_module, batch_index, total_batches, timestamp }
-write analysis-state.json
+1. 读取 .atool-docs/analysis-state.json（若不存在）
+   └─ 启动全新分析（fresh start）
+
+2. 存在 state.json
+   ├─ phases.phase1_setup != "completed"
+   │  └─ 执行 Phase 1（重新检测栈 / manifest / importance）
+   │
+   ├─ phases.phase1_setup == "completed"
+   │  ├─ 检查 phase2_understand 状态
+   │  │  ├─ "pending" → 执行 Phase 2（全部模块）
+   │  │  ├─ "in_progress" → 恢复到 Phase 2 中断位置（读 state.module_status，跳过已完成）
+   │  │  └─ "completed" → 进入 Phase 2.5
+   │  │
+   │  ├─ 检查 phase2_5_refine 状态
+   │  │  ├─ "pending" / "failed" → 执行 Phase 2.5（全部模块）
+   │  │  ├─ "in_progress" → 恢复精炼进度（读 state.refine_status，跳过已通过 Gate 3）
+   │  │  └─ "completed" / "skipped" → 进入 Phase 3
+   │  │
+   │  ├─ 检查 phase3_graph 状态
+   │  │  ├─ "pending" → 执行 Phase 3（知识图谱生成）
+   │  │  ├─ "blocked" → data.json 缺失, 需回到 Phase 2 重新执行
+   │  │  ├─ "in_progress" / "failed" → 重新执行 Phase 3
+   │  │  └─ "completed" → 进入 Phase 4
+   │  │
+   │  ├─ 检查 phase4_synthesize 状态
+   │  │  ├─ "pending" → 执行 Phase 4（聚合合成）
+   │  │  ├─ "in_progress" / "failed" → 重新执行 Phase 4
+   │  │  └─ "completed" → 进入 Phase 5
+   │  │
+   │  └─ 检查 phase5_export 状态
+   │     ├─ "pending" → 执行 Phase 5（最终导出）
+   │     ├─ "in_progress" / "failed" → 重新执行 Phase 5
+   │     └─ "completed" → 分析完成（可选重新导出）
 ```
 
-### Resume Flow
-1. Read `.atool-docs/analysis-state.json`
-2. If no state file → full analysis
-3. If `phases.phase1_setup != "completed"` → execute Phase 1
-4. Detect stale modules (file hash mismatch) → mark for re-analysis
-5. Determine resume point from checkpoint
-6. Execute pending phases, skip completed, rerun stale
-7. Update final state
+**断点恢复的具体判断**（在每个 Phase 入口执行）：
+- 若 phase 状态为 "completed" 且无 `--force`，**跳过该 phase**
+- 若 phase 状态为 "in_progress"/"failed"，**重新执行该 phase**（覆盖部分输出）
+- 若 phase 状态为 "pending"，**首次执行该 phase**
+
+**文件变更检测**（Phase 2+ 的可选优化）：
+- 计算 project root 下所有源文件的 hash（与 manifest.json 对比）
+- 若有新增/删除/修改的文件，标记对应模块为"需重新分析"
+- 该模块在 Phase 2 中重新派发 sub-agent（即使之前已完成）
 
-Detailed resume logic: see `phases/phase1-setup.md`.
+详见各 Phase 的前置检查条款（phase1-setup.md → phase5-export.md）
 
 ### Incremental Document Recovery
 When resuming Phase 5, incrementally update already-generated documents using `<!-- aTool-module-start:{slug} -->` markers. Only regenerate changed modules.
@@ -274,6 +339,51 @@ When resuming Phase 5, incrementally update already-generated documents using `<
 
 ---
 
+## 调试指南（Debug Guide）
+
+### 查看当前分析状态
+```bash
+cat .atool-docs/analysis-state.json | jq '.phases'
+# 输出每个 Phase 的状态（completed/in_progress/failed/pending）
+```
+
+### 强制重新执行某个 Phase
+```bash
+# 删除特定 Phase 的状态
+jq '.phases.{phase_name} = "pending"' .atool-docs/analysis-state.json > .tmp && mv .tmp .atool-docs/analysis-state.json
+
+# 示例：重新执行 Phase 2
+jq '.phases.phase2_understand = "pending"' .atool-docs/analysis-state.json > .tmp && mv .tmp .atool-docs/analysis-state.json
+
+# 重新触发分析
+# 在对话中说：分析项目 （AI 会检测到 phase2_understand = "pending"，重新执行）
+```
+
+### 完全重置分析（回到 Phase 1）
+```bash
+rm -rf .atool-docs/
+# 重新触发分析会从 Phase 1 开始
+```
+
+### 查看模块分析进度
+```bash
+# 查看每个模块在 Phase 2 的状态
+jq '.module_status' .atool-docs/analysis-state.json
+
+# 查看 Phase 2.5 精炼进度
+jq '.refine_status' .atool-docs/analysis-state.json
+```
+
+### 诊断常见问题
+| 问题 | 诊断命令 | 解决方案 |
+|------|---------|---------|
+| 没有检测到模块 | `cat .atool-docs/pre-scan/manifest.json \| jq '.modules'` | 检查源文件格式或 detect-stack 规则 |
+| phase3_graph 失败 | `cat .atool-docs/analysis-state.json \| jq '.phases.phase3_graph'` | 运行 `source lib/knowledge-graph.sh; assemble_enhanced_graph` 检查错误 |
+| Sub-agent 无法读文件 | `cat .atool-docs/modules/{name}/data.json` | 检查 Phase 2 初稿是否生成 |
+| 精炼 Gate 失败 | `cat atool-analysis/modules/{name}/prd.md \| wc -l` | PRD 文件小于 30 行，需要扩展初稿 |
+
+---
+
 ## Important Notes
 
 - Always check `.atool-docs/` before starting; offer incremental update if exists

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

@@ -80,7 +80,51 @@
 > fi
 > ```
 
-### 1.4a 扫描已有文档（用户已有的 PRD/README 等）
+### 1.4a 模块聚合（关键步骤 — 必须执行）
+
+> **背景**：原始发现的模块数量可能过多（如 Maven 多模块项目可能有 50-70 个子模块），需要按 `rules/{STACK}.md` 的聚合规则将子模块聚合为有业务含义的分析单元。
+
+**执行方式**：此步骤由 AI 执行（非 bash），因为需要理解模块的业务含义。
+
+**聚合流程**：
+
+1. 读取 `rules/{STACK}.md` 的「聚合规则」章节
+2. 对 `manifest.json` 中的每个模块，按聚合决策树分类：
+   - **业务模块**：保持独立
+   - **框架/基础设施模块**：聚合为单个 `framework` 模块
+   - **依赖管理模块**（无源码）：标记 `skip`
+   - **脚手架/模板模块**：标记 `skip`
+3. 生成聚合后的模块列表，每个模块包含：
+   - `slug`：模块标识（如 `dtt-module-mall`）
+   - `name`：显示名称（如 `商城模块`）
+   - `path`：模块根路径
+   - `type`：`business` | `framework` | `skip`
+   - `sub_modules`：聚合的子模块列表（仅 framework 类型）
+   - `importance`：`high` | `medium` | `low`
+4. **写入聚合后的模块列表**到 `analysis-state.json` 的 `modules` 字段
+
+> **执行命令（必须通过 Bash 工具）** — 写入聚合结果：
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> # 聚合后的模块列表（AI 生成后通过 jq 写入）
+> # 注意：AGGREGATED_MODULES 变量由 AI 基于聚合规则生成
+> AGGREGATED_MODULES='[
+>   {"slug":"dtt-gateway","name":"API网关","path":"dtt-gateway","type":"business","sub_modules":[],"importance":"high"},
+>   {"slug":"dtt-framework","name":"框架层","path":"dtt-framework","type":"framework","sub_modules":["dtt-common","dtt-spring-boot-starter-mybatis","dtt-spring-boot-starter-redis"],"importance":"high"},
+>   {"slug":"dtt-module-system","name":"系统管理","path":"dtt-module-system","type":"business","sub_modules":[],"importance":"high"}
+> ]'
+> # 上面的 JSON 是示例，实际内容由 AI 根据聚合规则生成
+> # 写入到 manifest.json 的 aggregated_modules 字段
+> jq --argjson modules "$AGGREGATED_MODULES" \
+>   '.aggregated_modules = $modules | .aggregated_count = ($modules | length)' \
+>   "$DOCS_DIR/pre-scan/manifest.json" > "$DOCS_DIR/pre-scan/manifest.json.tmp" \
+>   && mv "$DOCS_DIR/pre-scan/manifest.json.tmp" "$DOCS_DIR/pre-scan/manifest.json"
+> echo "Aggregated: $(jq '.aggregated_count' "$DOCS_DIR/pre-scan/manifest.json") analysis modules (from $(jq '.total_modules' "$DOCS_DIR/pre-scan/manifest.json") raw modules)"
+> ```
+
+**聚合结果必须向用户展示并确认**（纳入 §1.5 的预览中）。
+
+### 1.4b 扫描已有文档（用户已有的 PRD/README 等）
 
 > **执行命令（必须通过 Bash 工具）：**
 > ```bash
@@ -125,7 +169,20 @@
 技术栈：{STACK}
 文件数：{FILE_COUNT}（已排除 node_modules/build/.git 等）
 规模等级：{SCALE}
-识别模块：{MODULE_LIST}
+原始模块：{RAW_MODULE_COUNT} 个子模块
+聚合后分析模块：{AGGREGATED_COUNT} 个
+
+业务模块：
+  ✅ {slug} — {name} ({file_count} 文件)
+  ...
+
+框架模块：
+  📦 {slug} — {name}（聚合 {sub_count} 个子模块）
+  ...
+
+已跳过：
+  ⏭️ {slug} — {reason}
+  ...
 
 分析深度选项：
   L1  结构扫描    ~5分钟   ~10K tokens   目录树+技术栈识别
@@ -147,15 +204,16 @@
 > STACK="${STACK:-unknown}"
 > SCALE="${SCALE:-MEDIUM}"
 >
-> # 从 manifest 提取模块列表，fallback 为空数组
-> MODULES_JSON=$(jq -c '[.modules[].slug]' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '[]')
+> # 优先使用聚合后的模块列表，fallback 为原始模块
+> MODULES_JSON=$(jq -c 'if .aggregated_modules then [.aggregated_modules[] | .slug] else [.modules[].slug] end' "$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",
+>   "version": "5.2.0",
+>   "project": "$(basename "$PROJECT_ROOT")",
 >   "project_root": "$PROJECT_ROOT",
 >   "stack": "$STACK",
 >   "depth": "$DEPTH",
@@ -164,11 +222,14 @@
 >   "phases": {
 >     "phase1_setup": "completed",
 >     "phase2_understand": "pending",
+>     "phase2_5_refine": "pending",
 >     "phase3_graph": "pending",
 >     "phase4_synthesize": "pending",
 >     "phase5_export": "pending"
 >   },
 >   "module_status": $MODULE_STATUS,
+>   "refine_status": {},
+>   "deliverable_status": {},
 >   "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 > }
 > STATEEOF
@@ -180,3 +241,13 @@
 - `.atool-docs/pre-scan/manifest.json` 存在（或 warning 已记录）
 - `.atool-docs/analysis-state.json` 已写入且 `phases.phase1_setup = "completed"`
 - 用户已确认分析深度
+
+## 故障排查（Troubleshooting）
+
+| 症状 | 可能原因 | 解决方案 |
+|------|---------|---------|
+| pre-scan 超时（>2分钟） | 项目过大或网络配置问题 | 检查 PROJECT_ROOT，尝试指定具体子目录 |
+| manifest.json 为空或缺数据 | 源文件识别失败 | 检查 PRESCAN_EXCLUDE_DIRS，确保源文件扩展名被识别 |
+| state.json 初始化失败 | 目录权限问题 | 确保 ~/.atool-docs 目录可写 |
+| detected_stack = "generic" | 技术栈检测失败 | 检查是否存在 package.json/pom.xml/go.mod 等 |
+| 重复执行 Phase 1 | 上次中断或状态不清 | `rm -rf .atool-docs/analysis-state.json` 后重试 |