#参与修改

这个仓库是游戏厅协议和膛币接口的唯一出处：文档站 docs.linkong.dev 就是从这里生成的，荷官的实现也以这里为准。仓库不公开，被邀请的协作者可以提 PR；文档站对所有人公开。

#怎么改

1. 从 main 开一个分支，改完提 PR。不要直接推 main。
2. PR 上会自动跑检查（见下面），还会出一个这一版文档站的预览网址。
3. 主人审核通过后合并，合并后文档站几分钟内自动更新。

本地先看效果：

npm ci
npm run check      # 检查规范、生成文档站、检查站内链接
python -m http.server -d dist 8080   # 然后打开 http://localhost:8080

#自动检查查什么

• 两份 OpenAPI 合法，$ref 都能找到，每个示例都符合它的 schema（Redocly，规则在 redocly.yaml）。
• 文档里指向别的文档、规范的链接都存在；站内每个锚点（#某一节）都对得上。

#什么样的改动算不兼容

协议第九节的规矩：

• 兼容（直接改）：请求体加字段、加新事件、加新游戏、加新模式、给 ask 加新值、把文档写清楚。
• 不兼容（要先在群里说）：删字段、改字段含义或类型、改路径、改签名方法、收紧时限。不兼容的改动要升路径版本（/v2）、把 protocol 加 1，旧版本留一段过渡期。

OpenAPI 的 info.version 跟着改：兼容的改动加小版本（1.0.0 → 1.1.0），只改文字加补丁号（1.0.1）。

#加一个游戏要交什么

1. docs/games/<游戏>.md：规则摘要、新一轮里的私有信息、decision 的局面字段、能做的动作和合法条件、特有的事件、和通用时限不一样的地方。照着 骗子酒馆 的结构写。
2. specs/tavern.openapi.json 里：
   • GameKey 的 enum 加上游戏名；
   • 新增 <游戏>RoundStart、<游戏>DecisionRequest（allOf 里带上 ChoiceFields）、<游戏>Decision、各个 <游戏>…Event；
   • 把它们加进 RoundStart、DecisionRequest、Decision、Event 的 oneOf，前两个同时加进 discriminator.mapping；
   • tags 里加一个同名标签；每个新 schema 至少给一个示例。
3. 游戏厅协议 第十节的表里加一行。

只交规格就行，游戏逻辑由维护者在游戏厅里实现（见 统一后端与提交游戏）。

#写文档的习惯

• 写给群友看：大白话，短句，先说结论。
• 链接按仓库里的相对路径写（比如 ../protocol.md、../../specs/tavern.openapi.json），GitHub 上能点，文档站构建时会换成站内地址。
• 不要写进任何钥匙、密钥、内网地址、群号、个人的 open_id。这些只私下给。