dsh-tiddlywiki 0.28.13 → 0.28.14

package/docs/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.28.14**（2026-09-29）：**修「点击切换知识库感觉会卡那么一下」**（作者报障，接在 v0.28.13 之后）。① **先量再改**（不然只是猜）：`/status` 每次要 host 跑最多 5 个 git 进程（本机实测冷缓存 **300–400 ms**）；而换库后的 TW 文档本身是 **9.9 MB / 29.9 MB / 28 MB**（三个库实测），并且 TW 自己回 `Cache-Control: no-store`、没有 `ETag` —— **既缓存不了也预取不了**。② **两段来源分开处理**：内核的焦点订阅原来只调 `doRefresh()`，而它**先等一次 `/status` 往返**才动 iframe —— "点下去"到"真的开始换"之间于是空了 0.3–0.4 秒，紧接着才是那份大文档的下载与解析。现在新增 `switchFrameNow()`：焦点一变就**同步**用上一次 `/status` 的 payload（`mode` + 代理基址 + 名册）把 iframe 指到新库，`doRefresh()` 退为**后台对账**（不再挡在点击与界面反应之间）；拿不到可用 payload 时它什么都不做，行为与 v0.28.13 逐字一致。③ **侧边栏不再重复打 `/status`**：焦点变化原来会重跑一遍 `applyRoster()`（再打一次 `/status` + 重建所有行 + 重走放置逻辑），可名册根本没变、变的只是哪一行亮着；现在收成 `paintFocus()`，只重画高亮。④ **给可见说明**：换文档期间在 TW 界面底部挂一条 `正在载入知识库「个人」…`（`.dsh-tw-loading`），新文档 `load` 到达即收起，并留 **15s 兜底**（`load` 不来时不能把"正在载入"永久挂在界面上）；`showError` / `showStarting` / `setVisible(false)` 三条路径也都会收掉它。提示条是 view 的**最后一个孩子**，刻意**不碰** `frame` 的显隐规则（那条"未载入 TW 地址就绝不显示 frame"是 v0.22.3 的血债）。⑤ **剩下还能不能更快**：不能 —— 剩下的时间全是 TW 自己的文档大小（10–30 MB、`no-store`），不是这套代码能缩短的；面板与右侧栏共用同一条提示。**守门**：`verify-frame-surface.mjs` 新增 2 条**行为级**单测（把 `/status` 打桩成**永不返回**后切库：`frame.src` 必须**已经**指到新库，且提示条可见、写明目标库名、`load` 后收起、15s 兜底收起）；`verify-wiki-focus.mjs` 新增 1 条源码级（`switchFrameNow()` 必须早于 `doRefresh()`，订阅里不许 `await`；侧边栏焦点变化不许重跑名册 —— 反断言跑在**剥掉注释**的代码上；提示条必须**真有 CSS**，v0.28.9 的教训）。**已反向验证**四种注入（退回"只 doRefresh" / `load` 后不收提示 / 焦点重跑名册 / 提示条没有 CSS）都稳定变红，恢复即绿。单库安装行为逐字不变。
+
 - **v0.28.13**（2026-09-29）：**修「左侧多 wiki 入口有时候要点两次才能切到对应的库」**（作者报障）。① **症状**：面板正开着「工作」时点侧边栏「个人」那一行，得点两次才切过去。② **根因**：入口行的点击**一律**走 `state.toggle()` —— `setFocusWiki()` 确实把焦点换过去了（内核也开始换库），但**同一击**里的 toggle 又把面板关掉；用户看到的只是"面板没了"，于是再点一次。开着面板时点**另一个**库，用户要的是切换，不是关面板。③ **修法**：判定收成一个纯函数 `resolveEntryClick()`（面板关着 → `open`；开着且就是当前显示的那个库 → `close`；开着但是别的库 → `switch`），副作用收进 `applyEntryClick()`；`switch` 只切焦点、面板保持打开，换库仍由焦点订阅驱动内核重载（`tw-frame.ts`）。**两条顺序/同源要求**：(a) 判定必须在 `setFocusWiki()` **之前**求值 —— 反了的话刚切过去的那个库会被当成"面板此刻显示的就是它"→ 判成 `close`，等于没修；(b) 行**高亮**与点击判定改用同一个解析 `shownWiki()` —— 原来高亮那一路把 `defaultId` 传成了 `undefined`，焦点还没显式设过时会点亮**第一行**而不是默认库；高亮与点击语义不一致时，"点看起来没亮的那一行"就会变成关面板（同一个报障的第二个来源）。④ **守门**：`verify-wiki-focus.mjs` 新增两条 —— 判定表（7 个用例，含单库那一行）与**行为级**用例（真 `PanelState` + 真 `setFocusWiki`，直接断言本次报障的原始场景："面板开着时点另一个库，面板必须仍开着且焦点已切过去"），另加源码级反向断言（入口行里不得再出现 `toggle()`、判定必须在切焦点之前求值）。**已反向验证**：注入旧行为（切换判成关闭 / 退回无条件 toggle / 把判定挪到切焦点之后）三种改法都稳定变红。**单库安装行为逐字不变**（那一行没有 `wikiId`，仍是纯粹的开关）。⑤ **顺带修好一个长期红着没人看的守门**：`scripts/smoke-client.mjs`（CI 里那条「client bundle module-loader 形状」检查）的 React 替身缺 `createContext`，而 `src/client/tool-views.ts` 自 v0.28.8 起在**模块作用域**调用 `React.createContext(...)` —— 这个脚本于是每次都抛 `c.createContext is not a function`（已在 HEAD 的 `lib/client.js` 上复现确认，与本次改动无关），等于**从那时起就在 CI 里空转**。补全替身（`createContext`/`useContext`/`useMemo`/`useCallback`/`useLayoutEffect`/`forwardRef`/`memo`）并在注释里写清「stub 漏一个 API 就是漏一次检查」。
 
 - **v0.28.12**（2026-09-29）：**「默认库」不再是一个名字：哪里都直接用被设为默认的那个库的真实显示名**（作者要求：「设置了默认库之后，在其他所有的地方不出现默认库的字样……开启会话时默认选中的就是被设置成默认库的库，而不是显示默认库这个选项，这个选项都不该在下拉列表中出现」）。① **会话选择器**（输入框上方那一行）：删掉那个无名的 `value=''`「默认库」选项；默认那个库直接用自己的显示名排在最前，后缀「（默认）」只作**身份标记**；新会话打开时它已经是选中项 —— 靠 `/session/wiki` 返回的 `resolved{id,label}`（宿主解析出来的"这个会话实际用哪个库"），没显式选过就显示它。选中默认那一项 = 清空显式作用域（仍然跟随默认），所以以后改了默认库、没动过选择器的会话会跟着走（语义与旧的无名选项**逐字一致**，只是不再有那个名字）。② **快速笔记「写入」目标**：同样去掉名为「默认库」的占位项（清单里本来就有那个库本身），只给默认库加「（默认）」标记。③ **设置页剪藏目标**：空值那一项就地改名成默认库的显示名 +「（默认）」，并且**跳过**它自己那一行（否则同一个库在下拉里出现两次）；读不到清单时给中性说法「（跟随默认的那个库）」，绝不退回「默认库」。④ **设置页「运行模式」**：`单库（只跑默认库）` → `单库（只跑 <那个库的名字>）`，切单库的确认文案同样直呼其名。⑤ 顺带清掉两处宿主日志里的「默认库」措辞（共用仓库的 git 冲突、剪藏回落），插件说明 seed 里那句也改成「运行模式、库清单、以及哪个库是默认的」。**守门**：`verify-wiki-focus.mjs` 新增一条——把四个界面模块的**注释剥掉**后断言代码里不存在「默认库」字样（注释当然要能讲这段历史），并逐条断言会话选择器读 `resolved`、带「（默认）」标记、默认选中、选中默认项发 null，快速笔记无占位项，剪藏下拉改名且不重复列默认库，单库模式文案直呼其名。单库安装行为逐字不变。

package/docs/features.md

@@ -5,7 +5,7 @@
 | 能力 | 说明 |
 |---|---|
 | 🏠 **文档中心起步包** | 首次安装自动 seed：插件说明 + 「示例与文档」（主题汇总模板 / 教程 / 三个示例主题页），首页「📚 插件文档」栏一键查阅；**同名 tiddler 已存在一律安全跳过，绝不覆盖你的数据**（v0.16.22）；插件说明里的**工具清单由工具注册表实时生成**，不会再写着「10 个工具」却已经 15 个（v0.22.0） |
-| 🗂 **多知识库（v0.28.0）** | **多个 TiddlyWiki 同时在线**，每个库独立配置、独立 git 仓库（或共用仓库按文件夹物理划分 —— 「工作 + 个人」同仓、「书籍」独立仓，两种拓扑都支持）。开关是 `wikis.json` 的 `mode`，**缺省 `single`**：升级用户的行为逐字不变（位置仍由旧指针文件 > cordis 默认决定）。每个库有自己的编辑器与入口（右下角「知识库」菜单的分组、每个库自己的 `/tw/<id>/` 同源基址），设置页「知识库列表」负责增删改 / 启停 / 设为默认 / 开局自启 / 对 Agent 可见性；「移出列表」明确**不会删除目录**。快速笔记卡片也能选目标库（默认跟随你在 GUI 里看的那个库；**整张卡片一起换库**：标签建议 / 最近 / 附件 / 保存 / 弹窗编辑器同库）。**左侧边栏每个在运行的库一行**（各用自己在「知识库列表」里配的显示名与图标，当前显示的那个高亮）：**点另一个库 = 立刻切过去**（v0.28.13 起面板保持打开），点当前那个库才收起 —— 入口同时也是开关。 |
+| 🗂 **多知识库（v0.28.0）** | **多个 TiddlyWiki 同时在线**，每个库独立配置、独立 git 仓库（或共用仓库按文件夹物理划分 —— 「工作 + 个人」同仓、「书籍」独立仓，两种拓扑都支持）。开关是 `wikis.json` 的 `mode`，**缺省 `single`**：升级用户的行为逐字不变（位置仍由旧指针文件 > cordis 默认决定）。每个库有自己的编辑器与入口（右下角「知识库」菜单的分组、每个库自己的 `/tw/<id>/` 同源基址），设置页「知识库列表」负责增删改 / 启停 / 设为默认 / 开局自启 / 对 Agent 可见性；「移出列表」明确**不会删除目录**。快速笔记卡片也能选目标库（默认跟随你在 GUI 里看的那个库；**整张卡片一起换库**：标签建议 / 最近 / 附件 / 保存 / 弹窗编辑器同库）。**左侧边栏每个在运行的库一行**（各用自己在「知识库列表」里配的显示名与图标，当前显示的那个高亮）：**点另一个库 = 立刻切过去**（v0.28.13 起面板保持打开），点当前那个库才收起 —— 入口同时也是开关。切换 = 换成那个库的整份 TW 文档（10–30MB，TW 回 `no-store` 缓存不了），v0.28.14 起**点击即开始换**（不再先等一次 `/status`）、高亮即时跟上、界面底部显示「正在载入知识库「X」…」。 |
 | 🎨 **每库图标用 DSH 官方图标系统（v0.28.8）** | 知识库列表里每行的图标是个**弹出式网格**：收录 **DSH 官方的 36 个图标**（内联的是上游的 path 数据，客户端保持纯 DOM、零运行时依赖）+ 本插件自绘的 8 个 + 一组 emoji，超出 **48 个一页**分页展示；选中即写入 `wikis.json` 的 `icon`。同时修掉一个真 bug：`/admin/wikis` 的读取视图漏了 `icon` 字段，导致「选了图标、界面立刻变回默认」（写进去了、读回来是 `undefined`）—— 守门钉死该字段并反向验证过。 |
 | 📑 **设置页分页：总览 / 本库配置 / 全局（v0.28.8）** | 多库模式下十几块面板挤在一页里，既分不清「改这个库」还是「改整个插件」，改完也没有退出口。现在按作用域分成三个 tab：「**总览**」（名册 + 全局项）、「**本库配置**」（点某个库的「配置」才出现；按钮变成「**退出配置**」，再点一次就回到总览）、「**全局**」。「插件管理（自带官方插件）/ 主题管理 / 语言管理 / 初始化」这些**per-库**面板只在本库配置里渲染（此前它们混在全局项中，看着像所有库共用一个设置）。**单库安装没有 tab 条**，就是原来那一页，逐字不变。 |
 | 🆕 **新会话也能选知识库（v0.28.8 / v0.28.11）** | 会话知识库选择器此前只长在输入框上方；空白会话（还没发过消息、输入框尚未出现）里它挂在**预设/模式选择旁边**。实现是**声明感知**的：DSH 声明了 `conversation.input.selector.context` 就注入那里（那一格只对空白会话渲染），声明不到**就留在 dock 里那一行** —— 任何情况下都只有**一个**选择器（v0.28.11 修：旧实现"2 秒没等到就回落到 dock"会**再注册一个条目**，而 dock 里本来就有同一个选择器，于是新会话里出现两个、其中一个和快速笔记同一行）。 |

package/docs/usage.md

@@ -102,6 +102,7 @@
   `git.*` 以该仓库下**列表里第一个库**为准、配置不一致时打印警告；pull 之后**只重启内容真的变了的库**。
 - **快速笔记的目标库**：卡片里有一个「写入」下拉，**默认跟随你在 GUI 里看的那个库**（右下角菜单切换焦点库，它就跟着变）；在里面手动选过之后，这张卡片就不再被焦点带走。改目标库是**整张卡片一起换**——标签建议、最近列表、附件上传、保存、以及随后弹出的 TW 编辑器都会落到同一个库。目标库没在运行时卡片会先提示你，而不是等你写完再失败。
 - **左侧边栏每个库一行**（v0.28.3 起，点击语义见 v0.28.13）：每个**在运行**的库一个入口行，用自己的显示名与图标（在「知识库列表」里改），**当前面板显示的那个库高亮**。**点另一个库 = 立刻切过去**（面板保持打开，不会先关掉让你再点一次）；点**当前那个库** = 收起面板 —— 入口同时也是开关。没在运行的库不在这一列（它们仍可从右下角「知识库」菜单启动）。
+- **切库为什么需要等一下**（v0.28.14）：切换 = 在同一个 iframe 里**换成另一个库的整份 TW 文档**（一个 iframe 只能装一个编辑器）。本机实测这份文档是 **9.9 MB / 29.9 MB / 28 MB**，而且 TW 自己回 `Cache-Control: no-store`、没有 ETag —— **缓存不了也预取不了**，所以每次切换都要真下载解析一遍。这一版做了三件事让它不"看起来卡住"：① 点击**立即**开始换（不再先等一次 `/status`，那次往返在这台机器上要 300–400 ms，因为 host 每次都要跑最多 5 个 git 进程）；② 侧边栏的选中高亮即时跟上，且不再重复请求 `/status`；③ TW 界面底部显示 **`正在载入知识库「个人」…`**，新文档到达即收起（另有 15 秒兜底）。**剩下的等待是 TW 文档大小决定的**，不是可以再优化的延迟。
 - **「移出列表」不删目录**：只是让插件不再管理它，内容原样保留。
 - **每个库一个图标**（v0.28.8）：知识库列表每行的图标是个**弹出式网格**——里面是 **DSH 官方的 36 个图标**（与侧边栏/工具栏那套同源，深浅主题都对）、本插件自绘的 8 个（书籍 / 公文包 / 首页 / 笔记本 / 烧瓶 / 地球 / 星标 / 归档），外加一组 emoji 快捷选择；图标多了按 **48 个一页**翻页。选中即写入 `wikis.json` 的 `icon` 字段。当前值若不在候选里（比如你手写的短 emoji）会原样保留，不会被候选列表抹掉。**v0.28.8 同时修了一个真 bug**：此前选了图标界面会立刻变回默认 —— `/admin/wikis` 的读取视图漏了 `icon` 字段，于是"写进去了、读回来是 undefined"，看起来就是没生效（现在有守门钉死这个字段，反向验证过）。
 - **还没发过消息的新会话也能选库**（v0.28.8）：选择器此前只长在输入框上方；新会话（空白页，输入框还没出现）时它挂在**预设/模式选择旁边**，位置由声明决定、声明不到就 2 秒后回落，两种布局不会同时出现两个。