@dtt_siye/atool 1.4.0 → 1.6.0

package/skills/project-query/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: project-query
 description: 在需要查询项目分析结果时使用 — 支持节点查找、调用链追踪、影响分析、数据血缘、邻域查询、聚合统计，支持 G1-G5 五级粒度缩放。Use when querying analysis results — supports node lookup, call chain tracing, impact analysis, data lineage, neighborhood queries, aggregate statistics with G1-G5 granularity zooming.
-version: 0.2.0
+version: 0.3.0
 category: quality
 ---
 
@@ -9,7 +9,7 @@ category: quality
 
 ## 概述
 
-本 skill 提供对已完成 `project-analyze` 分析的项目进行 **深度交互式查询**。基于 knowledge-graph.json 的完整节点和边数据，支持 6 类强大的查询能力、5 级粒度缩放（G1-G5）、丰富的可视化输出（Mermaid 图、ASCII 树、结构化表格）。
+本 skill 提供 `/project-analyze` 完成分析后的 **深度交互式查询**。基于 knowledge-graph.json，支持 6 类查询能力、5 级粒度缩放（G1-G5），丰富的可视化输出。
 
 **核心价值**：快速回答关于代码结构的复杂问题，无需手工扫描源码。
 
@@ -20,543 +20,82 @@ category: quality
 - ✅ L2+ 深度的分析（推荐）— 更多节点和边信息，查询结果更丰富
 - ⚠️ L1 深度可用但结果只包含模块级节点（无函数、API 等细粒度）
 
-## 工作原理
+## When to Use
 
-```
-user query (自然语言或 /command)
-    ↓
-parse query intent (识别查询类型 + 参数)
-    ↓
-load knowledge-graph.json
-    ↓
-apply jq template (执行对应的图查询模板)
-    ↓
-generate output (结构化摘要 + Mermaid 图 + ASCII 视图 + 表格)
-    ↓
-display result (支持 Claude Code / Cursor / 终端)
-```
+- **节点查找**：寻找特定函数、类、模块、API 端点
+  - `/find functions named createUser`
+  - `/find classes in auth module`
+  - `/find modules with importance > 0.7`
 
-## 查询类别
+- **路径查询**：追踪两个节点之间的调用链或依赖链
+  - `/show call path from A to B`
+  - `/show dependency path from module-auth to module-api`
 
-### 1. 节点查找 (Node Lookup)
+- **影响分析**：评估修改某个节点的风险和影响范围
+  - `/what if I modify User entity`
+  - `/impact of changing AuthService`
+  - `/change analysis for database schema`
 
-快速查找特定的函数、类、模块、API 端点等。
+- **数据血缘**：追踪数据实体从源头到终点的完整流向
+  - `/trace data lineage of Order entity`
+  - `/where does User data flow`
 
-**用户指令**：
-```
-/find functions named createUser
-/find classes in auth module
-/find all API endpoints
-/find modules with importance > 0.7
-/find data_entity named User
-```
+- **邻域查询**：查看某个节点周围 N 跳的所有直接和间接关联
+  - `/neighbors of AuthService within 2 hops`
+  - `/what's connected to UserController`
 
-**执行步骤**：
-1. 解析查询中的 **type** 和 **label** 约束
-2. 读取 `knowledge-graph.json` 的 `nodes` 数组
-3. 按 `type`（精确或模糊）和 `label`（子串匹配，不分大小写）过滤
-4. 按 `importance` 降序排序，限制 top 20（避免过多结果）
-5. 生成输出表格
+- **聚合查询**：按各种度量指标排序和统计节点
+  - `/top 10 most complex functions`
+  - `/modules ranked by importance`
+  - `/functions with cyclomatic_complexity > 10`
 
-**输出示例**：
-```
-## Query Result: Node Lookup
+## Quick Workflow
 
-Found 5 nodes matching: type=function, label contains "create"
+1. **识别查询类型** — 确定要执行的查询：节点、路径、影响、数据流、邻域或聚合
+2. **准备输入参数** — 确定查询的源节点、目标节点、过滤条件、粒度级别（G1-G5）
+3. **执行查询** — 读取 knowledge-graph.json，应用对应查询模板
+4. **生成结果** — 返回结构化摘要 + Mermaid 图 + ASCII 视图 + 详细表格
+5. **解释洞察** — 提供分析建议和下一步操作
 
-| ID | Label | Path | Type | Importance | Metrics |
-|----|-------|------|------|------------|---------|
-| func:UserService.createUser | createUser | src/services/UserService.ts | function | 0.85 | CC: 3, Lines: 42 |
-| func:OrderService.createOrder | createOrder | src/services/OrderService.ts | function | 0.72 | CC: 5, Lines: 68 |
-| ... | | | | | |
-```
+## File Reference Map
 
-**jq 实现**：参考 `rules/query-templates.md` Template 1
+| File | When to Read | Content |
+|------|-------------|---------|
+| `rules/node-lookup.md` | 查找特定代码元素时 | 节点查找的详细步骤、jq 实现、用户指令示例 |
+| `rules/path-query.md` | 追踪调用链或依赖链时 | 路径查询算法、边类型支持、调用链可视化 |
+| `rules/impact-analysis.md` | 评估修改风险时 | 风险评分公式、影响范围统计、测试建议 |
+| `rules/data-lineage.md` | 理解数据流向时 | 数据流追踪算法、流向图生成、流量计算 |
+| `rules/neighborhood.md` | 分析节点关联时 | BFS 邻域算法、粒度级别过滤、关系统计 |
+| `rules/aggregate-stats.md` | 按指标排序统计时 | 支持的度量指标、过滤条件、风险等级判断 |
 
-### 2. 路径查询 (Path Query)
+## Constraints
 
-追踪两个节点之间的调用链或依赖链。
+- 必须先运行 `/project-analyze` 生成 knowledge-graph.json
+- 查询失败时使用 `/find` 确认节点存在
+- 复杂查询（如 G5）可能需要长时间，建议降低粒度
+- 某些度量需要 L2+ 深度，如结果缺失请重新运行更深的分析
 
-**用户指令**：
-```
-/show call path from UserController.createUser to Database.save
-/show dependency path from module-auth to module-api
-/show import chain from A to B
-```
-
-**执行步骤**：
-1. 解析 source 和 target 节点标识符
-2. 在 knowledge-graph 中定位两个节点 ID
-3. 根据查询类型选择遍历的边类型：
-   - `call path` → 沿 `calls` + `calls_async` 边
-   - `dependency path` → 沿 `depends_on` 边
-   - 其他 → 沿所有相关边类型
-4. 执行有向 BFS（广度优先搜索）找到最短路径
-5. 如有多条路径，返回所有（最多 5 条，按路径长度排序）
-6. 生成 Mermaid `graph LR` 有向图
-
-**输出示例**：
-```
-## Query Result: Call Path
-
-Source: UserController.createUser
-Target: Database.save
-
-### Path 1 (3 hops) ✅ SHORTEST
-
-UserController.createUser
-  --calls--> UserService.validateData
-    --calls--> Validator.checkEmail
-      --calls--> Database.save
-
-### Mermaid Diagram
-
-graph LR
-    A["UserController.createUser"] -->|calls| B["UserService.validateData"]
-    B -->|calls| C["Validator.checkEmail"]
-    C -->|calls| D["Database.save"]
-    style A fill:#90EE90
-    style D fill:#FFB6C1
-```
-
-**jq 实现**：参考 `rules/query-templates.md` Template 2
-
-### 3. 影响分析 (Impact Analysis)
-
-分析修改某个节点可能影响的其他部分，以及风险等级。
-
-**用户指令**：
-```
-/what if I modify User entity
-/impact of changing AuthService
-/change analysis for database schema
-```
-
-**执行步骤**：
-1. 定位目标节点 X
-2. 反向查询所有指向 X 的边（反向依赖）：
-   - `depends_on`、`calls`、`reads_from`、`reads_state`、`implements`、`extends`
-3. 对找到的每个直接依赖节点 D，继续反向追踪（递归，最多 3 层）
-4. 计算风险评分公式：
-   ```
-   risk_score = Σ (importance(D) × edge_weight(D→X)) 对所有直接依赖者
-   ```
-5. 风险等级判断：
-   - `risk_score > 0.7` → **🔴 HIGH RISK**（红色）
-   - `0.3 < risk_score ≤ 0.7` → **🟠 MEDIUM RISK**（橙色）
-   - `risk_score ≤ 0.3` → **🟢 LOW RISK**（绿色）
-6. 统计影响范围：受影响的模块数、函数数、API 端点数、数据实体数
-7. 按粒度级别生成 Mermaid 图
-8. 输出建议的测试范围（涉及的单元测试、集成测试、E2E 测试）
-
-**输出示例**：
-```
-## Query Result: Impact Analysis
-
-Target: data_entity:User
-
-**Risk Assessment**: 🔴 HIGH (0.84)
-
-### Direct Dependents (1-hop)
-- func:AuthService.validateUser (importance: 0.9, risk: HIGH)
-- func:OrderService.processOrder (importance: 0.8, risk: HIGH)
-
-### Transitive Dependents (2-hop)
-- module:api (affected functions: 4)
-- module:payment (affected functions: 2)
-
-### Impact Summary
-| Category | Count | Risk Level |
-|----------|-------|-----------|
-| Modules | 5 | HIGH |
-| Functions | 23 | HIGH |
-| API Endpoints | 3 | MEDIUM |
-| Data Entities | 2 | LOW |
-
-### Recommended Testing
-- [ ] Unit tests for AuthService, OrderService
-- [ ] Integration tests for api module
-- [ ] E2E tests for user creation, order flow
-```
-
-**jq 实现**：参考 `rules/query-templates.md` Template 3
-
-### 4. 数据血缘 (Data Lineage)
-
-追踪某个数据实体从源头到终点的完整流向。
-
-**用户指令**：
-```
-/trace data lineage of Order entity
-/where does User data flow
-/data flow for Payment status
-```
-
-**执行步骤**：
-1. 定位数据实体节点 D（type = `data_entity`）
-2. **反向追踪**（来源 Upstream）：
-   - 沿 `writes_to`、`writes_state` 边反向查找所有写入 D 的函数
-   - 继续追踪这些函数的输入来源
-   - 直到找到边界节点（API、user_input、scheduled_task）
-3. **正向追踪**（去向 Downstream）：
-   - 沿 `reads_from`、`reads_state`、`transforms` 边正向查找所有读取 D 的函数
-   - 继续追踪这些函数的输出流向
-   - 直到找到最终汇聚点（database、external_api、log）
-4. 计算数据流速率（flow_rate）：
-   ```
-   flow_rate = count(writers) × count(readers) × avg_transformation_steps
-   ```
-5. 生成 Mermaid `graph TD` 数据流图，包括：
-   - 数据节点（蓝色高亮）
-   - 处理函数（绿色）
-   - 外部系统（灰色）
-   - 每条边标注操作类型（read/write/transform/persist）
-
-**输出示例**：
-```
-## Query Result: Data Lineage
-
-Target: data_entity:Order
-
-### Upstream (Data Sources)
-api:POST/orders
-  --creates--> func:OrderService.createOrder
-    --writes_to--> data_entity:Order
-
-### Processing (Transformations)
-func:OrderService.createOrder
-  --transforms--> func:PaymentService.calculateTotal
-  --transforms--> func:ShippingService.estimateDelivery
-
-### Downstream (Data Sinks)
-data_entity:Order
-  --reads_from--> func:OrderService.getOrders
-    --returns--> api:GET/orders/{id}
-  
-  --persists_to--> database:PostgreSQL
-
-### Data Flow Metrics
-- Writers: 2 functions
-- Readers: 5 functions
-- Transformations: 3 steps
-- Flow Rate: 30 (very high activity)
-```
-
-**jq 实现**：参考 `rules/query-templates.md` Template 4
-
-### 5. 邻域查询 (Neighborhood)
-
-查看某个节点周围 N 跳的所有直接和间接关联。
-
-**用户指令**：
-```
-/neighbors of AuthService within 2 hops
-/what's connected to UserController
-/neighborhood of Order module (depth=3)
-```
-
-**执行步骤**：
-1. 定位焦点节点 F
-2. 构建双向邻接表（边无向化，忽略方向）
-3. 迭代 BFS 展开 N 跳（默认 2，最大 5）：
-   - Hop 0：焦点节点 F 本身
-   - Hop 1：F 的直接邻居
-   - Hop 2：邻居的邻居（排除已访问）
-   - Hop 3：再往外一层
-   - ...
-4. 按粒度级别过滤节点/边类型（G1-G5）
-5. 按关系类型分组统计邻域结构
-
-**输出示例**：
-```
-## Query Result: Neighborhood Query
-
-Focus: module:auth
-Depth: 2 hops
-
-### Hop 1 - Direct Neighbors (4 nodes)
-- module:core (depends_on, depends_on)
-- module:user (implements, depends_on)
-- service:jwt (uses)
-
-### Hop 2 - Secondary Neighbors (6 nodes)
-- module:api (depends_on via core)
-- module:database (depends_on via core)
-- function:validateToken (calls via jwt)
-
-### Relationship Summary
-| Relationship Type | Count | Nodes Affected |
-|------------------|-------|----------------|
-| depends_on | 3 | 4 |
-| calls | 2 | 3 |
-| implements | 1 | 2 |
-| uses | 1 | 1 |
-
-### Neighborhood Graph (Mermaid)
-graph TD
-    auth[("🎯 module:auth")] 
-    core["module:core"]
-    user["module:user"]
-    jwt["service:jwt"]
-    
-    auth -->|depends_on| core
-    auth -->|implements| user
-    auth -->|uses| jwt
-    
-    core -->|depends_on| api["module:api"]
-    core -->|depends_on| db["module:database"]
-```
-
-**jq 实现**：参考 `rules/query-templates.md` Template 5
-
-### 6. 聚合查询 (Aggregate)
-
-按各种度量指标排序和统计节点。用于快速识别高风险、高复杂度、高耦合等关键问题点。
-
-**用户指令**：
-```
-/top 10 most complex functions
-/modules ranked by importance
-/which module has highest coupling
-/functions with cyclomatic_complexity > 10
-/show all nodes with criticality CRITICAL
-```
-
-**支持的度量指标**：
-
-| 度量类别 | 可用指标 | 解释 |
-|---------|---------|------|
-| **复杂度** | cyclomatic_complexity | 圈复杂度（>10 为高风险） |
-| | halstead_volume | 代码体积（>8 为大） |
-| | lines_of_code | 函数行数 |
-| **耦合** | coupling (Ca) | 传入耦合（有多少依赖我） |
-| | coupling (Ce) | 传出耦合（我依赖多少） |
-| | instability (I) | 不稳定性 (Ce/(Ca+Ce)) |
-| **重要性** | importance | 综合重要性评分 (0-1) |
-| **质量** | maintainability_index | 可维护性指数 |
-| | technical_debt_ratio | 技术债占比 |
-| **中心性** | betweenness_centrality | 介数中心性（关键路由节点） |
-| | in_degree | 入度（被依赖次数） |
-| | out_degree | 出度（依赖他人次数） |
-| **数据流** | flow_rate | 数据流量 |
-| | schema_coupling | 数据耦合度 |
-
-**执行步骤**：
-1. 解析查询条件：目标度量、排序方向（升/降）、数量限制（top N）、过滤条件
-2. 从 knowledge-graph.json 加载所有节点及其 metrics
-3. 应用过滤条件（如 complexity > 10）
-4. 按指定度量排序
-5. 取 top N（默认 10，最大 50）
-6. 生成柱状图（ASCII 或 Mermaid）和排序表格
-
-**输出示例**：
-```
-## Query Result: Aggregate Metrics
-
-Query: Top 10 Functions by Cyclomatic Complexity
-
-### Results (Sorted by cyclomatic_complexity DESC)
-
-| Rank | Function | CC | Lines | Risk Level |
-|------|----------|----|----|------------|
-| 1 | OrderService.processOrder | 23 | 342 | 🔴 CRITICAL |
-| 2 | PaymentService.validatePayment | 18 | 267 | 🔴 HIGH |
-| 3 | AuthService.authenticate | 14 | 198 | 🟠 MEDIUM |
-| 4 | UserService.createUser | 9 | 156 | 🟢 LOW |
-| ... | | | | |
-
-### ASCII Chart
-
-cyclomatic_complexity distribution:
-OrderService.processOrder         |██████████████████████ 23
-PaymentService.validatePayment    |██████████████████ 18
-AuthService.authenticate          |██████████████ 14
-UserService.createUser            |█████████ 9
-ShippingService.estimateDelivery  |████████ 8
-...
-
-### Statistics
-- Mean CC: 8.2
-- Median CC: 7
-- Max CC: 23 (OrderService.processOrder)
-- Functions with CC > 10: 3 (HIGH RISK)
-
-### Recommendations
-- Refactor OrderService.processOrder (consider splitting into 3-4 functions)
-- Add comprehensive tests for PaymentService.validatePayment
-- Monitor AuthService.authenticate for future complexity growth
-```
-
-**jq 实现**：参考 `rules/query-templates.md` Template 6
-
-## 粒度缩放 (Zoom Level G1-G5)
-
-查询时通过 `zoom` 或 `G` 参数控制结果粒度，从高层架构到低层细节：
-
-| 缩放级别 | 可见节点类型 | 可见边类型 | 用途 | 典型查询 |
-|---------|------------|-----------|------|---------|
-| **G1** (System) | `module`、`layer` | `depends_on` | 高层架构视图 | /top modules by importance (G1) |
-| **G2** (Module) | G1 + `class`、`service`、`store`、`interface` | G1 + `implements`、`extends`、`belongs_to` | 模块内部结构 | /neighborhood of auth module (G2) |
-| **G3** (Function) | G2 + `function`、`api_endpoint`、`route`、`hook` | G2 + `calls`、`calls_async`、`returns`、`sends_http` | 调用链追踪 | /show call path from A to B (G3) |
-| **G4** (Data) | G3 + `data_entity` | G3 + `reads_from`、`writes_to`、`transforms`、`validates`、`reads_state`、`writes_state` | 数据流分析 | /trace data lineage of User (G4) |
-| **G5** (Cross-cutting) | 所有 14 种节点类型 | 所有 24 种边类型 | 全景分析 | /impact analysis of core module (G5) |
-
-**缩放机制**：
-1. 用户指定粒度（默认 G2）
-2. 根据粒度级别过滤 nodes 类型集合
-3. 根据粒度级别过滤 edges 类型集合
-4. 应用 BFS 或 DFS 算法
-5. 返回过滤后的子图
-
-**使用示例**：
-```bash
-# 系统级概览（只看模块和层）
-/top modules by importance (zoom=G1)
-
-# 模块级细节（看类和接口）
-/neighborhood of auth (zoom=G2)
-
-# 函数级调用链
-/show call path from UserController.create to UserService.save (zoom=G3)
-
-# 数据流（包括数据实体）
-/trace data lineage of Order (zoom=G4)
-
-# 完整全景
-/impact analysis of User entity (zoom=G5)
-```
+> IMPORTANT: When this skill is invoked, you MUST read the relevant
+> subdirectory files based on the user's query type. Do NOT attempt to execute
+> this skill using only this SKILL.md content.
 
 ## 输出格式
 
-每个查询结果包含以下部分（根据查询类型有所不同）：
-
-### 1. 结构化摘要
-```markdown
-## Query Result: Impact Analysis on User entity
-
-**Risk Level**: 🔴 HIGH (0.82)
-**Affected Modules**: 5
-**Affected Functions**: 23
-**Affected APIs**: 3
-**Affected Data Entities**: 2
-
-### Key Insights
-- Most critical: AuthService, OrderService
-- Highest risk path: User → AuthService → PaymentService
-```
-
-### 2. Mermaid 可视化
-根据查询类型生成对应的图表：
-- **路径查询** → `graph LR`（从左到右的有向链）
-- **影响分析** → `graph TD`（从上到下的辐射树，颜色表示风险等级）
-- **数据血缘** → `graph TD`（数据流向图，高亮数据节点）
-- **邻域查询** → `graph TD`（星形或树形拓扑）
-- **聚合查询** → ASCII 柱状图 + 表格
-
-### 3. ASCII 视图（终端兼容）
-```
-UserController.create()
-  --[calls]--> UserService.createUser()
-    --[calls]--> UserRepository.save()
-      --[persists_to]--> [DB: users]
-
-Tree format:
-  ┌─ UserController.create() [importance: 0.8, CC: 5]
-  │  └─ UserService.createUser() [importance: 0.7, CC: 8]
-  │     └─ UserRepository.save() [importance: 0.6, CC: 3]
-```
+每个查询结果包含：
+- **结构化摘要**：查询类型、关键指标、数量统计
+- **Mermaid 可视化**：根据查询类型生成相应图表
+- **ASCII 视图**：终端兼容的文本视图
+- **详细表格**：完整数据表格
+- **建议和洞察**：风险提示、优化建议、下一步行动
 
-### 4. 详细表格
-```markdown
-| 节点 ID | 节点名 | 类型 | 重要性 | 度量值 | 关系 |
-|--------|--------|------|--------|--------|------|
-| func:A.create | A.create | function | 0.8 | CC: 5 | calls |
-| func:B.validate | B.validate | function | 0.7 | CC: 8 | calls_async |
-```
+## 粒度缩放
 
-### 5. 建议和洞察
-```markdown
-### Recommendations
-- 🔴 CRITICAL: Refactor OrderService (CC=23)
-- 🟠 HIGH: Add integration tests for auth module
-- 🟢 LOW: Monitor UserService for future changes
-```
-
-## 多维分析查询（需要 Multi-Dimensional Analysis）
-
-如果 `.atool-docs/multi-dimensional-analysis.json` 存在（project-analyze Phase 3 输出），还可以进行高级多维分析查询：
-
-### 5 维分析框架
-
-| 维度 | 关注点 | 查询示例 |
-|------|--------|---------|
-| **结构维** | 模块划分、依赖拓扑、分层遵循 | `/show structural analysis results` |
-| **行为维** | 调用关系、数据流、控制流 | `/show call graph hotspots` |
-| **数据维** | 数据流向、数据耦合、数据质量 | `/show data flow hotspots` |
-| **质量维** | 复杂度、重复代码、技术债 | `/show quality metrics summary` |
-| **语义维** | 业务术语、领域对象、业务规则 | `/show domain vocabulary` |
-
-### 查询命令
-
-```bash
-# 结构分析
-/show structural analysis results
-/find layering violations
-/detect circular dependencies (depth=3)
-
-# 行为分析
-/show call graph hotspots (top=10)
-/trace control flow for OrderService
-/find execution bottlenecks
-
-# 数据分析
-/show data flow hotspots
-/trace data dependencies across modules
-/find schema coupling issues
-
-# 质量分析
-/show quality metrics summary
-/find code smell clusters
-/show technical debt hotspots (sorted=desc, limit=20)
-
-# 语义分析
-/show domain vocabulary
-/extract business concepts
-/map entity relationships
-```
-
-### 输出示例
-
-```markdown
-## Multi-Dimensional Analysis: Quality Metrics
-
-### 质量维 Quality Dimension
-- Average Cyclomatic Complexity: 6.2
-- Hotspots (CC > 10): 5 functions
-- Duplicate Code Blocks: 23 instances (~12% code duplication)
-- Technical Debt Ratio: 15.3% (MEDIUM)
-
-### 结构维 Structure Dimension
-- Modules: 8 (avg 3.2 imports per module)
-- Layering Violations: 0 ✅
-- Circular Dependencies: 0 ✅
-- Stability Index: 0.62 (MODERATE)
-
-### 行为维 Behavior Dimension
-- Call Graph Diameter: 7 hops
-- Hottest Call Paths: OrderService → PaymentService → Database
-- Async Calls: 12% of total
-
-### 数据维 Data Dimension
-- Data Entities: 14
-- Schema Coupling: 0.41 (MODERATE)
-- Data Flow Hotspots: User → Order → Payment (3-hop flow)
-
-### 语义维 Semantic Dimension
-- Domain Concepts: auth, order, payment, shipping
-- Entity Mapping: User → Order (1:many), Order → Payment (1:1)
-- Business Rules: 23 detected
-```
+通过 `zoom` 或 `G` 参数控制结果粒度：
+- **G1** (System)：模块、层的高层架构视图
+- **G2** (Module)：模块内部结构，包含类、服务
+- **G3** (Function)：调用链，包含函数、API 端点
+- **G4** (Data)：数据流，包含数据实体
+- **G5** (Cross-cutting)：全部分析，所有节点和边类型
 
 ## Skill 协作
 
@@ -566,220 +105,11 @@ Tree format:
 | **code-review** | 影响分析显示代码质量问题 | 建议运行 — 用于深度代码质量评分 |
 | **software-architecture** | 影响分析显示架构违反 | 建议运行 — 用于架构重构或规范化 |
 
-## 最佳实践和使用场景
-
-### 场景 1: 新人快速上手（30 分钟）
-```bash
-# Step 1: 了解项目全貌
-/top modules by importance (zoom=G1)
-
-# Step 2: 深入核心模块
-/neighborhood of core module (depth=2, zoom=G2)
-
-# Step 3: 追踪关键数据流
-/trace data lineage of User (zoom=G4)
-```
-
-### 场景 2: 评估修改风险
-```bash
-# 修改某个函数前
-/impact of changing UserService.updateProfile
-
-# 修改某个数据模型前
-/what if I modify Order entity
-
-# 推荐的测试范围会自动生成
-```
-
-### 场景 3: 识别技术债
-```bash
-# 查找最复杂的函数
-/top 20 functions by cyclomatic_complexity
-
-# 查找最高耦合的模块
-/modules ranked by coupling (sorted=desc, limit=10)
-
-# 查找技术债占比最高的
-/nodes with technical_debt_ratio > 0.3
-```
-
-### 场景 4: 架构审查
-```bash
-# 整个系统的依赖拓扑
-/show all modules and dependencies (zoom=G1)
-
-# 检测循环依赖
-/find circular dependencies
-
-# 验证分层原则
-/check layering violations
-```
-
-## 错误处理和故障排除
+## 错误处理
 
 | 错误 | 原因 | 解决方案 |
 |------|------|--------|
-| `knowledge-graph.json not found` | 项目未分析 | 运行 `/project-analyze` 完成初始分析 |
-| `node not found` | 查询的节点不存在 | 使用 `/find` 查询节点确切名称，或用模糊搜索 |
+| `knowledge-graph.json not found` | 项目未分析 | 运行 `/project-analyze` |
+| `node not found` | 查询的节点不存在 | 使用 `/find` 查询节点确切名称 |
 | `no results` | 查询条件过严格 | 放松过滤条件，或提升分析深度（L3+） |
-| `metric not available` | 该度量在此分析深度不存在 | 某些度量需要 L2+ 深度，重新运行更深的分析 |
-| `timeout` | 查询太复杂（如 G5 的大图） | 降低粒度级别（G5 → G3），或限制查询范围 |
-
-**快速故障排除流程**：
-```
-Query fails?
-  ├─ Check if knowledge-graph.json exists
-  │   └─ No → Run /project-analyze
-  ├─ Check if node/metric names are correct
-  │   └─ No → Use /find to search
-  ├─ Check if analysis depth is sufficient
-  │   └─ L1 → Rerun with L2+ for more detail
-  └─ Check if zoom level is appropriate
-      └─ Too detailed → Lower granularity
-```
-
-## 高级技巧
-
-### 1. 导出查询结果
-所有查询结果都支持导出为 JSON/CSV：
-```bash
-/find functions named "create*" (export=json)
-# 输出标准 JSON，可用 jq 处理
-```
-
-### 2. 保存查询模板
-频繁使用的查询可保存为别名：
-```bash
-/alias weekly-review = "top 10 modules by importance (G1) + top 20 functions by cyclomatic_complexity"
-/weekly-review  # 一键执行
-```
-
-### 3. 比较两个分析结果
-```bash
-# 对比两个不同版本的项目
-/compare analysis v1 vs v2 (metric=cyclomatic_complexity)
-# 输出：哪些函数变得更复杂、哪些模块耦合度增加等
-```
-
-### 4. 生成质量报告
-```bash
-/generate report (title="Project Quality Review", include=["complexity", "coupling", "risk"])
-# 输出一份综合报告，含图表和建议
-```
-
----
-
-## 快速参考表
-
-### 6 类查询速查
-
-| 查询类型 | 命令示例 | 适用场景 | 输出 |
-|---------|---------|---------|------|
-| **节点查找** | `/find functions named "create*"` | 查找特定代码元素 | 表格 + 重要性排序 |
-| **路径查询** | `/show call path from A to B` | 追踪调用链或依赖链 | Mermaid 图 + ASCII 树 |
-| **影响分析** | `/what if I modify User entity` | 评估修改风险 | 风险评分 + 影响范围 + 测试建议 |
-| **数据血缘** | `/trace data lineage of Order` | 理解数据流向 | 上游/处理/下游 + Mermaid 图 |
-| **邻域查询** | `/neighbors of AuthService (depth=2)` | 理解节点关联 | 星形/树形拓扑 + 关系统计 |
-| **聚合查询** | `/top 10 functions by cyclomatic_complexity` | 识别风险点 | 排序表格 + ASCII 柱状图 |
-
-### 粒度级别速查
-
-| 级别 | 用途 | 典型查询 |
-|------|------|---------|
-| **G1** | 系统级架构 | `/top modules by importance (G1)` |
-| **G2** | 模块结构 | `/neighborhood of core (G2)` |
-| **G3** | 调用链 | `/show call path A→B (G3)` |
-| **G4** | 数据流 | `/trace data lineage (G4)` |
-| **G5** | 全景分析 | `/impact analysis (G5)` |
-
-### 常用度量指标速查
-
-| 度量 | 含义 | 高风险阈值 |
-|------|------|-----------|
-| `cyclomatic_complexity` | 圈复杂度 | > 10 |
-| `halstead_volume` | 代码体积 | > 8 |
-| `lines_of_code` | 代码行数 | > 200 |
-| `coupling (Ce)` | 传出耦合 | > 0.7 |
-| `instability (I)` | 不稳定性 | > 0.8 |
-| `importance` | 综合重要性 | > 0.8 |
-| `technical_debt_ratio` | 技术债占比 | > 0.2 |
-| `betweenness_centrality` | 关键度（枢纽） | > 0.5 |
-
----
-
-## 完整工作流示例
-
-### 场景：重构一个遗留项目
-
-```bash
-# Step 1: 了解全局架构（5分钟）
-/top modules by importance (zoom=G1)
-# 识别核心模块和边界模块
-
-# Step 2: 深入高风险模块（10分钟）
-/top 10 functions by cyclomatic_complexity
-# 找出最复杂的函数，优先重构
-
-# Step 3: 分析重构影响范围（5分钟）
-/impact of changing OrderService.processOrder
-# 评估修改风险，确定测试范围
-
-# Step 4: 验证架构约束（3分钟）
-/find circular dependencies
-/find layering violations
-# 确保重构后不引入新的架构问题
-
-# Step 5: 生成交付物（2分钟）
-/generate report (title="Refactoring Plan", include=["complexity", "risk", "dependencies"])
-# 生成可交付的分析报告
-```
-
-### 场景：新人代码审查
-
-```bash
-# 新人需要 review UserService，但不知道从何下手
-
-# Step 1: 理解 UserService 的职责
-/show definition of UserService
-/neighborhood of UserService (depth=1, G2)
-# 知道它依赖谁，谁依赖它
-
-# Step 2: 追踪关键调用链
-/show call path from UserController.createUser to UserRepository.save
-# 理解整个流程
-
-# Step 3: 确认数据流
-/trace data lineage of User entity
-# 知道 User 数据怎么来的、流向哪里
-
-# Step 4: 评估修改风险
-/impact of changing UserService.validateEmail
-# 确定这个修改会影响哪些测试用例
-
-# 现在新人可以自信地进行 review 了！
-```
-
----
-
-## FAQ
-
-**Q: 我的项目有 500+ 文件，是否支持？**  
-A: 完全支持。使用 L1 分析快速了解全貌（<2分钟），或用粒度缩放（G1）查看模块级视图。
-
-**Q: Query Panel 和 code-review 有什么区别？**  
-A: code-review 专注代码质量分析（8维度评分），project-query 专注**结构和关系分析**（路径、影响、数据流）。通常配合使用。
-
-**Q: 怎样处理查询结果太多的情况？**  
-A: 使用 `limit`、`filter`、`zoom` 参数缩小范围。例如 `/top 50 functions ... (limit=10, zoom=G2)`。
-
-**Q: 支持导出为什么格式？**  
-A: 支持 JSON（标准格式，可用 jq 处理）、CSV（电子表格）、HTML（报告）、PDF（文档）。
-
----
-
-## 相关资源
-
-- **Project Analyze Guide**：`docs/14-project-analyze-guide.md`
-- **Query Templates**：`rules/query-templates.md`（jq 实现细节）
-- **Knowledge Graph Schema**：`lib/knowledge-graph.sh`（节点/边定义）
-- **Multi-Dimensional Analysis**：`lib/multi-dimensional-analysis.sh`（五维分析算法）
+| `timeout` | 查询太复杂 | 降低粒度级别（G5 → G3），限制查询范围 |