v0.1.29 · 全量修复（外部审查 40 条 + 自检第 41 条）

v0.1.29（2026-10-15 深夜）· 「全量修复」—— 一份外部代码审查（40 条）逐条复核后全部处理****

下载（页面最下面的 Assets，按平台挑一个；这些包都不含引擎）：

平台	文件
Windows	RapaceGo-win.zip

引擎要自己配（见 README「显卡品牌」那一节）。

---

想省事？直接下懒人包（自带引擎，解压就能用）

上面那个 zip 不含引擎（KataGo 权重 + LoGos 模型要自己配）。
懒人包把这些全带齐了，解压后双击 RapaceGo.exe 即可，零配置：

👉 夸克网盘 · 玄清围弈懒人包　（提取码 Svze）

约 8.5 GB，含：程序本体 + KataGo（N 卡加速版和通用版两套，软件自己按显卡挑）+ LoGos 讲解模型。
下载后解压、双击 RapaceGo.exe 就能用 —— 不用再去看「显卡品牌」那一节。

展开看这一版改了什么

v0.1.29（2026-10-15 深夜）· 「全量修复」—— 一份外部代码审查（40 条）逐条复核后**全部处理**

★ 会毁你棋谱的三条（最严重）

• 带摆子的棋谱（让子棋、死活题）打开后点「覆盖」或「导出」→ 摆子全部丢失（AB/AW 不再写出来）。已修。
• Big5 编码的棋谱（繁体棋谱）原来被当成 GBK 读：解说词是「看着像中文的错字」，改一处保存就永久写坏。
  现在认 SGF 自己声明的 CA[]，读、写都按它来；写回时还会把 CA[] 订正成与实际字节一致的编码。
• 棋谱库里的备注（GBK 棋谱）显示乱码，点「确定」会变成 ??????。已修。

★ 点一次就废掉的功能

• 「生成讲解」在正式对局落过 1 手之后点一次就永久失效（只能重启软件）——
  内部把整棵分支树丢给 JSON 序列化，撞上循环引用抛异常，异常又把按钮的「忙」标记卡死。已修。

★ 规则与计时

• 打劫禁着点在「切分支 / 提升主变 / 删除分支 / 撤销删除 / 回看岔出新支 / 翻手数 / AI 停一手」这些操作之后会丢失，
  于是非法提回被放行。这次是根治：禁着点改成只读盘面算，不再依赖「要靠重算补上的派生字段」。
• 回看历史手时时钟照走：数字冻住、时间在背后扣，耗尽直接把人在回看状态下判负。已修（回看不走表）。
• 进「试下」待几分钟再退出 → 那段时间被算成这一手的思考时间，轻则抹掉主时间、重则判负。已修。
• 读秒设 3 次实际给了 4 次。已修（设几次就是几次）。
• 认输 / 超时之后棋盘仍可继续下 —— 这是保留的行为（您要的继续下）；
  但结果条现在会随局面收起，不再一边下着一边挂着旧胜负。

★ 打谱与棋谱解析

• 棋谱里出现空树 ()（飞燕围棋安卓版导出的死活词典大量这么写）→ 后面的手和变着全丢，最坏主线 0 手。
  已修（本机 17290 份真实棋谱里 98 份受益）。
• 不认 AE[]（题集里「把这里的子拿掉」）→ 题面多出子，解的是另一道题。已修。
• 「第 1 手就分叉」的棋谱，另一条开局在树面板上一颗珠子都不显示。已修。
• 侧支深处的珠子右键「设为主变」被挡回「已经在主变上了」。已修。
• 「棋谱说明」落刀打到没有 C 的元数据节点上，清空后重开旧说明又回来。已修。
• 多值 C[a][b] 清空只删第一个值，留下游离的 [..] 挂到前一个属性上。已修。

★ 其它

• AI 回看历史局面后跳回末端 → AI 误认输。已修（判据改用末端那一手的评估）。
• AI 思考期间进「试下」，AI 会把自己那一手落进草稿。已修。
• 全盘讲解跑几分钟期间回看落子 → 越界崩且没有任何提示。已修（会说明原因并停下）。
• 百分比正则回溯爆炸：极端文本让主线程卡死 4 秒。已修。
• 分析超时把「算到一半的快照」当正式结果上屏、且不报错。已修。
• macOS 关一次窗口后引擎永久「加载中」、点「加载」没反应。已修。
• 「检查更新」或改棋谱库文件夹会把本机绝对路径写进配置，破坏懒人包「解压到哪都能用」。已修。
• 引擎权重不匹配时的那句原话被「引擎意外退出（code 1）」盖掉，看不到真原因。已修。
• 删棋谱时没带走 .bak 备份 → 留下孤儿，且同名棋谱重新导入会跳过备份。已修。
• 棋谱写盘改成原子写（先写临时文件再改名），崩溃/断电不会留下半截文件。
• 「棋谱库」「更改文件夹」这类只检测的接口不再偷偷建目录。
• 几处已删快捷键（PgUp 等）的残留文案已改。

★ 怎么验的（不是只点几下）

• 每条修复配一条能抓住该 bug 的回归断言；关键几条先在旧代码上跑红再改
  （例：把劫点判据换回旧实现 → 定向用例立刻报红，证明断言真的抓得住）。
• 不变式自检：2000 步随机操作 ＋ 定向劫场景，七条性质加「劫点语义判据」（独立实现）全部通过。
• 既有全套回归（分支 83 条 / 真实 217 手棋谱 / 树面板 / 试下 / 复盘 / 讲解清洗 …）全绿。

---

v0.1.28 修补三（2026-10-15 晚，同版本号覆盖包）：修「同一方连下两子」的恶性 bug + 把状态同步彻底根治

★ 修：在分支树里操作之后，可能出现「连续两手都是同一方下」

症状：在分支树里点珠子 / 提升主变 / 删除分支 / 撤销删除之后，再落子有可能变成同一方连下两子。

根因：这些操作在重算「该谁走」时，用的是你正在看第几手；而「该谁走」只该看当前局面的末端。
回看历史手时两者不相等 → 轮次算偏了；之后你把视图挪回最新再落子，用的还是那个偏值。

修法（根治）：把「该谁走」从可变字段改成只读派生属性 —— 它永远等于「当前局面该谁走」，
代码里再也写不错（原来 15 处手工赋值全部删除）；
同时把「重建路径」和「重算打劫禁着点」也各自收进唯一入口，不再让每个操作用手写三行去同步。

★ 顺带修掉两个自查抓出来的隐患

• 停一手压进手顺的是个"半成品节点"（没有父指针）—— 在它被补上之前，
  树面板和分支计算会把它当成"没有来路"的一手。现在走与落子完全相同的建节点流程。
• **试下（打草稿）期间点「撤销删除分支」**会把局面退到存档点之前，破坏试下的语义 —— 现在与其它操作一样被挡住。

★ 这次是怎么验证的（不是只点几下）

新写了一个不变式自检，用 2000 步随机操作（落子 / 回看 / 换分支 / 提升 / 删除 / 撤销 / 悔棋 / 停一手 / 试下…）
反复压，每一步都检查七条必须成立的性质（路径连续、颜色交替、游标合法、劫点自洽、轮次恒等、树无孤儿、草稿闸门）——
0 违规。上面那两个隐患就是它头一次跑抓出来的。

---

v0.1.28 修补二（2026-10-15 下午，同版本号覆盖包）：界面四处 —— 分支树右键菜单、删除分支确认窗、快捷键精简、帮助更新

★ 修：放大分支树后，右键点珠子的菜单弹不出来

菜单被放大窗的遮罩盖在下面了（轮廓看得见、点不着）。现在它浮在遮罩之上，右键正常弹出。

★ 改：删除分支要先弹窗确认

原来点「删除分支」只是把按钮文案变成「再点一次确认删除」、上方提示一句 —— 现在改成独立的确认窗：
写清「删掉第几手起的整条分支、一共几手、删完可以用 Ctrl+Shift+Z 放回来」，两个按钮【取消】/【删除】。
取消或点空白处 = 什么都不发生。

★ 改：快捷键精简（删掉三个）

删掉 Delete（删除分支）、空格（停一手）、PgUp（提升主变）：
这三件事在界面上都有入口（右键树面板的珠子、底栏「停一手」按钮），而且都是会改动棋谱结构的操作，
走「菜单 + 确认窗」比按一个键更稳妥。

留下的都是高频操作或显示开关：←/→ 翻手 · ↑/↓ 换分支 · Home/End 跳首尾 · C 折叠侧支 ·
Ctrl+Z 悔棋 · Ctrl+Shift+Z 撤销删除 · T/Z/M/B/Y/X/N 显示开关 · D 试下 · Ctrl+Shift+D 分析自检。

★ 改：帮助更新到最新

帮助里补上了整块「分支树」（点珠跳转、角标展开、绿色来路高亮、右键菜单、放大窗）和
「回看点落子 = 从那一手开新分支」（含"回看时也会显示淡一点的落子预览方块"）；
快捷键表同步更新。

---

v0.1.28 修补（2026-10-15，同版本号覆盖包）：修两个 bug —— 倒扑被当成劫 与 点分支树后落子预览消失

★ 修：一手合法的「扑之后反提」被当成打劫，点不进去

症状（在别的软件对弈、在这边录入棋谱时踩到）：第 84 手白扑、第 85 手黑提掉这一子，
第 86 手白点回原处本该提走 7 颗黑子，软件却提示「打劫：此处暂时不能下」。

根因：判断「这一点是不是打劫禁着点」时只比了坐标（这一点是不是上一手的提子点），
没算「这一手本身也只提 1 子」。倒扑这手一下提 7 子、局面根本不会重复，却被前一道闸门拦住。

修法：劫的判据换成主流开源围棋软件 Sabaki 的写法（四条同时成立才算制造劫）：
本手只提 1 子 · 落下的这子是孤子 · 它只有 1 口气 · 那口气正是刚被提掉的那一点。
「孤子」这条正是倒扑的抗体 —— 提完还连着己方大块的，一律不是劫。

顺带修掉一个同源的隐患：悔棋 / 切分支后重算禁着点时，盘面和手数会错开一手，
算出来的是另一个局面的禁着点。现在两者一一对应。

★ 修：点分支树里的珠子之后，棋盘上的落子预览小方块没了

根因：预览方块原来有条限制「只在看到最新一手时才画」。
点树上的珠子 = 跳到那一手 = 进入回看 → 预览就被挡掉了，看着像坏了。

修法：回看中也画（这个软件本来就允许从回看点落子 —— 会从那一点开一条新分支），
但画成半透明并描边，跟正常落子一眼区分得开。

---

关于「三大目录」的分工（维护者备查，也免得自己混）

位置	是什么	里面该有什么
RapaceGo\（开发目录）	改代码、跑测试的地方	源码 + node_modules + 一堆 _ 开头的开发脚本
dist\	只放要传 GitHub 的东西	只有 RapaceGo.zip（win-unpacked 是中间产物，同步完自动删）
玄清围弈\	本地自用的免解压版（唯一一个）	可直接双击运行的完整程序
桌面 RapaceGo懒人包\	给别人下载用的整包（传网盘，不传 GitHub）	程序 + KataGo + LoGos，解压即用、零配置

为什么懒人包不上 GitHub：它 8.2 GB，而 GitHub Release 单个附件上限 2 GB，
且大头（4.4GB 的 .gguf 模型、296MB 的 .bin.gz 权重）本身就是压缩格式，
再打 zip 也压不动。GitHub 那份走轻量路线（146MB + 首次运行自动下模型）。

★ 懒人包的目录约定（做包时最容易搞错的一条）

main.js 里打包态的「引擎位置」是和 RapaceGo.exe 平级，不是上一级：

BASE_DIR = IS_PACKAGED ? path.dirname(process.execPath) : __dirname;  // 打包后 = exe 目录
const up = IS_PACKAGED ? BASE_DIR : path.join(__dirname, '..');        // 打包后 up 就是 exe 目录本身
katago: path.join(up, 'KataGo', 'engine', 'katago.exe')

所以懒人包的布局必须是：

RapaceGo懒人包\
├─ RapaceGo.exe      ← 和下面两个目录平级
├─ KataGo\engine\katago.exe + weights\
└─ LoGos\llama-server.exe + *.gguf

别把程序本体再套一层 RapaceGo\ —— 那样软件会去找 懒人包\RapaceGo\KataGo\...，
而文件在 懒人包\KataGo\...，结果引擎永远起不来（实测 settings.check 五项全 false）。

重建懒人包：powershell -File _build_lazy.ps1（已含"删掉 settings.json / records"等铁律）。

下载

只有一个文件：

文件	大小	说明
RapaceGo.zip	约 146 MB	解压一次，之后从文件夹里双击启动 —— 启动最快，也最便携

包名固定不带版本号（这样每次下载地址都一样）。要知道自己装的是哪一版：
打开软件 → 左上角「帮助」，标题右边写着版本号。

完全不会用 GitHub 也能装（四步）

① 打开下载页：https://github.com/Rapace7/RapaceGo/releases

② 往下滑，找到最上面那条发布（标题写着版本号和日期，GitHub 的下载文件都放在「发布」里）

③ 那个区块下面有一栏 Assets

⚠️ Assets 不是一个文件夹，是这次发布附带的下载文件清单。
小白最容易在这儿绕晕 —— 你要找的就是这份清单里的文件。

④ 点清单里的 RapaceGo.zip 下载

• ⚠️ 别下页面最下面的 Source code (zip) —— 那是 GitHub 自动生成的源码压缩包，
  解压出来不能双击运行

⑤ 下载完右键「全部解压缩」，打开文件夹，双击 RapaceGo.exe —— 软件就起来了。

认准三样东西就行：① 最上面那条发布 → ② 它下面的 Assets 清单 → ③ 蓝色的 RapaceGo.zip

更新到新版本

把新包解压到原来那个文件夹、覆盖同名文件就行 —— 棋谱和设置不会丢。

1. 打开软件 → 左上角「帮助」，记下当前版本号
2. 到这个页面看最上面那条是不是更新了
3. 关掉软件（重要：程序开着文件被占用，覆盖会失败或只覆盖一半）
4. 下载新的 RapaceGo.zip → 解压到你现在用的那个文件夹 → 问是否覆盖时选「替换」
5. 重新双击 RapaceGo.exe

为什么不会丢东西：包里只有程序本体，records/（你的棋谱和讲解）、settings.json
（引擎路径）、KataGo/、LoGos/（引擎与模型）都不在包里，所以原样保留。

保险做法：更新前把 records 文件夹复制一份到别处 —— 那是唯一丢了找不回来的东西。

⚠️ 引擎要自己准备一次（包里不含）

下载包里只有软件本体（约 570KB 的代码 + Electron 运行时），两个引擎是别人的项目：

① KataGo（必需，不装就没有 AI 下棋和数据分析）

• 程序：https://github.com/lightvector/KataGo/releases 的 Windows 版
• 权重两个：https://katagotraining.org/ 的 b11c768nbt.bin.gz（算胜率）和
  b18c384nbt-humanv0.bin.gz（当对手，文件名带 human 的那个）

② 讲解模型（可选，4.4GB）

解压后的文件夹里有一个 下载讲解模型.bat —— 双击它就行。
它会自动下载、合并模型、装好推理运行时，全程中文提示；
中途断了重新双击会接着下（按精确字节数判断，没下全的续传）。

👉 已经自己下载了那三个 .part 分卷（part01/02/03）？
那就不用管 bat 了 —— 往下翻到 ▶ 点这里展开 那段，一行命令就能合并。

▶ 点这里展开：已经自己下好那三个 .part 分卷了？手动合并也行（不用 bat）

下载 LoGos-7B-Q4_K_M.gguf.part01 / .part02 / .part03 之后，任选一种方式合并成
LoGos-7B-Q4_K_M.gguf（三个文件放在同一个文件夹里）：

① 命令提示符一行

copy /b LoGos-7B-Q4_K_M.gguf.part01+LoGos-7B-Q4_K_M.gguf.part02+LoGos-7B-Q4_K_M.gguf.part03 LoGos-7B-Q4_K_M.gguf

② PowerShell（流式拷贝，内存占用低）

$out = [System.IO.File]::Create("LoGos-7B-Q4_K_M.gguf")
foreach ($p in "part01","part02","part03") {
  $i = [System.IO.File]::OpenRead("LoGos-7B-Q4_K_M.gguf.$p")
  $i.CopyTo($out); $i.Close()
}
$out.Close()

③ 7-Zip / WinRAR 不行 —— 压缩工具没有「合并分卷」功能。

⚠️ 合并后务必核对：应该是 4,683,071,328 字节（约 4.36 GB）。
不对就是没下全，删掉重下。核对完可以把三个 .part 删掉（省 4.4GB）。
然后回软件「设置」→ LoGos 组分别选 llama-server.exe 和合并出来的 .gguf。

为什么要分卷：GitHub 单个文件硬上限 2GB，而这模型 4.4GB —— 平台限制，
不是故意折腾你。三个分卷就是纯二进制切片，合并结果和原文件逐字节一致
（开发时用 sha256 验过）。

合并完还需要推理运行时（llama-server.exe）—— 上面那个 bat 会帮你装。

▶ 点这里展开：完全手动装（不用 bat、不用管分卷）

模型：YichuanMa/LoGos-7B 转的 GGUF Q4_K_M；
运行时：llama.cpp 的 Windows CUDA 版。
⚠️ 官方主包不含 CUDA 运行时，要另下同版本的 cudart-*.zip 放同目录。

装完之后文件夹长什么样

解压出来不止 RapaceGo.exe 一个文件，还有一堆 .dll、.pak、locales\ 之类 ——
那些都是软件自带的运行库（Electron 框架），不用管、也不要删（一共约 368 MB）。

下面把「你加进去的」和「软件自带的」分开写：

RapaceGo/                          ← 解压出来的文件夹（名字随便，拷到哪都能用）
│
├─ ★ 你自己准备的 ──────────────────────────
│  ├─ KataGo/                      ① 下 KataGo 的 Windows 版解压进来，改名成 KataGo
│  │  ├─ katago.exe
│  │  ├─ …（同目录还有一堆 .dll，一起放着别删）
│  │  └─ weights/                  ② 新建这个文件夹，放两个权重
│  │     ├─ b11c768nbt.bin.gz              算胜率 / 推荐点 / 形势
│  │     └─ b18c384nbt-humanv0.bin.gz      当 AI 对手（带 human 的那个）
│  └─ LoGos/                       ③ 双击「下载讲解模型.bat」之后自动出现（可选）
│     ├─ llama-server.exe
│     └─ LoGos-7B-Q4_K_M.gguf
│
├─ ★ 软件自带的（别删）─────────────────────
│  ├─ RapaceGo.exe                 ← 双击这个启动（245 MB，程序+框架都在里面）
│  ├─ 下载讲解模型.bat              ← 要讲解功能就双击它（会自动建上面的 LoGos/）
│  ├─ start.bat                    ← 双击没反应时的备用启动方式
│  ├─ resources/  locales/         ← 程序代码、界面、语言包
│  ├─ *.dll（7 个）                 ← 图形 / 视频 / 编译器等运行库
│  ├─ *.pak / *.bin / *.dat        ← 界面资源
│  └─ LICENSE.electron.txt · LICENSES.chromium.html  ← 开源许可声明
│
└─ ★ 自动生成的（随时可删）─────────────────
   ├─ settings.json                ← 你在「设置」里填的引擎路径（**删了要重填**）
   ├─ records/                     ← 你的棋谱 + 复盘报告 + 逐手讲解（**别删**）
   └─ userdata/                    ← 页面缓存（删了自动重建，不心疼）

一句话：只有 RapaceGo.exe 和那一...

v0.1.28 · 分支树看得清了（选中亮绿线 / 连线不再压珠子 / 默认收起按需展开）+ 全盘讲解前先问一句

v0.1.28 修补三（2026-10-15 晚，同版本号覆盖包）：修「同一方连下两子」的恶性 bug + 把状态同步彻底根治

★ 修：在分支树里操作之后，可能出现「连续两手都是同一方下」

症状：在分支树里点珠子 / 提升主变 / 删除分支 / 撤销删除之后，再落子有可能变成同一方连下两子。

根因：这些操作在重算「该谁走」时，用的是你正在看第几手；而「该谁走」只该看当前局面的末端。
回看历史手时两者不相等 → 轮次算偏了；之后你把视图挪回最新再落子，用的还是那个偏值。

修法（根治）：把「该谁走」从可变字段改成只读派生属性 —— 它永远等于「当前局面该谁走」，
代码里再也写不错（原来 15 处手工赋值全部删除）；
同时把「重建路径」和「重算打劫禁着点」也各自收进唯一入口，不再让每个操作用手写三行去同步。

★ 顺带修掉两个自查抓出来的隐患

• 停一手压进手顺的是个"半成品节点"（没有父指针）—— 在它被补上之前，
  树面板和分支计算会把它当成"没有来路"的一手。现在走与落子完全相同的建节点流程。
• **试下（打草稿）期间点「撤销删除分支」**会把局面退到存档点之前，破坏试下的语义 —— 现在与其它操作一样被挡住。

★ 这次是怎么验证的（不是只点几下）

新写了一个不变式自检，用 2000 步随机操作（落子 / 回看 / 换分支 / 提升 / 删除 / 撤销 / 悔棋 / 停一手 / 试下…）
反复压，每一步都检查七条必须成立的性质（路径连续、颜色交替、游标合法、劫点自洽、轮次恒等、树无孤儿、草稿闸门）——
0 违规。上面那两个隐患就是它头一次跑抓出来的。

---

2026-10-15 修补二（同版本号 v0.1.28，直接覆盖包）：界面四处 —— 分支树右键菜单、删除分支确认窗、快捷键精简、帮助更新。

★ 修：放大分支树后，右键点珠子的菜单弹不出来

菜单被放大窗的遮罩盖在下面了（轮廓看得见、点不着）。现在它浮在遮罩之上，右键正常弹出。

★ 改：删除分支要先弹窗确认

原来点「删除分支」只是把按钮文案变成「再点一次确认删除」、上方提示一句 —— 现在改成独立的确认窗：
写清「删掉第几手起的整条分支、一共几手、删完可以用 Ctrl+Shift+Z 放回来」，两个按钮【取消】/【删除】。
取消或点空白处 = 什么都不发生。

★ 改：快捷键精简（删掉三个）

删掉 Delete（删除分支）、空格（停一手）、PgUp（提升主变）：
这三件事在界面上都有入口（右键树面板的珠子、底栏「停一手」按钮），而且都是会改动棋谱结构的操作，
走「菜单 + 确认窗」比按一个键更稳妥。

留下的都是高频操作或显示开关：←/→ 翻手 · ↑/↓ 换分支 · Home/End 跳首尾 · C 折叠侧支 ·
Ctrl+Z 悔棋 · Ctrl+Shift+Z 撤销删除 · T/Z/M/B/Y/X/N 显示开关 · D 试下 · Ctrl+Shift+D 分析自检。

★ 改：帮助更新到最新

帮助里补上了整块「分支树」（点珠跳转、角标展开、绿色来路高亮、右键菜单、放大窗）和
「回看点落子 = 从那一手开新分支」（含「回看时也会显示淡一点的落子预览方块」）；快捷键表同步更新。

---

2026-10-15 修补（同版本号 v0.1.28，直接覆盖包）：修两个 bug —— 一手合法的「扑之后反提」被当成打劫、点分支树后棋子预览方块消失。

★ 修：一手合法的「扑之后反提」被当成打劫，点不进去

症状（在别的软件对弈、在这边录入棋谱时踩到）：第 84 手白扑、第 85 手黑提掉这一子，
第 86 手白点回原处本该提走 7 颗黑子，软件却提示「打劫：此处暂时不能下」。

根因：判断「这一点是不是打劫禁着点」时只比了坐标，没算「这一手本身也只提 1 子」。
倒扑这手一下提 7 子、局面根本不会重复，却被前一道闸门拦死。

修法：劫的判据换成主流开源围棋软件 Sabaki 的写法（四条同时成立才算制造劫）：
本手只提 1 子 · 落下的这子是孤子 · 它只有 1 口气 · 那口气正是刚被提掉的那一点。
「孤子」这条正是倒扑的抗体 —— 提完还连着己方大块的，一律不是劫。
顺带修掉同源隐患：悔棋 / 切分支后重算禁着点时，盘面与手数会错开一手。

★ 修：点分支树里的珠子之后，棋盘上的落子预览小方块没了

根因：预览方块原来有条限制「只在看到最新一手时才画」，点树上的珠子 = 跳到那一手 = 进入回看 → 被挡掉。

修法：回看中也画（本来就允许从回看点落子 —— 会从那一点开一条新分支），
但画成半透明并描边，与正常落子区分。

两个回归脚本随源码进仓库：dev/_cdp_ko.mjs（11 条，含 Sabaki 官方真劫棋形）、
dev/_cdp_hover.mjs（8 条，拿画布像素断言）。旧代码上分别红 8 条 / 4 条，改完全绿。

---

分支树看得清了（选中某手亮绿线 · 连线不再压珠子 · 默认收起按需展开 · 修「最上面拉不上去」）+ 全盘讲解前先问一句

下载（页面最下面的 Assets，按平台挑一个；这些包都不含引擎）：

平台	文件
macOS（M 系列，Apple 芯片）	RapaceGo-mac-arm64.zip
macOS（Intel）	RapaceGo-mac-x64.zip
Windows	RapaceGo-win.zip

引擎要自己配（见 README「显卡品牌」那一节）。

---

想省事？直接下懒人包（自带引擎，解压就能用）

上面那个 zip 不含引擎（KataGo 权重 + LoGos 模型要自己配）。
懒人包把这些全带齐了，解压后双击 RapaceGo.exe 即可，零配置：

👉 夸克网盘 · 玄清围弈懒人包　（提取码 Svze）

约 8.5 GB，含：程序本体 + KataGo（N 卡加速版和通用版两套，软件自己按显卡挑）+ LoGos 讲解模型。
下载后解压、双击 RapaceGo.exe 就能用 —— 不用再去看「显卡品牌」那一节。

展开看这一版改了什么

v0.1.28：分支树看得清了（选中某手亮绿线 · 连线不再压珠子 · 默认收起按需展开 · 修「最上面拉不上去」）+ 全盘讲解前先问一句

★ 选中某一手，往上到主干的那条链亮成绿线

在分支树里点某一手，从它一路往上到主干第一手的这条直系链会亮成绿色：

• 叔叔伯伯那条支不亮 —— 只亮你选的这条来路；
• 选中手以下的手不亮 —— 高亮到此为止；
• 沿途珠子不亮外圈，只有选中的那一颗带圈。

树一大就分不清「我这手是从哪儿来的」，现在一眼看得到来路。

★ 连线不再压在珠子上

真实棋谱里一次展开多条支时，会有连线贴着珠子画过去。查清了根因：
不是画线画错，是排行的兜底逻辑「明知会压还硬放」。改了两处：

• 排行的兜底改成降级（挑最不挤的位置），不再硬塞；
• 列距加宽约 18%，珠子之间更透气。

结果：按需展开 8 条支时，能修的地方全部零接触。

剩下极少数「一条支跨了 6 行以上」的情况，几何上无解 —— 但珠子是盖在连线之上的，
看上去就是线从珠子背后穿过（不是插进珠子里）。放大 3 倍实拍确认过，不是事故。

顺带：分支树行数从 276 降到 227，展开那一下的卡顿也明显减轻。

★ 默认收起、按需展开；「全部收起」留着

树面板默认只画主变，角标上写 +3 就表示那一手有 3 条侧支 —— 点角标才展开。
工具条上加了「全部收起」（一键回到只看主变）。「全部展开」已删掉。

★ 修「树最上面拉不上去」

以前树短的时候会纵向居中，于是内容上溢到滚动区上方、那段永远够不到（顶部被吃掉）。
现在一律顶部对齐，长树短树都不会再出现。

★ 全盘讲解前先问一句

以前点「全盘讲解」，不管算没算过都要把 KataGo 整盘重跑一遍（几分钟），
可旁边明明存着现成的胜率记录和逐手讲解。现在按情况先问：

情况	会发生什么
已经有整盘胜率记录	问：跳过重算（推荐，省下那几分钟）／重新算一遍
还没有任何讲解	什么都不问，直接开始
已经有讲解	问：接着讲没讲过的（推荐）／从头重跑

顺手修掉：跳过重算后「点了没反应」、停止按钮停不住、讲解词写着写着被重置。

★ 分支树布局重写（根治交叉）

树的行序重排：侧支之间不再交叉，珠子左上角不再贴边，手数不再出现 a/b 后缀
（同一手的多个分支改用树形展开表示），并修掉一处会让渲染进程卡死、页面全白的死循环。

关于「三大目录」的分工（维护者备查，也免得自己混）

位置	是什么	里面该有什么
RapaceGo\（开发目录）	改代码、跑测试的地方	源码 + node_modules + 一堆 _ 开头的开发脚本
dist\	只放要传 GitHub 的东西	只有 RapaceGo.zip（win-unpacked 是中间产物，同步完自动删）
玄清围弈\	本地自用的免解压版（唯一一个）	可直接双击运行的完整程序
桌面 RapaceGo懒人包\	给别人下载用的整包（传网盘，不传 GitHub）	程序 + KataGo + LoGos，解压即用、零配置

为什么懒人包不上 GitHub：它 8.2 GB，而 GitHub Release 单个附件上限 2 GB，
且大头（4.4GB 的 .gguf 模型、296MB 的 .bin.gz 权重）本身就是压缩格式，
再打 zip 也压不动。GitHub 那份走轻量路线（146MB + 首次运行自动下模型）。

★ 懒人包的目录约定（做包时最容易搞错的一条）

main.js 里打包态的「引擎位置」是和 RapaceGo.exe 平级，不是上一级：

BASE_DIR = IS_PACKAGED ? path.dirname(process.execPath) : __dirname;  // 打包后 = exe 目录
const up = IS_PACKAGED ? BASE_DIR : path.join(__dirname, '..');        // 打包后 up 就是 exe 目录本身
katago: path.join(up, 'KataGo', 'engine', 'katago.exe')

所以懒人包的布局必须是：

RapaceGo懒人包\
├─ RapaceGo.exe      ← 和下面两个目录平级
├─ KataGo\engine\katago.exe + weights\
└─ LoGos\llama-server.exe + *.gguf

别把程序本体再套一层 RapaceGo\ —— 那样软件会去找 懒人包\RapaceGo\KataGo\...，
而文件在 懒人包\KataGo\...，结果引擎永远起不来（实测 settings.check 五项全 false）。

重建懒人包：powershell -File _build_lazy.ps1（已含"删掉 settings.json / records"等铁律）。

下载

只有一个文件：

文件	大小	说明
RapaceGo.zip	约 146 MB	解压一次，之后从文件夹里双击启动 —— 启动最快，也最便携

包名固定不带版本号（这样每次下载地址都一样）。要知道自己装的是哪一版：
打开软件 → 左上角「帮助」，标题右边写着版本号。

完全不会用 GitHub 也能装（四步）

① 打开下载页：https://github.com/Rapace7/RapaceGo/releases

② 往下滑，找到最上面那条发布（标题写着版本号和日期，GitHub 的下载文件都放在「发布」里）

③ 那个区块下面有一栏 Assets

⚠️ Assets 不是一个文件夹，是这次发布附带的下载文件清单。
小白最容易在这儿绕晕 —— 你要找的就是这份清单里的文件。

④ 点清单里的 RapaceGo.zip 下载

• ⚠️ 别下页面最下面的 Source code (zip) —— 那是 GitHub 自动生成的源码压缩包，
  解压出来不能双击运行

⑤ 下载完右键「全部解压缩」，打开文件夹，双击 RapaceGo.exe —— 软件就起来了。

认准三样东西就行：① 最上面那条发布 → ② 它下面的 Assets 清单 → ③ 蓝色的 RapaceGo.zip

更新到新版本

把新包解压到原来那个文件夹、覆盖同名文件就行 —— 棋谱和设置不会丢。

1. 打开软件 → 左上角「帮助」，记下当前版本号
2. 到这个页面看最上面那条是不是更新了
3. 关掉软件（重要：程序开着文件被占用，覆盖会失败或只覆盖一半）
4. 下载新的 RapaceGo.zip → 解压到你现在用的那个文件夹 → 问是否覆盖时选「替换」
5. 重新双击 RapaceGo.exe

为什么不会丢东西：包里只有程序本体，records/（你的棋谱和讲解）、settings.json
（引擎路径）、KataGo/、LoGos/（引擎与模型）都不在包里，所以原样保留。

保险做法：更新前把 records 文件夹复制一份到别处 —— 那是唯一丢了找不回来的东西。

⚠️ 引擎要自己准备一次（包里不含）

下载包里只有软件本体（约 570KB 的代码 + Electron 运行时），两个引擎是别人的项目：

① KataGo（必需，不装就没有 AI 下棋和数据分析）

• 程序：https://github.com/lightvector/KataGo/releases 的 Windows 版
• 权重两个：https://katagotraining.org/ 的 b11c768nbt.bin.gz（算胜率）和
  b18c384nbt-humanv0.bin.gz（当对手，文件名带 human 的那个）

② 讲解模型（可选，4.4GB）

解压后的文件夹里有一个 下载讲解模型.bat —— 双击它就行。
它会自动下载、合并模型、装好推理运行时，全程中文提示；
中途断了重新双击会接着下（按精确字节数判断，没下全的续传）。

👉 已经自己下载了那三个 .part 分卷（part01/02/03）？
那就不用管 bat 了 —— 往下翻到 ▶ 点这里展开 那段，一行命令就能合并。

▶ 点这里展开：已经自己下好那三个 .part 分卷了？手动合并也行（不用 bat）

下载 LoGos-7B-Q4_K_M.gguf.part01 / .part02 / .part03 之后，任选一种方式合并成
LoGos-7B-Q4_K_M.gguf（三个文件放在同一个文件夹里）：

① 命令提示符一行

copy /b LoGos-7B-Q4_K_M.gguf.part01+LoGos-7B-Q4_K_M.gguf.part02+LoGos-7B-Q4_K_M.gguf.part03 LoGos-7B-Q4_K_M.gguf

② PowerShell（流式拷贝，内存占用低）

$out = [System.IO.File]::Create("LoGos-7B-Q4_K_M.gguf")
foreach ($p in "part01","part02","part03") {
  $i = [System.IO.File]::OpenRead("LoGos-7B-Q4_K_M.gguf.$p")
  $i.CopyTo($out); $i.Close()
}
$out.Close()

③ 7-Zip / WinRAR 不行 —— 压缩工具没有「合并分卷」功能。

⚠️ 合并后务必核对：应该是 4,683,071,328 字节（约 4.36 GB）。
不对就是没下全，删掉重下。核对完可以把三个 .part 删掉（省 4.4GB）。
然后回软件「设置」→ LoGos 组分别选 llama-server.exe 和合并出来的 .gguf。

为什么要分卷：GitHub 单个文件硬上限 2GB，而这模型 4.4GB —— 平台限制，
不是故意折腾你。三个分卷就是纯二进制切片，合并结果和原文件逐字节一致
（开发时用 sha256 验过）。

合并完还需要推理运行时（llama-server.exe）—— 上面那个 bat 会帮你装。

▶ 点这里展开：完全手动装（不用 bat、不用管分卷）

模型：YichuanMa/LoGos-7B 转的 GGUF Q4_K_M；
运行时：llama.cpp 的 Windows CUDA 版。
⚠️ 官方主包不含 CUDA 运行时，要另下同版本的 cudart-*.zip 放同目录。

装完之后文件夹长什么样

解压出来不止 RapaceGo.exe 一个文件，还有一堆 .dll、.pak、locales\ 之类 ——
那些都是软件自带的运行库（Electron 框架），不用管、也不要删（一共约 368 MB）。

下面把「你加进去的」和「软件自带的」分开写：

RapaceGo/                          ← 解压出来的文件夹（名字随便，拷到哪都能用）
│
├─ ★ 你自己准备的 ──────────────────────────
│  ├─ KataGo/                      ① 下 KataGo 的 Windows 版解压进来，改名成 KataGo
│  │  ├─ katago.exe
│  │  ├─ …（同目录还有一堆 .dll，一起放着别删）
│  │  └─ weights/                  ② 新建这个文件夹，放两个权重
│  │     ├─ b11c768nbt.bin.gz              算胜率 / 推荐点 / 形势
│  │     └─ b18c384nbt-humanv0.bin.gz      当 AI 对手（带 human 的那个）
│  └─ LoGos/                       ③ 双击「下载讲解模型.bat」之后自动出现（可选）
│     ├─ llama-server.exe
│     └─ LoGos-7B-Q4_K_M.gguf
│
├─ ★ 软件自带的（别删）─────────────────────
│  ├─ RapaceGo.exe                 ← 双击这个启动（245 MB，程序+框架都在里面）
│  ├─ 下载讲解模型.bat              ← 要讲解功能就双击它（会自动建上面的 LoGos/）
│  ├─ start.bat                    ← 双击没反应时的备用启动方式
│  ├─ resources/  locales/         ← 程序代码、界面、语言包
│  ├─ *.dll（7 个）                 ← 图形 / 视频 / 编译器等运行库
│  ├─ *.pak / *.bin / *.dat        ← 界面资源
│  └─ LICENSE.electron.txt · LICENSES.chromium.html  ← 开源许可声明
│
└─ ★ 自动生成的（随时可删）─────────────────
   ├─ settings.json                ← 你在「设置」里填的引擎路径（**删了要重填**）
   ├─ records/                     ← 你的棋谱 + 复盘报告 + 逐手讲解（**别删**）
   └─ userdata/                    ← 页面缓存（删了自动重建，不心疼）

一句话：只有 RapaceGo.exe 和那一堆自带的 dll/pak 是"程序本体"，其余要么是你放进去的引擎、
要么是它自己生成的数据。看不懂的文件不要删 —— 真正该动的只有 KataGo/、LoGos/ 和「设置」。
想彻底卸载：把整个文件夹删掉就行（棋谱想留就先复制 records/ 出来）。

装好后在软件左上角「设置」里指一下路径（选 katago.exe 时它会自动帮你填权重），
再点左上角（顶栏左侧）的引擎灯 →「加载」。

硬件：显存是主要门槛

实测（RTX 4070 Laptop / 8GB，nvidia-smi）：

组件	显存
KataGo 分析引擎	≈ 350 MB
KataGo 对弈引擎	≈ 170 MB
LoGos 讲解模型（Q4_K_M）	≈ 4.9 GB
三个全开	≈ 5.5 GB

6GB 显存的卡能用但别全开；4GB 或核显只能用 KataGo 部分功能。
软件默认一个引擎都不加载，用不到就不占显存。

说明

• 本项目代码 MIT；KataGo MIT；LoGos 授权为「仅研究、非商业」
• 讲解由本地小模型 LoGos ...

v0.1.27 · 手数分支树（回看能试下 / 分支存进棋谱 / 树面板 / 提升主变 / 删除分支）+ 讲解与界面修复

手数分支树（回看能试下 · 分支存进棋谱 · 水平分叉树面板 · 提升主变/删除分支）；讲解重写；棋手名能存进棋谱；棋谱库能“覆盖”

下载（页面最下面的 Assets，按平台挑一个；这些包都不含引擎）：

平台	文件
Windows	RapaceGo-win.zip

引擎要自己配（见 README「显卡品牌」那一节）。

---

想省事？直接下懒人包（自带引擎，解压就能用）

上面那个 zip 不含引擎（KataGo 权重 + LoGos 模型要自己配）。
懒人包把这些全带齐了，解压后双击 RapaceGo.exe 即可，零配置：

👉 夸克网盘 · 玄清围弈懒人包　（提取码 Svze）

约 8.5 GB，含：程序本体 + KataGo（N 卡加速版和通用版两套，软件自己按显卡挑）+ LoGos 讲解模型。
下载后解压、双击 RapaceGo.exe 就能用 —— 不用再去看「显卡品牌」那一节。

展开看这一版改了什么

v0.1.27：手数分支树（回看能试下 · 分支存进棋谱 · 水平分叉树面板 · 提升主变/删除分支）；讲解重写；棋手名能存进棋谱；棋谱库能“覆盖”

★ 全盘讲解会先问一句了（2026-10-14 补进这一版）

以前点「全盘讲解」，不管这份棋谱算没算过，都要把 KataGo 整盘分析重跑一遍（几分钟）——
可旁边明明就存着 <棋谱名>.review.json（整盘胜率）和 .coach.json（逐手讲解）。

现在按情况先问：

情况	会发生什么
已经有整盘胜率记录	弹窗告诉你这份记录是干什么的，并推荐「跳过重算」（省下那几分钟）；也可以选「重新算一遍」
还没有任何讲解	什么都不问，直接开始
已经有讲解	弹窗问：接着讲没讲过的（推荐）／从头重跑（把已讲的抹掉，从第一手重讲）

弹窗里会写清楚：整盘胜率是干嘛的（给每一手算胜率、标「这一手亏了多少」、画右边的走势图）、
已经讲过几手、还剩几手。取消随时可以点。

★ 手数分支树（这一版的大功能）

以前这软件只有一条手顺线：回看某一手时想试试别的下法，只能「试下」打个草稿，一退出就没了，
棋谱也存不下来。

现在能真正开分支了：

你想做的事	怎么做
在某一手试试别的下法	把局面退到那一手，直接落子 —— 自动开一条新分支，原来那条线留着不丢
在分支之间来回看	↑ ↓
把某条分支变成主线	跳到那一手，按 PgUp（原主线整枝还在，随时切回去）
删掉一整条分支	按 Delete —— 会先问一次，再按一次才真删；删错了按 Ctrl+Shift+Z 撤销
一眼看全所有分支	手数卡右上角的滑杆切到「树」
分支存进棋谱	导出时自动写成标准变着 (旧线)(新线)，别的围棋软件也认
打开带变着的棋谱	直接能看、能切分支；手数列表里标 ⑂1/2

树面板长什么样（参照 KaTrain 的「珍珠手串」）：

• 黑白棋子连着串起来，主变那条串金色外圈，当前在看的那一手是青色环 + 放大；
• 旁支从母珠上分出一条线垂下来再接进去，行与行之间不会交叉；
• 鼠标悬停出详情：手数 · 黑白 + 坐标 · 这一点共几种走法 · 这一手亏/赚多少胜率 ·
  复盘目损 · 此时黑棋胜率 · 有没有讲解；
• 右键按住拖动 = 拖动画布（原地右击才弹菜单：提升主变 / 删除分支）；
• 珠子上的手数是「12a 式」：分岔后同一支上的手共用字母后缀（12a、13a…），主线不带后缀。

试下（打草稿）不进分支树 —— 它还是「临时摆摆」，退出就干净了，不会在树上留幽灵旁支。

起因：一条讲解 bug，牵出了整块重写

用户实测发现：黑棋第 5 手实际下在 D16，讲解却在讲「如果黑棋下在 D4……」 ——
整段讲的是另一个点。查下去发现不是一个小错，是讲解的输入给错了。

根因：讲解一直拿「这一手之前」的盘面交给模型，却要求它讲「这一手之后」。
在那个盘面上正好轮到刚落子的那一方走 —— 模型看到的是「该我选点了」，
于是本能地退回它最擅长的「列候选点」。D4 就是它列的候选之一。

（顺带排除过一个更可疑的方向：不是坐标系上下颠倒。专门测过 ——
给模型一颗子问「它下在哪」，放 D16 答 D16、放 Q16 答「右上角」、放 C4 答「左下角」，全对。）

一、讲解现在长这样

每一手按 结论 → 道理 → 对照 三段给：

段	内容	谁说了算
① 结论	好棋就夸、烂棋就骂（口语，不写棋评八股）	KataGo 的胜率涨跌
② 道理	这一手碰到了谁、对方大概怎么应、好在哪差在哪	LoGos 讲
③ 对照	AI 当时更倾向下哪儿、那手多少胜率、你这一手差了几个点	KataGo 给的数字

好坏一定由 KataGo 说了算，不让模型自己判断。 为什么：实测同一手亏 8.5% 的棋跑两次，
模型一次骂「不太像棋啊」，一次夸「碰得很有想法」—— 它不稳定，而且会自己编胜率
（写出过「这个变化下白棋胜率 71.4%」这种根本没算过的数）。
现在结论由程序写死、模型只负责顺着讲理由。

一之二、讲解不再「瞎编盘面」（本次最重要的一处）

有用户实测发现：某手落在空空如也的角上，讲解却说「这手碰得有点早」
「黑棋在四个角都有子力，白棋的布局明显落后了」—— 全是编的。

根因：一直是让模型自己去读那个 19×19 的数字矩阵，判断"这一手碰到了谁"。
7B 读不准，读不准就凭"棋局感"瞎编。

现在盘面事实全部由程序算好喂进去，模型只负责顺着事实讲道理：

• 挨着谁 —— 四周八格没子，就明说「它既不是碰、也没挨着谁」
• 什么位置 —— 星位（4-4）/ 小目（3-4）/ 三三（3-3）/ 边 / 中腹
  （实测它把 3-4 的 D3 说成过「星位」）
• 四个角各有几颗子 —— 免得它再说"四个角都有子"

并且加了一条硬规矩：事实说是空的，就不许写「碰」「靠」「挡」「断」。
（光把"它不是碰"写在事实里没用 —— 它照样无视；写成一条独立规矩才管住。）

同一手、同一局面，改前改后：

	输出
改前	「白棋这手 D3 碰，明显是针对黑棋在左上小目的布局」
改后	「白棋在左下小目（3-4）落子，这个位置太偏了，既不能有效占角，对黑棋的压迫也不够。黑棋完全可以不理它」

还治不好的（7B 的能力边界，如实说明）：更细的地方它仍会编 ——
比如事实里写了「左上 黑1白2」，它照样说「黑棋左上两子」。
所以：事实类的信息（坐标/胜负/目损/碰到谁/什么位置）一律由程序给，
一个字都不让模型猜；棋理类的分析交给模型，但别指望它精确。

二、顺手清掉的六类废话

跑完整盘 217 手逐手看，模型翻来覆去就这几种毛病（下面每条都是真实原句）：

• 动作旁白：八十多手出现「（对着棋盘沉思片刻）」「（轻笑着摇头）」「（自言自语：…）」
  「（用教学语气）」—— 它把讲解写成剧本了
• 自己编的胜率：一律删；要数字由程序在最后补真的
• 推演变化图：「如果选择 D11 粘，预计变化：粘 / 扳 / 扳 / 粘……」这种残渣
• 替对方支招：「现在白棋有几个不错的选点值得考虑：」「白棋现在可以下在 P5 粘住」——
  你问的是这一手怎么样，不是教对手下棋
• 数字分点罗列：「1. 白棋下在 J18 粘住」—— 同上，而且把讲解写成条目了
• 「我建议…」：「我建议黑棋立即在 B17 扳一手」—— 评论员不该替谁出主意

顺带修掉的一个真 bug：讲解里出现「7一带」

有用户截图报的：某几手讲解里冒出「7一带已经形成了相当厚实的外势」，完全看不懂。

查出来是我们的清理正则干的 —— 模型用训练数据的记谱法写「X-L17」/「O-L17」，
而我们的清理是把整段抹成空格（当初的理由是"用户看不懂一个字母加横杠接坐标"），
于是「黑棋在 X-L17 一带」变成「黑棋在 一带」，甚至「X-L1 7一带」变成「7一带」。

现在改成只去掉前缀：「X-L17」→「L17」。
—— 用户当初抱怨的只是那个格式看不懂，坐标本身是该留的。

二之二、每手要讲「两三句」，不是只给一句结论

第一轮整盘跑完发现：有些手只剩「这手不行，这手有问题啊。」—— 只有结论，
没有理由，也没说这样下会怎样。

查出来是两层：① 给模型的生成长度太小（340），它写到 460 字左右就被掐断，
原始输出结尾是「这个变化虽然也能吃掉黑」这种半句；② "太短也算合格"的门槛太低，
这种一句结论也被放行了。

现在：生成长度 340 → 520、"讲出东西"的门槛 40 字 → 70 字
（不合格就重讲一遍），并在提示里把必须说到的三点写死：
碰到谁 / 对方大概怎么应 / 为什么好或不好。

三、棋手名能存进棋谱了

原来：打谱时点名字改名，界面上变了、文件里没变，重开还是 PLAYER1 / PLAYER2，
改几次都白改。原因：改名只写进了内存，而唯一会落盘的那条路只在「下完棋点保存」时才走 ——
打谱时根本不会触发。

现在：改完立刻写进棋谱（SGF 的 PB / PW 两项），别的软件也认。
而且只改这两个字段 —— 棋谱里的备注、解说词一字不动。

四、棋谱库

• 做得更大（580 → 880px），棋谱名和备注名完整显示、不再被截成「符…」
• 新增「覆盖」按钮（排在「删除」前面）：把当前棋盘上的这一盘棋写进这份棋谱，
  替换它原来的内容 —— 改完棋谱不用再「另存成一份新的、再手动删旧的」。
  覆盖前会自动留一份 .bak 备份，能捞回来。
• 覆盖之后这份棋谱的讲解对不上新内容了，要用就重跑一次「全盘讲解」

五、还有两处

• 桌面快捷方式改用中文名「玄清围弈」（和「玄清象棋」「玄清国象」统一）；
  老版本建的 RapaceGo.lnk 可以自己删掉
• 左栏比例调整：手数 / 分析讲解 / 推荐落点 = 2.5 : 5 : 2.5
  （原来 3:3:4，中间那栏从 30% 提到 50%）—— 复盘时中间才是主角

六、打开棋谱就能看到每手胜率

每手胜率（胜率 / 目差 / 目损）一直存在复盘报告里，但打开棋谱时不读它 ——
手数列表的「涨跌」列和走势图都是空的，非得再点一次「复盘报告」、或者重跑一遍「AI 复盘」。
数据本来就在，只是没人去拿。

现在打开棋谱就自动带出来：涨跌列有数字、走势图有曲线，不用再算一遍。

⚠️ 老棋谱里的讲解会自动作废

讲解是跟在棋谱旁边的（<棋谱名>.coach.json）。这次改了讲法，所以旧讲解
版本对不上一律作废，再点一次「全盘讲解」会按新讲法重讲。
（这是故意的 —— 不然修好了你也看不到新的。）

作废之后棋谱库里会明确标出来：那份棋谱显示「讲解要重讲」而不是「带讲解」，
点开也不会是一片空白让人以为坏了。

---

关于「三大目录」的分工（维护者备查，也免得自己混）

位置	是什么	里面该有什么
RapaceGo\（开发目录）	改代码、跑测试的地方	源码 + node_modules + 一堆 _ 开头的开发脚本
dist\	只放要传 GitHub 的东西	只有 RapaceGo.zip（win-unpacked 是中间产物，同步完自动删）
玄清围弈\	本地自用的免解压版（唯一一个）	可直接双击运行的完整程序
桌面 RapaceGo懒人包\	给别人下载用的整包（传网盘，不传 GitHub）	程序 + KataGo + LoGos，解压即用、零配置

为什么懒人包不上 GitHub：它 8.2 GB，而 GitHub Release 单个附件上限 2 GB，
且大头（4.4GB 的 .gguf 模型、296MB 的 .bin.gz 权重）本身就是压缩格式，
再打 zip 也压不动。GitHub 那份走轻量路线（146MB + 首次运行自动下模型）。

★ 懒人包的目录约定（做包时最容易搞错的一条）

main.js 里打包态的「引擎位置」是和 RapaceGo.exe 平级，不是上一级：

BASE_DIR = IS_PACKAGED ? path.dirname(process.execPath) : __dirname;  // 打包后 = exe 目录
const up = IS_PACKAGED ? BASE_DIR : path.join(__dirname, '..');        // 打包后 up 就是 exe 目录本身
katago: path.join(up, 'KataGo', 'engine', 'katago.exe')

所以懒人包的布局必须是：

RapaceGo懒人包\
├─ RapaceGo.exe      ← 和下面两个目录平级
├─ KataGo\engine\katago.exe + weights\
└─ LoGos\llama-server.exe + *.gguf

别把程序本体再套一层 RapaceGo\ —— 那样软件会去找 懒人包\RapaceGo\KataGo\...，
而文件在 懒人包\KataGo\...，结果引擎永远起不来（实测 settings.check 五项全 false）。

重建懒人包：powershell -File _build_lazy.ps1（已含"删掉 settings.json / records"等铁律）。

下载

只有一个文件：

文件	大小	说明
RapaceGo.zip	约 146 MB	解压一次，之后从文件夹里双击启动 —— 启动最快，也最便携

包名固定不带版本号（这样每次下载地址都一样）。要知道自己装的是哪一版：
打开软件 → 左上角「帮助」，标题右边写着版本号。

完全不会用 GitHub 也能装（四步）

① 打开下载页：https://github.com/Rapace7/RapaceGo/releases

② 往下滑，找到最上面那条发布（标题写着版本号和日期，GitHub 的下载文件都放在「发布」里）

③ 那个区块下面有一栏 Assets

⚠️ Assets 不是一个文件夹，是这次发布附带的下载文件清单。
小白最容易在这儿绕晕 —— 你要找的就是这份清单里的文件。

④ 点清单里的 RapaceGo.zip 下载

• ⚠️ 别下页面最下面的 Source code (zip) —— 那是 GitHub 自动生成的源码压缩包，
  解压出来不能双击运行

⑤ 下载完右键「全部解压缩」，打开文件夹，双击 RapaceGo.exe —— 软件就起来了。

认准三样东西就行：① 最上面那条发布 → ② 它下面的 Assets 清单 → ③ 蓝色的 RapaceGo.zip

更新到新版本

把新包解压到原来那个文件夹、覆盖同名文件就行 —— 棋谱和设置不会丢。

1. 打开软件 → 左上角「帮助」，记下当前版本号
2. 到这个页面看最上面那条是不是更新了
3. 关掉软件（重要：程序开着文件被占用，覆盖会失败或只覆盖一半）
4. 下载新的 RapaceGo.zip → 解压到你现在用的那个文件夹 → 问是否覆盖时选「替换」
5. 重新双击 RapaceGo.exe

为什么不会丢东西：包里只有程序本体，records/（你的棋谱和讲解）、settings.json
（引擎路径）、KataGo/、LoGos/（引擎与模型）都不在包里，所以原样保留。

保险做法：更新前把 records 文件夹复制一份到别处 —— 那是唯一丢了找不回来的东西。

⚠️ 引擎要自己准备一次（包里不含）

下载包里只有软件本体（约 570KB 的代码 + Electron 运行时），两个引擎是别人的项目：

① KataGo（必需，不装就没有 AI 下棋和数据分析）

• 程序：https://github.com/lightvector/KataGo/releases 的 Windows 版
• 权重两个：https://katagotraining.org/ 的 b11c768nbt.bin.gz（算胜率）和
  b18c384nbt-humanv0.bin.gz（当对手，文件名带 human 的那个）

② 讲解模型（可选，4.4GB）

解压后的文件夹里有一个 下载讲解模型.bat —— 双击它就行。
它会自动下载、合并模型、装好推理运行时，全程中文提示；
中途断了重新双击会接着下（按精确字节数判断，没下全的续传）。

👉 已经自己下载了那三个 .part 分卷（part01/02/03）？
那就不用管 bat 了 —— 往下翻到 ▶ 点这里展开 那段，一行命令就能合并。

▶ 点这里展开：已经自己下好那三个 .part 分卷了？手动合并也行（不用 bat）

下载 LoGos-7B-Q4_K_M.gguf.part01 / .part02 / .part03 之后，任选一种方式合并成
LoGos-7B-Q4_K_M.gguf（三个文件放在同一个文件夹里）：

① 命令提示符一行

copy /b LoGos-7B-Q4_K_M.gguf.part01+LoGos-7B-Q4_K_M.gguf.part02+LoGos-7B-Q4_K_M.gguf.part03 LoGos-7B-Q4_K_M.gguf

② PowerShell（流式拷贝，内存占用低）

$out = [System.IO.File]::Create("LoGos-7B-Q4_K_M.gguf")
foreach ($p in "part01","part02","part03") {
  $i = [System.IO.File]::OpenRead("LoGos-7B-Q4_K_M.gguf.$p")
  $i.CopyTo($out); $i.Close()
}
$out.Close()

③ 7-Zip / WinRAR 不行 —— 压缩工具没有「合并分卷」功能。

⚠️ 合并后务必核对：应该是 4,683,071,328 字节（约 4.36 GB）。
不对就是没下全，删掉重下。核对完可以把三个 .part 删掉（省 4.4GB）。
然后回软件「设置」→ LoGos 组分别选 llama-server.exe 和合并出来的 .gguf。

为什么要分卷：GitHub 单个文件硬上限 2GB，而这模型 4.4GB —— 平台限制，
不是故意折腾你。三个分卷就是纯二进制切片，合并结果和原文件逐字节一致
（开发时用 sha256 验过）。

合并完还需要推理运行时（llama-server.exe）—— 上面那个 bat 会帮你装。

▶ 点这里展开：完全手动装（不用 bat、不用管分卷）

模型：YichuanMa/LoGos-7B 转的 GGUF Q4_K_M；
运行时：llama.cpp 的 Windows CUDA 版。
⚠️ 官方主包不含 CUDA 运行时，要另下同版本的 cudart-*.zip 放同目录。

装完之后文件夹长什么样

解压出来不止 RapaceGo.exe 一个文件，还有一堆 .dll、.pak、locales\ 之类 ——
那些都是软件自带的运行库（Electron 框架），不用管、也不要删（一共约 368 MB）。

下面把「你加进去的」和「软件自带的」分开写：

RapaceGo/                          ← 解压出来的文件夹（名字随便，拷到哪都能用）
│
├─ ★ 你自己准备的 ──────────────────────────
│  ├─ KataGo/                      ① 下 KataGo 的 Windows 版解压进来，改名成 KataGo
│  │  ├─ katago.exe
│  │  ├─ …（同目录还有一堆 .dll，一起放着别删）
│  │  └─ weights/                  ② 新建这个文件夹，放两个权重
│  │     ├─ b11c768nbt.bin.gz              算胜率 / 推荐点 / 形势
│  │     └─ b18c384nbt-humanv0.bin.gz      当 AI 对手（带 human 的那个）
│  └─ LoGos/                       ③ 双击「下载讲解模型.bat」之后自动出现（可选）
│     ├─ llama-server.exe
│     └─ LoGos-7B-Q4_K_M.gguf
│
├─ ★ 软...

v0.1.26 · 出了 macOS 版（可自己打包）+ Win 包改名 RapaceGo-win.zip

出了 macOS 版（要自己打包）；同步脚本不再误删引擎；产物名区分 win / mac

下载（页面最下面的 Assets，按平台挑一个；三个都不含引擎）：

平台	文件
Windows	RapaceGo-win.zip
macOS（M 系列）	RapaceGo-mac-arm64.zip
macOS（Intel）	RapaceGo-mac-x64.zip

引擎要自己配（见 README「显卡品牌」那一节）；想省事就用懒人包（网盘那个完整包，自带引擎）。

展开看这一版改了什么

v0.1.26：出了 macOS 版（要自己打包）；同步脚本不再误删引擎；产物名区分 win / mac

📌 2026-10-09 深夜补充（只改说明，程序文件没有任何变化）

macOS 版发布后，用户实测反馈了说明里漏掉的一步，已修正：

从浏览器下载的引擎文件（llama-server、KataGo、LoGos 的 .gguf）也要过一遍
xattr -cr —— 只对 RapaceGo.app 做是不够的。

原因：macOS 会给浏览器下载的每个文件打上隔离标记（com.apple.quarantine），
带标记的二进制不能执行。表现是「软件能识别到这个程序，但就是跑不起来」——
不容易往隔离属性上想。

# 下官方 llama.cpp 包的人：对解压出来那一整个文件夹做（它要靠同目录的 .dylib）
xattr -cr ~/Downloads/llama-bXXXXX-bin-macos-arm64/

更省事的办法：两个引擎都用 Homebrew 装，压根不用碰这一步 ——

brew install katago
brew install llama.cpp      # → /opt/homebrew/bin/llama-server

然后在「设置」里直接指 Homebrew 的路径。README 已按这个思路重写。

🔧 本次只改文档，不涉及程序代码 —— RapaceGo-win.zip / -mac-arm64.zip /
-mac-x64.zip 三个包与之前完全相同，不必重新下载。

感谢 @zhenli789 的实测反馈 —— 这条只在真实 Mac 上才暴露得出来。

先说下载：这一版有三个包，别拿错

你要的平台	下哪个
Windows	RapaceGo-win.zip
macOS（M 系列 / Apple Silicon）	RapaceGo-mac-arm64.zip
macOS（Intel）	RapaceGo-mac-x64.zip

三个包都不含引擎（历来如此）—— 引擎要自己配，见 README 的「显卡品牌」那一节。
想省事就用懒人包（网盘那个完整包），它自带引擎、解压即用。

macOS 版：能用，但你要自己打包

代码层面已经支持 macOS 了。但我们不提供预编译的 Mac 包 —— 原因很实在：
开发者没有 Mac 机器，打出来的包没人能实测，不敢发没验过的东西；
而且 Apple 的签名公证要开发者年费（$99/年），暂时没投。

不过 "自己打包"只需要四条命令，而且 Mac 上装引擎比 Windows 还简单：

brew install katago                    # Metal 后端，Apple Silicon 原生
git clone https://github.com/Rapace7/RapaceGo.git && cd RapaceGo
npm install && npm run dist:mac        # 产出 dist/RapaceGo-mac-arm64.zip
xattr -cr /Applications/RapaceGo.app   # 未签名包第一次打开要过 Gatekeeper

那 Releases 里的 RapaceGo-mac-*.zip 是什么？ 是我在 GitHub 的 macOS 机器上
打出来的参考产物 —— 给不想自己装 Node 环境的人直接用。同样是未签名的，
第一次打开照样要 xattr -cr 或右键→打开。

已知限制（诚实说明）：

• 只承诺 Apple Silicon（M 系列） —— Homebrew 有 arm64 预编译瓶；
  Intel Mac 没有瓶，brew install katago 会从源码编译，很久。
• 整条 Mac 路径没有实机验证过（没有 Mac 机器）。代码改动是完整的
  （引擎名不再写死 .exe、加了 Mac 应用菜单、⌘ 快捷键），
  在 Windows 上跑全套测试确认没改坏，但真机效果要靠反馈。

Windows 用户：这一版修了一个会"删掉几 GB 引擎"的隐患

_sync_deploy.ps1（我自己同步用的脚本，不影响用户）的保留清单原来是
settings.json + records\，把 KataGo\、LoGos\ 当"旧内容"清掉。

这在"免解压版不自带引擎、靠配置里的绝对路径找引擎"的年代是对的 ——
但这次我们把引擎搬进免解压版内部（做成自包含、搬到哪都能跑）之后，
再清就等于把引擎删了。实测踩到：同步完引擎全没、软件起不来。

已修：保留清单加上这两个引擎目录。

对普通用户的影响：没有。 这是我自己工作流的脚本。
写出来是因为"前提变了、旧代码还在按旧前提干活"这类问题最容易复发。

其他

• 产物名改了：Windows 那个从 RapaceGo.zip 改成 RapaceGo-win.zip
  —— 因为现在有 mac 包了，不区分容易拿错。
• Win 版还修了 3 处文档错话（设置面板里能改 / 别解压成嵌套 / 不附带引擎），
  这些在 v0.1.25 的补丁里已经改过，这一版把打包产物也带上了。

验证（真机实测）

① Windows v0.1.26 免解压版启动正常
   下棋/分析：CUDA（v1.18.2） · 显卡：RTX 4070（NVIDIA）
             · AI 讲解：CUDA0（可用 8187 MB） —— ✓ 都能配上
② 同步两次，第二次确认引擎目录没被清掉（8.06 GB 完好）
③ mac 包在 GitHub 的 macOS runner 上打包成功（arm64 + x64）
④ Windows 全套测试：单测 12/1/7/1 全过，3 个 lint 全 0

关于「三大目录」的分工（维护者备查，也免得自己混）

位置	是什么	里面该有什么
RapaceGo\（开发目录）	改代码、跑测试的地方	源码 + node_modules + 一堆 _ 开头的开发脚本
dist\	只放要传 GitHub 的东西	只有 RapaceGo.zip（win-unpacked 是中间产物，同步完自动删）
玄清围弈\	本地自用的免解压版（唯一一个）	可直接双击运行的完整程序
桌面 RapaceGo懒人包\	给别人下载用的整包（传网盘，不传 GitHub）	程序 + KataGo + LoGos，解压即用、零配置

为什么懒人包不上 GitHub：它 8.2 GB，而 GitHub Release 单个附件上限 2 GB，
且大头（4.4GB 的 .gguf 模型、296MB 的 .bin.gz 权重）本身就是压缩格式，
再打 zip 也压不动。GitHub 那份走轻量路线（146MB + 首次运行自动下模型）。

★ 懒人包的目录约定（做包时最容易搞错的一条）

main.js 里打包态的「引擎位置」是和 RapaceGo.exe 平级，不是上一级：

BASE_DIR = IS_PACKAGED ? path.dirname(process.execPath) : __dirname;  // 打包后 = exe 目录
const up = IS_PACKAGED ? BASE_DIR : path.join(__dirname, '..');        // 打包后 up 就是 exe 目录本身
katago: path.join(up, 'KataGo', 'engine', 'katago.exe')

所以懒人包的布局必须是：

RapaceGo懒人包\
├─ RapaceGo.exe      ← 和下面两个目录平级
├─ KataGo\engine\katago.exe + weights\
└─ LoGos\llama-server.exe + *.gguf

别把程序本体再套一层 RapaceGo\ —— 那样软件会去找 懒人包\RapaceGo\KataGo\...，
而文件在 懒人包\KataGo\...，结果引擎永远起不来（实测 settings.check 五项全 false）。

重建懒人包：powershell -File _build_lazy.ps1（已含"删掉 settings.json / records"等铁律）。

下载

只有一个文件：

文件	大小	说明
RapaceGo.zip	约 146 MB	解压一次，之后从文件夹里双击启动 —— 启动最快，也最便携

包名固定不带版本号（这样每次下载地址都一样）。要知道自己装的是哪一版：
打开软件 → 左上角「帮助」，标题右边写着版本号。

完全不会用 GitHub 也能装（四步）

① 打开下载页：https://github.com/Rapace7/RapaceGo/releases

② 往下滑，找到最上面那条发布（标题写着版本号和日期，GitHub 的下载文件都放在「发布」里）

③ 那个区块下面有一栏 Assets

⚠️ Assets 不是一个文件夹，是这次发布附带的下载文件清单。
小白最容易在这儿绕晕 —— 你要找的就是这份清单里的文件。

④ 点清单里的 RapaceGo.zip 下载

• ⚠️ 别下页面最下面的 Source code (zip) —— 那是 GitHub 自动生成的源码压缩包，
  解压出来不能双击运行

⑤ 下载完右键「全部解压缩」，打开文件夹，双击 RapaceGo.exe —— 软件就起来了。

认准三样东西就行：① 最上面那条发布 → ② 它下面的 Assets 清单 → ③ 蓝色的 RapaceGo.zip

更新到新版本

把新包解压到原来那个文件夹、覆盖同名文件就行 —— 棋谱和设置不会丢。

1. 打开软件 → 左上角「帮助」，记下当前版本号
2. 到这个页面看最上面那条是不是更新了
3. 关掉软件（重要：程序开着文件被占用，覆盖会失败或只覆盖一半）
4. 下载新的 RapaceGo.zip → 解压到你现在用的那个文件夹 → 问是否覆盖时选「替换」
5. 重新双击 RapaceGo.exe

为什么不会丢东西：包里只有程序本体，records/（你的棋谱和讲解）、settings.json
（引擎路径）、KataGo/、LoGos/（引擎与模型）都不在包里，所以原样保留。

保险做法：更新前把 records 文件夹复制一份到别处 —— 那是唯一丢了找不回来的东西。

⚠️ 引擎要自己准备一次（包里不含）

下载包里只有软件本体（约 570KB 的代码 + Electron 运行时），两个引擎是别人的项目：

① KataGo（必需，不装就没有 AI 下棋和数据分析）

• 程序：https://github.com/lightvector/KataGo/releases 的 Windows 版
• 权重两个：https://katagotraining.org/ 的 b11c768nbt.bin.gz（算胜率）和
  b18c384nbt-humanv0.bin.gz（当对手，文件名带 human 的那个）

② 讲解模型（可选，4.4GB）

解压后的文件夹里有一个 下载讲解模型.bat —— 双击它就行。
它会自动下载、合并模型、装好推理运行时，全程中文提示；
中途断了重新双击会接着下（按精确字节数判断，没下全的续传）。

👉 已经自己下载了那三个 .part 分卷（part01/02/03）？
那就不用管 bat 了 —— 往下翻到 ▶ 点这里展开 那段，一行命令就能合并。

▶ 点这里展开：已经自己下好那三个 .part 分卷了？手动合并也行（不用 bat）

下载 LoGos-7B-Q4_K_M.gguf.part01 / .part02 / .part03 之后，任选一种方式合并成
LoGos-7B-Q4_K_M.gguf（三个文件放在同一个文件夹里）：

① 命令提示符一行

copy /b LoGos-7B-Q4_K_M.gguf.part01+LoGos-7B-Q4_K_M.gguf.part02+LoGos-7B-Q4_K_M.gguf.part03 LoGos-7B-Q4_K_M.gguf

② PowerShell（流式拷贝，内存占用低）

$out = [System.IO.File]::Create("LoGos-7B-Q4_K_M.gguf")
foreach ($p in "part01","part02","part03") {
  $i = [System.IO.File]::OpenRead("LoGos-7B-Q4_K_M.gguf.$p")
  $i.CopyTo($out); $i.Close()
}
$out.Close()

③ 7-Zip / WinRAR 不行 —— 压缩工具没有「合并分卷」功能。

⚠️ 合并后务必核对：应该是 4,683,071,328 字节（约 4.36 GB）。
不对就是没下全，删掉重下。核对完可以把三个 .part 删掉（省 4.4GB）。
然后回软件「设置」→ LoGos 组分别选 llama-server.exe 和合并出来的 .gguf。

为什么要分卷：GitHub 单个文件硬上限 2GB，而这模型 4.4GB —— 平台限制，
不是故意折腾你。三个分卷就是纯二进制切片，合并结果和原文件逐字节一致
（开发时用 sha256 验过）。

合并完还需要推理运行时（llama-server.exe）—— 上面那个 bat 会帮你装。

▶ 点这里展开：完全手动装（不用 bat、不用管分卷）

模型：YichuanMa/LoGos-7B 转的 GGUF Q4_K_M；
运行时：llama.cpp 的 Windows CUDA 版。
⚠️ 官方主包不含 CUDA 运行时，要另下同版本的 cudart-*.zip 放同目录。

装完之后文件夹长什么样

解压出来不止 RapaceGo.exe 一个文件，还有一堆 .dll、.pak、locales\ 之类 ——
那些都是软件自带的运行库（Electron 框架），不用管、也不要删（一共约 368 MB）。

下面把「你加进去的」和「软件自带的」分开写：

RapaceGo/                          ← 解压出来的文件夹（名字随便，拷到哪都能用）
│
├─ ★ 你自己准备的 ──────────────────────────
│  ├─ KataGo/                      ① 下 KataGo 的 Windows 版解压进来，改名成 KataGo
│  │  ├─ katago.exe
│  │  ├─ …（同目录还有一堆 .dll，一起放着别删）
│  │  └─ weights/                  ② 新建这个文件夹，放两个权重
│  │     ├─ b11c768nbt.bin.gz              算胜率 / 推荐点 / 形势
│  │     └─ b18c384nbt-humanv0.bin.gz      当 AI 对手（带 human 的那个）
│  └─ LoGos/                       ③ 双击「下载讲解模型.bat」之后自动出现（可选）
│     ├─ llama-server.exe
│     └─ LoGos-7B-Q4_K_M.gguf
│
├─ ★ 软件自带的（别删）─────────────────────
│  ├─ RapaceGo.exe                 ← 双击这个启动（245 MB，程序+框架都在里面）
│  ├─ 下载讲解模型.bat              ← 要讲解功能就双击它（会自动建上面的 LoGos/）
│  ├─ start.bat                    ← 双击没反应时的备用启动方式
│  ├─ resources/  locales/         ← 程序代码、界面、语言包
│  ├─ *.dll（7 个）                 ← 图形 / 视频 / 编译器等运行库
│  ├─ *.pak / *.bin / *.dat        ← 界面资源
│  └─ LICENSE.electron.txt · LICENSES.chromium.html  ← 开源许可声明
│
└─ ★ 自动生成的（随时可删）─────────────────
   ├─ settings.json                ← 你在「设置」里填的引擎路径（**删了要重填**）
   ├─ records/                     ← 你的棋谱 + 复盘报告 + 逐手讲解（**别删**）
   └─ userdata/                    ← 页面缓存（删了自动重建，不心疼）

一句话：只有 RapaceGo.exe 和那一堆自带的 dll/pak 是"程序本体"，其余要么是你放进去的引擎、
要么是它自己生成的数据。看不懂的文件不要删 —— 真正该动的只有 KataGo/、LoGos/ 和「设置」。
想彻底卸载：把整个文件夹删掉就行（棋谱想留就先复制 records/ 出来）。

装好后在软件左上角「设置」里指一下路径（选 katago.exe 时它会自动帮你填权重），
再点左上角（顶栏左侧）的引擎灯 →「加载」。

硬件：显存是主要门槛

实测（RTX 4070 Laptop / 8GB，nvidia-smi）：

组件	显存
KataGo 分析引擎	≈ 350 MB
KataGo 对弈引擎	≈ 170 MB
LoGos 讲解模型（Q4_K_M）	≈ 4.9 GB
三个全开	≈ 5.5 GB

6GB 显存的卡能用但别全开；4GB 或核显只能用 KataGo 部分功能。
软件默认一个引擎都不加载，用不到就不占显存。

说明

• 本项目代码 MIT；KataGo MIT；LoGos 授权为「仅研究、非商业」
• 讲解由本地小模型 LoGos 生成，只输出中文（训练数据是中文标注）。
  看不懂中文的话：把讲解文字选起来丢进翻译工具就行（软件里允许选中复制）。
• 代码几乎全部由 AI Agent 编写（对话由 DeepSeek V4.1 Flash 驱动），
  完整的决策过程见仓库里的 开发记录.md

v0.1.25 · 自检同时查两套引擎 + 引擎装两套时自动挑对显卡那套（本 zip 不含引擎）

自检现在同时报告两套引擎的状态；引擎装了两套时，软件自己挑对显卡那套

下载：页面下面的 Assets 里那个 RapaceGo.zip（约 146 MB）。

展开看这一版改了什么

v0.1.25：自检现在同时报告两套引擎的状态；引擎装了两套时，软件自己挑对显卡那套

先说明：这个 zip 里没有引擎

GitHub 上这个 RapaceGo.zip 是程序本体（约 146 MB），历来不含引擎和权重 ——
引擎要你自己按 README 的「显卡品牌」那一节准备（那里有每种显卡该下哪个包的对照表）。

懒人包（网盘那个完整包） 才是自带引擎的，而且这一版开始它两套一起带、软件自动挑。
下面「懒人包的变化」那节讲的是那个，不是这个 zip。

这一版你（从这个 zip 装的）实际得到的改动

① 「引擎兼容性自检」现在查两套引擎，不是只查一套

以前只检查 KataGo。问题是 KataGo 和讲解引擎（LoGos）是两套独立的引擎、各有各的显卡构建 ——
所以 A 卡用户按提示把 KataGo 换成 OpenCL 版之后，讲解引擎还是 N 卡那套、照样用不了，
而软件一句话都不说。那是最让人困惑的情况。现在分开报：

下棋/分析：CUDA（v1.18.2） · 显卡：NVIDIA GeForce RTX 4070 Laptop GPU（NVIDIA）
          · AI 讲解：CUDA0（可用 8187 MB） —— ✓ 都能配上

② 引擎装了两套时，软件自己挑对的那套

如果你同时留着 engine\ 和 engine-generic\（或 runtime-nvidia\ / runtime-generic\），
软件会看你的显卡挑对的那个用。原来只会死盯着配置里写的那一个。

③ 修了文档里 3 处说错的话（都是"把源码模式的行为当成打包版"这个病）：

原来写的	真相
「别解压成嵌套两层，程序按上一级找引擎」	打包版按 exe 所在目录找，嵌套无关
FAQ「找不到引擎？默认是放在项目上一级」	同上
「纯 CPU 模式（设置面板里能改）」	设置面板没有切换后端的控件，要下 eigen 版再指路径

还有软件内帮助里那句「引擎和权重本软件不附带」—— 对懒人包已经不对了，改成区分说明。

懒人包的变化（网盘那个完整包，不是这个 zip）

懒人包原来只装 NVIDIA 引擎，A 卡 / Intel 核显用户下完 8.5 GB 才发现跑不了。
现在两套一起带：

你的显卡	用哪套	谁挑的
NVIDIA	CUDA 加速版（最快）	软件自动挑
AMD / Intel / 核显	通用版（OpenCL + Vulkan）	软件自动挑

打开软件时自己看显卡、挑对的那套 —— 不选、不配、不挪文件。

验证（真机实测）

① 只有通用版引擎的包  → 自动挑到 engine-generic\katago.exe，自检报 OpenCL，
                        端到端真分析出结果（首选点 C4，胜率 95.0%）
② 两套都有的包        → 自动挑到 engine-nvidia\katago.exe，自检报 CUDA，
                        引擎 5 秒起来 + 分析出结果（首选点 C5，胜率 94.7%）
③ 免解压版整体        → 自检同时报出 KataGo(CUDA) 与 LoGos(CUDA0 / 8187 MB)
④ 嵌套两层目录        → 引擎正常找到、自检通过（打包版按 exe 所在目录找）
⑤ 默认不加载引擎      → 启动前后 katago / llama-server 进程数都是 0

诚实说明

A 卡 / Intel 那一路没有实机验证过 —— 开发机只有 RTX 4070。
通用版引擎能加载、能自报后端（已实测），但真在 A 卡上跑起来没测过。
如果按上表换了引擎还起不来，把「引擎兼容性自检」的结果贴到 Issue 里，我来定位。

顺手修掉的几个坑

• (?m) 是 PCRE 的写法，直接在 JS 里写会 SyntaxError（JS 要用 /re/m）
• 自动挑引擎的路径算错一层，导致两套并存时永远找不到另一套、静默不换
• 命令行传带反斜杠的路径会被当转义（"D:\GoStudy\_t2" 里的 \t 变成 Tab）

v0.1.24 · 帮助顶部加直达目录 + 设置里加「检查更新」

帮助顶部加直达目录（吸顶，滚多远都能跳）

下载：页面下面的 Assets 里那个 RapaceGo.zip（约 146 MB）。

展开看这一版改了什么

v0.1.24：帮助顶部加直达目录（吸顶，滚多远都能跳）

您要的功能

「软件内的帮助要有顶部列出的直达按钮，直接拉到对应位置，方便快速查询」
—— 做了，而且比"跳一次"更顺手一点：

① 六个直达按钮：第一次使用 · 界面分区 · 主要功能 · 四种规则 · 快捷键 · 数据怎么看

② 按钮排做成了吸顶（sticky）：往下翻到任何位置，这排按钮都还在头顶——
不用先滚回最上面才能跳去别的小节。这才是"便于查询"的关键。

③ 当前在哪一节会自动高亮：翻到"快捷键"那一节，目录里"快捷键"就变实心高亮，
一眼知道自己读到哪、还剩哪些没看。

④ 每次打开帮助都回到最上面，不会留着上次翻到一半的位置。

实现里踩到的两个坑（都记在代码注释里了）

坑一：CSS 的 scroll-behavior: smooth 会和"先归零再测量"打架。
它让每一次 scrollTop 赋值都变成动画 —— 于是"把滚动归零、再量目标元素的绝对位置"
这套算法失效：赋值后立刻量，量到的还是动画中途的值（实测设了 0、读到 72），跳转位置全错。
去掉 CSS 的平滑滚动，改成自己在 JS 里用 rAF 做 —— 该瞬时就瞬时、该平滑才平滑。

坑二：在布局不稳定的时候量位置。
弹窗关闭时是 display:none（里面所有元素位置都是 0）；
刚打开时还在做出现动画（量出来会偏）。两次都栽在同一个病上。
现在改成：只在弹窗稳定显示后量一次、缓存起来，之后所有跳转都用缓存值，
不再依赖任何实时测量。

验证（真机，15 条断言全过）

点「第一次使用」→ 落在顶部 44px    ✓
点「界面分区」  → 落在顶部 44px    ✓
点「主要功能」  → 落在顶部 44px    ✓
点「四种规则」  → 落在顶部 44px    ✓
点「快捷键」    → 落在顶部 44px    ✓
点「数据怎么看」→ 落在顶部 44px    ✓
滚动时高亮跟随当前小节              ✓
每次重开回到第一节                  ✓

（44px 是给吸顶目录让出的高度 —— 标题不会被按钮压住半行。）

---

---

v0.1.23：新增「检查更新」+ 修「分析讲解」讲错了对象

一、设置里新增「关于与更新」

您要的三件事都齐了：

位置	作用
当前版本	显示你在用的是哪一版（本地读，不发请求）
检查更新	点一下问 GitHub 最新版是多少，和本机比 —— 结果如实说：已是最新 / 有新版本 / 检查失败
去下载页	用系统浏览器打开 GitHub 上最新版的发布页（永远指向最新，不用改代码）

故意定的两条规矩：

1. 检查失败时绝不谎报"已是最新" —— 连不上就明说连不上。
2. 「去下载页」不依赖检查成功 —— 网络被挡时用户照样能手动去下。

二、修「分析讲解」讲错了对象（真 bug）

您实测撞到的：自己第 83 手亏 0.1%，讲解却整段在讲 AI 想下的 D8。

根因：代码里把 AI 推荐的那个点传给了 LoGos，而不是您实际下的那一手。
于是「分析讲解」输出的其实是"如果下在 AI 推荐点会怎样" —— 答非所问。
（「全盘讲解」里是同一个错，一起修了。）

用您那份 83 手棋谱实测（实际下的是 S12，AI 想的是 D8）：

改之前：如果黑棋下在 D8，……          ← 讲的是另一个点
改之后：这一手 S12（黑棋第 83 手）下出来，……   ← 讲的是您下的那一手

顺带改了 prompt：明确要求它先说这一手之后会发生什么
（碰到了哪些棋子、切断了什么、多了少了气、对方最可能的应手），
而不是只讲"该下在哪"。顶部提示也写清了「AI 想下的是 X；实际下的是 Y」。

三、修一个我自己造成的隐患：测试不再碰真棋谱

承认一个失误：测试要拿真实棋谱当夹具，我往 records\ 里拷文件、跑完删掉 ——
有一次清理写宽了，把用户自己下的一盘棋和一份职业棋谱一起删了（后来从回收站和备份里捞回来了）。

根因是"测试和用户数据共用一个目录"，所以从两头堵死：

• 程序支持 RAPACEGO_RECORDS 环境变量，可把棋谱库强制指到别处
  （★ 只在用户自己没在设置里指定过时生效，不抢用户的设置）
• 测试脚本 _rtest.py 默认就用 <项目>\_trash\records_test\，
  测试实例从此读写全在临时目录，怎么折腾都伤不到真棋谱

四、新增一条纪律检查：除了检查更新，任何地方都不出网

按您的说法「本软件无需联网，只有检查更新用网」，把它做成了可执行的检查
（dev/_lint_net.mjs）—— 以后谁（包括我）顺手加个联网调用，一跑就会被拦住。

当前审计结果：

出网点	判定
跟 LoGos 说话（127.0.0.1 的 /health、/completion）	✓ 本机回环，不出网卡
检查更新（api.github.com / github.com）	✓ 白名单，且只在你点按钮时发
其他	零
偷偷引的联网库（axios/got/node-fetch…）	零

顺带澄清一处：KataGo 自带的配置文件里满是 # https://… —— 那是注释里的文档链接，
不是请求。lint 里专门做了注释过滤，免得自己被自己骗。

---

v0.1.22 · 配置不再写入自动识别的路径（保持解压到哪都能用）

配置不再写入"自动识别出来的路径"（保持"解压到哪都能用"）

下载：页面下面的 Assets 里那个 RapaceGo.zip（约 146 MB）。

展开看这一版改了什么

v0.1.22：配置不再写入"自动识别出来的路径"（保持"解压到哪都能用"）

修的问题（我自己在 v0.1.21 里引入的）

做 v0.1.21 的权重自动识别时，我把"失效就回退"加在了 normalizeConfig 里 ——
而那个函数的结果会被 settings:save 写进 settings.json。
于是实测发现包里存下了：

"analyzeWeight": "...\\RapaceGo懒人包\\KataGo\\weights\\Bot.bin"   ← 自动识别结果，不是用户填的

这恰恰破坏了我们自己的设计：一旦用户把文件夹挪个位置 / 复制给别人，
这两条就变成失效的绝对路径，而那本来是"相对软件目录解析"就能解决的问题。

改法：把"解析"和"存盘"分开

环节	该做什么
readConfig（读盘）	做失效回退 —— 路径指的文件不在了就退回默认（运行时决定"用哪条"）
normalizeConfig（存盘用）	只做"填了没有"的规范化，不解析 —— 用户填什么就原样留着
settings:save	与默认值相同的路径不写进配置文件（含「最近用过」列表）

判据很直白：结果等于默认 → 就等于"没有自定义" → 不必存。
存下来的只可能是"用户确实指到了别处"，那才该持久化。

验证（真机端到端，用改名过的权重）

把懒人包的 weights 只留 Bot.bin / Human.bin（模拟夸克上传后的形态），启动：

① 权重自动识别    → Bot.bin / Human.bin   两个都 ok
② 加载分析引擎    → 3 秒就绪
③ 点一次「保存」  → settings.json 里五个路径字段**全是空串**、
                    recent 列表也**空**（不再存自动识别的路径）

再手动把文件夹当作"用户挪过位置"验证过：路径失效时能自己找回 Bot.bin / Human.bin。

测试

dev/_test_weight_bin.cjs 扩到 12 条，其中三条专测这次的分工：

• 配置里存着失效路径 → readConfig 回退到自动识别到的权重、并如实报 fellBack
• 配置有效时 readConfig 原样保留（不覆盖用户手动选的）
• normalizeConfig 不做解析（存盘不能写进解析结果）

顺带记一个坑：测试夹具最初漏了 RECENT_MAX，而 readConfig 自己有 try/catch ——
ReferenceError 被静默吞掉、直接走 catch 返回默认值，表现成"回退没生效"。
排查了半天才发现是夹具的问题、代码是对的。以后给这类函数做沙箱测试，依赖的模块级常量要一次列全。

---

v0.1.21 · 支持裸 .bin 权重（夸克网盘那种）

支持裸 .bin 权重（夸克网盘那种：解压后的文件）

下载：页面下面的 Assets 里那个 RapaceGo.zip（约 146 MB）。

展开看这一版改了什么

v0.1.21：支持裸 .bin 权重（夸克网盘那种：解压后的文件）

修的问题

用户报：夸克网盘不允许分享压缩包格式，所以把 KataGo 权重 .bin.gz 解压成 .bin
再上传，别人下到 .bin 之后，在「设置」里选不中那个文件 —— 手里明明有权重却用不了。

根因：我们把后缀和文件名都写死了。一共四处：

地方	原来	现在
文件选择框的过滤器	extensions: ['gz']	['gz', 'bin'] + 一个「全部文件」兜底
自动扫描权重（guessWeights）	只匹配 \.bin\.gz$	\.bin(\.gz)?$ —— 两种都认
选错文件时的报错文案	"请选 .bin.gz 结尾的权重"	说明两种都行
默认权重路径（defaultPaths）	把文件名写死成 b11c768nbt.bin.gz / b18c384nbt-humanv0.bin.gz	找不到就在同目录里找同类权重

最后那条才是致命的：懒人包里放的是解压后又改过名的裸权重（Bot.bin / Human.bin），
跟写死的名字对不上 → 双击懒人包后两个权重路径全指空、引擎起不来，
而用户去设置里手动选时文件框又只显示 .gz → 开箱不能用。

还补了一道：normalizeConfig 里，如果配置中存着的路径已经失效
（挪过文件夹、或之前手动选过旧文件），也去同目录找同类权重 ——
否则光是"从没配过"的人能得救，配过的人反而永远卡在「★ 找不到」。

KataGo 本身完全支持裸 .bin —— 实测：解压出的 268 MB .bin 能正常加载、分析、
返回候选点与胜率，与 .gz 行为一致（只是文件大一点：约 200 MB → 约 270 MB）。

认名字的规则：带 human 字样的归对弈权重、其余归分析权重，大小写无关
（所以 Human.bin、human.bin、Bot.bin、bot.bin 都能自动认）。

更新到这一版要替换什么

不用重下整包（懒人包 8GB 里 8GB 都是引擎和模型，它们没变）。
只要替换 resources\app\ 里的文件即可 —— 从 GitHub 下的那个 RapaceGo.zip（约 146 MB）
解出来，把里面的 resources\app\ 覆盖到原来的位置：

Expand-Archive RapaceGo.zip -DestinationPath $env:TEMP\rg -Force
Copy-Item "$env:TEMP\rg\resources\app\*" "你的懒人包\resources\app\" -Recurse -Force

⚠️ 只覆盖 RapaceGo.exe 是没用的 —— 它只是 Electron 的启动壳，不含程序逻辑；
真正的代码在 resources\app\main.js 和 resources\app\renderer\ 里。

验证

• dev/_test_weight_bin.cjs（11 条）：裸 .bin 识别、.bin.gz 老行为不坏、
  混合正确分类、空目录不崩、Bot.bin/Human.bin/小写 bot.bin/human.bin 都能自动找到、
  配置存着失效路径时能回退、配置有效时原样保留（不覆盖用户手动选的）。
• 正则单测 10 个正反例（不能把 foo.gz / note.bin.txt / .gguf 误认成权重）。
• 真机端到端：懒人包只留 Bot.bin / Human.bin 启动 →
  程序自己算出路径指向它们（files 全 true）→ 命令加载分析引擎 → 3 秒就绪。

顺手

• 帮助里补了说明：两种后缀都行；文件选择框里看不到时，可切「全部文件」。
• 修了外部贡献 dev/_test_hints.cjs：它原来断言「两个开关同步」，
  但用户要求删掉讲解卡片里那个重复开关，所以改成断言只剩一个（并检查另一个确实不存在）。

v0.1.20 · 规则全面审查 + 采纳外部贡献

v0.1.20：规则全面审查（对照 KataGo）+ 采纳外部贡献 + 推荐落点交互澄清

一、规则审查：揪出并修掉三个规则错误

这一版把围棋规则对着权威实现逐条核了一遍（KataGo 的规则引擎 + 开源围棋软件 KaTrain）。

① 让 3 子的位置错了。 第三子原来摆在左上，通行摆法是右上。
（KataGo 的 place_free_handicap 3 输出 D4 Q16 Q4 可印证。）2/4~9 子都是对的，只有 3 子这一档错。

② 座子制（明清规则）的黑白放反了。 原来是「左上/右下 = 黑」，
正确是「黑子在右上角 + 左下角，白子在左上角 + 右下角」
（依据：座子制通行规则原文「黑座子放置于右上角和左下角的四四位，白座子依此类推」）。
这个错影响整套明清规则 —— 古谱摆出来黑白是反的。

③ 打劫判据用的是我自己琢磨的启发式，会误禁合法棋。 换成开源围棋软件 KaTrain 的判据：
「上一手是否只提了 1 子、且提的正是这一手要下的那一点」+「这一手是否也只提 1 子」。
它不预判未来，天然避开倒扑和"提掉一个本来就只剩 1 气的子"这两类误判。
（我前后错了四版，全错在"预判未来"上。）

顺手还改了两处我们自己代码的问题：

• rebuildCapAt 的棋盘索引语义搞错（boardAt(i) 是"走完第 i 手"，我按"走了 i 手"取，
  整个错开一手）→ 悔棋后打劫判据形同失效。这正是您之前报的"悔棋后能直接提劫"的根子之一。
• _cdp_ko.mjs 里一条测试期望值写错了（写的是"倒扑回提应合法"），
  拿 KataGo 实测那个形，它判 illegal move —— 是断言错、代码对。

核对无误的：贴目（用空盘 final_score 反推：中 7.5 / 日韩 6.5 / 明清 0）、
还棋头（同局面只改块数，ancient-area 差 2 目 → tax=ALL 生效且我们没有重复计算）、
规则名映射、2~9 子让子摆法、星位（9/13/19 路）、坐标（GTP 跳 I / SGF 含 i）、
停一手与终局、SGF 导出。

二、采纳外部贡献（感谢 jerry barbarrossasky）

★ 按 SGF 的 SZ 属性读棋盘大小（原 PR #3）
原来 parseSGF 把「节点」当「属性」访问（t.id / t.vals），而节点结构是 {props, at, end} ——
于是 SZ 永远读不到，9 路和 13 路的棋谱全被按 19 路打开。改用现成的 firstProp('SZ') 读取。

★ 推荐落点交互改进（原 PR #6）
把「棋盘上的实时推荐」和「点击生成的讲解快照」明确分开，快照上方标明对应手数，
局面变化时提示「当前局面已变化」。

这一项我们做了调整（作者误会的根源）

作者做这个交互的起因是：他以为 LoGos 的讲解和 KataGo 的推荐是两套不同的点。
实际上点全部来自 KataGo，LoGos 只负责解释（prompt 里点名讲哪一点，还校验它有没有讲错点）。
所以「LoGos 推荐落点」这个名字本身就在强化误解，已改成：
标题「推荐落点讲解」+ 小字「KataGo 选点 · LoGos 讲道理」，
并且删掉了卡片里那个重复的「实时推荐落点」开关 ——
用「显示」菜单里那一个就行（快捷键 T），两处重复只会让人搞不清该信哪个。
他真正治好的那个病（实时推荐与旧快照会分歧、却没提示）保留了。

三、没采纳的

设置里可选「启动时自动加载引擎」（原 PR #4）—— 代码本身没问题，但它改的是
2026-10-05 已经定过的事（默认不加载任何引擎，因为开软件常常只是想摆棋打谱，
一开就吃几 GB 显存没道理）。这一版不并入。

---

v0.1.19：推荐点卡住的真根因 + 轻量化（撤掉调试日志、给引擎日志设上限）

一、修「推荐点永远不出来 / 那行『计算中… N』定住不动」

根因：悔棋时会清掉"这批选点作废"的记号，但另一个记号没跟着清。

if (state.candAt > len) state.candAt = -1;   // 这批选点废了
if (shownAt > len) shownAt = -1;             // ← 只管了"大于新长度"这一种情况

悔棋退到某一手时会出现：candAt（比如 6）> len（2）→ 清成 -1；
但 shownAt 恰好等于 2（≤ len）→ 原样留着。

于是**「这批选点废了」与「这个局面显示过了」同时成立**，成了死结：

• runAnalysis 判 shownAt !== cur → 为假 → 跳过当前局面，不重算
• scheduleAnalysis 又因 history[cur] 有值 → 不入队

两头都不动手 → 那个局面永远不再分析。修法：这两个记号是同一批结果的一对，
要废一起废。

怎么找到的：前两版都没修对（我先判成"记在了没上屏的结果上"——那条本身对，
但没打到这个问题；我加的自愈网还被自己写坏、只试一次就放弃）。
最后是让它把分析链路的关键决定写进日志文件，从日志里直接看到：

schedule at=2 入队=否(history已有→不入队) q=[] shownAt=2 candAt=-1 busy=true hist[2]=有
★ run 认为已算过但 candAt=-1 ≠ viewAt=2

验证：单元（截断时两个记号都要清 / candAt 有效时不误清）；
场景（落 8 手 → 回看第 2 手 → 回最新 → 悔棋退到第 2 手 → 116ms 选点重新上屏）；
猛捶 80 轮后日志里那个异常从 2 次降到 0 次。用户实测：不卡了。

二、轻量化：不做"一直产生垃圾文件"的软件

用户要求：「软件要尽量轻量化，尽量不像手机 APP 一样一直产生垃圾文件」。

• 撤掉上面那个分析链路日志：它实测玩 20 秒写 63.8 KB（约 11 MB/小时），
  而且是同步写盘。它是排查偶发问题的临时手段，问题解决后就该撤。
• 引擎日志自动限量：每次启动引擎，KataGo 会写自己的日志（2 个文件，几 KB），
  会无限累积。现在启动时自动只留最近 20 个。
  （实测：造 30 个 → 启动一次 → 剩 20 个，删的是最旧的。）
• Chromium 磁盘缓存上限 32 MB + 媒体缓存 8 MB（本软件不联网，只当保险绳）。

现在的写盘清单（都审过，没有会无限涨的）

写什么	增长情况
settings.json	固定一个文件
records\ 棋谱 / 复盘 / 讲解	同名覆盖，不涨
records\*.sgf.bak	每份棋谱最多 1 个（第一次编辑解说词时留的备份）
engine-logs\	只留最近 20 个
userdata\（GPU/着色器缓存）	约 8 MB 后稳定，另设了磁盘缓存上限

三、这个版本还包含（它们没有单独发 Release）

applyAnalysis 如实报告有没有真上屏、shownAt 只在真上屏时才记、
自愈网（卡住时每 6 秒重试一次、且自己续排，不依赖用户再操作）、
Ctrl+Shift+D 自检键修好（原来被上面一道 Ctrl 总闸挡成死代码）。

---

v0.1.17：查「选点卡住」的过程（这些都没有单独发 Release，留作记录）

怎么找到的（这次不是猜的）

用户报「AI 落子后很短时间内点悔棋，选点推荐和形势分析就卡住不显示，有时候会有时候不会」。
我在两台机器上做了三轮压力测试（共 100 轮、含 AI 思考中悔棋、悔棋延迟随机 0~400ms），
一次都复现不出来。

于是给软件加了一个自检键（Ctrl+Shift+D），让用户在自己那台出问题的机器上按一下。
他读出来这一行：

分析自检·局面: 2手·看第2手·选点: 还没算过·搜索量: 200·请求: 空闲·引擎: 就绪·链路: 轮30/成功19/空跑0

这一行就把病灶锁定了：

读数	说明
选点: 还没算过	candAt = -1，候选点从未上屏
搜索量: 200	请求发出去过、也回过进度（所以不是"没发请求"）
请求: 空闲、空跑0	队列空了、没有待办、也没有请求失败

三个事实合起来只有一个解释：软件认为「这个局面已经算过了」，所以永远不再算它。

真根因（一行代码）

applyAnalysis(res, at);   // ← 内部有提前 return（报文与当前局面不符 / 搜索量太低时直接返回）
shownAt = at;             // ← 但它**无条件**标记"已上屏"

applyAnalysis 提前返回时候选点根本没画上去，可 shownAt 已经记成"这个局面显示过了"。
而 runAnalysis 的判据是 shownAt !== cur —— 于是这个局面永远不再重算：
棋盘上方那行「计算中… N」定住，推荐点永远不出现。

为什么"有时候会有时候不会"：at !== state.viewAt 那条判断 ——
报文回来时局面刚好又变了（AI 刚落子、或用户刚落子），这一趟结果被当成
"补历史欠账"处理：只记走势、不画选点。这是个竞态，只在特定时序成立，所以偶发。

修法

1. applyAnalysis 现在如实报告有没有真上屏（返回布尔）：
   报文与当前局面不符 → false；搜索量太低（<20）→ false；真画上去了 → true。
2. runAnalysisOnce 只有真上屏才记 shownAt —— 没上屏就留着重算，死结解开。
3. 再加一道自愈网：若出现「算过但没上屏」这个不一致状态（shownAt === viewAt
   但 candAt !== viewAt），6 秒后自己重算一次。万一还有别的路径造成同样不一致，
   也不会再卡住等用户"再落一手"来撞开。
4. Ctrl+Shift+D 自检键修好了（原来写在 switch 里，被上面一道 Ctrl 总闸提前 return
   挡成死代码，按了没反应）+ 加了分析链路计数。

验证

项	结果
applyAnalysis 四种入参的返回值	正常→true / 局面不符→false / 搜索量太低→false / 空结果→false ✅
人为造出用户那个卡住状态，自愈网	6 秒救回，候选点上屏，路径记进埋点 ✅
强制重算后 shownAt 与 candAt 一致	✅
综合回归（悔棋/回看/涨跌/刷新/一致性）	全绿 ✅
打劫回归（悔棋×打劫，用那份 GN[打劫BUG] 棋谱）	全绿 ✅
倒扑仍合法（没被误判成劫）	✅
极限压力 40 轮（独立调试实例、rank_3d、极短延迟悔棋）	恢复 1.3~1.5 秒，无卡住 ✅

说明

这次有用户的实测读数做判据，不再是"我读代码猜出来的漏洞" —— 所以这一版可以说
根因是确定的。但请留意：如果那个竞态的触发条件还有我没覆盖到的分支，
自愈网（第 3 条）会兜住它，最多晚 6 秒，不会再永久卡住。

---

一、悔棋之后能无视禁着点直接提劫（用户报的，附了他自己存的棋谱）

现象：白提劫 → 黑被禁 → 黑在他处走一手 → 白补劫 → 黑悔棋回到「白提完劫」
→ 这时黑能直接提回去（禁着点凭空消失）。

根因：悔棋那段有一句 state.koPoint = null;。
注释写的只对一半 —— 退掉「提劫那一手」时它确实该失效，
但退到「刚提完劫」那个局面时它必须重新成立。
反方向也错：悔棋退掉一个「在别处走」的手之后，劫其实又成立，禁着点本该回来。

修法：悔棋后按新局面重算（新增 koFromBoard()），判据与 tryPlay 里那段逐条一致
（上一手提 1 子 + 落子是孤子 + 只剩一口气）—— 单一来源，避免两处规则跑偏。
因为沿用了「孤子」那条判据，上次修好的倒扑误判不会回退（已回归验证）。

验证（用那份棋谱逐手重下 32 手走到「白提完劫」）：

步骤	结果
提劫后生成禁着点	R17 ✓
立刻回提	被拒 ✓
走别处后禁着点清空	✓
悔棋回到提劫那一刻	禁着点重新成立 = R17 ✓
此时直接回提（报的那一手）	被拒 ✓
别处仍可正常落子	✓（没把局面锁死）

二、分析链路两处「卡住不会自愈」的隐患

用户报「AI 落子后马上悔棋，选点/形势有时卡住不显示，有时候会有时候不会」。
我按那个时序做了压力测试（60 轮、悔棋延迟随机 0~400ms、含 AI 思考中悔棋），
测试环境里 0 轮卡住，但翻代码找到了两个真实的机制漏洞：

1. shownAt 悔棋后没有跟着退。它是「屏幕上这批结果算的是第几手」，
   悔棋把局面变短之后如果它还指着一个已不存在的手数，
   runAnalysis 的判据 shownAt !== cur 就变成永远为假 ——
   它以为当前局面已算过，于是永远不再重算：候选点 / 胜率 / 形势雾停在旧值。
   原来只退了 candAt / ownAt，漏了 shownAt（它是模块级变量，不在 state 上，
   所以前几次审查都没扫到）。
2. 被 cancel 的那条路没有重排。分析请求被掐掉（比如数子时 runScore 会 cancel）
   返回 false 之后，anaBusy 放开了，但「重算当前局面」这个意图没人再触发 ——
   如果这一刻正好没有落子/回看，分析就停在那儿不动了。现在会主动重排一次。

另外给 Ctrl+Shift+D 自检加了一组分析链路计数（启动轮数 / 成功次数 / 空跑次数 /
提前 return 的原因），下次再遇到卡住，按一下就能看出它卡在哪一步。

三、顺带：测试跑在「活目录」上，动到了用户的棋谱

做这些测试时发现用户那份 20261007-155056-34手.sgf 从他的棋谱库里消失了。
已从备份快照完整恢复（内容逐字节一致，时间戳 15:51:39 对得上），
并新增 dev\_guard_records.ps1：跑任何端到端测试之前把用户 records 整个收起来、
跑完原样放回。以后测试再也碰不到用户的棋谱库。

打劫那份棋谱也复制成了仓库内 fixture（dev\fixtures\打劫BUG-34手.sgf），
测试不再依赖用户目录。

---

v0.1.15：修「悔棋之后能无视禁着点直接提劫」+ 分析链路两处卡死隐患

一、悔棋之后能无视禁着点直接提劫（用户报的，附了他自己存的棋谱）

现象（用户报的，附了他自己存的棋谱 GN[打劫BUG]）

白提劫 → 黑被禁着 → 黑在他处走一手 → 白补上劫空 → 黑悔棋…
悔到「白提完劫」那个局面时，黑能直接提回去 —— 也就是禁着点凭空消失了。

根因

悔棋那一段里有一句：

state.koPoint = null;          // 局面变了，打劫禁着点随之失效

注释说的只对了一半：

• 退掉提劫那一手时，禁着点确实该失效 ✅
• 退到**「刚提完劫」那个局面时，禁着点必须重新成立** ❗ ← 这里丢了

于是悔棋之后禁着点永远是 null，等于把劫禁手放行了。
反方向也错：悔棋退掉一个「在别处走」的手之后，劫其实又成立了，禁着点本该回来，却也是 null。

修法

悔棋后按新局面重算禁着点，而不是清空：

state.koPoint = koFromBoard(boardAt(state.moves.length), state.moves);

koFromBoard() 的判据与 tryPlay 里那段逐条一致（单一来源，避免两处规则跑偏）：
上一手提了恰好 1 子、落下的那颗是孤子、且它只剩一口气 → 那口气就是禁着点。

为什么必须带「孤子」那条：倒扑时落子连着自己人，对方回提会一口气提走 ≥2 子、
局面并不重复，那是合法的好手 —— 这条判据是 2026-10-06 修倒扑误判时定下来的，
这次原样沿用，所以倒扑仍然不会被误判成劫（已回归验证）。

验证

用用户自己那份棋谱（records\20261007-155056-34手.sgf）逐手重下 32 手，走到「白提完劫」：

步骤	结果
① 提劫后生成禁着点	R17 ✓
② 立刻回提	被拒 ✓
③ 在别处走一手	禁着点清空 ✓
④ 悔棋回到提劫那一刻	禁着点重新成立 = R17 ✓
⑤ 此时直接回提（用户报的那一手）	被拒 ✓
⑥ 别处仍可正常落子	✓（没把局面锁死）
⑦ 再撤一手后再试回提	仍被拒 ✓

同时回归：倒扑仍合法（提走 2 子、不误判为劫）、静态三件套全绿、综合回归
（悔棋 / 回看 / 涨跌数字 / 刷新按钮 / 界面一致性）全绿。

说明

顺带查清一件事：那份棋谱里 32 手全部合法、没有任何一手违反禁着点。
棋谱第 33 手 B[R17]（黑提回）是合法的 —— 因为在那之前白还下过一手自杀手，
棋盘没变也没提子，所以不产生新劫。所以这份棋谱本身没问题，是悔棋把禁着点弄丢了。

---

v0.1.13：修「引擎版本旧了吃不下新权重」+ 仓库目录整理 + Mac/显卡指引

现象

用户反馈（转来的原话）：「训练站最新的分析权重需要更高版本的 katago，旧版引擎会直接退出」。

根因（查证过，不是猜测）

KataGo 的权重是分代际的，引擎只认自己那一代和更早的：

权重代际	需要引擎
transformer（kata1-tf3-…，训练站现在最新的一批都是这个）	v1.17.0 以上
b28 系列	v1.14.0 以上
b18c384nbt 系列	v1.13.0 以上

两条硬证据：

1. 训练站首页公告（原文）：2026-09-15 — Support for versions prior to v1.18.0 has been retired.
   （前一条 2026-08-25：transformer 权重已上传，没升到 v1.18.0+ 的请尽快升）
2. katago.exe 里自带的报错文案：

   This neural net requires a newer KataGo version. Obtain a newer KataGo at https://github.com/...
   This neural net is from an extremely old version of KataGo and is no longer supported by the engine.

版本对不上时引擎加载权重失败后直接退出，于是软件里只显示「引擎异常 / 分析失败」——
用户看不出原因，只会觉得软件坏了。

本软件的实际情况（实测）

我们打包的引擎是能用的。本机实测：

KataGo v1.18.1 + 训练站最新 transformer 权重（kata1-tf3-b11c768-s12252M-d6398M）
  → Model version 17 · Model name: kata1-tf3-… (nbt transformer, 70442025 params)
  → Loaded model ✓

所以问题不在包，在"引擎版本 ↔ 权重代际"的搭配。

修法

1. 打包的引擎升到最新：v1.18.1 → v1.18.2（官方 2026-08-30，最后一个稳定版）
2. 把引擎的原话透到界面上（这条最要紧）：main.js 现在监听引擎 stderr，
   命中「requires a newer KataGo version」这类文案就把它转写成一句能照着做的话，
   显示在棋盘中央的提示框和右侧胜率卡上 —— 而不是只说「引擎异常」。
3. 文档写清楚代际对应表：README 与帮助面板都加了「引擎版本与权重代际」一节，
   并推荐「引擎和权重都从 KataGo 的 Release 页拿，那里附带的必定配套」。

顺带：仓库根目录整理

反馈"GitHub 页面上文件太多，要拉很久才看到产品介绍"。查了一下：
根目录 67 个文件里有 51 个是我的开发脚本（_cdp_*.mjs 测试脚本等）。

现在全部搬进 dev/，根目录只剩 16 个（README、LICENSE、程序本体、renderer/、assets/…）。
同时写了 dev/README.md 说明那堆脚本怎么用，并把脚本里写死的盘符路径改成按自身位置推导。

验证

• v1.18.2 + 最新 transformer 权重：加载成功、分析输出正常（退出码 0）
• 旧权重（`b11c768nb...

v0.1.19 · 修「推荐点不出来 / 计算中定住」+ 轻量化

v0.1.19：推荐点卡住的真根因 + 轻量化（撤掉调试日志、给引擎日志设上限）

一、修「推荐点永远不出来 / 那行『计算中… N』定住不动」

根因：悔棋时会清掉"这批选点作废"的记号，但另一个记号没跟着清。

if (state.candAt > len) state.candAt = -1;   // 这批选点废了
if (shownAt > len) shownAt = -1;             // ← 只管了"大于新长度"这一种情况

悔棋退到某一手时会出现：candAt（比如 6）> len（2）→ 清成 -1；
但 shownAt 恰好等于 2（≤ len）→ 原样留着。

于是**「这批选点废了」与「这个局面显示过了」同时成立**，成了死结：

• runAnalysis 判 shownAt !== cur → 为假 → 跳过当前局面，不重算
• scheduleAnalysis 又因 history[cur] 有值 → 不入队

两头都不动手 → 那个局面永远不再分析。修法：这两个记号是同一批结果的一对，
要废一起废。

怎么找到的：前两版都没修对（我先判成"记在了没上屏的结果上"——那条本身对，
但没打到这个问题；我加的自愈网还被自己写坏、只试一次就放弃）。
最后是让它把分析链路的关键决定写进日志文件，从日志里直接看到：

schedule at=2 入队=否(history已有→不入队) q=[] shownAt=2 candAt=-1 busy=true hist[2]=有
★ run 认为已算过但 candAt=-1 ≠ viewAt=2

验证：单元（截断时两个记号都要清 / candAt 有效时不误清）；
场景（落 8 手 → 回看第 2 手 → 回最新 → 悔棋退到第 2 手 → 116ms 选点重新上屏）；
猛捶 80 轮后日志里那个异常从 2 次降到 0 次。用户实测：不卡了。

二、轻量化：不做"一直产生垃圾文件"的软件

用户要求：「软件要尽量轻量化，尽量不像手机 APP 一样一直产生垃圾文件」。

• 撤掉上面那个分析链路日志：它实测玩 20 秒写 63.8 KB（约 11 MB/小时），
  而且是同步写盘。它是排查偶发问题的临时手段，问题解决后就该撤。
• 引擎日志自动限量：每次启动引擎，KataGo 会写自己的日志（2 个文件，几 KB），
  会无限累积。现在启动时自动只留最近 20 个。
  （实测：造 30 个 → 启动一次 → 剩 20 个，删的是最旧的。）
• Chromium 磁盘缓存上限 32 MB + 媒体缓存 8 MB（本软件不联网，只当保险绳）。

现在的写盘清单（都审过，没有会无限涨的）

写什么	增长情况
settings.json	固定一个文件
records\ 棋谱 / 复盘 / 讲解	同名覆盖，不涨
records\*.sgf.bak	每份棋谱最多 1 个（第一次编辑解说词时留的备份）
engine-logs\	只留最近 20 个
userdata\（GPU/着色器缓存）	约 8 MB 后稳定，另设了磁盘缓存上限

三、这个版本还包含（它们没有单独发 Release）

applyAnalysis 如实报告有没有真上屏、shownAt 只在真上屏时才记、
自愈网（卡住时每 6 秒重试一次、且自己续排，不依赖用户再操作）、
Ctrl+Shift+D 自检键修好（原来被上面一道 Ctrl 总闸挡成死代码）。

---

v0.1.17：查「选点卡住」的过程（这些都没有单独发 Release，留作记录）

怎么找到的（这次不是猜的）

用户报「AI 落子后很短时间内点悔棋，选点推荐和形势分析就卡住不显示，有时候会有时候不会」。
我在两台机器上做了三轮压力测试（共 100 轮、含 AI 思考中悔棋、悔棋延迟随机 0~400ms），
一次都复现不出来。

于是给软件加了一个自检键（Ctrl+Shift+D），让用户在自己那台出问题的机器上按一下。
他读出来这一行：

分析自检·局面: 2手·看第2手·选点: 还没算过·搜索量: 200·请求: 空闲·引擎: 就绪·链路: 轮30/成功19/空跑0

这一行就把病灶锁定了：

读数	说明
选点: 还没算过	candAt = -1，候选点从未上屏
搜索量: 200	请求发出去过、也回过进度（所以不是"没发请求"）
请求: 空闲、空跑0	队列空了、没有待办、也没有请求失败

三个事实合起来只有一个解释：软件认为「这个局面已经算过了」，所以永远不再算它。

真根因（一行代码）

applyAnalysis(res, at);   // ← 内部有提前 return（报文与当前局面不符 / 搜索量太低时直接返回）
shownAt = at;             // ← 但它**无条件**标记"已上屏"

applyAnalysis 提前返回时候选点根本没画上去，可 shownAt 已经记成"这个局面显示过了"。
而 runAnalysis 的判据是 shownAt !== cur —— 于是这个局面永远不再重算：
棋盘上方那行「计算中… N」定住，推荐点永远不出现。

为什么"有时候会有时候不会"：at !== state.viewAt 那条判断 ——
报文回来时局面刚好又变了（AI 刚落子、或用户刚落子），这一趟结果被当成
"补历史欠账"处理：只记走势、不画选点。这是个竞态，只在特定时序成立，所以偶发。

修法

1. applyAnalysis 现在如实报告有没有真上屏（返回布尔）：
   报文与当前局面不符 → false；搜索量太低（<20）→ false；真画上去了 → true。
2. runAnalysisOnce 只有真上屏才记 shownAt —— 没上屏就留着重算，死结解开。
3. 再加一道自愈网：若出现「算过但没上屏」这个不一致状态（shownAt === viewAt
   但 candAt !== viewAt），6 秒后自己重算一次。万一还有别的路径造成同样不一致，
   也不会再卡住等用户"再落一手"来撞开。
4. Ctrl+Shift+D 自检键修好了（原来写在 switch 里，被上面一道 Ctrl 总闸提前 return
   挡成死代码，按了没反应）+ 加了分析链路计数。

验证

项	结果
applyAnalysis 四种入参的返回值	正常→true / 局面不符→false / 搜索量太低→false / 空结果→false ✅
人为造出用户那个卡住状态，自愈网	6 秒救回，候选点上屏，路径记进埋点 ✅
强制重算后 shownAt 与 candAt 一致	✅
综合回归（悔棋/回看/涨跌/刷新/一致性）	全绿 ✅
打劫回归（悔棋×打劫，用那份 GN[打劫BUG] 棋谱）	全绿 ✅
倒扑仍合法（没被误判成劫）	✅
极限压力 40 轮（独立调试实例、rank_3d、极短延迟悔棋）	恢复 1.3~1.5 秒，无卡住 ✅

说明

这次有用户的实测读数做判据，不再是"我读代码猜出来的漏洞" —— 所以这一版可以说
根因是确定的。但请留意：如果那个竞态的触发条件还有我没覆盖到的分支，
自愈网（第 3 条）会兜住它，最多晚 6 秒，不会再永久卡住。

---

一、悔棋之后能无视禁着点直接提劫（用户报的，附了他自己存的棋谱）

现象：白提劫 → 黑被禁 → 黑在他处走一手 → 白补劫 → 黑悔棋回到「白提完劫」
→ 这时黑能直接提回去（禁着点凭空消失）。

根因：悔棋那段有一句 state.koPoint = null;。
注释写的只对一半 —— 退掉「提劫那一手」时它确实该失效，
但退到「刚提完劫」那个局面时它必须重新成立。
反方向也错：悔棋退掉一个「在别处走」的手之后，劫其实又成立，禁着点本该回来。

修法：悔棋后按新局面重算（新增 koFromBoard()），判据与 tryPlay 里那段逐条一致
（上一手提 1 子 + 落子是孤子 + 只剩一口气）—— 单一来源，避免两处规则跑偏。
因为沿用了「孤子」那条判据，上次修好的倒扑误判不会回退（已回归验证）。

验证（用那份棋谱逐手重下 32 手走到「白提完劫」）：

步骤	结果
提劫后生成禁着点	R17 ✓
立刻回提	被拒 ✓
走别处后禁着点清空	✓
悔棋回到提劫那一刻	禁着点重新成立 = R17 ✓
此时直接回提（报的那一手）	被拒 ✓
别处仍可正常落子	✓（没把局面锁死）

二、分析链路两处「卡住不会自愈」的隐患

用户报「AI 落子后马上悔棋，选点/形势有时卡住不显示，有时候会有时候不会」。
我按那个时序做了压力测试（60 轮、悔棋延迟随机 0~400ms、含 AI 思考中悔棋），
测试环境里 0 轮卡住，但翻代码找到了两个真实的机制漏洞：

1. shownAt 悔棋后没有跟着退。它是「屏幕上这批结果算的是第几手」，
   悔棋把局面变短之后如果它还指着一个已不存在的手数，
   runAnalysis 的判据 shownAt !== cur 就变成永远为假 ——
   它以为当前局面已算过，于是永远不再重算：候选点 / 胜率 / 形势雾停在旧值。
   原来只退了 candAt / ownAt，漏了 shownAt（它是模块级变量，不在 state 上，
   所以前几次审查都没扫到）。
2. 被 cancel 的那条路没有重排。分析请求被掐掉（比如数子时 runScore 会 cancel）
   返回 false 之后，anaBusy 放开了，但「重算当前局面」这个意图没人再触发 ——
   如果这一刻正好没有落子/回看，分析就停在那儿不动了。现在会主动重排一次。

另外给 Ctrl+Shift+D 自检加了一组分析链路计数（启动轮数 / 成功次数 / 空跑次数 /
提前 return 的原因），下次再遇到卡住，按一下就能看出它卡在哪一步。

三、顺带：测试跑在「活目录」上，动到了用户的棋谱

做这些测试时发现用户那份 20261007-155056-34手.sgf 从他的棋谱库里消失了。
已从备份快照完整恢复（内容逐字节一致，时间戳 15:51:39 对得上），
并新增 dev\_guard_records.ps1：跑任何端到端测试之前把用户 records 整个收起来、
跑完原样放回。以后测试再也碰不到用户的棋谱库。

打劫那份棋谱也复制成了仓库内 fixture（dev\fixtures\打劫BUG-34手.sgf），
测试不再依赖用户目录。

---

v0.1.15：修「悔棋之后能无视禁着点直接提劫」+ 分析链路两处卡死隐患

一、悔棋之后能无视禁着点直接提劫（用户报的，附了他自己存的棋谱）

现象（用户报的，附了他自己存的棋谱 GN[打劫BUG]）

白提劫 → 黑被禁着 → 黑在他处走一手 → 白补上劫空 → 黑悔棋…
悔到「白提完劫」那个局面时，黑能直接提回去 —— 也就是禁着点凭空消失了。

根因

悔棋那一段里有一句：

state.koPoint = null;          // 局面变了，打劫禁着点随之失效

注释说的只对了一半：

• 退掉提劫那一手时，禁着点确实该失效 ✅
• 退到**「刚提完劫」那个局面时，禁着点必须重新成立** ❗ ← 这里丢了

于是悔棋之后禁着点永远是 null，等于把劫禁手放行了。
反方向也错：悔棋退掉一个「在别处走」的手之后，劫其实又成立了，禁着点本该回来，却也是 null。

修法

悔棋后按新局面重算禁着点，而不是清空：

state.koPoint = koFromBoard(boardAt(state.moves.length), state.moves);

koFromBoard() 的判据与 tryPlay 里那段逐条一致（单一来源，避免两处规则跑偏）：
上一手提了恰好 1 子、落下的那颗是孤子、且它只剩一口气 → 那口气就是禁着点。

为什么必须带「孤子」那条：倒扑时落子连着自己人，对方回提会一口气提走 ≥2 子、
局面并不重复，那是合法的好手 —— 这条判据是 2026-10-06 修倒扑误判时定下来的，
这次原样沿用，所以倒扑仍然不会被误判成劫（已回归验证）。

验证

用用户自己那份棋谱（records\20261007-155056-34手.sgf）逐手重下 32 手，走到「白提完劫」：

步骤	结果
① 提劫后生成禁着点	R17 ✓
② 立刻回提	被拒 ✓
③ 在别处走一手	禁着点清空 ✓
④ 悔棋回到提劫那一刻	禁着点重新成立 = R17 ✓
⑤ 此时直接回提（用户报的那一手）	被拒 ✓
⑥ 别处仍可正常落子	✓（没把局面锁死）
⑦ 再撤一手后再试回提	仍被拒 ✓

同时回归：倒扑仍合法（提走 2 子、不误判为劫）、静态三件套全绿、综合回归
（悔棋 / 回看 / 涨跌数字 / 刷新按钮 / 界面一致性）全绿。

说明

顺带查清一件事：那份棋谱里 32 手全部合法、没有任何一手违反禁着点。
棋谱第 33 手 B[R17]（黑提回）是合法的 —— 因为在那之前白还下过一手自杀手，
棋盘没变也没提子，所以不产生新劫。所以这份棋谱本身没问题，是悔棋把禁着点弄丢了。

---

v0.1.13：修「引擎版本旧了吃不下新权重」+ 仓库目录整理 + Mac/显卡指引

现象

用户反馈（转来的原话）：「训练站最新的分析权重需要更高版本的 katago，旧版引擎会直接退出」。

根因（查证过，不是猜测）

KataGo 的权重是分代际的，引擎只认自己那一代和更早的：

权重代际	需要引擎
transformer（kata1-tf3-…，训练站现在最新的一批都是这个）	v1.17.0 以上
b28 系列	v1.14.0 以上
b18c384nbt 系列	v1.13.0 以上

两条硬证据：

1. 训练站首页公告（原文）：2026-09-15 — Support for versions prior to v1.18.0 has been retired.
   （前一条 2026-08-25：transformer 权重已上传，没升到 v1.18.0+ 的请尽快升）
2. katago.exe 里自带的报错文案：

   This neural net requires a newer KataGo version. Obtain a newer KataGo at https://github.com/...
   This neural net is from an extremely old version of KataGo and is no longer supported by the engine.

版本对不上时引擎加载权重失败后直接退出，于是软件里只显示「引擎异常 / 分析失败」——
用户看不出原因，只会觉得软件坏了。

本软件的实际情况（实测）

我们打包的引擎是能用的。本机实测：

KataGo v1.18.1 + 训练站最新 transformer 权重（kata1-tf3-b11c768-s12252M-d6398M）
  → Model version 17 · Model name: kata1-tf3-… (nbt transformer, 70442025 params)
  → Loaded model ✓

所以问题不在包，在"引擎版本 ↔ 权重代际"的搭配。

修法

1. 打包的引擎升到最新：v1.18.1 → v1.18.2（官方 2026-08-30，最后一个稳定版）
2. 把引擎的原话透到界面上（这条最要紧）：main.js 现在监听引擎 stderr，
   命中「requires a newer KataGo version」这类文案就把它转写成一句能照着做的话，
   显示在棋盘中央的提示框和右侧胜率卡上 —— 而不是只说「引擎异常」。
3. 文档写清楚代际对应表：README 与帮助面板都加了「引擎版本与权重代际」一节，
   并推荐「引擎和权重都从 KataGo 的 Release 页拿，那里附带的必定配套」。

顺带：仓库根目录整理

反馈"GitHub 页面上文件太多，要拉很久才看到产品介绍"。查了一下：
根目录 67 个文件里有 51 个是我的开发脚本（_cdp_*.mjs 测试脚本等）。

现在全部搬进 dev/，根目录只剩 16 个（README、LICENSE、程序本体、renderer/、assets/…）。
同时写了 dev/README.md 说明那堆脚本怎么用，并把脚本里写死的盘符路径改成按自身位置推导。

验证

• v1.18.2 + 最新 transformer 权重：加载成功、分析输出正常（退出码 0）
• 旧权重（b11c768nbt）与 human 权重：同样正常
• 静态三件套（DOM / hidden / IPC）全部「无 ✓」
• 回归套件（悔棋 / 回看 / 涨跌数字 / 刷新按钮 / 界面一致性）全绿

说明

A 卡 / Intel 显卡的路径我没有实测（本机是 NVIDIA RTX 4070）。
README 里那张「显卡品牌 → 下哪个 KataGo」的对应表来自 KataGo 官方发布的资产清单，
但"OpenCL 版在 A 卡上到底跑多快"要用户那边验证。

---

v0.1.12：修「手数后面的涨跌数字会自己跳」+ 顶栏加「刷新」按钮

现象

一、涨跌数字会变。 下完一手，手数列表里那一手右边显示一个数字（比如「−2.4%」），
过一会儿再点回去看，变成另一个数（比如「−16.8%」）—— 原本算是亏的，再看看就不亏了。

二、引擎像是卡住了。 偶尔出现：棋盘上推荐选点不出来，棋盘上方那行「计算中… 320」
定在一个数字上不动，点悔棋、回看、落子都没反应，只能重启软件。

根因

一、同一手被算了十几遍

引擎每 0.25 秒推一次「算到一半」的中间报告，每一份都往走势数据里写一次，
而列表读的是最后一次写的值。实测（连落 6 手）：

同一手	被写了几次	各次搜索量	胜率极差
第 1 手	6 次	151 / 298 / 463 / 515 / 515 / 515	0.62%
第 4 手	4 次	152 / 312 / 471 / 514	1.63%
第 5 手	5 次	168 / 340 / 515 / 515 / 515	1.69%
第 6 手	14 次	165 / 326 / 480 / 514 / 515 …	8.06%

第 6 手那一行就是您看到的现象：27.7% → 19.7% → 32.9%，来回跳。
不是"算得太短"，是"算了十几遍、而且用最早那份粗算覆盖了收敛后的结果"。

二、分析请求有一条"回不来"的路

分析链路上每发一次请求都要等引擎回话。万一那一次等待永远不返回，
「一次只允许一个分析在跑」那道闸门就永远占着 → 整个分析停摆：
选点不刷新、胜率条冻住、那行「计算中… N」定住不动 —— 三条现象同时成立。

修法

一、涨跌数字改成「算准了才出现，出现后不再变」

• 搜索量不到「计算深度」90% 的结果，只允许填空、不许覆盖已记的数据；
• 达标的结果才允许覆盖，而且不许用更少搜索量的结果改写更多的那一份；
• 没算准的那一格显示「…」（占位），算准了才变成数字。

试过一版「新结果比旧结果搜索量高 1.25 倍就允许覆盖」——形同虚设：
中间报告的访问量是 122 → 294 → 489 → 515 逐级涨的，每一级都比上一级高 2.4 倍，
于是每一级都过了那道门，数字照跳。必须用目标值的绝对比例当门槛。

二、请求回不来的路，两头都兜住

• 渲染端加 25 秒超时：超时就放弃这一次、主动重排一次（连续 3 次仍超时才停手并提示）；
• 顶栏状态灯旁边加一个「刷新」按钮：卡住时点一下 —— ①放开卡住的分析并重排；
  ②重新查一遍引擎真实状态；③引擎真挂了就卸载再加载（等于重启引擎）。

三、顺手加固两处

• 补账队列加上限（40 条）：连点几十手之后，引擎不会再长时间忙于补很久以前的数据；
• 新增 Ctrl+Shift+D：把分析链路的内部状态打到状态栏上（自检用，排查"点不出来"）。

验证

• 涨跌数字：刚落显示「…」→ 收敛后出数字 → 之后连续采样 5~6 次**一个字...