dsh-wrongbook
DSH Tavern 的错题库：按人物卡分类记下调试中踩过的坑，下次先查本卡、再跨卡。
调一张卡踩过的坑，隔一周换一张卡会再踩一遍 —— 因为是同一类问题：同名的状态字段、同一段正则、同一个脚本钩子。这个插件把每个坑记在出问题的那张卡名下，并在调试时给出一个固定顺序：先查出问题那张卡自己的错题库，再跨卡查。
可以做什么
- 按卡分类：卡片目录里有几张卡就自动建几项，带卡名与头像。原版卡和它的
MVU版本 互相认得，能把一条结论一键复制过去。
- 固定的检索顺序：① 本卡错题库 → ② 其它错题 → ③ 跨卡查询。本卡命中永远排在前面 —— 同卡的问题复发概率最高，先看它是为了避免把已知答案重查一遍。
- 其它错题：不挂在人物卡上的问题单独一组，预置了「卡内故障」「卡片更新器」「通用 / 未归类」，也可以自己建分类。记一个谁也没听说过的分类名时会自动建一个新分类，而不是默默塞进兜底。
- Agent 能查：注册了三个工具，卡片 Agent 在调试时按同一个顺序翻 —— 和面板上看到的是同一套打分与排序。
- 备份与还原：每次写盘前自动备份，独立页面里按份数清理、删单份、还原；备份目录可以自己选。
- 插件自检：面板右上角标着版本号，点一下「检测更新」比对插件自身文件的指纹与版本。
界面
入口只有一个：设置 → 错题库。左下角侧栏不注册任何东西。
页面里四个页签：
- 人物卡错题：卡片分类列表 + 本卡错题库 + 跨卡查询。分类由卡片目录自动生成，左边每行显示头像、卡名、未解决/观察中/已修复的条数。
- 其它错题：不挂在人物卡上的问题。这一组的分类是手建的，可以新建、改名、删除；删分类时它下面的记录会迁到「通用 / 未归类」，不会跟着一起消失。记一条不存在的分类名会当场建出来，所以「某个插件出的问题」天然就能各占一格。
- 卡脚本：卡内自带的自定义脚本与机制条目。见下一节。
- 备份与还原：当前数据概览、备份目录设置、备份列表（每条带时间和条目数）、还原、删除单份、按份数清理、导入导出。
错题页顶部还有一个**「回流到 Skill」**按钮：把调出来的结论写进某个 skill 的参考资料，下次做同类事情时 Agent 会读到。见「回流到 Skill」。
回流到 Skill
错题库是病历，skill 是诊疗手册。这一栏搭的就是两者的桥：错题页顶部点**「回流到 Skill」**，把选中的条目写进某个 skill 的 references/ 下。
弹窗里填三件事：目标 skill、范围（全部 / 当前分类 / 未解决的）、目标文件（默认 references/错题库回流.md）。每条按现象 / 根因 / 修法 / 证据铺开，带上分类、范围和状态。
只增不改：按标题去重，文件里已有同名的不再写第二遍，你手工改过的内容也不会被覆盖。所以同一个目标可以反复回流，新调的坑追加在末尾。
只能写你自己的 skill。 内置 skill（card-to-mvu、debug-card 这些）在程序目录里，Tavern 更新会整份覆盖它们 —— 写了也留不住。弹窗把它们一并列出来但标成写不了，并说明原因；要往那个语境里沉淀，先在弹窗里新建一个自己的 skill（名字用小写字母、数字和连字符），它会连带建好 SKILL.md 和那份回流文件。
两条硬边界：目标文件不许跑出 skill 目录（.. 会被拦），skill 名也不许带路径。
新建 skill 时把简介写实。 description 是 Agent 判断「要不要自动加载这个 skill」的唯一依据 —— 光有名字加一句"这是个错题库"，它不知道自己该在什么时候想起来。留空时插件会给一句通用的默认值，但那只能算占位；写清场景（比如"排查 MVU 转换后的功能缺失时读一遍"）它才会在合适的时机被读到。弹窗里有这一栏。
卡脚本
作者经常随卡附带自定义脚本 —— 悬浮状态栏、地理数据加载、变量更新器、自动化流程 —— 它们不在任何通用清单里，却决定了卡能不能正常跑。DSH 又没有全局脚本槽：脚本随卡加载，换一张卡就换一套。所以排查任何一张卡之前，先看清它带了什么。
「卡脚本」页签把这件事摊开。这一页是懒加载的，切过去才扫，不拖慢打开面板：
- 每张卡一块，标题上直接标出「N 个脚本 / 特化 N / 控制器 N」，带特化内容的不用挨个点开就知道；
- 块内逐条列脚本：名字、字符数、启用还是停用、
import 指向的外链、脚本自己的 data 键。常见的几个（外置状态栏、小手机脚本、创意工坊、格式修复、辅助计算脚本）算通用，压暗显示，不跟特化脚本混在一起；
- 另外挑出两类会左右卡行为的东西：控制器条目（世界推演、副本推进那类要求模型输出特定协议的）和含
update / json_patch 的条目；
- 页面下方单独列
data/tools/ 下的脚本 —— 那些不属于任何一张卡，是从卡里导出来的、或者为卡自制待命的那批，卡出问题时就靠它们适配。
脚本的判据是从 data/tools/card-scripts/scan.mjs 搬进来的：读 data.extensions.tavern_helper.scripts，并且要先剥掉卡文件外层可能套着的那层 raw —— 少这一层，脚本数会永远是 0。
调试时的检索顺序
这是这个插件存在的理由，所以单独说。
① 本卡错题库。 同一张卡上的问题是复发概率最高的一类：还是那个状态字段、还是那段正则。先看它，是为了避免把已经调出来的结论重新调一遍。
② 其它错题。 本卡没有答案时先来这一段：归档位置可能有偏差 —— 卡的问题被记进了「其它错题」、或者插件上的坑其实是某张卡的坑 —— 而归类偏了不该让检索漏掉它。它排在跨卡之前，因为插件与工具链上的坑影响的往往不止一张卡。
③ 跨卡查询。 最后才是别的卡片。这时候「这也是个新坑」本身就是信息，而别处的相似记录开始有参考价值。
三段的范围是固定的：① 当前分类，② 「其它错题」那一组（当前就在这一组时是组内其余分类），③ 其余卡片。从哪一头进来顺序都一样。
三段共用同一套打分：标题 > 标签 > 现象 > 根因/修法 > 引用，越靠前权重越高。没给关键词时，工具输出里的 ② ③ 只印前 8 条并标出总数 —— 全库几十条铺开会把 ① 淹掉；带上关键词就是有目的地在找，那时整段列出来。
给卡片 Agent 的三个工具
工具在插件加载时注册到宿主，同时会往 system prompt 注入一段说明。只有前者不够：工具列表里多几个名字，模型不会因此去用它们 —— 真发生过一次，让 Agent 归档时它把错题写进了 materials/错题库.md，因为它只知道那儿。
注入的说明要求 Agent：
- 动手前先
wrongbook_lookup，按三段顺序看；
- 解决后用
wrongbook_record 归档，现象、根因、证据、处理、防坑都写进去；
- 库里已有同一条就
wrongbook_update 补根因或标记已修复；
- 归档完在回复里写明「已归档到错题库」＋分类名和条目标题 —— 用户靠这句话确认归档真的发生了；
- 不要再把错题写进 md 文件。
| 工具 | 用途 |
|---|
wrongbook_lookup | 按固定顺序返回三段：「① 本分类」→「② 其它错题」→「③ 跨卡查询」。参数 card（卡名、cards/xxx.json，或其它错题里的主题名）、query、status、scope、limit |
wrongbook_record | 把新发现的问题记进对应分类；card 填一个还不存在的名字会当场建出这个分类。落库到 Tavern 数据根下 |
wrongbook_update | 标记已修复、补写根因或修法 |
card 的解析是分层的：完整路径 → 文件基名 → 分类显示名完全相等 → 名字包含。模糊命中多个分类时不猜，落到「通用 / 未归类」并把候选带回来。
这条对原版卡和它的 MVU版本 同样成立 —— 它们是两个不同的分类，坑往往只出在其中一张上（调试对象通常是 MVU 版）。所以 card: "道渊" 会同时命中两张，此时：
wrongbook_lookup 照常返回三段，但在开头警告「对上了 2 个分类：…」，让你补全名字；wrongbook_record 直接拒绝，要求写全名字。
替你在两者之间挑一个，就是把结论记到不该记的地方，比让你多写几个字贵得多。面板上这两类也各有标记：原版卡标「原版」，MVU 版标「MVU」。
安装
前置条件
先装 DSH Tavern。 这个插件是它的伴生工具：人物卡、卡片工作台对话都由 Tavern 提供，插件只负责把这些坑记下来、并在调试时按顺序翻出来。
Tavern 地址：https://github.com/flizzywine/dsh-tavern
此外需要已经在用的 DSH，且有一个 profile（本说明中默认叫 tavern，Tavern 项目用的就是它）。插件是 DSH 插件，不是独立程序。
用 dsh 命令安装
dsh plugin 是 DSH 自带的插件管理命令：把参数转给 profile 目录下的 pnpm，装完之后再按已安装状态核对 dsh.profile.bundles —— 声明了 dsh.bundle 的依赖自动进入层栈。所以不必手工改 profile 的 package.json。
从 GitHub 装，不必先 clone：
dsh plugin --profile tavern add github:XGUIMAX/dsh-wrongbook
在项目目录里装本地副本（改源码立刻生效）：
cd ~/.dsh/plugins/dsh-wrongbook
dsh plugin --profile tavern add .
装完重启 DSH，设置 → 错题库 出现即装好。
在 DSH Desktop 的命令行工具里，默认 profile 就是 tavern，写 dsh plugin add . 就够了，--profile 可以省略。
卸载
dsh plugin --profile tavern remove dsh-wrongbook
重启 DSH 后入口消失。数据留在 ~/.dsh/profile-data/tavern/data/tools/wrongbook，要一并清掉就手动删该目录。
更新
GitHub 装的：
dsh plugin --profile tavern update dsh-wrongbook
本地目录装的：在项目目录里 git pull，重启 DSH。
数据与备份
单文件 JSON：~/.dsh/profile-data/tavern/data/tools/wrongbook/data.json，结构是 { version, cards, entries, config }。
每次写盘前把旧文件复制到备份目录，文件名形如 <毫秒>__<起因>__data.json，一眼能看出这份备份是哪个动作之前留下的。自动清理保留最近 60 份；面板上可以按份数手动清理，也可以删掉指定的某一份。还原之前会先把当前内容备份一次，所以还原本身也是可回退的。
备份目录可以自己选
默认在 tools/wrongbook/backups，想换盘或丢进同步盘就在备份页上点「选择文件夹」。
选择目录走的是自己的浏览弹窗，不依赖宿主的目录选择器 —— 那个能力在不在、能不能用都说不定，而「点一下什么也没发生」是最难查的一类故障。做法参照卡片更新器：host 出一个接口列一层目录，面板渲染一层。空路径列出所有驱动器（逐个探 A:\ 到 Z:\，Windows 上 Node 没有列盘的 API），所以换到别的盘也走得到；路径框也接得住粘贴进来的东西（两边带引号、正反斜杠、D: 只写盘符、相对名都认）。
保存时会先建目录、再写一个探针文件试一下，路径有问题在按下去的那一刻就报出来 —— 而不是等某次备份静默失败、回头看才发现这几天的都没落地。
切换只影响之后写入的备份：旧目录里已有的文件不搬动也不删除，所以换回去随时还能看到。选空路径则恢复默认。
清理只动自己写的文件
自定义目录很可能是你挑的一个通用备份文件夹，里面躺着别人的 JSON。保留策略是会删东西的，所以列表、清理、删除都先按文件名认人：只有 <毫秒>__<起因>__data.json 这种形状才算本插件的备份，别的一律不列、不动、也删不掉。
插件自检
面板右上角的「检测更新」比对两件事：
- 本地指纹：
package.json、lib/index.js、client.js 三个文件的 sha256，跟上次检查的记录比。手改过源码就会被标成「本地有改动」。
- 远端清单（可选）：在数据文件里配
config.remoteUrl 指向一个返回 { "version": "..." } 的地址，有配置时会去比版本号，没配置就只报本地指纹结论。
结果落在 tools/wrongbook/selfcheck.json，保留最近 20 次。
不受 DSH 更新影响
- 插件源码在
~/.dsh/plugins/dsh-wrongbook，不在程序安装目录里。
- 数据在
<Tavern dataRoot>/tools/wrongbook。
- profile 侧只做两件事：
dependencies 里一条 link:（或 GitHub 装的版本号），dsh.profile.bundles 里一条名字。
这两处为什么动不到，不是猜的。Tavern 更新 profile 清单走 bin/profile-configuration.mjs 的 mergeProfileManifest，是读-改-写加精确排除：
const userBundles = currentProfile.bundles.filter((n) => !previousManagedBundleSet.has(n))
const bundles = uniqueStrings(sourceBundles.concat(userBundles))
const dependencies = { ...currentDependencies }
for (const n of [...previousManagedDependencies, ...excludedMobileBundles]) delete dependencies[n]
for (const n of managedDependencies) dependencies[n] = sourceDependencies[n]
它只删自己上次托管的、只覆盖自己这次托管的，用户自己加的条目原样留在里面。这个插件既不在这份 managedBundles / managedDependencies 里，也不在 previousManaged* 里，所以一个分支都碰不到它。
面板上有一行实时自检（备份与还原页底部），查三件事：dependencies 里那条还在不在、dsh.profile.bundles 里那条还在不在、node_modules 的链接是否指回插件目录。全绿即正常；缺了会直接给出补回命令（dsh plugin add <插件目录>，或手工补那两处），不用去翻这份 README 猜。
性能
数据量上去以后，最常走的几步都该是一次线性扫描。verify/perf.mjs 用 300 张卡 + 8000 条记录实测（同一台机器上的数字，量级参考）：
| 动作 | 耗时 |
|---|
打开面板（GET /state） | ~31 ms |
| 带关键词检索 | ~24 ms |
| 不带关键词检索 | ~16 ms |
| 靠名字模糊匹配检索 | ~12 ms |
| 记一条新错题 | ~56 ms |
| 导入 500 条 | ~67 ms |
| 一次手动备份 | ~43 ms |
有几处曾经会随规模恶化，都改成了单遍：
- 分类计数原来按卡各扫一遍全部条目，O(卡 × 条)；现在一次遍历算完所有分类。
- 导入去重原来对每条待导入项扫一遍现有条目，O(n × m)；现在靠一张 Set。
- 导入合并原来逐条
unshift，是 O(n²)；现在一次拼好再赋值。
- 头像解析原来每张卡依次试 5 个路径（几百张卡就是上千次同步
stat）；现在两个目录各列一次建索引，之后全是查表。
- 卡片扫描不再逐个
statSync 取尺寸和时间 —— 那两样没人用，只是顺手拿的。
写入路径的开销主要在备份：每次写盘前把旧文件整份复制走，这是拿磁盘换「随时能回退」。8000 条时一次约 43 ms，换来的是任何一次误操作都能找回上一份。
常见问题
「选择文件夹」点下去什么也没发生？ 不会。它走的是插件自己的浏览弹窗，只依赖插件自己的 HTTP 路由，跟宿主提供什么能力无关。
「打开数据目录 / 打开备份目录」没反应？ 两级依次尝试，每一级的失败原因都留着，全失败时连同 PATH 一起报回面板：宿主解析器 / SystemRoot 拼出的绝对路径 → cmd /c start。成功时消息末尾会带上走通的层级（比如 · C:\WINDOWS\explorer.exe），所以这台机器上到底是哪种方式有效不用猜。
面板里为什么没有系统弹窗？ window.prompt 在 Electron 的渲染进程里没有实现，调用后直接返回 null 而且不报错 —— 用它做的「导入 JSON」「改分类名」会表现成按钮点了没反应。window.confirm 的行为在各版本之间也不一致。所以导入用面板内的文本框、改名用内联输入框、删除和还原用二次确认按钮。验收脚本里有一条静态检查，防止这两个 API 再被引进来。
卡片改名或被移走了，记在上面的错题会丢吗？ 不会。已经不在卡片目录里的分类只标成「文件已不在卡片目录」，记录保留。删分类也一样，记录会先迁到「通用 / 未归类」。
为什么有两组分类？ 分类带 group 字段：card 来自卡片目录扫描，other 是手建的。两组共用同一套列表与条目区渲染，只是换数据源。
开发
lib/index.js Host 半边：数据、卡片扫描、检索、HTTP 路由、Agent 工具
client.js 浏览器半边：设置页的三个页签与目录浏览弹窗
verify/ 两套验收脚本
验收
node verify/host.mjs # 193 项：扫描、分组、归类、卡名解析、三段检索、卡内脚本、安装自检、skill 回流、路由、工具、备份
node verify/client.mjs # 84 项：注册接线、字典一致性、四个页签与两个弹窗、三段渲染、禁用 API 静态检查
node verify/perf.mjs # 7 项预算：300 张卡 + 8000 条记录下量一遍最常走的几条路
verify/host.mjs 在系统临时目录里现造一个沙盒数据根，不碰真实数据；verify/client.mjs 用最小 React 运行时渲染面板，不发网络请求。
套件不打开任何外部程序。 曾经有一条实跑 openBackupDir 的用例，已经删掉：它会真的弹出一个资源管理器窗口，而窗口指向的目录一旦在事后被删（沙盒会），资源管理器就弹「位置不可用」——比不测还烦。「打开目录」是人工验证项：重启后在面板上点一下，看窗口落到哪儿、via 是哪一级回退。
发版
改 package.json 的 version，打同名 tag：
git tag v1.0.1 && git push origin main --tags
面板右上角的版本号读的就是 package.json。
许可
MIT
