从零造一个代码复杂度热点定位 Skill

flowchart LR
    A[用户提问] --> B{扫描所有 Skill 的<br/>frontmatter description}
    B -->|关键词命中| C[加载该 Skill 的<br/>SKILL.md 正文 Level2]
    B -->|不命中| Z[Skill 保持沉默<br/>不占上下文]
    C --> D{正文是否需要<br/>确定性计算?}
    D -->|是| E[执行 scripts/xxx.js Level3]
    D -->|需要背景资料| F[打开 references/xx.md Level3]
    E --> G[把脚本输出 + 正文指令<br/>合成最终建议]
    F --> G
    G --> H[返回给用户]

mkdir -p ~/.claude/skills/complexity-hotspot/scripts
mkdir -p ~/.claude/skills/complexity-hotspot/references
cd ~/.claude/skills/complexity-hotspot

---
name: complexity-hotspot
description: 扫描 JS/TS/Python 源码，定位行数过长或嵌套过深的函数，按复杂度分数排序输出重构优先级清单。Use when the user asks to "find complex functions", "locate refactoring targets", "哪个函数最该重构", "复杂度分析", or wants to reduce a file's cognitive load before touching it.
allowed-tools: Bash, Read
---

#!/usr/bin/env node
/**
 * complexity.js — 启发式复杂度热点扫描器（零依赖）
 * 用法: node scripts/complexity.js <目录或文件> [--top 20] [--json]
 * 指标: span(函数行数) + maxDepth(最大嵌套深度) -> score = span + maxDepth*5
 */
const fs = require('fs');
const path = require('path');

const EXT = { '.js':'js','.jsx':'js','.mjs':'js','.ts':'ts','.tsx':'ts','.py':'py' };
const SKIP = /^(node_modules|\.git|dist|build|out|vendor|\.next|coverage)$/;

const argv = process.argv.slice(2);
const root = argv.find(a => !a.startsWith('--')) || '.';
const topN = (a => a ? +a.split('=')[1] : 20)(argv.find(a => a.startsWith('--top')));
const asJson = argv.includes('--json');

function walk(dir, out = []) {
  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
    const p = path.join(dir, e.name);
    if (e.isDirectory()) { if (!SKIP.test(e.name)) walk(p, out); }
    else if (EXT[path.extname(e.name)]) out.push(p);
  }
  return out;
}
const indent = ln => ln.match(/^[ \t]*/)[0].replace(/\t/g, '    ').length;
const FN = {
  py: ln => /^\s*(async\s+)?def\s+(\w+)|^class\s+(\w+)/.exec(ln),
  js: ln => /\bfunction\s+([\w$]+)|\bclass\s+(\w+)|([\w$]+)\s*\([^)]*\)\s*\{|([\w$]+)\s*[:=]\s*(async\s*)?\([^)]*\)\s*=>/.exec(ln)
};
const nameOf = m => m.slice(1).find(Boolean) || '<anon>';

function analyze(file) {
  const lang = EXT[path.extname(file)];
  const lines = fs.readFileSync(file, 'utf8').split('\n');
  const out = [];
  for (let i = 0; i < lines.length; i++) {
    const m = FN[lang](lines[i]); if (!m) continue;
    const ind = indent(lines[i]);
    let depth = 0, max = 0, span = 0, j = i, done = false;
    while (j < lines.length && span < 1000) {
      const ln = lines[j];
      for (const ch of ln) { if (ch === '{') depth++; else if (ch === '}') depth--; }
      if (lang === 'py') depth = Math.max(0, Math.floor((indent(ln) - ind) / 4));
      max = Math.max(max, depth); span++;
      if (lang === 'py' && j > i && ln.trim() && indent(ln) <= ind && !/^\s*(#|def |class |return\b)/.test(ln)) done = true;
      else if (lang !== 'py' && j > i && depth <= 0 && /[,);}]/.test(ln)) done = true;
      j++; if (done) break;
    }
    out.push({ file, name: nameOf(m), line: i + 1, span, maxDepth: max, score: span + max * 5 });
  }
  return out;
}

const files = fs.statSync(root).isDirectory() ? walk(root) : [root];
const all = files.flatMap(analyze).filter(f => f.span >= 3)
  .sort((a, b) => b.score - a.score).slice(0, topN);

if (asJson) { console.log(JSON.stringify(all, null, 2)); process.exit(0); }
console.log(`# 复杂度热点 Top ${all.length}\n`);
console.log('| # | 分数 | 行数 | 嵌套 | 函数 | 位置 |');
console.log('|---|---|---|---|---|---|');
all.forEach((f, i) => console.log(`| ${i + 1} | ${f.score} | ${f.span} | ${f.maxDepth} | \`${f.name}\` | ${f.file}:${f.line} |`));
console.log(`\n> 评分=行数+嵌套×5。建议优先重构分数>40 的函数。`);

# 代码复杂度热点定位

本 Skill 帮用户在动手重构前，先用数据看清"哪个函数最该改"。

## 工作流程

1. 确认分析目标（目录或文件）。未指定时，默认用项目根目录 `.`。
2. 执行扫描，把结果落到 JSON 方便后续引用：
   `node scripts/complexity.js <目标> --top 20 --json > /tmp/hotspots.json`
3. 再跑一次输出人类可读的 Markdown 表格，直接展示给用户。
4. 对分数 > 40 的 Top 3 函数，用 Read 打开源文件对应行，给出 1-2 句
   具体重构建议（拆分 / 提取函数 / 早返回 / 策略模式）。
5. 如需更系统的判定标准，查阅 references/refactor-checklist.md。

## 输出格式

- 先给 Markdown 热点表（分数、行数、嵌套、函数名、位置）。
- 再给"本周建议优先处理的 3 个函数"及理由。
- 不要替用户直接改代码，除非他明确说"帮我重构"。

## 边界

- 脚本是启发式，对装饰器、嵌套类可能误判，给出建议前必须 Read 核对。
- 只处理 JS/TS/Python，其他语言提示用户暂不支持。

# 重构判定清单
- 分数 0-20：健康，保持。
- 分数 21-40：可优化，关注嵌套>4 的分支。
- 分数 >40：高风险，强烈建议拆分。
- 单函数 >80 行：考虑按职责切分。
- 嵌套 >4 层：优先用早返回 / 卫语句压平。

~/.claude/skills/complexity-hotspot/
├── SKILL.md                      # frontmatter + 正文（第三、五步）
├── scripts/
│   └── complexity.js             # 确定性扫描核心（第四步）
└── references/
    └── refactor-checklist.md     # 深度判定标准（第六步）