弈瞬

September 18, 2026 · View on GitHub

同一个 Jev，不同的输入信息，会下出怎样的棋？

在线试玩 · Jev 官方文档

九局五子棋同时进行，jev玩家一与jev玩家二轮换黑白。用统一的问题模板比较不同信息输入，并查看每一步真实的请求、返回、选项概率和最终落点。

弈瞬实际游戏画面：九宫格棋盘与决策看板

截图来自本地真实完成的九局，比分为 2∶7。仅包含游戏网页，不含浏览器工具栏或桌面。在线免费回放采用另一轮已保存的真实对局，结果为 6∶3。

在线体验

打开 **https://xiechengyuan.github.io/jev-gomoku/**：

  1. 免密钥回放：默认选择“真实对局回放”，点击“开始 / 继续”或“推进一手”。播放已保存的 144 次 Jev 决策，可暂停、切换棋盘并逐手检查输入输出。页面明确标记 REPLAY；没有新模型调用，API 请求计数为 0。回放输入方案固定。
  2. 实时对战：填写自己的 OpenRouter API Key，点击“启用实时对战”，选择双方输入信息并开始。需要该账户有可用额度与 Jev 访问权限，费用由该账户承担。
  3. 保存实验：在线版使用当前浏览器的 IndexedDB 保存每轮记录，支持恢复最近归档、下载 JSON。清除浏览器数据会清除这些归档；重要数据请下载保存。

在线站点由 GitHub Pages 托管。实时请求由浏览器直接发往 https://openrouter.ai/api/alpha/decisions，每盘独立请求，最多三盘并发。访客密钥只保留在当前页面内存，输入框提交后清空，刷新后需要重新输入；不写入浏览器归档、仓库、GitHub Actions 或站点服务端。

能做什么

  • 15×15 五子棋九宫格，具有立体感的棋盘与棋子；支持专注观战和移动端布局。
  • 两位 Jev 玩家，每局轮换黑白，九种预设两手开局。
  • 固定每盘每手 1 个 Choice 问题：从同一规则生成的候选中选择最佳落点。
  • 双方独立选择输入方案；开赛后锁定，重开后调整。
  • 实时看板展示 state、questions、answers、usage、模型版本、候选概率、耗时及全部逐步记录。
  • 单盘失败时保留其他盘的成功落子，暂停后可继续重试。暂停不会取消已经提交的上游请求，这些请求仍可能计费。

五种输入方案

输入实际发送的内容用来观察什么
仅棋盘完整 15 行棋盘文本、规则、执棋颜色、坐标说明、候选落点模型自行读取棋盘的能力
棋盘＋战术事实额外给出候选是否立即取胜、是否堵住威胁、落子后双方的直接胜点数显式即时战术信息是否有帮助
棋盘＋战术事实＋短期预判额外列出对手下一手可直接取胜，或制造无法立即反击的双胜点的位置是否减少提前一手即可避免的陷阱
棋盘＋黑白坐标清单将同一个棋盘再表示为黑白棋坐标列表表达方式的影响
棋盘＋战术事实＋四向连线每个候选横、竖、两条斜线的连续子数和开放端坐标显式棋形信息的影响

棋盘是文本，不是截图。例如：

列：ABCDEFGHIJKLMNO
9行 ......OO.......
8行 .....XXX.......

X 为黑棋，O 为白棋，. 为空位。这两行表示黑棋在 F8/G8/H8，白棋在 G9/H9；实际请求包含全部十五行。

“短期预判”由本地规则代码计算，不是 Jev 的思考过程，也不是长期搜索或必胜证明。四向连线只分析连续棋子，不覆盖全部跳空棋形。

实验边界

  • 双方候选政策相同：本方启发式前 8、对方前 4，加全部立即取胜与直接防守位置，去重后按坐标排序。候选不是全部空位，因此这不是完全无辅助的棋力测试。
  • 模型负责选择落点；代码不自动取胜、防守或代下。题型由代码固定，不由模型自动选择。
  • 当前产品没有开放 Score/Noul 决策切换，也没有“最终胜率预测”配置；底层保留其历史解析回归测试。
  • Choice 的选项概率不是最终胜率；模型没有在本项目中提供思维链。
  • 九局胜负受开局、执棋颜色、模型版本与采样变化影响，不能单独证明某类输入更好。更严谨的测试应对相同局面切换输入、重复运行并交换黑白。
  • 使用 ~typesafe/jev-latest 模型别名，实际版本保留在每条记录中；不同模型版本应分组分析。

本地运行

需要 Node.js 22+：

git clone https://github.com/XieChengYuan/jev-gomoku.git
cd jev-gomoku
npm ci
cp .env.example .env
# 在 .env 填入 OPENROUTER_API_KEY（也可配置 TypeSafe 或 Vercel）
npm run dev

打开 http://127.0.0.1:5173/ 。本地版密钥仅由 Node 服务端读取，实验数据写入 reports/experiments/<roundId>.json。.env 与本地报告目录均不提交。

npm test             # 棋规、输入隔离、决策解析、回放、在线传输测试
npm run build        # 标准前端构建
npm run build:pages  # GitHub Pages 在线版，含免费回放和访客实时对战

npm run build 的产物需要配套本地 API；GitHub Pages 使用独立的 build:pages 模式，不依赖 Node 服务端。请勿用 VITE_ 环境变量存放密钥，这类变量会进入客户端构建。

发布

.github/workflows/pages.yml 在推送 main 后执行测试、构建并部署 GitHub Pages。仓库 Settings → Pages 的 Source 应为 GitHub Actions。不需要设置模型密钥作为 Actions secret。

Fork 后若更改仓库名，请同步调整 package.json 中 build:pages 的 --base 路径以及 README 链接。

代码结构

src/game.js             棋盘、棋规与候选生成
src/arena.js            九局开局与落子状态
src/decision.js         固定实验配置、问题构造与模型返回解析
src/input-features.js   坐标清单与四向连线
src/online.js           在线直连、真实记录回放、浏览器归档
src/main.js             对战界面与逐步决策看板
server.mjs              本地 API 与磁盘归档
public/demo/            可公开的真实棋局示例（不含密钥）
tests/                  自动化验证
scripts/                第一轮实验的复盘脚本

render-report.mjs 是第一轮专用报告模板，其他轮次需要按真实结果更新叙述，不能直接复用结论。