# Ninth Muse 工作室平台 · AI 操作手册

> 你是一个被授权的 AI 助手。用户给了你这个链接，以及一个账号（邮箱 + 密码）或一个 API 密钥。
> 读完本页你就能代表用户：创建/修改作品（游戏、课程、引擎、演示）、上传素材、发布网页版与下载文件、恢复旧版本（回滚）、写手记。
> 只需要 HTTP（curl / fetch / requests），不需要安装任何工具。

- 站点：https://ninthmuse.cn
- 接口根：https://ninthmuse.cn/api
- 本页 Markdown：https://ninthmuse.cn/agent.md

公开网址（给用户看的链接）：

| 内容 | 网址 |
|---|---|
| 游戏 | `https://ninthmuse.cn/games/<slug>` |
| 课程 | `https://ninthmuse.cn/courses/<slug>` |
| 引擎与工具、演示 | `https://ninthmuse.cn/engines/<slug>` |
| 在线游玩 / 学习（网页版） | `https://ninthmuse.cn/play/<slug>/` |
| 下载文件 | `https://ninthmuse.cn/dl/<buildId>/<文件名>`（作品 `downloads` 里的上传文件） |
| 成员主页 | `https://ninthmuse.cn/team/<成员 slug>` |
| 手记 | `https://ninthmuse.cn/journal/<slug>` |
| 自由页面 | `https://ninthmuse.cn/<slug>` |
| 搜索 / 标签筛选 | `https://ninthmuse.cn/search?q=<词>&kind=<game, course, engine, demo 或 post>&tag=<标签>` |
| 留言板 | `https://ninthmuse.cn/guestbook` |

接口返回的 `pageUrl` 已经按类型算好，直接给用户即可。

## 0. 规则

1. **只操作用户要求的内容。** 你只能修改自己参与的作品（接口会拒绝其它作品）。
2. **上线、回滚前先预演**：加 `?dryRun=1`，把预演结果告诉用户，确认后再正式执行（用户已明确让你直接发布时可跳过）。
3. **校验报告里的 warnings 要告诉用户**，尤其是 `absolute_paths`（网页会白屏）。
4. 写操作建议带 `Idempotency-Key: <随机串>` 头，网络重试不会重复发布。
5. 自定义接口出错时响应是 `{ "error": { "code", "message", "hint" } }`，按 `hint` 处理；通用接口（/api/projects 等）出错是 `{ "errors": [{ "message", "data" }] }`。

## 1. 认证

### 1.1 首选：API 密钥（无需登录、无需人机验证）

每个请求带：

```
Authorization: users API-Key <密钥>
```

密钥从哪来：

- 用户在后台 https://ninthmuse.cn/admin →「成员」→ 自己 → 勾选「启用 API 密钥」→ 复制给你；或
- 你用账号密码登录一次（1.2），然后**给自己生成一个**，之后一直用它：

```bash
KEY=$(python -c "import uuid;print(uuid.uuid4())")
curl -s -X PATCH https://ninthmuse.cn/api/users/<你的用户 id> -H "Authorization: JWT $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"enableAPIKey\":true,\"apiKey\":\"$KEY\"}"
# 之后：-H "Authorization: users API-Key $KEY"
```

下文示例用 `-H "$AUTH"` 表示认证头（`AUTH="Authorization: users API-Key <密钥>"` 或 `AUTH="Authorization: JWT <token>"`）。

### 1.2 账号密码登录（需要解一道工作量证明题）

登录和「忘记密码」都需要人机验证：先 `GET https://ninthmuse.cn/api/interact/challenge` 拿一道题，算出 `number`，
使 `sha256(salt + number)` 的十六进制等于 `challenge`（number 从 0 数到 maxnumber，通常 1 秒内），
把结果 base64 后放进 `x-altcha` 请求头。每个解只能用一次；缺少或错误返回 **403**（此时还没有校验密码）。

Python：

```python
import base64, hashlib, json, requests
B, EMAIL, PASSWORD = "https://ninthmuse.cn", "<邮箱>", "<密码>"
ch = requests.get(f"{B}/api/interact/challenge").json()
n = next(i for i in range(ch["maxnumber"] + 1)
         if hashlib.sha256(f'{ch["salt"]}{i}'.encode()).hexdigest() == ch["challenge"])
alt = base64.b64encode(json.dumps({"algorithm": ch["algorithm"], "challenge": ch["challenge"],
      "number": n, "salt": ch["salt"], "signature": ch["signature"]}).encode()).decode()
r = requests.post(f"{B}/api/users/login", json={"email": EMAIL, "password": PASSWORD}, headers={"x-altcha": alt})
TOKEN = r.json()["token"]          # 之后：Authorization: JWT <TOKEN>（7 天有效）
```

JavaScript（Node 18+）：

```js
import { createHash } from 'node:crypto'
const B = 'https://ninthmuse.cn', email = '<邮箱>', password = '<密码>'
const ch = await (await fetch(`${B}/api/interact/challenge`)).json()
let n = 0
while (n <= ch.maxnumber && createHash('sha256').update(ch.salt + n).digest('hex') !== ch.challenge) n++
const altcha = Buffer.from(JSON.stringify({ algorithm: ch.algorithm, challenge: ch.challenge, number: n, salt: ch.salt, signature: ch.signature })).toString('base64')
const res = await fetch(`${B}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-altcha': altcha }, body: JSON.stringify({ email, password }) })
const { token, user } = await res.json()   // Authorization: JWT <token>
```

看看你是谁、能管理哪些作品：

```bash
curl -s https://ninthmuse.cn/api/agent/me -H "$AUTH"
# → { user:{id,name,role,slug}, projects:[{id,slug,title,kind,_status,pageUrl,webBuild,liveBuild,playUrl}] }
```

## 2. 作品（projects）

作品 = 网站上的一个条目。**先选类型 `kind`**，它决定出现在哪个栏目、需要哪些信息：

| kind | 中文 | 栏目 | 上线必需素材 |
|---|---|---|---|
| `game` | 游戏（网页游戏、客户端游戏） | /games | 动态海报视频 `posterVideo` + 静态封面 `cover`（视频转码后的首帧可代替封面） |
| `course` | 课程 | /courses | `cover` 或 `heroImage` |
| `engine` | 引擎与工具 | /engines | `cover` 或 `heroImage` |
| `demo` | 演示（引擎对比、技术演示；可在线运行，也可以只有图片 / 视频） | /engines（“演示”一节） | `cover` 或 `heroImage` |

通用字段：

| 字段 | 说明 |
|---|---|
| `title` | 标题（必填，分语言） |
| `slug` | 网址标识，小写字母/数字/连字符，如 `star-garden`。**中文标题必须显式给 slug** |
| `kind` | 见上表，默认 `game` |
| `summary` | 一句话简介（≤60 字，分语言） |
| `features` | 卖点 / 能力 / 课程收获，`[{ "title", "text" }]`，最多 6 条（分语言） |
| `links` | `[{ "label", "url", "kind" }]`，kind 取 `store` `download` `docs` `repo` `video` `other`（label 分语言） |
| `gallery` | 画面：媒体 id 数组（图片或视频，顺序即展示顺序）。用 2.1 的接口上传最方便 |
| `_status` | `draft` 草稿 / `published` 已发布（访客只看得到已发布的版本） |
| `webBuild` / `entry` / `downloads` | 网页版与下载文件（见第 4 节） |
| `tags` | 字符串数组 |
| `cover` / `showcase` | 封面与海报素材（见 2.1） |
| `members` | 参与成员的用户 ID 数组 |
| `layout` | 可选的自由区块（见第 3 节），前台作为“更多”一节 |

按类型的信息组（只填当前类型的那一组）：

**`game`**

| 字段 | 说明 |
|---|---|
| `genre` | 类型，如“动作冒险 / 叙事解谜”（分语言） |
| `platforms` | 数组：`windows` `mac` `linux` `steamdeck` `ios` `android` `switch` `playstation` `xbox` `web` `vr`（`pc` 为旧值，仍可用） |
| `stage` | `concept` 概念 / `development` 研发中 / `early-access` 抢先体验 / `released` 已发售 |
| `releaseDate` | 自由文本，如 `"2027 Q2"`（分语言） |
| `availability` | 主按钮：`unannounced` `coming-soon` `wishlist` `download` `store` `online`；**留空自动推导**（有网页版→在线游玩；有下载→下载；有商店链接→前往商店；否则“研发中 · 敬请期待”） |
| `requirements` | 客户端配置要求 `[{ "label": "操作系统", "minimum": "Windows 10", "recommended": "Windows 11" }]`（常用 6 行：操作系统 / 处理器 / 显卡 / 内存 / 存储空间 / 其他） |

**`course`**

| 字段 | 说明 |
|---|---|
| `level` | `beginner` 入门 / `intermediate` 进阶 / `advanced` 专业 |
| `duration` | “约 6 小时”（分语言） |
| `lessons` | 课时数（整数） |
| `format` | “互动网页 · 含练习”（分语言） |
| `audience` | 适合谁（分语言） |
| `chapters` | 大纲 `[{ "title", "summary", "duration" }]` |
| `price` | “免费”（分语言） |
| `entryUrl` | 学习入口；**留空 = 当前网页版 `/play/<slug>/`** |

**`engine`（engine 与 demo 共用）**

| 字段 | 说明 |
|---|---|
| `repoUrl` | GitHub 地址。**填了就自动同步**星标、许可证、语言、最新版本（每天一次 + 修改时立即）；summary 为空时用仓库描述填 |
| `npmPackage` | 如 `pelican-engine`，自动生成安装命令、同步 npm 最新版本 |
| `installCommand` | 留空 = `npm install <npmPackage>` |
| `docsUrl` / `homepage` | 文档、主页 |
| `codeSample` | `{ "language": "ts", "code": "…" }`（language 取 ts / js / sh），前台“代码”一节 |
| `builtWith` | 用它做的作品：作品 id 数组（2.1 接口里也可以直接写 slug） |
| `stats` | 只读，自动同步的结果 |

```bash
# 新建草稿（kind 决定栏目；template 由系统自动推导，不用管）
curl -s -X POST https://ninthmuse.cn/api/projects -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"星之庭","slug":"star-garden","kind":"game","summary":"一款关于种星星的小游戏","tags":["webgl"]}'

# 查询（按 slug）
curl -s "https://ninthmuse.cn/api/projects?where[slug][equals]=star-garden&depth=1" -H "$AUTH"

# 修改（用 id；只传要改的字段）
curl -s -X PATCH https://ninthmuse.cn/api/projects/<id> -H "$AUTH" -H 'Content-Type: application/json' -d '{"_status":"published"}'
# 只存草稿（不影响线上）：加 ?draft=true 并带 "_status":"draft"
curl -s -X PATCH "https://ninthmuse.cn/api/projects/<id>?draft=true" -H "$AUTH" -H 'Content-Type: application/json' -d '{"summary":"…","_status":"draft"}'
```

**作品和手记一样有草稿与版本**：新建默认是草稿，访客看不到；`?draft=true` 保存的修改只是新草稿，线上内容不变；PATCH `{"_status":"published"}`（后台的「发布修改」）才会让这一版上线。每次保存都留在版本历史里（最多 30 个）。推荐流程：新建草稿 → 用 2.1 的接口上传素材和信息 →（可选）上传网页版 / 下载文件（第 4 节）→ PATCH `{"_status":"published"}`。缺必需素材时发布会被拒绝（400）。

英文内容：在 URL 上加 `?locale=en` 再写同样的字段（标题、简介、卖点、链接名称、课程信息等都是中英双语的）。只会写入英文，中文保持不变；英文缺失时访客看到中文。默认语言是中文。

## 2.1 海报展示接口（每个作品必读）

**一个接口填完整个作品**：`POST https://ninthmuse.cn/api/projects/<slug>/showcase`（multipart）——
素材文件按槽位名上传，`gallery` 可重复上传多张画面，文字信息放在 `data`（JSON）里。`<slug>` 也可以用作品数字 id。

### 素材槽位

| 槽位（字段名） | 游戏 | 课程/引擎/演示 | 接受类型 | 规格 |
|---|---|---|---|---|
| `posterVideo` 动态海报视频 | **必需** | 可选 | video/mp4、video/webm | 16:9，1920×1080（最低 1280×720），6–15 秒无缝循环，无声，≤ 15 MB。**服务器自动转码**出 640 宽预览、1280 宽主版本和首帧图，不用你压缩 |
| `cover` 静态封面 | **必需**（转码首帧可代替） | **必需**（或 heroImage） | jpeg / webp / png | 16:9，≥ 1920 宽。**自动从它取色**生成作品页配色 |
| `heroImage` 详情页主视觉 | 推荐 | 推荐 | image/* | 16:9，≥ 2560 宽 |
| `logo` | 推荐 | 推荐 | png / svg / webp | 透明背景，横向，≥ 1200 宽 |
| `depthMap` 深度图 | 可选 | 可选 | image/* | 与 heroImage 同尺寸同构图，灰度，白=近 黑=远 |
| `foreground` 前景层 | 可选 | 可选 | png / webp | 与 heroImage 同构图，透明背景，只保留前景主体 |
| `ambientAudio` 环境音 | 可选 | 可选 | audio/* | 30–90 秒可循环，≤ 3 MB；默认静音 |
| `sceneModel` 3D 模型 | 可选 | 可选 | .glb | ≤ 20 MB，Y 轴向上；仅 C 模式 |
| `gallery`（可重复） | 推荐 | 推荐 | 图片或 mp4/webm | 画面一节，每个 ≤ 60 MB，总数 ≤ 40；默认追加，`galleryMode=replace` 替换 |

### `data` 字段（JSON，全部可选，只传要改的）

| 键 | 说明 |
|---|---|
| `title` `kind` `summary` | 同第 2 节 |
| `features` `links` | 同第 2 节（整体替换） |
| `gallery` | 媒体 id 数组：重新排序或删减已有画面 |
| `galleryMode` | `append`（默认）/ `replace` |
| `renderMode` | `cinematic`（默认）A 电影视频；`depth` B 2.5D 深度视差（需 heroImage + depthMap）；`scene` C 交互 3D 场景（再加 sceneModel） |
| `display` | 封面展示方式：`auto`（默认，按画面明暗：暗调满版，亮色的网页 / 界面截图在列表里装裱在深色衬底上）、`full` 满版、`framed` 装裱。详情页：`full` = 整屏海报，`framed` = 右侧画框；`auto` 时游戏整屏、课程 / 引擎 / 演示画框 |
| `tagline` | 海报标语，一句话（分语言） |
| `accent` | 手动强调色 `#rrggbb`；**一般不用填**，系统会从封面自动取色（`showcase.palette`） |
| `depthStrength` `focusX` | 0–1 视差强度；0–100 竖屏裁切水平焦点 |
| `game` | `{ genre, platforms, stage, releaseDate, availability, requirements }`（旧的 `storeLinks` 仍可用，会变成 kind=store 的 links） |
| `course` | `{ level, duration, lessons, format, audience, chapters, price, entryUrl }` |
| `engine` | `{ repoUrl, npmPackage, installCommand, docsUrl, homepage, codeSample, builtWith }`（builtWith 可写 slug）；改了 repoUrl / npmPackage 会立即同步统计，响应里有 `repoSync` |

### 例子

```bash
# 游戏：视频 + 封面 + 两张画面 + 信息
curl -s -X POST https://ninthmuse.cn/api/projects/star-garden/showcase -H "$AUTH" \
  -F 'posterVideo=@poster.mp4;type=video/mp4' \
  -F 'cover=@cover.jpg;type=image/jpeg' \
  -F 'logo=@logo.svg;type=image/svg+xml' \
  -F 'gallery=@shot1.jpg;type=image/jpeg' -F 'gallery=@shot2.jpg;type=image/jpeg' \
  -F 'data={"tagline":"在夜空里种下第一颗星","features":[{"title":"手绘星空","text":"每颗星都不同"}],"links":[{"label":"Steam","url":"https://store.steampowered.com/app/1","kind":"store"}],"game":{"genre":"叙事解谜","platforms":["windows","steamdeck"],"stage":"development","releaseDate":"2027 Q2","requirements":[{"label":"操作系统","minimum":"Windows 10","recommended":"Windows 11"}]}}'

# 课程：只要一张封面 + 课程信息
curl -s -X POST https://ninthmuse.cn/api/projects/game-design-course/showcase -H "$AUTH" \
  -F 'cover=@cover.jpg;type=image/jpeg' \
  -F 'data={"kind":"course","course":{"level":"beginner","duration":"约 6 小时","lessons":12,"price":"免费","chapters":[{"title":"第一章 · 什么是游戏","duration":"20 分钟"}]}}'

# 引擎：只传 JSON（不带文件时可以直接用 application/json）
curl -s -X POST https://ninthmuse.cn/api/projects/pelican-engine/showcase -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"kind":"engine","engine":{"repoUrl":"https://github.com/owner/repo","npmPackage":"pelican-engine","codeSample":{"language":"ts","code":"import { Engine } from \"pelican-engine\""}}}'
```

响应（GET 同样返回）：

```
{ project:{id,slug,kind,_status,pageUrl}, kind, slots:[{ slot, level, filled, media?, accepts, spec }],
  complete, missingRequired:["posterVideo","cover"], publishGate:{ok,note},
  showcase:{renderMode,display,tagline,accent,palette}, summary, features, links, gallery:[media…],
  game:{…}, course:{…}|null, engine:{…,stats}|null, uploaded, galleryAdded, replaced, next }
```

- **每次都读 `next`**，它告诉你下一步（缺什么、怎么上线）。
- 视频的 `media.transcode.status`：`pending` 排队中 → `done`（附 preview/main/poster 地址）/ `failed` / `skipped`（服务器没有 ffmpeg，前台用原文件）。转码在后台进行，不用等。
- 只传要改的槽位，没传的保持不变；重复上传同一槽位会替换（旧文件保留在媒体库，`replaced` 里会列出）。
- **文件类型不对会 400 `bad_type`**（会检查文件真实内容）；未知字段 400 `unknown_slot`；过大 413 `too_large`。
- **先预演**：加 `?dryRun=1`，只校验、不写入。
- **英文**：加 `?locale=en`，tagline、summary、features、links 名称、课程文字等写入英文；features / requirements / chapters 行数与中文相同时会自动对齐到同一行（中文不受影响）。
- 也可以直接 `PATCH https://ninthmuse.cn/api/projects/<id>` 修改这些字段（媒体字段填媒体 id，先用第 5 节上传）。
- 手动刷新仓库统计：`POST https://ninthmuse.cn/api/projects/<slug>/repo-sync`。
- 权限：只有作品的负责人 / 成员 / 管理员能上传（否则 403）。

### 上线门槛

作品**第一次**变成 published（包括新建时直接带 `"_status":"published"`）时按 kind 检查必需素材（见第 2 节表格），缺了返回 400，
`errors[0].data.errors[].message` 里写明缺哪个（中英文）。已上线过的作品之后的编辑不受影响。

### 推荐的 AI 流程

1. `POST /api/projects` 创建草稿（给 `title`、`slug`、`kind`、`summary`）。
2. `POST /api/projects/<slug>/showcase?dryRun=1` 预演，再去掉 dryRun 正式上传素材 + `data`（卖点、链接、类型信息）。
3. （可选）`POST /api/builds` 上传网页版 zip 或下载文件，把返回的 id 填进 `webBuild` / `downloads`（第 4 节）。课程的“开始学习”默认指向网页版。
4. 确认 `complete: true` 后 `PATCH /api/projects/<id>` `{"_status":"published"}`，把 `pageUrl` 告诉用户。

## 3. 页面区块（layout）

`layout` 是有序数组，每项有 `blockType`。**PATCH layout 会整体替换**，所以先 GET 当前 layout，改完再整体写回。

| blockType | 字段 | 说明 |
|---|---|---|
| `richText` | `markdown`（写入用） | 正文。**直接传 Markdown**，服务端转换 |
| `hero` | `heading`、`subheading`、`media`(媒体ID)、`ctaLabel`、`ctaUrl` | 旧版主视觉区块（产品页顶部现在由海报素材驱动，一般不需要） |
| `gallery` | `items: [{media, caption}]` | 图集 |
| `video` | `url`（B站/YouTube 等）或 `media`、`caption` | 视频 |
| `features` | `heading`、`items: [{icon, title, description}]` | 卖点列表，icon 可以是 emoji |
| `playable` | `display`: `embed`/`link`，`aspectRatio`: `16x9`/`4x3`/`1x1`/`fill`，`label` | 在线游玩当前上线的网页版（自动） |
| `downloads` | `heading`、`note` | 已发布版本的 `downloads`（自动） |
| `links` | `items: [{label, url, style: primary/secondary}]` | 链接按钮 |
| `changelog` | `heading`、`limit` | 最近更新日期（v6 起没有版本说明；历史见版本记录） |
| `repoCard` | `heading` | 仓库信息卡（来自 `engine.repoUrl` / repo 链接与同步的统计，自动） |
| `relatedPosts` | `heading`、`limit` | 关联本作品的手记（自动） |
| `faq` | `items: [{question, answer}]` | 常见问题 |
| `subprojects` | `heading`、`projects: [项目ID...]` | 合集的子项目 |

示例：

```json
{ "layout": [
  { "blockType": "playable", "display": "embed", "aspectRatio": "16x9" },
  { "blockType": "richText", "markdown": "## 玩法\n\n- 点击种星\n- 连线成座" },
  { "blockType": "features", "items": [{ "icon": "✨", "title": "手绘星空", "description": "每颗星都不同" }] },
  { "blockType": "changelog" }, { "blockType": "downloads" }
] }
```

## 4. 网页版、下载文件与回滚

和后台作品的「发布」标签页完全相同：先把文件传到隐藏的上传集合 `builds`，再在作品上引用它，**发布作品时**网页版才上线。

### 4.1 网页版（可在线游玩 / 浏览）

把构建产物（含 `index.html` 的文件夹，如 Vite 的 `dist/`）打成 zip：

```bash
# 打包：zip 文件夹本身或其内容都可以，外层单个文件夹会自动去掉
cd dist && zip -r ../build.zip . && cd ..        # Windows: Compress-Archive dist\* build.zip

# 1) 上传（multipart 字段 file）
curl -s -X POST https://ninthmuse.cn/api/builds -H "$AUTH" -F 'file=@build.zip'
# → 201 { doc: { id, kind:"web", sha256, report:{ ok, entry:"index.html", fileCount, sizeBytes, warnings:[...] } } }

# 2) 引用并发布（就是后台的「发布修改」）
curl -s -X PATCH https://ninthmuse.cn/api/projects/<id> -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"webBuild": <buildId>, "_status": "published"}'
# → 网页版在 https://ninthmuse.cn/play/<slug>/ 上线（旧路径 https://ninthmuse.cn/<slug>/ 同步）

# 现在线上是哪个构建
curl -s https://ninthmuse.cn/api/projects/<id>/live -H "$AUTH"     # → { live: { build, entry, url } | null }
```

- `report.entry` 为 null 表示 zip 根目录没有 `index.html`：发布时带上 `"entry": "game/index.html"`（要打开的 HTML 的相对路径）。
- 发布时服务器把 zip 解压一次（`sites/<slug>/b<buildId>/`）并检查入口文件，失败返回 400，错误在 `webBuild` 字段上，线上内容不变。
- 只存草稿（`PATCH …?draft=true` 带 `"_status":"draft"`）**不会**改变线上内容；团队预览任意构建：`https://ninthmuse.cn/play/<slug>@<buildId>/`（需登录）。
- **重要**：网页必须使用相对路径。Vite 设 `base: './'`；否则报告里会有 `absolute_paths` 警告（旧站路径 `/<slug>/` 能兜住一部分）。

### 4.2 下载文件（安装包、压缩包、PDF…）

```bash
curl -s -X POST https://ninthmuse.cn/api/builds -H "$AUTH" -F 'file=@StarGarden-1.2.0-win.zip'      # → { doc: { id, kind:"file" } }
curl -s -X PATCH https://ninthmuse.cn/api/projects/<id> -H "$AUTH" -H 'Content-Type: application/json' -d '{
  "downloads": [
    { "label": "Windows 版", "platform": "windows", "build": <buildId>, "note": "v1.2 · 64 位" },
    { "label": "Steam", "url": "https://store.steampowered.com/app/…" }
  ],
  "_status": "published"
}'
```

每一行是上传的文件（`build`）或外部链接（`url`，只接受 http/https）；`label`、`note` 分语言；`platform` 取 `pc windows mac linux steamdeck ios android switch playstation xbox web vr`。上传的文件在 `https://ninthmuse.cn/dl/<buildId>/<文件名>` 下载——只有已发布的版本里列出的文件才能下载。

### 4.3 版本历史与回滚

```bash
curl -s "https://ninthmuse.cn/api/projects/versions?where[parent][equals]=<id>&sort=-updatedAt&limit=10&depth=0" -H "$AUTH"
# → docs:[{ id, updatedAt, version:{ _status, webBuild, downloads, title, … } }]
curl -s -X POST https://ninthmuse.cn/api/projects/versions/<versionId> -H "$AUTH"     # 恢复这个版本（= 回滚，立即切换网页版）
```

保留：任何一个保存过的版本引用的构建都会保留；没有被引用的上传在 24 小时后由每日维护清理。

## 5. 图片与视频

```bash
curl -s -X POST https://ninthmuse.cn/api/media -H "$AUTH" \
  -F 'file=@cover.png' -F '_payload={"alt":"星之庭封面"}'
# → { doc: { id, url, sizes:{thumb,card,large} } }   把 id 用在 coverSquare / hero.media / gallery 里（海报素材用 2.1 的 showcase 接口更省事）。图片、视频、音频、.glb 都可上传，公开地址是 `https://ninthmuse.cn/m/<filename>`（支持 Range）
```

## 6. 手记（文章）

```bash
curl -s -X POST https://ninthmuse.cn/api/posts -H "$AUTH" -H 'Content-Type: application/json' -d '{
  "title": "星之庭 1.2 开发日志",
  "slug": "star-garden-devlog-1-2",
  "excerpt": "这次我们重做了跳跃手感",
  "markdown": "## 改了什么\n\n...",
  "project": <项目ID>,
  "tags": ["devlog"],
  "_status": "published"
}'
```

- `markdown` 会转换为富文本；不传 `_status` 时保存为草稿。
- 发布后的地址：`https://ninthmuse.cn/journal/<slug>`。
- 修改：`PATCH https://ninthmuse.cn/api/posts/<id>`。你只能改自己写的文章。
- `tags`（作品与手记都有）：自由文本，保存时自动去空格、去重（不分大小写）、最多 20 个。见 8.1 的搜索与标签接口。

## 7. 代码仓库

v6 起不再绑定 / 同步仓库（仓库源、Webhook、CI 已移除）：发布就是第 4 节的上传 + 发布。引擎和演示的 GitHub / npm 统计照常工作——填 `engine.repoUrl`（或在 `links` 里加一条 `kind: "repo"` 的 GitHub 链接）和 `engine.npmPackage`，保存后自动同步，每天再同步一次；手动：`POST https://ninthmuse.cn/api/projects/<slug>/repo-sync`。

## 8. 其他

### 8.1 评论、搜索与标签

评论系统服务所有对象：作品（游戏 / 课程 / 引擎 / 演示）、手记、留言板。公开接口，不需要密钥（访客发表需要人机验证，见 1.2 的解题方式；登录成员发表不需要）。

```bash
# 某对象的评论（树形：顶层评论 + 每条的 replies；回复的回复也挂在顶层下，带 replyTo 昵称）
curl -s "https://ninthmuse.cn/api/interact/comments?target=projects&targetId=<作品ID>"        # target: projects | posts | guestbook（留言板 targetId=0）
# 发表（访客：altcha 是解好的人机验证；成员带密钥则自动标记为「团队」并免验证）
curl -s -X POST https://ninthmuse.cn/api/interact/comments -H 'Content-Type: application/json' -d '{
  "target": "projects", "targetId": <作品ID>, "name": "昵称", "content": "内容",
  "email": "可选，公开显示（也用于头像）", "parent": <回复的评论ID，可选，须同一对象>, "quote": <引用的评论ID，可选，须可见>,
  "altcha": "<解好的题>"
}'
curl -s -X POST https://ninthmuse.cn/api/interact/comments/<评论ID>/like      # 点赞，同一地址只算一次，返回 {liked, likes}
curl -s "https://ninthmuse.cn/api/interact/feed?page=1&limit=20&target=projects"  # 全站最新评论，每条带 source{kind,title,href} 和 href=<页面>#comment-<id>
```

- 评论节点：`{id, name, email, avatar, content, createdAt, isTeam, author, likes, replyTo, quote:{id,name,excerpt,href}|null, replies[]}`；团队成员发表的评论 `author` 是人物 `{id, name, title, avatar, href}`（访客为 null）。**访客填写的邮箱是公开的**（`email`，没填为 null）；团队回复的 `email` 永远是 null（成员账号邮箱只用于头像）。头像用不可逆的 `emailHash`（小写邮箱的 md5）。
- 头像：`https://ninthmuse.cn/avatar/<md5(小写邮箱)>?s=80&n=<昵称>`（服务端取 Cravatar 并缓存，没有就返回按昵称生成的默认头像）；`https://ninthmuse.cn/avatar/default?n=<昵称>`。
- 以团队身份回复：带 API 密钥调用上面的 POST 即可（`parent` 填被回复的评论 ID）。后台评论详情页的「以团队身份回复」调用的是同一个接口。
- 搜索：`GET https://ninthmuse.cn/api/search?q=<词>&kind=<game|course|engine|demo|post>&tag=<标签>&page=1&limit=24&locale=zh` → `{docs:[{type,id,kind,title,summary,tags,genre,href,thumb}], total, facets:{kinds, tags:[{tag,count}]}}`。只含已上线的公开内容；匹配标题（中英）、简介、标语、类型、标签、课程章节标题、手记标题与摘要。
- 全部标签：`GET https://ninthmuse.cn/api/tags` → `{tags:[{tag,count}]}`（作品与手记合计）。

### 8.2 页面（含关于页）、人物、背景音乐、社交链接（v5）

- **语言**：后台顶栏只有一个语言切换，同时切换界面语言与内容语言。接口里本地化字段用 `?locale=zh|en` 读写（例如 `PATCH https://ninthmuse.cn/api/users/<id>?locale=en` 写英文头衔）。
- **人物**：成员（`/api/users`）有 `name`、`title`（头衔，本地化）、`bio`（简介，本地化）、`avatar`（上传的媒体，可选）、`showOnTeamPage`（是否列在关于页）、`slug`（成员主页 `/team/<slug>`，留空按名称生成，唯一）。全站统一的人物形状 `PersonRef = {id, name, title, avatar, href}`：`avatar` 依次是上传头像 → 账号邮箱的 Cravatar（`/avatar/<md5>`，邮箱本身不公开）→ 默认头像；`href` = `/team/<slug>`。作品制作人员、手记作者、团队评论的 `author`、关于页团队卡片都用它。成员主页列出头像、名字、头衔、简介、链接、参与的作品与写的手记。
- **关于页**：`https://ninthmuse.cn/about` 的全部内容来自页面 `about`（`/api/pages`，slug=about，layout 按语言分别保存：`PATCH https://ninthmuse.cn/api/pages/<id>?locale=en`）。除第 3 节的通用区块外，页面还有：

| blockType | 字段 | 说明 |
|---|---|---|
| `team` | `heading`、`intro` | 自动列出所有 `showOnTeamPage` 的成员（头像、头衔、简介、参与作品），无需手填 |
| `contact` | `heading`、`intro`、`showEmail`、`showSocial` | 读取站点设置里的联系邮箱与社交链接 |

  默认内容极简：`richText`（一段工作室介绍）+ `team` + `contact`。
- **首页与页头（v6）**：全局 `site-settings` 的 `favicon`（媒体）、`headerCta: {label, url}`、`home: {eyebrow, subtitle, stageWorks, stageSeconds}`（v10 首屏舞台：`subtitle` 是首屏标语；`stageWorks` 是作品 id 数组，按顺序整屏轮播，最多 8 个，与 `featured` 无关、不限类型，建议只放画面强的游戏和演示，留空 = 有海报视频的精选作品；`stageSeconds` 每个作品停留 4–30 秒，默认 9。旧的 `title intro ctaLabel ctaUrl reel hallTiles cards` 仍可读写但前台不再使用）、`pageIntros: [{page, title, intro}]`（`page` 取 `games courses engines demos journal guestbook about team search`）。文字字段分语言（`?locale=en`）。v7 首页第二屏：`home.worksTitle`、`home.worksIntro`、`home.about: {image, eyebrow, title, text, ctaLabel}`（image 为媒体 id，只用这里设置的插图）、`home.links: [{target, title, description, url}]`（target 同上）。`headerCta.label` 留空 = 页头不显示按钮。默认值：`scripts/seed-v6.mjs`、`scripts/seed-v7.mjs`。
- **社交链接**：全局 `site-settings`（`https://ninthmuse.cn/api/globals/site-settings`）的 `social: [{platform, url, label?}]`，platform 取 `github bilibili youtube x weibo email discord other`（旧值会自动归一）。
- **背景音乐**：同一全局的 `music`：`enabled`、`defaultVolume`(0–1，默认 0.35)、`autoplay`(`load` 默认：页面加载好就播放，浏览器拦截时在访客第一次点击 / 按键 / 触摸时开始；`first-interaction`；`off`)、`order`(`sequential`/`shuffle`)、`loop`、`pages`(`all`/`home-only`)、`pauseOnMedia`、`tracks: [{title, artist?, source: upload|url|netease, file?(音频媒体ID), url?(http/https), neteaseId?(数字)}]`。公开读取：

```bash
curl -s https://ninthmuse.cn/api/site/music
# → { enabled, defaultVolume, autoplay, order, loop, pages, pauseOnMedia, tracks: [{ title, artist, src }] }
```

  `src` 已解析好：上传的音频是 `/m/<文件名>`，外链原样，网易云是 `https://music.163.com/song/media/outer/url?id=<id>.mp3`（仅免费曲目可播）。没有可播曲目时 `enabled` 为 false。
- **标签译名**：标签是自由文本（原文存储，通常是中文）。全局 `site-settings` 的 `tagLabels: [{tag, en}]` 给每个标签配英文名称（`tag` 不分大小写唯一）。`locale=en` 时，`/api/tags`、`/api/search`（结果的 `tags` 与 `facets.tags`）以及前台所有标签都显示英文名称，没有译名则显示原文；`/api/search?tag=` 接受原文或英文名称（不分大小写）。没有英文名称的标签会列在后台仪表盘「待补素材」里，并在标签输入框下提示（`GET /api/admin/dashboard` 的 `tagsMissingEn`）。新标签写入后，用 `scripts/seed-tag-labels.mjs` 或直接 PATCH 全局补译名。
- **删除评论**：`DELETE https://ninthmuse.cn/api/comments/<id>`（仅管理员；批量 `DELETE https://ninthmuse.cn/api/comments?where[id][in]=1,2,3`）。该评论的点赞一并删除，它的回复与引用保留（回复变为独立评论，引用被清除）；删除、隐藏、通过都会写入操作记录（`/api/audit-logs`，action 为 `delete` `hide` `approve` `hold`）。

### 8.3 其他

- 评论审核：`POST https://ninthmuse.cn/api/comments/<id>/moderate` body `{"status":"visible|pending|hidden"}`（任何成员）。
- 数据看板（作品数、浏览 / 点赞 / 评论、近 30 天趋势、热门作品、待补素材、系统状态）：`GET https://ninthmuse.cn/api/admin/dashboard`，与后台首页同一份数据。
- 重新转码失败 / 跳过的视频：`POST https://ninthmuse.cn/api/media/<id>/retranscode`（202，成员可用）。
- 立即维护（备份 + 清理未引用的构建 + 链接巡检）：`POST https://ninthmuse.cn/api/maintenance/run`；只备份：`POST https://ninthmuse.cn/api/maintenance/backup`；备份列表：`GET https://ninthmuse.cn/api/maintenance/backups`（均仅管理员）。备份是数据目录里的 `backups/<时间>/`（数据库快照 + 媒体 / 构建 / 网页版的硬链接快照 + manifest），保留 7 份。刷新 GitHub / npm 统计：`POST https://ninthmuse.cn/api/projects/<slug>/repo-sync`。
- 后台每个按钮调用的都是上面这些接口，界面能做的事 AI 都能做（对照表见仓库 docs/ARCHITECTURE.md）。
- 通用增删改查：`GET/POST https://ninthmuse.cn/api/<collection>`、`GET/PATCH/DELETE https://ninthmuse.cn/api/<collection>/<id>`，collection 包括 `projects` `builds` `posts` `pages` `media` `users`；查询语法 `?where[field][equals]=value&limit=10&sort=-createdAt&depth=1`。
- 自动化 / CI 同样用 API 密钥（见 1.1）。
- 视频上传后服务器自动转码（预览 640 宽、主版本 1280 宽、首帧图），媒体文档的 `variants` 字段记录结果。
- 健康检查：`GET https://ninthmuse.cn/api/health`。
