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. 规则
- 只操作用户要求的内容。 你只能修改自己参与的作品(接口会拒绝其它作品)。
- 上线、回滚前先预演:加
?dryRun=1,把预演结果告诉用户,确认后再正式执行(用户已明确让你直接发布时可跳过)。 - 校验报告里的 warnings 要告诉用户,尤其是
absolute_paths(网页会白屏)。 - 写操作建议带
Idempotency-Key: <随机串>头,网络重试不会重复发布。 - 自定义接口出错时响应是
{ "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),然后给自己生成一个,之后一直用它:
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:
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+):
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>
看看你是谁、能管理哪些作品:
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 | 只读,自动同步的结果 |
# 新建草稿(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 |
例子
# 游戏:视频 + 封面 + 两张画面 + 信息
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(会检查文件真实内容);未知字段 400unknown_slot;过大 413too_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 流程
POST /api/projects创建草稿(给title、slug、kind、summary)。POST /api/projects/<slug>/showcase?dryRun=1预演,再去掉 dryRun 正式上传素材 +data(卖点、链接、类型信息)。- (可选)
POST /api/builds上传网页版 zip 或下载文件,把返回的 id 填进webBuild/downloads(第 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...] | 合集的子项目 |
示例:
{ "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:
# 打包: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…)
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 版本历史与回滚
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. 图片与视频
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. 手记(文章)
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 的解题方式;登录成员发表不需要)。
# 某对象的评论(树形:顶层评论 + 每条的 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?(数字)}]。公开读取:
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 为deletehideapprovehold)。
8.3 其他
- 评论审核:
POST https://ninthmuse.cn/api/comments/<id>/moderatebody{"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 包括projectsbuildspostspagesmediausers;查询语法?where[field][equals]=value&limit=10&sort=-createdAt&depth=1。 - 自动化 / CI 同样用 API 密钥(见 1.1)。
- 视频上传后服务器自动转码(预览 640 宽、主版本 1280 宽、首帧图),媒体文档的
variants字段记录结果。 - 健康检查:
GET https://ninthmuse.cn/api/health。