@dtt_siye/atool 1.3.1 → 1.5.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.3.0
 category: quality
 ---
 
@@ -9,216 +9,107 @@ 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），丰富的可视化输出。
+
+**核心价值**：快速回答关于代码结构的复杂问题，无需手工扫描源码。
 
 ## 前置条件
 
-- 项目已通过 `/project-analyze` 完成分析
-- 存在 `.atool-docs/knowledge-graph.json`（v4.0+ 或 v5.0）
-- 如果需要数据流和调用链查询，需要 L2+ 深度的分析结果
-
-## 查询类别
-
-### 1. 节点查找 (Node Lookup)
-
-查找特定类型的节点。
-
-```
-/find all functions named createUser
-/find all classes in auth module
-/find all API endpoints
-/find modules with highest coupling
-```
-
-**执行步骤**：
-1. 读取 `knowledge-graph.json` 的 `nodes` 数组
-2. 按 `type` 和 `label` 过滤（支持子串匹配）
-3. 输出匹配节点的列表（ID、名称、路径、重要度）
-4. 如果结果 > 20 个，按 importance 降序排列，仅展示 top 20
-
-### 2. 路径查询 (Path Query)
-
-查找两个节点之间的调用路径。
-
-```
-/show call path from UserController.createUser to UserRepository.save
-/show dependency path from module-a to module-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 条）
-
-### 3. 影响分析 (Impact Analysis)
-
-分析修改某个节点后的影响范围。
-
-```
-/what changes if I modify User entity
-/impact of changing AuthService
-```
-
-**执行步骤**：
-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. 输出风险摘要 + 建议的测试范围
-
-### 4. 数据血缘 (Data Lineage)
-
-追踪数据的来源和去向。
-
-```
-/trace data lineage of Order entity
-/where does userData come from and where does it flow
-```
-
-**执行步骤**：
-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. 输出数据流描述文本
-
-### 5. 邻域查询 (Neighborhood)
-
-查看某个节点周围 N 跳的所有关联。
-
-```
-/show everything connected to AuthService within 2 hops
-/neighbors of UserController.createUser
-```
-
-**执行步骤**：
-1. 定位焦点节点 F
-2. 无向 BFS（不区分边的方向）展开 N 跳（默认 2，最大 5）
-3. 按当前粒度级别过滤节点/边类型
-4. 输出：
-   - 邻域图（Mermaid）
-   - 每个邻居节点与焦点的关系说明
-   - 按关系类型分组统计
-
-### 6. 聚合查询 (Aggregate)
-
-按度量值排序和筛选节点。
-
-```
-/which module has highest coupling
-/top 10 most complex functions
-/modules ranked by importance
-/show all nodes with Critical risk level
-```
-
-**支持的度量**：
-- `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
-
-**执行步骤**：
-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 展开（如有焦点）
-- 返回过滤后的子图
+- ✅ 项目已通过 `/project-analyze` 完成分析（L1-L5 任意深度）
+- ✅ 存在 `.atool-docs/knowledge-graph.json`（v5.0+ 格式）
+- ✅ L2+ 深度的分析（推荐）— 更多节点和边信息，查询结果更丰富
+- ⚠️ L1 深度可用但结果只包含模块级节点（无函数、API 等细粒度）
+
+## When to Use
+
+- **节点查找**：寻找特定函数、类、模块、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`
+
+- **影响分析**：评估修改某个节点的风险和影响范围
+  - `/what if I modify User entity`
+  - `/impact of changing AuthService`
+  - `/change analysis for database schema`
+
+- **数据血缘**：追踪数据实体从源头到终点的完整流向
+  - `/trace data lineage of Order entity`
+  - `/where does User data flow`
+
+- **邻域查询**：查看某个节点周围 N 跳的所有直接和间接关联
+  - `/neighbors of AuthService within 2 hops`
+  - `/what's connected to UserController`
+
+- **聚合查询**：按各种度量指标排序和统计节点
+  - `/top 10 most complex functions`
+  - `/modules ranked by importance`
+  - `/functions with cyclomatic_complexity > 10`
+
+## Quick Workflow
+
+1. **识别查询类型** — 确定要执行的查询：节点、路径、影响、数据流、邻域或聚合
+2. **准备输入参数** — 确定查询的源节点、目标节点、过滤条件、粒度级别（G1-G5）
+3. **执行查询** — 读取 knowledge-graph.json，应用对应查询模板
+4. **生成结果** — 返回结构化摘要 + Mermaid 图 + ASCII 视图 + 详细表格
+5. **解释洞察** — 提供分析建议和下一步操作
+
+## File Reference Map
+
+| 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` | 按指标排序统计时 | 支持的度量指标、过滤条件、风险等级判断 |
+
+## Constraints
+
+- 必须先运行 `/project-analyze` 生成 knowledge-graph.json
+- 查询失败时使用 `/find` 确认节点存在
+- 复杂查询（如 G5）可能需要长时间，建议降低粒度
+- 某些度量需要 L2+ 深度，如结果缺失请重新运行更深的分析
+
+> 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. 结构化摘要
-```
-## Query Result: Impact Analysis on User entity
-
-**Risk Level**: HIGH (0.82)
-**Affected Modules**: 5
-**Affected Functions**: 23
-**Affected APIs**: 3
-```
-
-### 2. Mermaid 可视化
-根据查询类型生成对应的 Mermaid 图：
-- 路径查询 → `graph LR`（从左到右的有向图）
-- 影响分析 → `graph TD`（从上到下的辐射图）
-- 数据血缘 → `graph TD`（数据流图）
-- 邻域查询 → `graph TD`（星形图）
-- 聚合查询 → 柱状图或表格
-
-### 3. ASCII 视图（终端兼容）
-```
-UserController.create()  --calls-->  UserService.createUser()
-    └── UserService.createUser()  --calls-->  UserRepository.save()
-        └── UserRepository.save()  --persists_to-->  [DB: users]
-```
-
-### 4. 明细表格
-| 节点 | 类型 | 度量 | 关系 |
-|------|------|------|------|
-
-## 多维分析查询
-
-如果 `.atool-docs/multi-dimensional-analysis.json` 存在，还可以查询：
-
-```
-/show structural analysis results
-/show call graph hotspots
-/show data flow hotspots
-/show quality metrics summary
-/show domain vocabulary
-```
+每个查询结果包含：
+- **结构化摘要**：查询类型、关键指标、数量统计
+- **Mermaid 可视化**：根据查询类型生成相应图表
+- **ASCII 视图**：终端兼容的文本视图
+- **详细表格**：完整数据表格
+- **建议和洞察**：风险提示、优化建议、下一步行动
+
+## 粒度缩放
+
+通过 `zoom` 或 `G` 参数控制结果粒度：
+- **G1** (System)：模块、层的高层架构视图
+- **G2** (Module)：模块内部结构，包含类、服务
+- **G3** (Function)：调用链，包含函数、API 端点
+- **G4** (Data)：数据流，包含数据实体
+- **G5** (Cross-cutting)：全部分析，所有节点和边类型
 
 ## Skill 协作
 
 | 协作 Skill | 触发条件 | 交互方式 |
 |-----------|---------|---------|
-| project-analyze | 需要生成 knowledge-graph.json | 前置依赖 |
-| code-review | 需要更详细的代码质量分析 | 建议运行 |
-| software-architecture | 影响分析显示架构问题 | 建议运行 |
+| **project-analyze** | 需要生成 knowledge-graph.json | 前置依赖 — 必须先运行 `/project-analyze` 生成数据 |
+| **code-review** | 影响分析显示代码质量问题 | 建议运行 — 用于深度代码质量评分 |
+| **software-architecture** | 影响分析显示架构违反 | 建议运行 — 用于架构重构或规范化 |
 
 ## 错误处理
 
-- 如果 `knowledge-graph.json` 不存在 → 提示用户先运行 `/project-analyze`
-- 如果查询的节点不存在 → 列出最接近的匹配建议（模糊搜索）
-- 如果查询的度量不存在 → 列出可用的度量列表
-- 如果结果为空 → 建议更高的分析深度（L2+ 推荐用于路径查询）
+| 错误 | 原因 | 解决方案 |
+|------|------|--------|
+| `knowledge-graph.json not found` | 项目未分析 | 运行 `/project-analyze` |
+| `node not found` | 查询的节点不存在 | 使用 `/find` 查询节点确切名称 |
+| `no results` | 查询条件过严格 | 放松过滤条件，或提升分析深度（L3+） |
+| `timeout` | 查询太复杂 | 降低粒度级别（G5 → G3），限制查询范围 |

package/skills/project-query/rules/aggregate-stats.md

@@ -0,0 +1,301 @@
+# Aggregate Query - 聚合查询
+
+## 支持的度量指标
+
+### 复杂度指标
+| 度量 | 解释 | 高风险阈值 | 数据来源 |
+|------|------|-----------|---------|
+| `cyclomatic_complexity` | 圈复杂度 | > 10 | Static Analysis |
+| `halstead_volume` | 代码体积 | > 8 | Static Analysis |
+| `lines_of_code` | 函数行数 | > 200 | Static Analysis |
+
+### 耦合指标
+| 度量 | 解释 | 高风险阈值 | 数据来源 |
+|------|------|-----------|---------|
+| `coupling (Ca)` | 传入耦合（有多少依赖我） | > 0.7 | Dependency Graph |
+| `coupling (Ce)` | 传出耦合（我依赖多少） | > 0.7 | Dependency Graph |
+| `instability (I)` | 不稳定性 Ce/(Ca+Ce) | > 0.8 | Dependency Graph |
+
+### 重要性指标
+| 度量 | 解释 | 高风险阈值 | 数据来源 |
+|------|------|-----------|---------|
+| `importance` | 综合重要性评分 | > 0.8 | Weighted Metrics |
+| `betweenness_centrality` | 介数中心性（关键路由节点） | > 0.5 | Network Analysis |
+| `in_degree` | 入度（被依赖次数） | > 20 | Dependency Graph |
+| `out_degree` | 出度（依赖他人次数） | > 20 | Dependency Graph |
+
+### 质量指标
+| 度量 | 解释 | 高风险阈值 | 数据来源 |
+|------|------|-----------|---------|
+| `maintainability_index` | 可维护性指数 | < 70 | Static Analysis |
+| `technical_debt_ratio` | 技术债占比 | > 0.2 | Code Analysis |
+| `code_duplication_ratio` | 重复代码占比 | > 0.1 | Duplication Analysis |
+
+### 数据流指标
+| 度量 | 解释 | 高风险阈值 | 数据来源 |
+|------|------|-----------|---------|
+| `flow_rate` | 数据流量 | > 100 | Data Flow Analysis |
+| `schema_coupling` | 数据耦合度 | > 0.5 | Schema Analysis |
+
+## 执行步骤
+
+### 1. 解析查询条件
+```bash
+/top 10 most complex functions
+# metric=cyclomatic_complexity, direction=desc, limit=10, filter=
+
+/modules ranked by importance
+# metric=importance, direction=desc, limit=*, filter=type=module
+
+/which module has highest coupling
+# metric=coupling (Ce), direction=desc, limit=1, filter=type=module
+
+/functions with cyclomatic_complexity > 10
+# metric=cyclomatic_complexity, direction=desc, limit=*, filter=>10
+
+/show all nodes with criticality CRITICAL
+# metric=criticality, direction=desc, limit=*, filter=CRITICAL
+```
+
+### 2. 从 knowledge-graph.json 加载所有节点
+```json
+{
+  "nodes": [
+    {
+      "id": "func:UserService.createUser",
+      "label": "createUser",
+      "type": "function",
+      "importance": 0.85,
+      "cyclomatic_complexity": 8,
+      "lines_of_code": 42,
+      "maintainability_index": 75,
+      ...
+    }
+  ]
+}
+```
+
+### 3. 应用过滤条件
+- 数值过滤：`cyclomatic_complexity > 10`
+- 类型过滤：`type=module`
+- 组合过滤：`importance > 0.7 AND type=function`
+
+### 4. 按指定度量排序
+- 降序：`cyclomatic_complexity DESC`
+- 升序：`lines_of_code ASC`
+- 多级排序：`importance DESC, cyclomatic_complexity ASC`
+
+### 5. 取 top N（默认 10，最大 50）
+```
+top 10: 前 10 个结果
+top 50: 前 50 个结果
+*：全部结果（谨慎使用）
+```
+
+### 6. 生成柱状图和排序表格
+- ASCII 柱状图：终端友好
+- Mermaid 柱状图：可视化展示
+- 详细表格：完整数据展示
+
+## jq 实现
+
+Template 6 (aggregate):
+```jq
+# 应用过滤条件
+def apply_filters($metric, $filter, $node_type):
+  $nodes | map(select(
+    .type == $node_type and
+    ($metric != "" and (.[$metric] | tonumber) >= $filter)
+  ));
+end;
+
+# 按度量排序
+def sort_by_metric($metric, $direction="desc"):
+  if $direction == "desc" then
+    sort_by(.[$metric] | tonumber) | reverse
+  else
+    sort_by(.[$metric] | tonumber)
+  end;
+end;
+
+# 生成 ASCII 柱状图
+def generate_ascii_chart($nodes, $metric, $max_length=40):
+  $max_value = $nodes | map(.[$metric] | tonumber) | max;
+  $nodes | map({
+    label: (.label | sub(".+:"; "") | .[:15] + "..."),  # 截断标签
+    value: .[$metric] | tonumber,
+    bar_length: (.[ $metric] | tonumber * $max_length / $max_value | floor)
+  }) | map("[\(.label)] \(.bar_length * "█" + ($max_length - .bar_length) * " ") \(.value)");
+end;
+
+# 生成结果表格
+def generate_result_table($nodes, $metric, $title):
+  if ($nodes | length) == 0 then
+    "No results found."
+  else
+    header = ["Rank", "Label", "Type", $metric | ascii_upcase, "Risk Level"];
+    rows = $nodes | map(. as $node | [
+      $rank,
+      $node.label,
+      $node.type,
+      $node[$metric] | tostring,
+      get_risk_level($node[$metric], $metric)
+    ]);
+
+    header + [""] + rows
+  end;
+end;
+
+# 获取风险等级
+def get_risk_level($value, $metric):
+  case $metric
+  when "cyclomatic_complexity" then
+    if $value > 10 then "🔴 CRITICAL"
+    elif $value > 7 then "🟠 HIGH"
+    elif $value > 3 then "🟢 MEDIUM"
+    else "🔵 LOW" end
+  when "importance" then
+    if $value > 0.8 then "🔴 CRITICAL"
+    elif $value > 0.6 then "🟠 HIGH"
+    elif $value > 0.3 then "🟢 MEDIUM"
+    else "🔵 LOW" end
+  else "🔵 LOW"
+  end;
+end;
+```
+
+## 用户指令示例
+
+### 复杂度相关
+```bash
+# 查找最复杂的函数
+/top 20 functions by cyclomatic_complexity
+
+# 查找代码体积大的函数
+/top 10 functions by halstead_volume
+
+# 查找行数过多的函数
+/functions with lines_of_code > 200
+```
+
+### 耦合相关
+```bash
+# 查找传出耦合最高的模块
+/modules ranked by coupling (Ce)
+
+# 查找不稳定的模块
+/modules with instability > 0.8
+
+# 查找传入耦合高的模块
+/modules with coupling (Ca) > 0.7
+```
+
+### 重要性相关
+```bash
+# 查找最重要的函数/top 15 functions by importance
+# 查找枢纽节点
+/top 10 nodes by betweenness_centrality
+# 查找被依赖最多的函数
+/functions with in_degree > 10
+```
+
+### 质量相关
+```bash
+# 查找技术债占比高的
+/nodes with technical_debt_ratio > 0.3
+
+# 查找可维护性差的
+/functions with maintainability_index < 60
+
+# 查找重复代码多的
+/modules with code_duplication_ratio > 0.15
+```
+
+## 输出示例
+
+```
+## 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 |
+| 5 | ShippingService.estimateDelivery | 8 | 124 | 🟢 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
+- 🔴 CRITICAL: Refactor OrderService.processOrder (consider splitting into 3-4 functions)
+- 🔴 HIGH: Add comprehensive tests for PaymentService.validatePayment
+- 🟠 MEDIUM: Monitor AuthService.authenticate for future complexity growth
+```
+
+## 聚合查询最佳实践
+
+### 1. 分层分析
+```bash
+# 系统级：顶层模块
+/top 10 modules by importance (G1)
+
+# 模块级：内部结构
+/top 20 functions by cyclomatic_complexity (G3)
+
+# 实现级：具体代码
+/functions with technical_debt_ratio > 0.2 (G5)
+```
+
+### 2. 组合查询
+```bash
+# 高复杂度 + 高耦合
+/functions with cyclomatic_complexity > 10 AND coupling (Ce) > 0.7
+
+# 高重要性 + 低质量
+/functions with importance > 0.8 AND maintainability_index < 70
+
+# 全局质量概览
+/show quality metrics summary
+```
+
+### 3. 趋势分析
+```bash
+# 对比两个版本
+/compare v1 vs v2 (metric=cyclomatic_complexity)
+
+# 查看历史趋势
+/show trend cyclomatic_complexity (last=5)
+```
+
+## 风险等级颜色编码
+
+| 颜色 | 风险等级 | 阈值 | 行动建议 |
+|------|---------|------|---------|
+| 🔴 | CRITICAL | 最严重 | 立即重构，优先级最高 |
+| 🟠 | HIGH | 严重 | 近期处理，安排重构 |
+| 🟢 | MEDIUM | 中等 | 计划内优化，持续监控 |
+| 🔵 | LOW | 轻微 | 正常维护，无需特别关注 |
+
+## 故障排除
+
+1. **度量不存在**：某些度量需要 L2+ 分析深度，重新运行更深分析
+2. **结果为空**：检查过滤条件是否过于严格，调整参数
+3. **性能问题**：大量数据时使用 limit 限制数量
+4. **排序错误**：确认 metric 名称和排序方向是否正确