AI 迁移：把已有项目带到 HTYF

已有项目可以作为迁移起点。htyf-migration 将迁移拆成可检查的步骤：盘点源功能、选择官方模板、逐项实现、适配宿主、构建并验证。你可以迁移整个项目，也可以指定页面或模块；源代码更新后，还可以基于上次记录继续同步。

AI 迁移由什么组成？

htyf-skills 提供 Agent Skills 规则，AI 编程工具负责执行；htyf-cli 负责生成模板、构建和调试；红糖云服客户端负责运行与真机验证。安装 CLI 不会自动安装 Skill，也不会自动提供模型服务。

1. 选择目标

源项目与诉求	目标	迁移重点
小程序、Web 应用或 RN 应用，希望使用宿主原生能力	RN `app` 模板	页面与导航、数据、权限、宿主已有原生模块
明确希望保留 Taro 多端开发方式	Taro `taro` 模板	Taro API、路由、`.htyf.*`、`htyf` 配置及其他端行为
含 `project.godot` 的 Godot 游戏	Godot `game` 模板	场景、资源、SDK 自动加载、触控、视口与 PCK 导出

默认非 Godot 项目选择 RN 应用目标；需要 Taro 时请在提示词中明确。Godot 迁移规则目前以 Godot 4.7 为目标，源项目版本不同需要先处理版本兼容。

将技能仓库克隆到源项目外，再安装到源项目。需要 Node.js 18 或更新版本。

git clone https://github.com/htyf-mp-community/htyf-skills.git
cd htyf-skills
node scripts/install.mjs --project /absolute/path/to/source-project

安装结果为：

source-project/
  .agents/skills/htyf-migration/
    SKILL.md
    references/
    agents/

在支持 Agent Skills 的 AI 编程工具中打开源项目，并新建会话。确认工具已发现 htyf-migration，再发出迁移请求。其他工具的技能目录可能不同，需按该工具约定复制完整目录。

已有同名技能时，安装器会停止。更新前先比较并备份本地修改；不要仅复制入口文件，迁移规则和 CLI 引用必须一并保留。

使用 $htyf-migration，将当前项目全部功能迁移到 HTYF。
目标放在当前项目的 HTYF/，保留源文件。
先盘点页面、交互、数据、接口、资源、权限、加载与错误状态，
从官方模板创建目标后逐项实现，最后报告功能映射、测试结果和未解决问题。

使用 $htyf-migration，将当前项目迁移到 HTYF，明确选择 Taro 模板。
保留 Taro 路由、API 和微信/H5 行为，HTYF 专属适配使用 .htyf.* 与 htyf 配置。
逐项验证页面、组件、异步状态、胶囊避让及真机交互。

使用 $htyf-migration，迁移当前 Godot 游戏到 HTYF。
先检查源引擎版本，再迁入 Godot 4.7 模板，保留 _HTYF_SDK 与 HtyfSdk 自动加载。
适配移动端触控、多点输入、横竖屏、安全区和胶囊区域，导出 PCK 并验证宿主运行。

建立清单。 读取源项目并记录基线；按功能列出页面、接口、资源和原生能力，排除目标目录以免递归迁移。
准备模板。 先检查 CLI 的 --help，确认支持非交互命令，再选择 RN、Taro 或 Godot 模板。未指定目标时使用源项目下的 HTYF/。
完成一个个功能。 每项包含 UI、交互、数据、权限、异常状态及适配代码，避免只还原静态页面。
适配宿主。 核对原生依赖是否已由宿主提供；处理导航、弹层、持久化命名空间、Safe Area 和胶囊位置。
逐项验收。 运行目标对应的检查和构建，并在客户端验证关键流程，输出完成项、差异和阻塞项。

当前 Taro 平台插件仍有交互菜单，不能将 RN CLI 的非交互参数直接套用到它上面。涉及 Taro 构建时，应检查项目已有的自动化脚本，或记录需要人工执行的菜单步骤，见 Taro 开发。

CLI 的项目名使用小写形式；迁移流程先在临时目录生成合法命名的项目，再将模板放到目标 HTYF/。已有迁移目标会先核对记录后复用，不会重新初始化覆盖。

宿主能力边界

小程序资源包不能凭空增加 iOS/Android 原生模块。源项目依赖宿主尚未提供的模块时，需评估已有 API 或 JS 实现；必须改宿主原生工程的能力要记录为缺口。完成编译不代表权限、相机、文件、支付等真机行为已经验证。

保留上次迁移报告、源代码基线和目标目录，再发出：

使用 $htyf-migration，基于上次记录的源代码基线同步最新变更。
复用现有 HTYF 目标，检查新增、修改和删除的功能，保留已完成的宿主适配。
报告本次变更、冲突处理和回归验证结果。

增量迁移需要可追溯的基线。缺少基线时，先重新比较源和目标，不能把“没有发现差异”当作已经同步。源与目标同时修改了同一功能时，需要按行为核对冲突。

AI 可以辅助实现和排查，最终验收以实际功能和目标宿主行为为准；这里不承诺任意项目零改动迁移。