@dtt_siye/atool 1.3.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/lib/install-skills.sh +16 -0
  2. package/lib/knowledge-graph.sh +483 -81
  3. package/lib/pre-scan.sh +70 -5
  4. package/package.json +1 -1
  5. package/skills/project-analyze/SKILL.md +34 -15
  6. package/skills/project-analyze/phases/phase2-understand.md +7 -1
  7. package/skills/project-analyze/phases/phase2.5-refine.md +284 -0
  8. package/skills/project-analyze/phases/phase4-synthesize.md +100 -119
  9. package/skills/project-analyze/phases/phase5-export.md +78 -32
  10. package/skills/project-analyze/prompts/understand-agent.md +17 -0
  11. package/skills/project-analyze/rules/android.md +61 -260
  12. package/skills/project-analyze/rules/devops.md +61 -421
  13. package/skills/project-analyze/rules/generic.md +53 -221
  14. package/skills/project-analyze/rules/go.md +60 -275
  15. package/skills/project-analyze/rules/harmony.md +64 -237
  16. package/skills/project-analyze/rules/java.md +47 -485
  17. package/skills/project-analyze/rules/mobile-flutter.md +57 -292
  18. package/skills/project-analyze/rules/mobile-react-native.md +65 -262
  19. package/skills/project-analyze/rules/mobile-swift.md +58 -303
  20. package/skills/project-analyze/rules/python.md +50 -296
  21. package/skills/project-analyze/rules/rust-tauri.md +51 -217
  22. package/skills/project-analyze/rules/rust.md +50 -274
  23. package/skills/project-analyze/rules/web-nextjs.md +61 -335
  24. package/skills/project-analyze/rules/web-react.md +50 -272
  25. package/skills/project-analyze/rules/web-vue.md +58 -352
  26. package/skills/project-analyze/rules/web.md +55 -347
  27. package/skills/requirements-writer/SKILL.md +48 -1
  28. package/skills/software-architecture/SKILL.md +73 -3
package/lib/pre-scan.sh CHANGED
@@ -426,7 +426,7 @@ _extract_typescript() {
426
426
  local lang="typescript"
427
427
  [[ "$rel_path" == *.js || "$rel_path" == *.jsx ]] && lang="javascript"
428
428
 
429
- # --- Imports ---
429
+ # --- Imports (enhanced with named symbols for cross-reference) ---
430
430
  local imports_json="[]"
431
431
  imports_json=$({ grep -n -E '^(import |const .* = require)' "$file" 2>/dev/null || true; } | awk -F: '
432
432
  {
@@ -435,20 +435,47 @@ _extract_typescript() {
435
435
  if (content ~ /^import /) {
436
436
  # ES module import
437
437
  source = ""
438
+ syms = "[]"
439
+ # Extract source path
438
440
  if (match(content, /from "[^"]*"/)) {
439
441
  source = substr(content, RSTART+6, RLENGTH-7)
440
442
  } else if (match(content, /"[^"]*"/)) {
441
443
  source = substr(content, RSTART+1, RLENGTH-2)
442
444
  }
445
+ # Extract named symbols from destructured import: import { X, Y } from ...
446
+ if (match(content, /\{[^}]+\}/)) {
447
+ brace = substr(content, RSTART+1, RLENGTH-2)
448
+ gsub(/^[[:space:]]+/, "", brace)
449
+ gsub(/[[:space:]]+$/, "", brace)
450
+ n = split(brace, parts, ",")
451
+ sym_arr = "["
452
+ for (i = 1; i <= n; i++) {
453
+ gsub(/^[[:space:]]+/, "", parts[i])
454
+ gsub(/[[:space:]]+$/, "", parts[i])
455
+ gsub(/[[:space:]]+as[[:space:]]+.*/, "", parts[i])
456
+ gsub(/=.*/, "", parts[i])
457
+ if (parts[i] != "") {
458
+ if (length(sym_arr) > 1) sym_arr = sym_arr ","
459
+ sym_arr = sym_arr "\"" parts[i] "\""
460
+ }
461
+ }
462
+ syms = sym_arr "]"
463
+ } else if (content ~ /^import [a-zA-Z_]/ && content !~ /^import type/ && content !~ /^import \*/) {
464
+ # Default import: import X from '"'"'Z'"'"'
465
+ tmp = content
466
+ gsub(/^import /, "", tmp)
467
+ gsub(/ .*$/, "", tmp)
468
+ syms = "[\"" tmp "\"]"
469
+ }
443
470
  is_local = (source ~ /^\./ || source ~ /^@/) ? "true" : "false"
444
- printf "{\"from\":\"%s\",\"import\":null,\"line\":%s,\"is_local\":%s}\n", source, line, is_local
471
+ printf "{\"from\":\"%s\",\"import\":null,\"line\":%s,\"is_local\":%s,\"symbols\":%s}\n", source, line, is_local, syms
445
472
  } else if (index(content, "require(") > 0) {
446
473
  source = ""
447
474
  if (match(content, /"[^"]*"/)) {
448
475
  source = substr(content, RSTART+1, RLENGTH-2)
449
476
  }
450
477
  is_local = (source ~ /^\./ || source ~ /^@/) ? "true" : "false"
451
- printf "{\"from\":\"%s\",\"import\":null,\"line\":%s,\"is_local\":%s}\n", source, line, is_local
478
+ printf "{\"from\":\"%s\",\"import\":null,\"line\":%s,\"is_local\":%s,\"symbols\":[]}\n", source, line, is_local
452
479
  }
453
480
  }' | jq -s '.' 2>/dev/null || echo '[]')
454
481
 
@@ -687,7 +714,7 @@ _extract_rust() {
687
714
  hash=$(file_checksum "$file")
688
715
  line_count=$(wc -l < "$file" | tr -d ' ')
689
716
 
690
- # --- Imports ---
717
+ # --- Imports (enhanced with symbols from use paths) ---
691
718
  local imports_json="[]"
692
719
  imports_json=$({ grep -n -E '^use ' "$file" 2>/dev/null || true; } | awk '
693
720
  {
@@ -697,7 +724,45 @@ _extract_rust() {
697
724
  gsub(/^use /, "", content)
698
725
  gsub(/;.*$/, "", content)
699
726
  gsub(/ *$/, "", content)
700
- printf "{\"from\":\"%s\",\"import\":null,\"line\":%s,\"is_local\":false}\n", content, line
727
+
728
+ # Detect local imports: crate::, self::, super::, or crate-relative paths
729
+ is_local = "false"
730
+ if (content ~ /^crate::/ || content ~ /^super::/ || content ~ /^self::/) is_local = "true"
731
+
732
+ # Extract symbols from {A, B, C} grouped imports: use path::{A, B}
733
+ syms = "[]"
734
+ if (match(content, /\{[^}]+\}/)) {
735
+ brace = substr(content, RSTART+1, RLENGTH-2)
736
+ gsub(/^[[:space:]]+/, "", brace)
737
+ gsub(/[[:space:]]+$/, "", brace)
738
+ n = split(brace, parts, ",")
739
+ sym_arr = "["
740
+ for (i = 1; i <= n; i++) {
741
+ gsub(/^[[:space:]]+/, "", parts[i])
742
+ gsub(/[[:space:]]+$/, "", parts[i])
743
+ gsub(/[[:space:]]+as[[:space:]]+.*/, "", parts[i])
744
+ gsub(/ .*$/, "", parts[i])
745
+ if (parts[i] != "") {
746
+ if (length(sym_arr) > 1) sym_arr = sym_arr ","
747
+ sym_arr = sym_arr "\"" parts[i] "\""
748
+ }
749
+ }
750
+ syms = sym_arr "]"
751
+ } else {
752
+ # Single import: extract the last segment as symbol
753
+ n = split(content, seg, "::")
754
+ if (n > 0 && seg[n] != "" && seg[n] !~ /^\{/ && seg[n] !~ /\}$/) {
755
+ gsub(/[[:space:]]+as[[:space:]]+.*/, "", seg[n])
756
+ gsub(/ .*/, "", seg[n])
757
+ if (seg[n] != "*") {
758
+ syms = "[\"" seg[n] "\"]"
759
+ }
760
+ }
761
+ }
762
+
763
+ # Escape double quotes in content for JSON
764
+ gsub(/"/, "\\\"", content)
765
+ printf "{\"from\":\"%s\",\"import\":null,\"line\":%s,\"is_local\":%s,\"symbols\":%s}\n", content, line, is_local, syms
701
766
  }' | jq -s '.' 2>/dev/null || echo '[]')
702
767
 
703
768
  # --- Structs/Enums/Traits ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dtt_siye/atool",
3
- "version": "1.3.0",
3
+ "version": "1.3.1",
4
4
  "description": "AI Developer Toolkit - 一键配置 AI IDE 的工具集",
5
5
  "bin": {
6
6
  "atool": "bin/atool.js"
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: project-analyze
3
3
  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"
4
- version: 5.1.0
4
+ version: 5.2.0
5
5
  ---
6
6
 
7
7
  # Project Analyzer v5.0
@@ -75,14 +75,15 @@ Pipeline 中 AI 与 bash 工具的分工遵循核心原则:**确定性操作
75
75
 
76
76
  ## Pipeline Controller
77
77
 
78
- ### 5-Phase 架构
78
+ ### 6-Phase 架构
79
79
 
80
80
  ```
81
81
  Phase 1: SETUP → phases/phase1-setup.md (bash only, no AI, ~30秒)
82
82
  Phase 2: UNDERSTAND → phases/phase2-understand.md (AI sub-agents ≤5并行)
83
+ Phase 2.5: REFINE → phases/phase2.5-refine.md (AI sub-agents ≤5并行,串联 requirements-writer + software-architecture Refine Mode)
83
84
  Phase 3: GRAPH → phases/phase3-graph.md (bash only, no AI, ~30秒)
84
- Phase 4: SYNTHESIZE → phases/phase4-synthesize.md (main agent + sub-agents)
85
- Phase 5: EXPORT → phases/phase5-export.md (bash only, no AI, ~10秒)
85
+ Phase 4: SYNTHESIZE → phases/phase4-synthesize.md (main agent, 聚合模式)
86
+ Phase 5: EXPORT → phases/phase5-export.md (bash + AI, export 单文件)
86
87
  ```
87
88
 
88
89
  ### 执行规则(硬性)
@@ -93,30 +94,48 @@ Phase 5: EXPORT → phases/phase5-export.md (bash only, no AI, ~10秒)
93
94
  4. **Phase 2 并发上限 5 个 sub-agent**,超出部分按 importance 降序分批排队
94
95
  5. **Phase 3 bash 调用失败时**:在 state.json 记录 `phase3_graph: "failed"`,继续 Phase 4(跳过图谱相关文档,Phase 4 检查此标记)
95
96
  6. **断点续传**:先读 state.json,跳过 `status: "completed"` 的 phase
97
+ 7. Phase 2.5 在 Phase 2 完成后自动执行;`--skip-refine` 可跳过;`--refine-threshold N` 自定义门禁阈值(默认 70)
96
98
 
97
99
  ### 状态管理(简化版)
98
100
 
99
101
  `analysis-state.json` 最小结构:
100
- ```json
102
+ ```jsonc
101
103
  {
102
- "version": "5.1",
103
- "project_root": "/path/to/project",
104
- "stack": "java-spring",
104
+ "version": "5.2.0",
105
+ "project": "...",
106
+ "detected_stack": "java-spring",
105
107
  "depth": "L2",
106
- "scale": "MEDIUM",
107
- "modules": ["user-service", "order-service"],
108
108
  "phases": {
109
109
  "phase1_setup": "completed",
110
110
  "phase2_understand": "in_progress",
111
+ "phase2_5_refine": "pending",
111
112
  "phase3_graph": "pending",
112
113
  "phase4_synthesize": "pending",
113
114
  "phase5_export": "pending"
114
115
  },
115
116
  "module_status": {
116
- "user-service": { "phase2": "completed" },
117
- "order-service": { "phase2": "in_progress" }
117
+ "{slug}": {
118
+ "phase2": "completed|in_progress|pending",
119
+ "assigned_to": "sub-agent-id"
120
+ }
118
121
  },
119
- "updated_at": "2026-04-04T10:00:00Z"
122
+ "refine_status": {
123
+ "{slug}": {
124
+ "prd_refine": "completed|in_progress|pending",
125
+ "prd_coverage": 82,
126
+ "prd_gate": "passed|failed",
127
+ "arch_refine": "completed|in_progress|pending|skipped",
128
+ "arch_gate": "passed|failed",
129
+ "conventions_loaded": "java-conventions",
130
+ "degraded": false,
131
+ "degraded_reason": null
132
+ }
133
+ },
134
+ "deliverable_status": {
135
+ "project_deliverable_md": "pending",
136
+ "export_single_file": "pending"
137
+ },
138
+ "errors": []
120
139
  }
121
140
  ```
122
141
 
@@ -275,10 +294,10 @@ When resuming Phase 5, incrementally update already-generated documents using `<
275
294
  | Collaborating Skill | Trigger Condition | Interaction |
276
295
  |---------------------|-------------------|-------------|
277
296
  | code-review | Phase 4 quality report generation | References rules/ files |
278
- | software-architecture | Phase 3 structural layer violation rate >30% | Suggest running |
297
+ | software-architecture | Phase 2.5 Refine Mode 调用;Phase 4 聚合时 layer_violations/total_edges > 30% 建议深度审查 | 精炼模式 + 建议运行 |
279
298
  | {stack}-conventions | Phase 2 module analysis | Load stack-level conventions |
280
299
  | doc-standards-enforcer | Phase 4 document generation | Validate frontmatter format |
281
300
  | smart-dispatch | LARGE/XLARGE projects | Batch parallel by module |
282
301
  | project-query | Need to query analysis results | User manually invokes /project-query |
283
- | requirements-writer | Phase 4 PRD 覆盖率 < 70% | 建议运行,自动进入后向增强模式读取 atool-analysis/ |
302
+ | requirements-writer | Phase 2.5 Refine Mode 调用;Phase 4 PRD 降级模块存在时建议补全 | 精炼模式 + 建议运行 |
284
303
  | clarify-before-build | Before Phase 1 user confirmation | Requirement clarification (auto-injected) |
@@ -94,7 +94,13 @@ atool-analysis/modules/{module-name}/dev-guide.md # 层2c: 开发指引
94
94
  ## 完成条件
95
95
 
96
96
  - 所有模块的 `module_status.{slug}.phase2 == "completed"`
97
- - `atool-analysis/modules/*/README.md` 全部存在
97
+ - 每个模块至少 5/6 核心文件存在(data-model.md 可选):
98
+ - `atool-analysis/modules/*/README.md` ✓ 必须
99
+ - `atool-analysis/modules/*/api.md` ✓ 必须
100
+ - `atool-analysis/modules/*/dev-guide.md` ✓ 必须
101
+ - `atool-analysis/modules/*/prd.md` ✓ 必须
102
+ - `atool-analysis/modules/*/test-cases.md` ✓ 必须
103
+ - `atool-analysis/modules/*/data-model.md` ○ 可选(无实体时可不存在)
98
104
  - `.atool-docs/modules/*/data.json` 全部存在
99
105
  - 更新 state:`phases.phase2_understand = "completed"`
100
106
 
@@ -0,0 +1,284 @@
1
+ # Phase 2.5: REFINE(精炼链 — AI sub-agents ≤5 并行)
2
+
3
+ **目标**:对 Phase 2 生成的模块初稿,串联 requirements-writer 和 software-architecture 的 Refine Mode 进行精炼,将初稿升级为专业级交付文档。
4
+
5
+ **并发上限**:最多 5 个模块同时精炼。每个模块内部串行(PRD 精炼 → 架构精炼)。
6
+
7
+ ---
8
+
9
+ ## 前置检查
10
+
11
+ 1. `analysis-state.json` 中 `phases.phase2_understand == "completed"`
12
+ 2. 读取 `detected_stack` 用于 conventions 加载
13
+ 3. 如果 `phases.phase2_5_refine == "completed"` 且非 `--force`,跳过本 Phase
14
+ 4. 如果 `--skip-refine`,跳过本 Phase
15
+
16
+ ## 输入数据
17
+
18
+ | 来源 | 文件 |
19
+ |------|------|
20
+ | Phase 2 模块文档 | `atool-analysis/modules/*/README.md`, `api.md`, `data-model.md`, `dev-guide.md`, `prd.md`, `test-cases.md` |
21
+ | Phase 2 结构化数据 | `.atool-docs/modules/*/data.json` |
22
+ | Conventions | `~/.claude/skills/{stack}-conventions/SKILL.md`(仅 Architecture + API Design 节) |
23
+
24
+ ## 执行流程
25
+
26
+ ### 2.5.1 加载 Conventions 上下文
27
+
28
+ ```bash
29
+ # 从 state.json 读取技术栈
30
+ STACK=$(jq -r '.detected_stack // "generic"' .atool-docs/analysis-state.json)
31
+ ```
32
+
33
+ 从对应 conventions SKILL.md 中提取以下章节内容(不加载全文,控制在 ~200 行):
34
+ - `## Architecture` 或 `## 架构` 章节
35
+ - `## API Design` 或 `## API 设计` 章节
36
+
37
+ 存为 `{conventions_context}` 变量。如果对应 conventions skill 不存在,`{conventions_context}` 为空字符串。
38
+
39
+ ### 2.5.2 构建模块精炼队列
40
+
41
+ ```bash
42
+ # 读取模块列表,按重要性降序排列
43
+ MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-scan/manifest.json)
44
+ ```
45
+
46
+ **断点续传检查**:对每个模块读取 `refine_status.{module}`:
47
+
48
+ | 状态 | 行为 |
49
+ |------|------|
50
+ | `arch_refine == "completed"` | 跳过该模块 |
51
+ | `prd_refine == "completed"` 且 `arch_refine != "completed"` | 加入队列,从架构精炼开始 |
52
+ | `prd_refine != "completed"` | 加入队列,从 PRD 精炼开始 |
53
+ | `degraded == true` | 跳过(除非 `--force`) |
54
+
55
+ ### 2.5.3 Gate 1: 初稿完整性检查(Hard Gate)
56
+
57
+ **对每个待精炼模块执行**:
58
+
59
+ 检查项:
60
+ - `atool-analysis/modules/{name}/prd.md` 存在且 ≥ 30 行
61
+ - `atool-analysis/modules/{name}/README.md` 存在
62
+ - `.atool-docs/modules/{name}/data.json` 存在且是合法 JSON
63
+
64
+ **失败处理**:该模块不进入精炼队列,记录 `refine_status.{name}.gate1 = "failed"`,打印警告,其他模块继续。
65
+
66
+ ### 2.5.4 批量派发精炼 Sub-Agents
67
+
68
+ **每批最多 5 个模块并行**,每个模块的精炼链为串行两步。等待当前批次全部完成后再派发下一批。
69
+
70
+ ---
71
+
72
+ #### Step A: requirements-writer Refine(PRD 精炼)
73
+
74
+ 为每个模块派发 sub-agent,prompt 模板:
75
+
76
+ ```
77
+ 你是 requirements-writer 的精炼模式(Refine Mode)。
78
+
79
+ ## 任务
80
+ 将以下模块的 PRD 初稿精炼为标准 8 节结构。
81
+
82
+ ## 模块信息
83
+ - 模块名:{module_name}
84
+ - 模块路径:{module_path}
85
+ - 技术栈:{detected_stack}
86
+
87
+ ## 输入文件(必须全部读取)
88
+ - atool-analysis/modules/{module_name}/prd.md — Phase 2 初稿
89
+ - atool-analysis/modules/{module_name}/api.md — 接口定义
90
+ - atool-analysis/modules/{module_name}/data-model.md — 数据模型(可能不存在,跳过)
91
+ - .atool-docs/modules/{module_name}/data.json — 结构化数据
92
+
93
+ ## 编码规范约束
94
+ {conventions_context}
95
+
96
+ ## 精炼规则
97
+ 参考 requirements-writer SKILL.md 的 "Refine Mode(精炼模式)" 章节,严格按照其中的精炼逻辑执行:
98
+ 1. 保留初稿 §1-§3 和原 §4 非目标(移至 §6)
99
+ 2. 补全 §4 数据需求、§5 跨模块依赖、§7 风险与假设、§8 需求追溯矩阵
100
+ 3. 增强 §2 加 FR-{MOD}-NNN 编号 + Given-When-Then AC + UI 交互表;§3 加 NFR-{MOD}-NNN 编号,标注 [待系统级确认]
101
+ 4. 输出必须包含完整 8 节结构
102
+
103
+ ## 输出
104
+ 原地覆盖 atool-analysis/modules/{module_name}/prd.md
105
+
106
+ ## 禁止行为
107
+ - 不做交互式问答
108
+ - 不修改 README.md / api.md / data-model.md / dev-guide.md / test-cases.md
109
+ - 不创建新文件
110
+ ```
111
+
112
+ 完成后立即写入 checkpoint:
113
+
114
+ ```bash
115
+ jq --arg mod "{module_name}" \
116
+ '.refine_status[$mod].prd_refine = "completed"' \
117
+ .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
118
+ ```
119
+
120
+ ---
121
+
122
+ #### Gate 2: PRD 覆盖率门禁(Hard Gate)
123
+
124
+ **对每个模块的精炼后 prd.md 执行**:
125
+
126
+ 检查项(每项 20 分,满分 100):
127
+
128
+ | 检查项 | 验证方式 | 分值 |
129
+ |--------|---------|------|
130
+ | 8 节结构完整 | `grep -c "^## [0-9]"` ≥ 8 | 20 |
131
+ | FR 编号存在 | `grep -c "FR-"` ≥ 1 | 20 |
132
+ | Given-When-Then AC | `grep -c "Given\|When\|Then"` ≥ 3 | 20 |
133
+ | NFR 编号存在 | `grep -c "NFR-"` ≥ 1 | 20 |
134
+ | 数据需求填充 | §4 非空(> 3 行) | 20 |
135
+
136
+ **通过**(≥ 70 分)→ 记录分数到 `refine_status.{name}.prd_coverage`,进入 Step B
137
+
138
+ **失败**(< 70 分)→ 提供恢复选项:
139
+
140
+ ```
141
+ ❌ Gate 2 失败:模块 {module_name} PRD 覆盖率 {score}%(需 ≥ 70%)
142
+ 缺失项:{列出具体未通过的检查项}
143
+
144
+ 恢复选项:
145
+ [A] 重跑该模块的 PRD 精炼(自动重试 1 次)
146
+ [B] 手动编辑 prd.md 后输入 "继续"
147
+ [C] 降级:跳过精炼,使用 Phase 2 初稿(标记 [未精炼])
148
+ ```
149
+
150
+ 选择 A 时:重新派发 Step A sub-agent(仅 1 次重试,再失败则自动降级)
151
+ 选择 C 时:`refine_status.{name}.degraded = true, degraded_reason = "PRD coverage {score}% below threshold"`
152
+
153
+ ```bash
154
+ # Gate 2 通过时写入
155
+ jq --arg mod "{module_name}" --argjson score {score} \
156
+ '.refine_status[$mod].prd_coverage = $score | .refine_status[$mod].prd_gate = "passed"' \
157
+ .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
158
+ ```
159
+
160
+ ---
161
+
162
+ #### Step B: software-architecture Refine(架构精炼)
163
+
164
+ 仅对通过 Gate 2 的模块执行。为每个模块派发 sub-agent,prompt 模板:
165
+
166
+ ```
167
+ 你是 software-architecture 的精炼模式(Refine Mode)。
168
+
169
+ ## 任务
170
+ 在以下模块的 dev-guide.md 基础上追加架构章节。
171
+
172
+ ## 模块信息
173
+ - 模块名:{module_name}
174
+ - 模块路径:{module_path}
175
+ - 技术栈:{detected_stack}
176
+
177
+ ## 输入文件(必须全部读取)
178
+ - atool-analysis/modules/{module_name}/dev-guide.md — 当前内容(保留全部,在末尾追加)
179
+ - atool-analysis/modules/{module_name}/prd.md — 精炼后的标准 PRD(8 节)
180
+ - atool-analysis/modules/{module_name}/api.md — 接口定义
181
+ - atool-analysis/modules/{module_name}/data-model.md — 数据模型(可能不存在,跳过)
182
+ - atool-analysis/modules/{module_name}/README.md — 模块概述
183
+ - .atool-docs/modules/{module_name}/data.json — 结构化数据(含 refine_hints)
184
+
185
+ ## 编码规范约束
186
+ {conventions_context}
187
+
188
+ ## 精炼规则
189
+ 参考 software-architecture SKILL.md 的 "Refine Mode(精炼模式)" 章节,严格按照其中的精炼逻辑执行:
190
+ 1. 在现有 dev-guide.md 内容末尾追加(不删除原有内容)
191
+ 2. 追加 B-subset 组件设计(分层表 + 边界 + 依赖方向)
192
+ 3. 追加 C-subset 数据与交互设计(数据所有权 + 同步/异步边界 + API 契约)
193
+ 4. 追加至少 1 个 ADR(使用 7 节 ADR 模板:Status/Context/Decision/Options/Consequences/NFR Impact/Related)
194
+ 5. NFR 对齐:标注 [待系统级确认]
195
+
196
+ ## 输出
197
+ 原地覆盖 atool-analysis/modules/{module_name}/dev-guide.md
198
+
199
+ ## 禁止行为
200
+ - 不删除 dev-guide.md 的原有内容
201
+ - 不修改 prd.md / api.md / data-model.md / README.md / test-cases.md
202
+ - 不创建新文件
203
+ - 不生成项目级文档(A/D/E/F)
204
+ ```
205
+
206
+ 完成后写入 checkpoint:
207
+
208
+ ```bash
209
+ jq --arg mod "{module_name}" \
210
+ '.refine_status[$mod].arch_refine = "completed"' \
211
+ .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
212
+ ```
213
+
214
+ ---
215
+
216
+ #### Gate 3: 架构精炼门禁(Hard Gate)
217
+
218
+ **对每个模块的精炼后 dev-guide.md 执行**:
219
+
220
+ 检查项:
221
+ - 包含 "组件设计" 或 "Component Design" 章节标题(`grep -c "组件设计\|Component Design"`)
222
+ - 包含 "ADR" 或 "架构决策" 标题(`grep -c "ADR\|架构决策"`)
223
+ - ADR 中包含 "Status" + "Decision" + "Consequences"(或中文等价 "状态" + "决策" + "影响")
224
+
225
+ **通过** → 记录 `arch_gate = "passed"`
226
+ **失败** → 同 Gate 2 的三选项恢复机制(A 重试 / B 手动 / C 降级)
227
+
228
+ ```bash
229
+ # Gate 3 通过时写入
230
+ jq --arg mod "{module_name}" \
231
+ '.refine_status[$mod].arch_gate = "passed"' \
232
+ .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
233
+ ```
234
+
235
+ ### 2.5.5 完成 Checkpoint
236
+
237
+ 每个模块完成全部精炼(或降级)后,写入完整状态:
238
+
239
+ ```bash
240
+ jq --arg mod "{module_name}" \
241
+ --argjson score {prd_score} \
242
+ --arg conv "{conventions_skill}" \
243
+ '.refine_status[$mod] = {
244
+ "prd_refine": "completed",
245
+ "prd_coverage": $score,
246
+ "prd_gate": "passed",
247
+ "arch_refine": "completed",
248
+ "arch_gate": "passed",
249
+ "conventions_loaded": $conv,
250
+ "degraded": false,
251
+ "degraded_reason": null
252
+ }' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
253
+ ```
254
+
255
+ ### 2.5.6 跨 IDE 降级
256
+
257
+ | IDE | 检测方式 | 行为 |
258
+ |-----|---------|------|
259
+ | Claude Code | Agent tool 可用 | 完整并行(≤5 模块同时) |
260
+ | Cursor | Agent tool 不可用 | 顺序执行(每次 1 个模块) |
261
+ | Kiro | 无 Agent tool + 无 sub-agent | 跳过 Phase 2.5(与 Phase 2 一样) |
262
+
263
+ 检测逻辑沿用 SKILL.md 的 Cross-IDE Adaptation 章节。
264
+
265
+ ---
266
+
267
+ ## 完成条件
268
+
269
+ - 所有非降级模块的 `refine_status.{name}.arch_gate == "passed"`
270
+ - 降级模块已记录 `degraded = true` 和 `degraded_reason`
271
+ - 更新 state:
272
+
273
+ ```bash
274
+ jq '.phases.phase2_5_refine = "completed"' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
275
+ ```
276
+
277
+ - 打印精炼摘要:
278
+
279
+ ```
280
+ ✅ Phase 2.5 REFINE 完成
281
+ 精炼模块:{M}/{N}({M} 个精炼完成,{D} 个降级)
282
+ 平均 PRD 覆盖率:{avg_score}%
283
+ 降级模块:{list}(如有,标注降级原因)
284
+ ```