Skip to content

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

Choose a tag to compare

View all tags
@Rapace7 Rapace7 released this 14 Oct 15:06
· 14 commits to main since this release
v0.1.28
9a87d44

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 下棋和数据分析）

② 讲解模型（可选，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
Assets 5
Loading