@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.
- package/lib/install-skills.sh +16 -0
- package/lib/knowledge-graph.sh +483 -81
- package/lib/pre-scan.sh +70 -5
- package/package.json +1 -1
- package/skills/project-analyze/SKILL.md +34 -15
- package/skills/project-analyze/phases/phase2-understand.md +7 -1
- package/skills/project-analyze/phases/phase2.5-refine.md +284 -0
- package/skills/project-analyze/phases/phase4-synthesize.md +100 -119
- package/skills/project-analyze/phases/phase5-export.md +78 -32
- package/skills/project-analyze/prompts/understand-agent.md +17 -0
- package/skills/project-analyze/rules/android.md +61 -260
- package/skills/project-analyze/rules/devops.md +61 -421
- package/skills/project-analyze/rules/generic.md +53 -221
- package/skills/project-analyze/rules/go.md +60 -275
- package/skills/project-analyze/rules/harmony.md +64 -237
- package/skills/project-analyze/rules/java.md +47 -485
- package/skills/project-analyze/rules/mobile-flutter.md +57 -292
- package/skills/project-analyze/rules/mobile-react-native.md +65 -262
- package/skills/project-analyze/rules/mobile-swift.md +58 -303
- package/skills/project-analyze/rules/python.md +50 -296
- package/skills/project-analyze/rules/rust-tauri.md +51 -217
- package/skills/project-analyze/rules/rust.md +50 -274
- package/skills/project-analyze/rules/web-nextjs.md +61 -335
- package/skills/project-analyze/rules/web-react.md +50 -272
- package/skills/project-analyze/rules/web-vue.md +58 -352
- package/skills/project-analyze/rules/web.md +55 -347
- package/skills/requirements-writer/SKILL.md +48 -1
- 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
|
-
|
|
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,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.
|
|
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
|
-
###
|
|
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
|
|
85
|
-
Phase 5: EXPORT → phases/phase5-export.md (bash
|
|
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
|
-
```
|
|
102
|
+
```jsonc
|
|
101
103
|
{
|
|
102
|
-
"version": "5.
|
|
103
|
-
"
|
|
104
|
-
"
|
|
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
|
-
"
|
|
117
|
-
|
|
117
|
+
"{slug}": {
|
|
118
|
+
"phase2": "completed|in_progress|pending",
|
|
119
|
+
"assigned_to": "sub-agent-id"
|
|
120
|
+
}
|
|
118
121
|
},
|
|
119
|
-
"
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
+
```
|