dsh-tiddlywiki 0.22.5 → 0.22.6

package/README.md

@@ -132,7 +132,7 @@ dsh plugin --profile web add link:/path/to/dsh-tiddlywiki
 - **🧭 中央列编辑器**：侧边栏「TiddlyWiki」开关（显示名可改 `ui.sidebarLabel`）。
 - **🗂️ 右侧边栏 Tab**（v0.16.21）：DSH 新右侧栏展开后，首页会出现「**TiddlyWiki 知识库**」入口盒，点击即在右侧栏以 tab 形式打开完整 TW 编辑器——**与聊天并排**，适合边聊边查/边记。由 `ui.showRightbarTab` 控制（默认开）；老版本 DSH（无右侧栏）自动跳过。
 - **🧩 Better Sidebar 共存**：装了 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 时，插件只做 UI 共存（中央 TW 面板的 z-index 自动压在其侧边栏展开/收起按钮之下，按钮始终可点）。**v0.17.0 起不再向 dsh-better-sidebar 注册「TiddlyWiki 知识库」tab**（旧版可用 `ui.showBetterSidebarTab` 关闭）——该 tab 的 kind 会与其它注册方冲突报 `tab kind "dsh-tiddlywiki" is already registered`。右侧边栏入口请用上面的 **右侧边栏 Tab**（DSH 原生 rightbar）。
-- **📝 快速笔记**：输入框上方快捷按钮（`ui.showQuickNoteDock`）或 FAB；`ui.quickNoteMode` 选打开方式——**native**（默认，直达 TW 原生编辑页，草稿自动续写）或 **card**（CodeMirror 6 Markdown 高亮、文件上传、多选 tag、草稿自动保存、「🕘 最近」载入、Ctrl+Enter 保存）。
+- **📝 快速笔记**：输入框上方快捷按钮（`ui.showQuickNoteDock`）或 FAB；`ui.quickNoteMode` 选打开方式——**native**（默认，直达 TW 原生编辑页，草稿自动续写）或 **card**（CodeMirror 6 Markdown 高亮、文件上传、多选 tag、草稿自动保存、「🕘 最近」载入、Ctrl+Enter 保存）。**v0.22.6**：原生编辑弹窗里用 TW 的「🗑 删除」把笔记删掉后不会再变成打不开的白板——再点一次「快速笔记」就会重新载入编辑器；card 模式底部操作条改成「按钮文字永不折行、放不下时整组换行」，窄卡片里不再把「✏️ 在 TW 中编辑」压成两行。
 - **📌 本地剪藏桥**（可选，v0.16.24+/v0.16.25 支持图片）：DSH 设置 → 常规配置 → 勾选「**启用本地剪藏桥**」（保存后立即生效）——DSH 即监听 `127.0.0.1:8618` 接收剪藏请求。浏览器书签栏新建书签，把知识库文档里的 JS 代码粘贴为地址，点一下弹出**浮层**：确认/修改标题与划线文字、勾选页面图片（封面自动标出）→「剪藏」即写入 wiki。文字成笔记（默认 `clip` 标签、正文含来源与选中文字、重名自动 `（2）` 去重）；**图片由 DSH 本机下载字节存为二进制附件**（`clip-url`/`clip-note` 溯源字段，笔记内 `[img[标题]]` 内嵌展示；某张下载失败自动降级为链接），全部随 wiki 自动 git commit。「📚 插件文档」栏的 `本地剪藏桥（书签小工具）` seed 文档含完整步骤、书签代码、安全说明与 curl 用法。安全：桥只监听 127.0.0.1 + Host 白名单防 DNS rebinding；**强烈建议设 `bridge.token`**（非空时校验书签的 `x-clip-token` 头，防止任意网页往 wiki 里塞内容）。图片附件按设计不参与 `search`/`recent`（避免刷屏），`get` 只回元数据。
 - **🏠 首页（初始化 home-index 后）**：待办四象限（`todo` 标签 + `q` 字段拖放分类）+ 快速记笔记（完整编辑器，勾选「同时加入待办」即建任务）+「所有标签 / 所有文章」入口 +「📚 插件文档」栏（自动收录所有带 `dsh-docs` 标签的 seed 文档）。
 - **📚 会话知识库 Tab**：会话顶部 Tab（`ui.tabLabel` 改名、`ui.showSessionTab` 关闭），自动汇总本会话读写过的 wiki 笔记（写入 volatile `$:/temp`，不落盘不进 git），**TW 原生渲染**（v0.16.19 起 `/tw/render` 片段管线，与回复流工具卡同链路），链接点击直达中央 TW 面板，不可编辑。
@@ -308,7 +308,8 @@ src/
 ├── index.ts            # host 入口：装配 WikiServer/路由/工具/提示词/自动 commit
 ├── sdk.ts              # 自包含 defineTool + dshHomePath（零 @deepseek-ai 运行时依赖）
 ├── host/
-│   ├── wiki.ts         # WikiServer：spawn/kill/自愈/端口探测/就绪轮询；TW_PROXY_PATH 同源代理
+│   ├── wiki.ts         # WikiServer：spawn/kill/自愈/端口探测/就绪轮询（策略见 ready-policy.ts）+ 迟到就绪复探；TW_PROXY_PATH 同源代理
+│   ├── ready-policy.ts # TW 启动就绪策略（v0.22.5）：软窗口 60s（可配）/ 硬上限 3× / awaitReady 纯策略（注入时钟，可单测）
 │   ├── tw-api.ts       # TiddlyWeb REST 客户端
 │   ├── git.ts          # git init/commit/pull/push/sync/status + AutoCommitter
 │   ├── routes.ts       # 全部 DSH 路由 + agent-send/create/modes + session/summary
@@ -345,6 +346,8 @@ lib/                    # 预构建产物（发布含 lib/**，提交入库；
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.22.6**（2026-09-14）：**修「快速笔记」两处用户实测报障**。① **原生编辑弹窗里删掉笔记后，弹窗变永久白板、再点「快速笔记」也回不来**。`ui.quickNoteMode=native` 的编辑器是**同一个 iframe 复用**的，而 `openEditorPopup()` 只在 **URL 变了**才给 iframe 赋 `src`（刻意如此：赋 `src` 即整页重载，会丢掉 TW 里未保存的草稿 / 滚动位置 / 撤销栈）。可 TW 编辑器的「删除」是 `tm-delete-tiddler`：它把**原 tiddler 与草稿一起删掉**、并用 `removeTitleFromStory` 把 story 清空——于是弹窗里剩一块白板；而此时主机重建的草稿标题往往与删除前**完全相同**（默认标题是分钟级时间戳 + canonical `Draft of "…"` 复用），URL 不变 → 不重载 → 白板永远摆在那儿，再点按钮也只是「收起/重新打开」同一个空 iframe。现在三处一起兜住：新增 `isEditorPopupBlank()`（同源读 iframe 文档里的 `.tc-story-river`，**一条 `.tc-tiddler-frame` 都没有**即判空；跨源 = TW 里点了外链、文档仍在 loading、读不到文档时**一律不判空**，绝不擅自重载一个可能正在编辑的编辑器），空掉的弹窗在 `openEditorPopup()` 里**强制重载**；`closeEditorPopup()` 同时清掉 `frame.dataset.loaded`，所以「关闭再打开」也一定是新的编辑器载入（关闭意味着丢掉上一次的 view 状态）；输入框上方的按钮与 `openNative()` 的「已打开」幂等守卫都改成 `isEditorPopupOpen() && !isEditorPopupBlank()`，用户再点一次就能拿回编辑器。② **card 模式底部操作条把按钮文字压成两行**（用户截图反馈的美化问题）。340px 的卡片里 5 个控件本就放不下，旧 CSS 让 flex 默认收缩，于是「📎 上传」「🕘 最近」「✏️ 在 TW 中编辑」「保存」**每个按钮里的文字都折成了两行**（无头 Chrome 实测：每个按钮 `textRects=2`、高 46px）。现在按钮一律 `white-space: nowrap` + `flex: 0 0 auto`（文字永不折行、永不被压扁），装不下时**整个右组换行**并用 `margin-left: auto` 继续贴右缘，「Ctrl+Enter」提示允许收缩让位——实测全部按钮恢复单行（高 30px），左下是「上传 / 最近 / Ctrl+Enter」、右下是「在 TW 中编辑 / 保存」两行布局。守门：新增 **`scripts/verify-editor-popup.mjs`**（进 `verify:unit`，tsx 直跑源码 + 最小 DOM 打桩，11 条行为断言——同 URL 有内容不重载 / story 被删空必须重载 / 关闭清 `dataset.loaded` / 关闭后重开必重载 / 空白判据的四种保守边界；**反向验证过**：把两处修复改回去会红 3 条），`verify-frame-guards.mjs` 另加 2 条接线断言（空弹窗不得被当成「已打开」）。真机复核：无头 Chrome 里确认「同一个 URL 再赋一次 `src` 确实会重新加载」「清空 story 后重载能恢复内容」，并用真实 CSS + 真实卡片结构对比修复前后的按钮排版。
+
 - **v0.22.5**（2026-09-14）：**修「大知识库冷启动被误判为启动失败」**（用户实测报障：dsh 启动时 `[dsh-tiddlywiki] startup issue (self-healing is armed): Error: wiki server did not become ready in time`）。根因不是 TW 没起来，而是**就绪判定太急 + 判失败后再也没人复探**。证据来自 `/status` 的环形日志：`01:43:51 spawn … tiddlywiki.js … --listen` → `01:44:11 wiki server did not become ready in time` → `01:44:35 [out] Processing background action …` + `[out] Serving on http://127.0.0.1:52323`。也就是说这个 5099 个 tiddler / 26MB 的知识库在**冷文件缓存**下真的需要约 44 秒才打印 `Serving on`，而旧代码只有**一个 20 秒硬超时**，于是：① 抛错中断整条启动管线——配置 tiddler 没加载、核心 seed（发送给 Agent / 渲染路由 / 同源代理 / markdown 插件）没写、剪藏桥没起，全都会拖到下一次重启；② 写死 `health='failed'` + 一条粘性 error，而**超时后没有任何东西会再探测**，所以 TW 明明在正常服务，`/status`（面板 / FAB / 悬浮提示）却一直报故障。现在把「就绪」变成一条明确的三段策略（新的 `src/host/ready-policy.ts`，纯函数 + 注入时钟，可单测）：**软窗口**（默认 60s，可用 `startup.readyTimeoutMs` 在设置页调，夹在 5s–600s）之内安静等待；超过它只写一条 `slow start: /status not ready after Ns — still loading` 并**继续等**（状态保持 `starting`，不再粘住 error）；**硬上限 = 3× 软窗口**仍无响应才判失败——并且失败时**不杀子进程**，而是挂一个**有界（10 分钟）、`unref` 的「迟到就绪」后台探测**，TW 真起来的那一刻立刻把状态改回 `running` 并清掉那条旧错误（`ready (late): /status 200`），`stop()` 与新一次 `start()` 都会取消它。`startup.readyTimeoutMs` 走「cordis 配置 < 配置 tiddler」双层，设置页保存后对**下一次启动/重启**生效，无需重启 dsh web。守门：新增 `scripts/verify-ready-policy.mjs`（进 `verify:unit`，tsx 直跑源码 + 虚拟时钟）——归一化/夹取、**44s 冷启动必须判成功**（本次事故形状的回归断言）、慢启动只警告一次、子进程退出 → 立即 `exited`、始终不就绪 → 到硬上限才 `timeout`、轮询节奏有界（慢窗口降到 2s，不空转），外加源码级接线断言（`wiki.ts` 不得再出现 20s 硬编码、必须有 `awaitReady` / `armLateReadyWatch` / `clearLateReadyWatch`，config/index/client 三处链路都在）；`verify-resilience.mjs` 增加一条真实 TW 的重启断言（窗口热改 + 夹取 + 仍判就绪）。
 
 - **v0.22.4**（2026-09-13）：**重构：把 TW frame 的生命周期收敛成唯一一份实现**（无功能变更，纯去重）。v0.22.3 那个「空 `src` 把 DSH 载进 iframe」的 P0 之所以发生，根因不是谁写错了某个判断，而是 `panel.ts`（中央列面板）与 `tw-frame.ts`（右侧栏 tab）**各自抄了一份** `showError` / `showStarting` / `showFrame` / `applyPendingHash` / `fallbackLoad` / `doRefresh`——修 bug 时守卫只补到 panel，tw-frame 那份照旧，同一个坑于是踩了两次（`panel.ts` 靠「`!hidden` ⇒ 已载入真实 twProxy」这个不成文不变量侥幸安全，tw-frame 连这个都没有）。现在这六个函数只在 `tw-frame.ts` 新增的 **`createTwFrameSurface(skin)`** 里各有一份，`createTwFrameController()` 退化成它的 rightbar 薄包装；一个 surface 只提供三样东西：**皮肤**（类名 + 可选内联样式）、**惰性构建点**（`build()` 返回 view，由调用方决定挂到哪里）、**可见性**（`setVisible()`）。`panel.ts` 因此从 469 行降到 280 行，只剩 rect 钉住 / 惰性构建 / 共存 chrome / 面板互斥。顺带三处行为改进（都是去重后的自然结果）：① 面板打开链接改为**先 `state.openPanel()` 再 `surface.openTiddler()`**（内核以 `visible=false` 拒绝隐藏 surface，顺序反了链接会静默丢失，脚本里有守门断言）；② `setVisible(false)` 现在会**隐藏 frame 并停掉有界轮询**（下次显示重新给满预算）；FAB「重载面板」刻意**不受可见性限制**（唯一判据是 `dataset.loaded`）——显式重载请求要能覆盖**关掉的**面板，否则「关掉面板 → 点重载 → 再打开」会看到旧资源，而展示陈旧内容比多一次重载更糟；③ 内核的 `build()` 会记住「DOM 还没建就被要求显示」的情况并在建好后补一次 `/status` —— 此前中心列若在面板挂载之后才出现，面板会停在空壳上直到用户再切一次。守门：`verify-frame-guards.mjs` 加了**计数去重断言**（panel 里出现任何一个生命周期函数就直接判红，反向验证过：植入回来必失败），并新增 **`scripts/verify-frame-surface.mjs`** —— 用 tsx 直跑源码 + 最小 DOM 打桩，真正执行 `createTwFrameSurface()` 跑 16 条行为断言（空 `src` 的两条重载路径、只显示真的载入过 TW 的 frame、同一 URL 不重复赋 `src`、启动/错误/重试恢复、同源 hash 导航与跨源兜底、共享 chip 标签、dispose 摘监听且幂等），已进 `verify:unit`。测试环境提示：本机沙箱里 node 再 spawn 孙进程会崩，`npm run` 偶发段错误，`verify-package-contents` 与 `verify-git-resolve` 的失败属环境问题（手动复核过断言全过），与本版无关。