SuperAPI AI 工具集

gs-no-comments

编程与开发

查看项目

更新于 11-19 19:06

技能介绍

用途

gs-no-comments 用于对一段代码变更或一组文件执行一次激进但审慎的注释清理。它的目标不是保留注释,而是删除几乎所有注释,并把“确实需要注释”的代码识别出来,通过重构让代码本身表达清楚。

主要能力

  • 按 references/comment-sicko.md 的规则判断注释去留:哪些保留、何时标记为 MUST KILL、如何处理抑制性注释、如何报告。
  • 支持用户指定的文件或 diff;未指定时使用当前工作区相对默认分支的 diff。默认分支依次通过 git symbolic-ref --short refs/remotes/origin/HEAD、git remote show origin、main 确定。
  • 启动一个子代理执行审查,把范围和规则全文作为指令;优先使用用户指定的模型,否则使用 harness 能达到的最强模型,再否则使用会话模型。若 harness 没有子代理工具,则自行执行并说明。
  • 审查前从磁盘重新读取范围内每个文件,仅依据参考文件判断注释,不依赖会话记忆。
  • 复核子代理的报告和 diff,拒绝应用代码修改、范围越界、受异常保护的删除、MUST KILL 理由不实,以及把有意保留的代码误判为有问题的标记。
  • 审计遗漏的范围受限 lint 和 TypeScript 抑制注释;正确性或安全性相关的抑制保持为可执行的 MUST KILL。
  • 对薄弱的 IMPORTANT 或“不要删除”类判断,用 git log -L 和 git blame 追踪符号历史;历史仍不清晰且已安装 gs-why 时,请用户自行运行 /gs-why。
  • 被拒绝的报告可带失败原因重跑一次;第二次仍被拒绝则报告为未解决,并以 gs-no-comments failed 停止。

使用方式

  1. 确定范围:用户指定的文件或 diff,否则使用当前 diff(含工作区)。
  2. 启动子代理执行 Comment Sicko 规则,写出报告。
  3. 复核报告与 diff,接受或拒绝各项发现。
  4. 对接受的标记:简单问题直接修复(删除死路径、去掉参数、改用真实 API);需要新形态时先写一段简短设计草图,列出重命名、抽取函数、类型或模块边界,并说明每个改动对应哪个标记,到此为止。
  5. 实施范围内最小的根因修复,移除所有点名的工作区绕过;根因在范围外时,落地最小范围内修复并报告其余未解决。修复注释所掩盖的原因,而非其描述的症状,不添加掩盖症状的守卫。
  6. 约束类注释(不要删除、不要改措辞、改动前先联系某人):对无法改变的事项保留;其余提供范围内最省的类型、运行时检查、测试或 CI lint 方案,等待用户批准;无人批准时只固化事先获批的内容。批准后固化约束并删除注释,否则删除注释、报告约束未解决并给出范围外工作草图。
  7. 报告删除数量、恢复的注释、重跑、设计草图、修复、固化提议、已固化内容、未固化的约束及其他未完成工作。

适用场景

适用于希望大幅减少注释、推动代码自解释的代码库或变更集,尤其是注释被用来掩盖糟糕结构、死代码或临时绕过的情况。

限制

  • 规则细节以 references/comment-sicko.md 为准,不重述或弱化其规则。
  • 子代理能力取决于 harness;无子代理工具时由主会话自行执行。
  • 范围外根因不会被修复,只报告为未解决。
  • 约束固化需用户批准;无人批准时仅执行事先获批内容。
  • 该技能的收费、价格、平台支持等信息暂未提供。