@dtt_siye/atool 1.3.0 → 1.4.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

@@ -1,7 +1,7 @@
 ---
 name: project-analyze
 description: "Deep project analysis v5.0 — 7-phase pipeline with five-dimensional analysis framework, 14 node types, 24 edge types, 5-level granularity zooming, interactive visualization (Cytoscape.js), and query system. 5 depth levels (L1-L5): Discovery → Pre-Scan → Inventory → Deep Analysis → Knowledge Graph → Multi-Dimensional Analysis → Code Quality → Document Synthesis → Validation. Checkpoint/resume, incremental docs, large-module decomposition. Zero-KT standard, Chinese output. 触发：分析项目/生成文档/analyze project/generate docs/project analysis"
-version: 5.1.0
+version: 5.2.0
 ---
 
 # Project Analyzer v5.0
@@ -75,14 +75,15 @@ Pipeline 中 AI 与 bash 工具的分工遵循核心原则：**确定性操作
 
 ## Pipeline Controller
 
-### 5-Phase 架构
+### 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 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秒)
-Phase 4: SYNTHESIZE → phases/phase4-synthesize.md   (main agent + sub-agents)
-Phase 5: EXPORT     → phases/phase5-export.md       (bash only, no AI, ~10秒)
+Phase 4: SYNTHESIZE → phases/phase4-synthesize.md   (main agent, 聚合模式)
+Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文件)
 ```
 
 ### 执行规则（硬性）
@@ -93,30 +94,52 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash only, no AI, ~10秒)
 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 参数识别**（无需 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
 
 ### 状态管理（简化版）
 
 `analysis-state.json` 最小结构：
-```json
+```jsonc
 {
-  "version": "5.1",
-  "project_root": "/path/to/project",
+  "version": "5.2.0",
+  "project": "...",
+  "project_root": "...",
   "stack": "java-spring",
   "depth": "L2",
-  "scale": "MEDIUM",
-  "modules": ["user-service", "order-service"],
   "phases": {
     "phase1_setup": "completed",
     "phase2_understand": "in_progress",
+    "phase2_5_refine": "pending",
     "phase3_graph": "pending",
     "phase4_synthesize": "pending",
     "phase5_export": "pending"
   },
   "module_status": {
-    "user-service": { "phase2": "completed" },
-    "order-service": { "phase2": "in_progress" }
+    "{slug}": {
+      "phase2": "completed|in_progress|pending",
+      "assigned_to": "sub-agent-id"
+    }
   },
-  "updated_at": "2026-04-04T10:00:00Z"
+  "refine_status": {
+    "{slug}": {
+      "prd_refine": "completed|in_progress|pending",
+      "prd_coverage": 82,
+      "prd_gate": "passed|failed",
+      "arch_refine": "completed|in_progress|pending|skipped",
+      "arch_gate": "passed|failed",
+      "conventions_loaded": "java-conventions",
+      "degraded": false,
+      "degraded_reason": null
+    }
+  },
+  "deliverable_status": {
+    "project_deliverable_md": "pending",
+    "export_single_file": "pending"
+  },
+  "errors": []
 }
 ```
 
@@ -175,16 +198,56 @@ state.checkpoint = { last_completed_phase, last_completed_module, next_pending_m
 write analysis-state.json
 ```
 
-### 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
+### Resume Flow（断点恢复决策树）
+
+**入口**：执行 Phase 1 setup 时自动检测恢复状态
+
+```
+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（知识图谱生成）
+   │  │  ├─ "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" → 分析完成（可选重新导出）
+```
+
+**断点恢复的具体判断**（在每个 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.
@@ -255,6 +318,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
@@ -275,10 +383,10 @@ When resuming Phase 5, incrementally update already-generated documents using `<
 | Collaborating Skill | Trigger Condition | Interaction |
 |---------------------|-------------------|-------------|
 | code-review | Phase 4 quality report generation | References rules/ files |
-| software-architecture | Phase 3 structural layer violation rate >30% | Suggest running |
+| software-architecture | Phase 2.5 Refine Mode 调用；Phase 4 聚合时 layer_violations/total_edges > 30% 建议深度审查 | 精炼模式 + 建议运行 |
 | {stack}-conventions | Phase 2 module analysis | Load stack-level conventions |
 | doc-standards-enforcer | Phase 4 document generation | Validate frontmatter format |
 | smart-dispatch | LARGE/XLARGE projects | Batch parallel by module |
 | project-query | Need to query analysis results | User manually invokes /project-query |
-| requirements-writer | Phase 4 PRD 覆盖率 < 70% | 建议运行，自动进入后向增强模式读取 atool-analysis/ |
+| requirements-writer | Phase 2.5 Refine Mode 调用；Phase 4 PRD 降级模块存在时建议补全 | 精炼模式 + 建议运行 |
 | clarify-before-build | Before Phase 1 user confirmation | Requirement clarification (auto-injected) |

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

@@ -155,7 +155,8 @@
 >
 > 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 +165,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 +184,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` 后重试 |

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

@@ -2,7 +2,16 @@
 
 **目标**：每个模块派发 1 个 sub-agent，产出三层文档（业务/技术/数据），直接写入 `atool-analysis/modules/`。
 
-**并发上限：5 个 sub-agent**
+---
+
+## IDE 适配（执行前检查）
+
+- **Claude Code**：使用 Agent 工具批量派发，每批最多 5 个并行，等待全部完成后派发下一批
+- **Cursor/其他**：**顺序执行**，按 importance 降序逐模块处理，每个模块完成后更新 state.json
+  - *原因*：Cursor 不支持并行 sub-agent，自动降级为逐个执行
+  - *判断方式*：若 Agent 工具不可用或不响应，自动切换到顺序模式
+
+---
 
 ## 前置检查
 
@@ -94,7 +103,13 @@ atool-analysis/modules/{module-name}/dev-guide.md    # 层2c: 开发指引
 ## 完成条件
 
 - 所有模块的 `module_status.{slug}.phase2 == "completed"`
-- `atool-analysis/modules/*/README.md` 全部存在
+- 每个模块至少 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"`