模型准备

模型不包含在 npm 包里。你在开发期通过 @optimalai/model-tools 下载并校验 它，它随后会生成一个供你 import 的 TypeScript 模块。

运行安装器

npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8

它会打印三行：

Installed kokoro-82m-v1.1-zh-int8@1.1-zh-int8
Model: <模型目录>
Generated: <optimalai-models.ts 路径>

它到底做了什么

1. 从 OPTIMALAI_MODELS_BASE_URL 或 --base-url 读取 base URL。
2. 拉取 <base>/<modelId>/manifest.json 并校验。
3. 逐文件下载，下载过程中即校验字节长度与 SHA-256。
4. 原子安装 —— 先写临时目录再 rename，因此下载失败绝不会留下写了一半的模型。
5. 生成含静态 require(...) 的 optimalai-models.ts。

完整契约见模型 CDN；简而言之，manifest 对每个模型版本不可变， 记录了运行时 ABI、103 个音色、最低 SDK 版本、字节长度与 SHA-256。

生成的模块

import type { OptimalAIModel } from "@optimalai/react-native";

export const kokoroZhInt8 = {
  modelId: "kokoro-82m-v1.1-zh-int8",
  modelVersion: "1.1-zh-int8",
  assets: {
    model: require("./optimalai-models/model.int8.onnx") as number,
    voices: require("./optimalai-models/voices.bin") as number,
    tokens: require("./optimalai-models/tokens.txt") as number,
    lexicons: [
      require("./optimalai-models/lexicon-zh.txt") as number,
      require("./optimalai-models/lexicon-us-en.txt") as number,
    ],
  },
  manifest: {/* 含音色条目的运行时 manifest */},
} satisfies OptimalAIModel;

把这个导出交给 createTts：

import { kokoroZhInt8 } from "./optimalai-models";

导出名默认由 model id 推导（kokoro-82m-v1.1-zh-int8 → kokoroZhInt8），除非 manifest 里指定了 exportName。

命令行选项

optimalai-model-tools add <model-id> \
  [--base-url URL] \
  [--models-dir DIR] \
  [--output FILE]

参数	用途
--base-url	本次运行覆盖 CDN base URL，调试 staging 时有用。
--models-dir	下载文件的存放位置。
--output	optimalai-models.ts 的写出位置。

Staging 与生产 CDN

生产 CDN 的 base URL 由 OptimalAI 在发布时注入；npm 包里刻意不含任何占位域名。 在该 URL 上线之前，请传 --base-url 或设置环境变量：

export OPTIMALAI_MODELS_BASE_URL="https://your-staging-host"

两者都没设置时，CLI 会直接失败，而不会去未知主机下载。

重复运行安装器

再次运行 add 是安全的。如果模型目录已存在且通过校验（逐文件比对字节长度与 SHA-256），CLI 会复用它而不是重新下载。

校验失败就是红灯

对于校验失败且已存在的目录，CLI 绝不会覆盖。请先查清失败原因，自行删除或移动 该目录，再重新运行命令。

提交策略

模型是大体积二进制文件。请把模型目录当作构建产物：加入 .gitignore，让每次 checkout 都通过安装器重现它。