dsh-tiddlywiki 0.28.13 → 0.29.0

package/src/client/tw-frame.ts

@@ -28,7 +28,7 @@
  */
 import * as React from 'react'
 import { RESTART_ENDPOINT, resolveTwUrl, twProxyFor } from './endpoints.ts'
-import { fetchStatus } from './status-cache.ts'
+import { fetchStatus, type StatusPayload } from './status-cache.ts'
 import { getFocusWiki, subscribeFocusWiki } from './wiki-focus.ts'
 import { attachThemeSync, setThemeSyncConfig } from './theme-sync.ts'
 
@@ -111,6 +111,8 @@ export interface TwFrameSkin {
   frame: string
   /** Error / starting panel. */
   error: string
+  /** Hint shown while a DIFFERENT wiki's document is on the wire (v0.28.14). */
+  loading: string
 }
 
 /**
@@ -177,7 +179,19 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
   let view: HTMLDivElement | undefined
   let frame: HTMLIFrameElement | undefined
   let errorArea: HTMLDivElement | undefined
+  let loadingEl: HTMLDivElement | undefined
   let refreshTimer: number | undefined
+  /** "Switching wiki" hint timer (v0.28.14). */
+  let switchTimer: number | undefined
+  /**
+   * The last successful `/status` payload (v0.28.14).
+   *
+   * A wiki switch needs only two things from it — `mode` and the proxy bases — and we
+   * already have them from the refresh that opened the current wiki. Re-fetching costs
+   * a full round-trip (the host runs up to five `git` processes per `/status`, measured
+   * 300–400 ms here), which used to sit BETWEEN the click and the start of the switch.
+   */
+  let lastStatus: StatusPayload | undefined
   /** In-flight hash-readiness retry timers (cancelled by dispose, v0.19.1). */
   const hashWaitTimers = new Set<number>()
   let refreshAttempts = 0
@@ -209,6 +223,7 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
 
   const showError = (message: string): void => {
     if (frame === undefined || errorArea === undefined) return
+    hideSwitching()
     frame.hidden = true
     errorArea.hidden = false
     errorArea.replaceChildren()
@@ -229,6 +244,7 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
 
   const showStarting = (): void => {
     if (frame === undefined || errorArea === undefined) return
+    hideSwitching()
     frame.hidden = true
     errorArea.hidden = false
     errorArea.replaceChildren()
@@ -237,7 +253,44 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
     errorArea.append(p)
   }
 
-  const showFrame = (url: string, wiki: string | undefined): void => {
+  /** Cancel the "switching wiki" hint's safety timer. */
+  const clearSwitchTimer = (): void => {
+    if (switchTimer !== undefined) {
+      window.clearTimeout(switchTimer)
+      switchTimer = undefined
+    }
+  }
+
+  /** Drop the "loading another wiki" hint (the new document arrived, or we gave up). */
+  const hideSwitching = (): void => {
+    clearSwitchTimer()
+    if (loadingEl !== undefined) loadingEl.hidden = true
+  }
+
+  /**
+   * Say 「正在载入知识库「X」…」 while a DIFFERENT wiki's document is on the wire.
+   *
+   * WHY (v0.28.14，作者报障「点击切换感觉会卡那么一下」): 一个 iframe 只能装一份 TW
+   * 文档，换库 = 重新下载并解析**整份** wiki。本机实测这份文档是 **9.9 MB / 29.9 MB /
+   * 28 MB**，而且 TW 自己回 `Cache-Control: no-store`、没有 ETag —— 既缓存不了也预取不了。
+   * 这段时间界面完全不动，用户只能感觉"卡住了"。加载时长不是这套代码能把控的，但**界面
+   * 必须说清正在发生什么**（否则一次正常的 1–2 秒等待看起来就是"卡死/没反应"）。
+   *
+   * 兜底 15s：`load` 万一不来（库没起来 / 服务挂了），提示不能永久挂在界面上 —— 那条路径
+   * 由 showError/showStarting 接管。
+   */
+  const showSwitching = (label: string): void => {
+    if (loadingEl === undefined) return
+    loadingEl.textContent = `正在载入知识库「${label}」…`
+    loadingEl.hidden = false
+    clearSwitchTimer()
+    switchTimer = window.setTimeout(() => { switchTimer = undefined; hideSwitching() }, 15_000)
+  }
+
+  /** A wiki's display name, from the last roster we saw (falls back to its id). */
+  const wikiLabel = (id: string): string => lastStatus?.wikis?.find((w) => w.id === id)?.label ?? id
+
+  const showFrame = (url: string, wiki: string | undefined, label?: string): void => {
     if (frame === undefined || errorArea === undefined) return
     errorArea.hidden = true
     // Only reveal the frame while the surface is on screen: doRefresh() can
@@ -252,6 +305,8 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
       frame.dataset.loaded = url
       frameLoaded = false
       frame.src = url
+      // 换了文档 = 重新下载整份 wiki（10–30MB、no-store）：这段时间必须给个可见说明。
+      if (label !== undefined) showSwitching(label)
     }
     // 换库这一步到此为止（url 没变也算了结：单库模式下两个 id 解析出同一条裸路径）。
     // 迟到的 hash 请求现在才允许落地 —— src 真的换了就等 load 事件再调一次。
@@ -352,6 +407,8 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
       showError('无法访问 /dsh-tiddlywiki/status')
       return
     }
+    // 记住这一份：换库要用它的 mode / 代理基址 / 名册（见 switchFrameNow 与 wikiLabel）。
+    lastStatus = payload
     if (payload.ui !== undefined) {
       // Shared surface label + theme config: both are module-level, so any
       // surface that polls keeps them fresh for every other surface.
@@ -372,10 +429,12 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
         // TW refuses to load its sync adaptor anywhere else — see resolveTwUrl.
         // WHICH knowledge base (v0.28.0): the focused one in multi mode, else the
         // bare path (= the default wiki, exactly as before).
-        const bases = twProxyFor(payload.mode, hooks.wikiId?.(), payload.twProxy, payload.twProxyAbsolute)
-        showFrame(resolveTwUrl(bases.relative, bases.absolute), hooks.wikiId?.())
+        const wiki = hooks.wikiId?.()
+        const bases = twProxyFor(payload.mode, wiki, payload.twProxy, payload.twProxyAbsolute)
+        showFrame(resolveTwUrl(bases.relative, bases.absolute), wiki, wiki === undefined ? undefined : wikiLabel(wiki))
       } else if (typeof payload.url === 'string') {
-        showFrame(payload.url, hooks.wikiId?.())
+        const wiki = hooks.wikiId?.()
+        showFrame(payload.url, wiki, wiki === undefined ? undefined : wikiLabel(wiki))
       } else {
         showError('服务未返回编辑器地址')
       }
@@ -410,14 +469,45 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
   }
   document.addEventListener(PANEL_RELOAD_EVENT, onReloadRequest)
 
+  /**
+   * Point the frame at the focused wiki RIGHT NOW, using the last `/status` payload.
+   *
+   * v0.28.14（作者报障「点击切换感觉会卡那么一下」）：旧实现只调 `doRefresh()`，而它要**先**
+   * 等一次 `/status` 往返才动 iframe。host 处理一次 `/status` 会跑最多五个 `git` 进程
+   * （本机实测 300–400 ms），于是"点下去"与"真的开始换库"之间空了 0.3–0.4 秒，紧接着才是
+   * 10–30MB 文档的下载与解析 —— 两段加起来就是那一下卡顿。换库需要的全部信息（`mode`、
+   * 代理基址、名册）上一次刷新已经拿到了，没有理由再等一次。
+   *
+   * 没有可用 payload（首次加载失败、服务在重启）时什么都不做：调用方的 `doRefresh()`
+   * 仍会照旧把整件事做完，行为与 v0.28.13 完全一致。
+   */
+  const switchFrameNow = (): void => {
+    const payload = lastStatus
+    if (payload === undefined || payload.status !== 'running') return
+    const wiki = hooks.wikiId?.()
+    const label = wiki === undefined ? undefined : wikiLabel(wiki)
+    if (typeof payload.twProxy === 'string') {
+      const bases = twProxyFor(payload.mode, wiki, payload.twProxy, payload.twProxyAbsolute)
+      showFrame(resolveTwUrl(bases.relative, bases.absolute), wiki, label)
+    } else if (typeof payload.url === 'string') {
+      showFrame(payload.url, wiki, label)
+    }
+  }
+
   /**
    * Switching the focused knowledge base needs a different proxy path, so the
    * frame reloads (v0.28.0). TW reloads inside the iframe — one iframe cannot
    * host two editors, and silently keeping the old wiki's data while the UI says
    * otherwise is exactly the confusion this feature must not create.
+   *
+   * v0.28.14：**先立即换，再后台复探**。`switchFrameNow()` 用已有 payload 当场把 iframe
+   * 指过去（并把"正在载入…"挂上），`doRefresh()` 只负责随后的状态/配置对账，不再挡在
+   * 用户点击与界面反应之间。
    */
   const unsubscribeFocus = subscribeFocusWiki(() => {
-    if (!disposed && visible) void doRefresh()
+    if (disposed || !visible) return
+    switchFrameNow()
+    void doRefresh()
   })
 
   const build = (): HTMLDivElement => {
@@ -438,14 +528,22 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
     const errorEl = document.createElement('div')
     errorEl.className = skin.error
     errorEl.hidden = true
-    viewEl.append(wrapEl, errorEl)
+    // 换库提示（v0.28.14）：**view 的最后一个孩子**。刻意不放进 wrap / 不改 frame 的
+    // 显隐规则 —— 那条"未载入 TW 地址就绝不显示 frame"的规则是 v0.22.3 的血债，不碰它。
+    const loadingEl2 = document.createElement('div')
+    loadingEl2.className = skin.loading
+    loadingEl2.hidden = true
+    viewEl.append(wrapEl, errorEl, loadingEl2)
     view = viewEl
     frame = frameEl
     errorArea = errorEl
+    loadingEl = loadingEl2
     // Track load so a pending tiddler-hash navigation can target a ready
     // document (setting contentWindow.location.hash before load is a no-op).
     frameEl.addEventListener('load', () => {
       frameLoaded = true
+      // 新文档到了：收起"正在载入…"（幂等，普通刷新时它本来就是隐藏的）。
+      hideSwitching()
       applyPendingHash()
     })
     // Embedded TW follows the DSH light/dark theme (non-persisting palette
@@ -476,6 +574,8 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
       } else {
         // Hidden surfaces stop polling and get a fresh budget on the next show.
         clearRetry()
+        // 界面都不显示了，"正在载入…" 没有意义（也不该在再次打开时凭空挂着）。
+        hideSwitching()
         refreshAttempts = 0
       }
     },
@@ -506,6 +606,7 @@ export function createTwFrameSurface(skin: TwFrameSkin, hooks: TwFrameHooks = {}
       document.removeEventListener(PANEL_RELOAD_EVENT, onReloadRequest)
       unsubscribeFocus()
       clearRetry()
+      clearSwitchTimer()
       for (const timer of hashWaitTimers) window.clearTimeout(timer)
       hashWaitTimers.clear()
       themeSyncDispose?.()
@@ -567,6 +668,7 @@ const RIGHTBAR_SKIN: TwFrameSkin = {
   frameWrap: 'dsh-tw-rightbar-frame-wrap',
   frame: 'dsh-tw-rightbar-frame',
   error: 'dsh-tw-rightbar-error',
+  loading: 'dsh-tw-loading',
 }
 
 /**

package/src/client/wiki-scope.ts

@@ -43,12 +43,22 @@ interface ScopeEntry { wikiId: string | undefined; at: number }
 const cache = new Map<string, ScopeEntry>()
 /** In-flight reads, so a card grid mounting at once makes ONE request. */
 const pending = new Map<string, Promise<string | undefined>>()
+/** Scope-invalidation subscribers (v0.29.0) — see invalidateSessionWikiId. */
+const scopeListeners = new Set<(sessionId?: string) => void>()
 
 /**
  * The wiki id this session is scoped to, or `undefined` for the default wiki.
  *
- * Never throws: a failed request resolves to `undefined` (the default), which is
- * the same thing the host does when nothing is scoped.
+ * v0.29.0 — "the default wiki" is now named explicitly in MULTI mode. When a
+ * session has no explicit scope, the host still serves its `tiddlywiki_*` calls
+ * from the registry default; the reply-stream card therefore shows THAT wiki's
+ * content, and its links must open THAT wiki. Previously this returned
+ * `undefined` for "no explicit scope", so with the session on the default wiki
+ * and the GUI focused on another one, a link inside the card (and inside the
+ * 「知识库」tab) opened the FOCUSED wiki — the v0.28.11 report, only half fixed
+ * (the card's own 「在 TW 打开」 button was already correct because it passes the
+ * resolved default). Single mode keeps returning `undefined`, so its DOM and
+ * URLs are byte-identical to what they were before multi-wiki.
  */
 export async function resolveSessionWikiId(sessionId: string | undefined): Promise<string | undefined> {
   if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined
@@ -64,8 +74,11 @@ export async function resolveSessionWikiId(sessionId: string | undefined): Promi
         { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) },
       )
       if (!res.ok) return undefined
-      const payload = (await res.json().catch(() => null)) as { scope?: unknown } | null
-      return typeof payload?.scope === 'string' && payload.scope.length > 0 ? payload.scope : undefined
+      const payload = (await res.json().catch(() => null)) as { scope?: unknown; resolved?: { id?: unknown }; mode?: unknown } | null
+      if (typeof payload?.scope === 'string' && payload.scope.length > 0) return payload.scope
+      const resolvedId = payload?.resolved?.id
+      if (payload?.mode === 'multi' && typeof resolvedId === 'string' && resolvedId.length > 0) return resolvedId
+      return undefined
     } catch {
       return undefined
     } finally {
@@ -85,14 +98,26 @@ export async function resolveSessionWikiId(sessionId: string | undefined): Promi
  * so the cards rendered next reflect the new knowledge base instead of waiting
  * out the TTL — a stale entry here is the same "card shows another wiki's data"
  * bug this module exists to fix.
+ *
+ * v0.29.0 also NOTIFIES subscribers: invalidating the id is enough for a card
+ * that re-renders anyway, but the 「知识库」 tab caches a whole generated summary
+ * for 3 minutes (`session-summary.ts`), so without a signal it kept showing the
+ * previous wiki's notes (and its `data-dsh-tw-wiki`) after a switch.
  */
 export function invalidateSessionWikiId(sessionId?: string): void {
   if (typeof sessionId === 'string' && sessionId.length > 0) cache.delete(sessionId)
   else cache.clear()
+  const id = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : undefined
+  for (const listener of [...scopeListeners]) listener(id)
 }
 
-/** Test/teardown hook: forget everything, including in-flight reads. */
-export function resetSessionWikiIdCache(): void {
-  cache.clear()
-  pending.clear()
+/**
+ * Subscribe to scope invalidations (one arg = the session, `undefined` = all).
+ *
+ * Returns the unsubscribe function; callers are React effects, so they must
+ * clean up on unmount like every other listener in this half.
+ */
+export function subscribeSessionWikiId(listener: (sessionId?: string) => void): () => void {
+  scopeListeners.add(listener)
+  return () => { scopeListeners.delete(listener) }
 }

package/src/host/admin-routes.ts

@@ -35,6 +35,17 @@ export interface AdminDeps {
    * practice, so the settings-page routes must say WHICH wiki they configure.
    */
   config: (req: IncomingMessage) => ConfigStore
+  /**
+   * Why this request names a knowledge base that cannot serve it (v0.29.0):
+   * `?wiki=<id>` naming a REGISTERED but STOPPED wiki returns an actionable
+   * sentence, everything else `undefined`.
+   *
+   * The settings page is the worst offender for the silent-wrong-wiki class
+   * (its status row and config form are built from `/admin/state`, which would
+   * otherwise answer with the DEFAULT wiki's path/git/config while the scope bar
+   * says 「正在配置：books」), so the wiki-scoped admin handlers check this FIRST.
+   */
+  targetProblem?: (req: IncomingMessage) => string | undefined
   /**
    * Called after a successful settings-page save (v0.21.0). The plugin rebuilds
    * its system-prompt section here, so a prompt.* edit applies to the running
@@ -138,9 +149,33 @@ export type AdminWikisApplyResult =
   | { ok: false; error: string }
 
 export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: AdminDeps): () => void {
+  /**
+   * 503 when `?wiki=<id>` names a REGISTERED but STOPPED knowledge base (v0.29.0).
+   *
+   * The settings page is where this used to hurt most: the scope bar said
+   * 「正在配置：books」 while `/admin/state` answered with the DEFAULT wiki's
+   * path/git/`tiddlywiki.info` and `/admin/config` wrote the books patch into the
+   * default wiki's config tiddler. Every wiki-scoped handler asks this FIRST,
+   * because `deps.config` / `deps.getWikiPath` have harmless-looking fallbacks
+   * that only ASK for the wrong-answer bug when the target is known-but-stopped.
+   */
+  const refuseStoppedTarget = (req: IncomingMessage, res: ServerResponse): boolean => {
+    const problem = deps.targetProblem?.(req)
+    if (problem === undefined) return false
+    json(res, { ok: false, error: problem }, 503)
+    return true
+  }
+
+  /** The 503 body for "no running wiki behind this request", wiki named if known. */
+  const notRunning = (req: IncomingMessage): string => deps.targetProblem?.(req) ?? 'wiki service is not running'
+
   const handleState = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       if (rejectNonRead(req, res)) return
+      // `/admin/state` is the settings page's whole view of "the wiki I am
+      // configuring": answering with the default wiki's path/git/config while the
+      // scope bar names another one is the silent-wrong-wiki bug (v0.29.0).
+      if (refuseStoppedTarget(req, res)) return
       const wikiPath = deps.getWikiPath(req)
       const [info, catalog] = await Promise.all([readWikiInfo(wikiPath), bundledCatalog(deps.twRoot())])
       let git: unknown = null
@@ -183,6 +218,9 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
   const handleInfo = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       if (rejectCrossSiteWrite(req, res, ['POST'])) return
+      // 插件/主题/语言写的是该库的 tiddlywiki.info：目标库没在跑就必须拒绝，
+      // 否则会把 A 库的清单写进**默认库**的文件（v0.29.0）。
+      if (refuseStoppedTarget(req, res)) return
       const body = JSON.parse(await readBody(req)) as { plugins?: unknown; themes?: unknown; themeActive?: unknown; languages?: unknown }
       const wikiPath = deps.getWikiPath(req)
       // A read failure must NEVER be turned into "the wiki has no plugins":
@@ -324,7 +362,7 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
       const body = JSON.parse(await readBody(req)) as unknown
       const client = deps.getClient(req)
       if (client === undefined) {
-        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        json(res, { ok: false, error: notRunning(req) }, 503)
         return
       }
       // Validate/normalise BEFORE merging (v0.25.0): the raw body used to be
@@ -387,7 +425,7 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
       if (rejectNonRead(req, res)) return
       const client = deps.getClient(req)
       if (client === undefined) {
-        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        json(res, { ok: false, error: notRunning(req) }, 503)
         return
       }
       const items = await deps.seeds.checkAll(client)
@@ -410,7 +448,7 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
       const force = body.force === true
       const client = deps.getClient(req)
       if (client === undefined) {
-        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        json(res, { ok: false, error: notRunning(req) }, 503)
         return
       }
       const seedStartedAt = Date.now()
@@ -465,7 +503,7 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
       const id = typeof body.id === 'string' && body.id.trim().length > 0 ? body.id.trim() : undefined
       const client = deps.getClient(req)
       if (client === undefined) {
-        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        json(res, { ok: false, error: notRunning(req) }, 503)
         return
       }
       const results = await deps.seeds.remove(client, id)
@@ -492,6 +530,9 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
    */
   const handlePrompt = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
+      // 提示词是**按库**存的（每库一份 prompt.*）：目标库没在跑时给出基座默认，
+      // 等于把「预览」变成另一个库的文本（v0.29.0）。
+      if (refuseStoppedTarget(req, res)) return
       const draft = (req.method ?? 'GET').toUpperCase() === 'POST'
       if (draft) {
         if (rejectCrossSiteWrite(req, res, ['POST'])) return

package/src/host/clip-bridge.ts

@@ -610,6 +610,19 @@ const CORS_HEADERS: Record<string, string> = {
 export class ClipBridge {
   private server: Server | undefined
   private boundPort = 0
+  /**
+   * 剪藏请求的串行队列（v0.29.0）。
+   *
+   * WHY: the note title is chosen with a check-then-write
+   * (`resolveClipTitle(deps.exists, …)`), so two clips of the same page in flight
+   * — a double bookmarklet click, or two tabs — both see "X is free" and the
+   * second PUT silently replaces the first note (leaving the first note's image
+   * tiddlers orphaned). TW's REST has no compare-and-set, so the cross-process
+   * race cannot be closed; the same-process one can, and that IS the common case:
+   * serialize `/clip` handling here. The second request then resolves the title
+   * AFTER the first landed and picks 「X 2」.
+   */
+  private clipChain: Promise<unknown> = Promise.resolve()
 
   constructor(private readonly deps: ClipBridgeDeps) {}
 
@@ -622,7 +635,12 @@ export class ClipBridge {
   start(port: number): Promise<void> {
     if (this.server !== undefined) return Promise.resolve()
     const server = createServer((req, res) => {
-      void this.handle(req, res).catch((err: unknown) => {
+      // 串行执行（v0.29.0）：标题解析是"先查后写"，并发时第二次会覆盖第一次
+      // （见 clipChain 的注释）。队列本身必须永远保持 resolved，否则一次失败
+      // 会把后续所有剪藏请求一起卡住。
+      const run = this.clipChain.then(() => this.handle(req, res))
+      this.clipChain = run.then(() => undefined, () => undefined)
+      run.catch((err: unknown) => {
         const message = err instanceof Error ? err.message : String(err)
         this.deps.log?.(`request failed: ${message}`)
         if (!res.headersSent) {

package/src/host/config.ts

@@ -207,6 +207,25 @@ export function describeUnreadableConfig(): string {
     + '为避免抹掉其它设置，本次保存已被拒绝。请先修好该 tiddler（或删除它、回落到 cordis config 块）再保存。'
 }
 
+/**
+ * Same refusal, different cause (v0.29.0): the tiddler could not be READ at all
+ * and we have never managed to read it — so we do not know what it contains.
+ *
+ * This is the v0.23.4 wipe through the other door. `set()` re-reads the tiddler
+ * specifically so a transient startup failure cannot cost the user's other
+ * overrides; that protection only exists when the re-read SUCCEEDS. When both
+ * reads failed and the cache is still the empty placeholder, merging a one-key
+ * patch onto it and writing persists a config tiddler containing ONLY that key —
+ * silently dropping `prompt.extra`, `git.remote`, every `ui.*` switch.
+ *
+ * Rule #3 ("a read failure is not an absence") applied to a read-modify-write:
+ * the honest answer is to refuse and let the user retry.
+ */
+export function describeUnconfirmedConfig(): string {
+  return `读不出配置 tiddler ${CONFIG_TIDDLER}（TiddlyWiki 正在重启或超时），因此无法确认里面还有哪些设置。`
+    + '为避免只写入本次改动、抹掉其余设置，本次保存已中止，请稍后重试。'
+}
+
 /** A settings-page patch that cannot be accepted (v0.25.0) — mapped to HTTP 400. */
 export class ConfigPatchError extends Error {
   constructor(message: string) {
@@ -315,6 +334,13 @@ export function normalizeConfigPatch(input: unknown): PluginConfigShape {
  */
 export class ConfigStore {
   private overrides: PluginConfigShape = {}
+  /**
+   * True once this store has successfully DETERMINED the stored overrides
+   * (v0.29.0): either the tiddler parsed, or it was absent (404 = no overrides).
+   * A failed read leaves it false, which is what makes `set()` refuse to merge
+   * onto an empty cache it cannot vouch for — see describeUnconfirmedConfig().
+   */
+  private loaded = false
   /** Set when the stored tiddler exists but cannot be parsed (v0.23.4). */
   private lastParseError: string | undefined
 
@@ -361,9 +387,13 @@ export class ConfigStore {
       console.warn('[dsh-tiddlywiki] config tiddler unreadable, keeping cached overrides:', err instanceof Error ? err.message : err)
       return
     }
-    if (tiddler === undefined) {
+    // `== null` covers a client that answers `null` for "no such tiddler" as well
+    // as the documented 404 → undefined (v0.29.0: `null.text` used to throw and be
+    // reported as "unparseable config", which is a different problem entirely).
+    if (tiddler == null) {
       this.overrides = {}
       this.lastParseError = undefined
+      this.loaded = true
       return
     }
     const raw = typeof tiddler.text === 'string' ? tiddler.text : ''
@@ -372,6 +402,7 @@ export class ConfigStore {
       if (!isPlainObject(parsed)) throw new Error('config tiddler is not a JSON object')
       this.overrides = parsed as PluginConfigShape
       this.lastParseError = undefined
+      this.loaded = true
     } catch {
       // Malformed/unparseable: keep the cache (never revert to the base) and
       // remember WHY so the UI can say it out loud.
@@ -400,24 +431,35 @@ export class ConfigStore {
     let storedText: string | undefined
     try {
       const tiddler = await client.get(CONFIG_TIDDLER)
-      if (tiddler !== undefined && typeof tiddler.text === 'string') {
+      // `!= null` (not `!== undefined`): a client that answers `null` for "no such
+      // tiddler" means exactly that — absent, so writing only this patch loses
+      // nothing. Only a THROWN read is "unconfirmed" (v0.29.0).
+      if (tiddler != null && typeof tiddler.text === 'string') {
         storedText = tiddler.text
         const parsed = JSON.parse(tiddler.text) as unknown
         if (!isPlainObject(parsed)) throw new Error('config tiddler is not a JSON object')
         stored = parsed as PluginConfigShape
       }
-      if (tiddler !== undefined && typeof tiddler.created === 'string' && tiddler.created.trim().length > 0) {
+      if (tiddler != null && typeof tiddler.created === 'string' && tiddler.created.trim().length > 0) {
         existingCreated = tiddler.created
       }
     } catch (err) {
       // Read succeeded (we have the raw text) but the content is unusable:
-      // refuse — writing would drop every key the caller did not send. A READ
-      // failure (no raw text) keeps the old "merge onto the cache" behaviour.
+      // refuse — writing would drop every key the caller did not send.
       if (storedText !== undefined) {
         this.lastParseError = describeUnreadableConfig()
         throw new ConfigUnreadableError(describeUnreadableConfig(), storedText)
       }
-      // Unreadable config tiddler → merge onto the in-memory cache.
+      // The read FAILED and this store never confirmed what is stored (v0.29.0):
+      // the cache is still the empty placeholder, so merging onto it would persist
+      // a config tiddler holding ONLY this patch — every other override gone.
+      // Refuse; a retry after the wiki settles is cheap, the loss is not.
+      if (!this.loaded) {
+        this.lastParseError = describeUnconfirmedConfig()
+        throw new ConfigUnreadableError(describeUnconfirmedConfig(), '')
+      }
+      // Read failure with a cache we DO trust (it came from a successful read):
+      // keep the old "merge onto the cache" behaviour.
       void err
     }
     const merged = deepMerge(stored, patch) as PluginConfigShape

package/src/host/prompt.ts

@@ -180,29 +180,48 @@ export function escapePromptBraces(text: string): string {
   return text.replace(/\{(?=\{)/g, '{\u200B')
 }
 
-/** Governance block: how to write without clobbering human edits. */
-const WRITE_RULES = `### 写入与并发
-- 覆盖或删除已有笔记前先 \`tiddlywiki_get\` 读一次，把读到的 \`modified\`（或 \`revision\`）作为 \`expectedModified\`（或 \`expectedRevision\`）传回去；若期间有人（在 TW 编辑器里）改过，写入会被拒绝并告诉你当前值——此时重新读一遍再决定，**不要用 \`force\` 硬覆盖**。\`tiddlywiki_attach\` 对同名已有条目默认拒绝写入，理由相同（要覆盖得显式 \`force: true\`）。
-- 纯增量内容（日志、批注、清单）优先用 \`tiddlywiki_append\`，不必读全文。
-- 覆盖既有条目时**不传 \`tags\` 就保留原有标签、自定义字段与内容类型**（只改正文）；显式传 \`tags\` 才整体替换标签，要改内容类型用 \`fields.type\`。
-- 内容类型：新笔记默认写成 Markdown（工具自动补 \`text/markdown\`，\`$:/\` 系统条目除外）；覆盖或追加既有条目时保留它原有的 \`type\`。要写 TW 原生 wikitext 才显式传 \`fields: {"type":"text/vnd.tiddlywiki"}\`。⚠️ \`fields.type\` 是 TW 的**内容类型**保留字段，业务分类请放 \`tags\`。`
+/**
+ * Governance block: how to write without clobbering human edits.
+ *
+ * v0.29.0 — TRIMMED TO THE PART THE SCHEMAS CANNOT SAY.
+ *
+ * This block used to restate `tiddlywiki_put` / `append` / `batch_put` / `attach`
+ * nearly sentence for sentence: tags/fields/type preservation, `tags: []` meaning
+ * "clear", the markdown default for new notes, `fields.type` being TW's content
+ * type. All of that is ALREADY in those tools' descriptions — which the model
+ * receives on every request — and this section's own intro tells it that the
+ * schemas are the contract. Two copies of one rule is not redundancy insurance,
+ * it is a second thing to keep in sync (the exact drift that v0.21.0 removed).
+ *
+ * What is left is the one thing no schema states: after a refused write, read
+ * again instead of forcing. `scripts/verify-prompt.mjs` now asserts the delegated
+ * rules on the SCHEMA side, so deleting them here can never lose them silently.
+ */
+const WRITE_RULES = `### 写入约定
+- 覆盖或删除已有笔记前先 \`tiddlywiki_get\` 读一次，并把读到的 \`expectedModified\`（或 \`expectedRevision\`）传回去；被拒绝说明刚有人（在 TW 编辑器里）改过——**重读一遍再决定，不要用 \`force\` 硬覆盖**。`
 
 /** Governance block: the three-step git discipline + conflict recovery. */
-const SYNC_RULES = `### 同步纪律（三条）
-1. 开工先 pull：\`tiddlywiki_git_sync action=pull\`（rebase + autostash；真冲突会自动 abort 并报冲突文件）。
-2. 收工 commit + push：\`tiddlywiki_git_sync action=sync\`（pull → commit → push）。
-3. 插件会自动防抖 commit（默认 60s），需要立刻同步时用上面的工具。
-pull 冲突后：先 \`tiddlywiki_git_resolve files=[冲突文件] strategy=keep-local\`（保留本地）或 \`strategy=keep-remote\`（改用远端版本），再重新 pull/sync 整合其余改动。`
+const SYNC_RULES = `### 同步纪律
+- 开工先 \`tiddlywiki_git_sync action=pull\`，收工 \`action=sync\`（插件另会防抖自动 commit，默认 60s）。
+- pull 冲突：先 \`tiddlywiki_git_resolve files=[冲突文件] strategy=keep-local\`（保留本地）或 \`keep-remote\`，再重新 pull/sync 整合其余改动。`
 
-/** Governance block: knowledge-base conventions (tags, memory, links). */
+/**
+ * Governance block: knowledge-base conventions (tags, memory, links).
+ *
+ * v0.29.0 — the 「工作区标记自动打」 bullet and the 「检索先窄后宽 / 多词 AND」
+ * bullet were REMOVED here because `tiddlywiki_put` and `tiddlywiki_search` already
+ * document them verbatim (see verify-prompt.mjs, which now asserts them on the
+ * schema side). What stays is what only this section can say: what a note IS for
+ * (long-term memory), the todo convention, time-boxing/supersession fields, the
+ * `human-edited` counterpart to the automatic `agent-written`, and the clickable
+ * link format.
+ */
 const NOTE_RULES = `### 笔记约定
 - wiki 是长期记忆：会议纪要、决策记录、调研笔记、随手的想法都存成独立 tiddler（tag 用 inbox/meeting/decision 等便于检索）。
-- **值得做但不在当前范围内的想法**：用 \`tiddlywiki_put\` 写成独立 tiddler、打 \`todo\`，正文简述来源（会话 / 工作区 / 项目背景），由用户决定是否继续。
-- **工作区标记自动打**：新建笔记自动带 \`ws/<项目名>\` 标签与 \`workspace\` 字段（取自会话工作目录），**不要手动再加**；只有内容显然属于**另一个**项目时才显式写 \`workspace\` 字段。
-- **检索先窄后宽**：\`tiddlywiki_search\` 先在工作区内查、没命中才自动扩到全库，回执写明实际范围——**「工作区内 0 条」不等于库里没有**。查询按空白切词、**全部词命中**才算（AND）。
-- **阶段性内容标时效**：会过期的笔记（版本记录 / 部署步骤 / 排期 / 临时方案 / 一次性口令）写时带 \`valid-until: YYYY-MM-DD\`（硬过期）或 \`review-after: YYYY-MM-DD\`（该复查）；被取代时写 \`superseded-by: [[新笔记]]\` 并打 \`superseded\` 标签、**保留旧笔记**。**淘汰只由人决定**，不要自行删除。
+- **值得做但不在当前范围内的想法**：写成独立 tiddler、打 \`todo\`，正文简述来源（会话 / 工作区 / 项目背景），由用户决定是否继续。
+- **阶段性内容标时效**：会过期的笔记带 \`valid-until: YYYY-MM-DD\`（硬过期）或 \`review-after: YYYY-MM-DD\`（该复查）；被取代时写 \`superseded-by: [[新笔记]]\` 并打 \`superseded\` 标签、**保留旧笔记**。**淘汰只由人决定**，不要自行删除。
 - \`agent-written\` 由工具自动补打，别手动加或删；人类编辑过 Agent 笔记后补 \`human-edited\`。
-- **引用笔记用可点击链接**：\`[标题](/dsh-tiddlywiki/tw/#标题)\`（空格等特殊字符做 URL 编码；中文可直写）。点击会打开中央 TW 面板并跳转，优先用它代替纯文本标题。`
+- **引用笔记用可点击链接**：\`[标题](/dsh-tiddlywiki/tw/#标题)\`（空格等特殊字符做 URL 编码；中文可直写）。点它会打开中央 TW 面板并跳转，优先用它代替纯文本标题。`
 
 /**
  * Publish-metadata rule, appended ONLY when `wechat.enabled` is on (v0.23.0).
@@ -233,11 +252,20 @@ export function toolSignatureLines(tools: readonly PromptToolSummary[], bullet =
   })
 }
 
-/** Heading + a one-line capability pointer (slim intro). */
+/**
+ * Heading + a one-line capability pointer (slim intro).
+ *
+ * v0.29.0 — the hand-written CATEGORY LIST ("检索/读写/批量/增量追加/重命名…") is
+ * gone. Only the COUNT was derived from the live registry, so adding or renaming a
+ * tool silently made that sentence wrong, and `verify-prompt.mjs` could not see it
+ * (it asserts there is no signature catalogue, not that this list is current). The
+ * tools themselves are described in full by their schemas, which the model always
+ * has; a second, unmaintainable summary of them is exactly what v0.21.0 removed.
+ */
 function slimIntro(count: number): string {
   return `## TiddlyWiki 持久知识库
 
-本机有一个 TiddlyWiki 5 持久知识库（wiki 文件夹即 git 仓库）。插件提供 ${count} 个 \`tiddlywiki_*\` 工具：检索/读写/批量/增量追加/重命名/删除与回收站/反向链接/附件/体检/git 同步与冲突解决。**参数与返回契约以各工具 schema 的 description 为准**，本段只补充 schema 表达不了的约定。`
+本机有一个 TiddlyWiki 5 持久知识库（wiki 文件夹即 git 仓库）。插件提供 ${count} 个 \`tiddlywiki_*\` 工具：**参数与返回契约以各工具 schema 的 description 为准**，本段只补充 schema 表达不了的约定。`
 }
 
 /** Heading + the generated signature catalogue (full intro). */