# 安装 Miragea 音频与字幕 Skill

这是给 Codex 等 Agent 阅读的安装说明。用户发送「安装 本文地址」即授权安装本 Skill。

## 安装

1. 以获取本文的完整 URL 为基准，解析相对地址 `../miragea-audio.zip`，下载 Skill 包。下载和安装均无需 API Key。
2. 检查压缩包仅包含 `miragea-audio/SKILL.md` 和 `miragea-audio/scripts/miragea_audio.py`；拒绝绝对路径或包含 `..` 的归档成员。
3. 将 `miragea-audio` 目录安装到当前 Agent 的个人 skills 目录。Codex 使用 `$CODEX_HOME/skills`，未设置时使用 `~/.codex/skills`；其他 Agent 使用其支持的 skills 目录。如果用户要求更新，先比较本地和下载包 `SKILL.md` 的 `metadata.version`，检查本地修改。使用新版的指令和脚本一起更新，保留用户的本地修改和服务地址。
4. 阅读安装后的 `SKILL.md`。仅依赖 Python 3.9+ 标准库，无需安装额外软件包，也无需修改 Agent 的全局配置。

## 服务地址与密钥

- 服务地址使用本文 URL 所在站点的 `/v1`。将该地址记录在安装后的 Skill 中，调用脚本时通过 `MIRAGEA_BASE_URL` 传入，适配用户正在使用的站点。
- 检查 `MIRAGEA_API_KEY` 是否已配置，仅判断是否存在，不输出密钥内容。
- 如果未配置，提醒用户在同一站点的 `/workspace/api` 页面生成 API Key，再通过安全的本地环境变量配置；不要要求用户把密钥贴进聊天。免费账号默认可调用 API，实际以账号的 API 访问权限为准。安装可以完成，配置密钥后才能调用。
- 不在安装过程中生成音频、识别字幕或创建计费任务。用户之后提出任务时，先查询 `/capabilities` 再调用相应能力。

完成后简短告知 Skill 已安装；如缺少密钥，一并提醒生成和配置 API Key。