Yida Ui Improve

页面与应用 UI 美化

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

明确针对数据管理列表、表头或操作栏的美化任务，优先由 yida-data-manage-ui 编排，复用本流程的备份和恢复参考；不要再路由回通用美化形成循环。

不可跳过的执行顺序

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

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

1. 读取现状与限定范围

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

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

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

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

涉及布局时按 共享响应式规则 展示宽屏和窄容器的效果及重排方式，包含筛选换行、主辅面板堆叠和等高解除；批准桌面效果不等于批准隐藏移动端字段或操作。

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

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

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

方案用日常语言写清：

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

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

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

3. 确认方案

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

4. 备份与实施

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

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

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

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

5. 核验与用户验收

布局改动按 响应式实际页面验收 覆盖容器缩放、重排点、内容增长和状态保持，逐项记录证据；静态示意或编译成功不能标记为响应式已验证。

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

6. 不满意时恢复

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

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