# mimi 教材包 v1

mimi 是播放器，教材包是纯内容。教材安装在 `~/Library/Application Support/Mimi/Packs/<id>/`，进度在同级 `progress.json`。App 本身不包含课程或音频。工具升级不替换已安装教材。

## 本地格式

教材是一个后缀为 `.mimipack` 的普通文件夹，内有 `manifest.json` 和 `audio/`。在菜单的“教材库”导入整个文件夹或 manifest.json，切换教材不自动播放。移除将教材文件夹移入系统废纸篓，学习记录保留。相同 id 暂不覆盖；更新时先移除再导入。

可运行的最小测试实例见 `tests/fixtures/demo.mimipack`（仅测试音）。结构约定：

```json
{
  "schemaVersion": 1,
  "id": "my-japanese-pack",
  "version": "1",
  "title": "我的日语练习",
  "language": "ja",
  "source": {"title": "自制教材", "license": "个人使用"},
  "generation": {
    "llm": {"provider": "provider-name", "model": "model-name"},
    "tts": {"provider": "provider-name", "model": "model-name", "voice": "voice-id"},
    "createdAt": "2026-09-10T00:00:00Z",
    "promptVersion": "1",
    "reviewStatus": "unreviewed"
  },
  "scenes": [{"id": "work", "title": "同事交流"}],
  "lessons": [{
    "id": "request-01",
    "contentRevision": "1",
    "scene": "work",
    "text": {
      "ja": "あとで、もう一度送ってください。",
      "annotated": "あとで、もう{一度|いちど}{送|おく}ってください。",
      "zh": "请稍后再发一遍。",
      "note": "あとで是稍后，もう一度是再一次。"
    },
    "audio": {
      "path": "audio/request-01.mp3",
      "sha256": "由实际文件计算的64位小写SHA256",
      "duration": 4.2
    }
  }]
}
```

以上是字段示例，不是可导入的成品；必须生成真实音频并填写其散列和时长。所有 ID/version/revision 使用 1–32 位小写字母、数字、连字符；版本示例用 `1` 或 `1-1`。一包 1–2000 段，一段音频最多 50 MB，一包最多 500 MB。ja 必填，annotated/zh/note 可缺省。移除 `{字|读音}` 标记后的注音文本必须等于 ja。

可选 `segments` 放在每条 lesson 上，每项包含 `id`、`start`、`end`（秒）和同结构的 `text`。按时间顺序排列，不重叠，必须落在音频时长内。没有可靠时间轴就省略；播放器不猜测分段边界。标注必须对应真实录音，格式检查不能判断语言内容是否正确。

## ID 与学习记录

进度键为 `pack.id--lesson.id--contentRevision`。单纯修正翻译或排版，保持 contentRevision；改动音频、日文或考察的理解目标时递增 contentRevision。version 是整个包的发行版本；仅改 version 不清空学习记录。不能只为更新译文重新随机生成全部 ID。

迁移既有教材时，应按原音轨的稳定标识映射记录，避免重复计数或丢失历史。

## 未来 AI 制作流程

1. LLM 生成草稿：结构化 ja、annotated、zh、note、稳定 ID。
2. 校对文字与读音，再交给 TTS；声线、模型写入 generation.tts。
3. TTS 生成本地音频，计算 SHA256、实际时长；有可靠对齐结果再写 segments。
4. 运行与导入相同的校验，产出完整 `.mimipack`。生成失败的草稿留在生成器工作目录，不作为半成品教材导入。
5. 未人工确认的内容标为 unreviewed，教材库显示“AI 内容未校对”；检查后可标 reviewed。

LLM、TTS 是教材制作者，不参与每次播放。密钥放在未来生成工具的安全凭据存储中，不能写入教材包。包中不包含 JS、HTML 页面或可执行代码；播放 UI 由 mimi 自己生成，文本做转义处理。

## 云端目录预留，尚未实现下载

将来使用静态 JSON 目录即可，每项包含 id、version、title、description、language、level、sizeBytes、downloadUrl、sha256、source、reviewStatus。下载到临时位置，检查归档安全和完整性，再走相同本地校验/安装流程；失败不替换已安装教材。目录本身不可通过更改展示字段授权执行代码。需要分发权限的教材先核对许可。

现在未实现：远程目录、网络下载、zip 导入、LLM/TTS API、账号、云同步、自动升级教材。预留接口不依赖某一家模型供应商。

## 分发工具

`mimi-macos-arm64.zip` 只有工具，解压后可放进 Applications；首次无教材时点击猫头会打开教材库。当前构建为本机 Apple Silicon 的本地签名应用，尚未做 Developer ID 签名、公证或其他 Mac 的兼容验证。下载页应明确这些早期版本限制。


## 音频教材补充字段

每段可带 `title` 和 `transcriptStatus`（`available` 或 `missing`）。缺省按 available 处理。missing 时 `text.ja` 为空、不得包含注音或时间轴，界面显示暂无原文，播放仍使用原音频。不得把音轨标题伪装成原文。

教材库进度按音轨唯一编号统计：曾无提示理解、仅借助提示理解、未自评互斥；重复练习不重复增加完成数。移除教材保留记录。