mcpField
A
api-review

api-review

github.com/athola测试与质量343105 次安装4 天前更新
代码仓库

关于 api-review

api-review 是一项用于审查公共 API 变更、设计新接口和检查文档完整性的工作流技能，适合在 API 发布前进行系统审计。它结合接口盘点、范例研究、一致性检查和可验证的证据记录形成审查结论。

主要功能

  1. 01盘点公共 API
  2. 02研究语言范例
  3. 03审查接口一致性
  4. 04检查文档与版本治理
  5. 05记录并验证审查发现

适用场景

  1. 01发布前审查公共 API 变更
  2. 02设计新 API 表面
  3. 03检查 API 命名与错误处理一致性
  4. 04发现文档及迁移说明缺漏

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/athola/claude-night-market --skill api-review

安装后在 Claude Code 中输入/api-review确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

modules/
consistency-audit.md
exemplar-research.md
surface-inventory.md

详细介绍

API 评审工作流

不要使用的情况

  • 稳定接口背后的内部重构（使用 pensive:code-refinement）
  • 耦合和分层问题（使用 pensive:architecture-review）

用法

使用此技能评审公共 API 变更、设计新接口、审查一致性并验证文档完整性。在发布任何 API 之前运行此技能，以确认其符合项目指南。

必需的进度跟踪

  1. api-review:surface-inventory
  2. api-review:exemplar-research
  3. api-review:consistency-audit
  4. api-review:docs-governance
  5. api-review:evidence-log
  6. api-review:findings-verified

工作流

第 1 步：接口清单

按语言列出所有公共 API。记录稳定性级别、功能标志和版本元数据。使用 rg 等工具查找公共符号（例如 Rust 中的 pub 或 Python 中不带下划线的 def）。开始前使用 git status 确认工作树状态。

第 2 步：范例调研

为相关语言至少找出两个高质量的 API 参考，例如 pandas、requests 或 tokio。记录它们在命名空间、分页、错误处理和结构方面的模式，作为审查基准。

第 3 步：一致性审查

将项目的 API 与已确定的范例模式进行比较。分析命名约定、参数顺序、返回类型和错误语义。找出重复、泄漏的抽象、缺失的功能门控和文档缺漏。

第 4 步：文档治理

验证文档是否包含入口、快速入门和完整的 API 参考。确认变更日志和迁移说明均有维护。检查是否符合 SemVer、是否明确稳定性承诺，以及弃用时间表是否清晰。确认文档是否使用 rustdoc、Sphinx 或 OpenAPI 等工具自动生成。

第 5 步：证据日志

记录所有已执行的命令和发现。将最终建议概括为“批准”“批准并采取行动”或“阻止”。列出具体行动项，并注明负责人和截止日期。

API 质量检查清单

命名

确认命名约定一致、描述清晰，并遵循特定语言的惯用方式。

参数

验证参数顺序一致，并确保可选参数有明确的默认值。检查类型注解是否完整。

返回值

分析返回模式是否一致。确认错误情况均有文档说明，且分页遵循统一结构。

文档

验证所有公共 API 都包含用法示例，且变更日志反映了当前变更。

输出格式

最终报告必须包含 API 接口概述、端点和公共类型的数量清单，以及与调研所得范例的对齐分析。使用精确的文件和行号引用记录一致性问题和文档缺漏。最后给出明确的决定和有时间安排的行动计划。

每个问题必须遵循以下结构：

[A1] Title
- Location: file.py:42
- Anchor: `verbatim source text at line 42`
- Issue: what is wrong | Fix: remediation | Evidence: [E1]

Anchor 是 Location 处的确切源文本，也是 citation_verifier.py 会重新读取以证明该发现属实的文本。

技术集成

使用 imbue:proof-of-work 进行可复现的命令捕获，并使用 imbue:structured-output 格式化发现。评估破坏性变更时，参考 imbue:diff-analysis/modules/risk-assessment-framework。

模块参考

  • 有关 API 编目模式，请参阅 modules/surface-inventory.md
  • 有关 API 标准调研，请参阅 modules/exemplar-research.md
  • 有关跨 API 一致性检查，请参阅 modules/consistency-audit.md
验证发现有据可依（api-review:findings-verified）

将发现写入 .review/findings.json，运行引用验证器 （Skill(imbue:review-core) 第 5 步），并删除验证器驳回的发现，或将其标记为 UNVERIFIED。

退出标准

  • 已盘点表面内容、研究范例、审查一致性、检查文档治理，并记录证据。
  • 每条已报告的发现都包含经 citation_verifier.py 确认（退出码为 0）的 Location + 原文 Anchor；或者，未验证的发现已被删除或标记为 UNVERIFIED。

故障排查

如果找不到审核命令，请确认依赖项已安装，且可通过系统 PATH 访问。若出现访问错误，请检查文件权限。如果工具行为异常，请使用 --verbose 标志查看执行日志。

评论

支持 Markdown