sb-flows

sb-flows——审计的连接部分

路由列表无法证明覆盖情况；流程图需要边和持久导航来源 （侧边栏／页眉／页脚链接会出现在每个屏幕上，且页面正文扫描无法发现它们——这是审计中最常见的遗漏）。映射前请加载 references/flow-capture.md。

运行

SKILL=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
"$SKILL/scripts/extract-flows.sh"      # 1. generic first pass → .storybook/flows.json (routes + edges + navSources)
"$CORE/scripts/scaffold-wrapper.sh" --flow   # 2. AppFlowGraph + JourneyGraph (+ icons.tsx)

# 3. The app-graph the wrappers actually render (edges with ACTION labels, deep store/service
#    tracing, role lanes, component lists). Copy the reference template, ADAPT its 3 marked blocks
#    to this repo's router/nav/role-gate, then run it. It writes app-graph.json + component-pages.json.
cp "$SKILL/templates/extract-app-graph.mjs" .storybook/scripts/extract-app-graph.mjs   # then edit ADAPT-1/2/3
node .storybook/scripts/extract-app-graph.mjs

如果提取器检测到导航界面元素，请根据它打印的扫描提醒采取行动。如果它打印了 ⚠ LIKELY UNDER-EXTRACTION，则应将 flows.json 视为草稿——应用使用了脚本尚未解析的惯用写法（类似 nanostores 的遗漏）。不要相信 edgeCount：阅读它列出的未匹配调用点，找回真正的边（基于仓库本地、能感知源码的解析器优于更多正则表达式），并将通用惯用写法纳入 extract-flows.sh。完整流程：references/flow-capture.md → “提取结果少报时”。

深层边（不要止步于浅层扫描）。 从 store／service 操作（或深层嵌套的功能组件）触发的导航本身没有所属屏幕——它真正的起点是调用它的对象。 模板的 moduleOrigins 会沿导入图向上追踪到路由页面，并能感知重新导出的符号（它会跟踪 barrel：通过 store 重新导出的 service，可借助 store 的导入 token 找到）。这种追踪找回了浅层扫描漏掉的真实 switchToHotel → scheduler 边。请参阅 references/flow-capture.md → “深层边追踪”。

验证——绝不要臆造空边。 约定：每条边都必须有 file:line 来源；无法归属的内容应记录在 unresolvedEdges/dynamicCallSites 中，而不是凭空捏造。运行后，用 node -e 检查 JSON：unresolvedEdges 应数量较少，且每个原因都应属实（没有对应路由的 404、真正的动态分派等）；再抽查几条 module-trace 边，对照源码核实。请参阅 references/flow-capture.md → “验证图”。

建模

• <AppFlowGraph graph={...}>——整个应用的路由图：按角色划分泳道、带类型／颜色的边、覆盖率着色、点击跳转到 story。传入由 flows.json 派生的 AppGraph。
• <JourneyGraph journey={...}>——单个流程的旅程图（Flows/* Docs 索引）；每一步通过 storyId 链接到对应状态的 story。默认提供一条折叠的“如何添加流程”编写提示（用 hideAuthoringHint 隐藏）；“这是什么？”来源横幅默认显示（流程图是一份报告）——使用 setProvenance(false)／__SB_WB_PROVENANCE__ = false 可在所有位置隐藏，使用 hideIntro 可在单张图上强制隐藏。journey 是一段精选的叙事——某个角色穿越已捕获图谱的路径——并非 flows.json 中的字段（该文件包含 AppFlowGraph 绘制所用的路由节点和边）。
• 两者都接受可注入的 icons 属性（传入 lucide／项目图标）——不要使用 emoji（CONTEXT.md §wrapper-view-design）。
• 通过应用的 token 设置主题，而非使用固定调色板。 界面元素（面板、文本、边框、泳道条纹）读取 var(--color-foreground|surface|border-subtle|muted-foreground, <fallback>)，因此一次 .dark 切换即可让整张图在浅色↔深色之间换肤；回退值则确保在没有 token 的应用中仍能渲染。只有数据编码保持字面颜色——覆盖率圆点和每种 EdgeKind 的色调属于分类编码，而非界面元素。不要将界面元素的 var() 替换为硬编码颜色。

重要规则

• 扫描所有导航来源——flows.json.navSources[]，而不只是页面正文。
• 捕获边，而不只是路由——flows.json.edges[]。
• 探索角色——同一应用对不同角色来说是不同的图。flows.json 会为每条路由提供 access（public/user/admin，基于路径的启发式判断）和 roleSignals[]（实际的守卫）。根据守卫验证访问权限，按角色泳道布局图（node.role = route.access），并审查跨越情况：匿名用户能访问用户路由吗？用户能访问管理员路由吗？参见 flow-capture.md → “步骤 — 探索角色。”
• 以实际宽度渲染页面/流程——使用 layout: 'fullscreen'，并同时提供桌面视口和移动视图；绝不要使用窄幅居中的画布。每个已记录的状态都应有独立的全宽故事。
• 使用编号名称约定 N · label，并通过 storyId 关联（参见 flow-capture.md）。

下一步

追加一条发现，然后为每个屏幕的状态运行 sb-stories，或运行 sb-audit 检查覆盖情况。