开放 API 的设想

差不多每周都有人问我们有没有 game api（游戏接口），问得最多的是小型棋社的组织者和想给学生摆棋的老师。这篇就是我们现在的真实状态：一个 board game api 会开放什么、我们还没解决的两个问题、以及我们打算按什么顺序做。这里没有一样东西是明天就上线的。想直接下棋的话，对战页一直开着。

我们为什么想做

这些请求基本分成两类。棋社的人想把自己社里的对局记录导进表格，省掉手抄比分；教棋的人想摆一个局面，把同一份练习发给三十个学生。两类人都不想要另一个 App，他们想要的是"已经在 YiBoard 上产生的数据，能在别的地方用起来"。

第二个原因是自私的。对战页、棋谱库和排行榜三处读的是同一批对局记录，却各写了一套查询。把这三处改成对着同一份有文档的接口读写，在我们的清单上已经躺了几个月。对外公开的版本就是同一套接口，只是限额更低。

第一版会开放什么

• 对局记录：每一步、结果、用时规则、双方的分数变化，JSON 格式
• 摆棋：提交一个盘面，返回合法着法列表和引擎评估
• 引擎着法：指定一个固定的搜索预算（现在是 500 毫秒），返回着法和评分
• 排行榜切片：任一段位区间的 Top N，每小时刷新一次

不开放什么更重要。接口不会返回访客令牌、设备列表，也不会返回任何本来就不公开的个人资料字段。这条界线我们在开源棋盘引擎生态那篇里画过，对我们来说没有商量余地。

两个还没解决的问题

限额是容易的那个：定一个数、公布出来、要是来的流量友好再往上调。难的是机器人。无禁手规则下五子棋接近被解，一个只管进攻的脚本客户端就能赢下多数人类，来几百个，一周之内段位榜就被压平。我们的服务器会对每一步做校验，这能挡住改客户端的作弊，但分不出一个强人和一个脚本的区别。

三条路，我们还没选。给接口对局单独开一张榜；按令牌限制每天的排位局数；或者上线时不计分，以后再定。我们倾向最后一条，因为它是唯一一个事后能改、又不会作废别人已经打出来的成绩的方案。

第二个问题是变体。连珠禁双三，无禁手不禁。如果对局记录里没写清楚它是按哪套规则下出来的，调用方会把一部分棋局读错，而且是静默地读错，等到有人发了一份错的分析出来，才有人发现。

国际象棋的开发者接口已经证明了什么

国际象棋早就有了。Lichess 有一个公开的 HTTP 接口，覆盖对局、棋题和引擎分析，线上国际象棋周围一大半的工具之所以存在，就是有人能读到这些数据。这类 developer api（开发者接口）能跑通，一部分原因是规则固定、记谱法统一，两个程序对同一个字符串的理解永远一致。

五子棋没有对应物。引擎项目各做各的，盘面格式互不相通，几乎没有一个能读另一个写出来的对局记录。给这些棋做一个开放的棋盘游戏平台能解决这件事，但前提是我们必须随每条记录公布变体和棋盘尺寸，这比多数国际象棋工具愿意带的元数据要多。

代价，以及我们的顺序

实话：比现在这个站更贵。每一个公开的端点都要配额、要可用性监控，也要有人在调用方被改动搞坏时出面回答。我们的预算不大。反作弊的工作和象棋的上线都排在前面，我宁愿直说这一点，也不想先宣布一个日期再错过它。

比较现实的顺序是：先只读的对局记录，然后摆棋，最后才是引擎着法，因为最后这一项每次被调用都要烧算力。要是你想对这个顺序提意见，关于页上有联系方式，我们是看的。

FAQ

在 YiBoard 免费下一局

YiBoard (yiboardgame.com) — 中华棋类，浏览器即玩，免费无注册。 去下一局 · 更多博客 · 玩法指南