---
name: yida-ui-improve
description: 已有宜搭页面或应用的 UI 美化子流程。先展示视觉方案，通过 ask_human 确认，再备份和实施；只改外观，用户不满意时恢复本轮修改前状态。
---

# 页面与应用 UI 美化

由 `yida-design` 路由到本流程。适用于“美化这个页面”“应用风格不统一”“看起来太乱”“只改一下间距”等已有资源外观调整，也处理本轮美化后的不满意和恢复请求。首次搭建沿用 Fast / Plan；新增功能、业务重构和运行时迁移不属于本流程。

## 不可跳过的执行顺序

读取现状 → 准备视觉方案 → `ask_human` 确认当前方案 → 验证备份及恢复路径 → 实施 UI 修改 → 核验并请用户验收。用户不满意时执行恢复分支。

即使修改很小、用户已指定颜色或说“直接美化”，也要展示本次具体方案并确认。需求明确可以缩短方案，不省略确认。已确认的同一方案在同一轮内不重复询问；范围或效果变化必须重新确认。当前流程约束优先于一般单页设计、Fast 直接修改和发布闭环的默认推进规则。

## 1. 读取现状与限定范围

- 解析真实组织、环境、应用和页面。单页范围不扩大到应用主题；“应用美化、全应用配色统一和谐”覆盖该应用所有页面和浮层，必须先读 [全应用覆盖与一致性](references/application-coverage.md)，建立页面及状态清单，包含导航、门户、自定义页面、表单、表单详情、数据管理、报表、抽屉及其他弹层，不能只处理首页或代表性页面。
- 应用级主题改动前读取服务端实际 `appThemeEnable`、`appThemeMode`，记录新主题、老主题或能力未知；按 [旧主题作用域规则](../../references/application-style-library.md#旧主题应用的样式作用域与确认) 制定对应方案。老主题或能力未知不能假定所有页面、抽屉与 iframe 都会消费新版变量，也不能自动升级主题。
- 读取现有 `prd.md`、`design.md` 的相关段落、当前应用配置、目标页面完整 Schema 和可维护源码。线上与本地版本不同则分别保存，不能拿旧本地源码覆盖线上业务。
- 有浏览器能力时查看目标页面及代表性状态，保留修改前画面。看不到页面时说明观察来自源码/配置，不能声称完成视觉诊断。
- 记录 `functionContract`：数据源、API 参数、字段 ID/类型/映射、查询/筛选/排序/分页、计算口径、校验/必填/默认值、事件处理、按钮动作和跳转目标、权限、状态流转、提交与审批逻辑。
- 可改颜色、字体、间距、圆角、边框、阴影、对齐、响应式排布、视觉层级和装饰素材；自定义页面也可按获批方案更换 UI 组件及展示结构，遵守 [组件替换边界](references/component-replacement.md)。原有内容、操作和入口必须继续可见可达；不借美化删除/隐藏字段或操作、修改业务文案含义、替换数据、迁移 JSX 到 Canvas、升级应用主题模式或重做导航结构。
- 遇到业务问题只记录并说明，不能顺手修复。仅因美化加载的下游技能不得引入新的业务默认值、URL 规则、表单打开方式或状态管理实现。

用户说不清时，用“按钮不好找、文字看不清、内容挤在一起、颜色太抢眼”等可观察现象说明问题；只询问影响方案的关键偏好。沿用满意区域和现有主题，小修改不重新选三套风格或规划整个应用。

自定义页面允许换 UI 组件，业务实现保持原样；涉及替换时读取 [组件替换边界](references/component-replacement.md)，记录映射并验证事件、数据与状态行为。

## 2. 准备可查看的视觉方案

在 `<projectRoot>/.cache/openyida/<任务名>/ui-improve/<runId>/` 建立独立工作目录；`runId` 每轮唯一，不覆盖旧目录。方案、候选设计和预览都放这里，确认前不写入有效 `design.md`、页面源码、主题 CSS 或线上配置。只读快照可提前准备。

创建可打开的 `visual-plan.html` 和内部 `manifest.json`。HTML 用当前页面内容呈现“当前状态 / 预计效果”的并排或上下对照，标明哪些是实际截图、哪些是设计示意；无法取得原图时用真实内容的结构示意并标注。局部修改只展示相关区域，应用级方案展示共用主题和代表性页面。预览不得包含真实写操作或冒充已发布页面，不在 HTML 内放确认按钮。

出方案时先按 [备份和恢复](references/backup-and-restore.md) 核实各项恢复路径，避免让用户批准无法恢复的改动；完整备份在首次修改前完成。新版本预览存入新的 revision 子目录，更新附件路径，不覆盖已经展示的文件。

方案用日常语言写清：

1. 哪个页面、哪个区域目前有什么具体问题。
2. 准备变成什么样：布局、颜色、字号、间距等落到可看见的变化。
3. 修改范围及保持原样的业务功能；应用级方案必须展示完整覆盖清单和各类页面/浮层的效果示意，说明自动继承、需要单独适配和受限区域，不能只写“全局统一”而省略报表、门户或抽屉。
4. 如何验收，以及“不满意就恢复本轮修改前”的处理方式。

复用 `yida-design` 的主题、可读性和组件规则；需要单页证据时读 [page-design](../page-design/SKILL.md)。该子流程只辅助准备方案，不允许提前执行其主题生成、覆盖设计源或实施交接。没有值得改的问题可以说明理由并结束，不制造修改。

`manifest.json` 至少记录 `runId`、目标环境/组织/应用/页面、修改范围、`functionContract`、方案路径与内容摘要、`revision`、`status`、`presentedRevision`、`confirmedRevision`、确认交互及用户回答证据、备份清单、逐资源执行与恢复结果。初始状态为 `draft`。每次修改方案生成新 revision 并清空确认；此前展示的 HTML 保留不可变副本。

## 3. 确认方案

按 [方案确认](references/confirmation.md) 调用宿主支持的 ask_human，绑定当前方案和版本，等待用户选择“确认并开始美化 / 继续调整 / 暂不修改”。未明确同意不修改；方案变化后重新确认，同一获批方案不重复询问。

## 4. 备份与实施

确认后、首次修改前必须读 [备份和恢复](references/backup-and-restore.md)，逐资源证明可以恢复，才将状态设为 `backed_up`。备份不完整或当前 CLI 无法恢复某项原值时不实施该项；缩小范围需更新方案并重新确认。

备份完成后，将获批设计按范围合并到有效 `design.md`，再交接实现：

| 资源 | 实施入口 | 限制 |
| --- | --- | --- |
| Canvas 自定义页面 | `yida-canvas-custom-page` → `yida-publish-page` | 可替换 UI 组件；保留原运行时和业务实现，遵守组件替换边界 |
| 历史 JSX 页面 | `yida-custom-page` → `yida-publish-page` | 可替换运行时支持的 UI 组件，保留业务实现；不迁移到 Canvas |
| 原生表单视觉属性 | `yida-create-form-page` 的受控 patch | 只改已核实的视觉属性，不重建字段、组件树或规则 |
| 应用主题/导航样式 | `app-theme snapshot` → `yida-design` 主题生成与 `update-app`；恢复用 `app-theme restore` | 先按备份文档检查可恢复键与图标联带变化；仅改已确认应用级样式，不升级主题模式、不改变导航结构 |
| 门户、报表、数据管理和浮层 | 按覆盖清单确定实际承载类型，复用应用主题或已核实的样式维护能力 | 不把原生页面当自定义页面发布，不重建报表/门户；抽屉外壳和内部页面分别适配，业务配置保持不变 |

交接必须携带 runId、获批 revision、备份位置、允许改动清单和功能契约。下游缺少这些信息时回到本流程，不能从“请美化”直接发布。旧主题全局注入仍须满足原有确认条件，方案已明确覆盖同一应用及注入范围的有效回答可复用；不能用页面美化批准推导全局注入授权。

首次实施写 `status=applying`。每次远端写入前先检查待发布 diff：只含获批 UI 项，业务契约及非 UI Schema 保持原样；否则先撤掉越界修改。逐资源记录开始、完成、读回证据及修改后指纹。每次写入前核对最新状态与该资源基线（后续写入与本轮上次成功读回指纹比较）；不一致时停止，先确认是否有外部修改。失败或响应未知时先读回，确定实际已变更集合，再恢复本轮变更，不盲目重试或新增替代资源。

## 5. 核验与用户验收

- 对照备份检查 diff：每处修改必须能对应获批视觉项；业务函数、表达式、数据绑定、配置和入口保持一致。UI 组件及其绑定写法可以按 [组件替换边界](references/component-replacement.md) 替换，但原事件处理函数、参数语义和触发行为必须保持；有组件替换时逐项核验 `componentReplacements`。发现业务变化先撤掉该变化，不能用“功能还能用”代替业务未改。
- 按对应技能编译、校验并发布，读回目标资源。检查实际页面、文字对比、溢出、响应式以及原有按钮、筛选、分页和表单入口。验证不能自动提交真实业务数据或触发审批。
- 应用级美化按覆盖清单逐页核验导航、门户、自定义页面、表单、表单详情、数据管理、报表及其抽屉/浮层；打开实际抽屉检查外壳和内部内容，确认 iframe、Portal 挂载边界及已有局部样式没有造成风格断层。代表性截图只用于方案展示，不能代替全应用验收。运行态无法检查的具体项标记待验证，不能把编译/发布成功或单页截图说成全应用统一。
- 展示实际效果与访问入口，再通过 `ask_human` 询问“保留这次效果 / 不满意，恢复原样”。发布成功进入 `awaiting_acceptance`，只有用户满意才记 `accepted`；未回复时保留可恢复状态，不自动接受或回滚，不清理备份。

## 6. 不满意时恢复

用户选择恢复，或明确表示不满意且没有要求保留本轮修改时，立即按 [恢复步骤](references/backup-and-restore.md#恢复步骤) 恢复本轮修改前状态，不继续叠加新设计，也不重复索要同一范围的恢复许可。若用户明确“保留这些，只调整另一处”，保留指定部分并据此准备下一轮方案、确认和新备份，旧备份继续保留。

恢复包括本轮已修改的线上资源及本地设计、源码、主题文件。逐项读回和核对后才能记 `rolled_back`；部分失败记 `rollback_failed`，说明已恢复和未恢复的资源，保留全部证据。下一轮不得覆盖最初基线；“恢复最初版本”按任务记录选取初始备份，“恢复本轮前”使用本轮备份。