---
name: yida-upgrade-app-theme
description: 将老应用升级为新版主题，同步更新页面和表单样式。仅在用户明确要求升级时使用，执行前须通过 ask_human 确认；普通换色、美化不触发。
---

# 老应用升级新版主题

保持业务逻辑和主要布局，升级应用主题、自定义页面和表单样式。

## 1. 准备

仅在用户明确要求升级新版主题时使用。普通美化、换色或创建应用不触发。

确定目标应用，运行 `openyida agent-capabilities --summary-json`，再将页面备份到新目录：

```bash
openyida upgrade-app-theme <appType> --explicit-request --prepare --output-dir <projectRoot>/.cache/openyida/theme-upgrade/<appType>/<run-id> --json
```

准备命令不会修改远端页面。读取生成的 `upgrade-plan.json`，核对隐藏页、嵌入页和用户指定页面；遗漏项通过 `openyida get-schema <appType> <formUuid>` 补齐。无法获取源码的页面记录为未完成项。

## 2. 判断应用风格

先看原自定义页面的实际效果和源码，从主按钮、标题、链接、背景和卡片中判断主色、明暗及整体风格。优先遵循用户指定的风格；否则延续已有页面的品牌色。不要直接采用平台默认色，也不要把成功、警告等状态色当作主色。

页面风格不一致或主色不明确时，用 **ask_human** 提供候选颜色和简短理由，确认后再改。将选定主色和判断依据记录在升级清单中，统一用于应用导航、页面和表单。

## 3. 确认

任何远端修改前，必须调用 **ask_human**，说明：

- 目标应用、组织及涉及的页面和表单。
- 拟采用的主色和风格，以及它与原页面的关系。
- 将升级主题、迁移旧自定义页面、统一样式并重新发布。
- 保留业务逻辑和主要布局。

提供“确认升级”和“取消”，收到明确确认后继续。无回复、拒绝或工具不可用时停止写入，“直接做”不能替代确认。范围变更时只确认新增部分。

## 4. 迁移并升级

按 [页面和表单迁移](references/page-migration.md) 完成本地修改和验证：

- JSX 页面转为 CodeCanvas。
- 已有 CodeCanvas 页面更新主题样式。
- 表单和详情页移除旧主题注入，保留业务代码。

保留原应用和页面 ID。任一必要页面无法保留业务或结构时，停止升级并说明原因。

本地验证通过后执行：

```bash
openyida upgrade-app-theme <appType> --explicit-request --confirm --json
```

成功后保存选定的应用主题，再按清单发布页面、保存表单并回读验证。命令失败时停止后续操作。向用户说明进度和结果，不展示内部检查、配置字段或诊断数据。

## 5. 验收

重新加载页面，验证业务操作、表单详情、主题样式和窄屏效果，逐页记录结果。编译或升级命令成功不能代替页面验收。

全部目标页面和表单通过后，才能报告升级完成；否则列出已完成项和剩余问题。