# 读取与使用已有 UX

适用：理解、评审已有流程，以及据此做视觉方案、组件设计、开发或测试的 Agent。默认只读取；用户授权修改 UX 时，转入 [创建与修改指南](authoring-guide.md)。操作与数据格式见 [Agent 指南](agent.md)。

## 先建立可靠的理解

1. **确认项目和版本。** 读取用户指定的项目概览、当前修订、用户目标、分组和体验样例。确认当前可见环境是否能访问项目；跨环境按页面上的存储提示通过项目文件交接。不要另建空项目来代替原项目。
2. **定位相关页面。** 先按本次任务选页面 ID，再读完整“页面 JSON”和“查看关联动作、条件与前后路径”。涉及共享条件或效果时读取关联定义；按需展开完整项目，不为单页视觉任务默认读取所有内容。
3. **还原任务路径。** 把入口、前置状态、动作、条件分支、结果和恢复串起来。必要时顺着前后页面查证，并在预览中体验相关样例。体验当前页可能是独立样例，不等于已走过进入它的真实前置路径。
4. **形成可追溯的交接。** 输出已理解的路径、页面与状态清单、引用的项目修订／页面 ID、发现的问题及未定项。区分结构记录、实际体验结果和你的建议。

## 阅读时不能省略的信息

- **完整内容而非缩略图。** 总览卡片可能只展示部分内容；截图也可能只有一种状态。字段是否存在应核对完整页面与备注，不能因为卡片未显示就判定遗漏。
- **画面类型和方向。** 核对概览 `display`，应用类型在创建时确定，后续只读；同一项目统一手机、平板、桌面应用或网页，手机固定竖屏、其余固定横屏；未配置默认手机竖屏。预览缩放仅用于查看，设计尺寸见快照 metadata.viewport；低保真尺寸不等同于物理设备或正式响应式适配。
- **字段和行为。** 核对标签、必填性、默认值／示例值、校验及错误反馈、按钮条件、跳转目标、状态修改、返回后的保留规则。数据没写清楚就记为缺项，不凭常识补成已确定规则。
- **状态与变体。** 区分页面、弹窗／局部状态、体验样例和样例数据。空、加载、错误、禁用、成功等只覆盖与本次任务相关的部分；缺少关键状态时列出问题。
- **决策与未知。** 阅读页面备注中的已确认、示例假设、待确认、暂不模拟及未覆盖事项。项目描述了设计，不代表真实服务已经实现；结构检查通过也不代表 UX 已获批准。
- **来源冲突。** 优先依照用户当前确认的需求／决策与指定项目修订。需求、流程或截图冲突时列出具体差异及影响，请求关键取舍；不要用旧截图静默覆盖新流程，也不要把你的推断写回为事实。

## 如果你负责视觉方案

**从 UX 中提取结构与行为，再决定视觉表达。** 低保真的字体、颜色、灰框尺寸、占位图和连线坐标不是正式视觉规范；用户明确给出的品牌、无障碍或视觉约束仍需遵守。

交付至少能对应以下信息：

| 输入 | 视觉交付中的对应 |
| --- | --- |
| 项目修订与页面 ID | 设计页面／画板映射，说明对应版本 |
| 字段、内容层级与主要动作 | 真实标签、必要字段、信息层级与动作优先级 |
| 关键页面状态 | 相关空态、加载、错误、禁用、选中与成功变体；可复用为组件状态，不必全拆画板 |
| 跳转、返回与状态变化 | 保留行为约束；视觉稿能追溯到来源动作和分支 |
| 示例、占位与未定项 | 占位内容与正式内容分清，待确认政策保留标记 |

可以提出更好的布局、组件或动效。若建议会改变字段、步骤、必填性、动作、跳转、默认值或保存／取消规则，明确列为“UX 变更建议”，说明原因和受影响页面；得到相应授权后再改流程源。单纯的视觉设计任务不自动授权保存／覆盖 UX，也不要创建项目副本、修改状态或填补业务规则来让视觉稿显得完整。

建议交付：页面 ID → 视觉画板的映射表、复用组件及必要状态、已保留的交互约束、提出的 UX 变更和待确认问题。不要仅输出一张无法追溯页面与状态的漂亮截图。

## 如果你负责开发、测试或评审

开发：把已明确的输入、状态、动作和条件转成实现清单，缺失政策先标记。测试：根据已声明的路径提出用例与期望，不能把尚未执行的路径写成通过。评审：给出具体页面／动作、问题、用户影响和建议，区分确定错误与设计取舍。需要修改源数据时，使用创建／修改流程并检查受影响范围。

## 读取任务的完成条件

能够解释本次任务所需的页面、字段、状态和闭环；交付能追溯到项目修订及页面 ID；未知和建议没有混进已确认规则；未授权时没有更改原项目。

通用布局可包含可填写字段、下拉、单选列表／卡片网格、开关和并排操作。读取时保留 field 绑定、必填性、选择范围、onChange、组合条件、validate 和快照复制关系；不能将这些信息只画成静态文字而丢失交互语义。

## 阅读结构化界面

读取 [组件语义](components.md) 和 page.regions、presentation、嵌套 children、集合绑定。固定区／滚动区、点击对象、Tab 选中项和弹层返回关系是 UX 契约。读取 repeat 的 itemsField、selectedField、筛选排序和空态，不把样例条数当业务容量；读取 feedback 的所在区域、blocking 和恢复动作。视觉方案保留这些关系，不将弹层重画成独立页面，或把固定主操作挪进正文。后台任务 (`flow.tasks`) 与外部事件 (`flow.events`) 为系统与环境行为，通过同页状态或弹层呈现，切勿误当成用户界面控件。

## 读取行为用例

若项目含 flow.testCases，读取与当前任务相关的情境、步骤和期望。运行结果必须对应同一项目修订；用例通过说明声明路径的状态逻辑符合断言，不证明布局、真实服务、原生设备或未声明分支已验收。未声明用例也不应推断为全部通过。格式与读取入口见 [behavior-guide.md](behavior-guide.md)。