SuperAPI AI 工具集

api-review

编程与开发

查看项目

更新于 10-15 17:20

技能介绍

用途:审查公开 API 变更、设计新 API 表面、审计一致性并验证文档完整性,建议在任何 API 发布前运行,以确认符合项目规范。不适用于稳定表面背后的内部重构(改用 pensive:code-refinement),也不适用于耦合与分层问题(改用 pensive:architecture-review)。

主要能力与流程:技能按六个进度节点推进——surface-inventory、exemplar-research、consistency-audit、docs-governance、evidence-log、findings-verified。第一步按语言清点所有公开 API,记录稳定性级别、功能开关与版本元数据,可用 rg 查找公开符号(如 Rust 的 pub、Python 的非下划线 def),开始前用 git status 确认工作树状态。第二步为相关语言找出至少两个高质量 API 参考(如 pandas、requests、tokio),记录其命名空间、分页、错误处理与结构模式作为基线。第三步对照范例模式比较命名约定、参数顺序、返回类型与错误语义,识别重复、泄漏抽象、缺失功能门与文档缺口。第四步验证文档是否包含入口点、快速上手与完整 API 参考,检查变更日志与迁移说明、SemVer 合规、稳定性承诺与弃用时间线,并确认文档由 rustdoc、Sphinx 或 OpenAPI 等工具自动生成。第五步记录所有执行命令与发现,给出 Approve、Approve with actions 或 Block 的最终建议,并附负责人与截止日期的行动项。

输出与验证:最终报告需包含 API 表面摘要、端点与公开类型的数量清单、与范例的对齐分析,并以精确文件与行号记录一致性问题与文档缺口。每条问题采用 [A1] 标题、Location、Anchor(该行逐字源文本)、Issue、Fix、Evidence 的结构;Anchor 是 citation_verifier.py 重新读取以证明发现真实存在的依据。发现写入 .review/findings.json,运行引用验证器(Skill(imbue:review-core) Step 5),被拒绝的发现需丢弃或标记 UNVERIFIED。退出标准为表面已清点、范例已研究、一致性已审计、文档治理已检查、证据已记录,且每条发现都带有经 citation_verifier.py 确认(exit 0)的 Location 与逐字 Anchor。

集成与限制:可配合 imbue:proof-of-work 做可复现命令捕获、imbue:structured-output 格式化发现,评估破坏性变更时参考 imbue:diff-analysis/modules/risk-assessment-framework。模块参考见 modules/surface-inventory.md、modules/exemplar-research.md、modules/consistency-audit.md。若审计命令缺失,需确认依赖已安装且在系统 PATH 中;出现访问错误时检查文件权限;工具行为异常时用 --verbose 查看执行日志。