SuperAPI AI 工具集

code-upkeep

编程与开发

查看项目

更新于 10-16 07:12

技能介绍

用途

Code Upkeep 用于对 Python 项目进行代码维护审计,主要覆盖两个方面:文档字符串(docstring)和测试覆盖率。它面向已修改的源文件,帮助发现文档缺失、文档过时以及测试缺口,并可直接应用修复。

主要能力

文档字符串审计

对每个目标文件中的公共类、方法和函数检查:

  • 缺失 docstring:公共方法或函数完全没有 docstring。
  • 过时 docstring:Args、Returns 或 Raises 部分与当前函数签名不匹配。
  • 缺失 Pydantic 字段描述:公共模型中的 Field() 调用缺少 description=。

会跳过:私有方法(除非复杂)、双下划线方法、简单属性 getter、平凡的一行函数、测试函数。

测试覆盖率审计

将每个源文件映射到对应测试文件,检查:

  • 缺失测试文件:完全不存在测试文件。
  • 未测试的公共方法:源方法没有对应测试。
  • 过时测试断言:测试引用了旧签名或已移除的参数。
  • 过时 mock 夹具:mock 与当前配置或服务签名不匹配。

使用方式

第一步:确定目标文件

确定要审计的 .py 源文件:

  • 如果用户指定了文件或目录,使用这些。
  • 否则检查 git diff --name-only HEAD 和 git diff --name-only --cached,找出最近修改的 .py 文件。
  • 文档字符串审计排除测试文件;测试审计包含源文件。
  • 如果没有找到修改过的文件,询问用户要扫描哪个服务或目录。

第二步:确定范围

询问用户(或根据请求推断)要运行哪些阶段:

阶段 触发短语
文档字符串 "update docstrings"、"add docstrings"、"fix docs"
测试 "update tests"、"add tests"、"check coverage"
两者 "code upkeep"、"bring up to date",或未具体提及

第三步:文档字符串审计(若在范围内)

阅读 python/code-upkeep/references/docstring-convention.md 中的 docstring 约定。然后按上述检查项逐文件审计。

第四步:测试覆盖率审计(若在范围内)

阅读 python/code-upkeep/references/test-patterns.md 中的测试模式。然后按上述检查项逐文件审计。

第五步:呈现发现

以报告形式列出文档字符串审计和测试覆盖率审计的结果,例如:

## Code Upkeep Report

### Docstring Audit
#### worker/services/book_api_client.py
- MISSING: `create_jwt_token()` — no docstring
- STALE: `store_chapters()` — Args section missing `chapter_data` param
- FIELD: `HarvestConfig.timeout` — Field() missing description

### Test Coverage Audit
#### worker/services/book_api_client.py
- NO TEST FILE: tests/test_book_api_client.py does not exist
- Public methods needing tests:
  - `BookAPIClient.store_chapters()` — API call with retry

第六步:应用修复

  • 文档字符串:使用 Edit 工具应用修复。只修改 docstring,绝不改动实现代码。
  • 测试:按照 references/test-patterns.md 中的模式编写测试。生成后运行:
cd {service-directory} && poetry run pytest {test_file} -v

完成前修复任何失败。

规则

  • 匹配本地风格:如果服务使用不同约定,遵循它。
  • 只触碰 docstring:更新文档时绝不修改实现代码。
  • 生成后运行测试:始终执行并修复失败。
  • 不要过度 mock:直接测试纯逻辑,无需 mock。
  • 测试行为而非实现:断言结果,而非调用次数。
  • 每个测试一个断言焦点:每个测试验证一个逻辑行为。
  • 使用真实测试数据:示例数据应类似真实负载。
  • 检查 conftest.py:使用共享夹具而非重复。

适用场景

  • 在提交或合并前更新最近修改的 Python 文件的文档字符串。
  • 为新增或修改的公共方法补充测试。
  • 检查测试文件是否因签名变更而过时。
  • 审计 Pydantic 模型字段描述是否完整。

限制

  • 仅针对 Python 代码。
  • 只修改 docstring 和测试文件,不修改实现代码。
  • 需要项目使用 poetry 运行 pytest(命令中指定)。
  • 具体支持的 Python 版本、依赖要求、安装方式等暂未提供。