SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场duck-tidy

duck-tidy

编程与开发

查看项目

更新于 10-16 04:20

技能介绍

用途

duck-tidy 用于识别并清理陈旧、过时的注释与非 CONTEXT 文档，使其不再污染后续会话、不再误导智能体与开发者。它采用“审计优先、证据支撑”的方式，默认只扫描和报告，不直接修改；需要修改时，将确认后的发现交给 duck-patch 执行。

主要能力

  • 陈旧性检测（需证据支撑）：注释与当前代码矛盾、描述已不存在的功能、或记录了仅在当前工作区添加又删除、从未合并到默认分支的行为。
  • 开发叙事检测：注释或普通文档记录了“变更如何产生”，而非持久约束、不变量、契约或行为。
  • 分类输出：stale-comment（可操作、可编辑）、development-narrative（可操作、可编辑）、superseded-doc（ADR/设计笔记已过时，仅标记不编辑）、skip（TODO 标记、准确或历史性注释、CONTEXT.md/.duck-tape 内容）。
  • 审计报告：每条发现给出位置（file:line）、类别、证据（引用一行）、建议动作（删除/改写/标记）；ADR 类发现单独分组标记为“已过时——请勿作为当前依据引用”。
  • 补丁交接：在“审计并编辑”模式下，用户选择要修复的发现后，作为有界范围交给 duck-patch，并在编辑前走执行审批流程。

使用方式

激活信号：

  • 仅审计（默认）："duck-tidy"、"stale comments audit"、"outdated docs audit"。
  • 审计并编辑："tidy and fix comments"、"clean up stale comments"。

方法步骤：

  1. 扫描范围：用户指定的路径/glob，否则为工作区文件（已跟踪+未跟踪，排除 git-ignored），并排除 CONTEXT.md、.duck-tape/ 及常见生成目录（build/、dist/、node_modules/、coverage/、target/）。若仓库生成目录不同，扫描前先问一个问题；若范围不明确，问一个问题确认是单文件/目录/工作区 diff 对比默认分支。收集范围内的代码注释、文档注释、非 CONTEXT 的 markdown。
  2. 收集陈旧证据：满足任一规则即视为陈旧——矛盾（文本与当前代码矛盾，如过时不变量、错误参数语义、旧返回类型或签名）、已移除行为（描述的功能已不存在，引用的符号/函数/特性已删除）、仅工作区增删（记录了在当前工作区添加又删除、从未合并到默认分支的行为，通过 git diff <default-branch> 验证，默认分支用 git symbolic-ref refs/remotes/origin/HEAD 解析，回退到 main；未跟踪文件用 git status --porcelain 确认）。对每个可疑项交叉引用：符号能否解析？测试是否覆盖？引用矛盾证据（file:line、符号、diff hunk）。不做“凭感觉”的陈旧判断。
  3. 分类发现（见上）。
  4. 生成审计报告（见上）。仅审计模式到此为止，只报告不编辑。
  5. 补丁交接（仅审计并编辑模式）：展示审计台账；用户选择要修复的发现；将选定编辑作为有界范围交给 duck-patch；编辑前走执行审批。

审批与范围规则（摘要）：

  • 任何改变工作区的动作都需用户批准/确认。语义变更（代码/逻辑、文档/规划、配置/schema、依赖、文件操作、变更性命令、任务委派）需完整执行审批；外观变更（仅格式/空白、非代码文本文件拼写修正）需轻量确认。
  • 审批前需提供预检信息：目标阶段（Phase 1 桩/骨架/接口、Phase 2 接线/集成、Phase 3 具体实现）、阶段适配说明、目标文件、预期行为变化、最小验证检查；按文件给出格式化 diff（已存在文件用统一 diff，不存在文件用完整内容代码块），每个 diff 块上方内联注释说明每处变更。
  • 阶段上限（默认）：Phase 1 最多 6 个文件，Phase 2 最多 4 个，Phase 3 最多 2 个。阶段内容有硬性约束（如 Phase 1 不得含完整业务逻辑、副作用流程等）。
  • 新文件引导规则：若范围引入新功能文件，首次审批必须仅为 Phase 1 桩/骨架/接口。
  • 审查疲劳触发（客观阈值）：Phase 1 单次审批 diff 超过 180 行变更（增+删）则阶段上限至少减 1 个文件（最低 1 个）；单文件超过 90 行则拆分。Phase 2 阈值 120 行/单文件 60 行；Phase 3 阈值 80 行/单文件 40 行。同一批次中审查者对超过 2 个文件请求澄清，则下一批至少减 1 个文件。
  • 阶段之间重新开启执行审批；审批后范围变化需重新确认范围。
  • 用最小可运行检查验证（构建/测试，或对变更 hunk 重新审计）。

适用场景

  • 代码库中注释与实现长期脱节，需要系统性排查。
  • 文档、注释中残留“以前是这样”“最近改过”等开发历史叙述，需要清理。
  • 工作区中临时添加又删除、未合并的行为被写入注释，需要识别。
  • 希望在修改前先获得有证据支撑的审计清单，再决定是否修复。

限制

  • 无批准不得自动编辑。
  • TODO/FIXME/HACK/XXX 标记不在范围内（由 duck-debt 负责）。
  • ADR/设计笔记仅标记不编辑。
  • CONTEXT.md 或 .duck-tape 状态不在范围内（由 duck-tape 负责）。
  • 每次删除都必须附带引用证据。
  • 上下文不完整时提出 1-3 个针对性澄清问题；证据缺失时明确陈述假设。
  • 关于收费、价格、平台支持等具体信息，资料中暂未提供。