dsh-tiddlywiki 0.16.21 → 0.16.22

package/src/host/seed-starter-docs.ts

@@ -0,0 +1,251 @@
+/**
+ * The "示例与文档" starter seed (v0.16.22): the generic docs / templates /
+ * example pages that give a fresh wiki a working "文档中心" out of the box —
+ * 主题汇总页·模板 (blank template) + 教程：按主题/标签做汇总页 (how-to) + three
+ * runnable 主题页 examples (日志 / 决策记录 / 排障).
+ *
+ * Sanitized: every tiddler carries NO personal data — the tutorial's
+ * 配套产物清单 points only at the tiddlers this seed actually provides, and
+ * the example pages auto-collect by tag (text verbatim from the author's wiki,
+ * they were already generic). Every item gets the shared `dsh-docs` tag so the
+ * seeded home's「📚 插件文档」tabs strip collects them automatically.
+ *
+ * Tier: STARTER — seeded automatically on first install (safe-skip: any
+ * same-named tiddler already present is never overwritten) and removable via
+ *「反初始化」from the settings page (ONE-SHOT marker-gated, like doc-note).
+ *
+ * @module dsh-tiddlywiki/host/seed-starter-docs
+ */
+import type { TiddlyWebClient } from './tw-api.ts'
+
+/** One-time marker: presence means "the docs were offered once — hands off". */
+export const STARTER_DOCS_MARKER_TITLE = '$:/plugins/dsh-tiddlywiki/seed-starter-docs'
+
+/** Shared tag that collects every plugin-seeded doc into the home docs tab. */
+export const DSH_DOCS_TAG = 'dsh-docs'
+
+export interface StarterDocItem {
+  title: string
+  tags: string[]
+  type: string
+  text: string
+}
+
+/** The docs, exactly as seeded (user-owned afterwards, freely deletable). */
+export const STARTER_DOCS_ITEMS: StarterDocItem[] = [
+  {
+    title: '主题汇总页·模板',
+    tags: ['索引', 'dsh-docs'],
+    type: 'text/vnd.tiddlywiki',
+    text: `\\whitespace trim
+
+!! 📌 主题汇总页
+
+<div style="color:#888; font-size:0.85em; border:1px dashed rgba(128,128,128,0.35); border-radius:8px; padding:6px 10px; margin-bottom:8px;">【模板】复制本页 → 改名（如「XX主题汇总」）→ 把下面两处 <code>主题A</code> 替换成你的标签名 → 保存。给笔记打上该标签即自动收录，本页无需维护。</div>
+
+<div class="tc-message-box">自动收集带 <code>主题A</code> 标签的笔记，按最近修改排序，共 <strong>{{{[tag[主题A]!is[system]!has[draft.of]count[]]}}}</strong> 篇。</div>
+
+<<list-links "[tag[主题A]!is[system]!has[draft.of]] +[!sort[modified]]">>
+
+---
+
+### 可选：自定义样式的 <$list> 版（想更花哨时用它替换上面的 list-links）
+
+<ul>
+<$list filter="[tag[主题A]!is[system]!has[draft.of]] +[!sort[modified]]">
+<li><$link to=<<currentTiddler>>><$view field="title"/></$link><span style="color:#aaa; font-size:0.85em;"> · <$view field="modified" format="relativedate"/></span></li>
+</$list>
+</ul>
+
+### 可选：把本页收进「一页多主题」tabs
+
+给本页打上 <code>主题页</code> 标签、并加一个 <code>caption</code> 字段（按钮文字），然后在总览页写：<code>&lt;&lt;tabs "[tag[主题页]!is[system]]"&gt;&gt;</code>。详见 [[教程：按主题/标签做汇总页]]。
+`,
+  },
+  {
+    title: '教程：按主题/标签做汇总页',
+    tags: ['教程', 'dsh-docs'],
+    type: 'text/markdown',
+    text: `# 教程：按主题/标签做汇总页
+
+> 适用：本 wiki 的 TiddlyWiki 5.3.x 内核。⚠️ 网上大量教程是 5.1/5.2 时代写的，其中 \`<<tabs "筛选器" "标签">>\` 和 \`<<count "筛选器">>\` 两种写法在本版本已**改版/移除**，照抄会报错，注意甄别。
+
+## 核心思路（一句话）
+
+「汇总页」不是 TW 的特殊功能，而是：**一个普通笔记 + 正文里一段筛选器（filter）**。渲染时 TW 实时从整个 wiki 挑出符合条件的笔记列出来。**新笔记只要打上对应标签，汇总页自动出现，零维护**——不用像手工目录那样每次手动更新。
+
+## 方法一：零代码，直接用内置标签页
+
+- 打开任意笔记，点正文底部的**标签链接**；
+- 或侧边栏「标签」（标签云）里点某个标签。
+- TW 会自动生成该标签的页面，列出所有带此标签的笔记。
+- 优点：一行代码都不用写；缺点：不能加说明文字、不能自定义排序/样式，也做不了「多主题合一」。
+
+## 方法二：一页一主题（最常用）
+
+新建一个笔记（wikitext），正文写：
+
+\`\`\`wikitext
+!! 📔 日志主题汇总
+<div class="tc-message-box">自动收集带 <code>日志</code> 标签的笔记，共 <strong>{{{[tag[日志]!is[system]!has[draft.of]count[]]}}}</strong> 篇，按最近修改排序。</div>
+
+<<list-links "[tag[日志]!is[system]!has[draft.of]] +[!sort[modified]]">>
+\`\`\`
+
+各片段含义：
+
+- \`[tag[日志]]\`：挑出所有带「日志」标签的笔记；
+- \`!is[system]\`：排除 \`$:/\` 系统页；
+- \`!has[draft.of]\`：排除未保存的草稿副本；
+- \`+[!sort[modified]]\`：按修改时间**倒序**（\`sort[modified]\` 为正序）；
+- \`{{{[...count[]]}}}\`：筛选器计数（旧版 \`<<count>>\` 宏已移除，这是 5.3 新写法）。
+
+想自定义每行样式（带相对时间、复选框等），用你更熟悉的 \`<$list>\` 写法：
+
+\`\`\`wikitext
+<ul>
+<$list filter="[tag[日志]!is[system]!has[draft.of]] +[!sort[modified]]">
+<li><$link to=<<currentTiddler>>><$view field="title"/></$link><span style="color:#aaa; font-size:0.85em;"> · <$view field="modified" format="relativedate"/></span></li>
+</$list>
+</ul>
+\`\`\`
+
+## 方法三：一页多主题（Dashboard，5.3 新版 tabs）
+
+5.3 的 \`tabs\` 宏签名：\`<<tabs "选中标签页的筛选器" "默认选中项">>\`。思路分两步：
+
+1. **每个主题各建一个汇总页**（就是方法二那种），全部打上同一个标签（本插件 seed 的示例用 \`主题页\`）；要自定义按钮文字，就给该页加一个 \`caption\` 字段（如 \`📔 日志\`）。
+2. **建一个总览页**，正文只写一行：
+
+\`\`\`wikitext
+<<tabs "[tag[主题页]!is[system]]" "主题页·日志">>
+\`\`\`
+
+效果：页面上方一排按钮，点哪个就内嵌显示哪个主题的汇总。第二个参数是默认展开的页（可省略，省略则初始不展开）。
+
+> 老教程的 \`<<tabs "筛选器A" "标签A" "筛选器B" "标签B">>\` 在 5.3 已失效，别用。
+
+本插件已 seed 了可直接运行的示例：[主题页·日志]、[主题页·决策记录]、[主题页·排障]（都带 \`主题页\` 标签），复制改造即可。
+
+## 筛选器速查表（背熟这几行就够用）
+
+| 想要 | 写法 |
+| --- | --- |
+| 某标签下的笔记 | \`[tag[主题]]\` |
+| 排除系统页 / 草稿 | \`[tag[主题]!is[system]!has[draft.of]]\` |
+| 修改时间倒序 / 正序 | \`+[!sort[modified]]\` / \`+[sort[modified]]\` |
+| 按标题排序 | \`+[sort[title]]\` |
+| 交集（同时有两个标签） | \`[tag[A]+tag[B]]\` |
+| 并集（有任一标签） | \`[tag[A]] [tag[B]]\` |
+| 差集（有 A 无 B） | \`[tag[A]-tag[B]]\` |
+| 排除某标签 | \`-[tag[排除项]]\` |
+| 限定时间段 | \`[tag[主题]modified[2026-09]]\` |
+| 计数 | \`{{{[tag[主题]!is[system]count[]]}}}\`（或 \`<$count filter="[tag[主题]]"/>\`） |
+| 整个 wiki 的非系统非草稿 | \`all[tiddlers]!is[system]!has[draft.of]\` |
+
+## 进阶玩法
+
+1. **按字段筛选**：\`[tag[todo]get[due]compare:date:lt<today>]\` 可列出「到期日早于今天」的笔记（主页的逾期看板就是这么写的）。
+2. **树状目录**：\`<<toc tag:"主题">>\` 显示层级目录，适合一个主题下还有子主题的情况。
+3. **模板复用**：复制 [主题汇总页·模板] 改标题和标签即可，不用每次重写。
+4. **打开直达**：把 \`$:/DefaultTiddlers\` 改成 \`[[主题页·日志]]\`，启动即打开汇总页（当前默认是 [🏠 主页]）。
+5. **导航收录**：给汇总页打 \`索引\` 标签，它就会从「全部笔记 / 所有文章」里消失、只作为导航页存在；再在 [🏠 主页] 的按钮区加一个入口按钮即可。
+6. **标签整理**：控制台 → 工具 → 标签管理器，可重命名/合并标签，改名后所有笔记自动跟随，汇总页筛选器无需改动（筛选器按标签名匹配，自动跟随改名）。
+
+## 配套产物清单（插件 seed 提供了什么）
+
+- [主题页·日志]、[主题页·决策记录]、[主题页·排障] —— 单主题汇总页实例（各自可独立打开，也可作为「一页多主题」tabs 的标签页）
+- [主题汇总页·模板] —— 空白模板，复制即用
+- 本教程 —— 就是这一页
+
+以上都来自「示例与文档」seed（tag \`dsh-docs\`），不需要可自由删除，删除后不会自动恢复。
+`,
+  },
+  {
+    title: '主题页·日志',
+    tags: ['主题页', '索引', 'dsh-docs'],
+    type: 'text/vnd.tiddlywiki',
+    text: `\\whitespace trim
+
+!! 📔 日志主题汇总
+
+<div class="tc-message-box">自动收集带 <code>日志</code> 标签的笔记，按最近修改排序，共 <strong>{{{[tag[日志]!is[system]!has[draft.of]count[]]}}}</strong> 篇。给笔记打上「日志」标签即自动收录，本页无需维护（做法见 [[教程：按主题/标签做汇总页]]）。</div>
+
+<<list-links "[tag[日志]!is[system]!has[draft.of]] +[!sort[modified]]">>
+`,
+  },
+  {
+    title: '主题页·决策记录',
+    tags: ['主题页', '索引', 'dsh-docs'],
+    type: 'text/vnd.tiddlywiki',
+    text: `\\whitespace trim
+
+!! 📌 决策记录主题汇总
+
+<div class="tc-message-box">自动收集带 <code>决策记录</code> 标签的笔记，按最近修改排序，共 <strong>{{{[tag[决策记录]!is[system]!has[draft.of]count[]]}}}</strong> 篇。给笔记打上「决策记录」标签即自动收录，本页无需维护（做法见 [[教程：按主题/标签做汇总页]]）。</div>
+
+<<list-links "[tag[决策记录]!is[system]!has[draft.of]] +[!sort[modified]]">>
+`,
+  },
+  {
+    title: '主题页·排障',
+    tags: ['主题页', '索引', 'dsh-docs'],
+    type: 'text/vnd.tiddlywiki',
+    text: `\\whitespace trim
+
+!! 🔧 排障主题汇总
+
+<div class="tc-message-box">自动收集带 <code>troubleshooting</code> 标签的笔记，按最近修改排序，共 <strong>{{{[tag[troubleshooting]!is[system]!has[draft.of]count[]]}}}</strong> 篇。给笔记打上「troubleshooting」标签即自动收录，本页无需维护（做法见 [[教程：按主题/标签做汇总页]]）。</div>
+
+<<list-links "[tag[troubleshooting]!is[system]!has[draft.of]] +[!sort[modified]]">>
+`,
+  },
+]
+
+/**
+ * Seed the starter docs once per wiki (safe-skip: same-named tiddlers already
+ * present are NEVER overwritten — user data stays user data). Marker-gated
+ * ONE-SHOT; with `opts.force` the tiddlers are (re)written and the marker
+ * (re)recorded — the settings page uses this for "重新初始化".
+ * Returns whether anything was written this call. Never throws.
+ */
+export async function seedStarterDocs(client: TiddlyWebClient, opts?: { force?: boolean }): Promise<boolean> {
+  const force = opts?.force === true
+  if (!force) {
+    const marker = await client.get(STARTER_DOCS_MARKER_TITLE).catch(() => undefined)
+    if (marker !== undefined) return false
+  }
+  let wrote = false
+  for (const item of STARTER_DOCS_ITEMS) {
+    const existing = await client.get(item.title).catch(() => undefined)
+    if (force || existing === undefined) {
+      await client.put({ title: item.title, text: item.text, type: item.type, tags: item.tags })
+      wrote = true
+    }
+  }
+  await client
+    .put({ title: STARTER_DOCS_MARKER_TITLE, text: 'seeded-once', type: 'text/plain', tags: [] })
+    .catch(() => undefined)
+  return wrote
+}
+
+/**
+ * Un-seed (反初始化): remove the starter docs and their marker. Deletion is
+ * idempotent — a tiddler already gone is not listed. Never throws.
+ */
+export async function unseedStarterDocs(client: TiddlyWebClient): Promise<{ removed: string[] }> {
+  const removed: string[] = []
+  for (const item of STARTER_DOCS_ITEMS) {
+    const t = await client.get(item.title).catch(() => undefined)
+    if (t !== undefined) {
+      await client.delete(item.title)
+      removed.push(item.title)
+    }
+  }
+  const marker = await client.get(STARTER_DOCS_MARKER_TITLE).catch(() => undefined)
+  if (marker !== undefined) {
+    await client.delete(STARTER_DOCS_MARKER_TITLE)
+    removed.push(STARTER_DOCS_MARKER_TITLE)
+  }
+  return { removed }
+}

package/src/host/seed-ui-styles.ts

@@ -0,0 +1,74 @@
+/**
+ * Generated from the wiki's custom stylesheet tiddlers (do not hand-edit the
+ * constants). Source: 编辑器美化 CSS.css, 标题与按钮区分开.css, 侧边栏窄屏自动隐藏.css, 批注弹窗样式.css, menubar 顶栏加高样式.css
+ *
+ * The「自定义样式」optional seed: the generic UI stylesheets the wiki owner
+ * curated (编辑器美化 / 标题与按钮区分开 / 侧边栏窄屏自动隐藏 / 批注弹窗 /
+ * menubar 顶栏加高). Only the functional tag $:/tags/Stylesheet is kept —
+ * wiki-local tags (自定义 / agent-written …) are NOT seeded, and none of the
+ * sheets carry personal data. Seeded ONE-SHOT (marker-gated, never overwrites
+ * user edits) + force 重新初始化 + remove 反初始化, like the other optional seeds.
+ *
+ * @module dsh-tiddlywiki/host/seed-ui-styles
+ */
+import type { TiddlyWebClient } from './tw-api.ts'
+
+/** One-time marker: presence means "the styles were offered once — hands off". */
+export const UI_STYLES_MARKER_TITLE = '$:/plugins/dsh-tiddlywiki/seed-ui-styles'
+
+export interface UiStyleItem {
+  title: string
+  tags: string[]
+  type: string
+  text: string
+}
+
+/** The stylesheets, exactly as seeded (user-owned afterwards). */
+export const UI_STYLE_ITEMS: UiStyleItem[] = [{"title":"编辑器美化 CSS","tags":["$:/tags/Stylesheet"],"type":"text/css","text":"/* ===== 编辑器美化（TiddlyWiki 5.4 + CodeMirror）===== */\n\n/* 字体 / 字号 / 行高 */\n.tc-editor .CodeMirror {\n  font-family: \"Fira Code VF\", Consolas, \"Courier New\", monospace;\n  font-size: 14px;\n  line-height: 1.7;\n}\n\n/* 编辑区内边距（呼吸感） */\n.tc-editor .CodeMirror-lines {\n  padding: 12px 14px;\n}\n\n/* 光标颜色 */\n.tc-editor .CodeMirror-cursor {\n  border-left: 2px solid #2e80ff !important;\n}\n\n/* 当前行高亮 */\n.tc-editor .CodeMirror-activeline-background {\n  background: rgba(46, 128, 255, 0.08);\n}\n\n/* 行号 */\n.tc-editor .CodeMirror-linenumber {\n  color: #9aa0a6;\n  padding-right: 10px;\n}\n\n/* 选区配色 */\n.tc-editor .CodeMirror ::selection {\n  background: rgba(46, 128, 255, 0.22);\n}\n\n/* 工具栏按钮：圆角 + 间距 */\n.tc-editor-toolbar button {\n  border-radius: 6px;\n  margin: 0 2px 2px 0;\n}\n\n/* 编辑页标题输入框：vanilla 默认 2.35em 过大，缩小字号与内边距 */\n.tc-tiddler-frame input.tc-edit-texteditor.tc-titlebar,\n.tc-tiddler-frame .tc-titlebar.tc-edit-texteditor {\n  font-size: 1.2em !important;\n  line-height: 1.35em !important;\n  padding: 4px 8px !important;\n}\n\n/* 查看模式标题：vanilla 默认 2.35em 过大，调小一些 */\n.tc-tiddler-frame .tc-tiddler-title .tc-titlebar,\n.tc-tiddler-frame .tc-tiddler-title h2.tc-title {\n  font-size: 1.3em !important;\n  line-height: 1.1em !important;\n}\n\n/* 侧边栏站点标题（sidebar 顶部的 wiki 站名）：vanilla 默认 2.35em 过大，调小 */\n.tc-sidebar .tc-site-title {\n  font-size: 1.5em !important;\n  line-height: 1.3em !important;\n}\n"},{"title":"标题与按钮区分开","tags":["$:/tags/Stylesheet"],"type":"text/css","text":".tc-titlebar h2 {\n\tdisplay: table-header-group;\n\tword-wrap:break-word;\n\tword-break:break-all;\n}\n"},{"title":"侧边栏窄屏自动隐藏.css","tags":["$:/tags/Stylesheet"],"type":"text/css","text":"/* ===== 侧边栏窄屏自动隐藏 =====\n   视口（TW 面板/iframe 宽度）< 960px 时自动完全隐藏右侧 TiddlyWiki 侧边栏，\n   正文占满整行；窗口变宽 >= 960px 后自动恢复。\n   断点 959px 对齐主题默认 sidebarbreakpoint=960px（vanilla/snowwhite/starlight）。\n   想改断点：改下面媒体查询里的数值即可。\n   想恢复默认：删除本 tiddler。 */\n\n@media (max-width: 959px) {\n\n\t/* 侧边栏整栏隐藏（含站点标题、各 sidebar 板块） */\n\t.tc-sidebar-scrollable {\n\t\tdisplay: none !important;\n\t}\n\n\t/* 右上角「显示/隐藏侧边栏」chevron 按钮一并隐藏：\n\t   窄屏下侧边栏已被 CSS 隐藏，此时按钮点击只会改 $:/state/sidebar 状态、\n\t   界面却看不到变化，反而误导，故隐藏 */\n\t.tc-hide-sidebar-btn,\n\t.tc-show-sidebar-btn {\n\t\tdisplay: none !important;\n\t}\n\n}\n"},{"title":"批注弹窗样式","tags":["$:/tags/Stylesheet"],"type":"text/css","text":"/* 批注功能弹窗美化（dsh-ann-*） */\n.dsh-ann-popup {\n\tborder-radius: 12px;\n\tpadding: 14px 16px;\n\tmax-width: 520px;\n\twidth: max-content;\n\tmin-width: 300px;\n\tbox-shadow: 0 10px 30px rgba(0,0,0,.22);\n\tborder: 1px solid rgba(127,127,127,.25);\n}\n.dsh-ann-popup .dsh-ann-head {\n\tdisplay: flex;\n\talign-items: center;\n\tjustify-content: space-between;\n\tgap: 10px;\n\tfont-weight: 700;\n\tfont-size: 1.02em;\n\tmargin-bottom: 8px;\n}\n.dsh-ann-icon-btn {\n\tborder: none;\n\tbackground: transparent;\n\tcursor: pointer;\n\tfont-size: 1em;\n\tline-height: 1;\n\tpadding: 2px 8px;\n\tborder-radius: 6px;\n\topacity: .55;\n}\n.dsh-ann-icon-btn:hover { opacity: 1; background: rgba(127,127,127,.15); }\n.dsh-ann-sub { font-size: .88em; margin: 4px 0; }\n.dsh-ann-quote {\n\tbackground: rgba(127,127,127,.14);\n\tpadding: 2px 8px;\n\tborder-radius: 6px;\n\tfont-style: italic;\n}\n.dsh-ann-chip {\n\tdisplay: inline-block;\n\twidth: 12px;\n\theight: 12px;\n\tborder-radius: 50%;\n\tmargin: 0 4px 0 8px;\n\tborder: 1px solid rgba(0,0,0,.18);\n\tvertical-align: -1px;\n}\n.dsh-ann-label { font-size: .9em; margin: 10px 0 4px; }\n.dsh-ann-input {\n\twidth: 100%;\n\tborder-radius: 8px;\n\tborder: 1px solid rgba(127,127,127,.35);\n\tpadding: 6px 9px;\n\tfont-size: .95em;\n\tresize: vertical;\n}\n.dsh-ann-input:focus {\n\toutline: none;\n\tborder-color: #4a90d9;\n\tbox-shadow: 0 0 0 2px rgba(74,144,217,.22);\n}\n.dsh-ann-actions {\n\tdisplay: flex;\n\tjustify-content: flex-end;\n\talign-items: center;\n\tgap: 8px;\n\tmargin-top: 12px;\n}\n.dsh-ann-btn {\n\tdisplay: inline-block;\n\tborder-radius: 8px;\n\tpadding: 5px 14px;\n\tcursor: pointer;\n\tborder: 1px solid rgba(127,127,127,.35);\n\tbackground: rgba(127,127,127,.08);\n\tfont-size: .9em;\n\ttext-decoration: none !important;\n}\n.dsh-ann-btn:hover { background: rgba(127,127,127,.18); }\n.dsh-ann-btn-primary {\n\tbackground: #4a90d9;\n\tborder-color: #4a90d9;\n\tcolor: #fff !important;\n}\n.dsh-ann-btn-primary:hover { background: #3a80c9; }\n.dsh-ann-colors {\n\tdisplay: flex;\n\tgap: 10px;\n\tmargin: 10px 0 12px;\n}\n.dsh-ann-swatch {\n\twidth: 34px;\n\theight: 34px;\n\tborder-radius: 50%;\n\tborder: 2px solid rgba(0,0,0,.14);\n\tcursor: pointer;\n\tpadding: 0;\n\ttransition: transform .12s ease, box-shadow .12s ease;\n}\n.dsh-ann-swatch:hover {\n\ttransform: scale(1.18);\n\tbox-shadow: 0 2px 8px rgba(0,0,0,.28);\n}\n.dsh-ann-sel { font-size: .88em; margin-top: 4px; }\n"},{"title":"menubar 顶栏加高样式","tags":["$:/tags/Stylesheet"],"type":"text/css","text":"/* ==== menubar 顶栏加高 ====\n   默认顶栏约 28px（菜单项 padding 0.5em + line-height 1）。\n   想调高度：改 min-height 数值即可（如 40 / 48 / 56px）。\n   想恢复默认：删除本 tiddler。\n   flex 布局让菜单项在加高的栏内垂直居中；窄屏汉堡展开时保持纵向堆叠。 */\n\nnav.tc-menubar ul.tc-menubar-list {\n\tdisplay: flex;\n\talign-items: center;\n\tbox-sizing: border-box;\n\tmin-height: 44px;\n}\n\nnav.tc-menubar .tc-menubar-narrow ul.tc-menubar-list {\n\tflex-direction: column;\n\talign-items: stretch;\n}\n"}]
+
+/**
+ * Seed the custom stylesheet tiddlers once per wiki (mirrors the one-shot
+ * policy). With opts.force the tiddlers are overwritten with the built-in
+ * content and the marker (re)written — the settings page uses this for
+ * "重新初始化". Returns whether anything was written this call. Never throws.
+ */
+export async function seedUiStyles(client: TiddlyWebClient, opts?: { force?: boolean }): Promise<boolean> {
+  const force = opts?.force === true
+  if (!force) {
+    const marker = await client.get(UI_STYLES_MARKER_TITLE).catch(() => undefined)
+    if (marker !== undefined) return false
+  }
+  let wrote = false
+  for (const item of UI_STYLE_ITEMS) {
+    const existing = await client.get(item.title).catch(() => undefined)
+    if (force || existing === undefined) {
+      await client.put({ title: item.title, text: item.text, type: item.type, tags: item.tags })
+      wrote = true
+    }
+  }
+  await client
+    .put({ title: UI_STYLES_MARKER_TITLE, text: 'seeded-once', type: 'text/plain', tags: [] })
+    .catch(() => undefined)
+  return wrote
+}
+
+/**
+ * Un-seed (反初始化): remove the stylesheet tiddlers and their marker.
+ * Deletion is idempotent — a tiddler already gone is not listed. Never throws.
+ */
+export async function unseedUiStyles(client: TiddlyWebClient): Promise<{ removed: string[] }> {
+  const removed: string[] = []
+  for (const item of UI_STYLE_ITEMS) {
+    const t = await client.get(item.title).catch(() => undefined)
+    if (t !== undefined) {
+      await client.delete(item.title)
+      removed.push(item.title)
+    }
+  }
+  const marker = await client.get(UI_STYLES_MARKER_TITLE).catch(() => undefined)
+  if (marker !== undefined) {
+    await client.delete(UI_STYLES_MARKER_TITLE)
+    removed.push(UI_STYLES_MARKER_TITLE)
+  }
+  return { removed }
+}

package/src/host/seeds.ts

@@ -2,32 +2,39 @@
  * Unified seed registry (design: every one-time "与 dsh 联动需要 wiki 预置"
  * item is a SeedDef here).
  *
- * Two tiers (v0.15.0):
+ * Three tiers (v0.16.22):
  *   - CORE seeds (`core: true`) are functionally required by the plugin's
- *     own features — the startup path seeds exactly these (non-force).
- *   - OPTIONAL seeds (`core: false`) are nice-to-have content (说明笔记 /
- *     首页 / 所有文章 / menubar 顶栏主题自适应) — they are NEVER auto-seeded;
- *     the user opts in from the settings page「初始化」section (重新初始化)
- *     and can opt out again with 反初始化 (remove).
+ *     own features — the startup path seeds exactly these (non-force) and
+ *     they can never be 反初始化'd.
+ *   - STARTER seeds (`startup: true`, removable) are docs / examples that
+ *     give a fresh wiki a working「文档中心」out of the box — the startup path
+ *     ALSO seeds them on first install (safe-skip: same-named tiddlers are
+ *     never overwritten), and the user can 反初始化 them anytime.
+ *   - OPTIONAL seeds (`core: false`, `startup: false`) are nice-to-have
+ *     content (首页 / 所有文章 / 自定义样式 / menubar 顶栏主题自适应) — they are
+ *     NEVER auto-seeded; the user opts in from the settings page「初始化」section
+ *     (重新初始化) and can opt out again with 反初始化 (remove).
  *
  * Each seed owns:
  *   - `check` — current state (present / missing / needs-update) for the UI;
  *   - `run(force)` — non-force keeps the ONE-SHOT / user-owned semantics
  *     (write only when missing, never overwrite), force (re)writes the
  *     built-in content and (re)records the marker;
- *   - `remove` — optional seeds only: delete the seeded tiddlers + markers,
- *     returning the wiki to the "never seeded" state.
+ *   - `remove` — optional + starter seeds only: delete the seeded tiddlers +
+ *     markers, returning the wiki to the "never seeded" state.
  *
- * Registry: doc-note / send-to-agent / render-route / home-index /
- * all-articles / menubar-theme / tw-web-host.
+ * Registry: doc-note / starter-docs / send-to-agent / render-route /
+ * home-index / all-articles / ui-styles / menubar-theme / tw-web-host.
  *
  * @module dsh-tiddlywiki/host/seeds
  */
 import type { TiddlyWebClient } from './tw-api.ts'
 import { seedDocNote, unseedDocNote, DOC_NOTE_TITLE } from './seed-notes.ts'
+import { seedStarterDocs, unseedStarterDocs, STARTER_DOCS_ITEMS, STARTER_DOCS_MARKER_TITLE } from './seed-starter-docs.ts'
 import { seedSendToAgent, SEND_TO_AGENT_PLUGIN_TITLE } from './seed-send-to-agent.ts'
 import { seedHomeIndex, unseedHomeIndex, HOME_INDEX_ITEMS } from './seed-home.ts'
 import { seedAllArticles, unseedAllArticles, ALL_ARTICLES_TITLE } from './seed-all-articles.ts'
+import { seedUiStyles, unseedUiStyles, UI_STYLE_ITEMS } from './seed-ui-styles.ts'
 import { seedMenubarTheme, unseedMenubarTheme, MENUBAR_THEME_TIDDLER } from './seed-menubar-theme.ts'
 import { seedRenderRoute, RENDER_PLUGIN_TITLE } from './seed-render.ts'
 import { TW_WEB_HOST_TIDDLER, TW_WEB_HOST_DEFAULT } from './config.ts'
@@ -70,13 +77,19 @@ export interface SeedDef {
   title: string
   description: string
   /**
-   * Core seeds are seeded automatically on startup (功能必需). Optional
-   * seeds are manual-only from the settings page — never forced on users.
+   * Core seeds are seeded automatically on startup (功能必需) and can never
+   * be 反初始化'd — removing them would break a plugin feature.
    */
   core: boolean
+  /**
+   * STARTER tier (v0.16.22): docs / examples that the startup path ALSO seeds
+   * on first install (safe-skip: same-named tiddlers never overwritten), but
+   * which stay removable via「反初始化」. Meaningful only when `core` is false.
+   */
+  startup?: boolean
   check(ctx: SeedContext): Promise<SeedStatus>
   run(ctx: SeedContext, force: boolean): Promise<SeedRunResult>
-  /** Optional seeds only: delete the seeded tiddlers + markers (反初始化). */
+  /** Non-core seeds only: delete the seeded tiddlers + markers (反初始化). */
   remove?(ctx: SeedContext): Promise<SeedRunResult>
 }
 
@@ -99,6 +112,8 @@ interface SeedMeta {
   title: string
   description: string
   core: boolean
+  /** STARTER tier: also auto-seeded on first install (removable). */
+  startup?: boolean
 }
 
 type SeedWriter = (client: TiddlyWebClient, opts?: { force?: boolean }) => Promise<boolean>
@@ -122,7 +137,7 @@ function defineSeed(meta: SeedMeta, impl: {
   run?: (ctx: SeedContext, force: boolean) => Promise<SeedRunResult>
   unseed?: SeedUnseeder
 }): SeedDef {
-  const { id, title, description, core } = meta
+  const { id, title, description, core, startup } = meta
   const removable = !core
   const check: SeedDef['check'] = impl.check ?? (async (ctx) => {
     const present = await presentOf(ctx, impl.presentTitle ?? '')
@@ -143,15 +158,29 @@ function defineSeed(meta: SeedMeta, impl: {
       return { id, ok: false, wrote: false, error: err instanceof Error ? err.message : String(err) }
     }
   }
-  return { id, title, description, core, check, run, ...(remove === undefined ? {} : { remove }) }
+  return { id, title, description, core, ...(startup === undefined ? {} : { startup }), check, run, ...(remove === undefined ? {} : { remove }) }
 }
 
 /** The full registry, in display order. */
 export const SEED_DEFS: SeedDef[] = [
   defineSeed(
-    { id: 'doc-note', title: '插件说明笔记', description: '「dsh-tiddlywiki 插件说明」——入门说明笔记（可选，设置页「初始化」手动写入；ONE-SHOT，用户可改可删）。', core: false },
+    { id: 'doc-note', title: '插件说明笔记', description: '「dsh-tiddlywiki 插件说明」——入门说明笔记（首次安装默认写入；ONE-SHOT，用户可改可删，标记 dsh-docs 自动进首页「📚 插件文档」栏）。', core: false, startup: true },
     { presentTitle: DOC_NOTE_TITLE, write: seedDocNote, unseed: unseedDocNote },
   ),
+  defineSeed(
+    { id: 'starter-docs', title: '示例与文档（汇总模板 / 教程 / 主题页示例）', description: '新手文档中心起步包：主题汇总页·模板、教程（按主题/标签做汇总页）、三个可直接运行的示例主题页（日志 / 决策记录 / 排障）。全部打 dsh-docs 标签，自动出现在首页「📚 插件文档」栏；纯示例无个人数据，同名 tiddler 已存在则安全跳过，不会覆盖。首次安装默认写入，可反初始化。', core: false, startup: true },
+    {
+      check: async (ctx) => {
+        const missing: string[] = []
+        for (const item of STARTER_DOCS_ITEMS) {
+          if (!(await presentOf(ctx, item.title))) missing.push(item.title)
+        }
+        return { id: 'starter-docs', title: '示例与文档（汇总模板 / 教程 / 主题页示例）', description: '新手文档中心起步包：主题汇总页·模板、教程（按主题/标签做汇总页）、三个可直接运行的示例主题页（日志 / 决策记录 / 排障）。全部打 dsh-docs 标签，自动出现在首页「📚 插件文档」栏；纯示例无个人数据，同名 tiddler 已存在则安全跳过，不会覆盖。首次安装默认写入，可反初始化。', present: missing.length === 0, removable: true, detail: missing.length === 0 ? '已存在' : `缺失：${missing.join('、')}` }
+      },
+      write: seedStarterDocs,
+      unseed: unseedStarterDocs,
+    },
+  ),
   defineSeed(
     { id: 'send-to-agent', title: '「发送给 Agent」按钮', description: 'TW 笔记工具栏「发送给 Agent」按钮插件（$:/plugins/dsh/send-to-agent）——把笔记一键注入 DSH 会话。', core: true },
     { presentTitle: SEND_TO_AGENT_PLUGIN_TITLE, write: seedSendToAgent },
@@ -178,6 +207,20 @@ export const SEED_DEFS: SeedDef[] = [
     { id: 'all-articles', title: '所有文章（两列分页总览）', description: '「所有文章」——全部条目分两列（🤖 Agent 撰写 / 👤 人工·人类）各自分页展示。每页条数取插件设置 ui.allArticles.pageSize（默认 10）。', core: false },
     { presentTitle: ALL_ARTICLES_TITLE, write: seedAllArticles, unseed: unseedAllArticles },
   ),
+  defineSeed(
+    { id: 'ui-styles', title: '自定义样式（编辑器美化 / 窄屏侧栏 / menubar 加高 / 批注弹窗）', description: '5 张通用样式表（tag $:/tags/Stylesheet）：编辑器美化（CodeMirror 字体/光标/行号）、标题与按钮区分开、侧边栏窄屏自动隐藏（<960px）、menubar 顶栏加高、批注弹窗美化。纯样式无个人数据。', core: false },
+    {
+      check: async (ctx) => {
+        const missing: string[] = []
+        for (const item of UI_STYLE_ITEMS) {
+          if (!(await presentOf(ctx, item.title))) missing.push(item.title)
+        }
+        return { id: 'ui-styles', title: '自定义样式（编辑器美化 / 窄屏侧栏 / menubar 加高 / 批注弹窗）', description: '5 张通用样式表（tag $:/tags/Stylesheet）：编辑器美化（CodeMirror 字体/光标/行号）、标题与按钮区分开、侧边栏窄屏自动隐藏（<960px）、menubar 顶栏加高、批注弹窗美化。纯样式无个人数据。', present: missing.length === 0, removable: true, detail: missing.length === 0 ? '已存在' : `缺失：${missing.join('、')}` }
+      },
+      write: seedUiStyles,
+      unseed: unseedUiStyles,
+    },
+  ),
   defineSeed(
     { id: 'menubar-theme', title: 'menubar 顶栏主题自适应', description: '样式表覆盖（$:/plugins/dsh-tiddlywiki/menubar-theme，tag $:/tags/Stylesheet）——把 tiddlywiki/menubar 顶栏从「默认色映射的蓝色」改为跟随当前 palette 的 background/foreground，随 DSH 主题切换（$:/palette 翻转）自动换色。', core: false },
     { presentTitle: MENUBAR_THEME_TIDDLER, write: seedMenubarTheme, unseed: unseedMenubarTheme },
@@ -256,25 +299,28 @@ export async function runSeedById(ctx: SeedContext, id: string | undefined, forc
 }
 
 /**
- * Startup path: seed ONLY the core items (功能必需：发送给 Agent 按钮 +
- * TW 前端 API 基址), non-force (write only what is missing). Optional seeds
- * (说明笔记 / 首页 / 所有文章 / menubar 顶栏主题自适应) are never forced on
- * users — they opt in from the settings page「初始化」section.
+ * Startup path: seed the CORE items (功能必需：发送给 Agent 按钮 + 原生渲染
+ * 路由 + TW 前端 API 基址) AND the STARTER items (首次安装默认：插件说明 +
+ * 示例与文档), all non-force (write only what is missing — a same-named
+ * tiddler already present is NEVER overwritten, so user data stays user data).
+ * Remaining optional seeds (首页 / 所有文章 / 自定义样式 / menubar 顶栏主题自
+ * 适应) are never forced on users — they opt in from the settings page
+ * 「初始化」section.
  */
 export async function runAllSeeds(ctx: SeedContext): Promise<SeedRunResult[]> {
   const out: SeedRunResult[] = []
   for (const def of SEED_DEFS) {
-    if (!def.core) continue
+    if (!def.core && def.startup !== true) continue
     out.push(await def.run(ctx, false))
   }
   return out
 }
 
 /**
- * 反初始化 (remove): delete one optional seed's seeded tiddlers + markers, or
- * all optional seeds when `id` is undefined. Core seeds are functionally
- * required and cannot be removed — a direct request for one returns an error
- * result (and is skipped when removing all).
+ * 反初始化 (remove): delete one non-core seed's (starter 或 optional) seeded
+ * tiddlers + markers, or all non-core seeds when `id` is undefined. Core
+ * seeds are functionally required and cannot be removed — a direct request
+ * for one returns an error result (and is skipped when removing all).
  */
 export async function removeSeedById(ctx: SeedContext, id: string | undefined): Promise<SeedRunResult[]> {
   if (id === undefined) {

package/src/index.ts

@@ -45,10 +45,12 @@ export { writeSessionSummary, SESSION_SUMMARY_PREFIX } from './host/routes.ts'
 export type { SessionQueryFace, SessionSummaryResult } from './host/routes.ts'
 export { registerAdminRoutes, resolveTwRoot, readWikiInfo, writeWikiInfo, bundledCatalog, ensureLanguage, normalizeThemes } from './host/admin.ts'
 export { seedDocNote, DOC_NOTE_TITLE, DOC_NOTE_TAG, DOC_NOTE_TEXT } from './host/seed-notes.ts'
+export { seedStarterDocs, STARTER_DOCS_ITEMS, STARTER_DOCS_MARKER_TITLE, DSH_DOCS_TAG } from './host/seed-starter-docs.ts'
 export { seedSendToAgent, SEND_TO_AGENT_PLUGIN_TITLE, SEND_TO_AGENT_MARKER_TITLE, SEND_TO_AGENT_BUNDLE_TEXT } from './host/seed-send-to-agent.ts'
 export { seedRenderRoute, RENDER_PLUGIN_TITLE, RENDER_MARKER_TITLE, RENDER_BUNDLE_TEXT } from './host/seed-render.ts'
 export { seedHomeIndex, HOME_INDEX_ITEMS, HOME_INDEX_MARKER_TITLE, HOME_DEFAULT_TIDDLERS } from './host/seed-home.ts'
 export { seedAllArticles, ALL_ARTICLES_TITLE, ALL_ARTICLES_MARKER_TITLE, ALL_ARTICLES_TEXT } from './host/seed-all-articles.ts'
+export { seedUiStyles, UI_STYLE_ITEMS, UI_STYLES_MARKER_TITLE } from './host/seed-ui-styles.ts'
 export { seedMenubarTheme, MENUBAR_THEME_TIDDLER, MENUBAR_THEME_MARKER_TITLE, MENUBAR_THEME_TEXT } from './host/seed-menubar-theme.ts'
 export { runAllSeeds, checkAllSeeds, runSeedById, removeSeedById, SEED_DEFS, type SeedStatus, type SeedRunResult } from './host/seeds.ts'
 export { registerTiddlywikiTools } from './host/tools.ts'