SuperAPI AI 工具集

uw-grill

编程与开发

查看项目

更新于 10-30 09:34

技能介绍

用途

uw-grill 解决一个覆盖率验证无法覆盖的问题:覆盖率只能证明每个符号都被描述过,不能证明所描述的行为值得在新技术栈中复现。例如 2019 年针对第三方 bug 的临时绕过写法、硬编码的每天 8 小时工作制、缺少租户过滤的查询,都能以 100% 覆盖率通过,并被原样重建。执行重建的工程师是在阅读他人代码做考古,无法判断这些规则今天是否仍然成立,贸然询问只能得到自信的猜测。因此该技能把发现按“谁能真正回答”分流:代码库能回答的就地解决,其余写成业务语言问卷交给知情者。

前提与产物

前提:层文档覆盖率达到 100%(uw-verify → uw-complete)。产物包括:docs/unwind/questions/*.md(每个业务能力一份问卷)、docs/unwind/.cache/grill-findings.json(机器记录),以及裁决落定后重新打标签的层文档。

两轮流程

技能先检测当前处于哪一轮:若已存在问卷文件则进入第二轮(环节 E–F),否则为第一轮(环节 A–D)。第一轮依次为:确定性简报(读取约定、阈值、分层预算与热点桶、能力候选)、按依赖顺序派发分层探查子代理并确定性合并(校验证据、去重、分配稳定编号 GQ-nnnn)、按可回答方分类、生成问卷。第二轮先干跑(dry run)再应用答案,然后逐条把裁决写回层文档。

裁决如何影响重建

裁决类型包括 preserve(保留,追加确认说明)、fix-in-rebuild(标签不变,把修正后的行为写入文档正文)、drop([MUST] 改为 [DON'T] 并附强制理由行)、downgrade([MUST] 改为 [SHOULD] 并附理由)、document-first(加入 gaps.md 交给 uw-complete)、reassign(保持开放并记录负责人)。其中 fix-in-rebuild 是关键:专家答案只存在于代码库之外,必须写进层文档正文,因为 uw-build-layer 正是以正文作为规范。

安全与校验

编辑时只允许改动 [MUST]/[SHOULD]/[DON'T] 标记,锚点 id 必须逐字节保持不变;无锚点、多处匹配、docs/unwind 已有未提交改动等情况均停止并报告。修改后必须运行 verify-coverage,确认各层覆盖率百分比不变(该检查按 id 匹配、与标签无关);由于 build-graph 把 [DON'T] 计为不计覆盖,重建图统计发生变化属于预期,需明确说明。

适用场景与限制

适用于使用 Unwind 流程做代码库重建、已完成覆盖率验证并准备制定重建计划的团队。问卷放置位置有讲究:放在 docs/unwind/layers/** 下会被解析为已记录条目并虚增覆盖率,因此放在 docs/unwind/questions/ 下。技能明确禁止以下做法:把代码库能回答的问题抛给业务专家;在问题中出现 [MUST]、锚点 id 或候选 id;对未作答或双选的问题猜测裁决;无理由行就改标签;报告被简报抑制的类别。资料未说明该技能的收费、授权方式或除上述流程外的平台支持情况。