造变更影响分析 Skill：改一处代码，秒圈全仓波及面

change-impact/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
├── assets/           # 可选：图片等资源
└── skills/           # 可选：嵌套子 skill

mkdir -p .claude/skills/change-impact/{scripts,references}

.claude/skills/change-impact/
├── SKILL.md
├── scripts/
│   └── blast_radius.py
└── references/
    └── risk-rules.md

---
name: change-impact
description: 分析一次代码变更（git diff）的波及范围。当用户改了函数/类/接口后问"影响哪些地方""要重跑哪些测试""合并前风险"，或在 PR 审查、重构、删函数前做影响评估时使用。先跑脚本做确定性溯源，再补充语义层面的契约影响。
---

# 变更影响分析

## 何时触发
用户改动了代码，且表达出对"影响范围""回归风险""要跑哪些测试"的关心。

## 执行流程（严格按序）

1. 确认比对区间。若用户给了基准/目标 ref 就用它；否则脚本会自动回退到 main/master/HEAD~1。
2. 运行溯源脚本（在仓库根目录执行）：
   ```bash
   python3 "$SKILL_DIR/scripts/blast_radius.py" [base] [head]
   ```
   把 `$SKILL_DIR` 替换为本 Skill 目录的实际绝对路径。
3. 脚本输出 Markdown 报告，含三档：🔴 高风险调用方 / 🟡 必跑测试 / 🟢 待核对文档。
4. 基于报告，由你（Claude）补充脚本无法判断的部分：
   - 被改符号若被导出为公共 API，提示对外契约可能破坏。
   - 若 🔴 清单里有"核心路径"文件，提升风险定级并说明理由。
   - 若 🟡 为空，明确提示"缺乏测试覆盖，建议补充回归用例"。
5. 输出给用户：一段结论 + 必跑测试清单 + 建议核对项。

## 风险评级细则
参见 references/risk-rules.md，仅在需要解释某条定级理由时读取。

#!/usr/bin/env python3
"""blast_radius.py — 变更影响分析引擎
用法: python3 blast_radius.py [基准ref] [目标ref] [仓库根目录]
基准默认 main/master/HEAD~1(按可用性回退), 目标默认 HEAD。
输出 Markdown 报告: 🔴高风险调用方 / 🟡必跑测试 / 🟢待核对文档。
"""
import os, re, sys, subprocess

EXCLUDE_DIRS = {".git","node_modules","dist","build","vendor",
                "__pycache__",".venv",".next","target",".idea",".vscode"}
TEST_RES = [r"test_.+\.py$", r".+_test\.go$", r".+\.(test|spec)\.(ts|tsx|js|jsx)$",
            r"Test.+\.java$", r"tests?/.+\.(py|ts|js)$"]
# 多语言函数/类定义符号提取
DEF_RE = re.compile(
    r"\b(?:def|class|fn|func|function|interface|type|struct|enum|"
    r"export\s+(?:default\s+|async\s+)?function)\s+([A-Za-z_][A-Za-z0-9_]+)")
KEYWORDS = {"if","for","while","return","new","class","def","import","from",
            "const","let","var","function","func","fn","true","false","null",
            "void","this","self","async","await"}

def run(cmd):
    return subprocess.run(cmd, capture_output=True, text=True).stdout

def pick_base():
    for c in ("main","master","origin/main","origin/master","HEAD~1"):
        if subprocess.run(["git","rev-parse","--verify","--quiet",c],
                          capture_output=True).returncode == 0:
            return c
    return "HEAD~1"

def changed_symbols(base, head):
    diff = run(["git","diff","--unified=0",f"{base}..{head}"])
    syms = set()
    for line in diff.splitlines():
        if line.startswith("+") and not line.startswith("+++"):
            for s in DEF_RE.findall(line):
                if len(s) >= 2 and s not in KEYWORDS:
                    syms.add(s)
    return syms

def is_excluded(path):
    return any(p in EXCLUDE_DIRS for p in path.replace("\\","/").split("/"))

def search(symbol, repo):
    try:
        out = subprocess.run(["rg","-n","--no-heading","-w",symbol,repo],
                             capture_output=True, text=True, check=True).stdout
    except Exception:
        out = subprocess.run(["grep","-rnw",symbol,repo],
                             capture_output=True, text=True).stdout
    hits = []
    for l in out.splitlines():
        seg = l.split(":",2)
        if len(seg) < 3: continue
        path, ln, code = seg[0], seg[1], seg[2]
        if is_excluded(path): continue
        hits.append((symbol, path, ln, code.strip()))
    return hits

def kind(path):
    p = path.replace("\\","/")
    if any(re.search(r, p) for r in TEST_RES): return "test"
    if p.endswith(".md"): return "doc"
    return "src"

def main():
    repo = sys.argv[3] if len(sys.argv) > 3 else os.getcwd()
    base = sys.argv[1] if len(sys.argv) > 1 else pick_base()
    head = sys.argv[2] if len(sys.argv) > 2 else "HEAD"
    syms = changed_symbols(base, head)
    if not syms:
        print(f"## 变更影响分析 `{base}..{head}`\n\n未识别到函数/类级符号——"
              "可能仅改了函数内部实现或纯文本, 建议人工定位核心改动。")
        return
    buckets = {"src":[], "test":[], "doc":[]}
    for s in syms:
        for h in search(s, repo): buckets[kind(h[1])].append(h)
    print(f"# 变更影响分析报告\n")
    print(f"**比对** `{base}..{head}`  **改动的符号**: "
          + ", ".join(f"`{s}`" for s in sorted(syms)) + "\n")
    print(f"## 🔴 高风险调用方({len(buckets['src'])} 处)")
    for s,p,l,c in sorted(buckets['src'], key=lambda x:x[1])[:40]:
        print(f"- `{p}:{l}` 调用 `{s}` — `{c[:70]}`")
    print(f"\n## 🟡 必跑测试({len(set(x[1] for x in buckets['test']))} 个文件)")
    seen=set()
    for s,p,l,c in buckets['test']:
        if p not in seen: seen.add(p); print(f"- `{p}` 命中 `{s}`")
    if not seen: print("- 未找到直接覆盖, 建议补回归用例")
    print(f"\n## 🟢 待核对文档({len(buckets['doc'])} 处)")
    for s,p,l,c in buckets['doc'][:20]:
        print(f"- `{p}:{l}` 提到 `{s}`")
    print("\n---\n_确定性溯源由 blast_radius.py 完成; 契约/语义影响由 Claude 补充。_")

if __name__ == "__main__":
    main()

# 风险评级细则（change-impact 参考）

## 🔴 高风险（必须人工核对）
- 调用点位于 `src/api/`、`src/core/`、`internal/` 等核心路径。
- 被改符号出现在 ≥ 5 个文件的导入语句中（公共 API 特征）。
- 改动涉及函数签名（参数增删、返回类型变化）。

## 🟡 中风险（务必重跑测试）
- 存在直接覆盖的测试文件 → 必跑。
- 无覆盖但调用方 ≥ 3 → 必须先补用例再合并。

## 🟢 低风险（顺手核对）
- 仅文档/注释引用，行为不受影响。
- 调用点位于已废弃目录（`deprecated/`、`legacy/`）。

## 误报处理
- 短名符号（如 `get`、`id`）易误匹配，溯源时若某命中明显无关，可忽略并说明。

我刚改了 parseConfig 函数，帮我看看影响哪些地方，要重跑哪些测试？

git checkout -b feat/add-timeout
# 编辑 config.py，给 parse_config 加一个 timeout 参数
sed -i 's/def parse_config(path):/def parse_config(path, timeout=30):/' config.py

# 变更影响分析报告
**比对** `main..HEAD`  **改动的符号**: `parse_config`

## 🔴 高风险调用方(6 处)
- `src/cli/run.py:42` 调用 `parse_config` — `cfg = parse_config(args.file)`
- `src/api/server.py:118` 调用 `parse_config` — `conf = parse_config(p)`
- ... (共 6 处)

## 🟡 必跑测试(2 个文件)
- `tests/test_config.py` 命中 `parse_config`
- `tests/cli/test_run.py` 命中 `parse_config`

## 🟢 待核对文档(1 处)
- `docs/config.md:23` 提到 `parse_config`

flowchart TD
    A[用户: 这次改动影响哪些地方?] --> B[匹配 description 触发 Skill]
    B --> C[仅加载 SKILL.md 元数据<br/>name+description ~几十 token]
    C --> D{需要执行分析?}
    D -->|是| E[加载 SKILL.md 正文流程 ~300 token]
    E --> F[调用 scripts/blast_radius.py]
    F --> G[确定性溯源<br/>git diff + ripgrep<br/>不占 Claude 上下文]
    D -->|需解释定级| H[按需读 references/risk-rules.md]
    G --> I[Claude 解读报告<br/>补充语义/契约影响]
    H --> I
    I --> J[输出红黄绿三档影响清单]

flowchart LR
    A[git diff base..head] --> B[正则提取被改符号<br/>def/class/function...]
    B --> C[对每个符号 ripgrep 全仓溯源]
    C --> D{按文件类型分类}
    D --> E1[🔴 源码调用方]
    D --> E2[🟡 测试文件]
    D --> E3[🟢 文档引用]
    E1 --> F[结构化 Markdown 报告]
    E2 --> F
    E3 --> F
    F --> G[Claude 接管: 语义判断 + 建议]