需补全annotate.py中“文件遍历与替换逻辑”以支持--file、--dir等参数，否则脚本报错；其余步骤按文档执行即可完成符合国内规范的中文注释批量生成。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要为团队维护的Python代码库快速补全符合国内开发规范的中文注释，避免手动逐行编写耗时易漏，且不希望引入外部依赖或修改原有执行逻辑。
准备本地运行环境
确认已安装Python 3.8及以上版本，执行python --version验证。若未安装，请先从python.org下载对应系统安装包。
创建独立虚拟环境：执行python -m venv stepai_env → 激活环境（Windows用stepai_envScriptsctivate.bat，macOS/Linux用source stepai_env/bin/activate）。
安装核心工具：pip install astroid openai。注意：openai SDK需v1.0+，旧版openai包不兼容，【务必卸载旧版：pip uninstall openai -y】。
配置API密钥与项目路径
登录阶跃AI控制台，在「API密钥」页生成新密钥，复制保存到安全位置。
新建配置文件stepai_config.json，写入以下内容：
{"api_key": "sk-xxx", "base_url": "https://api.jieyue.ai/v1", "model": "step-1.5"}
将该文件放在待注释代码库的根目录下，【文件名和字段名必须完全一致，大小写敏感】。
运行注释生成脚本
在代码库根目录下新建annotate.py，粘贴以下代码：
import os, json, astroid<br>from openai import OpenAI<br><br>with open("stepai_config.json") as f:<br> cfg = json.load(f)<br>client = OpenAI(api_key=cfg["api_key"], base_url=cfg["base_url"])<br><br>def gen_comment(code_snippet):<br> resp = client.chat.completions.create(<br> model=cfg["model"],<br> messages=[{"role":"user","content":f"请为以下Python函数添加标准中文注释（按Google风格），只输出带注释的完整函数代码，不要解释、不要省略原逻辑：\n{code_snippet}"}]<br> )<br> return resp.choices[0].message.content<br><br># 此处插入文件遍历与替换逻辑（略）
这一步操作起来很简单，直接把文件拖进去就行。但注意：脚本中# 此处插入文件遍历与替换逻辑（略）不是占位符，你必须补全——否则运行会报错。
批量处理指定.py文件
方法一：单文件精准注入
打开终端，进入代码库根目录，执行：python annotate.py --file src/utils/data_loader.py。脚本会读取该文件→提取所有函数定义→调用阶跃AI接口→将返回的带注释代码覆盖原文件。
方法二：目录递归处理
执行：python annotate.py --dir src/ --exclude tests/ --inplace。其中--inplace表示直接改写源文件，【执行前务必git commit或备份原始文件】。
方法三：预览模式（推荐首次使用）
加--dry-run参数，例如：python annotate.py --dir src/ --dry-run。此时不修改任何文件，仅在终端打印每个函数将被如何注释，确认无误后再去掉该参数执行真实写入。
验证注释质量与格式合规性
第一步：用VS Code打开任意被注释的.py文件，检查函数上方是否出现三引号包裹的中文docstring，且包含Args/Returns字段。
第二步：执行pylint --disable=all --enable=missing-docstring,invalid-name src/，确认输出中不再出现C0111（缺少文档字符串）警告。
第三步：人工抽查3个含复杂参数或异常处理的函数，确认注释是否准确描述了边界条件和错误返回场景——阶跃AI对try-except块的注释容易遗漏except子句的语义，发现即需手动补全。
