@dtt_siye/atool 1.3.0 → 1.4.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.1.0
+version: 0.2.0
 category: quality
 ---
 
@@ -9,216 +9,777 @@ category: quality
 
 ## 概述
 
-本 skill 提供对已完成 `project-analyze` 分析的项目进行交互式查询。基于 `.atool-docs/knowledge-graph.json` 和 `.atool-docs/multi-dimensional-analysis.json`，支持 6 类查询和 5 级粒度缩放。
+本 skill 提供对已完成 `project-analyze` 分析的项目进行 **深度交互式查询**。基于 knowledge-graph.json 的完整节点和边数据，支持 6 类强大的查询能力、5 级粒度缩放（G1-G5）、丰富的可视化输出（Mermaid 图、ASCII 树、结构化表格）。
+
+**核心价值**：快速回答关于代码结构的复杂问题，无需手工扫描源码。
 
 ## 前置条件
 
-- 项目已通过 `/project-analyze` 完成分析
-- 存在 `.atool-docs/knowledge-graph.json`（v4.0+ 或 v5.0）
-- 如果需要数据流和调用链查询，需要 L2+ 深度的分析结果
+- ✅ 项目已通过 `/project-analyze` 完成分析（L1-L5 任意深度）
+- ✅ 存在 `.atool-docs/knowledge-graph.json`（v5.0+ 格式）
+- ✅ L2+ 深度的分析（推荐）— 更多节点和边信息，查询结果更丰富
+- ⚠️ L1 深度可用但结果只包含模块级节点（无函数、API 等细粒度）
+
+## 工作原理
+
+```
+user query (自然语言或 /command)
+    ↓
+parse query intent (识别查询类型 + 参数)
+    ↓
+load knowledge-graph.json
+    ↓
+apply jq template (执行对应的图查询模板)
+    ↓
+generate output (结构化摘要 + Mermaid 图 + ASCII 视图 + 表格)
+    ↓
+display result (支持 Claude Code / Cursor / 终端)
+```
 
 ## 查询类别
 
 ### 1. 节点查找 (Node Lookup)
 
-查找特定类型的节点。
+快速查找特定的函数、类、模块、API 端点等。
 
+**用户指令**：
 ```
-/find all functions named createUser
-/find all classes in auth module
+/find functions named createUser
+/find classes in auth module
 /find all API endpoints
-/find modules with highest coupling
+/find modules with importance > 0.7
+/find data_entity named User
 ```
 
 **执行步骤**：
-1. 读取 `knowledge-graph.json` 的 `nodes` 数组
-2. 按 `type` 和 `label` 过滤（支持子串匹配）
-3. 输出匹配节点的列表（ID、名称、路径、重要度）
-4. 如果结果 > 20 个，按 importance 降序排列，仅展示 top 20
+1. 解析查询中的 **type** 和 **label** 约束
+2. 读取 `knowledge-graph.json` 的 `nodes` 数组
+3. 按 `type`（精确或模糊）和 `label`（子串匹配，不分大小写）过滤
+4. 按 `importance` 降序排序，限制 top 20（避免过多结果）
+5. 生成输出表格
+
+**输出示例**：
+```
+## Query Result: Node Lookup
+
+Found 5 nodes matching: type=function, label contains "create"
+
+| 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 |
+| ... | | | | | |
+```
+
+**jq 实现**：参考 `rules/query-templates.md` Template 1
 
 ### 2. 路径查询 (Path Query)
 
-查找两个节点之间的调用路径。
+追踪两个节点之间的调用链或依赖链。
 
+**用户指令**：
 ```
-/show call path from UserController.createUser to UserRepository.save
-/show dependency path from module-a to module-b
+/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. 在 knowledge-graph 中定位 source 和 target 节点
-2. 根据 edge 类型选择子图：
-   - `call path` → `calls` + `calls_async` 边
-   - `dependency path` → `depends_on` 边
-3. 执行 BFS 从 source 到 target
-4. 输出路径（每步包含：节点名称、边类型、行号）
-5. 生成 Mermaid `graph LR` 图
-6. 如果有多条路径，展示所有（最多 5 条）
+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 changes if I modify User entity
+/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，递归查找 D 的依赖者（最多 3 层）
-4. 计算风险评分：
-   - `risk(X) = Σ importance(D) × weight(D→X)` 对所有直接依赖者 D
-   - risk > 0.7 = **HIGH**（红色标记）
-   - 0.3-0.7 = **MEDIUM**（橙色标记）
-   - < 0.3 = **LOW**（绿色标记）
-5. 统计受影响的：模块数、函数数、API 端点数、数据实体数
-6. 生成影响范围 Mermaid 图（G1 视角 = 模块级，G3 视角 = 函数级）
-7. 输出风险摘要 + 建议的测试范围
+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 userData come from and where does it flow
+/where does User data flow
+/data flow for Payment status
 ```
 
 **执行步骤**：
-1. 定位数据实体节点 D
-2. **反向追踪**（来源）：沿 `writes_to`, `writes_state`, `transforms` 边反向 BFS
-   - 找到所有写入 D 的函数/服务
-   - 继续追踪这些函数的数据来源
-   - 直到找到外部输入（API、用户输入、定时任务）
-3. **正向追踪**（去向）：沿 `reads_from`, `reads_state`, `transforms`, `persists_to` 边正向 BFS
-   - 找到所有读取 D 的函数/服务
-   - 继续追踪这些函数的输出去向
-   - 直到找到最终汇聚点（数据库、外部 API、日志）
-4. 生成数据血缘图：
-   - Mermaid `graph TD` 图，数据节点高亮
-   - 每步标注操作类型（read/write/transform/persist）
-5. 输出数据流描述文本
+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 跳的所有关联。
+查看某个节点周围 N 跳的所有直接和间接关联。
 
+**用户指令**：
 ```
-/show everything connected to AuthService within 2 hops
-/neighbors of UserController.createUser
+/neighbors of AuthService within 2 hops
+/what's connected to UserController
+/neighborhood of Order module (depth=3)
 ```
 
 **执行步骤**：
 1. 定位焦点节点 F
-2. 无向 BFS（不区分边的方向）展开 N 跳（默认 2，最大 5）
-3. 按当前粒度级别过滤节点/边类型
-4. 输出：
-   - 邻域图（Mermaid）
-   - 每个邻居节点与焦点的关系说明
-   - 按关系类型分组统计
+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)
 
-按度量值排序和筛选节点。
+按各种度量指标排序和统计节点。用于快速识别高风险、高复杂度、高耦合等关键问题点。
 
+**用户指令**：
 ```
-/which module has highest coupling
 /top 10 most complex functions
 /modules ranked by importance
-/show all nodes with Critical risk level
+/which module has highest coupling
+/functions with cyclomatic_complexity > 10
+/show all nodes with criticality CRITICAL
 ```
 
-**支持的度量**：
-- `coupling` → instability (I), efferent coupling (Ce), afferent coupling (Ca)
-- `complexity` → cyclomatic_complexity, halstead_volume
-- `importance` → composite importance score
-- `quality` → maintainability_index, technical_debt_ratio
-- `centrality` → betweenness, in_degree, out_degree
-- `data_flow` → flow_rate, schema_coupling
+**支持的度量指标**：
+
+| 度量类别 | 可用指标 | 解释 |
+|---------|---------|------|
+| **复杂度** | 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. 解析查询的度量和排序方向
-2. 从 knowledge-graph.json 读取所有节点的 metrics
-3. 按指定度量排序
-4. 输出 top N 结果（默认 10，最大 50）
-5. 生成柱状图 ASCII 或 Mermaid
-
-## 粒度缩放 (Zoom Level)
-
-查询时通过 `zoom` 参数控制结果粒度：
-
-| 缩放级别 | 可见节点类型 | 可见边类型 | 适用场景 |
-|---------|------------|-----------|---------|
-| G1 (System) | module, layer | depends_on | 架构全景 |
-| G2 (Module) | + class, service, store, interface | + implements, extends, belongs_to | 模块内部结构 |
-| G3 (Function) | + function, api, route, hook | + calls, calls_async, returns, sends_http | 调用链追踪 |
-| G4 (Data) | + data_entity | + reads_from, writes_to, transforms, validates, reads_state, writes_state | 数据流分析 |
-| G5 (Cross-cutting) | 所有类型 | 所有边类型 | 全景视图 |
-
-**缩放实现**：
-- 读取 knowledge-graph.json
-- 按级别过滤节点类型 → 按级别过滤边类型
-- 从焦点节点 BFS 展开（如有焦点）
-- 返回过滤后的子图
+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)
+```
 
 ## 输出格式
 
-每个查询结果包含以下部分：
+每个查询结果包含以下部分（根据查询类型有所不同）：
 
 ### 1. 结构化摘要
-```
+```markdown
 ## Query Result: Impact Analysis on User entity
 
-**Risk Level**: HIGH (0.82)
+**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 可视化
-根据查询类型生成对应的 Mermaid 图：
-- 路径查询 → `graph LR`（从左到右的有向图）
-- 影响分析 → `graph TD`（从上到下的辐射图）
-- 数据血缘 → `graph TD`（数据流图）
-- 邻域查询 → `graph TD`（星形图）
-- 聚合查询 → 柱状图或表格
+根据查询类型生成对应的图表：
+- **路径查询** → `graph LR`（从左到右的有向链）
+- **影响分析** → `graph TD`（从上到下的辐射树，颜色表示风险等级）
+- **数据血缘** → `graph TD`（数据流向图，高亮数据节点）
+- **邻域查询** → `graph TD`（星形或树形拓扑）
+- **聚合查询** → ASCII 柱状图 + 表格
 
 ### 3. ASCII 视图（终端兼容）
 ```
-UserController.create()  --calls-->  UserService.createUser()
-    └── UserService.createUser()  --calls-->  UserRepository.save()
-        └── UserRepository.save()  --persists_to-->  [DB: users]
+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]
 ```
 
-### 4. 明细表格
-| 节点 | 类型 | 度量 | 关系 |
-|------|------|------|------|
+### 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` 存在，还可以查询：
+如果 `.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
-/show call graph hotspots
+/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
 ```
 
 ## Skill 协作
 
 | 协作 Skill | 触发条件 | 交互方式 |
 |-----------|---------|---------|
-| project-analyze | 需要生成 knowledge-graph.json | 前置依赖 |
-| code-review | 需要更详细的代码质量分析 | 建议运行 |
-| software-architecture | 影响分析显示架构问题 | 建议运行 |
+| **project-analyze** | 需要生成 knowledge-graph.json | 前置依赖 — 必须先运行 `/project-analyze` 生成数据 |
+| **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` 查询节点确切名称，或用模糊搜索 |
+| `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（文档）。
+
+---
 
-## 错误处理
+## 相关资源
 
-- 如果 `knowledge-graph.json` 不存在 → 提示用户先运行 `/project-analyze`
-- 如果查询的节点不存在 → 列出最接近的匹配建议（模糊搜索）
-- 如果查询的度量不存在 → 列出可用的度量列表
-- 如果结果为空 → 建议更高的分析深度（L2+ 推荐用于路径查询）
+- **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`（五维分析算法）