@dtt_siye/atool 1.2.0 → 1.3.0

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.0.0
+version: 5.1.0
 ---
 
 # Project Analyzer v5.0
@@ -40,83 +40,94 @@ version: 5.0.0
 | L4 | 函数级分析：L3 + 逐函数调用链追踪 + 性能热点识别 + 安全审计点 + 数据流路径 | 质量审查、性能优化 |
 | L5 | 跨模块行为推断：L4 + 时序图 + 状态机 + 异常路径追踪 + 数据血缘 | 架构重构、完整技术文档 |
 
-**选择规则**：用户未指定 → 默认 L2；<50 文件 → 建议提升到 L3；L3/L4/L5 对所有项目规模可用（通过多批次执行）。**L1 特殊**：Phase 0.5 完全替代 Phase 1（0 AI agents，纯 bash 提取）。
+**选择规则**：用户未指定 → 默认 L2；<50 文件 → 建议提升到 L3。**L1-L5 所有深度对任何项目规模均可用**（L3+ 通过多批次执行）。Phase 1 确认时**必须向用户展示全部 L1-L5 五个选项**。**L1 特殊**：Phase 1 pre-scan 完全替代 Phase 2 AI 分析（0 AI agents，纯 bash 提取）。
 
----
-
-## Pipeline Controller
-
-### Execution Flow
+### AI 调用设计原则
 
-1. **Detect IDE** → set execution_mode (parallel/sequential/compressed)
-2. **Read `analysis-state.json`** (if exists) → determine resume point (see `phases/phase0-discovery.md` 0.5a)
-3. **Execute Phase 0**: Read `phases/phase0-discovery.md` → detect stack, evaluate scale, compute importance, get user confirmation → write `analysis-state.json`
-4. **Execute Phase 0.5 (Pre-Scan)**: Run `source lib/pre-scan.sh && pre_scan_project "$PROJECT_ROOT" "$PRESCAN_DIR"` → pure bash structural extraction → output `.atool-docs/pre-scan/{module-slug}.json` + `manifest.json` → write checkpoint `phase0_5_prescan = "completed"`
-5. Based on Phase 0 + Phase 0.5 pre-scan data → set depth, scale, module list
-6. **For each phase in pipeline order**:
-   - Check preconditions in `analysis-state.json`
-   - If not completed:
-     - **Read `phases/phase{N}-{name}.md`** for detailed instructions
-     - Execute phase → write checkpoint to `analysis-state.json`
-6. **Phase 6**: Read `phases/phase6-validation.md` → validate all outputs → write summary
+Pipeline 中 AI 与 bash 工具的分工遵循核心原则：**确定性操作用 bash，语义理解用 AI**。
 
-### Pipeline Order
-
-```
-Phase 0  → phases/phase0-discovery.md       (always)
-Phase 0.5→ phases/phase0.5-prescan.md       (always, pure bash, no AI)
-Phase 1  → phases/phase1-inventory.md       (always; L1 depth: skip, use Phase 0.5 data)
-Phase 2  → phases/phase2-deep-analysis.md   (skip if Kiro)
-Phase 2a → phases/phase2a-l4-analysis.md    (only if depth >= L4, skip if Kiro)
-Phase 2b → phases/phase2b-l5-analysis.md    (only if depth >= L5, skip if Kiro)
-Phase 3  → phases/phase3-knowledge-graph.md (always, main agent only)
-Phase 3a → phases/phase3a-multi-dimensional.md (always, Kiro: structure only)
-Phase 4  → phases/phase4-code-quality.md    (skip if Kiro)
-Phase 5  → phases/phase5-synthesis.md       (always)
-Phase 6  → phases/phase6-validation.md      (always)
-```
+| Phase | AI 调用 | 方式 | 原因 |
+|-------|---------|------|------|
+| Phase 1 SETUP | 否 | bash 脚本 | 栈检测、文件计数、重要性排序、pre-scan 语法提取 = 确定性操作 |
+| Phase 2 UNDERSTAND | 是 | Sub-agent × N | 核心分析 — 业务逻辑、设计意图、Zero-KT 三层文档 |
+| Phase 3 GRAPH | **否** | bash `knowledge-graph.sh` + `multi-dimensional-analysis.sh` | 图组装 + 五维分析 = 确定性算法 |
+| Phase 4 SYNTHESIZE | 是 | 主 agent + Sub-agent | 项目级文档综合 + Mermaid 图表 + 质量报告 |
+| Phase 5 EXPORT | 否 | bash 脚本 | 文件整理 + 项目注册 = 确定性操作 |
 
-### IMPORTANT RULE
+**Pre-scan 效率基石**：Phase 1 的 pre-scan 一次 bash 提取（~5秒/150文件）→ Phase 2 所有 AI sub-agent 复用数据。跳过 pre-scan → 每个 AI sub-agent 都要重新全量读取源文件（5-10x token 浪费）。
 
-**Before executing ANY phase, you MUST read the corresponding phase file from `phases/phase{N}-{name}.md`. Do not execute from memory. Each phase file contains critical details not duplicated here.**
+### 深度等级 AI 使用差异
 
-### Phase 0.5: Pre-Scan (纯 Bash，无 AI)
+| 维度 | L1 | L2 | L3 | L4 | L5 |
+|------|-----|-----|-----|-----|-----|
+| 执行 Phase | 1→3→5 | 1→2→3→4→5 | 同 L2 | 同 L2（Phase 2 追加 L4 指令） | 同 L2（Phase 2 追加 L5 指令） |
+| AI Sub-agent | **0 个** | Phase 2 + Phase 4 | 同 L2 | 同 L2（更深指令）| 同 L2（最深指令）|
+| 源文件 AI 读取 | 无 | 分层策略* | 同 L2，提取更多细节 | +函数体定向行范围 | +跨模块推断（不重读源文件） |
+| Sub-agent Prompt | N/A | 标准模板 | +L3 追加指令（签名/模式/ADR）| +L4 追加指令（调用链/性能/安全）| +L5 追加指令（时序图/状态机/数据血缘） |
+| 独特产出 | overview + modules(lite) | +quality + diagrams | +实现细节+设计决策 | +调用链分析+性能报告 | +时序图+状态机+数据血缘 |
+| Token 估算 | ~10K | ~50K | ~100K | ~200K | ~350K |
 
-**目标**：使用 grep/awk/jq 秒级提取所有语法元数据，消除 AI 重复读取。
+\* 分层策略：小文件(<100行)用 pre-scan 数据不重读；中文件(100-500行)全文；大文件(>500行)仅读关键行范围
 
-**执行**：
-1. 读取 `analysis-state.json` 获取模块列表和技术栈
-2. 执行 `source lib/pre-scan.sh && pre_scan_project "$PROJECT_ROOT" "$PRESCAN_DIR"`
-3. 输出 `.atool-docs/pre-scan/{module-slug}.json` + `manifest.json`
-4. 写入检查点 `phase0_5_prescan = "completed"`
+**递增原则**：每级深度在上一级基础上通过 sub-agent prompt 追加指令增加分析维度，不重新读取已分析过的文件。L1 完全零 AI（Phase 1 bash 替代 Phase 2），是最快但最浅的扫描。
 
-**支持语言**：Python, Java/Kotlin, TypeScript/JavaScript/Vue/Svelte, Go, Rust, 通用 fallback
-
-**性能目标**：152 文件/10 模块 < 10 秒（vs AI Phase 1 的 2-4 分钟）
+---
 
-**增量扫描**：比对文件 MD5 hash，仅重新扫描变更文件。
+## Pipeline Controller
 
-**降级**：pre-scan 失败时，Phase 1 自动回退到全量 AI 提取（v5.0 行为）。
+### 5-Phase 架构
 
-详细指令：`phases/phase0.5-prescan.md`
+```
+Phase 1: SETUP      → phases/phase1-setup.md        (bash only, no AI, ~30秒)
+Phase 2: UNDERSTAND → phases/phase2-understand.md   (AI sub-agents ≤5并行)
+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秒)
+```
 
-### Sub-Agent Prompts
+### 执行规则（硬性）
+
+1. **每个 Phase 开始前必须读取对应的 phase 文件**，不可从记忆执行
+2. **bash Phase（1/3/5）必须通过 Bash 工具调用**，禁止 AI 模拟执行或用 Write 工具写脚本代替
+3. **每个 Phase 完成后立即写 `.atool-docs/analysis-state.json`**
+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
+
+### 状态管理（简化版）
+
+`analysis-state.json` 最小结构：
+```json
+{
+  "version": "5.1",
+  "project_root": "/path/to/project",
+  "stack": "java-spring",
+  "depth": "L2",
+  "scale": "MEDIUM",
+  "modules": ["user-service", "order-service"],
+  "phases": {
+    "phase1_setup": "completed",
+    "phase2_understand": "in_progress",
+    "phase3_graph": "pending",
+    "phase4_synthesize": "pending",
+    "phase5_export": "pending"
+  },
+  "module_status": {
+    "user-service": { "phase2": "completed" },
+    "order-service": { "phase2": "in_progress" }
+  },
+  "updated_at": "2026-04-04T10:00:00Z"
+}
+```
 
-When dispatching sub-agents for phases 1, 2, 2a, 4:
-- Read the prompt template from `prompts/{name}-agent.md`
-- Fill in module-specific variables (module name, inventory data, rules content, etc.)
-- Dispatch with the filled prompt
+status 枚举值：`"pending"` | `"in_progress"` | `"completed"` | `"failed"` | `"skipped"`
 
-| Phase | Prompt Template | Variables to Fill |
-|-------|----------------|-------------------|
-| Phase 1 | `prompts/inventory-agent.md` | file_list, module-slug |
-| Phase 2 | `prompts/deep-analysis-agent.md` | module_name, inventory_json_content, rules_content, stack, project_name, module_list, depth_specific_instructions |
-| Phase 2a | `prompts/l4-analysis-agent.md` | module_name, analysis_json_content, inventory_json_content, file_list |
-| Phase 4 | `prompts/code-review-agent.md` | module_name, inventory_json, relevant_graph_subtree, multi_dimensional_context, file_list |
+### HARD GATE — bash Phase 执行验证
 
-### Batch Dispatch Rule (Hard Limit)
+Phase 1、3、5 执行前在对话中明确声明：
+> "正在通过 Bash 工具执行 Phase N..."
 
-**Maximum 5 concurrent sub-agents at all times.** When modules > 5, dispatch in batches of 5 by importance descending order. Wait for all agents in current batch to complete before dispatching next batch.
+执行后检查输出文件是否存在以确认成功。不得跳过此验证。
 
 ---
 
@@ -139,23 +150,17 @@ else:
 
 | Phase | Claude | Cursor | Kiro | Notes |
 |-------|--------|--------|------|-------|
-| Phase 0 | full | full | full | All IDEs |
-| Phase 0.5 | full (bash) | full (bash) | full (bash) | Pure shell, no AI |
-| Phase 1 | parallel | sequential | compressed (file counts only) | |
-| Phase 2 | parallel | sequential | **skip** | Kiro uses inventory directly |
-| Phase 2a | parallel | sequential | **skip** | L4 function-level |
-| Phase 2b | parallel+aggregate | sequential | **skip** | L5 cross-module |
-| Phase 3 | main agent | main agent | main agent | No sub-agents |
-| Phase 3a | 5 dimensions | 5 dimensions | structure only | v5.0 |
-| Phase 4 | parallel | sequential | **skip** | |
-| Phase 5 | full | full | L1 quality from inventory | |
-| Phase 6 | full | full | full | All IDEs |
+| Phase 1 SETUP | full (bash) | full (bash) | full (bash) | Pure shell, no AI |
+| Phase 2 UNDERSTAND | parallel sub-agents | sequential | **skip** | Kiro uses pre-scan data directly |
+| Phase 3 GRAPH | main agent (bash) | main agent (bash) | main agent (bash) | No sub-agents |
+| Phase 4 SYNTHESIZE | parallel sub-agents | sequential | L1 quality from pre-scan | |
+| Phase 5 EXPORT | full (bash) | full (bash) | full (bash) | All IDEs |
 
 ### Kiro Compressed Mode
-Phase 0.5: full pre-scan (bash, same as all IDEs). Phase 1: file counts + import/export counts only (no signatures). Phase 5: L1 quality docs from pre-scan inventory. No CODE_REVIEW.md.
+Phase 1: full pre-scan (bash, same as all IDEs). Phase 2: skip (use pre-scan data). Phase 4: L1 quality docs from pre-scan data only. No quality/ reports.
 
 ### Cursor Sequential Mode
-Modules processed in importance order, one at a time. Progress line per module. Phase 3 and 6 execute normally.
+Modules processed in importance order, one at a time. Progress line per module. Phase 3 and 5 execute normally.
 
 ---
 
@@ -173,13 +178,13 @@ write analysis-state.json
 ### Resume Flow
 1. Read `.atool-docs/analysis-state.json`
 2. If no state file → full analysis
-3. If `phase0_5_prescan != "completed"` → execute Phase 0.5
+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
 
-Detailed resume logic: see `phases/phase0-discovery.md` section 0.5a.
+Detailed resume logic: see `phases/phase1-setup.md`.
 
 ### Incremental Document Recovery
 When resuming Phase 5, incrementally update already-generated documents using `<!-- aTool-module-start:{slug} -->` markers. Only regenerate changed modules.
@@ -188,54 +193,62 @@ When resuming Phase 5, incrementally update already-generated documents using `<
 
 ## Output File Summary
 
-### Final Deliverables (project directory)
-
-| File | Condition |
-|------|-----------|
-| `README.md` | always |
-| `COMPONENT.md` | always |
-| `CODE_REVIEW.md` | L2/L3/L4/L5 |
-| `UI_STYLE.md` | UI projects only |
-| `CLAUDE.md` | append project rules |
-| `.cursor/rules/atool-conventions.mdc` | always |
-| `.kiro/steering/atool-conventions.md` | always |
-| `docs/` (~15 files) | L2/L3/L4/L5 |
-
-### Intermediate Artifacts (.atool-docs/)
-
-| File | Phase |
-|------|-------|
-| `analysis-state.json` | Phase 0 |
-| `pre-scan/{module-slug}.json` | Phase 0.5 |
-| `pre-scan/manifest.json` | Phase 0.5 |
-| `inventory/{module-slug}.json` | Phase 1 |
-| `modules/{module-slug}/MODULE-DOC.md` | Phase 2 |
-| `modules/{module-slug}/analysis.json` | Phase 2 |
-| `modules/{module-slug}/references.json` | Phase 2 |
-| `modules/{module-slug}/l4-analysis.json` | Phase 2a (L4+) |
-| `modules/{module-slug}/l5-analysis.json` | Phase 2b (L5) |
-| `cross-module-behavior.json` | Phase 2b (L5) |
-| `knowledge-graph.json` | Phase 3 |
-| `multi-dimensional-analysis.json` | Phase 3a |
-| `query-index.json` | Phase 3a |
-| `visualization/index.html` | Phase 3a |
-| `code-review/{module-slug}.json` | Phase 4 |
-
-### Multi-Project Extra Outputs
-
-| File | Description |
-|------|-------------|
-| `.atool-docs/discovery.json` | Project discovery record |
-| `.atool-docs/summaries/{name}/summary.md` | Sub-project summary |
-| `.atool-docs/cross-project-analysis.md` | Cross-project relations |
+### 用户交付物（`atool-analysis/`）— 统一入口
+
+| 路径 | 内容 | 生成阶段 |
+|------|------|---------|
+| `atool-analysis/manifest.json` | 元数据：分析时间/版本/栈 | Phase 5 |
+| **overview/** | | |
+| `atool-analysis/overview/summary.md` | 业务摘要（非技术人员友好）| Phase 4 |
+| `atool-analysis/overview/architecture.md` | 架构说明 + Mermaid 图 + ADR | Phase 4 |
+| `atool-analysis/overview/tech-stack.md` | 技术栈明细 | Phase 4 |
+| `atool-analysis/overview/getting-started.md` | 新人上手指南（Zero-KT）| Phase 4 |
+| **modules/{name}/** | | |
+| `atool-analysis/modules/{name}/README.md` | 模块业务说明（非技术人员友好）| Phase 2 |
+| `atool-analysis/modules/{name}/api.md` | 接口文档（字段级 Schema + 错误码表 + curl 示例）| Phase 2 |
+| `atool-analysis/modules/{name}/data-model.md` | 数据模型（字段约束 + 枚举 + 级联 + ER 图）| Phase 2 |
+| `atool-analysis/modules/{name}/dev-guide.md` | 开发指引（如何扩展/调试）| Phase 2 |
+| `atool-analysis/modules/{name}/prd.md` | 模块级 PRD（按钮级交互定义 + 验收标准）| Phase 2 |
+| `atool-analysis/modules/{name}/test-cases.md` | 测试用例（功能/边界/安全/集成）| Phase 2 |
+| **quality/** | | |
+| `atool-analysis/quality/code-review.md` | 代码质量（+重构优先级矩阵+迁移路线图+代码对比）| Phase 4 |
+| `atool-analysis/quality/tech-debt.md` | 技术债清单 | Phase 4 |
+| `atool-analysis/quality/recommendations.md` | 改进建议（+impact-vs-effort 矩阵）| Phase 4 |
+| `atool-analysis/quality/security-audit.md` | 安全审计（OWASP Top 10 逐项检查）| Phase 4 |
+| `atool-analysis/quality/performance-baseline.md` | 性能基准（延迟/内存/并发估算）| Phase 4 |
+| **project/** | | |
+| `atool-analysis/project/prd.md` | 项目级 PRD（全局用户流 + 功能矩阵 + 路线图）| Phase 4 |
+| `atool-analysis/project/deployment.md` | 部署文档（环境/配置/检查清单/回滚）| Phase 4 |
+| `atool-analysis/project/testing-strategy.md` | 测试策略（金字塔 + 覆盖率 + 自动化）| Phase 4 |
+| `atool-analysis/project/runbook.md` | 运维手册（故障排查 + 监控 + 告警）| Phase 4 |
+| **diagrams/** | | |
+| `atool-analysis/diagrams/architecture.mmd` | Mermaid 整体架构图 | Phase 4 |
+| `atool-analysis/diagrams/module-dependencies.mmd` | 模块依赖图 | Phase 4 |
+| `atool-analysis/diagrams/data-flow.mmd` | 数据流向图 | Phase 4 |
+| **data/** | | |
+| `atool-analysis/data/knowledge-graph.json` | 完整知识图谱（供 aTool Monitor）| Phase 5 |
+| `atool-analysis/data/modules.json` | 模块列表 + 指标 | Phase 5 |
+| `atool-analysis/data/metrics.json` | 质量指标（五维分析）| Phase 5 |
+
+### 机器内部产物（`.atool-docs/`）— 用户无需关心
+
+| 路径 | 内容 |
+|------|------|
+| `.atool-docs/analysis-state.json` | Pipeline 状态 |
+| `.atool-docs/pre-scan/*.json` | bash 语法提取（Phase 1）|
+| `.atool-docs/modules/{name}/data.json` | sub-agent 结构化数据（Phase 2）|
+| `.atool-docs/knowledge-graph.json` | 图谱原始数据（Phase 3）|
+| `.atool-docs/multi-dimensional-analysis.json` | 五维分析数据（Phase 3）|
+
+**废弃**：不再生成 `docs/101-*.md`、`docs/201-*.md` 等数字命名文件。原 `README.md`、`COMPONENT.md`、`CODE_REVIEW.md` 等项目根目录文件也不再生成（改为 `atool-analysis/` 内对应文件）。
 
 ---
 
 ## Error Handling
 
 - Analysis state file corrupted → warn user, offer fresh start or manual recovery
-- Pre-scan failure → graceful degradation: skip Phase 0.5, Phase 1 falls back to full AI extraction (v5.0 behavior)
-- Sub-agent fails mid-analysis → mark module as "failed" in state, continue with next module, report in Phase 6
+- Pre-scan failure → graceful degradation: Phase 2 sub-agents 回退到全量 AI 读取源文件
+- Sub-agent fails mid-analysis → mark module as "failed" in state, continue with next module, report in Phase 5 completion summary
 - Source file read error → skip file, mark in inventory as "unreadable", continue
 - Disk space insufficient → warn immediately, offer partial save
 - Resume with changed state version → auto-migrate v3.0/v4.0 → v5.0 (add missing fields with defaults)
@@ -250,7 +263,7 @@ When resuming Phase 5, incrementally update already-generated documents using `<
 - Output summary report upon completion (modules, files, deliverables)
 - Each module document must be immediately readable (Zero-KT standard)
 - Existing CLAUDE.md: only append project rules section
-- docs/: only update aTool-numbered files (101, 201-801), never modify user-created docs
+- `atool-analysis/`: only update files generated by aTool analysis, never modify user-created docs
 - All inferred content marked `[推断]`
 - UI wireframes: UI projects only (web/mobile)
 - **Never fabricate**: only record what is visible in code
@@ -261,10 +274,11 @@ When resuming Phase 5, incrementally update already-generated documents using `<
 
 | Collaborating Skill | Trigger Condition | Interaction |
 |---------------------|-------------------|-------------|
-| code-review | Phase 4 eight-dimension review | References rules/ files |
-| software-architecture | Phase 3a structural layer violation rate >30% | Suggest running |
-| {stack}-conventions | Phase 2 deep analysis | Load stack-level conventions |
-| doc-standards-enforcer | Phase 5 document generation | Validate frontmatter format |
+| code-review | Phase 4 quality report generation | References rules/ files |
+| software-architecture | Phase 3 structural layer violation rate >30% | Suggest running |
+| {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 |
-| clarify-before-build | Before Phase 0 user confirmation | Requirement clarification (auto-injected) |
+| requirements-writer | Phase 4 PRD 覆盖率 < 70% | 建议运行，自动进入后向增强模式读取 atool-analysis/ |
+| clarify-before-build | Before Phase 1 user confirmation | Requirement clarification (auto-injected) |

package/skills/project-analyze/phases/{phase0-discovery.md → archive/phase0-discovery.md}

@@ -21,7 +21,7 @@
 
 统计源文件数（排除 node_modules, build, .git, vendor, target, dist），按规模选择策略：
 
-| 规模 | 文件数 | 建议深度 | 覆盖率 | 最大 Agent | 多批次 | 说明 |
+| 规模 | 文件数 | 默认深度 | 覆盖率 | 最大 Agent | 多批次 | 说明 |
 |------|--------|---------|--------|-----------|--------|------|
 | TINY | 1-50 | L3 | 100% | 5 | 否 | 小项目全量深度分析 |
 | SMALL | 51-200 | L2 | 100% | 5 | L3+ 自动分批 | 中小项目，L3+ 按模块分批 |
@@ -30,7 +30,9 @@
 | XLARGE | 1501-5000 | L2 | Top 50% | 5 | L3+ 始终分批 | 核心 L3+，重要 L2，其余 L1 |
 | MEGA | 5001+ | L2 | 用户选择 | 5 | Wave 策略 | 多波策略，Wave 深度递增 |
 
-**深度覆盖规则**：建议深度为推荐值，用户可在 Phase 0.6 覆盖为任意深度。LARGE/XLARGE 的覆盖率仅影响 L4/L5 深度的模块范围，所有模块至少 L2。
+> **所有项目规模均可使用 L1-L5 任意深度**。上表"默认深度"仅用于回车确认时的默认值，Phase 0.6 必须**始终向用户展示全部 L1-L5 五个选项**。
+
+**深度覆盖规则**：上表"默认深度"仅作为回车确认默认值。**用户可在 Phase 0.6 选择 L1-L5 任意深度**。LARGE/XLARGE 的覆盖率仅影响 L4/L5 深度的模块范围，所有模块至少 L2。
 
 ### 0.2a 批量派发规则（硬性限制）
 
@@ -226,6 +228,8 @@ else (中断的分析):
 
 ### 0.6 用户确认（必须）
 
+> **硬性规则：必须向用户展示全部 L1-L5 五个深度选项，不得省略或隐藏任何等级。** 即使项目规模很小，L4 和 L5 也必须出现在选项列表中，让用户做出知情选择。
+
 向用户展示分析计划并获得确认：
 
 ```

package/skills/project-analyze/phases/{phase1-inventory.md → archive/phase1-inventory.md}

@@ -10,6 +10,16 @@ Phase 1 现在基于 Phase 0.5 pre-scan 数据工作。AI agent 接收 pre-scan
 
 - Phase 0 已完成（`analysis-state.json` 存在，模块列表和 importance 排序已确定）
 
+### 前置检查（硬性 — 禁止跳过）
+
+1. 读取 `analysis-state.json`，确认 `phase0_5_prescan.status == "completed"`
+2. 如果未完成 → **停止 Phase 1**，先执行 Phase 0.5：
+   ```bash
+   source lib/pre-scan.sh && pre_scan_project "$PROJECT_ROOT" "$PRESCAN_DIR"
+   ```
+3. 读取 `.atool-docs/pre-scan/{module-slug}.json`，确认数据存在
+4. 如果某个模块的 pre-scan 数据不存在 → 标记 warning，该模块回退到全量 AI 提取
+
 ## 输入数据
 
 1. Pre-scan JSON（来自 Phase 0.5）

package/skills/project-analyze/phases/{phase2-deep-analysis.md → archive/phase2-deep-analysis.md}

@@ -6,6 +6,13 @@
 
 - Phase 1 已完成（所有 `inventory/{module-slug}.json` 已写入）
 
+### 前置检查（硬性）
+
+1. 读取 `analysis-state.json`，确认 `phase1_inventory.status == "completed"`
+2. 如果未完成 → **停止**，先完成 Phase 1
+3. 读取 `.atool-docs/inventory/{module-slug}.json`，确认数据存在
+4. **L1 深度例外**：Phase 1 被跳过（Phase 0.5 替代），此时直接使用 pre-scan 数据
+
 ## 输入数据
 
 - Phase 0.5 Pre-Scan 数据：每个文件的 imports/exports/classes/functions/decorators/api_endpoints 已由 grep+awk+jq 提取，AI agent 直接引用，无需重新读取
@@ -15,6 +22,17 @@
 - 中文件（100-500行）：读取全文
 - 大文件（>500行）：仅读取 pre-scan 标记的关键行范围
 
+### Pre-scan 降级规则
+
+当 pre-scan 数据或 inventory 数据缺失时（Phase 0.5/1 未执行），sub-agent prompt 必须降级：
+
+1. **pre-scan 数据存在** → 正常三层策略
+2. **pre-scan 数据缺失** → 全量读取降级：
+   - `small_files_list`/`medium_files_list`/`large_files_list` → 全部归入 medium（需全文读取）
+   - `prescan_summary_content` → 替换为 `"⚠️ Pre-scan data NOT available. Read ALL source files to extract structural information."`
+   - `inventory_semantic_content` → 替换为 `"⚠️ Inventory data NOT available. Extract business context from source files."`
+   - 在 sub-agent prompt 末尾追加：`"Pre-scan was skipped. You MUST read all source files first to extract structural info (imports, classes, functions), THEN perform deep analysis."`
+
 ## 详细步骤
 
 ### 2.0a 超大模块拆分策略
@@ -84,6 +102,8 @@ else: 按文件扩展名分组
 
 ### 2.2b 深度级别指令（追加到 sub-agent prompt 末尾）
 
+> **硬性规则：必须将对应深度的完整指令内联展开到 `{depth_specific_instructions}` 变量中。禁止用 "执行 L3 分析" 等抽象标签替代具体指令 — sub-agent 不知道 "L3" 意味着什么。**
+
 根据当前分析深度级别，在 sub-agent prompt 模板末尾追加以下指令：
 
 #### L1 指令

package/skills/project-analyze/phases/{phase3-knowledge-graph.md → archive/phase3-knowledge-graph.md}

@@ -9,12 +9,32 @@
 - Phase 2 已完成（所有 `MODULE-DOC.md` + `analysis.json` 已写入）
 - Phase 2a（如 depth ≥ L4）和 Phase 2b（如 depth ≥ L5）应已完成
 
+### 输入数据检查（硬性 — 禁止跳过）
+
+Phase 3 不读取源文件，只处理 JSON 中间产物。开始前必须确认：
+
+1. 读取 `analysis-state.json`，确认 `phase2_deep_analysis.status == "completed"`
+2. 检查 `.atool-docs/inventory/*.json` 是否存在（Phase 1 输出）
+3. 检查 `.atool-docs/modules/*/analysis.json` 是否存在（Phase 2 输出）
+4. 如果以上文件缺失 → **停止 Phase 3**，先完成对应的 Phase 1 或 Phase 2
+5. **禁止**在缺失中间产物时回退到读取源文件 — 这会导致全量重复读取，违背 pipeline 设计
+6. 如果 `lib/knowledge-graph.sh` 不存在 → 标记 warning，跳过自动图谱构建，AI 手动从 JSON 数据构建
+
 ## 详细步骤
 
 ### 知识图谱构建 (v5.0: 6 步管线)
 
 v5.0 使用 `lib/knowledge-graph.sh` 的函数进行构建。**不要手动实现以下算法，全部通过库函数调用。**
 
+> ⚠️ **硬性指令：必须通过 Bash 工具执行以下命令构建知识图谱。**
+> **禁止用 AI/LLM 直接生成 knowledge-graph.json 内容。**
+> AI 生成的 JSON 格式（如 `modules`/`dependency_edges`）与 `generate-visualization.sh` 期望的 `nodes`/`edges` 格式不兼容，会导致后续可视化、查询和多维分析全部失败。
+>
+> ```bash
+> source lib/knowledge-graph.sh
+> assemble_enhanced_graph "$DOCS_DIR" "$PROJECT_ROOT"
+> ```
+
 1. **节点组装**: 调用 `assemble_enhanced_graph()` — 从 `inventory/*.json` 和 `analysis.json` 读取，支持 14 种节点类型（module, component, function, store, data_entity, api_endpoint, route, config, service, repository, middleware, event, test_suite, layer）
 2. **边组装**: `assemble_enhanced_graph()` 内部调用 `compute_edge_weights()` — 计算 `base_weight × frequency × confidence`，支持 24 种边类型
 3. **层确认**: 结合启发式（Phase 0.3a）+ LLM 验证（Phase 2 sub-agent 结果）
@@ -58,6 +78,17 @@ Instability(M) = Ce / (Ca + Ce)     // 0=稳定(被依赖), 1=不稳定(依赖
 
 写入 `.atool-docs/knowledge-graph.json`：
 
+**格式校验（硬性 — assemble_enhanced_graph() 完成后必须验证）**：
+
+```bash
+jq '.nodes | length' .atool-docs/knowledge-graph.json   # 必须 > 0
+jq '.edges | type' .atool-docs/knowledge-graph.json      # 必须是 "array"
+jq '.layers | type' .atool-docs/knowledge-graph.json     # 必须是 "object"
+jq '.indexes | type' .atool-docs/knowledge-graph.json    # 必须是 "object"
+```
+
+如果 `nodes` 数组长度为 0 → 说明 `inventory/` 或 `analysis.json` 数据缺失，回到输入数据检查步骤排查。**不要在此情况下用 AI 补充生成节点** — 应修复上游 Phase。
+
 ```json
 {
   "version": "5.0",

package/skills/project-analyze/phases/{phase3a-multi-dimensional.md → archive/phase3a-multi-dimensional.md}

@@ -6,6 +6,19 @@
 
 ## 详细步骤
 
+> ⚠️ **硬性指令：必须通过 Bash 工具执行以下命令运行五维分析。**
+> **禁止用 AI/LLM 直接生成 multi-dimensional-analysis.json 内容。**
+> AI 生成的格式与后续查询和可视化工具不兼容。
+>
+> ```bash
+> source lib/multi-dimensional-analysis.sh
+> analyze_structural "$DOCS_DIR"
+> analyze_behavioral "$DOCS_DIR"
+> analyze_data "$DOCS_DIR"
+> analyze_quality "$DOCS_DIR"
+> analyze_semantic "$DOCS_DIR"
+> ```
+
 使用 `lib/multi-dimensional-analysis.sh` 执行 5 个独立分析维度：
 
 ### 3a.1 结构分析

package/skills/project-analyze/phases/{phase5-synthesis.md → archive/phase5-synthesis.md}

@@ -83,6 +83,26 @@ Phase 5 incremental flow:
    g. Generate .atool-docs/visualization/index.html (Cytoscape.js)
 ```
 
+> ⚠️ **可视化生成硬性指令（step 6.g）**：必须通过 Bash 工具执行，禁止用 AI/LLM 直接生成 HTML。
+>
+> 前置检查：
+> ```bash
+> jq '.nodes | length' .atool-docs/knowledge-graph.json
+> ```
+> 如果返回 0 → 可视化跳过（knowledge-graph.json 格式错误或数据缺失），在 Phase 6 报告此问题。
+>
+> 生成可视化：
+> ```bash
+> source lib/generate-visualization.sh
+> generate_visualization "$DOCS_DIR"
+> ```
+>
+> 验证输出：
+> ```bash
+> test -f .atool-docs/visualization/index.html && echo "OK" || echo "MISSING"
+> wc -c < .atool-docs/visualization/index.html  # 应 > 10KB
+> ```
+
 #### COMPONENT.md 增量标记
 
 使用标记包裹每个模块段落，恢复时只替换对应标记内容：