docs(skills): 更新 maafw-template-migration 至 CMP 3.5.1

[Windsland52]

背景

Storage/skills/Windsland52/maafw-template-migration 写于 2026-07-07，之后 create-maa-project（CMP）多次重构，指南里若干关键结论已经失效。本次按 CMP 3.5.1 与 MaaFramework 5.13.0 的实际现状重写，依据来自 CMP 仓库 HEAD（模板、src/project-config.ts、docs/commands.md、CHANGELOG）、M9A 迁移后的真实目录，以及上游 release 列表。

主要修正

• 文件构成：原文把 tools/build-release.mjs、tools/sync-runtime.mjs、release.yml 当作基础产物；实际它们来自 github add-on，package.json/.node-version/tools/schema/* 来自 dev-tools。补齐 base 与各 add-on 的文件清单及 managed/once 刷新语义。
• Agent 项目：agent/bootstrap.py 已在 CMP 3.5.0 移除，发布包改为自带 Python 运行时，迁移需 --update python-runtime / --update python-deps。
• interface.json：原文称 CMP 不管该文件；实际 --sync 会就地修复派生部分（控制器标识与 type，含 Android/WlRoots 旧拼写）并保留手写内容，另有 project.interfaceUnmanaged 供完全自管（M9A 采用）。
• OCR：补 submodule / download 两种供应方式的布局差异、CREATE_MAA_PROJECT_OCR_SOURCE、ocr.submodulePath 与 --update ocr-models；确认 ocr.files 为 {目标文件名: 子模块内相对路径} 且仅用于 submodule 模式。
• 维护面：补 --add/--sync/--update/--doctor --report、备份与 --restore 回滚、schema v1 → v2 的显式迁移路径、Node >= 22.13，以及 CMP 自带 skill/MCP（日常维护交给它，本 skill 只覆盖迁移）。
• 坑位：保留并经复核的两条——logo.ico 未提交会导致打包静默跳过图标（hashFiles('logo.ico')），以及发布 workflow 里 ${gui^^} 在 macOS runner 的 bash 3.2 下不可用（M9A 的迁移后 workflow 正是用 tr 预计算的补丁）。

变更文件

• SKILL.md：指南重写
• README.md：中文说明同步更新
• maahub_meta.json：version 0.1.0 → 0.2.0、mfwVersion 5.11.1 → 5.13.0、updatedAt → 2026-09-15、描述同步

校验

本地 npm run validate:meta 通过（24 个 meta 文件）；SKILL.md front-matter 可被 YAML 正常解析。

Sourcery 摘要

使 MaaFramework 模板迁移技能及其元数据与当前的 create-maa-project 工作流和项目结构保持同步。

增强：

• 重写 MaaFramework 模板迁移指南，以适配 create-maa-project 3.5.1 和 MaaFramework 5.13.0，涵盖当前的基础/附加组件结构、迁移工作流、接口归属、OCR 提供模式、Agent 项目、维护命令、架构迁移、备份以及已验证的打包问题。

文档：

• 更新 README，说明修订后的迁移范围、兼容性基线、支持的场景，并指导用户使用 CMP 内置的维护技能或 MCP 模式进行持续的项目管理。

测试：

• 验证更新后的元数据和 SKILL.md front matter。

杂项：

• 将 MaaHub 元数据更新至版本 0.2.0、MaaFramework 5.13.0，并更新日期。

Original summary in English

Sourcery 摘要

将 MaaFramework 模板迁移技能和元数据更新至与 create-maa-project 3.5.1 和 MaaFramework 5.13.0 兼容的最新状态。

新功能：

• 扩展迁移技能，涵盖当前的 CMP 基础布局和附加组件布局、接口所有权、OCR 供应模式、Agent 项目、维护命令、备份、架构迁移以及已验证的打包问题。
• 添加有关将已转换项目迁移至 CMP 3.5.1 和 MaaFramework 5.13.0 的指南。

改进：

• 根据当前的 create-maa-project 工作流和 MaaFramework 项目结构，调整迁移文档和支持的场景。

文档：

• 重写 SKILL.md，并更新 README.md，以包含当前的迁移工作流、兼容性基线、维护范围和支持的场景。

测试：

• 验证 MaaHub 元数据和 SKILL.md 的 YAML front matter。

杂项：

• 将 MaaHub 元数据更新至适用于 MaaFramework 5.13.0 的 0.2.0 版本，并刷新其描述和时间戳。

Original summary in English

Summary by Sourcery

Bring the MaaFramework template migration skill and metadata up to date with create-maa-project 3.5.1 and MaaFramework 5.13.0.

New Features:

• Expand the migration skill to cover current CMP base and add-on layouts, interface ownership, OCR supply modes, Agent projects, maintenance commands, backups, schema migration, and verified packaging pitfalls.
• Add guidance for migrating previously converted projects to CMP 3.5.1 and MaaFramework 5.13.0.

Enhancements:

• Align the migration documentation and supported scenarios with the current create-maa-project workflow and MaaFramework project structure.

Documentation:

• Rewrite SKILL.md and update README.md with the current migration workflow, compatibility baseline, maintenance scope, and supported scenarios.

Tests:

• Validate MaaHub metadata and SKILL.md YAML front matter.

Chores:

• Update MaaHub metadata to version 0.2.0 for MaaFramework 5.13.0 and refresh its description and timestamp.

[sourcery-ai]

你好——我发现了 1 个问题

面向 AI 代理的提示

请处理此次代码审查中的评论：

## 各条评论

### 评论 1
<location path="Storage/skills/Windsland52/maafw-template-migration/SKILL.md" line_range="51" />
<code_context>
 ```bash
-pnpm dlx create-maa-project@latest
+npx create-maa-project@latest ./new-project --template agent \
+  --slug m9a --name "M9A" --controller Adb,Win32 --license AGPL-3.0-or-later \
+  --add dev-tools --add github --yes --no-interactive
 ```
</code_context>
<issue_to_address>
**issue (bug_risk)：** 该示例创建的项目 slug 为 `m9a`，但显示名称为 `M9A`；而后续说明指出，打包时要求 `interface.json.name` 与发布产物的 slug 完全匹配。遵循这两条说明会生成 `interface.json.name = M9A` 和产物 slug `m9a`，因此文档中的脚手架无法通过所述的打包验证。

**触发条件：** 生成的 `interface.json.name` 使用 `--name "M9A"` 的值，且打包检查区分大小写时。

**建议修复：** 明确检查比较的是显示名称还是 slug；如果确实要求与 slug 完全匹配，请在示例中使用一致的值，或说明所需的生成字段覆盖方式。

```suggestion
  --slug m9a --name "m9a" --controller Adb,Win32 --license AGPL-3.0-or-later \
```
</issue_to_address>

---

Sourcery 对开源项目免费——如果您喜欢我们的审查结果，请考虑分享它们 ✨

• X
• Mastodon
• LinkedIn
• Facebook

Original comment in English

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="Storage/skills/Windsland52/maafw-template-migration/SKILL.md" line_range="51" />
<code_context>
 ```bash
-pnpm dlx create-maa-project@latest
+npx create-maa-project@latest ./new-project --template agent \
+  --slug m9a --name "M9A" --controller Adb,Win32 --license AGPL-3.0-or-later \
+  --add dev-tools --add github --yes --no-interactive
 ```
</code_context>
<issue_to_address>
**issue (bug_risk):** The example creates a project with slug `m9a` but display name `M9A`, while the later instruction says packaging requires `interface.json.name` to exactly match the release artifact slug. Following both instructions produces `interface.json.name = M9A` and an artifact slug of `m9a`, so the documented scaffold fails the stated packaging validation.

**Triggers:** When the generated `interface.json.name` follows the `--name "M9A"` value and the packaging check is case-sensitive.

**Suggested fix:** Clarify whether the check compares the display name or slug; if it truly requires an exact slug, use matching values in the example or document the required generated-field override.

```suggestion
  --slug m9a --name "m9a" --controller Adb,Win32 --license AGPL-3.0-or-later \
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook