build-and-deploy

用途

该技能用于将 Even Hub G2 应用打包并部署为可分发的 .ehpk 文件，并准备提交到 Even Hub 开发者门户。适用于打包、部署、发布等场景。

主要能力与工作流程

按顺序执行以下步骤：

校验 app.json：在项目根目录定位 app.json，逐字段按字段参考表校验。若字段缺失、类型错误或违反校验规则，报出确切错误并修复（若修复会改变 package_id 或 name 等有意义的值，需经用户确认）。在 app.json 有效前不得继续。
构建：在项目根目录运行 npm run build，确认构建成功（退出码 0），且输出目录（通常为 dist/）存在且非空。
打包为 .ehpk：运行 npx evenhub pack app.json dist -o <name>.ehpk，其中 <name> 取 app.json 中 name 字段的值（小写、空格替换为连字符）。例如 name 为 "Weather Now"，则使用 weather-now.ehpk。
验证输出：运行 ls -lh <name>.ehpk 确认文件已生成。若文件缺失，检查 pack 命令的错误输出并参考故障排查表。
分发：将 .ehpk 文件提交到 Even Hub 开发者门户进行审核与发布。

app.json 字段参考

除特别说明外，所有字段均为必填，在运行 evenhub pack 前需逐字段校验。

package_id（string，必填）：反向域名格式（如 com.example.myapp）。仅小写字母和数字，不得含连字符、大写字母、下划线。至少 2 个以点分隔的段。每段必须以小写字母开头，且只含小写字母或数字。
edition（string，必填）：必须恰好为 "202601"。
name（string，必填）：最多 20 个字符。
version（string，必填）：semver 格式 x.y.z，三段数字以点分隔（如 "1.0.0"）。不得有 v 前缀，不得有预发布后缀。
min_app_version（string，必填）：所需的最低 Even Hub 应用版本，如 "2.0.0"。
min_sdk_version（string，必填）：所需的最低 SDK 版本，应与你所构建的 SDK 版本一致（当前为 "0.0.12"）。
entrypoint（string，必填）：入口 HTML/JS 文件路径，相对于构建输出目录。该文件在 npm run build 后必须存在于构建输出目录内。
permissions（array，必填）：权限对象数组（见权限参考）。可为空数组 []。不得使用键值映射形式。
supported_languages（array，必填）：来自受支持集合的 BCP 47 语言代码数组。有效值：en、de、fr、es、it、zh、ja、ko。

最小有效 app.json 示例：

{
  "package_id": "com.example.weatherapp",
  "edition": "202601",
  "name": "Weather Now",
  "version": "1.0.0",
  "min_app_version": "2.0.0",
  "min_sdk_version": "0.0.12",
  "entrypoint": "index.html",
  "permissions": [],
  "supported_languages": ["en"]
}

权限参考

permissions 必须是对象数组。每个对象包含：

name（string，必填）：下列有效权限名之一。
desc（string，必填）：人类可读描述，1–300 个字符。
whitelist（string[]，仅用于 network）：允许的 URL 列表。当 name 为 "network" 时必填。

有效权限名：

network —— 出站网络访问（需要 whitelist）
location —— 设备 GPS/位置数据
g2-microphone —— G2 眼镜上的麦克风
phone-microphone —— 配对手机上的麦克风
album —— 访问相册
camera —— 访问摄像头

示例：

"permissions": [
  {
    "name": "network",
    "desc": "Fetches weather data from the API.",
    "whitelist": ["https://api.weather.com"]
  },
  {
    "name": "g2-microphone",
    "desc": "Enables voice commands for hands-free control."
  }
]

常见错误：不要使用键值映射格式。

// 错误
"permissions": { "network": ["example.com"] }

// 正确
"permissions": [{ "name": "network", "desc": "...", "whitelist": ["example.com"] }]

WebView 中的 CORS

Even App 在真实浏览器引擎中运行插件（Android 上为 Chromium，iOS 上为 WKWebView），完全适用 CORS 强制策略。app.json 的 network 白名单是 Even 层级的权限检查，并不会绕过 CORS。你需要同时满足：

域名在 app.json 的 permissions.network.whitelist 中被列入白名单，且
远程 API 返回正确的 CORS 响应头（Access-Control-Allow-Origin 等）。

若所调用的 API 不发送 CORS 头，即使域名已列入白名单，fetch() 也会以网络错误失败。

场景与修复：

API 有 CORS 头：只需在 app.json 中列入域名白名单即可正常工作。
API 无 CORS 头：使用自己的后端、Cloudflare Worker 代理（免费套餐）或寻找原生支持 CORS 头的镜像。
开发服务器（localhost）被 CORS 阻止：在 vite.config.ts 中添加 Vite 代理，见下文。

Vite 开发代理：在本地开发时用 Vite 代理避免 CORS。

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        rewrite: (p) => p.replace(/^\/api/, ''),
      },
    },
  },
})

该代理仅在开发环境有效。生产环境的 .ehpk 中，WebView 直接发起请求——你的 API 必须有 CORS 头，或必须通过自己的代理转发。

免费 CORS 代理服务不可靠：corsproxy.io、allorigins.win、api.codetabs.com 等公共代理会无预警地宕机、返回 403 或超时。若应用依赖没有 CORS 的第三方 API，请部署自己的 Cloudflare Worker（免费套餐，约 5 分钟设置）或寻找原生提供 CORS 头的镜像。

evenhub pack 选项

npx evenhub pack <app.json> <build-folder> [options]

-o <file> / --output <file>：输出文件名。未指定时默认为 out.ehpk。
--no-ignore：在包中包含通常被忽略的点文件和其他文件。
-c / --check：打包前检查 package_id 在 Even Hub 商店中是否可用。

故障排查

Invalid package id：使用小写反向域名格式，至少 2 个以点分隔的段。不得含连字符、大写字母、下划线，不得有以数字开头的段。示例：com.example.myapp。
name: must be 20 characters or fewer：将 app.json 中 name 的值缩短到 20 个字符以内。
version: must be in x.y.z format：使用三段数字 semver 字符串，如 "1.0.0"。不要使用 "1.0"、"v1.0.0" 或预发布标签。
min_app_version: expected string, received undefined：min_app_version 为必填，在 app.json 中添加它（如 "2.0.0"）。
min_sdk_version: expected string, received undefined：min_sdk_version 为必填，在 app.json 中添加它（如 "0.0.12"）。
permissions: each permission must be an object with name and desc keys：permissions 必须是对象数组，每个对象包含 name 和 desc，见上文权限参考。
supported_languages: invalid language：仅使用受支持的小写 ISO 代码：en、de、fr、es、it、zh、ja、ko。
Entrypoint file not found：确保 app.json 中的 entrypoint 指向的文件在运行 npm run build 后存在于构建输出目录内。
Project folder not found：构建输出目录不存在。先运行 npm run build，再重试 evenhub pack。

分发

.ehpk 文件验证通过后，将其提交到 Even Hub 开发者门户进行审核与发布。门户会校验包、运行兼容性检查，并在审核通过后使该应用对 Even Hub G2 用户可用。

任务

$ARGUMENTS