mkdir -p .claude/skills/docstring-forge/scripts

.claude/
└── skills/
    └── docstring-forge/
        ├── SKILL.md          ← 主文件：元数据 + 操作指令
        └── scripts/
            └── analyze.py     ← 捆绑脚本：用 AST 找无注释函数

---
name: docstring-forge
description: 扫描 Python 文件中缺少 docstring 的函数与方法，并按指定风格（Google/NumPy）批量补写注释。当用户要求"补注释/补 docstring/给函数加文档/规范注释"或抱怨"这些函数没说明"时使用本 skill。
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
---

# docstring-forge

为 Python 源文件中缺失 docstring 的函数/方法批量补写注释。

## 工作流程

1. 确认目标：向用户确认要处理的文件或目录，以及希望的 docstring 风格
   （默认 Google 风格；可选 NumPy）。若无明确风格，优先沿用文件中已有 docstring 的风格。
2. 运行分析：对目标调用捆绑脚本 `scripts/analyze.py`，拿到缺注释函数清单（JSON）。
   命令形如：`python3 scripts/analyze.py <目标路径>`
   脚本路径相对于本 skill 目录。
3. 阅读上下文：用 Read 读取每个目标函数及其上下文（调用方、被调用方、类型提示），
   理解其真实行为，杜绝凭函数名臆测。
4. 生成注释：按选定风格生成 docstring，必须包含：
   - 一句话功能摘要（祈使句，首字母大写）。
   - Args：每个参数一行，含类型与含义。
   - Returns：返回值类型与含义；无返回值写 None。
   - Raises：仅当函数确实显式抛出异常时才写。
5. 落盘：用 Edit 把 docstring 插回原位，缩进与函数体对齐，绝不改动业务逻辑代码。
6. 复核：重新跑一次 analyze.py，确认无注释函数数量下降到 0（或仅剩用户确认跳过的）。

## 风格示例（Google）

def transfer(amount, src, dst):
    """从一个账户向另一个账户转账。

    Args:
        amount: 转账金额，单位元，必须为正。
        src: 源账户 ID。
        dst: 目标账户 ID。

    Returns:
        转账成功后的流水号字符串。

    Raises:
        ValueError: amount 非正数时抛出。
    """

## 禁止事项

- 不得修改函数签名、函数体、返回逻辑。
- 不得臆造参数含义；看不懂就标注"待确认"并提示用户。
- 单行函数/lambda 不强求注释。

#!/usr/bin/env python3
"""扫描 Python 文件，找出缺少 docstring 的函数与方法。"""
import ast, json, sys, pathlib

def has_docstring(node):
    """判断函数节点首条语句是否为文档字符串。"""
    body = getattr(node, "body", [])
    if not body:
        return False
    first = body[0]
    return (isinstance(first, ast.Expr)
            and isinstance(first.value, ast.Constant)
            and isinstance(first.value.value, str))

def analyze(path):
    """解析单个文件，返回缺注释函数清单。"""
    src = pathlib.Path(path).read_text(encoding="utf-8")
    tree = ast.parse(src, filename=str(path))
    missing = []
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            args = [a.arg for a in node.args.args]
            if not has_docstring(node):
                missing.append({
                    "name": node.name,
                    "lineno": node.lineno,
                    "args": args,
                    "kind": "method" if node.name.startswith("__") else "function",
                })
    return {"file": str(path), "total_funcs": sum(
        1 for n in ast.walk(tree)
        if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))),
        "missing": missing}

def main():
    """命令行入口，支持文件或目录，输出 JSON。"""
    if len(sys.argv) < 2:
        print(json.dumps({"error": "usage: analyze.py <path> [path...]"}))
        sys.exit(2)
    results = []
    for p in sys.argv[1:]:
        root = pathlib.Path(p)
        files = [root] if root.is_file() else root.rglob("*.py")
        for f in files:
            try:
                results.append(analyze(f))
            except SyntaxError as e:
                results.append({"file": str(f), "error": f"语法错误: {e}"})
    print(json.dumps(results, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

class Account:
    def __init__(self, account_id, balance=0):
        self.account_id = account_id
        self.balance = balance

    def charge(self, amount):
        if amount <= 0:
            raise ValueError("amount must be positive")
        self.balance += amount
        return self.balance


def transfer(amount, src, dst):
    src.charge(-amount)
    dst.charge(amount)
    return f"{src.account_id}->{dst.account_id}:{amount}"

class Account:
    def __init__(self, account_id, balance=0):
        """初始化一个账户。

        Args:
            account_id: 账户唯一标识。
            balance: 初始余额，单位元，默认 0。
        """
        self.account_id = account_id
        self.balance = balance

    def charge(self, amount):
        """对账户进行一笔入账或扣账。

        Args:
            amount: 金额，正数为充值，负数为扣款。

        Returns:
            操作后的账户余额。

        Raises:
            ValueError: amount 非正数时抛出（注意：扣款场景请传负值）。
        """
        if amount <= 0:
            raise ValueError("amount must be positive")
        self.balance += amount
        return self.balance

flowchart TD
    U["用户：'给 billing.py 补 docstring'"] --> M["模型读取各 Skill 的 description"]
    M -->|"命中 docstring-forge"| L["加载 SKILL.md 正文（渐进式披露）"]
    M -->|"未命中"| F["回退为普通对话"]
    L --> S1["Bash 运行 scripts/analyze.py"]
    S1 --> J["拿到缺注释函数 JSON 清单"]
    J --> S2["Read 读取函数上下文"]
    S2 --> S3["按风格生成 docstring"]
    S3 --> S4["Edit 落盘回原位"]
    S4 --> S5["复跑 analyze.py 校验 missing=0"]
    S5 --> D["报告完成 / 暴露逻辑问题"]