# Agent 原生视觉设计与实现

有界面影响的新应用、页面或改版，由当前 AI Agent 在同一个 OpenXiangda 工作区内完成
视觉方向、真实页面实现、浏览器走查和修正。按需使用用户指定或当前可用的图片生成能力
（例如 Image 2.5）输出少量设计参考；不安装或调用独立设计运行时，也不在图片与实现之间
建立第二个项目状态。纯后端或无视觉影响的文字修正沿用已有设计。

图片只回答构图、层次、色彩、材质和氛围等视觉问题。AppSpec 继续定义用户、任务、页面、
字段、权限、状态和验收；真实 React 页面才是最终界面事实。静态图不能证明加载、失败、
拒绝、校验、提交、未保存输入、键盘、响应式或业务权限已经实现。

## 先固定设计输入 {#inputs}

开始界面工作前，从当前 AppSpec、平台契约和用户材料形成一个短设计输入，至少明确：

- 目标用户、主任务、页面归属以及 PC/移动设备范围；
- 必须保留的平台路由与授权导航事实、字段协议、权限和数据来源；Shell 外观可通过正式扩展接口自定义；
- 页面信息层次、关键操作，以及空、加载、失败、拒绝、校验、提交中和成功状态；
- 用户提供的品牌、参考图和素材授权；没有品牌事实时标记为 Agent 推断；
- 目标视口、可访问性、内容长度、数据量和性能边界；
- 本轮可以改变、必须保留和明确不做的内容。

已有有效设计继续沿用。只有视觉方向存在真实取舍时才比较候选；已经确认的意图不重复
提问。不得凭空补充 KPI、品牌故事、业务统计、角色能力或示例数据来源。

## 图片参考 {#image-reference}

图片生成是可选步骤。需要建立新视觉方向、比较布局或统一多页面风格时，可用 Image 2.5
等当前 Agent 图片能力生成一至三个关键视图；普通 CRUD、小范围样式修正或已有明确设计时
直接实现。生成提示应包含真实页面类型、主要内容、设备、密度、组件约束和不应出现的元素，
不得包含生产秘密、真实个人数据或未经授权的品牌和人物素材。

只保留实际采用的参考图，并记录实际模型、日期、提示摘要、目标视口和采用/拒绝理由。
不要逐像素照抄图片中的伪文字、虚构控件或不可能交互。Agent 应从参考图提取可实现的布局、
排版、颜色、间距和组件关系，再对照真实内容与平台组件修正。图片生成失败、不可用或结果
不合格时，记录事实并使用现有设计约束、成熟组件和浏览器迭代继续开发，不伪造产物。

## 页面归属与平台边界 {#adapter}

应用结构先于视觉：标准管理后台是默认骨架，必须保留平台后台路由、授权与显式菜单，Shell 外观可定制、
资源表单、数据列表、详情/编辑、权限和流程入口。Agent 可以在这些边界内优化布局、视觉和
交互，但不能用设计图、独立原型、单页 HTML 或 iframe 替代后台。

用户端 PC 与移动端按真实旅程分别实现，通过平台 runtime/Data API 使用后台数据，并与
后台保持独立的导航状态。Shell 的路由、当前用户、授权菜单和拒绝事实仍来自平台，不在
用户端复制。先复用 PC/移动 Field Kit 的输入、校验、上传、只读和权限行为；替换外观或
专业控件时，证明字段值、未保存输入、拒绝和恢复行为仍正确。

普通管理与录入保持工作型界面的扫描效率和信息密度。专业交互先评估项目已有依赖与成熟
组件，图表优先评估 ECharts。营销式大标题、装饰性卡片堆叠、无任务依据的插画、纯氛围
背景和重复导航不能因为参考图中出现就进入业务应用。

## 从参考到真实实现 {#loop}

1. 读取设计输入和相关契约，确定本轮页面、状态、视口与验收动作。
2. 需要时生成并筛选图片参考，提取可实现的视觉规则；不需要时直接沿用现有设计系统。
3. 在 `tokens.css` 或应用现有 token 源中定义实际采用的数值，派生 AntD theme 与移动 CSS
   变量；不要在图片说明、组件和全局偏好中维护多份数值事实。
4. 直接使用真实 React、平台 Shell、Field Kit 和受支持组件实现页面。原型只有在能降低
   高风险交互的不确定性时创建，且不得成为另一套长期业务代码。
5. 在目标尺寸打开真实页面，操作完整关键任务；检查布局、滚动、弹层、键盘、长文本、
   空、加载、失败、拒绝、校验、提交、恢复和离开保护。浏览器控制台错误必须处理。
6. 获取实际截图与交互发现，修正代码并重复检查。截图用于比较视觉，不替代操作断言。
7. 连接平台后，从真实入口按实际角色验证后台与用户端、允许与拒绝路径；只有业务证据
   通过后才进入部署。组件样例、本地数组和图片参考不能冒充远端业务验收。

现有交互模式作为任务检查依据，见[交互模式](./interaction-patterns.md)；它们允许按当前设计
改进，不是固定页面皮肤。

## AppSpec 设计资源 {#artifacts}

只固定本轮实际采用、可审阅且自包含的资源。目录可以按任务裁剪：

```text
appspec/design/visual.md                 # 范围、来源、取舍与受影响页面
appspec/design/references/<task>/        # 实际采用的图片参考及来源说明
appspec/design/system/DESIGN.md          # 视觉语义与实现交接
appspec/design/system/tokens.css         # 数值 token 的唯一可编辑来源
appspec/design/prototypes/<task>/        # 仅在必要时保留的可运行交互原型
```

图片来源可以用工具无关的清单记录；字段只描述实际事实，不要求特定模型或提供商：

```json
{
  "schema": "openxiangda.design-system/v1",
  "sources": [
    {
      "kind": "generated-image",
      "model": "Image 2.5",
      "path": "../references/request/desktop.png",
      "viewport": "1440x1024",
      "promptSummary": "内部事项办理台，紧凑主从布局"
    }
  ],
  "tokens": "tokens.css",
  "design": "DESIGN.md",
  "status": "reviewed-reference"
}
```

没有图片参考时省略 `sources` 和 `references`，不要创建占位文件。历史设计包已有其他来源
字段时仍可读取，不要求为了新流程重写。业务规则引用 AppSpec ID，图片清单不复制权限、
字段或页面协议。

运行时代码从 `tokens.css` 派生 AntD theme 与移动 CSS 变量。标准应用使用
`OpenXiangdaApplication` 的 `ui`，独立组件预览使用 `OpenXiangdaUiProvider` 的同名参数：

```tsx
const ui = { theme: derivedAntdTheme, className: 'project-design' };
<OpenXiangdaApplication {...applicationProps} ui={ui} />
```

`.project-design` 下的样式只覆盖本应用。移动端使用可继承的 `--oxa-mobile-*` 输入；平台
Provider 让 PC 下拉、对话框、消息与通知留在当前应用作用域。使用上下文反馈 API，避免
AntD 静态 API 脱离作用域；不要通过 theme 变化给整个应用换 key，以免清空正在编辑的值。

在 `visual.md` 的 front matter 中引用实际资源：

```yaml
assets:
  - appspec/design/references/request
  - appspec/design/system
```

目录引用包含所有后代文件；新增、修改或删除依赖都会改变评审摘要。引用拒绝越界、符号
链接、空目录和超预算；每次检查最多 128 文件、单文件 2 MiB、总计 8 MiB、16 层目录。
参考图应压缩为足以评审的尺寸，大型媒体放在受控来源并记录摘要，不靠删除 assets 声明
绕过检查。`spec context` 只读取资源字节，不执行原型或图片内容。

## 完成标准 {#acceptance}

视觉完成至少同时具备：当前 AppSpec 设计范围、真实实现、目标视口截图、关键交互断言、
无不可解释的浏览器错误，以及适用的真实角色允许/拒绝证据。图片模型的输出、Agent 自评、
结构检查或组件样例只能是过程证据，不能单独宣称设计或业务验收通过。