用途
storybook-check 是 storybook-rsbuild 项目中的上游漂移检查技能,用于将当前上游 Storybook 源码与本地 storybook-rsbuild 对应文件进行比对,是 storybook-sync 技能的安全网。
storybook-sync 以增量方式消费上游提交流,每份报告从上一次的终点开始,每个提交只做一次性判断。错误判断是永久性的:该提交再也不会被查看,遗漏会一直隐藏,直到以用户可见的缺陷形式重新浮现。本技能针对这一结构性盲点:每次运行都对两侧当前文件内容做一次全量、无状态的扫描,不因之前的运行而跳过任何内容,因此任何漂移(包括过去同步判断错误的漂移)都会在每次运行中浮现,直到真正解决。
基本规则
- 全量扫描,不保留记忆。每次运行审计所有映射;跳过“已检查”的配对会重新引入本技能旨在捕获的故障模式。
- 先验证映射,再比对内容。两侧文件集都会变化;先修复 manifest,用过时的映射审计内容会产生虚假信心。
- 审计单元是本地包,按行为逐项判断。映射并非双向干净的 1:1:多个上游文件折叠进一个本地文件,多个上游包可能供给一个本地包(framework-react 来自 react-webpack5、react-vite 和 presets/react-webpack),部分上游文件没有直接对应物。按接收移植的本地包分组,可避免同一文件被无法互相查看发现的多个代理重复判断。
- 有意差异记录在 manifest 中,而非依赖判断。发现新的合法差异时,应在同一次变更中加入 manifest;未记录的差异与缺陷无法区分。
- local: null 条目仍需审查。无直接对应物不代表无关,需按条目的说明审查上游文件中的语义并行项。
文件
- manifest.json:文件级映射,上游路径 → 本地路径(null 加 reviewWith 表示仅审查条目),以及 intentionalDivergences(已接受的有意差异)、ignoredUpstreamFiles、localOnlyFiles。属于已提交状态,保持准确是工作流的一部分。
- scripts/check-upstream.mjs:基于共享无 blob 缓存(~/.cache/storybook-upstream/,与 storybook-sync 相同缓存)的确定性 git 管道。纯 Node,无依赖或构建步骤,用 node 运行;--help 列出所有模式。
使用方式
1. 映射维护(先包级)
运行 node <skill-dir>/scripts/check-upstream.mjs --coverage 校验 manifest:先检查内部一致性,再对照两侧现实。
- INVALID-MANIFEST:条目本身格式错误(仅审查条目缺少 reviewWith、重复上游、已有 local 的条目带 reviewWith、指向不存在的包)。
- MISSING-UPSTREAM:映射的上游文件已不存在。用
git -C ~/.cache/storybook-upstream log --follow --format='%H %s' -5 origin/next -- <path>追踪重命名并修正条目。 - UNMAPPED:新的上游文件无映射决策。为其建立映射,或加入 ignoredUpstreamFiles。新映射需要本地路径,或 local: null 加 reviewWith 指明审查它的本地包。
- MISSING-LOCAL:映射或仅本地的文件已从仓库移除。修正条目。
- UNLISTED-LOCAL:manifest 不知道的新本地文件。建立映射或加入 localOnlyFiles。
在深入单个文件前,先检查包级形态:每个上游包是否仍映射到同一本地包(按 storybook-sync 技能中的映射表)?上游的包拆分、重命名或重构会使文件映射整体失效,必须先反映到 manifest 中。解决所有 coverage 发现并提交 manifest 修复后,再进行第 2 步。
2. 漂移审计(每个本地包一个子代理)
分组由脚本计算,不要手工从 manifest 推导:运行 node <skill-dir>/scripts/check-upstream.mjs --no-fetch --groups,输出为 GROUP|UPSTREAM|LOCAL,GROUP 是拥有该移植的本地包。为每个不同 GROUP 启动一个子代理,全部放在一条消息中作为并行前台 Agent 调用。保持每组完整:映射在两个轴上都多对一收敛,只有持有整组的代理才能区分“该行为在本地位于另一个文件”与“该行为缺失”。
每个子代理的提示需包含三部分:输入(该组的 manifest 切片及说明、inintentionalDivergences 声明为不报告、如何获取上游内容 node check-upstream.mjs --no-fetch --show <path>,本地文件直接读取);方法(在整个本地包范围内逐行为比对,移植是适配的而非复制的,也不按 1:1 结构;行为只要存在于本地包中任何适当位置即视为存在,检查完整个包后才可判定缺失);输出(结论,以及每项缺失行为的上游做法、两侧证据位置、来源溯源——引入该行为的上游提交与 PR 及上游给出的理由、严重程度:high = 缺陷修复/正确性,medium = 功能/性能,low = 打磨;还要暴露看似有意但尚未进入 manifest 的差异,以及值得注意的仅本地行为)。
溯源:运行 node check-upstream.mjs --no-fetch --log <upstream-path> 列出触及某文件的近期提交,git -C ~/.cache/storybook-upstream log -S'<distinctive snippet>' --format='%H|%ai|%s' origin/next -- <path> 定位引入特定代码的提交。提交主题不含 PR 编号,需用 gh api repos/storybookjs/storybook/commits/<sha>/pulls --jq '.[0] | {number, title, body}' 从提交解析 PR。日志用于解释漂移,从不用于确立漂移——内容始终是事实依据。
3. 处置
对每项缺失发现,与用户(或按其常设指示)确定恰好一种结果:
- 移植:实现它(单独的提交/PR,引用发现溯源中的上游 PR)。
- 有意差异:在同一变更中加入该条目的 intentionalDivergences 并附理由。
- 推迟:在报告中记录阻碍项。无需其他操作:下次运行的全量扫描会自动重新浮现它。
4. 报告
将 upstream-check-report-<YYYYMMDD>.md 写入项目根目录,并在回复中总结发现,报告包含标题、生成日期、上游版本(storybookjs/storybook@next 及 origin/next 短 SHA)、审计包数量与发现数量,以及按包列出的缺失行为表格(严重程度、两侧证据、上游 PR 及理由、处置)、推迟项(含阻碍)、本次运行的映射变更。
适用场景与限制
适用于维护 storybook-rsbuild 上游移植的开发者。建议在消费一次 sync 报告后运行(以验证判断),以及定期(每月或每个上游次版本发布)运行。两个技能设计上相互独立:check 的结果永不进入 sync 的范围追踪,sync 报告也从不限定 check 的审计范围。原资料未提供托管平台、收费、价格或效果数据。