create-hmos-project

用技能自带脚本从模板生成 HarmonyOS ArkTS 工程，而不是让 Agent 逐个手抄模板文件。脚本负责递归复制、二进制资源复制、占位符替换（bundleName 等）与完整性校验；SDK/API Level 从 DEVECO_HOME 的 SDK 元数据自动检测，模型不得凭空发明版本号。

本技能的模板与脚本经用户许可，吸收自本机安装技能 deveco-create-project（技能目录名有意不同，避免同名冲突；模板路径解析已改为技能内相对路径）。

When to Use This Skill

Follow this skill's workflow whenever any of the following conditions is met:

• 用户要从零新建鸿蒙 ArkTS 工程（"0-1"、"from scratch"、"新建工程"、"创建项目"、空目录初始化）
• 目标目录已存在同名目录也不能跳过本技能——不要假定已有目录就是用户要的工程
• 用户提供中文或其他非 ASCII 工程名，需要转换为合法 appName
• 用户要求"帮我搭一个鸿蒙应用骨架/初始化一个可以跑的工程"

Do not force this skill onto "在已有工程里写新功能"、"UI 设计"、"构建签名"、"运行期崩溃" 场景 — 使用对应 skill（见下表）。

Boundary with Other Skills

This skill covers 「工程脚手架创建」, not 「业务代码实现」 or 「构建链路」:

Workflow (Follow Strictly)

1. 确认必需参数

任何必填值缺失时先询问用户再执行。

2. appName 规则（含中文工程名转换）

appName 必须匹配 ^[A-Za-z][A-Za-z0-9_]{0,127}$；中文/非 ASCII 名称会被脚本拒绝（exit code 4，APP_NAME_INVALID）。

用户提供中文或其他非 ASCII 名称时，必须：

1. 按含义提出 2-3 个 UpperCamelCase ASCII 候选（如 购物车 → ShoppingCart / ShopCart / Cart；天气预报 → WeatherForecast / Weather / Forecast；含义不明时才退回拼音）
2. 让用户选择，不得代选，即使某个选项看起来明显最优
3. 绝不把原始非 ASCII 名称传给脚本

3. 目录冲突与 SDK 错误处理（强制）

• {projectPath}/{appName} 已存在且非空：脚本 exit code 2 并输出 PROJECT_EXISTS JSON。此时询问用户选择覆盖 / 改名 / 取消，不要静默重跑或自行删除目录
• 用户显式指定 SDK/API Level 时直接透传，必须在 17..defaultApiVersion 范围内（defaultApiVersion 取自 DEVECO_HOME/sdk/default/sdk-pkg.json → data.apiVersion）；用户未指定时让脚本自动检测，模型不得发明版本
• DEVECO_HOME 必须已配置且指向有效 DevEco Studio 安装；SDK 元数据缺失/非法时脚本输出结构化 JSON 错误（code、message、hint），没有回退 API Level

脚本非零退出并输出以下错误码时，必须立即停止，把 code、message、hint 原样报告给用户，不做任何恢复动作：

所有情况一律：停止、原样报告 JSON 错误、让用户修好环境后再试。 不要搜索 SDK 文件、不要扫描 DEVECO_HOME/sdk/ 子目录、不要修改 SDK 目录内任何内容。脚本 stdout 的 JSON（apiLevel、sdkVersion、source、detectedFrom）是权威结果，不要重读 {DEVECO_HOME}/sdk/** 去复核。

4. 执行创建

需要 Node.js；不可用时立即停止并向用户说明。运行：

node "{SKILL_DIR}/scripts/copy-template.mjs" --project-path "{projectPath}" --app-name "{appName}" --bundle-name "{bundleName}" --api-level "{apiLevel}"

apiLevel 未由用户指定时省略 --api-level 让脚本自动检测。执行要求：

• 不要手工逐个复制模板文件——递归复制、二进制资源、占位符替换、完整性校验都由脚本负责
• 模板默认从本技能的 application/ 目录读取（也可用 --template-dir 显式指定）；脚本会执行模板完整性校验
• 非零退出时按 Step 3 的错误表处理并停止

5. 校验结果并继续功能开发

至少确认 {projectPath}/{appName}/build-profile.json5 存在；缺失即视为创建失败，不得继续后续编译或页面开发。

用户需求里除创建外还包含页面/行为时，继续开发前：

1. 读工程根的 AGENT.md（模板自带）——它列明该读哪些文件、跳过哪些（通常是 main_pages.json、Index.ets、EntryAbility.ets），不要盲目 glob 工程树
2. 修改实际启动页或其导航路径，保证所求功能从首屏可达

关键约束：EntryAbility.ets 与 main_pages.json 必须保持同步。 EntryAbility.ets 通过 windowStage.loadContent('pages/SomePage', ...) 加载首屏；该页面路径必须出现在 main_pages.json 的 src 数组中，否则框架静默加载失败，表现为白屏。重命名/替换 main_pages.json 首项、或在其前面插入新的启动页时，必须同步更新 loadContent() 指向；改完重读两文件确认一致。

不要只新建一个页面/组件而不让启动页路由到它；完成后用 arkts-build 的 hvigorw 流程构建验证。

6. 向用户汇报

完成全部创建/实现/构建/验证后（或阻塞失败时立即）输出：

• 工程绝对路径
• App name / bundle name / API Level
• API Level 来源：user_input / sdk_pkg
• 模板完整性校验是否通过
• 若有功能开发：构建/运行/验证状态

Directory Structure

create-hmos-project/
├── SKILL.md                          # This file
├── FILES.md                          # 模板文件清单与说明
├── application/                      # ArkTS 工程模板（Stage 模型，含 AppScope/entry/hvigor 全套）
│   ├── AppScope/                     # app.json5 + 应用级资源（分层图标占位）
│   ├── entry/                        # entry 模块（EntryAbility/Index.ets/main_pages.json/深色资源）
│   ├── build-profile.json5           # 工程级构建配置
│   ├── hvigorfile.ts / hvigor/       # 构建入口与 hvigor 配置
│   ├── oh-package.json5 / code-linter.json5
│   └── AGENT.md                      # 模板自带：生成后该读/跳过哪些文件的指引
└── scripts/
    ├── copy-template.mjs             # 模板复制 + 占位符替换 + 完整性校验
    └── detect-sdk.mjs                # DEVECO_HOME SDK 元数据检测（API 17-24 映射表）

Documentation Source & Maintenance

• 模板与脚本来源：经用户许可，吸收自本机安装技能 deveco-create-project（2026-08-29）；copy-template.mjs 的默认模板路径已改为技能内相对解析（scripts/../application），junction 安装下同样可用
• 脚本：自包含 Node 脚本，无外部依赖；SDK 检测基于 DEVECO_HOME/sdk/default/sdk-pkg.json
• 更新策略：DevEco 新版本 API Level 变化时更新 detect-sdk.mjs 的 API_CONFIGS 映射；模板结构问题优先修 application/ 后同步 FILES.md