ux-persona

ux-persona — 以用户画像为驱动的可用性走查

你将成为一名真实用户，走完应用的一条使用流程，判断它是否易于使用——关注的不是代码是否“能运行”，而是真实用户能否独立达成目标。你需要记录每一处阻碍，并提交一份可执行的报告。适用于任何 Web 项目：所有项目特定内容（入口 URL、用户画像、步骤）都来自流程文件，而非此技能。

这些技能还会验证已编码页面是否符合规划设计（设计还原度），而不仅是抽象层面的可用性。如果流程（或某个步骤）声明了设计参考（design_ref——例如 Figma 节点 URL、导出的图片、规格说明），就要据此评判已编码页面：页面与规划设计不符，即使“能运行”，也应记录为问题。

输入（先读取流程）

• $ARGUMENTS = 流程文件的路径（约定为项目中的 e2e/flows/<id>.md）。如果为空，请列出项目中可用的流程，并询问要运行哪一个。
• 流程文件声明：用户画像、入口点（第一个 URL，通常是主页／落地页）、前置条件和步骤（每一步包含一个 UI 操作和预期结果）。
• 用户画像是你采用的视角。按以下顺序确定：
  1. 项目中的用户画像文件：e2e/personas/<persona>.md（项目特定）。
  2. 此技能自带的通用用户画像：personas/<persona>.md（相对于此 SKILL.md）——参见下文的自带用户画像。
  3. 后备方案：一名赶时间的新手用户，不会输入 URL，也不会猜测路径。

黄金规则（不可妥协）

只能通过界面进行导航。 从流程中声明的入口点开始，每一步都必须通过点击／输入可见元素来完成。绝不能输入内部路由 URL 来“跳转”到某个页面。如果只能通过输入 URL 才能到达下一步，这属于阻断级可用性问题——请记录并在此处停止流程（页面虽然存在，但用户无法到达）。直接输入 URL 会掩盖问题；不要这样做。

执行后端

默认使用当前会话中可用的浏览器自动化工具。仅当用户明确要求使用 Webwright、提供可重放证据、生成浏览器脚本或进行更严格的截图／操作日志审查时，才使用 Webwright 技能／插件作为执行后端。

使用 Webwright 时：

• 将此技能的流程文件作为事实来源。把流程的用户目标、步骤、前置条件、预期结果、用户画像视角以及任何 design_refs 转换为 Webwright 关键检查点。
• 遵守黄金规则：生成的脚本必须从流程的 entry URL 开始，并且只能通过可见的 UI 操作到达后续页面，绝不能输入内部 URL。
• 将 Webwright 的 final_runs/run_<id>/ 产物视为证据，而非长期报告。请在此技能的常规报告 e2e/usability/<flow-id>--<YYYY-MM-DD>.md 中引用相关截图／日志行。
• 如果 Webwright 在机械执行层面成功，但用户画像评估发现可发现性差、文案不清晰、缺少反馈、设计不符或数据造假，请记录为可用性问题。自动化成功不等于 UX 成功。
• 如果 Webwright 脚本可广泛用于回归测试，请建议将稳定路径移植到项目原生的 Playwright E2E 测试套件；不要将生成的 Webwright 脚本视为 CI 的事实来源。

流程

1. 前置条件。 阅读流程。确认应用可通过流程的入口点访问（如果不能，通过项目的运行命令启动应用，或报告问题并停止），并确认流程所需的最少数据已存在。
2. 打开浏览器（使用会话中可用的浏览器自动化工具）：获取标签页上下文 → 为本次演练新建一个标签页 → 导航到入口点。截取初始屏幕截图。
3. 代入角色。 对每个步骤：
   • 用第一人称、以角色身份叙述（“作为 ，我想要 。我会寻找类似……的内容。”）。
   • 截图、查看屏幕，并尝试通过 UI 执行操作（点击/填写）。
   • 保真度检查 — 如果流程/步骤声明了 design_ref，则获取规划的设计稿（Figma 节点 / 图片 / 规范）。首先从上到下列出设计稿中的每个分区、区块和组件。然后逐一对照渲染后的屏幕进行评判，并归类为：present（存在且匹配）、missing（设计稿中存在、代码中缺失）、extra（代码中存在、设计稿中没有）或 different（存在但不一致 — 布局、文案、颜色/设计令牌）。保真度结论必须来自这种逐分区枚举，绝不能依据整体印象。**绝不能默默把某个分区视为“可选”，或以“简化”为由省略：**设计稿中未实现的内容都必须作为 missing 问题明确列出。“忠实还原”是必须用逐分区清单支撑的结论，而不是主观意见。与设计稿不符的占位符/无样式屏幕，即使“能用”，也必须记为问题。
   • 数据真实性检查 — 每当屏幕向用户显示数据回显（确认信息、详情/结果页、列表、摘要）时，都要验证其反映的是真实数据：即你在流程前面实际输入的值，或后端实际返回的内容，而不是占位符、无意义文本、示例或硬编码值。精致的屏幕如果连接的是模拟/桩数据（例如“Lorem ipsum”、000000/00、固定姓名、静态日期），即使“能用”且看起来忠实于设计稿，也必须记为问题——因为系统向真实用户展示了假数据。至少将一个字段与本次演练中你先前生成的值（搜索的协议、输入的文本、上传的文件）进行交叉核对。把伪造数据当作用户数据展示，通常属于 high 严重性。设计稿中包含无意义文本是预期情况；同样的无意义文本出现在运行中的应用里，则是缺陷。
   • 根据下方标准进行评估，并记录造成问题的因素。
4. 总结。 编写报告（见 输出），并返回简短摘要。

可用性评估标准（评估每个步骤）

维度	角色会提出的问题
可发现性	我无需猜测就能找到路径吗？操作/入口是否清晰可见？
清晰度	标签、标题和说明是否清晰？我知道要填写什么吗？
反馈	系统是否对每项操作都给出确认/响应（成功、错误、加载状态）？
摩擦	步骤/字段是否过多？是否重复请求？是否要求提供我没有的信息？
错误/死路	是否出现故障或错误，或让我无路可走？
保真度	实现的屏幕是否符合规划设计（design_ref）？品牌/页眉、布局、组件、文案、颜色/设计令牌是否一致？
数据真实性	屏幕显示的是我的真实数据——我输入的值以及操作产生的真实结果——还是占位符/示例/无意义文本/硬编码数据？即使屏幕看起来忠实于设计稿，向真实用户展示模拟内容也必须记为问题。

每项问题都要标注严重性：blocker（无法完成）· high（可以完成，但摩擦很大）· medium（令人烦恼）· low（润色问题）。

输出（持久化报告）

写入 e2e/usability/<flow-id>--<YYYY-MM-DD>.md（从环境中获取日期；询问或推导，不要编造）：

# Usability — <flow name> (<flow-id>)
- **Persona:** <persona> · **Date:** <YYYY-MM-DD> · **Entry:** <flow url>
- **Verdict:** ✅ completable | ⚠️ completable with friction | ❌ blocked at "<step>"

## Walkthrough
<one line per step: what the persona did and saw>

## Findings (prioritized)
| # | Severity | Step | What happened | Suggested fix |
|---|---|---|---|---|
| 1 | blocker | ... | ... | ... |

## Key screens
<reference to the saved screenshots>

最后返回：结论 + 各严重性问题数量 + 报告路径。

内置角色

此技能在 personas/（与此文件位于同一目录）下附带一组常见、与项目无关的角色，开箱即用：novice、rushed、skeptical、mobile、accessibility、power-user。项目可以在 e2e/personas/ 下定义自己的角色（优先级更高）。角色目录请参阅 personas/README.md。

操作说明

• 不要伪造成功： 如果页面没有响应，就说“没有反馈”——这是发现的问题，不是你的失败。
• 避免反复尝试： 如果浏览器操作失败 2–3 次，就停止并报告；不要继续反复点击，也不要转到流程之外的界面。
• 使用合理的测试数据；复用前序步骤生成的值（例如，刚创建的引用 ID）。如果缺少前置条件，将其记录为发现的问题／前置条件，不要强行继续。
• 浏览器是单一共享资源——一次验证一个流程。ux-flows 技能会按顺序调用你。