SuperAPI AI 工具集

docs-code-sample-standards

写作与研究

查看项目

更新于 10-16 08:44

技能介绍

用途:为开发者文档中的代码示例建立统一政策,并对现有示例库进行审计,输出按优先级排序的修复队列。

主要能力:先机械盘点全部已发布示例(文件、行号、语言、所在界面、最后提交日期),再用 ROT(冗余、过时、琐碎)做初筛;为每个示例分配执行层级(Run 可执行并断言输出、Compile-only 仅编译或类型检查、Illustrative 伪代码或片段),据此决定 CI 强制内容;按清晰度→惯用性→一致性→简洁性→可移植性→可维护性的顺序解决规则冲突;产出示例政策文档、语言层级与对等矩阵、审计报告和修复队列。

使用方式:先做范围确认与访谈,明确示例所在界面、产品类型、语言、是否已有执行机制、归属方、破坏触发因素、时间与人力约束;再盘点、ROT 初筛、分层、起草政策、设定语言层级、两轮审计(全量机械检查加分层评分)、设计验证、分配归属与治理、排序修复队列并复测。可运行 scripts/sample-audit.py <docs-dir>,支持 --format summary/json/tsv、--ext、--max-lines、--placeholder-style 等参数。

适用场景:审计文档代码示例、编写示例政策、排查多语言示例不一致、判断某片段是否应进 CI、检查示例中泄露的密钥。

限制:脚本标记仅为待确认候选而非结论;无 CI 或无人力时 Run 与 Compile-only 层级不可用;涉及计费、破坏性或第三方依赖的示例不能设为 Run;Illustrative 必须在页面显式标注;未分层示例默认按 Run 处理。具体阈值与基线需结合团队数据,资料未提供价格与平台信息。