Bug 提交 API

这一页是那两条硬门槛的机器可读形状：字段叫什么、缺了会怎样、失败长什么样。一个 agent 读完这一页就应该能交出一条我们处理得了的报告，不用猜。本站没有后端——所以入口有两个，能力不同，下面分别写清楚。

先读这一条，否则另外两个入口会被你误解。 浏览器里那个 API 不落盘——它只把报告排成统一格式，因为没有任何服务器可以接。真正能写进去的只有本机那个，它绑在 127.0.0.1 上，机器外面碰不到。这不是设计取舍，是 GitHub Pages 只发文件、不跑代码。

报告对象

两个入口收的是同一个对象。前五个字段缺任何一个，报告都无法处理。

字段	必填	是什么
`title`	是	一行说清哪里不对。看板上显示的就是它。
`what`	是	站上那句话的原文，或它所在页面的地址。
`cmd`	是	你跑的命令，原样。
`out`	是	你得到的输出，原样。错误信息别删。
`expect`	是	按站上那句话，应该发生什么。
`version`	否	站上写的版本串。
`env`	否	OS / 浏览器 / 工具链——只在确实相关时。
`area`	否	五选一：`kernel` / `language` / `compat` / `ai` / `site`。默认 `site`。
`url`	否	相关页面的地址，做成链接挂在条目上。

入口一：浏览器

在提交页上，window.FJ.submitBug(report) 和表单走的是同一段代码。用了浏览器自动化的人（或 agent）可以完全跳过点击。

js 在提交页的控制台里

FJ.submitBug({
  title:  "quickstart 里的等价套件跑不出 63/63",
  what:   "https://fujojtop.github.io/FujoOSwebsite/docs/language/quickstart/",
  cmd:    "python tools/loment_rule_parity.py",
  out:    "E13 @20 line 4: twice",
  expect: "规则等价 63/63",
  version: "0.1.4 Alpha2.3",
  area:   "language"
})

// 成功 → { ok: true, report: "【标题】…" }
// 失败 → { ok: false, missing: ["the command"] }

返回的 report 就是你要交出去的那段文本。它不会被发到任何地方——没有地方可发。

入口二：本机

仓库里的 tools/bugapi.mjs 是一个只绑 127.0.0.1 的小服务。它校验、按顺序发号、把条目写进 content/bugs.json。写进去的条目是非官方——本机没人复现过它，这一点写在行上。

bash 起服务，然后交一条

node tools/bugapi.mjs
# bug intake listening on http://127.0.0.1:8788

curl -sS http://127.0.0.1:8788/api/bug \
  -H 'content-type: application/json' \
  -d '{"title":"…","what":"…","cmd":"…","out":"…","expect":"…","area":"language"}'

# 201 { "ok": true, "id": "FJ-0004", "file": "content/bugs.json",
#       "next": "node tools/docs.gen.mjs",
#       "note": "written as an unofficial entry — nobody here has reproduced it yet" }

失败码	什么时候
`missing_field`	必填字段为空或不是字符串
`unknown_field`	传了契约里没有的字段——宁可拒收，也不要静默丢掉
`bad_area`	area 不在那五个里
`too_long`	单个字段超过两万字符
`bad_json`	请求体不是合法 JSON

校验不过时返回 422，一次列出全部问题——不是第一个。写完之后条目是数据，看板要重新生成才看得见：node tools/docs.gen.mjs。

一句话总结： 报告的形状到处都一样；能不能落盘，取决于你在哪台机器上。