modernize-ui5-app

UI5 现代化工作流

这项技能分 五个阶段 对 UI5 应用进行现代化改造，每个阶段后都设有一个验证关卡。用户在开始时只选择一次关卡行为：完全自主、半自主或手动；协调器会在每个阶段边界应用该选择。

五个阶段

1. 机械式基线 — 自动修复 + 测试启动器重构。风险较低，可解锁测试运行。
2. 基础配置 — manifest.json 和 Component.js。后续所有工作都会读取 manifest。
3. 模块系统与全局变量 — 依赖关系图（sap.ui.define 数组、延迟加载、无隐式全局变量）。循环依赖和盲点修复也在此阶段进行。
4. 已弃用 API — 逐名称直接替换。在第 3 阶段稳定依赖关系图后执行较为安全。
5. CSP 合规性 — 最后执行，因为这取决于之前所有阶段均符合 CSP 要求。

第 5 阶段之后，文档整理环节会生成 MODERNIZATION-REPORT.md 和 MODERNIZATION-ISSUES.md。

规则 ID 到技能的映射

规则 ID	技能	阶段
no-deprecated-theme	fix-bootstrap-params	4
no-outdated-manifest-version	fix-manifest-json	2
no-legacy-ui5-version-in-manifest	fix-manifest-json	2
no-deprecated-library	fix-manifest-json（manifest）或 fix-bootstrap-params（HTML）	2 / 4
no-deprecated-component	fix-manifest-json	2
no-removed-manifest-property	fix-manifest-json 或 fix-component-async	2
async-component-flags	fix-component-async	2
no-globals	fix-xml-globals（所有 XML）或 fix-js-globals（JS — sap./jQuery.）	3
no-ambiguous-event-handler	fix-xml-globals	3
no-deprecated-control-renderer-declaration	fix-control-renderer	4
ui5-class-declaration	fix-control-renderer	4
no-pseudo-modules	fix-pseudo-modules	3
no-implicit-globals	fix-pseudo-modules	3
unsupported-api-usage	fix-partially-deprecated-apis	4
prefer-test-starter	modernize-test-starter	1
csp-unsafe-inline-script	fix-csp-compliance	5
（结构性）	fix-cyclic-deps	3
（运行时）	fix-linter-blind-spots	3

区分 no-deprecated-api

文件类型	消息包含	技能	阶段
.html	"bootstrap parameter", "deprecated theme"	fix-bootstrap-params	4
manifest.json	"view type", "model type", "resources/js"	fix-manifest-json	2
.js	"Lib.init/Library.init"	fix-library-init	4
.js	"deprecated renderer", "apiVersion", "IconPool", "rerender"	fix-control-renderer	4
.js	"deprecated class/property/interface"	fix-deprecated-controls	4
.js	"registerControllerExtensions" 或 manifest sap.ui.controllerExtensions 中的 sap.ui.controller	fix-fiori-elements-extensions	4
.js	manifest 扩展中不包含 sap.ui.controller	fix-js-globals（情况 9）	3
.js	"jQuery.sap.declare", "jQuery.sap.require"	fix-js-globals（情况 10）	3
.js	"getLibraryResourceBundle"	fix-js-globals	3
.js	"MessagePage"	fix-deprecated-controls	4
.js	"Parameters.get", "loadData", "Mobile.init", "createEntry", "View.create", "Fragment.load", "Router"	fix-partially-deprecated-apis	4
.xml	"native HTML", "SVG"	fix-xml-native-html	4
.xml	"visibleRowCountMode", 行模式属性	fix-table-row-mode	4
.xml	"MessagePage"	fix-deprecated-controls	4
任意	（无匹配项）	记录到 MODERNIZATION-ISSUES.md	—

阶段 0：前提条件与模式选择

前提条件检查

npx @ui5/linter --version || echo "ERROR: @ui5/linter not available"

如果未安装，告知用户运行 npm install --save-dev @ui5/linter，然后停止。

非交互模式

如果提示词包含“Do not ask for confirmation”或类似内容：跳过模式选择、验证关卡、提交和文档。依次执行阶段 1–5，不暂停。

先询问用户一次：选择哪种验证模式？

模式	每个关卡的操作
完全自主	运行测试 → 失败时，调试并修复（最多重试 3 次，或调试失败 1 次后停止）。停止时，输出报告并询问用户。
半自主	运行测试 → 输出结构化报告。等待用户输入“继续”。
手动	跳过测试。打印一行摘要。等待用户输入“继续”。

保存模式。各阶段之间不要再次询问。

构建与测试命令

阅读 references/build-and-test-commands.md。必须连接 Chrome DevTools MCP（如有需要，通过 /install-mcps 安装）。

• 存在 pom.xml → 使用 Maven。关卡使用 §1.3（mvn clean verify -P execute.qunit ...）。
• 不存在 pom.xml → 使用 npm。采用 package.json 中的脚本。备用方案：npx @ui5/linter --details。

操作原则

1. 修复每个有对应技能的错误。 数量多不是推迟处理的理由。
2. 必须按顺序执行各阶段。 阶段 3 会捕获 linter 看不到的运行时模式——报告中错误为零不代表阶段 3 已完成。
3. 返回类型发生变化时，绝不自动将同步改为异步。 sap.ui.xmlfragment()、sap.ui.component()、sap.ui.view()、sap.ui.controller()（实例化）→ 记录到 MODERNIZATION-ISSUES.md。
4. MODERNIZATION-ISSUES.md 是最后手段。 有效情况：不存在对应技能，或技能确实执行失败。无效情况：存在对应技能时，以“规则 X 仍有约 N 个错误”为由记录问题。

Git 提交策略

每个阶段提交一次，共五次（另加文档提交）。只暂存该阶段修改的文件——绝不使用 git add -A。

绝不暂存： headless-chrome.json、pom.xml（dev profile 补丁）、.gitignore（本地测试基础设施）。

#	阶段结束后	提交信息
1	1	chore: apply UI5 linter autofix and modernize test starter
2	2	fix: modernize manifest.json and Component.js
3	3	fix: modernize module system (globals, pseudo-modules, cycles, blind spots)
4	4	fix: replace deprecated UI5 APIs
5	5	fix: enforce CSP compliance
6	文档	docs: add modernization report and issues

阶段未产生更改时，跳过提交。

阶段 1：机械化基线

步骤 1.1：初始分析

npx @ui5/linter --details 2>&1 | tee /tmp/ui5-linter-baseline.txt
grep -c " error \| warning " /tmp/ui5-linter-baseline.txt || echo "0"

解析：按规则 ID 和文件分组统计错误与警告总数。保存结果以便最终比较。

步骤 1.2：应用自动修复

npx @ui5/linter --fix
npx @ui5/linter --details 2>&1 | tee /tmp/ui5-linter-post-autofix.txt

步骤 1.3：测试启动器现代化

启动一个子 Agent，使用 modernize-test-starter。使用自定义提示词，指示其：阅读技能，在更改前完整执行阶段 0 检测，遵循所有阶段，并根据 14 项完成清单进行验证。

阶段 1 提交 + 关卡

阶段 2：基础

步骤 2.1：manifest.json

启动一个子 Agent，使用 fix-manifest-json。传入以下规则中的所有 manifest.json 错误：no-outdated-manifest-version、no-legacy-ui5-version-in-manifest、no-deprecated-library、no-deprecated-component、no-removed-manifest-property，以及带有“view type”/“model type”/“resources/js”的 no-deprecated-api。

步骤 2.2：Component.js

启动一个子 Agent，使用 fix-component-async。无条件执行——即使 linter 未报告 async-component-flags，也要应用（只有当 manifest.json 从 rootView 中移除 async: true 后，才会出现此错误）。

步骤 2.3：验证 Component.js

node {skills-dir}/fix-component-async/scripts/verify-component.js {project-path}

如果退出代码为 1，修复以下问题：imported-interface → 从依赖项中移除，改用字符串字面量；interface-not-string → 将变量替换为字符串；missing-interface → 添加到 metadata 中。重新运行以确认。

阶段 2 提交 + 关卡

阶段 3：模块系统与全局变量

策略： 三个全局变量/模块技能并行运行（涉及不同文件）。之后依次运行 fix-linter-blind-spots 和 fix-cyclic-deps（需要稳定且完整的 JS 层）。

重要： 步骤 3.1 始终使用子 Agent。主 Agent 上下文中没有 fix-js-globals 的关键规则。

步骤 3.1：并行批处理

并行启动子 Agent（最多同时运行 8 个）：

• fix-js-globals：处理 JS no-globals 错误和路由至此的 no-deprecated-api 问题
• fix-pseudo-modules：处理 no-pseudo-modules / no-implicit-globals
• fix-xml-globals：处理所有 XML no-globals / no-ambiguous-event-handler（包括 app 命名空间全局变量）

已包含测试资源——test/ 文件同样适用这些规则。

步骤 3.1b：回归检查

重新运行代码检查工具。如果步骤 3.1 的规则出现新错误，则针对这些错误启动第二批处理。忽略属于其他阶段的错误。

步骤 3.2：fix-linter-blind-spots

启动一个子 Agent。指示它：阅读技能说明，阅读命名空间的清单，运行 detect-blind-spots.js，修复所有模式，然后重新运行脚本，确认总数为零。

步骤 3.3：fix-cyclic-deps

启动一个子 Agent。指示它：阅读技能说明，构建依赖关系图，自动修复 2 节点循环依赖（延迟 require），并在 MODERNIZATION-ISSUES.md 中标记 3 个及以上节点的依赖链。

第 3 阶段提交 + 门禁

重新运行代码检查工具，确认没有回归后再提交。

第 4 阶段：已弃用的 API

策略：不同技能针对不同规则/文件 → 按技能并行运行。使用映射表按技能归类错误，每个文件（或文件组）启动一个子 Agent。

执行

并行启动子 Agent（最多同时运行 8 个）。使用子 Agent 提示模板。按技能归类文件。

步骤 4.2：回归检查

重新运行代码检查工具。仅针对新增的第 4 阶段错误启动第二批处理。

第 4 阶段提交 + 门禁

第 5 阶段：CSP 合规性

CSP 放在最后处理，因为前面的阶段可能会引入内联代码块。

**重要：绝不要删除内联脚本——始终将其外置。**将内联代码移至 .js 文件，并替换为 <script src="...">。

针对包含 csp-unsafe-inline-script 的文件启动子 Agent。使用 fix-csp-compliance 模板。

第 5 阶段提交 + 门禁

最后运行代码检查工具，统计错误数。

验证门禁

每次提交阶段后，都要运行与第 0 阶段所选模式相匹配的门禁。所有测试命令的超时时间均设为 600000ms。

全自主

**委派给子 Agent。**打印 ⏳ Phase {N} gate: launching test sub-agent...

子 Agent 指示：

1. 阅读 references/build-and-test-commands.md → 判断使用 Maven 还是 npm
2. 运行测试命令（Maven §1.3 或 npm test）。除非不存在测试命令，否则仅运行代码检查工具不算验证。
3. **Maven：退出代码为 0 ≠ 所有测试均通过。**检查输出中的失败摘要以及 target/surefire-reports/。
4. 通过 → 报告 ✅ TESTS OK
5. 失败 → 分析并尝试最小修复（仅修复导入/路径/断言错误——绝不现代化代码），然后重新运行。最多重试 3 次，或调试失败 1 次后停止。
6. **范围约束：**仅修复由当前阶段导致的失败测试。绝不应用其他阶段的现代化修改。

收到结果后：✅ → 继续。❌ → 打印摘要并询问用户。

半自主

使用相同的子 Agent，但不要调试失败。仅报告结果：

✅/❌ Tests: N passed, N failed, N skipped
Failed test names (≤10)

等待用户输入：“continue” / “skip phase” / “run tests” / “abort”。

手动

打印：Phase {N} done. Files: {count}. Fixed: {count}. Deferred: {count}. 等待用户输入“continue”。

子 Agent 提示模板（第 1–5 阶段）

Fix UI5 linter errors in the following file(s) using the {skill-name} skill.

Project root: {project-path}

File: {file-path}
Errors to fix:
{errors}

Instructions:
1. Read {skills-dir}/{skill-name}/SKILL.md
2. Pay special attention to "Key Rules" — load-bearing constraints from past failures.
3. Read reference files mentioned in the skill.
4. Read the affected file(s).
5. Apply fix patterns EXACTLY as documented.
6. Verify each error is resolved.
7. Report: files modified, errors fixed, unfixable errors ({file}:{line} | {rule} | {reason}).

子 Agent 执行规则

• **仅限前台模式。**在一条消息中启动某个阶段步骤的所有子 Agent——等待全部返回。
• **每条消息最多约 8 个并发任务。**如果数量更多，则分批依次运行——不要在一批后停止。
• 将相关文件分组（控制器及其 XML 视图）交给同一个子 Agent。
• **在阶段步骤的各批处理之间不要验证。**检查应在阶段步骤完成后进行。
• 必须处理每个包含已映射错误的文件。

按阶段分派技能

阶段	技能
1	modernize-test-starter
2	fix-manifest-json、fix-component-async
3（并行）	fix-js-globals、fix-pseudo-modules、fix-xml-globals
3（顺序）	fix-linter-blind-spots、fix-cyclic-deps
4	fix-bootstrap-params、fix-library-init、fix-control-renderer、fix-deprecated-controls、fix-fiori-elements-extensions、fix-partially-deprecated-apis、fix-table-row-mode、fix-xml-native-html
5	fix-csp-compliance

文档阶段（阶段 5 之后）

使用 references/documentation-templates.md 中的模板创建 MODERNIZATION-ISSUES.md 和 MODERNIZATION-REPORT.md。

提交：docs: add modernization report and issues

上下文管理

主 Agent 绝不读取子技能文件，只由子 Agent 读取。

1. 绝不读取子技能。 路由表会告知你应使用哪项技能；子 Agent 会自行读取对应内容。
2. 解析并丢弃代码检查器输出。 只向每个子 Agent 提供筛选后的错误。
3. 压缩子 Agent 的结果。 保留：修复数量、无法修复的错误、已修改的文件。
4. 优先完成任务。 如果上下文不足，完成阶段 5；必要时跳过文档工作。

错误处理

如果修复确实失败：记录错误，将其加入 MODERNIZATION-ISSUES.md，然后继续处理下一个错误。

完成检查清单

• 用户已在阶段 0 选择验证模式；Agent 未再次询问
• 阶段 1–5 均有一次提交（或已跳过且无更改）
• 每个阶段结束后，均按照所选模式运行验证关卡
• 阶段 3 执行了全部三个步骤（并行 + 盲点 + 循环依赖），即使批处理后代码检查器显示 0 个问题也不例外
• 子 Agent 在前台以单消息批次启动
• 按阶段暂存文件（不得使用 git add -A）
• MODERNIZATION-ISSUES.md 仅包含确实无法修复的错误