flow-preview

流程预览

使用此技能的 scripts/generate.mjs 生成临时、自包含的预览。移动时请将整个技能文件夹放在一起。CLI 仅使用 Node 内置模块，可从任意项目根目录运行，无需 Halo 软件包或工作区配置。画布是开发工具，不是生产应用的状态。

从真实 UI 推导流程

• 阅读生产组件、使用它的组件及其状态转换。梳理与请求相关的用户入口、操作、成功、加载、验证、失败、重试和权限分支。不要为了填满网格而编造屏幕。
• 通过 props 和本地 fixture 回调适配实际的生产组件。如果它将服务器调用与渲染结合在一起，请考虑拆分出一个小型展示组件；不要维护一个外观相似的第二套 UI。
• 将 fixture 和模拟请求放在临时预览中，而不是生产环境的条件分支中。缩略图会同时挂载所有状态：渲染缩略图不得发送请求、启动实际任务或修改生产数据。使用确定性值，不要使用时间戳或随机内容。
• 如果有 Maui 技能，请用它来组合 UI。将流程专属文案和业务数据放在场景／适配器中，而不是通用画布中。
• 渲染生产 UI 时，不要添加表面标签、标题、说明面板或模拟免责声明页脚。将上下文放入节点的 note 中。只显示当前状态所需的本地模拟按钮，并使用明确的操作标签，例如“模拟授予访问权限”；不要添加“预览控件”标题。
• 地图缩略图在静止时不加边框。悬停时，在整个节点周围显示一个背景，包括标题、审核复选框和缩略图，以及它们之间的间隙。保留生产组件自身的界面。只有选中的交互式预览才使用画廊风格的点状面板，并将 UI 居中放置其中。状态标题使用不带数字前缀的纯文本；图表和大纲已能体现顺序。

生成并运行服务

在目标项目的根目录中，从已安装的技能位置运行脚本。Skills CLI 通常会将其安装到 .agents/skills/flow-preview；如果你的 Agent 使用了其他目录，请相应调整路径：

node .agents/skills/flow-preview/scripts/generate.mjs preferences-flow 4180
npm --prefix tmp/preferences-flow install --workspaces=false

参数为 <lowercase-name> [port]；默认端口为 4180。名称不能包含路径。已有预览不会被覆盖。脚本会在当前目录下创建 tmp/<name>/，而不是相对于技能目录创建。它会将画布和 Vite 辅助文件，以及 scenario.tsx、main.tsx、index.html、vite.config.mjs 和私有的 package.json 一并复制过去。生成的预览不会从此技能或 Halo 导入内容；即使移动技能，也不会影响预览。

编辑 tmp/<name>/scenario.tsx。仅在该预览中安装依赖；不要将其添加到项目工作区。导入实际应用组件时，请将 React 和 Maui 版本与该项目保持一致，并保留 Vite 辅助文件中的去重配置。在 vite.config.mjs 中，只将必需的源目录作为 sourceRoots 传给 previewConfig（路径相对于预览目录，例如 sourceRoots: ["../../packages/web/src"]）。默认允许列表仅包含预览目录；绝不要允许项目根目录或运行时工作区。即使在允许的源目录中，凭据文件、.git、.halo 和 .amp 仍会被拒绝。分享门户之前，请通过 HTTP 验证这些边界。

在 Amp orb 中，请严格遵循脚本打印的监督命令：

amp orb service start flow-preferences-flow --command 'npm --prefix tmp/preferences-flow run dev' --port 4180 --portal

分享返回的门户 URL；不要分享 localhost 或直接的 orb 主机 URL。在 orb 之外，使用 npm --prefix tmp/preferences-flow run dev。删除预览目录前，请先停止服务。在 orb 中，绝不要使用 nohup 或 shell 后台进程启动预览服务器。

描述状态

FlowScenario 和 FlowNode 从生成的 ./FlowCanvas.tsx 导出：

• 场景：稳定的 id、title、initialState 和 nodes；可选的 description、navigationLabel 和 dimensions。
• 每个节点：唯一且稳定的 id、title、action（传入的用户操作）、可选的 parent、非负 row，以及 render({ mode })。父节点必须排在子节点之前；根节点省略 parent。初始状态必须存在。如果旅程会重访某个状态，请使用单独的出现 ID，而不是创建循环。
• 列按父节点深度排列，并在垂直方向紧凑排布，不留空位。row 用于排列各节点所在列中的状态，不会预留全局泳道。即使垂直位置不同，箭头仍连接实际的父节点和子节点。
• render 返回真实的组件适配器。mode 为 thumbnail 或 preview；两者使用不同的 DOM ID。保持可见内容等效。可选的 note 仅显示在交互式预览中，不显示在缩略图标题下方。
• dimensions：previewWidth 是默认未缩放的组件宽度；nodeWidth 是缩略图宽度，nodeHeight 是其最大高度。每个节点都可以设置未缩放像素单位的 maxWidth 和 maxHeight。使用生产组件现有的宽度上限，让内容填满缩略图，而不是缩小后仍留有未使用空间。交互式 UI 填满可用宽度，但不超过该上限；其高度随内容增长，并在高度上限（默认是未缩放的缩略图高度）与可用窗格高度两者中的较小值处滚动。标题和导航应置于滚动区域之外。较短的预览会收缩至其渲染高度，包括点击目标和箭头锚点。标题行采用自然高度，而非固定高度的标题槽。使用 columnGap/rowGap 分隔分支。将最大高度设得足够大，以便显示相关内容。

画布提供层级大纲、每个缩略图上方的标题/复选框、滚动平移、缩放、动画选择/交叉淡入淡出、重置和带动画的侧边栏切换。预览的界面元素仅保留状态标题、审核复选框、重置和导航操作；不要重复显示“Interactive preview”或“Follow this flow”标题。两个侧边栏都使用 Maui 的凸起元素表面。缩略图在静止时不带包裹卡片的表面或边框。整个节点通过单个原生 CSS :hover 提供即时的 Maui 悬停背景，不使用过渡效果，不改变几何尺寸或标题颜色。标题、复选框、缩略图及其间距都应位于这个连续的悬停区域内。选择按钮在原生 :hover 时应保持透明，而不只是依赖 React Aria 延迟设置的 data-hovered，以避免 UI 上闪现首帧填充色。选中时，标题使用强调色并以半粗体显示。点击标题或缩略图可选择状态；复选框仅更改其审核状态。悬停不会选择或重置状态。后续场景和缩略图内容均不可交互；请使用交互式预览操作其中的控件。减少动态效果时，移除位移效果，同时保留交叉淡入淡出。 将选中的 UI 放在一个面板中居中，面板采用 Maui gallery 的 Panel 配方：gray-1 表面、间隔为 12px 的 gray-alpha-3 点阵、描边边框和超大圆角。地图画布也使用相同的点阵背景配方。四边使用均匀紧凑的内边距，不设置面板最小高度；面板本身的宽度上限应为 UI 宽度加内边距和边框，而不是留出更宽的两侧空白。由带内边距的面板负责滚动，而不是紧贴 UI 的包装层：保留生产组件的阴影，不要将其裁切成角标。为缩略图设置较小的溢出裁切边距以容纳阴影，同时仍限制过高的内容。保留生产 UI 自身的内边距。这是 gallery 样式，不是导入 Panel 包。将 Previous 状态和前进操作放在该面板外部，靠右对齐，并使用相同的默认按钮样式。不要添加免责声明页脚。两个侧边栏边界都支持拖动和键盘调整大小；宽度按场景保存到浏览器 localStorage。轮廓选中背景应覆盖整行，包括其审阅复选框；点击该复选框仍只会更改审阅状态。限制侧边栏宽度，为地图留出空间；在窄屏堆叠布局中隐藏调整大小手柄，但不要因此替换已保存的桌面宽度。

审阅与验证

轮廓、画布和交互式预览中的审阅复选框共享每个状态的同一个值。勾选后，只将对应缩略图变暗，并叠加带勾号的绿色圆圈。标记应始终完整可见，且不能阻止状态被选中。浏览器 localStorage 会按场景/状态存储指纹；重置、主题更改和重新加载都不会清除这些指纹。渲染内容或样式类发生变化时，只使受影响状态的指纹失效。指纹忽略生成的 ID、主题值以及临时动画变换/不透明度。它们描述的是确定性缩略图，而不是经过编辑的交互式草稿。保持场景/状态 ID 稳定；新 ID 代表新的审阅项。审阅记录仅保存在该浏览器和源站，不会与其他审阅者共享。

对于新场景，应在其 portal 中驱动所有相关状态并执行真实交互。开始浏览器操作前，如有 using-agent-browser 技能，请先使用。检查浅色、深色、窄屏布局、键盘导航、重置、审阅同步/持久化以及减少动态效果。检查截图，而不只是 DOM 断言。在 Amp orb 中，将可供审阅的最终截图/录屏保存在 .amp/in/artifacts/ 下。否则，使用项目的制品目录。临时截图放在预览的 tmp/ 文件夹中。不要将 fixture 预览视为真实后端操作成功的证明。

维护技能

随附的 assets/FlowCanvas.tsx 和 assets/previewConfig.mjs 是 CLI 复制的源文件。编辑这些文件或生成器后，从此技能所在目录运行：

npm install --workspaces=false
npm run typecheck
npm run lint
npm run format:check
npm run test:e2e

浏览器测试会将该技能复制到单独的使用方项目中，生成一个通知偏好设置流程，移除该技能副本，然后测试生成的预览。如有需要，请使用 npx playwright install chromium 安装 Playwright Chromium，或将 PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH 设置为已安装浏览器的路径。此技能不依赖仓库的 lint 或 TypeScript 配置。对技能的更改不会自动更新现有生成的预览；请创建新的预览，或有意刷新已复制的画布/辅助文件，同时保留场景 ID 和 fixtures。