@dtt_siye/atool 1.1.0

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

@@ -0,0 +1,94 @@
+# Phase 1: Inventory
+
+**目标**：轻量扫描所有模块，提取结构元数据。不注入技术栈规则，仅做纯提取。
+
+## Phase 1 变更说明（v5.0）
+
+Phase 1 现在基于 Phase 0.5 pre-scan 数据工作。AI agent 接收 pre-scan JSON，仅验证 confidence: low 的文件并添加语义注释，而非从头提取所有结构信息。
+
+## 前置条件
+
+- Phase 0 已完成（`analysis-state.json` 存在，模块列表和 importance 排序已确定）
+
+## 输入数据
+
+1. Pre-scan JSON（来自 Phase 0.5）
+2. analysis-state.json
+
+## 详细步骤
+
+### 1.1 Sub-agent 分配
+
+按模块分组，每个 agent 处理最多 8 个文件。模块 agent 从 Phase 0 的 importance 排序分配。
+
+### 1.2 提取模板
+
+每个 sub-agent 使用统一提取模板（完整 prompt 见 `prompts/inventory-agent.md`）。
+
+### 1.3 输出
+
+每个模块写入 `.atool-docs/inventory/{module-slug}.json`。输出格式与 v4.0 完全一致（向后兼容），新增 `semantic_purpose`、`module_business_domain`、`component_type` 字段。
+
+### 1.4 跨 IDE 适配
+
+| IDE | 执行方式 |
+|-----|----------|
+| Claude | 并行 sub-agents（最多 5 个，按 importance 分批） |
+| Cursor | 顺序执行，每模块后报告进度 |
+| Kiro | 压缩模式——仅提取文件数、导入/导出计数（无签名详情） |
+
+### 1.5 进度反馈
+
+```
+[Phase 1: Inventory] ████░░░░ 50% (14/28 modules)
+```
+
+## 超大模块拆分策略
+
+当单个模块文件数超过阈值时，自动拆分为子组并行分析：
+
+**拆分阈值**：
+
+| 模块文件数 | 策略 | 说明 |
+|-----------|------|------|
+| ≤30 | 单 agent 处理 | 无需拆分 |
+| 31-100 | 按子目录拆分 | 直接子目录作为子组 |
+| 101-500 | 按子目录 + 文件类型拆分 | 子组 ≤30 文件 |
+| >500 | 递归拆分 + 多轮合并 | 子目录拆 → 仍大则再拆 |
+
+**拆分算法**：
+```
+if file_count <= 30: 单 agent 处理
+elif has_multiple_subdirs: 按直接子目录分组
+else: 按文件扩展名分组
+对仍 >30 文件的组递归拆分
+根目录散落文件归入 "root" 子组
+```
+
+**分析流程**（以 1000 文件模块为例）：
+
+```
+1. 拆分 → sub-group-A(200) / B(350) / C(300) / D(150)
+2. 子组内再拆为 ≤30 文件的 agent 单元（共 ~34 单元）
+3. 并行分析（每批 5 agent）→ 每个 agent 产出 sub-analysis.json
+4. 同组交叉验证：
+   - 悬空引用: callee 在本模块所有子组搜索 → 标记 [external]/[unresolved]
+   - 重复定义: 同名函数多组出现 → 按文件路径消歧
+   - 隐式依赖: 子组 A import 子组 B → 追加到依赖列表
+   - 循环调用: 子组间调用环 → 记录并标注
+   → 输出: sub-group-merged.json
+5. 模块级合并 → 统一函数签名、构建完整调用图、标注跨子组依赖
+6. 向上反馈 → 输出标准 MODULE-DOC.md + analysis.json（与其他模块格式一致）
+```
+
+**状态记录**：拆分信息写入 module 的 `split` 字段。恢复时按子组粒度续传。
+
+## 检查点
+
+每个模块 inventory JSON 写入后立即写入 checkpoint：
+```
+state.modules[module_slug].phase1_status = "completed"
+state.modules[module_slug].phase1_completed_at = now()
+state.checkpoint = { last_completed_phase: "phase1", ... }
+write analysis-state.json
+```

package/skills/project-analyze/phases/phase2-deep-analysis.md

@@ -0,0 +1,249 @@
+# Phase 2: Deep Analysis
+
+**目标**：基于 inventory 数据 + 技术栈规则，生成模块深度文档。
+
+## 前置条件
+
+- Phase 1 已完成（所有 `inventory/{module-slug}.json` 已写入）
+
+## 输入数据
+
+- Phase 0.5 Pre-Scan 数据：每个文件的 imports/exports/classes/functions/decorators/api_endpoints 已由 grep+awk+jq 提取，AI agent 直接引用，无需重新读取
+
+**文件读取策略**：
+- 小文件（<100行）：直接使用 pre-scan 数据
+- 中文件（100-500行）：读取全文
+- 大文件（>500行）：仅读取 pre-scan 标记的关键行范围
+
+## 详细步骤
+
+### 2.0a 超大模块拆分策略
+
+当单个模块文件数超过阈值时，自动拆分为子组并行分析：
+
+**拆分阈值**：
+
+| 模块文件数 | 策略 | 说明 |
+|-----------|------|------|
+| ≤30 | 单 agent 处理 | 无需拆分 |
+| 31-100 | 按子目录拆分 | 直接子目录作为子组 |
+| 101-500 | 按子目录 + 文件类型拆分 | 子组 ≤30 文件 |
+| >500 | 递归拆分 + 多轮合并 | 子目录拆 → 仍大则再拆 |
+
+**拆分算法**：
+```
+if file_count <= 30: 单 agent 处理
+elif has_multiple_subdirs: 按直接子目录分组
+else: 按文件扩展名分组
+对仍 >30 文件的组递归拆分
+根目录散落文件归入 "root" 子组
+```
+
+**分析流程**（以 1000 文件模块为例）：
+
+```
+1. 拆分 → sub-group-A(200) / B(350) / C(300) / D(150)
+2. 子组内再拆为 ≤30 文件的 agent 单元（共 ~34 单元）
+3. 并行分析（每批 5 agent）→ 每个 agent 产出 sub-analysis.json
+4. 同组交叉验证：
+   - 悬空引用: callee 在本模块所有子组搜索 → 标记 [external]/[unresolved]
+   - 重复定义: 同名函数多组出现 → 按文件路径消歧
+   - 隐式依赖: 子组 A import 子组 B → 追加到依赖列表
+   - 循环调用: 子组间调用环 → 记录并标注
+   → 输出: sub-group-merged.json
+5. 模块级合并 → 统一函数签名、构建完整调用图、标注跨子组依赖
+6. 向上反馈 → 输出标准 MODULE-DOC.md + analysis.json（与其他模块格式一致）
+```
+
+**状态记录**：拆分信息写入 module 的 `split` 字段。恢复时按子组粒度续传。
+
+### 2.1 加载分析规则（两级）
+
+**优先级 1 — 栈特定**：`rules/{stack_type}.md`（如 `rules/web-vue.md`）
+**优先级 2 — 模板通用**：`rules/{template}.md`（如 `rules/web.md`）
+**优先级 3 — 通用兜底**：`rules/generic.md`
+
+可用规则文件（16 个）：
+- Web: `web.md`, `web-vue.md`, `web-react.md`, `web-nextjs.md`
+- Mobile: `mobile-swift.md`, `mobile-flutter.md`, `mobile-react-native.md`, `android.md`, `harmony.md`
+- Backend: `java.md`, `python.md`, `go.md`, `rust.md`, `rust-tauri.md`
+- Infra: `devops.md`
+- Fallback: `generic.md`
+
+### 2.2 Sub-agent Prompt
+
+完整的 sub-agent prompt 模板见 `prompts/deep-analysis-agent.md`。
+
+### 2.3 输出
+
+| 文件 | 路径 |
+|------|------|
+| MODULE-DOC.md | `.atool-docs/modules/{module-slug}/MODULE-DOC.md` |
+| analysis.json | `.atool-docs/modules/{module-slug}/analysis.json` |
+| references.json | `.atool-docs/modules/{module-slug}/references.json` |
+
+### 2.2b 深度级别指令（追加到 sub-agent prompt 末尾）
+
+根据当前分析深度级别，在 sub-agent prompt 模板末尾追加以下指令：
+
+#### L1 指令
+（Phase 2 跳过，此指令不生效）
+
+#### L2 指令（默认）
+（使用标准 prompt 模板，无追加）
+
+#### L3 追加指令
+```
+## L3 额外要求
+- 对每个公开函数：提取完整函数签名（含参数名、参数类型、返回类型、throws 声明）
+- 对每个类/接口：提取所有方法签名、属性类型、泛型参数
+- 识别关键实现模式：设计模式使用（策略/工厂/观察者等）、算法选择、缓存策略
+- 对核心业务逻辑函数：提取关键实现步骤（3-5 步），标注 [推断] 如果是推断的
+- 在 MODULE-DOC.md 中新增「实现细节」章节（仅 L3+），含：
+  - 核心函数调用链（caller → current → callee，ASCII 图）
+  - 关键数据结构（接口定义 + 字段说明）
+  - 实现模式说明（用了什么设计模式，为什么）
+- 在 MODULE-DOC.md 中新增「设计决策记录」章节扩展（ADR 格式，至少 3 条）
+```
+
+#### L4 追加指令
+```
+## L4 额外要求（在 L3 基础上）
+- 对每个函数（不仅公开函数）执行以下分析：
+
+1. **调用链追踪**：完整 caller → current → callee 链（跨文件追踪，最多 3 层）
+2. **性能热点识别**：
+   - 循环内的 I/O 操作（网络请求、文件读取、数据库查询）
+   - O(n²) 及以上复杂度算法
+   - 重复计算 / 缓存机会
+   - 大对象创建/复制
+3. **安全审计点**：
+   - 用户输入处理路径（从入口到存储/输出）
+   - SQL/命令拼接点
+   - 认证/授权检查缺失
+   - 敏感数据暴露（日志、错误消息、响应体）
+4. **数据流路径**：
+   - 每个函数的输入数据来源（参数、全局状态、外部调用）
+   - 数据变换步骤（mutation/transformation）
+   - 输出数据去向（返回值、副作用、状态变更）
+
+- 输出文件 3: l4-analysis.json（写入 .atool-docs/modules/{module-slug}/l4-analysis.json）
+{
+  "module": "{module-slug}",
+  "functions": [
+    {
+      "name": "processOrder",
+      "file": "src/services/order.ts",
+      "line_range": [45, 112],
+      "callers": ["OrderController.create", "BatchProcessor.run"],
+      "callees": ["validateOrder", "calculateTotal", "saveOrder", "notifyUser"],
+      "complexity": 8,
+      "hotspots": [
+        { "type": "N+1_query", "line": 78, "severity": "warning", "description": "循环内调用 getUserById" }
+      ],
+      "security_points": [
+        { "type": "input_validation", "line": 49, "status": "present", "description": "订单数据校验" }
+      ],
+      "data_flow": {
+        "inputs": ["params: CreateOrderDTO", "ctx.user (implicit)"],
+        "transforms": ["validate → enrich → calculate → persist"],
+        "outputs": ["return Order entity", "side-effect: notifyUser()"]
+      }
+    }
+  ],
+  "hotspot_summary": { "total": 5, "critical": 1, "warning": 4 },
+  "security_summary": { "total": 8, "issues": 2, "mitigated": 6 }
+}
+```
+
+#### L5 追加指令
+```
+## L5 额外要求（在 L4 基础上）
+- 在 L4 分析基础上，推断跨模块运行时行为：
+
+1. **时序图推断**：
+   - 从调用链推断模块间交互时序
+   - 标注同步/异步、请求/响应方向
+   - 用 Mermaid sequenceDiagram 格式输出
+
+2. **状态机推断**：
+   - 从 if/switch/state 字段推断业务状态机
+   - 列出所有状态、触发条件、转换动作
+   - 用 Mermaid stateDiagram-v2 格式输出
+
+3. **异常路径追踪**：
+   - 每个公开 API 的异常传播路径
+   - 未捕获异常场景
+   - 异常恢复/降级策略
+   - 用 ASCII 路径图展示
+
+4. **数据血缘**：
+   - 追踪数据从用户输入到持久化的完整路径
+   - 标注每个环节的数据变换
+   - 识别数据聚合点和分叉点
+   - 跨模块数据依赖图
+
+- 输出文件 4: l5-analysis.json（写入 .atool-docs/modules/{module-slug}/l5-analysis.json）
+{
+  "module": "{module-slug}",
+  "sequence_diagrams": [
+    {
+      "name": "用户下单流程",
+      "mermaid": "sequenceDiagram\n  participant UI\n  participant OrderService\n  ...",
+      "modules_involved": ["order-service", "user-service", "payment-service"]
+    }
+  ],
+  "state_machines": [
+    {
+      "entity": "Order",
+      "mermaid": "stateDiagram-v2\n  [*] --> Draft\n  Draft --> Pending: submit\n  ...",
+      "states": ["Draft", "Pending", "Approved", "Completed", "Cancelled"],
+      "triggers": { "submit": "Draft→Pending", "approve": "Pending→Approved" }
+    }
+  ],
+  "exception_paths": [
+    {
+      "entry_point": "OrderService.create",
+      "path": "create → validateOrder(throws ValidationException) → saveOrder(throws DBException)",
+      "unhandled": ["DBException at saveOrder: 仅日志记录，未向用户反馈"]
+    }
+  ],
+  "data_lineage": [
+    {
+      "data_item": "Order.totalAmount",
+      "origin": "用户输入 (OrderItem.price * quantity)",
+      "transforms": ["price lookup from Product table", "discount calculation", "tax addition"],
+      "destination": "Order entity → DB → Invoice generation",
+      "cross_module": true,
+      "related_modules": ["product-service", "invoice-service"]
+    }
+  ]
+}
+```
+
+### 2.4 跨 IDE 适配
+
+| IDE | 执行方式 |
+|-----|----------|
+| Claude | 并行 sub-agents（最多 5 个，按 importance 分批） |
+| Cursor | 顺序执行，每模块完成后更新 progress |
+| Kiro | **跳过 Phase 2**（inventory 数据直接进入 Phase 5） |
+
+### 2.5 进度反馈
+
+```
+[Phase 2: Deep Analysis] ██░░░░░░ 25% (7/28 modules)
+  ✓ user-management (15 files) → MODULE-DOC.md + analysis.json
+  ✓ auth-module (8 files) → MODULE-DOC.md + analysis.json
+  ⏳ order-management (23 files) → analyzing...
+```
+
+## 检查点
+
+每个模块 MODULE-DOC.md + analysis.json 写入后立即写入 checkpoint：
+```
+state.modules[module_slug].phase2_status = "completed"
+state.modules[module_slug].phase2_completed_at = now()
+state.checkpoint = { last_completed_phase: "phase2", ... }
+write analysis-state.json
+```

package/skills/project-analyze/phases/phase2a-l4-analysis.md

@@ -0,0 +1,94 @@
+# Phase 2a: L4 Per-Function Analysis
+
+**仅 depth ≥ L4 时执行**
+
+## 前置条件
+
+- Phase 2 完成（所有 MODULE-DOC.md + analysis.json 已写入）
+
+## 目标
+
+对每个模块的每个函数进行调用链追踪、性能热点识别、安全审计、数据流分析。
+
+## 详细步骤
+
+### 2a.1 批量策略
+
+- 复用 Phase 0 的 importance 排序
+- 每个 sub-agent 处理 1 个模块（L4 分析 token 密度高，不合并模块）
+- 批次大小：5 个 agent（硬限制不变）
+- 大模块（>30 文件）：使用超大模块拆分策略（见 `phases/phase2-deep-analysis.md` 2.0a）
+
+### 2a.2 Sub-agent 输入
+
+每个 sub-agent 接收：
+1. Phase 2 的 `analysis.json`（已有函数签名列表）
+2. Phase 1 的 `inventory/{module-slug}.json`（文件列表）
+3. **Pre-Scan 函数表**：Phase 0.5 已提取函数名、参数、行范围、caller/callee 关系。L4 agent 利用行范围定向读取函数体，而非逐文件扫描
+4. 源文件内容（使用 pre-scan 提供的行范围定向读取）
+5. L4 追加指令（见 `phases/phase2-deep-analysis.md` 2.2b L4 追加指令）
+6. Zero-KT 原则 + 语言约束
+
+完整的 sub-agent prompt 模板见 `prompts/l4-analysis-agent.md`。
+
+### 2a.3 输出
+
+- `.atool-docs/modules/{module-slug}/l4-analysis.json`
+
+输出格式（每个函数一个条目）：
+
+```json
+{
+  "module": "{module-slug}",
+  "functions": [
+    {
+      "name": "processOrder",
+      "file": "src/services/order.ts",
+      "line_range": [45, 112],
+      "callers": ["OrderController.create", "BatchProcessor.run"],
+      "callees": ["validateOrder", "calculateTotal", "saveOrder", "notifyUser"],
+      "complexity": 8,
+      "hotspots": [
+        { "type": "N+1_query", "line": 78, "severity": "warning", "description": "循环内调用 getUserById" }
+      ],
+      "security_points": [
+        { "type": "input_validation", "line": 49, "status": "present", "description": "订单数据校验" }
+      ],
+      "data_flow": {
+        "inputs": ["params: CreateOrderDTO", "ctx.user (implicit)"],
+        "transforms": ["validate → enrich → calculate → persist"],
+        "outputs": ["return Order entity", "side-effect: notifyUser()"]
+      }
+    }
+  ],
+  "hotspot_summary": { "total": 5, "critical": 1, "warning": 4 },
+  "security_summary": { "total": 8, "issues": 2, "mitigated": 6 }
+}
+```
+
+### 2a.4 跨 IDE 适配
+
+| IDE | 执行方式 |
+|-----|----------|
+| Claude | 并行 sub-agents（最多 5，按 importance 分批） |
+| Cursor | 顺序执行 |
+| Kiro | **跳过**（Kiro 不执行 L4/L5） |
+
+### 2a.5 检查点
+
+每个模块 L4 分析完成后立即写入 checkpoint：
+```
+state.modules[module_slug].phase2a_status = "completed"
+state.modules[module_slug].phase2a_completed_at = now()
+state.checkpoint = { last_completed_phase: "phase2a", ... }
+write analysis-state.json
+```
+
+### 2a.6 进度反馈
+
+```
+[Phase 2a: L4 Analysis] ███░░░░ 40% (11/28 modules)
+  ✓ user-management (15 files) → l4-analysis.json (23 functions, 2 hotspots, 1 security issue)
+  ✓ auth-module (8 files) → l4-analysis.json (12 functions, 0 hotspots, 3 security points)
+  ⏳ order-management (23 files) → analyzing functions...
+```

package/skills/project-analyze/phases/phase2b-l5-analysis.md

@@ -0,0 +1,97 @@
+# Phase 2b: L5 Cross-Module Behavior Inference
+
+**仅 depth ≥ L5 时执行**
+
+## 前置条件
+
+- Phase 2a 完成（所有 l4-analysis.json 已写入）
+
+## 目标
+
+基于 L4 数据推断跨模块运行时行为——时序图、状态机、异常路径、数据血缘。
+
+## 详细步骤
+
+### 2b.1 执行策略
+
+本阶段分两步：
+
+**步骤 1: 模块内推断（sub-agent 并行）**
+- 每个 sub-agent 读取一个模块的 l4-analysis.json
+- 推断模块内时序图、状态机、异常路径、数据血缘
+- 输出：`.atool-docs/modules/{module-slug}/l5-analysis.json`
+
+**步骤 2: 跨模块聚合（主 agent）**
+- 读取所有 l5-analysis.json 的 summary 字段
+- 构建全局时序图（跨模块交互）
+- 构建全局数据血缘图
+- 检测跨模块异常传播链
+- 输出：`.atool-docs/cross-module-behavior.json`
+
+### 2b.2 cross-module-behavior.json Schema
+
+```json
+{
+  "version": "4.0",
+  "generated_at": "...",
+  "global_sequence_diagrams": [
+    {
+      "name": "完整订单流程",
+      "mermaid": "sequenceDiagram ...",
+      "modules": ["order-service", "user-service", "payment-service"],
+      "entry_trigger": "POST /api/orders"
+    }
+  ],
+  "global_state_machines": [
+    {
+      "entity": "Order",
+      "cross_module": true,
+      "mermaid": "stateDiagram-v2 ...",
+      "owning_module": "order-service",
+      "interacting_modules": ["payment-service", "notification-service"]
+    }
+  ],
+  "global_data_lineage": {
+    "flows": [
+      {
+        "data_item": "User authentication token",
+        "origin_module": "auth-service",
+        "path": "auth-service → [JWT] → gateway → [header] → all-services",
+        "sinks": ["order-service", "user-service", "payment-service"]
+      }
+    ]
+  },
+  "unhandled_exception_clusters": [
+    {
+      "path": "OrderService → PaymentService.charge → [timeout] → no fallback",
+      "severity": "critical",
+      "recommendation": "Add circuit breaker pattern"
+    }
+  ]
+}
+```
+
+### 2b.3 跨 IDE 适配
+
+| IDE | 执行方式 |
+|-----|----------|
+| Claude | 步骤 1 并行 sub-agents，步骤 2 主 agent 聚合 |
+| Cursor | 顺序执行 |
+| Kiro | **跳过** |
+
+## 输出
+
+| 文件 | 路径 |
+|------|------|
+| l5-analysis.json | `.atool-docs/modules/{module-slug}/l5-analysis.json` |
+| cross-module-behavior.json | `.atool-docs/cross-module-behavior.json` |
+
+## 检查点
+
+每个模块 l5-analysis.json 写入后 + 主 agent 聚合完成后写入 checkpoint：
+```
+state.modules[module_slug].phase2b_status = "completed"
+state.modules[module_slug].phase2b_completed_at = now()
+state.checkpoint = { last_completed_phase: "phase2b", ... }
+write analysis-state.json
+```

package/skills/project-analyze/phases/phase3-knowledge-graph.md

@@ -0,0 +1,120 @@
+# Phase 3: Knowledge Graph
+
+**目标**：主 agent 读取所有 inventory + analysis JSON，构建全局知识图谱。
+
+**关键**：本阶段由主 agent 执行，不启动 sub-agent。所有数据从磁盘读取（不在上下文中保留源码）。
+
+## 前置条件
+
+- Phase 2 已完成（所有 `MODULE-DOC.md` + `analysis.json` 已写入）
+- Phase 2a（如 depth ≥ L4）和 Phase 2b（如 depth ≥ L5）应已完成
+
+## 详细步骤
+
+### 知识图谱构建 (v5.0: 6 步管线)
+
+v5.0 使用 `lib/knowledge-graph.sh` 的函数进行构建。**不要手动实现以下算法，全部通过库函数调用。**
+
+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 结果）
+4. **度量计算**: `assemble_enhanced_graph()` 内部计算 Ca/Ce/I 耦合 + importance 集成。公式详见 `lib/knowledge-graph.sh` 头部注释
+5. **图索引**: `build_graph_indexes()` 构建 5 个查询索引（nodes_by_type, nodes_by_name, edges_by_source, edges_by_target, edges_by_type）
+6. **输出**: knowledge-graph.json v5.0
+
+**调用方式**：
+```
+source lib/knowledge-graph.sh
+assemble_enhanced_graph "$DOCS_DIR" "$PROJECT_ROOT"
+```
+
+此函数执行完整 6 步管线。算法细节（节点类型、边类型、权重公式、度量计算）全部定义在 `lib/knowledge-graph.sh` 头部注释中。
+
+### 节点类型（14 种）
+
+完整列表见 `lib/knowledge-graph.sh` 头部注释。主要类型：module, component, function, store, data_entity, api_endpoint, route, config, service, repository, middleware, event, test_suite, layer。
+
+### 边类型（24 种）
+
+完整列表见 `lib/knowledge-graph.sh` 头部注释。主要类型：calls, calls_async, reads_state, writes_state, returns, depends_on, implements, extends, renders, routes_to, sends_http, persists_to, subscribes, publishes, validates, transforms, configures, imports, tests, mocks, contains, inherits, delegates, layer_depends。
+
+### 图谱指标
+
+对每个模块计算（由 `assemble_enhanced_graph()` 自动完成）：
+
+```
+Ca(M) = afferent_coupling  = count(edges where target == M and type == depends_on)
+Ce(M) = efferent_coupling  = count(edges where source == M and type == depends_on)
+Instability(M) = Ce / (Ca + Ce)     // 0=稳定(被依赖), 1=不稳定(依赖别人)
+```
+
+全局检测（由 `assemble_enhanced_graph()` 自动完成）：
+- **循环依赖**：图中的环 → 标记为 Critical
+- **孤立模块**：Ca=0 且 Ce=0 → 标记为 Warning
+- **上帝模块**：Ca > total_modules * 0.5 → 标记为 Warning
+- **不稳定核心**：importance > 0.7 且 Instability > 0.7 → 标记为 Critical
+
+### 输出
+
+写入 `.atool-docs/knowledge-graph.json`：
+
+```json
+{
+  "version": "5.0",
+  "generated_at": "2024-01-01T00:00:00Z",
+  "nodes": [
+    {
+      "id": "mod:user-management",
+      "type": "module",
+      "label": "用户管理",
+      "path": "src/views/user/",
+      "importance": 0.87,
+      "metrics": { "Ca": 5, "Ce": 3, "instability": 0.375 },
+      "layer": "presentation"
+    }
+  ],
+  "edges": [
+    { "source": "comp:UserList", "target": "store:useAuthStore", "type": "reads_state", "weight": 0.8, "confidence": 0.95 }
+  ],
+  "layers": {
+    "detected": ["presentation", "service", "repository", "domain", "infrastructure"],
+    "assignments": { "mod:user-management": "presentation" }
+  },
+  "indexes": {
+    "nodes_by_type": {},
+    "nodes_by_name": {},
+    "edges_by_source": {},
+    "edges_by_target": {},
+    "edges_by_type": {}
+  },
+  "issues": [
+    { "type": "circular_dependency", "severity": "critical", "modules": ["mod:A", "mod:B"], "description": "A→B→A 循环依赖" },
+    { "type": "orphan_module", "severity": "warning", "modules": ["mod:legacy-util"] }
+  ],
+  "mermaid_diagrams": {
+    "module_deps": "graph TD\n  A[user-mgmt] --> B[auth]\n  A --> C[api-user]",
+    "data_flow": "graph LR\n  UI --> Store --> API --> Backend"
+  }
+}
+```
+
+### 图表生成
+
+从知识图谱生成：
+- **模块依赖图**（Mermaid + ASCII）：节点=模块，边=depends_on
+- **数据流图**（Mermaid + ASCII）：追踪 sends_http + persists_to 边
+- **组件树图**（ASCII）：从 renders 边构建
+
+## 跨 IDE 适配
+
+所有 IDE 均执行本阶段（主 agent 计算，不依赖 sub-agent）。
+
+## 检查点
+
+knowledge-graph.json 写入后：
+```
+state.phases.phase3_knowledge_graph.status = "completed"
+state.phases.phase3_knowledge_graph.at = now()
+state.checkpoint = { last_completed_phase: "phase3", ... }
+write analysis-state.json
+```