---
name: "py-zh-commenter"
description: "为 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（推荐）

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

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

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

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

### 复杂分支注释（示例）

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

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

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

## 交付格式

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