ux-flows

ux-flows — 使用流程目录与编排

此技能是项目使用流程的事实来源，也是将流程交给 persona 的协调者。它将做什么（流程，即项目数据）与如何做（可用性走查，位于 ux-persona 技能中）分开。它与技术栈无关：没有硬编码端口／地址，每个流程都会声明自己的入口点。

流程存放位置

约定：在项目的 e2e/flows/<id>.md 中为每个流程创建一个文件，并纳入版本控制。模板：

---
id: <kebab-id>
name: <readable name>
reference: <optional: requirement / ticket>
persona: <id of e2e/personas/<persona>.md, or a bundled ux-persona persona>
entry: "<entry-point URL — typically the app's home/landing>"
preconditions:
  - <app running at the entry point>
  - <minimal data required>
design_refs:               # optional but recommended: the planned design per screen
  <screen-key>: "<Figma node URL / exported image / spec — the source of truth for that screen>"
---

## User goal
<what the person wants to achieve, in one sentence>

## Steps (each step is a UI ACTION + the expected result)
1. At the entry point (`<screen-key>`), **<UI action>** → <expected result>.
2. (`<screen-key>`) **<UI action>** → <expected result>.

## Expected result
<the final observable state that proves success>

建模规则：每个流程都从入口点（主页／落地页）开始，并描述UI 操作（点击／填写），绝不写“前往 URL X”。这样 persona 才能指出无法通过导航到达的屏幕。如果某个屏幕已有计划中的设计，请将其列入 design_refs，以便 persona 根据原型验证已编码的屏幕（设计还原度），而不只是评估其可用性。

命令（通过 $ARGUMENTS）

• 为空或 list → 列出项目的流程（id · 名称 · persona · 参考），并询问是否运行。如果目录为空或缺失，先运行 discover（见下文）——不要只报告“没有流程”。
• <flow-id> → 运行一个流程：调用 ux-persona 技能，并传入流程文件的路径。
• all → 按顺序运行所有流程（浏览器是单一资源——绝不能并行运行）：对每个流程调用 ux-persona，并等待其报告后再运行下一个。如果目录为空，先运行 discover（确认草稿），然后再运行。
• new → 协助编写一个流程：询问目标／persona／参考，发现入口点和真实的 UI 步骤（必要时探索项目的路由／屏幕），并使用上面的模板编写 e2e/flows/<id>.md。
• discover → 当尚无流程时，调查应用并初始化目录（见下文的发现）。

发现——初始化空目录

此目录约定项目使用 e2e/flows/，但项目起步时可能什么都没有。如果没有流程（或用户要求运行 discover），请自行调查应用并提出初始目录——不要让用户从头编写。这与技术栈无关；请结合现有的各种线索：

1. 梳理屏幕／路由。检查代码库中的路由器（路由定义、routes/／pages/／app/ 目录、站点地图或路由清单），列出可到达的屏幕和入口点（主页／落地页）。不同框架各不相同——应查找项目使用的路由机制，而不是预设某一种。
2. **阅读导航。**从入口点开始（在运行中的应用里，或从落地页组件中），查看实际向用户提供了哪些操作——这决定了一段旅程是可到达的，还是一个孤立屏幕。
3. 挖掘意图。利用产品／需求文档、README、路由／屏幕名称和主要 CTA，推断用户目标（例如“注册”“搜索并查看商品”“查看订单状态”“完成购买”）。一个目标对应一个流程。
4. **按 persona 分组。**为每个流程分配合适的 persona（内置 persona 或项目 persona）。不同受众（终端用户与后台／管理员）通常需要不同的 persona。
5. 起草目录。为每个目标使用模板编写一个 e2e/flows/<id>.md，并将步骤写成从入口点开始的 UI 操作。创建所需的 e2e/personas/<id>.md。
6. **运行前确认。**列出建议的流程（id · 名称 · persona · 入口 · 步骤数），供用户审核／删减／更正。发现阶段只负责提出建议；目录由用户负责。

发现过程尽力而为：如果仅凭代码无法确定某个流程的 UI 路径，请在草稿中注明假设，以便 persona 运行时（以及人工审核时）确认或否定。经过调查但尚未确认的流程，也胜过没有目录。

编排（run = 分发给对应角色）

1. **单次预检：**应用是否正在流程入口点运行？如果没有，请通过项目的运行命令启动应用，否则报告并停止。是否已播种最少量的数据？
2. 对于每个选定的流程，使用该流程文件的路径调用 ux-persona 技能。依次执行——等待收到一份报告后再执行下一个。
3. 最后，汇总：读取本轮生成的报告（e2e/usability/），并生成一份评分板——按流程列出：结论 + 各严重级别的问题数量；以及一份按优先级排序的易用性修复清单（阻塞项优先），并注明每项对应的屏幕/参考内容。

Webwright 支持的运行

如果用户要求使用 Webwright、可重放的证据、生成的浏览器脚本，或更完善的截图/操作日志，仍要将此技能用作目录编排器，并继续将每个流程分发给 ux-persona。告知 ux-persona 在该流程中使用 Webwright 作为执行后端。

不要用 Webwright 脚本替换 e2e/flows/*.md。流程定义仍是事实来源；Webwright 的 final_runs/run_<id>/ 构件是生成的 e2e/usability/<flow-id>--<date>.md 报告的辅助证据。原生 Playwright E2E 仍是持久 CI 回归测试的执行位置。

目录维护

• 出现新的用户旅程/屏幕时，创建对应的 e2e/flows/<id>.md。
• 完成易用性修复后，重新运行受影响的流程，以确认问题已消失（UX 回归）。
• e2e/usability/ 中的报告是历史记录——不要删除；每轮都会生成一份新的带日期报告。

推荐的项目布局

e2e/
  personas/<persona>.md      # reusable project personas (the persona's lens)
  flows/<id>.md              # one file per flow (the definition handed to the persona)
  usability/<id>--<date>.md  # findings reports (generated by runs)

角色也可以使用 ux-persona 技能中自带的常见角色（novice、rushed、skeptical、mobile、accessibility、power-user）。