sb-audit

sb-audit — 漂移调查 + 决策看板

定期关卡。调查目录，为台账播种，并指出整合候选项。

运行

SKILL=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
"$SKILL/scripts/audit-drift.sh"                 # naming drift across stories
"$SKILL/scripts/audit-archived.sh"              # L1/L2/L3 preservation surveillance (HEAVY warning)
"$CORE/scripts/find-stories-by-tag.sh" decision:pending   # stale decisions needing a nudge
"$CORE/scripts/extract-component-usage.sh"      # REFRESH real prop-usage → component-usage.json (auto, no hand-edits)
"$SKILL/scripts/audit-controls.sh" .            # Controls-panel coverage: component stories missing argTypes + manager showPanel
"$CORE/scripts/refresh-usage.sh" --docs .       # ONE-COMMAND refresh: components + tokens + routes + health JSON + re-stamp per-component usage MDX

# App flow + component lists: re-run the repo-local app-graph extractor if present, then VALIDATE it
[ -f .storybook/scripts/extract-app-graph.mjs ] && node .storybook/scripts/extract-app-graph.mjs   # refresh app-graph.json + component-pages.json
[ -f .storybook/app-graph.json ] && node -e 'const g=require("./.storybook/app-graph.json"); const by={}; for(const e of g.edges) by[e.attribution]=(by[e.attribution]||0)+1; console.log("flow edges by attribution:", by, "| unresolved:", g.unresolvedEdges.length); for (const u of g.unresolvedEdges) console.log("  UNRESOLVED", u.provenance, "→", u.to, "—", u.reason)'

执行顺序 — 不要一上来就冷启动运行全部六项。 从 audit-drift.sh 开始（成本低，可指出整合候选项）。只有当目录规模足够大时，高成本的 audit-archived.sh L1/L2/L3 扫描才值得运行 — 少于约 20 个已选故事时跳过（还没有可精简的内容）。检查覆盖率时运行 audit-controls.sh + extract-component-usage.sh；refresh-usage.sh --docs 是一体化的渲染刷新 — 最后运行，不要与它所替代的单独提取器同时运行。

单命令刷新用量。 refresh-usage.sh 会运行全部四个提取器（清单/令牌映射、组件 prop 用量、路由、设计系统健康状况 — 每个已渲染文件；参见 CONTEXT.md §STORAGE MAP），并在使用 --docs 时重新生成每个 <Name>.usage.mdx。自动文档会导入 JSON，因此之后重建 Storybook 就能反映当前实际情况，无需手动编辑。可通过三种方式触发：按脚本运行（在此运行，或直接调用某个提取器）、每次审计时运行（此步骤），或在 CI 中于 storybook build 前运行。StateGrid/StateMatrix 上的 usage prop 会读取同一份 JSON，为每个变体单元格标注真实调用点数量（已声明但未使用 → 加删除线）。

自动刷新用量（无需人工编写）。 在此重新运行 extract-component-usage.sh，可随应用变更保持 component-usage.json 最新；usage-profile.mdx 自动文档会在构建时读取该 JSON，因此下次构建 Storybook 时，“此应用中的实际用量”表格会自动更新。对于希望始终保持最新的仓库，可将同一条命令接入 CI。如果用量发生变化（某个原先为 declaredButUnused 的变体现在已发布，反之亦然），请将受影响故事的 usage:unused 标签标记为漂移发现。

决策（自问）

• 漂移 — 17 个名称都表示“空状态” → 整合候选项；1 个集群 → 噪声，忽略。
• 归档 — 如果 audit-archived.sh 标记出超过 20 个已选故事 → 精简至从 templates/design-decisions.md 播种的持久台账（$SKILL/scripts/prune-to-ledger.sh）；否则保持不变。
• 待定决策 — 过时的 decision:pending → 提醒相关方。
• 控件覆盖率 — audit-controls.sh 会标记传入 args、却既未配置 argTypes、也未禁用控件的组件故事（因此它们不会显示可用的 Controls 面板）；如果 .storybook/manager.ts 未设置 showPanel，也会发出警告。修复方法是配置 argTypes（联合类型 → select，标志 → boolean，通过 table.category 分组，隐藏不可序列化的 props），或对仅渲染故事禁用控件 — 遵循 sb-stories 中的 Controls 模式（其 without-mcp 参考资料 §13）。
• 流程 / 应用图漂移 — 上方的 validate 步骤会打印按归因分类的边以及每个 UNRESOLVED。如果 unresolvedEdges 增多，或者新条目的原因是“动态分发”/提取器无法解析的导航惯用写法，这表示有一条真实边被丢弃 — 应用新增了脚本未识别的导航模式。按照 sb-flows（flow-capture.md）中的提取不足修复流程，扩展仓库本地的 extract-app-graph.mjs，然后重新验证。绝不要接受地图在悄无声息中缩小：没有来源的边属于未解析，而非不存在。（同一份 JSON 也用于生成组件列表 — 某个组件如果失去了所有 parents/pages，则属于死组件或导入追踪问题。）

在搭建 TagGallery 时加载 references/galleries-and-tags.md；处理归档/弃用时加载 references/lifecycle-tags.md；出现精简候选项时加载 references/propagate-workflow.md；审查 AI 生成的故事时加载 references/anti-patterns.md（完整列表 — 巨型故事、内联模拟、CSF2、伪类误用）— 根据发现的问题选择，不要一次加载全部四项。

台账（由你掌控的持久记忆）

将发现追加到 .storybook/audit/findings.md（带时间戳，只追加）。仅记录规则：对于超出故事审查范围的真实生产问题（未关联的 <label>、低于 AA 级的对比度、无头模式崩溃），添加 LOG-ONLY: 标记——记录下来，继续处理，除非有人要求，否则不要改动应用代码。创建台账后，提示提交它（git add .storybook/audit/）——未提交的台账，只需一次 git clean 就会消失。

下一步

/sb-hub → 通常进行一次 sb-stories 整合审查，或为已完成探索阶段的内容执行 sb-ship。