SuperAPI AI 工具集

uw-verify

编程与开发

查看项目

更新于 10-30 09:34

技能介绍

用途:在层级分析之后检测文档与源代码之间的差距,输出供后续技能修复的工作清单。该技能已改为确定性检查,完整性通过集合算术(manifest 减 docs)验证,而非主观的 LLM 比较;扫描器已知每一层的真实条目集合,本技能将其与文档实际内容做差集(先按锚点 id 匹配,再按名称匹配)。

输出:docs/unwind/.cache/coverage/{layer}.json 为每层覆盖报告;docs/unwind/layers/{layer}/gaps.md 为缺失条目工作清单(仅在存在缺口时生成)。

使用方式:第一步运行覆盖校验器。脚本会定位已安装的 Unwind 插件并加载核心辅助脚本,然后执行 node "$UNWIND_PLUGIN_ROOT/skills/scripts/verify-coverage.mjs" "$(pwd)"。脚本加载 docs/unwind/.cache/scan-manifest.json(真实候选集),读取各 docs/unwind/layers/{layer}/ 下的章节 .md,提取已记录条目 id(来自 <!-- id: ... --> 锚点,其次按名称模糊匹配),计算差集:missing 为源中存在但文档中没有,extra 为文档中有但扫描中不存在(标记待审查,可能为动态或过时),并写出 coverage/{layer}.json 及存在缺失层的 gaps.md 工作清单。第二步汇总:报告脚本打印的每层覆盖表(covered/total = pct%),并指向生成的 gaps.md 文件,随后交给 uw-complete 填补。

gaps.md 的输出格式包含标题、覆盖率说明、缺失条目列表,每个条目给出类型(如 table)、位置(如 src/db/schema.ts:12-34)和 Id(如 table:src/db/schema.ts:users)。uw-complete 逐字读取该文件,用锚点 id 标题格式在正确章节记录每个条目,然后删除 gaps.md。

限制与回退:当确定性核心不可用(无 Node/pnpm 或构建失败)时,退回主观比较方式:对每一层读取文档与 architecture.md 中的源入口点,手工构建两个条目列表,并将 LLM 发现的缺口以相同格式写入 docs/unwind/layers/{layer}/gaps.md;该方式更慢且不可复现,仅用于无确定性引擎时保持插件可用。

下一步:根据刚打印的覆盖表分支处理。任一层低于 100%(已写 gaps.md)则下一步为 unwind:uw-complete 补齐;所有层均为 100% 则分析完成,下一步为 unwind:uw-plan。使用 AskUserQuestion 确认:继续(推荐,缺口存在时调用 unwind:uw-complete,100% 时调用 unwind:uw-plan)或在此暂停。若用户暂停,提示恢复方式:运行 unwind:uw-complete(输入 /uw-complete)填补缺口,若覆盖率已达 100% 则运行 unwind:uw-plan。流水线为:scan → analyze → verify ✓ → complete → grill → plan → dashboard。