dsh-tiddlywiki 0.28.9 → 0.28.11

package/README.md

@@ -63,26 +63,7 @@ dsh plugin --profile web add dsh-tiddlywiki
 | 发布到微信公众号（可选，需额外安装） | [docs/wechat-publish-setup.md](docs/wechat-publish-setup.md) |
 | 把知识库拆成几个独立的小库（含可复制给 Agent 的提示词） | [docs/wiki-split.md](docs/wiki-split.md) |
 | 开发与发布流程（给维护者） | [docs/development.md](docs/development.md) |
-| 完整版本变更历史 | [docs/CHANGELOG.md](docs/CHANGELOG.md) |
-
-## 🕘 版本记录
-
-- **v0.28.9**（2026-09-28）：**修「点击图标没有正常弹出」**（作者重启后实测报障）。根因：v0.28.8 的图标弹层只写了 DOM 与接线，**`styles.ts` 里一条 CSS 都没有** —— 弹层照样被 append 到 `document.body`，但它是个无宽高约束的裸块、压在页面底部，视觉上就是「点了没反应」。现在补齐 `.dsh-tw-iconpicker`（含 `position:fixed`——它挂在 body 上，用 absolute 会被页面滚动带走）、8 列网格、格子（含当前项高亮）、分页器与按钮图标位共 12 条规则。**守门一并补强**：`verify-wiki-focus.mjs` 原先只断言「TS 源码里出现过 `dsh-tw-iconpicker` 这个字符串」—— 而 class 名当然会出现在 TS 里（它是 `make()` 的参数），所以组件没样式也照样绿。现在改为**双向**断言：弹层/网格/格子/分页器必须真有 CSS 规则，且 **picker 里 `make()` 出来的每个 `dsh-tw-*` 类都必须在 `styles.ts` 里有下落**（下次再加子元素忘写 CSS 会当场变红）。新断言已反向验证（删掉那段 CSS → 红）。顺带被这条新守门抓出第二处漏写：按钮文字位 `.dsh-tw-settings-iconbtn-label` 也没样式。教训：**断言「某个类名存在」不等于断言「这个组件可用」** —— 渲染型组件的守门至少要跨两个文件，一个说"我生成了这个 DOM"，一个说"这个 DOM 有样式"。
-- **v0.28.8**（2026-09-28）：**多库第五批反馈：图标真能用了、设置页分页了、新会话也能选库了 + 拆大文件**（12 条反馈一次做完）。① **图标选择器用上 DSH 官方图标系统** —— 从 8 个手绘图标扩到 **36 个官方图标**（内联的是上游 path 数据：客户端是纯 DOM、零运行时依赖）+ 8 个自绘 + 一组 emoji，弹出网格 **48 个一页**分页。② **修「选了图标立刻变回默认」** —— 根因在 `/admin/wikis` 的**读取视图漏了 `icon` 字段**：写进去了、读回来是 `undefined`，客户端拿它重渲染就回落默认，看起来完全像"没保存"。补上该字段，并加**源码级守门**钉死它（去掉修复即红）。③ **多库下设置页分页**：十几块面板挤一页既分不清"改这个库"还是"改整个插件"、改完也没有退出口 —— 现在分「**总览 / 本库配置 / 全局**」三个 tab，「插件管理 / 主题管理 / 语言管理 / 初始化」这些 per-库面板**只在点了某个库的「配置」之后**才出现，按钮变成「**退出配置**」；单库安装没有 tab 条，逐字不变。④ **新会话也能选知识库**：选择器此前只长在输入框上方（新会话还没有输入框），现在挂在预设/模式选择旁边 —— 声明感知注入 + 2 秒回落 + `blankOnly`，两种布局不会同时出现两个。⑤ **剪藏可指定落哪个库**（`bridge.wiki`，设置页下拉，留空 = 默认库）。⑥ **回复流卡片、会话「知识库」Tab 按会话作用域取数**：不这样做会出现"A 库的标题在 B 库里渲染成空白卡片"。⑦ **桌面版能起 TW 了**：`process.execPath` 在桌面版里是 Electron，TW 根本起不来 —— 现在按 `DSH_TIDDLYWIKI_NODE` → `where/which node` → `execPath` 解析并缓存，行为级守门进 `verify:unit`。⑧ **代码清理**：`tools.ts` 1913→132、`admin.ts` 1265→24、`index.ts` 1407→1001、`note-widget.ts` 1245→916、`settings-page.ts` 1815→400（全部**纯搬移**，注册顺序与装配顺序逐字保持），并新增 `scripts/lib/source-family.mjs` 让 12 个守门按「模块族」读源码 —— 以后纯搬迁不会再假红。⑨ **复核确认无需改动的两条**：注入提示词本来就是**按会话求值**的（换库后下一步即生效，且读的是那个库自己的 `prompt.*`），15 个工具在多库下全部正常（回执在可见库 >1 时标明库名）。全链路复跑：`typecheck` / `verify:static` / `verify:unit` / `verify:e2e` / `verify:large` 全绿（含真起两个 TW 子进程、3100 条大库 64s）。
-① **图标选择器用上 DSH 官方图标系统** —— 从 8 个手绘图标扩到 **36 个官方图标**（内联的是上游 path 数据：客户端是纯 DOM、零运行时依赖）+ 8 个自绘 + 一组 emoji，弹出网格 **48 个一页**分页。② **修「选了图标立刻变回默认」** —— 根因在 `/admin/wikis` 的**读取视图漏了 `icon` 字段**：写进去了、读回来是 `undefined`，客户端拿它重渲染就回落默认，看起来完全像"没保存"。补上该字段，并加**源码级守门**钉死它（去掉修复即红）。③ **多库下设置页分页**：十几块面板挤一页既分不清"改这个库"还是"改整个插件"、改完也没有退出口 —— 现在分「**总览 / 本库配置 / 全局**」三个 tab，「插件管理 / 主题管理 / 语言管理 / 初始化」这些 per-库面板**只在点了某个库的「配置」之后**才出现，按钮变成「**退出配置**」；单库安装没有 tab 条，逐字不变。④ **新会话也能选知识库**：选择器此前只长在输入框上方（新会话还没有输入框），现在挂在预设/模式选择旁边 —— 声明感知注入 + 2 秒回落 + `blankOnly`，两种布局不会同时出现两个。⑤ **剪藏可指定落哪个库**（`bridge.wiki`，设置页下拉，留空 = 默认库）。⑥ **回复流卡片、会话「知识库」Tab 按会话作用域取数**：不这样做会出现"A 库的标题在 B 库里渲染成空白卡片"。⑦ **桌面版能起 TW 了**：`process.execPath` 在桌面版里是 Electron，TW 根本起不来 —— 现在按 `DSH_TIDDLYWIKI_NODE` → `where/which node` → `execPath` 解析并缓存，行为级守门进 `verify:unit`。⑧ **代码清理**：`tools.ts` 1913→132、`admin.ts` 1265→24、`index.ts` 1407→1001、`note-widget.ts` 1245→916、`settings-page.ts` 1815→400（全部**纯搬移**，注册顺序与装配顺序逐字保持），并新增 `scripts/lib/source-family.mjs` 让 12 个守门按「模块族」读源码 —— 以后纯搬迁不会再假红。⑨ **复核确认无需改动的两条**：注入提示词本来就是**按会话求值**的（换库后下一步即生效，且读的是那个库自己的 `prompt.*`），15 个工具在多库下全部正常（回执在可见库 >1 时标明库名）。全链路复跑：`typecheck` / `verify:static` / `verify:unit` / `verify:e2e` / `verify:large` 全绿（含真起两个 TW 子进程、3100 条大库 64s）。
-- **v0.28.7**（2026-09-28）：**会话知识库选择器改成与「快速笔记」同一行 + 单库专属配置项不再在多库下出现**（两条都是作者报障）。① **选择器"没和对话框对齐"** —— 上次的修法方向就错了：`conversation.input.dock` 是**竖向 flex 列，一个条目独占一整行**，选择器和快速笔记是**两个条目**时永远是上下两行，怎么调内边距都不可能并排。现在选择器不再是独立条目，而是由快速笔记条目通过 `scope` 参数渲染在**自己这一行里**（按钮前面），整行统一与输入框右缘对齐，一行只测一次。顺手修掉合并时的一处遗留：选择器组件里还留着上一版的 `alignDockEntry` 自测，并入同一行后会把右内边距补两遍——已移除（`wiki-scope` 也从客户端 slot 表里消失，回归由 `verify-wiki-focus.mjs` 断言"input.dock 只能有一个条目"守住）。② **「侧边栏 TW 入口显示名称」在多库下不该出现** —— 多库时侧边栏是每个库各占一行、各用自己 `wikis.json` 里的显示名，`ui.sidebarLabel` 只喂单库那一行，所以多库下它是个**改了不生效的假配置项**。现在该字段只在单库模式渲染（多库时换成一行说明"去知识库列表改各自的显示名"）；模式探测失败**回落成单库**（保守：宁可多给一个真能用的字段，也不要因为一次请求失败把设置项藏了），并反向断言不许写成 `!== 'single'`（那会把未知模式误判成多库）。两条守门断言都做了反向验证。
-- **v0.28.6**（2026-09-28）：**修两个多库界面的真机报障**。① **「插件管理 / 主题管理 / 语言包 / 初始化」看起来是混在一起管理的** —— 宿主侧一直是 per-request 解析目标库的（`deps.server(req)`/`config(req)`/`getClient(req)`），缺的是**客户端那一半**：设置页只有 `state`/`config`/`prompt` 三处带上了 `?wiki=`，而**插件信息与初始化 seed 的调用没带**，于是它们永远落在默认库上，「切了库、面板内容却没变」。现在 7 个 per-wiki 端点全部经 `withWiki()`，并有守门逐个断言（去掉任一处的作用域 → 红）。单库（未选库）时 `withWiki` 原样返回 URL，现有用户逐字不变。② **左侧入口点一个却三个都高亮** —— 我上一版把「面板是共享的」错解成「所有行一起高亮」，但面板一次只显示一个库（当前焦点库）。现在只有那一行点亮，并订阅焦点变化重算；单库默认行在面板打开时仍正常高亮。两条守门断言都做了反向验证。
-- **v0.28.5**（2026-09-28）：**修「多库模式下侧边栏多出一个没有库名的 `TiddlyWiki` 入口」**（作者报障）。根因是**同一个 CSS 陷阱踩了第 12 次**：`hidden` 属性在 CSS 里只是 `display:none`，而 `.dsh-tw-entry` 有显式 `display:flex` —— **显式 display 盖掉了 hidden**，于是那行让位给每库入口的默认行照样渲染。这次不再给它单独补一条规则，而是**收敃成一条全局兜底** `[hidden] { display: none !important; }`，并删掉本仓库历史上为此在不同元素上各补的 **12 条逐元素规则**（面板 iframe / 错误块 / 快速笔记 / FAB 菜单与提示 / 右侧栏 / 目标库下拉 / 草稿栏 / 最近列表…）。守门同时改为断言「全局兜底存在 + 不允许再出现逐元素版本」，并反向验证（把全局规则改成挂在类名下 → 红）。
-- **v0.28.4**（2026-09-28）：**每库自定义图标 + 修「右键菜单切库后选中项不更新」**。① **右侧「知识库」菜单的选中项停在旧值** —— 根因是选中标记（`●`/`○`）只在**菜单构建时**算了一次，之后无论怎么切都不重画；现在改为从当前焦点重算，并在 `setFocusWiki` 订阅里即时重画、每次打开菜单前再兜一次（切库也可能来自侧边栏入口或快速笔记卡片）。② **每个库的入口图标可自定义**：`wikis.json` 的条目新增可选 `icon` 字段，值可以是内置图形名（book / briefcase / home / notebook / flask / globe / star / archive，各是一枚继承 `currentColor` 的手写 16×16 线性 SVG，两套主题下都对）或**一个短 emoji**（📚 / 💼 / 🏠 …，用来一眼区分四五个库，不用下载任何资源）。设置页「知识库列表」每行多了图标下拉（当前值若不在候选里会保留，不会被抹掉）。校验口径：名字或 ≤8 字符的可打印短串，超长与控制字符一律拒绝；空值 = 清除自定义回落默认。**emoji 用 `textContent` 渲染而不是 `innerHTML`** —— 这个值来自用户可编辑的文件，绝不能变成注入点。缺省不设 = 内置默认图标，升级用户看到的一模一样。
-- **v0.28.3**（2026-09-28）：**修三个真机报障 + 插件说明补「多库 / 升级」两节**（作者拆库实测中发现）。① 单库模式下快速笔记露出一个没有选项的下拉 —— 根因是 **CSS `hidden` 只是 `display:none`，被显式 `display` 盖掉**（修法：显式 `[hidden]{display:none}` + 组件兜底）。② 会话级选择器没和输入框对齐 —— **对齐规则原本只写在 quick-note 条目内部**，已抽成 `client/dock-align.ts` 两处共用。③ 左侧入口按库显示：多库时每个在运行的库一个入口行、用各自显示名，点该行先切焦点库再开面板。④ 插件说明新增「多知识库」与「从旧版本升级上来」两节：明确升级后**不会自动变成多库**、`wikis.json` 在哪、旧指针文件何时还权威。守门扩到 19 条（含反向验证）。
-- **v0.28.2**（2026-09-28）：**设置页去掉重复的「知识库位置」**（作者反馈：多库配置做完后它重复且逻辑冲突）。这一块的语义是「把**唯一的那个库**换到别处」——写的是 wiki 之外的指针文件 `location.json`，措辞也是单库时代的（"切换到这个位置" / "恢复为配置默认"）。现在**按模式二选一**：**单库模式**保留它（那里它是唯一正确入口）；**多库模式整块不渲染**，某个库换目录收到「知识库列表」那一行的**「改目录」**（默认库经 `/admin/wiki/switch` → 改清单 + farm 收敛 + 校验；非默认库直接 `update`）。宿主接口**没有**冲突也**没有**改动：`/admin/wiki/switch|reset` 从 v0.28.0 起就按模式分派。守门：`verify-wiki-focus` 新增"多库模式下不得渲染该块"的断言；farm-boot 补上 location 面接线（22 条），保证藏了界面之后**接口仍按模式正确分派**。
-- **v0.28.1**（2026-09-28）：**修「拆库 skill 在 wiki 启动慢 / 起不来时永远装不上」+ 快速笔记的目标库可切换（R7）**。① **真实事故**（作者升级 0.28.0 后重启宿主时发现，测试没拦住）：技能安装写在了 `farm.startAll()` **之后**，而那个 wiki 很大、启动要几十秒 —— 于是"技能装没装"取决于"wiki 起得快不快"；更糟的是 wiki 若因配置问题**永远起不来**，技能就永远不装，而它跟 wiki 毫无关系（只往 `$DSH_HOME/skills/` 写一个文件）。已挪到启动任务**最前面**并新增**顺序守门**（`verify-skill-install` 断言安装早于 `startAll()`，已反向验证）。② 快速笔记卡片新增「写入」目标库：**默认跟随你在 GUI 里看的那个库**（焦点库），卡片内可临时改、改过后不再被焦点带走。要点是**整张卡片一起换库**：标签建议 / 最近 / 草稿读取 / 附件上传 / 保存 / 随后弹出的 TW 编辑器必须落在同一个库 —— 只改保存那一处会产出"标签列表来自 A、笔记写进 B"，比不做还糟（弹窗那条另有一条守门：写入 A、编辑器打开 B（空白）是典型的"看起来成功了"的失败）。目标库没在运行时卡片**先讲清楚**，而不是让你写完一段再失败。单库安装不显示选择器、请求 URL 逐字不变。
-- **v0.28.0**（2026-09-28）：**多知识库**——同一进程内可同时运行多个 TiddlyWiki，每个库独立配置、独立 git、按会话选择作用域，且可对 Agent **彻底隐身**。起因是作者自己的库：`书籍` 语料 2468 条与日常笔记挤在一个 800MB 仓库里，Agent 检索/lint/backlink 每天在约 30 倍于工作集的内容上跑。拆库需要**同时在线**——只切换位置的话，你切到语料库翻资料时 Agent 也跟着切过去了。要点：① 三个模块各司其职（`wiki-registry` 清单/模式/动作、`wiki-instance` 单库运行时、`wiki-farm` 谁该在跑 + 会话作用域）；② 模式开关 `wikis.json` 的 `mode`（缺省 `single`，升级用户逐字不变）；③ 路由按库定向 `/tw/<id>/…`（每个库 seed 自己的同源基址——不区分 id 就会「页面显示 A、读写落在 B」），裸 `/tw/` 仍是默认库别名，为此引入**保留 id 名单**；④ **git 按仓库重构**：多库可共用一个仓库，`git add -A` 只允许一个 committer，pull 后只重启受影响的库；⑤ Agent 侧：会话单选作用域 + `agentVisible`，工具回执在可见库多于一个时**标明库名**，注入提示词**按会话求值**并读作用域库的 `prompt.*`；两条刻意拒绝（隐身库→忽略；没在跑→报错而非静默换库）；⑥ GUI：输入框上方的会话选择器、FAB 的知识库分组、设置页「知识库列表」与**显式配置作用域**；⑦ **拆库引导** `docs/wiki-split.md` + 随包 skill（安装时只覆盖带标记的文件）。新增 6 个守门脚本（共约 96 条断言，含**真起两个 TW 子进程**与**真 git 仓库**两类集成验证），全部反向验证；4 个既有守门跟着间接层更新。**未做**：per-wiki 认证（`auth.*` 仍全局）、快速笔记目标切换策略。
-- **v0.27.3**（2026-09-28）：**修 v0.27.1 拆文档时打断的 6 个相对链接**（`docs/` 内的链接仍按仓库根写成 `docs/xxx.md`，从 `docs/` 内部点击打不开）；新增守门 `scripts/verify-doc-links.mjs`（校验 README + `docs/**` 的全部相对链接，已挂进 `verify:static`，让这类错误下次发不出来）；**修 CI 偶发假红**：`verify-wiki-switch` 的回滚断言会抢在 TW 载入 store 之前读取，改为 15s 有界轮询后再断言。**无运行时行为改动。**
-- **v0.27.2**（2026-09-28）：修本页一处**指向不存在内容的死链**（"不适合"那段曾让人去看 `docs/features.md` 末尾的说明，那里并没有）。纯文案，无代码改动。
-- **v0.27.1**（2026-09-28）：**README 从 175KB 精简成本页**——原来 68% 的篇幅是变更历史。能力清单 / 使用指南 / 开发发布 / 完整变更历史拆到 `docs/`（内容未删），首页只留"是什么、怎么装、好在哪、适不适合你"。**无代码改动。**
-
-更早版本 → [docs/CHANGELOG.md](docs/CHANGELOG.md)
+| 版本变更历史（逐版本、含"为什么"；**README 不再重复它**） | [docs/CHANGELOG.md](docs/CHANGELOG.md) |
 
 ## 🔗 仓库与发布元数据
 

package/docs/CHANGELOG.md

@@ -1,9 +1,12 @@
 # 版本记录
 
-> 逐版本变更。README 只保留最新一条，完整历史在这里。
+> 逐版本变更。**版本历史的唯一所在地**——README 只放"是什么、怎么装、好在哪"，不再重复这里（2026-09-29 起，此前 README 抄了最近 18 条，每次发布都要改两处）。
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.28.11**（2026-09-29）：**修两个多库界面的真机报障（卡片链接开错库、新会话两个选择器）+ README 不再放版本记录**（三条都是作者当天报的）。① **点卡片上的「在 TW 打开」跳到最后打开的那个库** —— 卡片把会话作用域（`wikiId`）塞进了 `openTiddler` 的事件 detail，但 `panel.ts` 的事件处理**只读了 title**；而面板与右栏都按 GUI 的**焦点库**加载 `/tw/<id>/`，链接的库被整个丢掉（`undefined` 当时还同时表示"默认库"和"未指定"，根本区分不开）。现在 `TwWikiTarget` 把三者分开（`string` = 该库 / `null` = 明确默认库 / `undefined` = 未指定、跟随焦点库）：卡片与列表行传 `null` 而不是省略；`panel.ts` 拿到 `wiki` 先 `setFocusWiki()` 再路由（两个 TW 界面都按焦点库加载），并把目标库透传给右栏 tab 与中央面板。内核补齐**换库时序**：`wikiSwitchPending` 期间不落 hash —— 否则 hash 会写进正在被替换的旧文档，随后整页重载把它连同 `pendingHash` 一起吞掉（表现为"停在库首页、笔记没打开"）。全局链接拦截面同样不再把裸 `/tw/#标题` 一律当默认库：链接自带 `/tw/<id>/` 就用它，裸路径取**所在卡片 / 会话汇总面板**的 `data-dsh-tw-wiki`（工具卡与会话「知识库」Tab 的根节点新增该属性），两者都没有才跟随焦点库。② **新会话出现两个知识库选择器**（其中一个与快速笔记同一行）—— 根因是 v0.28.8 给 `conversation.input.selector.context` 配的**「2 秒没等到就回落到 dock」**：回落会往 `conversation.input.dock` **再注册一个 blank-only 条目**，而 dock 里本来就有同一个选择器（v0.28.7 起由快速笔记条目的 `scope` 参数渲染在同一行）——本机 shell 恰好不声明 `selector.context`（`app.asar` 里连这个字符串都没有），于是回落成了常态、两个选择器同时渲染。现在**删掉回落**（dock 里那个才是唯一常驻的家），并把"谁在用"做成显式协议：`scope-seat.ts` 用 `isBlankSeatMounted()` 公布 context 那一格是否已挂上，dock 里的选择器在**空白会话 + 那一格在挂着**时返回 null 让位（`useSessions` 随之从快速笔记条目透传给子组件，否则子组件认不出空白会话、让位不了）。③ **README 不再放版本记录**（作者要求：只放最新最重要的信息，版本历史单独一个文档）—— 删掉 README 那一节（内容本来就是 `docs/CHANGELOG.md` 的副本），版本一致性的第三个锚点从 README 改到 `docs/CHANGELOG.md` 顶部第一条，并**反向断言 README 里不得再出现逐版本条目**（防止它随每次发布慢慢长回去）。守门：`verify-frame-surface.mjs` 新增换库时序行为单测（旧文档不得收到 hash、新文档必须收到）；`verify-wiki-focus.mjs` 重写选择器座位那条（不许再回落注册 dock 条目、必须有 blankSeat 让位协议）并新增「卡片链接必须带库」的源码级断言；`verify-version-consistency.mjs` 改锚点 + 新增 README 反向断言。单库安装行为逐字不变。
+
+- **v0.28.10**（2026-09-28）：**修「图标弹层出现在设置弹窗后面、被遮挡」**（作者 v0.28.9 重启后实测报障）。① **根因是层级用错了数**：设置页是 DSH 的 `Modal`，渲染进 portal 且根层就是 `position:fixed; z-index:1000`（`dsh-client-ui-primitives/Modal.module.css` 的 `.root`），而弹层写的是 `z-index:60`。**`z-index` 只在同一个层叠上下文里比较** —— 弹层虽然是 `document.body` 的直接子节点（自己也在根上下文），但 60 < 1000，所以整层被 Modal 盖住：弹是弹了，在设置弹窗**后面**。② **修法**：改为 **1100**。这不是随手挑的"大一点的数"，而是 DSH 自己给「锚点在对话框内部的浮层」定的值 —— `Menu.module.css` 的 `.portal`，注释原话：*"Portaled lists must layer above modal overlays (z 1000) — an anchor inside a dialog still expects its menu on top"*。跟它对齐即高于 Modal(1000)、低于我们自己的 toast(10001)。③ **守门**：断言弹层 `z-index ≥ 1100`，并**解析规则体时先剥掉注释**（第一版按字符往后切 400 字符，结果切到了我新写的注释里那句「DSH Modal 的 1000」，解析出 1000 而误报）。已反向验证：改回 `z-index:60` → 红；恢复 1100 → 绿。④ **顺带补 `styles.ts` 模板串守门**：CSS 正文里的反引号会让 `CSS_TEXT` 提前结束，`typecheck` 报 TS1005、而 `lib/` 已被 `clean-lib` 删掉（构建到一半失败）。本仓库踩过两次（v0.25.0 注释里引 `.dsh-tw-settings`；v0.28.9 我在解释 z-index 时又写了一次）。⑤ **这条守门的第一版是错的，值得单独记**：它检查「第一个闭引号之前有没有反引号」—— 可一旦正文多了一个反引号，**那个反引号本身就变成了"闭引号"的位置**，body 在它之前就结束了，于是"body 里没有反引号"**永远成立**：注入反引号反而让断言更容易通过。**用出错的输入去验证出错的解析器，必然假绿。** 改成检查「模板串有没有被提前截断」——正文须以 CSS 注释开头、以 `}` 结尾，且闭引号之后必须紧跟正常模块代码（`/**` / `import` / `const` …）。再注入反引号即稳定变红。⑥ 复核：`typecheck` / `build`（`client.bundle.js` 704856 字节，并确认 `z-index:1100` 进了 bundle）/ `verify:static` / `verify:unit` / `verify:e2e` / `verify:large` 全绿。
 - **v0.28.9**（2026-09-28）：**修「点击图标没有正常弹出」**（作者重启后实测报障）。本版只有一个修复，但值得单独发一版：它暴露的是**守门的失效模式**，不是普通的漏写。① **现象**：设置页知识库列表里点「图标」，弹层没有出现。② **根因**：v0.28.8 的 `settings-icon-picker.ts` 生成了完整 DOM（弹层 / 网格 / 格子 / 分页器）、接线也对，**但 `styles.ts` 里一条 CSS 都没有** —— 弹层照样被 append 到 `document.body`，而它是个无宽高约束的裸块、压在页面最底部，视觉上就等于「点了没反应」。③ **修复**：补齐 12 条规则 —— `.dsh-tw-iconpicker`（含 `position:fixed`：弹层挂在 body 上，用 absolute 会被页面滚动带走、也受祖先 overflow 影响）、`min(420px, 100vw-24px)` 宽度与 `max-height` 上限、8 列网格、格子悬停与当前项高亮、名称省略（8 列必须对齐）、分页器分隔线，以及按钮的图标位与文字位。④ **守门为什么没拦住（本版最重要的部分）**：`verify-wiki-focus.mjs` 原本断言的是 `assert.match(settings, /dsh-tw-iconpicker/)` —— 检查「TS 源码里出现过这个字符串」。但**类名当然会出现在 TS 里**（它是 `make('div', 'dsh-tw-iconpicker')` 的参数），所以组件一条 CSS 都没有时这条断言照样绿。**通用教训：断言「某个类名存在」不等于断言「这个组件可用」。** 渲染型组件的守门至少要跨两个文件——一个说「我生成了这个 DOM」，一个说「这个 DOM 有样式」。⑤ **新守门（双向）**：弹层 / 网格 / 格子 / 分页器四个类必须真有 CSS 规则；并且从 picker 源码里**解析出所有 `make()` 生成的 `dsh-tw-*` 类名**，逐个要求它们在 `styles.ts` 里有下落 —— 这条通用网能拦住「下次再加子元素、又忘了写 CSS」。**已反向验证**：删掉那段 CSS → 红；恢复 → 绿。⑥ **新守门当场抓出第二处漏写**：按钮的文字位 `.dsh-tw-settings-iconbtn-label` 同样没有样式。⑦ 复核：`typecheck` / `build`（`client.bundle.js` 701305 → **704155 字节**，并确认 CSS 真进了 bundle）/ `verify:static` / `verify:unit` / `verify:e2e` / `verify:large` 全绿。
 - **v0.28.8**（2026-09-28）：**多库第五批反馈（12 条一次做完）+ 拆大文件**。① **图标选择器接上 DSH 官方图标系统**（反馈 1）—— 从 8 个手绘图标扩到 **36 个官方图标**：没有 `require` 上游的 React 图标组件（客户端是纯 DOM，那样会引入运行时依赖、还会让改名对不上），而是把**上游的 path 数据内联**进 `src/client/wiki-icon.generated.ts`（由 `scripts/gen-wiki-icons.mjs` 生成，`scripts/extract-dsh-icons.mjs` 是取图素材的开发助手）；实心图标（data / plugin / settings / dark）与线性图标分两套渲染。弹出网格 **48 个一页**分页，另有 8 个自绘图标与一组 emoji。守门断言 host↔client 的图标名单**双向完全一致**（少一个即红）。② **修「选了图标立刻变回默认」**（反馈 2）—— 根因是 `/admin/wikis` 的**读取视图漏了 `icon` 字段**（`buildWikisView()` 逐字段手写，加字段时漏了一处）：写进 `wikis.json` 了，读回来是 `undefined`，客户端拿它重渲染就回落默认图标 —— 症状"完全像没保存"。补上 `...(entry.icon !== undefined ? { icon: entry.icon } : {})`，并加**源码级守门**钉死该字段（去掉修复即红）。③ **多库下设置页按作用域分页**（反馈 3/4/11）—— 十几块面板挤一页，既分不清「改这个库」还是「改整个插件」，改完也找不到退出口。现在分「**总览 / 本库配置 / 全局**」三个 tab；「插件管理（自带官方插件）/ 主题管理 / 语言管理 / 初始化」这些 **per-库** 面板只在你点了某个库那一行的「配置」之后才出现（此前它们和全局项混排，看着像所有库共用一个设置）；「配置」按钮变成**开关**（再点 = 退出配置），顶部「配置作用域」条一直显示正在改哪个库。**单库安装没有 tab 条**，就是原来那一页。④ **新会话也能选知识库**（反馈 9）—— 选择器此前只长在 `conversation.input.dock`（新会话还没有输入框）。现在挂在**预设/模式选择旁边**：先声明式探测 `conversation.input.selector.context`，2 秒内没等到就回落到 dock，两条路径带 `blankOnly` 互斥，不会同时出现两个。⑤ **剪藏可指定落哪个库**（反馈 8）—— 新增 `bridge.wiki` 配置与设置页下拉（留空 = 默认库）。剪藏来自浏览器书签、没有"当前会话"可以跟随，所以这里必须是**显式钉死**；填了不存在的 id 时 `/clip` 回执会带 `wiki` 字段说明实际落点，插件日志也提示一次。⑥ **回复流卡片与会话「知识库」Tab 按会话作用域取数**（反馈 7/10）—— 卡片取数 / 链接 / 缓存 key / 汇总的存在性探测与渲染全部带上会话作用域的那个库；不这样做会出现"A 库的笔记标题在 B 库里渲染成空白卡片"。工具卡片右上角还会显示库名徽标。⑦ **桌面版能起 TW**（反馈 12）—— TW 子进程需要真正的 `node`，而桌面版里 `process.execPath` 是 Electron。现在按 `DSH_TIDDLYWIKI_NODE` → `where node` / `which node` → `process.execPath` 的顺序解析并缓存，启动日志写明用了哪个；新增 `scripts/verify-desktop-node.mjs` 做**行为级**断言（进 `verify:unit`）。⑧ **复核后确认无需改动的两条**：注入提示词**本来就是按会话求值**的（`systemPrompt.section` 的 text 是函数，DSH 每次装配传入该会话的 agent，插件据此读作用域库的 `prompt.*`）—— 在输入框上方换库，**下一步**就生效，不需要重启或新开会话；15 个 `tiddlywiki_*` 工具在多库下全部正常（可见库 >1 时每条回执由一处包装统一标明库名）。单库安装两条都是逐字节不变。⑨ **代码清理**（反馈 5）—— `tools.ts` 1913→132、`admin.ts` 1265→24（barrel）、`index.ts` 1407→1001、`note-widget.ts` 1245→916、`settings-page.ts` 1815→400，**全部纯搬移**（15 个工具的注册顺序、`apply()` 的装配顺序、所有注释与字符串逐字保持）。配套新增 `scripts/lib/source-family.mjs`：`readFamily()` 把 `<base>.ts` 与 `<base>-*.ts` 拼成一份文本，12 个守门脚本改用它 —— **以后纯搬迁不再假红**（断言的是"规则"而不是"路径"）。`verify-frame-guards` 的 runSwitch 断言跟着新形状更新（`disposed` → `deps.isDisposed()`），并顺手收紧成必须命中**那一条**消息（旁边 `repointDefault` 的「已取消修改」曾因前缀相同而误判通过），两条都做了反向验证。⑩ **文档**：`docs/usage.md` 补 `bridge.wiki` / 设置页分页 / 新会话选择器 / 每个库一个图标 / 桌面版 node；`docs/features.md` 补四条能力；README 顶部版本记录同步。**验证**：`npx tsc --noEmit` 全绿、`npm run build` OK（`client.bundle.js` 701305 字节 / 684.9 KB，远低于 900KB 闸门）、`verify:static` / `verify:unit`（26 个脚本）/ `verify:e2e` / `verify:large` 全绿（含 `WIKI FARM BOOT` 真起两个 TW 子进程、`LARGE WIKI` 3100 条 64s）。
 - **v0.28.7**（2026-09-28）：**会话知识库选择器改成与「快速笔记」同一行 + 单库专属配置项不再在多库下出现**（两条都是作者报障）。① **选择器"没和对话框对齐"** —— 上次的修法方向就错了：`conversation.input.dock` 是**竖向 flex 列，一个条目独占一整行**，选择器和快速笔记是**两个条目**时永远是上下两行，怎么调内边距都不可能并排。现在选择器不再是独立条目，而是由快速笔记条目通过 `scope` 参数渲染在**自己这一行里**（按钮前面），整行统一与输入框右缘对齐，一行只测一次。顺手修掉合并时的一处遗留：选择器组件里还留着上一版的 `alignDockEntry` 自测，并入同一行后会把右内边距补两遍——已移除（`wiki-scope` 也从客户端 slot 表里消失，回归由 `verify-wiki-focus.mjs` 断言"input.dock 只能有一个条目"守住）。② **「侧边栏 TW 入口显示名称」在多库下不该出现** —— 多库时侧边栏是每个库各占一行、各用自己 `wikis.json` 里的显示名，`ui.sidebarLabel` 只喂单库那一行，所以多库下它是个**改了不生效的假配置项**。现在该字段只在单库模式渲染（多库时换成一行说明"去知识库列表改各自的显示名"）；模式探测失败**回落成单库**（保守：宁可多给一个真能用的字段，也不要因为一次请求失败把设置项藏了），并反向断言不许写成 `!== 'single'`（那会把未知模式误判成多库）。两条守门断言都做了反向验证。

package/docs/development.md

@@ -119,5 +119,13 @@ npm publish    # 版本号在 package.json；文件白名单见 files 字段
 
 `tiddlywiki` 依赖体较大（含全部语言包/插件）。
 
+### 发布时要动的地方（完整清单见 AGENTS.md §4）
+
+1. `package.json` 的 `version`；
+2. **本仓库的 `docs/CHANGELOG.md` 顶部**新增一条 `- **vX.Y.Z**（日期）：…` —— 版本历史只住在这里，README 不再放逐版本条目（`scripts/verify-version-consistency.mjs` 会把「README 又长出版本条目」判红）；
+3. `AGENTS.md` §2 速查表的版本行（同一个 commit 里改）。
+
+三处版本号必须一致，由 `npm run verify:static` 里的版本守门盯着。
+
 ---
 

package/docs/plans/migrate-old-machine-to-multi-wiki.md

@@ -0,0 +1,151 @@
+# 给「另一台旧机器」的整段指令（多知识库迁移）
+
+> 用途：把这台机器上**已经落地的多库拆分方案**，同步到另一台仍跑旧版本、单库的机器。
+> 用法：下面「=== 复制开始 ===」到「=== 复制结束 ===」之间的整段，**原样复制**丢给那台机器上的 Agent 会话。
+> 依据：`docs/wiki-split.md`（人读的拆分页）+ `skills/dsh-tiddlywiki-wiki-split/SKILL.md`（Agent 的操作手册）+ 本机实测的 `wikis.json`。
+
+---
+
+=== 复制开始 ===
+
+我的 dsh-tiddlywiki 知识库要升级成**多知识库（多实例）**方案，并且要**把笔记和插件一起同步过来**。
+这台机器是旧版本、单库。请按下面做，**每一步先只读体检、报告给我，我确认再动手**。
+
+## 0. 先把版本升到 ≥ 0.28.9（不然多库功能不存在）
+
+1. 先报告当前版本：读 `C:\Users\bbq\.dsh\profiles\web\node_modules\dsh-tiddlywiki\package.json` 的 `version`，
+   以及 `C:\Users\bbq\.dsh\profiles\web\package.json` 里 `dsh-tiddlywiki` 的声明版本。
+2. 升级（**必须显式指定官方源**，本机默认 `registry.npmmirror.com` 是只读镜像，可能还没有新版本）：
+   ```
+   dsh plugin --profile web up dsh-tiddlywiki --registry=https://registry.npmjs.org
+   ```
+3. 注意：**开发仓库 ≠ 运行时加载的那份插件**。dsh web 实际加载的是 profile 里的副本，
+   所以「改了仓库代码」不会生效，必须走上面的安装命令 + **重启 dsh web**。
+4. 升完先**重启 dsh web**，再继续。多库功能需要 ≥ 0.28.0；本方案的界面细节需要 ≥ 0.28.9。
+
+## 1. 先做只读体检，不要改任何文件
+
+报告这些数字（命令都只读）：
+
+- 当前是不是单库：`GET http://127.0.0.1:<DSH端口>/dsh-tiddlywiki/status`，看有没有 `mode` / `wikis[]`。
+  （旧版本没有这两个字段 = 单库模式，只有「切换知识库位置」。）
+- 当前 wiki 根目录在哪、指针文件 `C:\Users\bbq\.dsh\dsh-tiddlywiki\location.json` 有没有内容。
+- tiddler 数量、tag 分布 Top-20、`files/` 附件体积与文件数。
+- `git rev-parse --show-toplevel` 与各仓库体积、`git remote -v`。
+- **`git status --porcelain` 必须是干净的**（不干净就先同步完再继续，否则后面搬迁会混在一起）。
+
+## 2. 我这边已落地的目标方案（照这个来，除非我另行说明）
+
+**三个库，两套 git 拓扑：**
+
+| 显示名 | id | 收什么 | 目录 | git 仓库 | Agent 可见 | 开局自启 | 图标 |
+|---|---|---|---|---|---|---|---|
+| 工作 | `work` | 日常笔记、开发文档、会议/决策记录 | `C:\Users\bbq\.dsh\tiddlywiki\notes\work` | `dsh-tiddlywiki-data`（与个人库**共用**） | ✅ 是 | ✅ 是 | 默认 |
+| 个人 | `personal` | 个人笔记、生活记录、归档的旧日志 | `C:\Users\bbq\.dsh\tiddlywiki\notes\personal` | 同上（共用） | ✅ 是 | ✅ 是 | `briefcase` |
+| 书籍 | `books` | 书籍/语料/扫描件，基本只读 | `D:\corpus\books` | `dsh-tiddlywiki-books`（**独立仓库，且是 private**） | ❌ **隐身** | ❌ 否 | `book` |
+
+**关键设计点（这些是有意为之，别"优化"掉）：**
+
+- **工作 + 个人共用同一个 git 仓库**（`notes/` 是一个仓库，两个库是它下面的两个文件夹）。
+  为什么：`git add -A` 从子目录执行会暂存**整个工作树**，所以**一个仓库只能有一个 committer**；
+  两个库共用仓库 = 一次提交同时覆盖两者，不会互相踩。
+- **书籍库独立仓库且在 D 盘**：语料约 740MB（其中 `files/` 附件 907 个文件 / 364MB），
+  不能背在 60 秒一次的自动提交上。
+  它同时是 **private** 仓库（`dsh-tiddlywiki-books`）。
+- **书籍库 `agentVisible: false`**：Agent 永远碰不到它（检索 / lint / 反向链接 / 会话选择器都不出现）。
+  这是"防检索被语料淹没"的正解。
+- **书籍库 `autostart: false`**：不随 DSH 启动（每个库一个 TW 子进程，约 150MB），
+  在你打开或选中它时才自动拉起来。
+- **书籍的图片放在 wiki 自己的 `files/` 里**（907 个文件 / 364MB），**不要**改成外链或图床 ——
+  必须保证书籍能独立打开、扫描件不裂图。
+- **`wikis.json` 放在每本 wiki 之外**（`C:\Users\bbq\.dsh\dsh-tiddlywiki\wikis.json`），
+  这样它不会随某个库被搬走。
+
+**`wikis.json` 的目标内容（结构照抄，路径按那台机器实际情况改）：**
+
+```json
+{
+  "version": 1,
+  "mode": "multi",
+  "defaultId": "work",
+  "wikis": [
+    { "id": "work", "label": "工作", "root": "C:\\Users\\bbq\\.dsh\\tiddlywiki\\notes", "name": "work",
+      "agentVisible": true, "autostart": true },
+    { "id": "personal", "label": "个人", "root": "C:\\Users\\bbq\\.dsh\\tiddlywiki\\notes", "name": "personal",
+      "agentVisible": true, "autostart": true, "icon": "briefcase" },
+    { "id": "books", "label": "书籍", "root": "D:\\corpus\\books", "name": ".",
+      "agentVisible": false, "autostart": false, "icon": "book" }
+  ]
+}
+```
+
+手写注意：
+- `id` 只能小写字母/数字加 `._-`，且不能是 `status`/`files`/`recipes`/`render` 这类与 TW 根路径撞名的保留字。
+- 两个库不能指向同一目录，**也不能互相嵌套**（外层库的 `git add -A` 会把内层内容一起提交进去）。
+- `name` 是**该 root 目录下的文件夹名**；`name: "."` 表示 root 本身就是库根（书籍库就是这样）。
+
+## 3. 分步执行（每步做完停下来报告）
+
+1. **备份**：给现有仓库打 tag（例如 `pre-split-<日期>`），保证能整体回滚。**旧库一个都不许删。**
+2. **建目录 / 搬迁**：用 `git mv` 尽量保住历史。
+   ⚠️ **`git mv` 不能跨仓库**（会 `fatal: ... is outside repository`）。
+   跨仓库搬迁的正确姿势：先在**原仓库内** `git mv` 到暂存目录并提交（历史保住在原仓库），
+   再物理移动到新位置、在新位置 `git init` 建新仓库。
+3. **每个库补 `tiddlywiki.info`**（容器根的 `tiddlywiki.info` 要改名让位，例如
+   `tiddlywiki.info.container-backup`，否则 TW 会把它当成一个库根）。
+   容器根下原本的 tiddler 要归档挪走（本机挪到了 `notes\_container-root-tiddlers\`，446 个文件）。
+4. **写 `wikis.json`**（内容见上），`mode: multi`。
+5. **重启 dsh web**，然后设置页里确认「知识库列表」出现三行。
+6. **恢复首页**：三库都要有首页 —— `$:/DefaultTiddlers` 指向 `[[🏠 主页]]`，
+   每库各自设 `SiteTitle` / `SiteSubtitle`（工作 / 个人 / 书籍）。
+   `🏠 主页` 是 `toc-tabbed-external-nav`，用 `索引` 标签收集索引页。
+7. **第三方插件恢复**：把原来那批第三方插件**补回每个库**。本机确认要有的 11 个：
+   `BTC_TiddlyFlex`、`BTC_resizer`、`dyp_LXGWNeoXiHeiScreenFull`、`Gk0Wk_CPL-Repo`、`kookma_narenj`、
+   `kookma_pinboard`、`linonetwo_fira-code-font`、`linonetwo_gallery`、`linonetwo_simple-layout-launcher`、
+   `nico_notebook-mobile`、`oeyoews_mermaid`
+   （在每库的插件管理里勾选；这些是**经 TW 原生方式装进 wiki 的**，落盘为
+   `tiddlers/$__plugins_<author>_<name>.json`，**不会**写进 `tiddlywiki.info`）。
+8. **校验**：
+   - 各库 tiddler 计数与预期一致；
+   - 工作库检索**不再命中**书籍语料；
+   - 每个库能独立打开、独立提交（`git status` 在各仓库里都干净）；
+   - 书籍库在会话选择器里**不出现**（隐身生效）；
+   - 书籍里的扫描图片能正常显示（不是裂图）。
+
+## 4. 软性节点提醒（容易踩的）
+
+- **`heading` 定位**：`tiddlywiki_append` 的 `heading` 落点是「该标题之后、下一个任意级别标题之前」，
+  不是整节末尾；**未命中不会静默**，会返回 `headingMatched=false` 并说明已追加到文末。认这个字段。
+- **一切内容改动走插件 API**（`put`/`append`/`batch_put`/`rename`/`delete`），
+  **不要**直接用文件工具编辑 `tiddlers/` —— 运行中的插件有内存快照，看不见你的磁盘改动，
+  而且下次写入会用内存版**覆盖**你的改动。
+- **要整篇重写大 tiddler，别让模型复述全文**：用脚本在磁盘上做手术 → `POST /dsh-tiddlywiki/restart`
+  （自带 `drainThenStop`，安全）让 TW 重新读盘 → 校验。**前提是先确认 `git status` 干净**，
+  否则重启时的 flush 会把内存里的旧版本写回、覆盖你的手术。
+- **`git pull` 冲突时不要无脑 `keep-local`**：它只改工作区、**那个领先的本地提交没变**，
+  下一次 pull 会重放同一个提交 → 同一个冲突（原地打转）。时间戳-only 的冲突要丢弃本地那个提交。
+- **wiki 指针文件在 wiki 之外**（`location.json`），权限优先级：指针文件 > cordis config > 默认值。
+
+## 5. 我要你先回答我
+
+1. 体检数字（第 1 步那些）。
+2. 那台机器的实际路径跟我上表里的**哪些不一样**（D 盘存不存在？`notes/` 这个结构适不适合照搬？）。
+3. 有没有第二块盘 / 书籍库放哪个盘。
+4. 现有仓库的远端是什么、要不要也拆成两个远端。
+
+**我确认之前，不要创建、移动、删除任何文件。**
+
+=== 复制结束 ===
+
+---
+
+## 附：为什么这样拆（给人看的背景，不用发给那台机器）
+
+- **检索被淹没**是本方案的直接动因：书库 4026 个 tiddler + 907 个扫描附件，
+  和日常笔记混在一个库时，Agent 搜一个词前十条全是语料。
+- **`agentVisible: false` 是"彻底隐身"**，不是"优先级低"——检索、lint、反向链接、会话选择器
+  全都不会碰它。比"让 Agent 自己判断"可靠得多。
+- **一个仓库一个 committer** 是硬约束（`git add -A` 的语义），所以「共用仓库」不是偷懒，
+  而是这两个库必须共用才能各自独立提交而不互相踩。
+- 每个库有**自己的一套配置**（各自的 `$:/plugins/dsh-tiddlywiki/config` tiddler），
+  设置页顶部会显示「配置作用域」，不会出现"改了但不生效"。