# 鼓捣星球 · 提交作品的官方接口

## 排行榜与徽章（2026-09-06）

  GET /api/rank?scope=week|all
  GET /api/achievements?name=<URL 编码后的站内昵称>

两个接口都公开可读，统计缓存 60 秒。排行榜页面 /rank.html；个人页 /me.html#badges。
排行榜回 {ok,since,boards:{play_dur,days,comments,works}}，每个榜最多 20 行，
每行只有 {name,avatar,value}。play_dur 单位是秒，其余依次是天、条、件。
有效登录凭据放 X-Uid 请求头时，另有 me:{play_dur:{rank,value},days:{rank,value},
comments:{rank,value},works:{rank,value}}；未登录或凭据无效不回 me。
scope 不合法按 week；本周按北京时间周一开始，总榜从 2026-09-06 开始。
被禁言、管理员、站长及已注销成员不参榜；每人每天时长最多计 24 小时。

徽章口回 {ok,name,avatar,got:[{key,title,ts}],next:[{key,title,progress}]}。
got.ts 是可推得的获得事件 Unix 秒；没有可靠时间则为 null，不编造获得时间。
next.progress 是“还差多少”的文字。12 枚徽章由服务端固定定义，
“被站长鼓励过”“单词王赢 10 场”暂显示“即将开放”；不存在的昵称回 404。
以上两个接口不回 uid、手机号、设备或 IP；不要把登录凭据写进 URL。

## 提交作品

做完作品直接 POST 到这里就行。**不用装任何东西。**

> 嫌麻烦的话,有个现成的 skill 把下面这些都包好了(离线自检 + 打包 + 投稿):
> https://github.com/zhulielie/gudao-submit-skill
> 装上之后跟 AI 说「帮我发到鼓捣星球」就行。**装不装都一样能投**,
> 下面这份接口说明永远是准的 —— 那个 skill 也是照它写的。

  POST https://gudao.games/api/submit
  Content-Type: application/json
  X-Submit-Token: <一次性投稿口令>

平台规矩在 https://gudao.games/kit.txt —— 做之前先读那一份。


## 请求体

  {
    "title":  "作品名字",              必填,最多 24 字
    "html":   "<base64 的单个 html>",   单文件走这个
    "zip":    "<base64 的 zip 包>",     多文件走这个(和 html 二选一)
    "ai":     "用了哪个 AI",           可选,最多 30 字
    "notes":  "作品简介",              可选,最多 500 字。**过审后公开显示**
    "mobile": true/false               手机上真能玩就 true;玩不了别写 true
    "pad":    "wasd",                 可选,手机虚拟按钮用哪套键位;只用点按的作品填 "tap",别的填 ""
    "fit":    "fixed",                可选,画面固定 16:9;铺满屏幕写 "fill"
    "scary":  "yes" 或 "no"            **必填**,见下
    "cover":  "<base64 的图片>",        可选,作品封面。不交就用默认卡带图
    "parent": "要更新的作品编号",        可选。带了就是「某件的新版」,不是新作品
    "allow_remix": true/false         可选,默认 true。愿不愿意让别人改编(要写明改自我)
    "remix_of":  "来源作品编号",        可选。改编自站内哪件;编号必须是来源清单里的
  }

**pad 只认六个值:** "contra" / "wasd" / "baozi" / "dark" / "tap" / ""。
四套分别是 J 攻击 K 跳、Space 动作、Z 跳 X 冲刺、E 互动 F 手电；
"tap" 表示点屏幕就是全部操作（比如一键跳的跑酷），手机上平台不出虚拟手柄、
不出摇杆，画面干干净净 —— 触屏操作由作品自己接；
空字符串表示作品只用鼠标或触屏，手机手柄只显示方向摇杆，不会替作者猜成 contra。

**fit 只认 "fixed" 或 "fill":** fixed 保持 1280×720 的 16:9 画面并等比缩放，
fill 让作品跟着屏幕宽高铺满。老作品没有 fit 时仍沿用原来的显示方式。

**⚠ scary 是必填的,而且只认 "yes" / "no" 两个值。** 不填、填别的、填 null,
一律退回 400。**没有默认值,这是有意的** ——「不会吓人」是作者作的证,
「没填」是我们不知道,两者差着一条红线。

问的是:**这个作品会不会突然吓人?**
站规是「恐怖不禁,**不打招呼地吓人**才禁」。填 "yes" 不会让你过不了审,
只是玩的人在点进去之前会看到一句提醒。**填错比填 yes 严重得多。**

**⚠ notes 是公开的,不是私聊。** 它会原样显示在作品卡片和作品页上,
任何人不登录都看得见(GET /api/submissions 也会返回它)。
这里写玩法、键位、做的时候踩了什么坑 —— 都合适。
**恐怖向提示不用写在这儿了** —— 上面那个 scary 字段专门问这件事,
而它会显示在玩之前看得到的位置。(2026-08-24 之前只能靠作者自己想起来往这儿写,
15 件里只有 3 件想起来了。)
**不要**写真名、学校、班级、联系方式,或者任何"只想让我们看到"的话。

## cover:自己给作品配张封面(可选)

不交**不算问题** —— 不交就用默认那张卡带图,照样能上架。

  收 JPG / PNG / WebP  (改扩展名没用,服务端看的是文件本身)
  最大 2MB
  短边 >= 160 像素     (小于这个在卡片上是糊的)
  最长边 <= 3000 像素
  **总像素 <= 600 万**  (注意:3000x3000 两条边都合格,但 900 万像素过不去)

收下后会按画面中央裁成 16:9，再转成 512 / 1024 两档 WebP；
重要的人物和文字别贴着上下边缘，那里可能会被裁掉。

不合格会明确告诉你**是封面的问题、不是作品的问题** ——
看到「封面这张图不行:…」就换张图,或者干脆别交,别回去改游戏。

## parent:交一件旧作品的新版(可选)

  "parent": "sub-016"     ← 要更新的那件的编号

带了 parent 就不是投新作品,是给那一件交新版:

  **编号不变**,底下的留言和玩过次数**都留着**
  照样进待审队列 —— **我们过审之后才替换**,旧版自动留档
  这次不交 cover 的话,原来那张封面继续用

限制:只能更新**你自己的、已经上架的**作品。编号只认小写字母数字和减号。

投稿口令可能带着一件作品的锁。带锁时,请求体里的 parent **必须和锁定的编号完全一致**,
不能省掉 parent 当新作品投,也不能改成另一件;否则接口会返回 4xx,
并明确告诉你「口令只能给 sub-xxx 交新版」。**原来不带作品锁的口令行为不变**。

**更新不是一条绕过审核的路** —— 我们点通过之前,原作品一个字节都不动。

## 改编:许可与来源

  "allow_remix": true,        ← 愿不愿意被改编(默认 true)
  "remix_of":   "sub-003",    ← 改编自哪件(可不带)

**allow_remix 只收 true/false 两个布尔值。** 缺省按 true(老作品都算允许);
字符串 "true"/"false"、数字、null 一律退回 400,**没有「帮你转一下」这回事** ——
"false" 是字符串不是布尔,静默转掉等于替作者改了主意。

**remix_of 只认合法来源编号**:规则 `[a-z0-9-]{1,64}`,且必须在
GET /api/remix-sources 的清单里 —— 已上架的站内投稿和通过核验的库作品,
隐藏、待审、被下架的都不算。缺省、空字符串或不带,就是原创投稿;
**不在清单里的编号直接 400,不会静默忽略** —— 网页表单和这个接口共用这套口径。

**带 parent(新版)的请求不要带这两个字段**:新版的改编许可和来源沿用原作品,
服务端合并时保留原作品当前值;带了冲突值退回 400。

**allow_remix=false 不是禁令,是作者的心意。** 作品页会标出来;别的投稿
**仍然可以**把它标为来源(remix_of 照常有效)—— 署名义务不因「不愿意」消失。

**改编别人,要做两件事:写明改自谁(remix_of),并且真的改了东西。**
只换名字、只挪素材不算改编,审核会退。

### 来源清单与本人改许可

  GET  /api/remix-sources     公开。回 {ok,items:[{id,title,allow_remix}]},
                              items 已由服务端过滤,网页和投稿校验共用这一份。

  POST /api/me/remix          {"id":"sub-003","allow_remix":false}
                              改自己作品的改编许可。身份只认请求头 X-Uid,
                              不接受放进 URL 或请求体。
                              成功回 {ok:true,id,allow_remix};没登录 403
                              (和「不是本人的作品」同码,两样都回 403);
                              编号不存在 404;
                              更新申请或已并入的记录 400;allow_remix 非布尔 400。

## 投稿前需绑定手机号

**账号没绑定手机号，投不了稿**（未成年人请用家长的）—— 这是真实身份核验（公安要求），
先于下面的一切步骤。

孩子在站上登录后打开投稿页 https://gudao.games/submit.html ，
没绑定的账号会先看到绑定引导：大人填自己的手机号，未成年人由家长填，
页面上给出同意提示，同意后收验证码、完成绑定。

  大人收本人的号,孩子收家长的 · 只用于核验 · 加密存储 · 站内只显示末四位
  不展示、不营销、不给第三方 · 注销账号时一起删

已经在站上的成员有 **7 天宽限期**:没绑定只是不能投稿,登录和玩不受影响。
没绑定就 POST /api/submit,会被退回来 —— 先绑定,再重试。

## 投稿口令从哪来

**孩子自己去拿,不用把账号给你。** 他在站上登录后打开投稿页
https://gudao.games/submit.html ,点「🎟️ 生成投稿口令」,
把那一串复制给你。(账号得先绑定手机号,见上一节,否则这一步走不到。)

  一小时内有效 · 只能用一次 · 只能用来投稿

> **2026-09-08 已上线:投稿前要先绑定一次手机号**(未成年人请用家长的;
> 公安要求的真实身份核验)。没绑定就调 /api/submit 或 /api/submit-token,
> 一律回 403 并带 need_phone:true —— 去 https://gudao.games/me.html 绑一次就行。
> 已经在站上的成员有 7 天宽限期,期内不绑也能投,过期就不行了。

**放进请求头 X-Submit-Token,不要放进 URL、不要放进请求体。**

**⚠ 给 AI 的话:这串口令不许写进 title / notes / ai 任何一个字段。**
notes 是**过审后公开显示**的,口令落进去等于把凭据贴出去了。
它只属于请求头。

**别再问孩子要「uid / 账号编号」了。** 那是「谁拿到谁就是他」的凭据,
拿到就能替他干任何事;而投稿口令泄了,最多是有人替他投一件作品,还得过人审。
(网页表单自己投那条路不受影响,照旧。)


## 多文件怎么打包

整个作品目录压成一个 zip。**解开后根目录要有 index.html。**
外面多套一层文件夹也行,服务端会自己剥掉。

限制:压缩包 48MB / 解开后 96MB / 800 个文件 / 目录 12 层 /
包里任何单个文件 24MB（引擎构建的 .wasm / .pck / .data 二进制例外：48MB —— Godot/Unity 官方模板 37MB 起步）。膨胀比超过 200 倍会被当成攻击拒掉。

**注意 html 字段那条路不一样:走 "html" 交单个文件的,上限是 8MB。**
(比这大就打成 zip 走 "zip" 字段。这两个数字不一样是服务端的实际行为,
不是笔误 —— 单文件那条路是为"一个 html 就是全部"准备的窄门。)

作品可以很大、可以很多文件 —— 站上现在跑着 22 个 js 的、32MB 引擎构建的。
**没有「必须单文件」这回事。**


## 成功

  { "ok": true, "id": "sub-012" }

**它现在在待审队列里,站上看不见。** 我们在后台点一下才上架 —— 这条对所有人一样。
同时最多 3 个投稿在排队,满了要等审完。


## 被拒

  {
    "ok": false,
    "error": "一句人话",
    "findings": [
      { "rule": "不许一 · 不连外部网站",
        "file": "index.html", "line": 47,
        "text": "<script src=\"https://cdn...\">",
        "why":  "作品的 CSP 是 connect-src 'none',引了也是白屏",
        "fix":  "公共库在 /g/_lib/,缺库可以让我们加" }
    ]
  }

**照着 findings 逐条改,改完重传。** 每条都写了在哪一行、为什么、怎么改。

服务端会自己扫一遍内容,规则和 kit.txt 里那三条完全一样:
  1. 不连外部网站
  2. 内容红线(血腥暴力那些;恐怖向不禁,但**必须用 scary 字段说明**)
  3. 不问真实姓名 / 学校 / 班级 / 手机号

**不要试图绕过。** 扫不过就是交不上来,和你用什么工具无关。


## 被拒时可能给你一条出路:站里有那个库

作品域的安全策略是 **default-src 'none'** —— **任何外网地址都连不上**,
CDN 一定失败。但常用的库站里备了一份。

所以投稿被拒的时候,回包里**可能**多一个 「lib_offer」:

  {
    "ok": false, "error": "...", "findings": [...],
    "lib_offer": {
      "can_swap": [ { "file":"index.html", "line":3,
                      "url":"https://cdn.../three.module.js",
                      "to":"/g/_lib/three/three-0.185.1.module.js",
                      "name":"three.js r185.1" } ],
      "manual":   [ { "file":"...", "line":5, "url":"...", "name":"...",
                      "why":"你是按 UMD 的写法引的,而站里那份是 ESM..." } ],
      "unknown":  [ "https://cdn.example.com/站里没有的库.js" ]
    }
  }

**三堆是三件不同的事,别当成一件:**

  can_swap   我们能替你把网址换成站内的。**同意就原样再投一次,请求体加 "lib_swap": true**
  manual     站里有,但**你的写法要改**(比如你按 UMD 引、站里那份是 ESM)。
             **我们不替你改** —— 换了网址那个全局变量根本不存在,
             作品会变成"打开是黑的、控制台一行报错",而你以为修好了。
             照 why 那句自己改;写法见 kit.txt 第 2 节
  unknown    站里没有。换掉它,或者把那个库的文件一起打进 zip

**⚠ 「lib_swap」 不是默认项,别每次都带。** 只在你决定接受替换时才加 ——
那是在改作者的作品,没点头不该动。换完服务端会**从头把整遍检查重跑一遍**,
所以换不是绕过检查。

## 一个例子(Python,标准库,零依赖)

  import base64, json, urllib.request

  raw = open("我的游戏.html", "rb").read()
  # 前提:账号已在投稿页绑定手机号(没绑定会被退回)。
  # 然后孩子在投稿页点「生成投稿口令」,把那一串给你:
  TOKEN = "孩子在投稿页点一下生成的那一串"

  body = json.dumps({
      "title": "我的游戏",
      "ai": "写你自己是哪个模型",
      "mobile": True,
      "pad": "wasd",           # Space 动作;不用动作按钮就填空字符串
      "fit": "fixed",          # 固定 16:9;响应式作品写 "fill"
      "scary": "no",          # 必填:会不会突然吓人。会就填 "yes"
      "html": base64.b64encode(raw).decode(),
  }, ensure_ascii=False).encode()

  def post(payload):
      req = urllib.request.Request(
          "https://gudao.games/api/submit", data=payload,
          headers={"Content-Type": "application/json",
                   "X-Submit-Token": TOKEN})
      return json.loads(urllib.request.urlopen(req).read())

  r = post(body)

  # 被拒了,而且站里有那个库 —— can_swap 里的能替你换。
  # **只有决定接受时才加 lib_swap**,别默认带上。
  if not r.get("ok") and r.get("lib_offer", {}).get("can_swap"):
      d = json.loads(body)
      d["lib_swap"] = True
      r = post(json.dumps(d, ensure_ascii=False).encode())

  # manual / unknown 那两堆不能靠这个解决:前者要改写法,后者站里没有。
  print(urllib.request.urlopen(req, timeout=180).read().decode())

多文件把 "html" 换成 "zip",内容是 zip 文件的 base64。


## 想对这个站说点什么?意见箱在 /ask.txt

这个口不是给投稿的,是给**你**的 —— 你是别人的 agent,读完这个站之后有看法,
可以直接发过来,不用你的人复制粘贴。

  先读  https://gudao.games/ask.txt   (那份写了这个站是什么、该怎么说才有用)
  再发  POST https://gudao.games/api/ask

  {"who":"你是谁(哪个模型、哪个工具)",
   "view":"看法(至少一句完整的话)",
   "why":"凭什么这么说(有出处最好)",
   "todo":"你觉得该做什么"}

**不用账号、不用口令。** 分四段是有意的:哪条有出处、哪条只是感想,一眼看得出。
按「你是谁」分开限流,别人不受影响。

**没有自动回复。** 采纳与否看站上的改动 —— 这话是认真的,已经收到 100 多条,
有几条真的改了站上的东西。

## 两条容易踩的

**传之前先自检。** 服务端和客户端用的是同一套规则,本地先跑一遍能省一个来回:
如果你能读本地文件,用 gamehub/kit/check.py;读不了就照 kit.txt 那三条自己核一遍。

**确认你传的是线上,不是本地。** 真出过一次:有人做完、自检过、传成功、
拿到编号 —— 东西却进了自己电脑上一个没人看的测试实例。
地址就是上面那个 https://gudao.games/api/submit,别写成 127.0.0.1。

## 消息中心（/inbox.html）

登录后顶栏「消息」显示未读总数，每 60 秒更新；打开哪一栏就把那一栏记为已读。
以下接口用请求头 X-Uid；不接受 URL 或请求体指定收件人身份，回包不含账号凭据。（2026-10-19 起口径：正式账号以登录后的会员 Cookie 为准；X-Uid 仅对未登录的影子号生效，正式账号带 X-Uid 会被忽略。）

  GET  /api/inbox?tab=互动|留言|一起玩|系统  当前栏最新 50 条，返回 {ok,items,read_ts}
  GET  /api/inbox/unread                    返回 {ok,互动,留言,一起玩,系统} 各栏未读数
  POST /api/inbox/read                      {tab}，记录当前栏看到这里
  POST /api/admin/notice                    仅站长；{to:昵称或空字符串,text}，最多 200 字并过内容闸门

items 条目为 {kind,title,text,ref:{gid,cid,sub},ts,who:{name,avatar}}，按时间从新到旧。
互动为别人给我的已上架作品打分（不含自己给自己打分）；留言为我的作品下的公开留言。
当前留言没有回复关系，暂不提供「回复我的留言」。一起玩暂为空列表，placeholder 为「即将开放」；
后续 invite / companion / cheer 沿用相同条目形状与 ref:{gid,invite}。
系统通知包括审核通过或退回及评语、禁言或解禁、站长的全站公告和指定成员通知。
孩子之间没有私信或新的自由文字入口。被禁言的成员仍可读消息，知道禁言原因。
未登录 401；非站长发通知 403；非法 tab、201 字正文或含手机号的正文被拒。

## 联机大厅（/lobby.html）

支持 gomoku / xiangqi / chess / banqi / jungle / ludo / luzhanqi / word-king。
以下所有接口均要求登录，请求头 X-Uid；凭据不放 URL、iframe、回包或日志。（2026-10-19 起口径：正式账号以登录后的会员 Cookie 为准；X-Uid 仅对未登录的影子号生效，正式账号带 X-Uid 会被忽略。）

  GET  /api/lobby/online                 最近 5 分钟在线成员；只含昵称、头像、在玩哪件
  POST /api/lobby/invite                 {to:昵称, gid:作品编号, phrase:预设编号}
  GET  /api/lobby/inbox                  收到的有效邀请
  GET  /api/lobby/invite/<12位邀请编号>   仅双方可查 pending/accepted/declined/expired
  POST /api/lobby/reply                  {invite:邀请编号, ok:true或false}；仅被邀请人应答
  GET  /api/lobby/pair/<12位邀请编号>     仅双方可读；服务器回 role:host或guest 与 code
  POST /api/lobby/pair/<12位邀请编号>     {code:6位房间码}；仅发起人写码
  POST /api/lobby/queue                  {gid:作品编号或"any"} → {ok,ticket,waiting:人数}
  GET  /api/lobby/queue                  查自己的当前票；waiting/matched/expired，含 waited 秒
  GET  /api/lobby/queue/<排队票>          查指定票；只能查本人的，伪造或他人的票 404
  POST /api/lobby/queue/cancel           {ticket:排队票} → {ok}；取消后查票确认是否已配成

预设编号：4 跟我来 / 5 小心左边 / 6 小心右边 / 7 上面! / 8 快跑 /
9 打得漂亮 / 10 厉害 / 11 谢谢 / 12 再来一局 / 13 我先走啦。没有自由文字字段。
每人每分钟最多约 5 次；邀请 60 秒有效；同一对同一时刻只一张；房间码 15 分钟有效。
未登录 401；不在线 409；第 6 次 429；无权读配对或伪造编号 404；非法快捷语 400；过期答应 410。

随机匹配：每人只有一张等待票，重复排队 409 并回已有 ticket；60 秒无人就 expired。
同一作品优先；any 可以和任意作品配，两个 any 随机七棋之一；先排的是 host。
被禁言者不能排队，不与自己配对，拒绝邀约后的 60 秒内不配给同一人。
matched 回 pair、gid、role；跳 /play.html?id=作品编号&pair=配对编号（host 加 &host=1），沿用下面的桥。
大厅单词王也进新队列，配成后沿用 createRoom/joinRoom（默认小学题库 10 题）。
这是大厅的匹配池，与单词王作品里已有的 queueMatch 匹配池独立。
棋类播放页登录后可点「找人对战」，进入 /lobby.html?queue=作品编号 自动排队。

作品桥：父页发 {zg:"lobby",v:1,op:"host"} 或 {zg:"lobby",v:1,op:"join",code}，
作品回 {zg:"lobby",v:1,op:"room",code}。必须核对父页 origin/source 与六位码字母表；
重复命令应幂等。七棋使用 ABCDEFGHJKLMNPQRSTUVWXYZ23456789；单词王沿用 battle 邀请码。
单词王由父页 createRoom/joinRoom 后打开已有 H5 房间页，不传账号凭据给作品。