dsh-tiddlywiki 0.1.2 → 0.2.1

package/src/client/panel.ts

@@ -79,6 +79,7 @@ interface StatusPayload {
   wikiPath?: string
   error?: string
   note?: { tag?: string }
+  ui?: { showPanelStatus?: boolean }
 }
 
 function conversationColumn(): HTMLElement | undefined {
@@ -115,6 +116,8 @@ export function mountPanel(state: PanelState): () => void {
   let frameArea: HTMLDivElement | undefined
   let errorArea: HTMLDivElement | undefined
   let chip: HTMLSpanElement | undefined
+  let statusDot: HTMLSpanElement | undefined
+  let statusFloater: HTMLDivElement | undefined
   let refreshTimer: number | undefined
   let refreshAttempts = 0
 
@@ -123,27 +126,6 @@ export function mountPanel(state: PanelState): () => void {
     view.dataset.dshTwView = ''
     view.className = 'dsh-tw-view'
 
-    const bar = document.createElement('div')
-    bar.className = 'dsh-tw-panel-bar'
-    const title = document.createElement('span')
-    title.className = 'dsh-tw-panel-title'
-    title.textContent = 'TiddlyWiki 知识库'
-    chip = document.createElement('span')
-    chip.className = 'dsh-tw-status-chip'
-    chip.dataset.state = 'unknown'
-    chip.textContent = '—'
-    const reload = document.createElement('button')
-    reload.type = 'button'
-    reload.textContent = '重载'
-    reload.addEventListener('click', () => {
-      if (iframe !== undefined && !iframe.hidden) iframe.src = iframe.src
-    })
-    const refresh = document.createElement('button')
-    refresh.type = 'button'
-    refresh.textContent = '状态'
-    refresh.addEventListener('click', () => { void doRefresh() })
-    bar.append(title, chip, refresh, reload)
-
     frameArea = document.createElement('div')
     frameArea.className = 'dsh-tw-panel-frame-wrap'
     frameArea.style.cssText = 'flex:1;min-height:0;display:flex;flex-direction:column'
@@ -157,14 +139,50 @@ export function mountPanel(state: PanelState): () => void {
     errorArea.className = 'dsh-tw-panel-error'
     errorArea.hidden = true
 
-    view.append(bar, frameArea, errorArea)
+    view.append(frameArea, errorArea)
     return view
   }
 
+  /**
+   * Bottom-right floating status/reload buttons (same visual language as the
+   * quick-note toggle) — the top panel bar is gone, so TW's menubar reaches
+   * the very top of the panel and clears the host's top-right buttons. Mount
+   * is gated by `ui.showPanelStatus` (settings page toggle).
+   */
+  const buildStatusFloater = (): HTMLDivElement => {
+    const wrap = document.createElement('div')
+    wrap.className = 'dsh-tw-panel-status'
+
+    const statusBtn = document.createElement('button')
+    statusBtn.type = 'button'
+    statusBtn.className = 'dsh-tw-panel-status-btn'
+    statusBtn.title = '刷新状态'
+    statusDot = document.createElement('span')
+    statusDot.className = 'dsh-tw-status-dot'
+    statusDot.dataset.state = 'unknown'
+    chip = document.createElement('span')
+    chip.className = 'dsh-tw-panel-status-text'
+    chip.textContent = '—'
+    statusBtn.append(statusDot, chip)
+    statusBtn.addEventListener('click', () => { void doRefresh() })
+
+    const reloadBtn = document.createElement('button')
+    reloadBtn.type = 'button'
+    reloadBtn.className = 'dsh-tw-panel-status-btn'
+    reloadBtn.textContent = '重载'
+    reloadBtn.title = '重载 TiddlyWiki 面板'
+    reloadBtn.addEventListener('click', () => {
+      if (iframe !== undefined && !iframe.hidden) iframe.src = iframe.src
+    })
+
+    wrap.append(statusBtn, reloadBtn)
+    document.body.append(wrap)
+    return wrap
+  }
+
   const setChip = (stateName: string, text: string): void => {
-    if (chip === undefined) return
-    chip.dataset.state = stateName
-    chip.textContent = text
+    if (statusDot !== undefined) statusDot.dataset.state = stateName
+    if (chip !== undefined) chip.textContent = text
   }
 
   /** Pin the overlay to the center column's current viewport rect. */
@@ -329,6 +347,13 @@ export function mountPanel(state: PanelState): () => void {
   ensure()
   applyActive()
 
+  // Bottom-right status/reload buttons, gated by ui.showPanelStatus.
+  void (async () => {
+    const payload = await fetchStatus()
+    if (payload?.ui?.showPanelStatus === false) return
+    statusFloater = buildStatusFloater()
+  })()
+
   return () => {
     if (refreshTimer !== undefined) window.clearTimeout(refreshTimer)
     window.clearInterval(syncInterval)
@@ -341,5 +366,6 @@ export function mountPanel(state: PanelState): () => void {
     unsubscribe()
     document.documentElement.removeAttribute(ACTIVE_ATTR)
     container?.remove()
+    statusFloater?.remove()
   }
 }

package/src/client/settings-page.ts

@@ -146,6 +146,7 @@ function renderConfigSection(body: HTMLElement, config: Record<string, unknown>,
   section.append(make('h3', 'dsh-tw-settings-h', '常规配置'))
   const note = (config.note ?? {}) as Record<string, unknown>
   const git = (config.git ?? {}) as Record<string, unknown>
+  const ui = (config.ui ?? {}) as Record<string, unknown>
   const fields: ConfigField[] = []
 
   const textField = (key: string, label: string, initial: string): void => {
@@ -180,6 +181,8 @@ function renderConfigSection(body: HTMLElement, config: Record<string, unknown>,
   numField('git.debounceMs', '自动 commit 防抖(ms)', typeof git.debounceMs === 'number' ? git.debounceMs : 60_000)
   textField('git.remote', 'git 远端（空=仅本地）', typeof git.remote === 'string' ? git.remote : '')
   textField('git.branch', 'git 分支', typeof git.branch === 'string' ? git.branch : 'main')
+  checkField('ui.showQuickNote', '显示「快速笔记」悬浮按钮', ui.showQuickNote !== false)
+  checkField('ui.showPanelStatus', '显示 TW 面板右下角「状态/重载」悬浮按钮', ui.showPanelStatus !== false)
   // 界面语言在下方「语言管理」区块设置（config 的 uiLanguage 仅供启动时自动应用）。
 
   const save = make('button', 'dsh-tw-settings-btn dsh-tw-settings-primary', '保存配置')

package/src/client/styles.ts

@@ -24,6 +24,21 @@ const CSS_TEXT = `
 .dsh-tw-entry[data-active="true"] { background: var(--dsw-alias-interactive-bg-active, rgba(128,128,128,.18)); color: var(--dsw-alias-label-primary, inherit); font-weight: 500; }
 .dsh-tw-entry svg { flex: none; }
 .dsh-tw-entry .dsh-tw-entry-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+/* Collapsed rail: the shell narrows the sidebar to a 56px icon rail (dual
+   signals — the frame's data-sidebar-collapsed + the sidebar root's hashed
+   *_collapsed class, same doctrine as dsh-taskboard 0.4.3). Mirror the
+   native 36×36 icon-button geometry: center the icon, hide the label, and
+   scale it up to match the shell's 18px rail icons. */
+[data-sidebar-collapsed] [data-dsh-tw-entry],
+[class*="_collapsed"] [data-dsh-tw-entry] {
+  width: 36px; height: 36px; min-width: 36px;
+  margin: 0 0 12px; padding: 0;
+  justify-content: center; gap: 0; text-align: center;
+}
+[data-sidebar-collapsed] [data-dsh-tw-entry] .dsh-tw-entry-label,
+[class*="_collapsed"] [data-dsh-tw-entry] .dsh-tw-entry-label { display: none; }
+[data-sidebar-collapsed] [data-dsh-tw-entry] svg,
+[class*="_collapsed"] [data-dsh-tw-entry] svg { width: 18px; height: 18px; }
 
 /* ── center-column panel (fixed overlay, JS-pinned to the column rect) ── */
 .dsh-tw-view {
@@ -36,31 +51,31 @@ html[data-dsh-tw-active] [data-pane="conversation"] > :not([data-dsh-tw-view]),
 html[data-dsh-tw-active] [class*="centerCol"] > :not([data-dsh-tw-view]),
 html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view]) { display: none !important; }
 
-.dsh-tw-panel-bar {
-  display: flex; align-items: center; gap: 8px; padding: 6px 10px;
-  border-bottom: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.18));
-  background: var(--dsw-alias-bg-layer-1, transparent);
-  font-size: 12px; color: var(--dsw-alias-label-secondary, inherit);
-  flex: none;
-}
-.dsh-tw-panel-bar button {
-  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.25));
-  background: transparent; color: inherit; font: inherit; font-size: 12px;
-  padding: 2px 8px; border-radius: 6px; cursor: pointer;
-}
-.dsh-tw-panel-bar button:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
-.dsh-tw-panel-title { font-weight: 600; margin-right: auto; }
-/* dsh-better-sidebar coexistence: the floating toggle cluster (two 28px
-   buttons at the viewport's top-right) lives above the panel (z-index is
-   handled in JS — the panel stays below the host layer), so reserve the
-   cluster's width at the panel bar's right end — mirroring how
-   dsh-better-sidebar pads the DSH session header — and the panel's own
-   状态/重载 buttons never sit underneath it. */
-.dsh-tw-view[data-sidebar-host] .dsh-tw-panel-bar { padding-right: 80px; }
-.dsh-tw-status-chip { font-variant-numeric: tabular-nums; }
-.dsh-tw-status-chip[data-state="running"] { color: var(--dsw-alias-state-success-primary, #3eaa5f); }
-.dsh-tw-status-chip[data-state="starting"] { color: var(--dsw-alias-state-warning-primary, #d9822b); }
-.dsh-tw-status-chip[data-state="failed"], .dsh-tw-status-chip[data-state="stopped"] { color: var(--dsw-alias-state-error-primary, #d13b3b); }
+/* ── bottom-right status / reload floating buttons ───────────────────
+   The top panel bar (title + status + reload row) is gone so TW's menubar
+   reaches the panel top; status/reload now live here as floating buttons,
+   same visual language as the quick-note toggle. The ui.showPanelStatus
+   setting controls whether they mount at all. */
+.dsh-tw-panel-status {
+  /* 状态/重载悬浮按钮：右对齐到与快速笔记按钮同一条竖线（right:24），
+     垂直排在快速笔记按钮（bottom:88，高约 38px）上方；
+     两个按钮竖直依次排列（状态在上、重载在下），与其他插件按钮列对齐、不堆叠。 */
+  position: fixed; right: 24px; bottom: 140px; z-index: 950;
+  display: flex; flex-direction: column; align-items: flex-end; gap: 8px;
+}
+.dsh-tw-panel-status-btn {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  font: inherit; font-size: 12px; padding: 7px 12px; border-radius: 999px;
+  box-shadow: var(--dsw-shadow-lv3, 0 4px 16px rgba(0,0,0,.16)); cursor: pointer;
+  display: inline-flex; align-items: center; gap: 6px;
+  transition: background-color 120ms ease;
+}
+.dsh-tw-panel-status-btn:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.1)); }
+.dsh-tw-status-dot { width: 8px; height: 8px; border-radius: 50%; background: #999; flex: none; }
+.dsh-tw-status-dot[data-state="running"] { background: var(--dsw-alias-state-success-primary, #3eaa5f); }
+.dsh-tw-status-dot[data-state="starting"] { background: var(--dsw-alias-state-warning-primary, #d9822b); }
+.dsh-tw-status-dot[data-state="failed"], .dsh-tw-status-dot[data-state="stopped"] { background: var(--dsw-alias-state-error-primary, #d13b3b); }
 
 .dsh-tw-panel-frame { flex: 1; min-height: 0; border: 0; width: 100%; display: block; background: #fff; }
 /* [hidden] must beat the author display rules above (UA hidden is overridden). */
@@ -139,6 +154,34 @@ html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view
 }
 .dsh-tw-note-edit:hover:not(:disabled) { filter: brightness(.96); }
 .dsh-tw-note-edit:disabled { opacity: .55; cursor: default; }
+/* ── Multi-tag chip editor (quick-note tags) ─────────────────────────────── */
+.dsh-tw-note-tags { position: relative; flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 4px; }
+.dsh-tw-note-chips { display: flex; flex-wrap: wrap; gap: 4px; }
+.dsh-tw-note-tagchip {
+  display: inline-flex; align-items: center; gap: 4px;
+  padding: 2px 6px 2px 8px; border-radius: 999px; font-size: 11px; line-height: 1.4;
+  background: color-mix(in srgb, var(--dsw-alias-brand-primary, #3e63dd) 10%, var(--dsw-alias-bg-layer-1, #fff));
+  border: 1px solid color-mix(in srgb, var(--dsw-alias-brand-primary, #3e63dd) 30%, transparent);
+  color: var(--dsw-alias-label-primary, #222);
+}
+.dsh-tw-note-tagchip-x {
+  cursor: pointer; font-size: 12px; line-height: 1; padding: 0 2px; border-radius: 50%;
+  color: var(--dsw-alias-label-secondary, #888);
+}
+.dsh-tw-note-tagchip-x:hover { color: var(--dsw-alias-state-error-primary, #d13b3b); }
+.dsh-tw-note-taginput { width: 100%; box-sizing: border-box; }
+.dsh-tw-note-tagsuggest {
+  position: absolute; left: 0; right: 0; top: calc(100% + 2px); z-index: 60;
+  max-height: 168px; overflow-y: auto; border-radius: 8px; padding: 4px;
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  box-shadow: var(--dsw-shadow-lv2, 0 4px 16px rgba(0,0,0,.16));
+  font-size: 12px;
+}
+.dsh-tw-note-tagsuggest-item {
+  padding: 6px 9px; border-radius: 6px; cursor: pointer; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.dsh-tw-note-tagsuggest-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
 /* ── Native-editor popup iframe (quick-note "在 TW 中编辑") ──────────────── */
 .dsh-tw-editor-popup {
   position: fixed; left: 0; right: 0; top: 0; bottom: 0; margin: auto;

package/src/host/config.ts

@@ -20,6 +20,12 @@ export const CONFIG_TIDDLER = '$:/plugins/dsh-tiddlywiki/config'
 export interface PluginConfigShape {
   note?: { tag?: string }
   git?: { autoCommit?: boolean; debounceMs?: number; remote?: string; branch?: string }
+  ui?: {
+    /** 是否在界面右下角显示「快速笔记」悬浮按钮（默认 true）。 */
+    showQuickNote?: boolean
+    /** 是否显示 TW 面板右下角的「状态/重载」悬浮按钮（默认 true）。 */
+    showPanelStatus?: boolean
+  }
   uiLanguage?: string
   [key: string]: unknown
 }

package/src/host/routes.ts

@@ -39,6 +39,7 @@ export interface RouteDeps {
   git: GitFace
   autoCommit: () => void
   noteDefaults: () => { tag: string }
+  uiDefaults: () => { showQuickNote: boolean; showPanelStatus: boolean }
   getWikiPath: () => string
 }
 
@@ -86,10 +87,10 @@ export async function openInTwEditor(
   client: TiddlyWebClient,
   title: string,
   text: string,
-  tag: string,
+  tags: string[],
 ): Promise<{ title: string; draftTitle: string }> {
   if (text.trim().length > 0) {
-    await client.put({ title, text, tags: [tag] })
+    await client.put({ title, text, tags })
   }
   // Draft content: the provided text, else the existing tiddler's content.
   let draftText = text
@@ -115,6 +116,22 @@ export async function openInTwEditor(
   return { title, draftTitle }
 }
 
+/** Resolve note tags from the request body: `tags` array wins, then the
+ *  legacy single `tag` string, then the configured default tag. */
+function resolveTags(
+  body: { tag?: unknown; tags?: unknown },
+  defaultTag: string,
+): string[] {
+  if (Array.isArray(body.tags)) {
+    const tags = body.tags.filter((t): t is string => typeof t === 'string' && t.trim().length > 0).map((t) => t.trim())
+    if (tags.length > 0) return tags
+  }
+  if (typeof body.tag === 'string' && body.tag.trim().length > 0) {
+    return body.tag.trim().split(/\s+/).filter(Boolean)
+  }
+  return [defaultTag]
+}
+
 export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDeps): () => void {
   const handleStatus = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
     const view = deps.server.status()
@@ -124,12 +141,12 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     } catch {
       gitSummary = null
     }
-    json(res, { ok: true, ...view, git: gitSummary, note: { tag: deps.noteDefaults().tag } })
+    json(res, { ok: true, ...view, git: gitSummary, note: { tag: deps.noteDefaults().tag }, ui: deps.uiDefaults() })
   }
 
   const handleNote = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
-      const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; text?: unknown }
+      const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; tags?: unknown; text?: unknown }
       const text = typeof body.text === 'string' && body.text.trim().length > 0 ? body.text.trim() : null
       if (text === null) {
         json(res, { ok: false, error: 'text is required' }, 400)
@@ -141,10 +158,10 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
         return
       }
       const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : timestampTitle()
-      const tag = typeof body.tag === 'string' && body.tag.trim().length > 0 ? body.tag.trim() : deps.noteDefaults().tag
-      await client.put({ title, text, tags: [tag] })
+      const tags = resolveTags(body, deps.noteDefaults().tag)
+      await client.put({ title, text, tags })
       deps.autoCommit()
-      json(res, { ok: true, title, tag, text })
+      json(res, { ok: true, title, tag: tags.join(' '), tags, text })
     } catch (err) {
       json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
     }
@@ -152,16 +169,16 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
 
   const handleEdit = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
-      const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; text?: unknown }
+      const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; tags?: unknown; text?: unknown }
       const client = deps.getClient()
       if (client === undefined) {
         json(res, { ok: false, error: 'wiki service is not running' }, 503)
         return
       }
       const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : timestampTitle()
-      const tag = typeof body.tag === 'string' && body.tag.trim().length > 0 ? body.tag.trim() : deps.noteDefaults().tag
+      const tags = resolveTags(body, deps.noteDefaults().tag)
       const text = typeof body.text === 'string' ? body.text : ''
-      const result = await openInTwEditor(client, title, text, tag)
+      const result = await openInTwEditor(client, title, text, tags)
       deps.autoCommit()
       json(res, { ok: true, ...result, twUrl: deps.server.url })
     } catch (err) {
@@ -169,6 +186,27 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
   }
 
+  /** Distinct non-system tags for the quick-note tag autocomplete. */
+  const handleTags = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const client = deps.getClient()
+    if (client === undefined) {
+      json(res, { ok: false, error: 'wiki service is not running' }, 503)
+      return
+    }
+    try {
+      const items = await client.list(undefined, false)
+      const tags = new Set<string>()
+      for (const item of items) {
+        for (const tag of item.tags ?? []) {
+          if (tag.length > 0 && !tag.startsWith('$:/')) tags.add(tag)
+        }
+      }
+      json(res, { ok: true, tags: [...tags].sort((a, b) => a.localeCompare(b, 'zh')) })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
   const handleRestart = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       await deps.server.restart()
@@ -212,6 +250,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/status`, handler: (req, res) => { void handleStatus(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/note`, handler: (req, res) => { void handleNote(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/edit`, handler: (req, res) => { void handleEdit(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/tags`, handler: (req, res) => { void handleTags(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
     ctx.webServer.register({ kind: 'prefix', path: `${ROUTE_PREFIX}/api`, handler: (req, res) => { void handleApiProxy(req, res) } }),
   ]

package/src/host/seed-notes.ts

@@ -1,62 +1,79 @@
-/**
- * Built-in doc note for the plugin (design doc §14): a short user-facing
- * "how to use dsh-tiddlywiki" note that is seeded into the wiki on first run.
- *
- * Idempotent seed (create-if-missing): on every plugin start we check whether
- * the note tiddler exists and only write it when it is absent — deleting it
- * and restarting dsh web recreates it, but editing it never gets overwritten.
- *
- * @module dsh-tiddlywiki/host/seed-notes
- */
-import type { TiddlyWebClient } from './tw-api.ts'
-
-/** Note tiddler title (a normal, searchable note — not a system tiddler). */
-export const DOC_NOTE_TITLE = 'dsh-tiddlywiki 插件说明'
-
-/** Tag that makes the note easy to find via `tiddlywiki_search tag=docs`. */
-export const DOC_NOTE_TAG = 'docs'
-
-/** The note body, TiddlyWiki wiki-text. */
-export const DOC_NOTE_TEXT = `! dsh-tiddlywiki 插件说明
-
-本插件把 **TiddlyWiki 5** 作为 DSH 的持久知识库（wiki 文件夹本身就是一个 git 仓库，随内容自动提交/同步）。
-
-!! 它能做什么
-
-* **5 个 agent 工具**：\`tiddlywiki_search\`（检索）/ \`tiddlywiki_get\`（读）/ \`tiddlywiki_put\`（写）/ \`tiddlywiki_delete\`（删）/ \`tiddlywiki_git_sync\`（git 同步）。
-* **TW 编辑器面板**：侧边栏「TiddlyWiki」按钮 → 在界面中央打开完整版 TW 编辑器。
-* **快速笔记**：右下角悬浮「📝 快速笔记」写随手记，\`Ctrl+Enter\` 保存；点「✏️ 在 TW 中编辑」会弹出独立小窗用 TW 原生编辑器编辑。
-* **git 同步**：写入自动防抖 commit（默认 60 秒）；手动 \`tiddlywiki_git_sync action=sync\` 做 pull → commit → push。
-* **设置页**：DSH 设置 → 「TiddlyWiki 知识库」管理插件/主题/语言与运行配置。
-
-!! 知识库纪律（三条）
-
-1. 开工先 \`tiddlywiki_git_sync action=pull\`（rebase + autostash，真冲突会自动 abort 并报文件）。
-2. 收工 \`tiddlywiki_git_sync action=sync\`。
-3. 插件自动 commit 兜底，手动 sync 用于需要主动推送的场合。
-
-!! 主题与语言
-
-* **主题**分两层：每行一个「☑ 加载」（多选 = TW 里可用的主题，依赖链自动带上）和「◉ 活动」（单选 = 当前视觉主题）。应用后自动重启 TW。
-* **语言**：设置页勾选 \`zh-Hans\`（简体）并应用，TW 界面即切换为中文。
-
-!! 说明
-
-* 本笔记由插件在首次启动时自动写入 wiki（幂等：不存在才写）。删除后重启 dsh web 会重建；手动编辑过的内容不会被覆盖。
-* 更多细节见插件仓库 README。`
-
-/**
- * Seed the doc note when it is absent. Returns whether a note was written.
- * Never throws (missing wiki or note already present → no-op / false).
- */
-export async function seedDocNote(client: TiddlyWebClient): Promise<boolean> {
-  const existing = await client.get(DOC_NOTE_TITLE).catch(() => undefined)
-  if (existing !== undefined) return false
-  await client.put({
-    title: DOC_NOTE_TITLE,
-    text: DOC_NOTE_TEXT,
-    type: 'text/vnd.tiddlywiki',
-    tags: [DOC_NOTE_TAG],
-  })
-  return true
-}
+/**
+ * Built-in doc note for the plugin (design doc §14): a short user-facing
+ * "how to use dsh-tiddlywiki" note seeded into the wiki the first time the
+ * plugin runs on a wiki.
+ *
+ * ONE-SHOT seed: a marker tiddler (`seed-doc-note`) records that the note has
+ * been offered once; after that the note is the user's own content — deleting
+ * it and restarting dsh web does NOT recreate it, and edits are never
+ * overwritten.
+ *
+ * @module dsh-tiddlywiki/host/seed-notes
+ */
+import type { TiddlyWebClient } from './tw-api.ts'
+
+/** Note tiddler title (a normal, searchable note — not a system tiddler). */
+export const DOC_NOTE_TITLE = 'dsh-tiddlywiki 插件说明'
+
+/** Tag that makes the note easy to find via `tiddlywiki_search tag=docs`. */
+export const DOC_NOTE_TAG = 'docs'
+
+/** One-time marker: its presence means "the note was offered once — hands off". */
+export const SEED_MARKER_TITLE = '$:/plugins/dsh-tiddlywiki/seed-doc-note'
+
+/** The note body, TiddlyWiki wiki-text. */
+export const DOC_NOTE_TEXT = `! dsh-tiddlywiki 插件说明
+
+本插件把 **TiddlyWiki 5** 作为 DSH 的持久知识库（wiki 文件夹本身就是一个 git 仓库，随内容自动提交/同步）。
+
+!! 它能做什么
+
+* **5 个 agent 工具**：\`tiddlywiki_search\`（检索）/ \`tiddlywiki_get\`（读）/ \`tiddlywiki_put\`（写）/ \`tiddlywiki_delete\`（删）/ \`tiddlywiki_git_sync\`（git 同步）。
+* **TW 编辑器面板**：侧边栏「TiddlyWiki」按钮 → 在界面中央打开完整版 TW 编辑器。
+* **快速笔记**：右下角悬浮「📝 快速笔记」写随手记（可多选/自动补全 tag），\`Ctrl+Enter\` 保存；点「✏️ 在 TW 中编辑」会弹出独立小窗用 TW 原生编辑器编辑。
+* **git 同步**：写入自动防抖 commit（默认 60 秒）；手动 \`tiddlywiki_git_sync action=sync\` 做 pull → commit → push。
+* **设置页**：DSH 设置 → 「TiddlyWiki 知识库」管理插件/主题/语言与运行配置（含「快速笔记」显示开关、面板「状态/重载」悬浮按钮开关）。
+
+!! 知识库纪律（三条）
+
+1. 开工先 \`tiddlywiki_git_sync action=pull\`（rebase + autostash，真冲突会自动 abort 并报文件）。
+2. 收工 \`tiddlywiki_git_sync action=sync\`。
+3. 插件自动 commit 兜底，手动 sync 用于需要主动推送的场合。
+
+!! 主题与语言
+
+* **主题**分两层：每行一个「☑ 加载」（多选 = TW 里可用的主题，依赖链自动带上）和「◉ 活动」（单选 = 当前视觉主题）。应用后自动重启 TW。
+* **语言**：设置页勾选 \`zh-Hans\`（简体）并应用，TW 界面即切换为中文。
+
+!! 说明
+
+* 本笔记由插件在**首次启动**时自动写入（一次性：只写一次）。删除后重启 dsh web **不会自动恢复**——它从此归你所有。
+* 更多细节见插件仓库 README。`
+
+/**
+ * Seed the doc note exactly once per wiki. A marker tiddler records that the
+ * note has been offered; from then on the note is user-owned and is never
+ * re-created (deleting it survives restarts). Returns whether a note was
+ * written this call. Never throws.
+ */
+export async function seedDocNote(client: TiddlyWebClient): Promise<boolean> {
+  const marker = await client.get(SEED_MARKER_TITLE).catch(() => undefined)
+  if (marker !== undefined) return false
+  const existing = await client.get(DOC_NOTE_TITLE).catch(() => undefined)
+  let wrote = false
+  if (existing === undefined) {
+    await client.put({
+      title: DOC_NOTE_TITLE,
+      text: DOC_NOTE_TEXT,
+      type: 'text/vnd.tiddlywiki',
+      tags: [DOC_NOTE_TAG],
+    })
+    wrote = true
+  }
+  // Record the offer regardless, so an existing note (upgrade from an older
+  // create-if-missing version) also becomes user-owned from here on.
+  await client
+    .put({ title: SEED_MARKER_TITLE, text: 'seeded-once', type: 'text/plain', tags: [] })
+    .catch(() => undefined)
+  return wrote
+}

package/src/index.ts

@@ -55,6 +55,7 @@ export interface TiddlywikiConfig {
   port?: number
   git?: { autoCommit?: boolean; debounceMs?: number; remote?: string; branch?: string }
   note?: { tag?: string }
+  ui?: { showQuickNote?: boolean; showPanelStatus?: boolean }
   auth?: { username?: string; password?: string }
 }
 
@@ -75,6 +76,7 @@ interface ResolvedConfig {
   port: number
   git: { autoCommit: boolean; debounceMs: number; remote: string; branch: string }
   note: { tag: string }
+  ui: { showQuickNote: boolean; showPanelStatus: boolean }
   auth: { username?: string; password?: string }
 }
 
@@ -84,6 +86,7 @@ const DEFAULTS: ResolvedConfig = {
   port: 0,
   git: { autoCommit: true, debounceMs: 60_000, remote: '', branch: 'main' },
   note: { tag: 'inbox' },
+  ui: { showQuickNote: true, showPanelStatus: true },
   auth: { username: '', password: '' },
 }
 
@@ -163,6 +166,7 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
     port: rawConfig.port ?? DEFAULTS.port,
     git: { ...DEFAULTS.git, ...(rawConfig.git ?? {}) },
     note: { ...DEFAULTS.note, ...(rawConfig.note ?? {}) },
+    ui: { ...DEFAULTS.ui, ...(rawConfig.ui ?? {}) },
     auth: { ...DEFAULTS.auth, ...(rawConfig.auth ?? {}) },
   }
   const wikiPath = join(config.wikiRoot, config.wiki)
@@ -171,12 +175,16 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
   // Runtime-editable config (settings page): the cordis `config:` block is the
   // BASE; a config tiddler ($:/plugins/dsh-tiddlywiki/config) written by the
   // settings page overlays it. Effective values come from configStore.get().
-  const configStore = new ConfigStore({ note: config.note, git: config.git } satisfies PluginConfigShape)
+  const configStore = new ConfigStore({ note: config.note, git: config.git, ui: config.ui } satisfies PluginConfigShape)
   const eff = (): PluginConfigShape => configStore.get()
   const effectiveNoteTag = (): string => {
     const tag = eff().note?.tag
     return typeof tag === 'string' && tag.trim().length > 0 ? tag : config.note.tag
   }
+  const effectiveUi = (): { showQuickNote: boolean; showPanelStatus: boolean } => ({
+    showQuickNote: eff().ui?.showQuickNote !== false,
+    showPanelStatus: eff().ui?.showPanelStatus !== false,
+  })
 
   const disposers: Array<() => void> = []
   const disposeAll = (): void => {
@@ -265,11 +273,14 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
     try {
       await server.start()
       await configStore.load(client())
-      // Seed the built-in doc note (idempotent, create-if-missing) so a fresh
-      // wiki gets the plugin guide by default.
+      // Seeds (run after the effective config is loaded):
+      //  - doc note: ONE-SHOT — a fresh wiki gets the plugin guide; deleting
+      //    it afterwards survives restarts (see seedDocNote).
       try {
         const seedClient = client()
-        if (seedClient !== undefined) await seedDocNote(seedClient)
+        if (seedClient !== undefined) {
+          await seedDocNote(seedClient)
+        }
       } catch (err) {
         console.warn('[dsh-tiddlywiki] seeding doc note:', err)
       }
@@ -307,6 +318,7 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
       git,
       autoCommit: () => committer?.touch(),
       noteDefaults: () => ({ tag: effectiveNoteTag() }),
+      uiDefaults: () => effectiveUi(),
       getWikiPath: () => wikiPath,
     })
     const adminDeps: AdminDeps = {