dsh-go-sensei

LIMITATIONS

Known limitations

- **自带引擎只在 Windows x64 上自动启用**（OpenCL 后端）；其他平台请自备引擎并配置 `engineDir`。 - **权重与路径每次调用实时解析**（丢个新 `*.bin.gz` 进 `engine/` 下次补算即用），但 `go_engine_analyze` 工具是否注册在插件加载期决定——改了 `engineDir` / `kataGoPath` 要重启 `dsh web` 才会出现。 - **仓库体积约 110 MB**（引擎 + 18b 权重）：clone 会慢一些，GitHub 也会对单文件 >50 MB 给出提示；不需要可删掉 `engine/`。 - **补算只支持 19 路**；让子棋支持 2~9 子，更多子数会明确报错。 - **补算规则按棋谱的 `RU[]` 判断**：含 `japan` 用日本规则，其余一律中国规则；贴目取自 `KM[]`，会吸附到 0.5 的整数倍并夹在 `[-150, 150]`。 - **胜率视角取决于引擎配置**：插件读 `kataGoConfig` 里的 `reportAnalysisWinratesAs` 做换算（读不到时按 KataGo 默认＝行棋方视角）。改了引擎配置，同一盘棋的胜率数字会变，属预期。 - **写回依赖沙箱策略服务（fail-closed）**：DSH 沙箱后端下，写入会带上调用会话的策略；**拿不到该服务时写入被直接拒绝**，而不是降级成"无策略写入"（那等于绕过工作区限制）。读取不由该策略约束，只读工具照常工作。 - **报告骨架靠整行匹配**区分「引擎分析行」与「人写的讲解」；若某种导出器的分析行格式很特殊，可能被当成讲解收进报告——导出后扫一眼即可。 - **题目型棋谱**（只有摆子、没有实战手顺）没有可复盘的手数，但**棋盘能把摆子画出来**（读根节点的 `AB`/`AW`）；`AE[]`（清除摆子）与 `PL[]`（指定行棋方）不参与画盘。 - **棋盘只画主变化线**（与复盘口径一致，旁支不算手数）；盘上的 AI 标注给的是**首选点 + 它这条变化的前几手**（最多 5 手带序号，更长的看工具返回的文字），第二、第三候选只出现在右侧/下方的列表说明里、不画到盘上。变化图若落在实战已占的点上（那条变化与当前局面无关），盘上就不画那一手（序号照原样，不重排）。变化棋的黑白只按轮转推算，不重放提子：一条四五手的变化里互相提子的情形罕见，真遇上也就是多画一颗子。 - **「跟随讲解」按会话分桶**：宿主为每个会话单独记一条指针，`/go-sensei/focus?session=…` 只返回本会话那条；最近一次 `go_*` 调用（读谱 / 找问题手 / 取局面 / 写回注释）决定**本会话**的指针指向哪一盘、第几手。多会话并存时互不串台；不带 `session` 参数的请求（旧客户端、整页视图拿不到会话 id 时）仍退回"最近一次"。任何情况下都**只在有新事件时**才换掉你手动选的棋谱；不想被切就关掉面板上的「跟随讲解」。 - **棋谱解析的三道上限**：单个 SGF 文本 8 MB（读盘时就按此上限拒绝，不会整份读进内存再判）、节点数 20 万、嵌套深度 512 层，均在进入解析器**之前**判定 —— 畸形或拼接的超大棋谱会被明确拒绝，而不是先把整棵语法树材质化再慢慢超时（深度单独限，是因为解析器是递归下降，嵌套太深会先爆调用栈而不是给出可读的拒绝；属性值内部的 `;`/`(` 不算结构字符）。棋盘路数（`SZ`）钳在 2~52 路，盘外坐标直接忽略。 - **改完 `client.js`（浏览器 half）通常不用重启**：宿主会侦测到产物变化并热重载这个插件行——实测改完几秒内面板就换了新代码。若没生效，刷新页面；仍不行再重启 `dsh web`。**改 `index.mjs` / `src/*.js`（宿主 half）必须重启** `dsh web`，否则工具与路由还是旧代码。 - **配图需要 Web 面板**：`go_draw_diagram` 的图片由 `/go-sensei/diagram` 路由提供，纯 CLI 组合（没有 `webServer`）下它会明确报错、不编造 URL。图是 SVG，聊天区按 `<img>` 显示；用不支持 SVG 的客户端看会退化成 alt 文字。 - **曲线只反映棋谱里已有的分析数据**：没有分析数据的棋谱要等补算完（补算过后写回的 `WV[]`/`DM[]` 就是曲线的数据源）；某一手取不到数据时曲线在那里断开，不连线、不猜。 - **形势判断要引擎，且以引擎为准**：判定用的是 KataGo 的归属图（`ownership`），所以它随引擎强弱变化；引擎不可用时按钮禁用、配图不出图——**没有"无引擎估算"这条退路**（早期版本的启发式估算已撤掉）。另外浮窗里的目数是**点目**，与目差曲线（`DM[]`）不是同一个数，两套数字不要混着讲。归属图按每点 2 bit 存进副本的 `TP[]`，19 路约 124 字符/手（300 手约 36 KB）。