SmartEDT/.trae/skills/py-zh-commenter/SKILL.md

name	description
py-zh-commenter	为 Python 代码补充清晰的中文注释与必要 docstring。用户要求“加中文注释/解释这段代码/补齐注释/可读性提升”时调用。

Python 中文注释助手（py-zh-commenter）

目标

在不改变代码行为的前提下，为 Python 代码补充高质量的中文注释与必要的 docstring，提升可读性与可维护性。

何时调用

当用户提出以下需求时调用：

• “给这段 Python 代码加中文注释/补齐注释”
• “解释代码在做什么，希望在源码里体现”
• “帮我把关键逻辑注释清楚/写 docstring”

不适用于：

• 纯代码审查（请用 code-reviewer / pr-reviewer）
• 重构/改逻辑（除非用户明确要求）

输出原则（必须遵守）

1. 不改逻辑：仅添加注释/docstring 与必要的类型提示（仅当非常明确且不影响行为）。
2. 少而精：不写“显而易见”的注释；只解释“为什么/边界/约束/不变量/副作用/复杂算法/业务含义”。
3. 就近放置：
   • 模块：文件头 docstring（可选，描述模块职责）
   • 类/函数：docstring（参数/返回/异常/副作用/线程安全/性能）
   • 复杂分支/循环：行内注释说明意图与约束
4. 风格一致：遵循项目现有格式（注释语气、标点、缩进、是否偏好 docstring）。
5. 安全合规：不在注释中写入密钥、口令、内网地址等敏感信息；不把用户数据或隐私写进注释。
6. 避免噪音：不要对每行都加注释；避免把代码翻译成中文。

注释内容清单（优先级从高到低）

• 业务含义：字段/表/状态机/权限点的语义
• 不变量：必须满足的条件（例如“role_id 必须存在且启用”）
• 边界情况：空值/异常路径/并发/重试/超时
• 副作用：数据库写入、网络请求、文件读写、全局状态变更
• 性能：复杂度、批处理、索引依赖、潜在慢点
• 安全：鉴权、权限校验点、数据校验原因

注释模板（可直接复用）

函数 docstring（推荐）

def foo(x: int) -> int:
    \"\"\"一句话说明做什么。

    Args:
        x: 参数含义（业务语义/单位/范围）。

    Returns:
        返回值含义（单位/范围/是否可能为空）。

    Raises:
        ValueError: 触发条件说明。
    \"\"\"

复杂分支注释（示例）

# 这里做 X 的原因：……
# 约束：……（例如必须在事务内/必须先校验权限）
if cond:
    ...

执行步骤（给模型的工作流）

1. 先快速阅读：识别模块职责、关键数据结构、外部依赖（DB/HTTP/文件/线程/协程）。
2. 找“复杂点”：多层嵌套、隐藏副作用、异常处理、权限判断、数据转换。
3. 优先写 docstring：为对外接口（路由函数/服务方法/工具函数）补齐输入输出语义。
4. 补关键行注释：只在需要解释“意图/原因/约束”的地方写。
5. 自检：确保不引入代码变更、不新增导入导致 lint/test 变化。

交付格式

• 如果是仓库内改动：直接在对应 .py 文件中增加注释/docstring。
• 如果用户只要解释：给出“建议应写在源码中的注释内容”，并可选附带 patch。