常见问题

新项目用哪个模板？

RN 小程序选 app；需要保留 Taro 多端开发方式选 taro；Godot 游戏选 game。当前 CLI 初始化菜单没有 web-template，已有 Web 项目仍可参考历史说明。

CLI 和 Skill 分开安装。CLI 负责模板与构建；htyf-skills 提供迁移规则，需在支持 Agent Skills 的编程工具中使用。安装后新建会话确认工具发现 htyf-migration。完整流程见 AI 迁移。

Skill 要求按功能清单逐项迁移和验收，但不能保证任意源项目都具备相同原生能力。宿主未提供的模块、平台特有接口或引擎版本差异需逐项处理并记录。未完成项必须出现在报告中，不能用编译成功代替功能验收。

有可追溯基线时，复用既有目标进行增量迁移，检查新增、修改和删除。不要重新初始化覆盖已有适配；缺少基线时先比较源与目标。

先执行 npx --yes @htyf-mp/cli --help 检查安装版本。仓库源码可能先于 npm 发布；需要最新能力时使用 htyf-cli 源码入口。旧版本仍可能使用旧 Taro 模板路径，仓库拆分不等于 npm 已发布。

目标目录应尚不存在。选择新的目录名，或确认现有目录是否是可复用的迁移目标。不要为了初始化清空已有业务目录。

先保留锁文件和完整错误信息。确认 Node.js 满足 CLI 与模板依赖的 engines，固定包管理器，检查 registry、网络与缺失包版本，再根据错误修复。不要一开始就删除锁文件或强制忽略 peer 依赖。

检查执行位置是否包含 app.json.htyf；从其他目录运行时传入 --project。首次打包提供合法 --version；RN、Taro 与 Godot 使用各自的构建路径，见快速开始。

依次检查手机能否访问电脑的服务地址、构建是否成功、资源 URL 是否可访问、平台是否匹配，以及版本和缓存。通过开发助手查看运行日志，再核对入口与宿主支持的模块。

不能。JS 包存在不代表宿主已编译对应原生模块。优先使用宿主已有能力与 JS SDK；需要新原生模块时，必须修改和重建宿主，并记录客户端版本要求。

部分接口依赖宿主桥接。按 JS SDK 指南检查运行环境、初始化与类型定义，并为普通浏览器提供合适的降级行为。

提供模板类型、CLI 和关键依赖版本、操作系统、实际命令、完整报错和最小复现。迁移问题附上源类型、目标目录及未通过的验收项。仓库归属见仓库与贡献。