Claude Code Skills 开发实战：从零造一个错误码字典 Skill

mkdir -p .claude/skills/error-code-catalog/scripts

---
name: error-code-catalog
description: 扫描代码库中散落的错误码定义，生成统一错误码字典（markdown 表格）并标记冲突、重复、缺失文案。Use when the user asks to document/list/audit error codes, build an error code catalog/dictionary, or says "错误码字典/目录", "error code catalog", "整理错误码".
allowed-tools: Bash(python3 *) Read
---

# 错误码字典生成

扫描当前仓库里的错误码定义，生成统一目录。脚本支持两种写法约定：
- **映射式**：`"10001": "用户不存在"` 或 `10001: "用户不存在"`
- **命名+尾注释**：`code = 10001 // 用户不存在`

## 步骤
1. 执行扫描：`python3 ${CLAUDE_SKILL_DIR}/scripts/scanner.py . -o docs/error-codes.md`
2. 读 `docs/error-codes.md`，向用户汇报：码总数 / 冲突数 / 重复数
3. 对"冲突"项（同一码不同文案）逐条列位置，请用户裁决保留哪个
4. 若 `$ARGUMENTS` 给了子目录，把扫描根换成该路径再扫一遍

## 红线
- 只读源码，不修改任何业务文件
- 表格按码升序；冲突单独成节并给 `文件:行`

#!/usr/bin/env python3
"""错误码字典生成器：扫描错误码定义 → 统一目录 + 标记冲突/重复/缺文案。"""
import argparse, json, re
from collections import defaultdict
from pathlib import Path

IGNORE_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv",
               "dist", "build", ".idea", ".vscode"}
INCLUDE_EXT = {".py", ".go", ".ts", ".tsx", ".js", ".jsx", ".java",
               ".kt", ".rs", ".rb", ".php", ".cs"}

# 约定 A："10001": "用户不存在"  或  10001: "用户不存在"
PAT_MAP = re.compile(r'(\d{3,6})\s*[:=]\s*["\'](.+?)["\']')
# 约定 B：code = 10001 // 用户不存在（尾注释即文案）
PAT_NAMED = re.compile(r'(?:code|err(?:or)?(?:_?code)?|status|errno)\s*[:=]\s*(\d{3,6})\b', re.I)

def iter_files(root: Path):
    for p in root.rglob("*"):
        if not p.is_file() or p.suffix.lower() not in INCLUDE_EXT:
            continue
        if any(part in IGNORE_DIRS for part in p.parts):
            continue
        yield p

def scan_file(path: Path, rel: str):
    out = []
    try:
        text = path.read_text(encoding="utf-8", errors="ignore")
    except Exception:
        return out
    for i, line in enumerate(text.splitlines(), 1):
        pairs = PAT_MAP.findall(line)
        for code, msg in pairs:
            out.append((code, msg.strip(), rel, i, "map"))
        if not pairs:  # 没匹配到映射式，再试命名+尾注释
            m = PAT_NAMED.search(line)
            if m:
                cm = re.search(r'(?:#|//|;)\s*(.+)$', line.strip())
                msg = cm.group(1).strip() if cm else "(无文案)"
                out.append((m.group(1), msg, rel, i, "named"))
    return out

def main():
    ap = argparse.ArgumentParser(description="生成错误码字典")
    ap.add_argument("path", nargs="?", default=".")
    ap.add_argument("-o", "--output")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    root = Path(args.path).resolve()
    entries = []
    for f in iter_files(root):
        entries.extend(scan_file(f, str(f.relative_to(root))))

    by_code = defaultdict(list)
    for code, msg, rel, line, kind in entries:
        by_code[code].append((msg, rel, line, kind))
    codes = sorted(by_code, key=int)

    conflicts, dups = [], []
    for code, hits in by_code.items():
        (conflicts if len({h[0] for h in hits}) > 1 else dups).append((code, hits)) if len(hits) > 1 else None

    L = ["# 错误码字典", "",
         f"> 根目录 `{root}` ｜ 码 **{len(codes)}** ｜ 定义点 **{len(entries)}** ｜ 冲突 **{len(conflicts)}** ｜ 重复 **{len(dups)}**", ""]
    L += ["| 错误码 | 文案 | 文件:行 | 类型 |", "|---|---|---|---|"]
    for code in codes:
        for msg, rel, line, kind in by_code[code]:
            L.append(f"| `{code}` | {msg} | {rel}:{line} | {kind} |")
    if conflicts:
        L += ["", "## ⚠️ 冲突（同码不同文案）", "", "| 码 | 文案 | 位置 |", "|---|---|---|"]
        for code, hits in sorted(conflicts, key=lambda x: int(x[0])):
            for msg, rel, line, _ in hits:
                L.append(f"| `{code}` | {msg} | {rel}:{line} |")
    if dups:
        L += ["", f"### 重复（{len(dups)} 个码多处定义，建议收敛）", ""]
        L.append(", ".join(f"`{c}`" for c, _ in sorted(dups, key=lambda x: int(x[0]))))
    md = "\n".join(L)

    if args.output:
        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
        Path(args.output).write_text(md, encoding="utf-8")
        print(f"✅ 已写入 {args.output}")
    print(md)
    if args.json:
        jp = Path(args.output).with_suffix(".json") if args.output else Path("catalog.json")
        data = {c: [{"msg": m, "file": r, "line": l} for m, r, l, _ in v] for c, v in by_code.items()}
        jp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
        print(f"✅ JSON 已写入 {jp}")

if __name__ == "__main__":
    main()

✅ 已写入 docs/error-codes.md
# 错误码字典
> 根目录 `/repo` ｜ 码 2 ｜ 定义点 3 ｜ 冲突 1 ｜ 重复 0

| 错误码 | 文案 | 文件:行 | 类型 |
|---|---|---|---|
| `10001` | 用户不存在 | services/user.py:12 | map |
| `10002` | 参数错误 | api/handler.go:8 | named |
| `10002` | 请求超时 | middleware/timeout.py:30 | map |

## ⚠️ 冲突（同码不同文案）
| 码 | 文案 | 位置 |
|---|---|---|
| `10002` | 参数错误 | api/handler.go:8 |
| `10002` | 请求超时 | middleware/timeout.py:30 |

## 参考资料
- 码段分配与命名规范见 [naming.md](naming.md)
- 多语言文案对照见 [i18n.md](i18n.md)

## 当前扫描结果
```!
python3 ${CLAUDE_SKILL_DIR}/scripts/scanner.py .
```