桌面应用【免费下载链接】SabakiAn elegant Go board and SGF editor for a more civilized age.项目地址https://gitcode.com/gh_mirrors/sa/Sabaki点击查看免费下载本文以 Sabaki 仓库中 scripts/engine-transcripts/README.md 为核心完整讲解这套「引擎转录捕获与回放」测试体系的设计动机、分层验证策略、配置矩阵、捕获脚本capture.mjs的工作流程以及黄金转录golden transcripts如何被单测与 e2e 测试回放从而在无引擎、无 GPU 的环境下确定性验证 Sabaki 的 GTP 分析解析管线。读完后你既能理解如何用一份「真实引擎输出的字节级快照」替代昂贵且不确定的活引擎测试也能掌握如何扩展引擎版本矩阵与测试棋谱来覆盖新的输出方言。背景为什么需要引擎黄金转录引擎分析engine analysis是 Sabaki 的核心功能之一Sabaki 通过 GTP 协议向 KataGo / Leela Zero 等围棋引擎发送kata-analyze/lz-analyze命令引擎持续流式输出info ...分析行由 src/modules/analysis.js 中的parseAnalysis解析最终写入节点的SBKV胜率与SBKS比分优势两个 SGF 属性。但在引入这套工具之前该解析路径缺乏测试覆盖。原 README 指出了两个关键缺口e2e/engine.spec.js使用的假引擎只会「下棋」只实现genmove从不产生分析输出parseAnalysis此前从未被真实info行验证过解析逻辑最可能「悄悄坏掉」的场景是上游引擎厂商修改其info行的字段格式——这种回归只有拿真实引擎输出做基准才能捕获。因此这套工具的策略是在维护者机器上跑一次真实引擎把它的原始info ...输出逐行录制成 fixture即「黄金转录」并提交进仓库之后所有测试都在测试时回放这些转录做到确定性、零引擎依赖。分层验证策略原 README 给出了一张清晰的分层表各层职责与是否需要真实引擎如下下表完整继承自原文档路径已转为仓库根目录相对路径层位置验证内容测试时是否需要引擎解析正确性test/analysisTests.jsparseAnalysis对照录制的真实info行KataGo 与 Leela-Zero 两种方言否 — 回放转录管线 e2ee2e/engine-analysis.spec.jsattach 引擎 → GTP analyze →parseAnalysis→ 写入节点SBKV经由 test/engines/replayEngine.js否 — 回放转录真实引擎契约本目录脚本npm run gen:engine-transcripts确认真实引擎仍在输出我们所解析的格式是— 真的运行引擎只有第三层捕获层需要安装引擎并且它是有意排除在npm test与 CI 之外的手动步骤。这一点在 package.json 中可以得到印证test: mocha --require tsx只跑 mocha 单测含analysisTests.js的回放测试而gen:engine-transcripts: node ./scripts/engine-transcripts/capture.mjs是独立脚本需要维护者手工执行。目录与文件职责原 README 的 Files 一节列出的组件路径转为仓库根目录起点scripts/engine-transcripts/engines.config.mjs — 引擎版本矩阵 SGF 棋谱矩阵scripts/engine-transcripts/capture.mjs — 驱动每个引擎通过 GTP 逐谱分析并把转录写入test/resources/engine-transcripts/engine-id/test/resources/engine-transcripts/ — 已提交的黄金转录 manifest.json测试回放的 fixture 目录test/resources/engine-transcripts/sgf/ — 被分析的 SGF 局面test/engines/replayEngine.js — 回放一份转录的假 GTP 引擎供 e2e 测试使用。当前仓库中已提交的实际矩阵只有一个引擎条目KataGo 1.16.4对应 manifest.json 里 8 个转录单元4 个 SGF × 2 种 analyze 命令每个单元 8 行info。例如 endgame-9.kata-analyze.txt 中可见 KataGo 方言的完整字段utility、winrate0–1 浮点、scoreMean、scoreStdev、scoreLead、prior、lcb、weight等而 endgame-9.lz-analyze.txt 则是 Leela-Zero 兼容方言winrate为万分位整数如9562表示 95.62%且没有scoreLead字段。捕获配置矩阵engines.config.mjs捕获行为完全由 engines.config.mjs 驱动它导出三部分engines引擎矩阵、sgfs棋谱列表与capture捕获调优参数。引擎条目字段当前提交的矩阵内容如下Leela Zero 条目以注释形式保留供后续启用export const engines [ { id: katago-1.16.4, kind: katago, version: 1.16.4, bin: katago, net: { url: https://katagoarchive.org/g170/neuralnets/g170-b6c96-s175395328-d26788732.bin.gz, file: g170-b6c96.bin.gz, }, // kata-analyze - KataGo dialect (float winrate scoreLead). // lz-analyze - Leela-Zero dialect (integer winrate, no scoreLead). analyzeCommands: [kata-analyze, lz-analyze], overrides: numSearchThreads1, }, ]各字段含义依据该文件头部注释字段说明idfixture 子目录名如katago-1.16.4kindkatago|leelaz决定启动参数拼装方式version人类可读的引擎版本仅用于来源标注bin引擎二进制PATH 解析或绝对路径net{ url, file }权重文件缺失时下载到.engine-cache/nets/只下小网络——测试的是协议不是棋力analyzeCommands要捕获的 GTP 分析命令每个命令产出一份转录捕获多种变体正是为了把每种输出方言都文档化configKataGo 可选GTP 配置路径省略时通过brew --prefix katago自动发现gtp_example.cfgoverridesKataGo 可选额外-override-config kv。numSearchThreads1尽量让单线程搜索可复现。注意kata-analyze/lz-analyze会持续搜索并忽略maxVisits因此捕获时长由capture.settleMs限定而非访问数上限args可选额外二进制参数如 Leela Zero 的 playout 上限棋谱矩阵与捕获调优export const sgfs [ empty-19.sgf, opening-19.sgf, corner-9.sgf, // A decisive late 9x9 endgame (Black clearly winning) — gives a firm, // directional winrate the e2e can assert against, unlike the ~50% openings. endgame-9.sgf, ] export const capture { interval: 20, // GTP 分析报告间隔厘秒 settleMs: 1500, // 收到第一条 info 后允许继续分析多久再停止 maxMs: 60000, // 每个「单元」的硬超时 }棋谱刻意保持少手数、混合棋盘尺寸9 路与 19 路以加快捕获。其中 endgame-9.sgf 是一局黑方明显领先的 9 路残局——它给 e2e 测试提供了「方向明确」的胜率约 97%可以用来断言而开局类局面约 50% 的评估会随引擎/网络变化断言会失去意义。关于非确定性的重要说明kata-analyze/lz-analyze在被中断前会持续搜索因此捕获由墙钟时间capture.settleMs限定而不是固定的访问次数。这意味着重新生成产生的是「新鲜、有效但访问数/胜率不同」的转录不是字节级一致的。注释中的原话把它们定位为「代表性真实引擎输出而非确定性工件」。因此矩阵变更后需要重新生成并提交刷新后的 fixture 树而不能 diff 期望。捕获脚本 capture.mjs 的实现细节capture.mjs 是维护者工具文件头注释明确「It is a MAINTAINER tool. It is intentionally NOT wired intonpm testor CI」。其核心由四部分组成。1. SGF 主线路读取parseSgf用sabaki/sgf与应用同一解析器注释说明这是为了让坐标/属性处理不会与应用漂移读出SZ、KM与主线的B/W手数sgfToGtpVertex借助sabaki/go-board的规范标注跳过字母 I、行翻转把 SGF 坐标如pd换算为 GTP 顶点如Q16表示pass。2. 引擎供给provisioninglaunchArgscapture.mjs#L91-L105按kind拼装启动命令KataGo先ensureNet把权重下载到.engine-cache/nets/若缺失则用fetch拉取并打印体积再经findKataGoConfig定位gtp_example.cfg支持engine.config显式指定或brew --prefix katago自动发现找不到直接抛错提示设置config最终形如katago gtp -model net -config cfg -override-config numSearchThreads1Leela Zeroleelaz --gtp -w net加可选engine.args注释中给出示例[-p, 16, --noponder]。ensureNet的缓存目录.engine-cache/已在 .gitignore 中声明# Engine integration test cache (downloaded nets, gtp configs)与 README 的描述一致。3. GTP 驱动与单元格捕获captureCellcapture.mjs#L111-L177对每个「引擎 × SGF × 分析命令」单元格执行一次完整会话spawn引擎进程用readline逐行读 stdout一次性写入全部设置命令 一条分析命令boardsize n、clear_board、komi k、逐手play color vertex最后是command color interval。buildSetup中有个讲究komi放在clear_board之后因为有些引擎在 clear 时重置 komi这样引擎才能保留 SGF 中的值。分析颜色取「轮到的一方」最后一手黑则白方分析无手数则黑方以第一条info行为「引擎已就绪并开始分析」的信号而不是固定启动延时从而对首次运行的着色器编译等慢启动稳健收到第一条info后启动settleMs计时器到点后发stop\nquit\n正常退出maxMs为硬超时兜底进程关闭时收尾若一条info都没有则报错「engine produced no analysis」否则返回全部infoLinesfinish还会先stdin.end()再SIGKILL兜底确保不留僵尸进程。4. 主流程与 manifestmaincapture.mjs#L193-L267三重循环遍历engines × sgfs × analyzeCommands每次成功捕获后把infoLines写入test/resources/engine-transcripts/engine-id/sgf 主名.command.txt如katago-1.16.4/endgame-9.kata-analyze.txt并向manifest.json追加一条单元记录字段包括engineId、kind、version、net、command、sgf、boardSize、color、interval、infoLineCount、file。manifest 顶部写有「Generated by scripts/engine-transcripts/capture.mjs — do not edit by hand.」。任何单元格失败都会打印 stderr 尾 6 行并计入failures最终以非零process.exitCode退出零成功捕获同样视为失败。如何重新生成转录原文档给出的操作方式就是单条命令npm run gen:engine-transcripts前提条件engines.config.mjs列出的引擎二进制需在PATH中可用小网络会在首次运行时下载到 gitignored 的.engine-cache/nets/。之所以用小网络 短时间盒式捕获是因为这里测试的是「协议/解析集成」而不是棋力。执行完成后需要把刷新后的test/resources/engine-transcripts目录树提交进仓库测试侧的回放才跟着矩阵一起更新。回放侧一parseAnalysis 单测test/analysisTests.jstest/analysisTests.js 分两部分消费黄金转录1黄金回放断言。它读取manifest.json为每个单元格生成一个describe块取该转录最后一行info注释说明这是「最已收敛」的更新——即最终被写入节点 SBKV/SBKS 的那一条用before内调用parseAnalysis(lastInfoLine(cell.file), board, winrateFormat)解析特意放在before而非收集期使某个 fixture 引发的解析抛错只失败该块而不炸掉整个套件。方言由命令名决定kata-analyze传floatlz-analyze传integer。随后断言至少解析出一个变着variationwinrate是[0, 100]内有限数正是SBKV的值域visits是非负整数注释指出引擎合法地报告visits 0即只有策略先验、无 playout 的棋在真实lz-analyze输出中确实观察到顶点合法长度为 2 的数组且pv是数组方言相关断言kata-analyze单元格要求scoreLead为有限数对应SBKSlz-analyze单元格要求scoreLead null该方言没有比分。若manifest.json缺失套件会显式失败并提示运行npm run gen:engine-transcripts而不是静默跳过。2解析器自身逻辑的聚焦单测。这部分用手工最小行不依赖引擎格式假设钉住黄金快照无法确定性覆盖的分支例如整数万分位归一化winrate 5213→52.13浮点归一化winrate 0.5213→52.13并读取scoreLead 1.5无小数的浮点陷阱KataGo 可能输出整数值浮点必胜局的winrate 1启发式按有无小数点判断方言会误读为 0.01%显式传float方言则正确归一化为 100%——这正是运行期传入winrateFormat的原因主变化pv在pass处截断缺少move或winrate字段的畸形info片段被跳过而不是抛错丢弃整行。这与 src/modules/analysis.js 的实现严格对应parseAnalysisanalysis.js#L21-L67按info分段、用正则提取尾部 pv、把键值对归约成对象并「跳过畸形片段而不是解引用缺失字段」normalizeWinrateanalysis.js#L73-L76信任调用方传入的方言否则按小数点启发式判断。该模块刻意不含 Electron 与应用状态依赖唯一协作者是sabaki/go-board的纯坐标助手因此能直接对着录制的引擎转录做单测——这是整个分层策略能够成立的前提。回放侧二e2e 管线测试与 replayEngine第二层测试 e2e/engine-analysis.spec.js 验证完整管线attach 引擎 → GTP analyze →parseAnalysis→ 节点SBKV。它加载 endgame-9.sgf 并走到末手然后把 replayEngine.js 作为引擎「附加」到 Sabaki用process.execPath即 Node 本身执行参数为--transcript ... --analyze-command kata-analyze随后断言同步器EngineSyncer的commands包含kata-analyzeSabaki 据此选择分析命令启动分析后当前节点的SBKV[0]解析为黑方视角的高胜率 85且 100——黑方在这局残局中决定性领先「钉住视角」意味着如果代码把符号翻转写错写入的会是约 2 而不是 98断言即失败SBKS[0]为有限、明显为正 1且 50的比分优势同样钉住scoreLead的提取与符号。测试用try/finally保证断言失败时也stopAnalysis 拆除引擎不向后续测试泄漏子进程。这与生产写入逻辑一致src/modules/sabaki.js 中在sign 0白方视角时做winrate 100 - winrate; scoreLead -scoreLead再Math.round(x * 100) / 100后以字符串写入SBKV/SBKSsabaki.js#L1895-L1915而SBKV/SBKS也在 src/modules/utils.js 的markupCleanupProperties.winrate中登记供 Clean Markup 功能按类清理。replayEngine 为什么直接裸写 GTPtest/engines/replayEngine.js 的头部注释解释了它不复用sabaki/gtp的Engine助手的原因分析协议是「一边流式输出info行、一边要并发处理stop」而该助手按严格顺序处理命令会死锁。其响应框架刻意模仿 KataGo 的真实行为普通命令 content\n\n分析命令先输出\n随后流式输出info ...\n空行终止符被扣住直到下一条命令到达才发出——这正是真实引擎「任何新输入都会停止分析并终结响应」的行为。这一点很关键Sabaki 中止分析用的不是 GTPstop而是经EngineSyncer.sendAbort发送protocol_version见注释因此如果回放引擎只在stop时关闭响应会让控制器失步。实现上startStreaming每 100ms 循环发射录制的info行stopStreaming在任何新输入到达时先关闭仍打开的分析响应补一个空行再处理命令对boardsize/clear_board/komi/play/undo等局面同步命令一律宽容应答保证位置同步永不失败。启动时若--transcript缺失、文件不可读或不含任何info行立即以退出码 2 大声失败——否则引擎只是「什么都不流」只会表现为一个不透明的 e2e 超时SBKV 永不写入而真正的病因被掩盖。当前捕获的输出方言原 README 的「Dialects captured today」一节指出从同一个 KataGo 构建即可捕获两种输出方言命令方言winrate形态scoreLeadkata-analyzeKataGo 方言0–1 浮点有lz-analyzeLeela-Zero 兼容方言万分位整数无两者合起来恰好覆盖parseAnalysis的两条胜率归一化分支×100与/100以及「有比分 / 无比分」两条路径。原文档还留了一个明确的后续项最终应向矩阵加入一个真正的 Leela Zero 构建在engines.config.mjs中已有注释掉的leela-zero-0.17示例条目analyzeCommands: [lz-analyze]示例参数[-p, 16, --noponder]以确认 KataGo 的lz-analyze仿真与真机输出一致。需要说明的是Sabaki 对引擎开发者公开的analyze协议规范见 docs/guides/engine-analysis-integration.mdmove/visits/winrate必填scoreLead可选响应在任意 stdin 输入时终止黄金转录正是对这套规范的「真实引擎侧」回归基准。扩展覆盖范围原 README 给出的三类扩展路径结合源码可落地为新引擎版本 / 新引擎在 engines.config.mjs 的engines中增加条目二进制、权重 URL、分析命令然后重新生成。README 特别提到在 Linux/CI 上KataGo 还提供纯 CPU 的eigen构建适合放进一个「独立、定时调度」的真实引擎作业。新局面把一个 SGF 放进 test/resources/engine-transcripts/sgf/在sgfs中列出再重新生成。新分析特性例如SBKS之类的新属性KataGo 的kata-analyze转录中已经包含scoreLead字段可先在 test/analysisTests.js 中对其断言待功能真正把属性写入节点后再补到 e2e 层。小结这套工具的核心思路可以概括为一句话把「真实引擎输出」从测试时移到了构建时。capture.mjs负责在维护者机器上录制真实 KataGo/Leela-Zero 方言的info字节流并提交为黄金转录analysisTests.js用它们钉住parseAnalysis的双方言归一化与比分提取replayEngine.js则用相同的字节流驱动整个 Electron 应用走通 attach → analyze →SBKV/SBKS写入的 e2e 管线。代价需要真实引擎与权重的第三层被隔离成一次性的手动命令npm run gen:engine-transcripts从而让确定性与真实性兼得日常npm test/ CI 零引擎依赖而上游引擎格式变化导致的解析回归则会在下一次手动捕获 提交刷新 fixture 时被立刻暴露。赞分享桌面应用【免费下载链接】SabakiAn elegant Go board and SGF editor for a more civilized age.项目地址https://gitcode.com/gh_mirrors/sa/Sabaki点击查看免费下载相关推荐Sabaki 引擎集成实战为 GTP 围棋引擎接入、对战与分析做图形化前端Sabaki 引擎集成实战为 GTP 围棋引擎接入、对战与分析做图形化前端 Sabaki 是一款基于 Electron 的 SGF 编辑器与棋盘应用而 do桌面应用Flame游戏引擎测试指南从单元测试到黄金测试Flame游戏引擎测试指南从单元测试到黄金测试 Flame作为一款功能强大的2D游戏引擎其稳定性和可靠性很大程度上依赖于完善的测试体系。本文将深入解析Fla游戏开发图形学Flutter 引擎集成黄金测试用 Skia Gold 对真实渲染管线做跨环境一致性校验Flutter 引擎集成黄金测试用 Skia Gold 对真实渲染管线做跨环境一致性校验 在 Flutter 仓库中 引擎集成黄金测试Engine Int跨平台移动开发前端UI组件桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
