Ninth Museagent.md

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

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

公开网址(给用户看的链接):

内容网址
游戏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 <密钥>

密钥从哪来:

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课程/coursescover 或 heroImage
engine引擎与工具/enginescover 或 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 的接口上传最方便
_statusdraft 草稿 / 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 为旧值,仍可用)
stageconcept 概念 / 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

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

engine(engine 与 demo 共用)

字段说明
repoUrlGitHub 地址。填了就自动同步星标、许可证、语言、最新版本(每天一次 + 修改时立即);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/webm16:9,1920×1080(最低 1280×720),6–15 秒无缝循环,无声,≤ 15 MB。服务器自动转码出 640 宽预览、1280 宽主版本和首帧图,不用你压缩
cover 静态封面必需(转码首帧可代替)必需(或 heroImage)jpeg / webp / png16: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 数组:重新排序或删减已有画面
galleryModeappend(默认)/ replace
renderModecinematic(默认)A 电影视频;depth B 2.5D 深度视差(需 heroImage + depthMap);scene C 交互 3D 场景(再加 sceneModel)
display封面展示方式:auto(默认,按画面明暗:暗调满版,亮色的网页 / 界面截图在列表里装裱在深色衬底上)、full 满版、framed 装裱。详情页:full = 整屏海报,framed = 右侧画框;auto 时游戏整屏、课程 / 引擎 / 演示画框
tagline海报标语,一句话(分语言)
accent手动强调色 #rrggbb;一般不用填,系统会从封面自动取色(showcase.palette)
depthStrength focusX0–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 }

上线门槛

作品第一次变成 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字段说明
richTextmarkdown(写入用)正文。直接传 Markdown,服务端转换
heroheading、subheading、media(媒体ID)、ctaLabel、ctaUrl旧版主视觉区块(产品页顶部现在由海报素材驱动,一般不需要)
galleryitems: [{media, caption}]图集
videourl(B站/YouTube 等)或 media、caption视频
featuresheading、items: [{icon, title, description}]卖点列表,icon 可以是 emoji
playabledisplay: embed/link,aspectRatio: 16x9/4x3/1x1/fill,label在线游玩当前上线的网页版(自动)
downloadsheading、note已发布版本的 downloads(自动)
linksitems: [{label, url, style: primary/secondary}]链接按钮
changelogheading、limit最近更新日期(v6 起没有版本说明;历史见版本记录)
repoCardheading仓库信息卡(来自 engine.repoUrl / repo 链接与同步的统计,自动)
relatedPostsheading、limit关联本作品的手记(自动)
faqitems: [{question, answer}]常见问题
subprojectsheading、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 }

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"
}'

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>

8.2 页面(含关于页)、人物、背景音乐、社交链接(v5)

blockType字段说明
teamheading、intro自动列出所有 showOnTeamPage 的成员(头像、头衔、简介、参与作品),无需手填
contactheading、intro、showEmail、showSocial读取站点设置里的联系邮箱与社交链接

默认内容极简:richText(一段工作室介绍)+ team + contact。

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。

8.3 其他