@dtt_siye/atool 1.4.0 → 1.5.0

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 名称和排序方向是否正确

package/skills/project-query/rules/data-lineage.md

@@ -0,0 +1,228 @@
+# Data Lineage - 数据血缘
+
+## 执行步骤
+
+### 1. 定位数据实体节点 D
+查找类型为 `data_entity` 的节点：
+- `Order entity` → `data_entity:Order`
+- `User data` → `data_entity:User`
+- `Payment status` → `data_entity:PaymentStatus`
+
+### 2. 反向追踪（来源 Upstream）
+沿着 `writes_to`、`writes_state` 边反向查找：
+
+```mermaid
+graph TD
+    User_Input -->|creates| OrderService.createOrder
+    User_Input -->|creates| UserService.createUser
+    OrderService.createOrder -->|writes_to| data_entity:Order
+    UserService.createUser -->|writes_to| data_entity:User
+```
+
+递归规则：
+- 从数据实体反向查找写入该实体的函数
+- 继续查找这些函数的输入来源
+- 直到找到边界节点：API、user_input、scheduled_task、config
+
+### 3. 正向追踪（去向 Downstream）
+沿着 `reads_from`、`reads_state`、`transforms` 边正向查找：
+
+```mermaid
+graph TD
+    data_entity:Order -->|reads_from| OrderService.getOrders
+    data_entity:Order -->|reads_from| OrderService.processOrder
+    data_entity:Order -->|persists_to| database:PostgreSQL
+```
+
+递归规则：
+- 从数据实体查找读取该实体的函数
+- 继续查找这些函数的输出流向
+- 直到找到汇聚点：database、external_api、log、output
+
+### 4. 计算数据流速率
+```
+flow_rate = count(writers) × count(readers) × avg_transformation_steps
+```
+
+评级：
+- `flow_rate > 100` → 🔴 HIGH ACTIVITY
+- `10 < flow_rate ≤ 100` → 🟠 MEDIUM ACTIVITY
+- `flow_rate ≤ 10` → 🟢 LOW ACTIVITY
+
+### 5. 生成 Mermaid `graph TD` 数据流图
+使用标准样式：
+- 数据节点（蓝色）：`data_entity:Order`
+- 处理函数（绿色）：`func:OrderService.createOrder`
+- 外部系统（灰色）：`api:POST/orders`
+- 每条边标注操作类型
+
+## jq 实现
+
+Template 4 (data-lineage):
+```jq
+# 查找写入者（上游）
+def find_upstream_writers(data_entity_id):
+  .edges[] | select(
+    .target == data_entity_id and
+    (.type == "writes_to" or .type == "writes_state")
+  ) | .source;
+end;
+
+# 查找读取者（下游）
+def find_downstream_readers(data_entity_id):
+  .edges[] | select(
+    .source == data_entity_id and
+    (.type == "reads_from" or .type == "reads_state")
+  ) | .target;
+end;
+
+# 生成数据流图
+def generate_data_flow_graph($data_entity_id):
+  $writers = find_upstream_writers($data_entity_id);
+  $readers = find_downstream_readers($data_entity_id);
+
+  $upstream = $writers | map({
+    id: .,
+    type: if (. | startswith("api:")) or (. | startswith("user_input:"))
+           then "source"
+           else "function" end,
+    direction: "to",
+    target: $data_entity_id
+  });
+
+  $downstream = $readers | map({
+    id: .,
+    type: if (. | endswith(":database")) or (. | endswith(":external_api"))
+           then "sink"
+           else "function" end,
+    direction: "from",
+    source: $data_entity_id
+  });
+
+  $all_nodes = ($upstream + $downstream) | .id | unique;
+
+  {
+    nodes: $all_nodes | map({
+      id: .,
+      label: .,
+      class: if startswith("data_entity:") then "dataEntity"
+              elif startswith("api:") then "api"
+              elif endswith(":database") then "database"
+              elif startswith("user_input:") then "userInput"
+              else "function" end
+    }),
+    edges: ($upstream + $downstream) | map({
+      source: .source,
+      target: .target,
+      label: .type,
+      class: .type
+    })
+  };
+end;
+
+# 计算流速率
+def calculate_flow_rate($data_entity_id):
+  $writers = find_upstream_writers($data_entity_id) | length;
+  $readers = find_downstream_readers($data_entity_id) | length;
+  $avg_steps = if $writers + $readers > 0
+               then 3  # 平均变换步骤
+               else 0 end;
+  $writers * $readers * $avg_steps;
+end;
+```
+
+## 用户指令示例
+
+```bash
+# 追踪实体流向
+/trace data lineage of Order entity
+/trace data lineage of User
+/trace data lineage of Payment status
+
+# 查看数据来源
+/where does Order data flow from
+/where does User data come from
+/trace data flow for Order creation
+```
+
+## 输出示例
+
+```
+## 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)
+```
+
+## Mermaid 图示例
+
+```mermaid
+graph TD
+    classDef dataEntity fill:#90EE90
+    classDef function fill:#98FB98
+    classDef api fill:#FFB6C1
+    classDef database fill:#87CEEB
+
+    U[user_input:POST/orders] -->|creates| F1[func:OrderService.createOrder]
+    F1 -->|writes_to| O[data_entity:Order]
+
+    O -->|reads_from| F2[func:OrderService.getOrders]
+    F2 -->|returns| API[api:GET/orders/{id}]
+
+    O -->|persists_to| DB[database:PostgreSQL]
+    F1 -->|transforms| F3[func:PaymentService.calculateTotal]
+    F1 -->|transforms| F4[func:ShippingService.estimateDelivery]
+
+    class U api
+    class O dataEntity
+    class F1,F2,F3,F4 function
+    class DB database
+    class API api
+```
+
+## 数据流类型表
+
+| 操作类型 | 边标签 | 含义 | 颜色 |
+|---------|-------|------|------|
+| `creates` | creates | 创建新数据 | #90EE90 |
+| `writes_to` | writes_to | 写入数据 | #FFB6C1 |
+| `reads_from` | reads_from | 读取数据 | #87CEEB |
+| `transforms` | transforms | 数据转换 | #FFD700 |
+| `persists_to` | persists_to | 持久化到数据库 | #DDA0DD |
+| `returns` | returns | 返回响应 | #FFA07A |
+
+## 故障排除
+
+1. **无数据流**：检查 entity 名称是否正确，使用 `/find` 确认
+2. **流向不完整**：检查分析深度是否足够（推荐 L2+）
+3. **变换步骤过多**：使用粒度缩放（G3-G4）过滤
+4. **环形引用**：可能存在设计问题，需要评审
+
+## 最佳实践
+
+1. **关键实体优先**：重点关注核心业务实体
+2. **高活跃度监控**：对 flow_rate > 50 的实体进行重点监控
+3. **变更影响评估**：修改关键实体前必须分析影响
+4. **性能优化**：高流量的实体可能是性能瓶颈