@dtt_siye/atool 1.1.0

package/skills/code-review/rules/maintainability.md

@@ -0,0 +1,203 @@
+---
+name: maintainability
+dimension: maintainability
+weight: 0.10
+---
+
+> **栈级规范：** 代码可维护性标准和项目结构约定参考对应 `{stack}-conventions` skill。
+
+# 可维护性分析规则（SQALE 启发）
+
+本维度基于 SQALE（Software Quality Assessment based on Lifecycle Expectations）方法，评估代码的可维护性技术债务。
+
+## 1. 修复工作量估算（Remediation Effort）
+
+### 1.1 评估方法
+
+对每个代码异味（code smell），估算修复所需的分钟数：
+
+| 异味类型 | 修复工作量 | 说明 |
+|----------|-----------|------|
+| 过长函数 (>120行) | 30-60 min | 拆分为多个小函数 |
+| 过深嵌套 (>5层) | 20-45 min | 提取方法 + guard clause |
+| 高圈复杂度 (>15) | 45-90 min | 分解分支逻辑 |
+| 重复代码块 | 15-30 min/块 | 提取公共方法 |
+| 硬编码常量 | 5-10 min | 提取为配置/常量 |
+| 过长参数列表 (>8) | 10-20 min | 封装参数对象 |
+| 上帝类/模块 (>20个方法) | 60-120 min | 按职责拆分 |
+| 过长文件 (>500行) | 30-60 min | 按职责拆分文件 |
+| 紧耦合（直接依赖实现） | 20-40 min | 引入接口/依赖注入 |
+
+### 1.2 技术债务比率
+
+```
+technical_debt_ratio = total_remediation_time / estimated_development_time
+
+# 估算开发时间
+estimated_development_time = total_lines_of_code / 30  # 假设 30 行/人时
+
+# 健康评级
+ratio < 0.05  → ✅ 优秀（技术债务可控）
+ratio 0.05-0.10 → ⚠️ 一般（建议关注）
+ratio 0.10-0.20 → ❌ 较差（需计划性重构）
+ratio > 0.20  → 🔴 严重（系统性重构优先级）
+```
+
+## 2. 可维护性指数（Maintainability Index）
+
+### 2.1 计算公式
+
+基于原始 Microsoft MI 公式的简化版本：
+
+```
+MI = MAX(0, 171 - 5.2 * ln(HV) - 0.23 * CC - 16.2 * ln(LOC) + 50 * sin(sqrt(2.4 * CM)))
+
+其中:
+- HV = Halstead Volume（估算，见 2.2）
+- CC = 平均圈复杂度
+- LOC = 有效代码行数（排除空行和纯注释行）
+- CM = 注释率 (comment_lines / total_lines)
+```
+
+### 2.2 Halstead Volume 估算
+
+精确计算需要完整的词法分析，此处使用简化估算：
+
+```
+# 统计操作符（operators）
+operators = count of: +, -, *, /, =, ==, !=, <, >, <=, >=, &&, ||, !, &, |, ^, ~, <<, >>,
+                       if, else, for, while, do, switch, case, return, new, delete,
+                       ., ->, ::, [], (), {}, import, class, function, def, fn, let, const, var
+
+# 统计操作数（operands）
+operands = count of: 变量名、常量值、字符串字面量、数字字面量
+
+# 计算
+N = operators + operands                    # 程序长度
+n = unique_operators + unique_operands      # 词汇量
+HV = N * log2(n)                            # Halstead Volume
+
+# 简化估算（逐文件）
+HV ≈ (total_tokens * 1.2) * log2(unique_symbols)
+其中 total_tokens ≈ LOC * 3（平均每行约 3 个 token）
+unique_symbols ≈ sqrt(LOC) * 5（估算词汇量）
+```
+
+### 2.3 MI 健康评级
+
+| MI 值 | 等级 | 描述 |
+|--------|------|------|
+| 85-100 | 优秀 | 高度可维护，易于理解和修改 |
+| 65-85 | 良好 | 可维护性良好，局部可改进 |
+| 40-65 | 一般 | 可维护性下降，建议重构 |
+| 20-40 | 较差 | 难以维护，重构优先级高 |
+| 0-20 | 严重 | 几乎不可维护，需系统性重写 |
+
+## 3. 代码异味检测（Code Smells）
+
+### 3.1 检测项
+
+| 异味 | 严重度 | 判定标准 | 修复工作量 |
+|------|--------|----------|-----------|
+| 上帝函数 | Critical | 单个函数 >200 行或 CC >20 | 60-90 min |
+| 过长参数列表 | Warning | 函数参数 >6 个 | 15-20 min |
+| 特性嫉妒 | Warning | 函数频繁访问其他类的数据（>5 次引用其他类字段） | 20-40 min |
+| 拒绝的馈赠 | Warning | 子类未使用父类 >50% 的方法 | 30-60 min |
+| 过度耦合 | Warning | 类的直接依赖 >10 个 | 30-45 min |
+| 中间人 | Info | 类 >80% 的方法仅委托给其他类 | 20-30 min |
+| 惰性类 | Info | 类 <3 个方法且总行数 <30 行 | 10-15 min |
+| 纯数据类 | Info | 类只有字段，无行为方法（贫血模型） | 20-40 min |
+
+### 3.2 检测方法
+
+逐文件扫描，对每个类/模块执行：
+1. 统计方法数量和总行数（识别上帝类/惰性类）
+2. 检查方法体中对外部类/模块的引用次数（特性嫉妒）
+3. 统计 import/依赖数量（过度耦合）
+4. 检查类是否有业务方法或仅为数据容器（纯数据类）
+
+## 4. 模块级可维护性评估
+
+### 4.1 模块健康度矩阵
+
+对每个模块（3+ 文件的目录），生成：
+
+| 指标 | 值 | 评级 |
+|------|-----|------|
+| MI 均值 | {value} | {level} |
+| 技术债务比率 | {ratio} | {level} |
+| 总修复工作量 | {hours} 人时 | — |
+| 高风险文件数 | {count} | — |
+| 代码异味密度 | {count}/KLOC | — |
+
+### 4.2 高风险文件识别
+
+满足以下任一条件的文件标记为高风险：
+- MI < 40
+- 圈复杂度 > 20
+- 函数长度 > 200 行
+- 重复代码占比 > 30%
+- 硬编码安全敏感信息
+
+## 评分算法
+
+```
+maintainability_score = 0
+
+# 代码异味评分
+for each smell:
+    if Critical: maintainability_score += 20
+    if Warning:  maintainability_score += 8
+    if Info:     maintainability_score += 2
+
+# 技术债务比率惩罚
+debt_penalty = 0
+if debt_ratio > 0.20: debt_penalty += 30
+elif debt_ratio > 0.10: debt_penalty += 15
+elif debt_ratio > 0.05: debt_penalty += 5
+
+maintainability_score += debt_penalty
+
+# MI 偏差惩罚（MI < 65 的文件越多，惩罚越大）
+low_mi_ratio = count(MI < 65 files) / total_files
+mi_penalty = low_mi_ratio * 30
+
+maintainability_score += mi_penalty
+
+# 标准化
+normalized = min(maintainability_score / max(total_modules, 1) * 10, 100)
+```
+
+## 报告章节模板
+
+```markdown
+### 可维护性 (Score: {score}/100)
+
+**技术债务比率：** {ratio} — {level}
+**估算修复工作量：** {hours} 人时
+**MI 均值：** {mi_value}
+
+发现 {count} 个可维护性问题：
+- 上帝函数：{n} 个
+- 过长参数列表：{n} 个
+- 代码异味：{n} 个
+- 高风险文件：{n} 个
+
+#### 技术债务分析
+
+| 异味类型 | 数量 | 单项修复时间 | 总修复时间 |
+|----------|------|------------|-----------|
+| 过长函数 | {n} | 30-60 min | {total} |
+| ... | ... | ... | ... |
+| **合计** | **{total}** | — | **{hours} 人时** |
+
+#### 高风险文件
+
+| 文件 | MI | CC | 最大函数长度 | 风险因素 |
+|------|-----|-----|------------|---------|
+| ... | ... | ... | ... | ... |
+
+**重构优先级建议：**
+1. {最高 ROI 的重构项（修复工作量低但改善最大的）}
+2. {第二优先重构项}
+```

package/skills/code-review/rules/quality.md

@@ -0,0 +1,158 @@
+---
+name: code-quality
+dimension: quality
+weight: 0.15
+---
+
+> **栈级规范：** 如需更详细的命名约定、代码风格标准，参考对应 `{stack}-conventions` skill。
+
+# 代码质量分析规则
+
+## 检测维度
+
+### 1. 圈复杂度 (Cyclomatic Complexity)
+
+**阈值：**
+- Critical: >15（函数包含过多分支，难以测试和维护）
+- Warning: >10（函数较复杂，建议拆分）
+- Info: >6（可考虑简化）
+
+**检测方法：**
+逐函数/方法扫描，统计以下结构数量：
+- `if`/`elif`/`else` 分支
+- `for`/`while`/`do-while` 循环
+- `case`/`switch` 分支（含 `default`）
+- `&&`/`||`/`and`/`or` 逻辑运算符
+- `?.`/`??`/`?.()` 空值链式操作
+- `try`/`catch` 异常路径
+- 嵌套的三元运算符
+
+**输出格式：**
+```
+| Severity | File | Line | Function | Complexity | Suggestion |
+|----------|------|------|----------|------------|------------|
+| Critical | src/auth.rs | 89 | process_login | 23 | 拆分为 validate_input() + authenticate() + create_session() |
+```
+
+### 2. 函数长度 (Function Length)
+
+**阈值：**
+- Critical: >120行（极长函数，几乎不可能正确理解）
+- Warning: >40行（函数做了太多事情）
+- Info: >25行（可考虑精简）
+
+**检测方法：**
+统计每个函数/方法从声明到结束的行数。排除空行和纯注释行后计数。
+
+**特殊情况处理：**
+- Rust `impl` 块中的方法：按方法边界计数
+- JavaScript/TypeScript 箭头函数：`const fn = () => { ... }` 到闭合 `};`
+- Python 装饰器方法：从 `def` 行到下一个同缩进级别的 `def` 或文件末尾
+- Java 匿名类/lambda：如果超过 20 行，标记为 Warning
+
+### 3. 嵌套深度 (Nesting Depth)
+
+**阈值：**
+- Critical: >5层（深度嵌套，逻辑极难追踪）
+- Warning: >3层（建议使用 guard clause 或 early return）
+- Info: >2层
+
+**检测方法：**
+追踪缩进层级或大括号嵌套。每进入一个 `if`/`for`/`while`/`switch`/`try`/`match` 块深度+1。
+
+### 4. 注释率 (Comment Ratio)
+
+**阈值（按文件计算）：**
+- Critical: <3%（几乎无注释，维护者无法理解设计意图）
+- Warning: <10%（关键逻辑缺少注释）
+- Info: <15%
+
+**检测方法：**
+```
+comment_ratio = (注释行数 / 总有效行数) * 100
+```
+
+排除空行后计算。以下算作注释：
+- `//` 和 `/* */` (C-style)
+- `#` (Python/Ruby/Shell)
+- `///` 和 `//!` (Rust doc comments)
+- `--` (SQL/Haskell)
+- JSDoc/TSDoc `/** */`
+
+以下不算注释：
+- 被注释掉的代码（以 `//` 开头后紧跟变量声明、函数调用等代码特征）
+
+### 5. 参数数量 (Parameter Count)
+
+**阈值：**
+- Critical: >8个（函数签名过长，应使用配置对象/结构体）
+- Warning: >5个（建议封装为参数对象）
+- Info: >3个
+
+**检测方法：**
+统计函数声明的参数数量。排除 `self`/`this`。
+
+### 6. Halstead Volume 估算（新增）
+
+**说明：**
+v3.0 新增维度。与 `maintainability.md` 的 MI 计算配合使用。此处的估算值会被 `maintainability.md` 引用。
+
+**简化估算方法（精确计算需要完整词法分析）：**
+
+```
+# 操作符（operators）
+operators = count of: +, -, *, /, =, ==, !=, <, >, <=, >=, &&, ||, !, &, |, ^,
+                       ., ->, ::, [], (), {}, if, else, for, while, switch, return, new, class, function
+
+# 操作数（operands）
+operands = count of: 变量名、常量值、字符串字面量、数字字面量
+
+# Halstead Volume
+HV = (operators + operands) * log2(unique_operators + unique_operands)
+
+# 简化估算（逐文件，无需精确词法分析）
+# 假设：平均每行约 3 个 token，词汇量 ≈ sqrt(LOC) * 5
+HV_approx = (LOC * 3) * log2(max(sqrt(LOC) * 5, 2))
+
+# 阈值
+HV > 10000 → Critical（文件过于复杂）
+HV > 5000  → Warning（文件较复杂）
+HV > 2000  → Info（可考虑简化）
+```
+
+**输出格式：**
+```
+| Severity | File | HV | CC | MI | Suggestion |
+|----------|------|-----|-----|-----|------------|
+| Critical | report-generator.ts | 12500 | 18 | 31 | 拆分为多个模块 |
+```
+
+## 评分算法```
+quality_score = 0
+
+for each issue:
+    if Critical: quality_score += 15
+    if Warning:  quality_score += 5
+    if Info:     quality_score += 1
+
+normalized = min(quality_score / (total_functions * 2) * 100, 100)
+```
+
+## 报告章节模板
+
+```markdown
+### 代码质量 (Score: {score}/100)
+
+发现 {count} 个代码质量问题：
+- 圈复杂度超标：{n} 个函数
+- 过长函数：{n} 个函数
+- 嵌套过深：{n} 处
+- 注释不足：{n} 个文件
+- 参数过多：{n} 个函数
+
+{issue_table}
+
+**优先修复建议：**
+1. {top_critical_issue}
+2. {second_critical_issue}
+```

package/skills/devops-conventions/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: devops-conventions
+description: Docker/Kubernetes/Terraform/CI-CD DevOps conventions and best practices
+version: 1.0.0
+---
+
+# DevOps Conventions
+
+Use this skill when working on DevOps, infrastructure, or CI/CD projects.
+
+## When to Use
+- Detected DevOps project (Dockerfile, docker-compose.yml, *.tf, Chart.yaml)
+- User asks about Docker, K8s, Terraform, or CI-CD best practices
+- Writing or reviewing infrastructure code
+
+## Docker
+
+### Dockerfile Best Practices
+```dockerfile
+# Multi-stage build
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o myapp ./cmd/myapp
+
+FROM alpine:3.19
+RUN apk --no-cache add ca-certificates
+COPY --from=builder /app/myapp /usr/local/bin/myapp
+ENTRYPOINT ["myapp"]
+```
+
+### Rules
+- Pin base image versions (never use `latest`)
+- Use multi-stage builds to minimize image size
+- Use `.dockerignore` to exclude unnecessary files
+- Run as non-root user (`USER appuser`)
+- Combine `RUN` commands to reduce layers
+- Use health checks (`HEALTHCHECK`)
+- Order instructions from least to most frequently changing
+
+### Docker Compose
+```yaml
+version: "3.9"
+services:
+  app:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      - DB_HOST=db
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_PASSWORD: secret
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+```
+
+## Kubernetes
+
+### Resource Manifest Structure
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myapp
+  labels:
+    app: myapp
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: myapp
+  template:
+    metadata:
+      labels:
+        app: myapp
+    spec:
+      containers:
+        - name: myapp
+          image: myapp:1.0.0
+          ports:
+            - containerPort: 8080
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "250m"
+            limits:
+              memory: "256Mi"
+              cpu: "500m"
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 8080
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: 8080
+```
+
+### Best Practices
+- Always define resource limits and requests
+- Use ConfigMaps for configuration, Secrets for sensitive data
+- Implement liveness and readiness probes
+- Use NetworkPolicies for security
+- Use anti-affinity rules for high availability
+- Horizontal Pod Autoscaler (HPA) for scaling
+
+## Terraform
+
+### Module Structure
+```
+terraform/
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── providers.tf
+├── modules/
+│   ├── vpc/
+│   └── ecs/
+└── environments/
+    ├── dev/
+    │   ├── main.tf
+    │   └── terraform.tfvars
+    ├── staging/
+    └── prod/
+```
+
+### Best Practices
+```hcl
+# Pin provider versions
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+# Use variables for environment-specific values
+variable "environment" {
+  type        = string
+  description = "Deployment environment"
+}
+
+# Use modules for reusability
+module "vpc" {
+  source = "./modules/vpc"
+  cidr   = var.vpc_cidr
+}
+```
+
+### Rules
+- Pin provider versions
+- Use remote state with locking (S3 + DynamoDB)
+- Separate environments
+- Run `terraform plan` before `terraform apply`
+- Use `tflint` for linting
+- Name resources consistently
+
+## CI/CD
+
+### GitHub Actions
+```yaml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+      - run: go test ./...
+      - run: golangci-lint run
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t myapp:${{ github.sha }} .
+```
+
+### Best Practices
+- Pipeline as code (never manual)
+- Test before build, build before deploy
+- Use immutable artifacts
+- Implement rollback strategy
+- Separate build and deploy stages
+- Cache dependencies between runs
+- Use secrets management (never hardcode)