dsh-tiddlywiki 0.16.28 → 0.18.0

package/README.md

@@ -26,14 +26,15 @@
 | 🏠 **文档中心起步包** | 首次安装自动 seed：插件说明 + 「示例与文档」（主题汇总模板 / 教程 / 三个示例主题页），首页「📚 插件文档」栏一键查阅；**同名 tiddler 已存在一律安全跳过，绝不覆盖你的数据**（v0.16.22） |
 | 🎨 **自定义样式** | 「自定义样式」seed：编辑器美化 / 窄屏侧栏隐藏 / menubar 加高 / 批注弹窗等 5 张通用样式表，新 wiki 也能一键初始化（可选，v0.16.22） |
 | 🤖 **Agent 工具** | 10 个 `tiddlywiki_*` 工具：检索、读写、批量、重命名、删除、git 同步与冲突解决（v0.16.20 起检索/最近在**服务端**排除二进制附件，大 wiki 上从 515MB/17s 降到 ~0.4s） |
-| 📊 **回复流卡片** | 工具结果显示原生 TW 卡片；`[标题](/dsh-tiddlywiki/tw/#标题)` 点击直达 TW 面板 |
+| 📊 **回复流卡片** | 工具结果显示原生 TW 卡片（**按笔记自己的内容类型渲染**：Markdown 笔记就是 Markdown，v0.18.0）；`[标题](/dsh-tiddlywiki/tw/#标题)` 点击直达 TW 面板 |
 | 📤 **发送给 Agent** | TW 笔记工具栏一键把当前笔记注入所选 dsh 会话（可选工作模式/权限/附加说明） |
 | 🧭 **内嵌编辑器** | 中央列内嵌完整 TW 5 编辑器（同源代理，Tailscale/内网/域名/HTTPS 均可） |
 | 🗂️ **右侧边栏 Tab** | DSH 新右侧栏（rightbar）：首页「TiddlyWiki 知识库」入口一键打开，与聊天并排；链接点击可直达（v0.16.21） |
-| 🧩 **Better Sidebar Tab** | dsh-better-sidebar 侧边栏：+ 菜单注册 TiddlyWiki tab，与聊天并排；链接点击可直达；未安装该插件自动跳过（v0.16.23） |
+| 🧩 **Better Sidebar 共存** | 与 dsh-better-sidebar 侧边栏共存（其展开/收起按钮浮在 TW 面板之上）；**不再向该侧边栏注册 TW tab**（v0.17.0 移除了 tab 注册，避免 tab kind 冲突） |
 | 📚 **会话知识库 Tab** | 每个会话顶部汇总本会话读写过的 wiki 笔记，TW 原生渲染（`/tw/render` 片段管线，v0.16.19） |
 | 📝 **快速笔记** | 输入框上方快捷按钮或右下角「知识库」FAB；原生编辑页或 Markdown 卡片两种模式；首页内置「快速记笔记（完整编辑器）」 |
-| 📌 **本地剪藏桥** | 可选「剪藏桥 + 书签小工具」：DSH 监听 127.0.0.1 端口接收剪藏请求（Host 校验防 rebinding），点书签弹出浮层——可改标题/编辑选中文字/**勾选图片**，一键写入知识库；文字成笔记（默认 `clip` 标签），图片由桥下载存为**二进制附件**（`type: image/*` + base64，笔记内 `[img[标题]]` 内嵌），随 wiki 自动进 git |
+| 📌 **本地剪藏桥** | 可选「剪藏桥 + 书签小工具」：DSH 监听 127.0.0.1 端口接收剪藏请求（Host 校验防 rebinding），点书签弹出浮层——可改标题/编辑选中文字/**勾选图片**，一键写入知识库；文字成笔记（默认 `clip` 标签），图片由桥下载存为**二进制附件**（`type: image/*` + base64，笔记内 `[img[标题]]` 内嵌），随 wiki 自动进 git；图片下载有 **SSRF 守卫**（仅公网 http(s)、逐跳校验重定向，v0.18.0） |
+| 🔐 **写操作防跨站** | 所有写路由（笔记/上传/同步/后台/代理）拒绝跨站请求（403），仅同源的 GUI 与内嵌 TW 可写；跨站 GET 与浏览器地址栏直达不受影响（v0.18.0） |
 | ✅ **待办四象限** | 首页看板：任务打 `todo` 标签即收录，拖动即可分类/完成（正文附 `q` 字段），逾期/今日到期自动统计 |
 | 🌗 **跟随主题** | 内嵌 TW 自适应 DSH 深浅主题（纯内存切换，不进 git） |
 | 🔄 **一键同步** | FAB「同步」一键 pull→commit→push，状态点实时反映 git 状态 |
@@ -101,7 +102,7 @@ dsh plugin --profile web add link:/path/to/dsh-tiddlywiki
 - **📤 发送给 Agent**：TW 工具栏按钮（首次启动自动写入 wiki，ONE-SHOT）。弹层可选**附加说明**（位于消息末尾）、**工作模式**（Agent 预设）、**权限**（权限预设），按工作区分组选会话或新建。消息自带待办说明。
 - **🧭 中央列编辑器**：侧边栏「TiddlyWiki」开关（显示名可改 `ui.sidebarLabel`）。
 - **🗂️ 右侧边栏 Tab**（v0.16.21）：DSH 新右侧栏展开后，首页会出现「**TiddlyWiki 知识库**」入口盒，点击即在右侧栏以 tab 形式打开完整 TW 编辑器——**与聊天并排**，适合边聊边查/边记。由 `ui.showRightbarTab` 控制（默认开）；老版本 DSH（无右侧栏）自动跳过。
-- **🧩 Better Sidebar Tab**（v0.16.23）：安装了 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 插件时，其侧边栏 **+ 菜单**会出现「TiddlyWiki 知识库」tab，点击即打开完整 TW 编辑器（同一套同源代理 iframe / 主题跟随 / 互斥协议，与右侧栏完全相同），**与聊天并排**。由 `ui.showBetterSidebarTab` 控制（默认开）；未安装 Better Sidebar 自动跳过；Better Sidebar 自己的设置页也会为该 tab 提供独立的启用开关。**更新后刷新页面**即可看到入口。
+- **🧩 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 保存）。
 - **📌 本地剪藏桥**（可选，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 文档）。
@@ -152,7 +153,7 @@ seed 是把「wiki 里预置内容」随插件分发的机制：**ONE-SHOT（只
       tag: "inbox"                     # 快速笔记默认 tag
     bridge:
       enabled: false                   # 本地剪藏桥（书签小工具）；保存后立即生效
-      port: 8618                       # 监听端口（127.0.0.1；改后需重启 dsh web）
+      port: 8618                       # 监听端口（127.0.0.1；改后需重启 dsh web 才绑定新端口）
       token: ""                        # 共享口令；非空时校验书签的 x-clip-token 头（强烈建议设置）
       tag: "clip"                      # 剪藏笔记默认 tag
     ui:
@@ -171,10 +172,10 @@ seed 是把「wiki 里预置内容」随插件分发的机制：**ONE-SHOT（只
     uiLanguage: ""                     # 留空不干预；"zh-Hans" 自动启用简体
     auth:
       username: ""                     # 默认 loopback 匿名；暴露到非回环才需要
-      password: ""
+      password: ""                     # 非空时插件内置客户端/就绪探测/浏览器代理都带 Basic 认证（v0.18.0 起真正可用）
 ```
 
-> **运行时配置**：设置页写入的 `$:/plugins/dsh-tiddlywiki/config` tiddler 是 `config:` 块之上的覆盖层（tiddler 优先、随 wiki git 同步），改 note tag / git / ui 开关无需动 cordis。
+> **运行时配置**：设置页写入的 `$:/plugins/dsh-tiddlywiki/config` tiddler 是 `config:` 块之上的覆盖层（tiddler 优先、随 wiki git 同步），改 note tag / git / ui 开关**以及剪藏桥端口**都无需动 cordis（端口改动仍需重启 dsh web 重新绑定监听）。
 
 ---
 
@@ -191,13 +192,16 @@ TW 子进程只监听 **127.0.0.1 回环**；Agent 工具/快速笔记/同步都
 ```bash
 npm install
 npm run typecheck     # tsc --noEmit
-npm run build         # clean + host tsdown + client tsdown + wrap
+npm run build         # clean + host tsdown + client tsdown + wrap（wrap 会校验 id 与体积 <900KB）
 npm run selftest      # headless：spawn TW → REST 读写 → git → 退出回收
-node scripts/verify-clip-bridge.mjs   # 剪藏桥 headless 验收（build 后跑）
+npm run smoke:client  # client bundle 的 module-loader 形状冒烟
+node scripts/verify-send-to-agent-bundle.mjs  # bundle 字段 + 源件逐字一致
+node scripts/verify-seed-send-to-agent.mjs    # 全新 wiki 上的 seed E2E
+node scripts/verify-clip-bridge.mjs   # 剪藏桥 headless 验收（含 SSRF 守卫）
 node scripts/verify-seeds-admin.mjs   # /admin/seeds 状态与 run 的 E2E
 ```
 
-**改 bundle/seed 的再生成流水线**（不要手改 `seed-*.ts` 里的生成常量）：
+**改 bundle/seed 的再生成流水线**（不要手改 `seed-*.ts` 里的生成常量；bundle 版本号只在 `scripts/bundle/versions.mjs` 定义一处）：
 
 ```bash
 # 发送给 Agent 按钮（改 scripts/bundle/send-to-agent/ 后）
@@ -205,13 +209,13 @@ node scripts/build-send-to-agent-bundle.mjs
 node scripts/gen-seed-send-to-agent.mjs scripts/bundle/send-to-agent.bundle.json src/host/seed-send-to-agent.ts
 node scripts/verify-send-to-agent-bundle.mjs
 
-# 渲染路由（改 scripts/bundle/render/server-routes/render.js 后）
+# 渲染路由（改 scripts/bundle/render/server-routes/render.js 后；版本在 versions.mjs）
 node scripts/build-render-bundle.mjs
 node scripts/gen-seed-render.mjs scripts/bundle/render.bundle.json src/host/seed-render.ts
 
-# 首页（改 wiki 的 🏠 主页/所有标签/标签笔记 .tid 后；必须 --strip-private，
-# 产出通用版：剥离作者私有人口 + 注入「📚 插件文档」栏）
-node scripts/gen-seed-home.mjs '<wiki>/tiddlers/🏠 主页.tid' '<wiki>/tiddlers/所有标签.tid' '<wiki>/tiddlers/标签笔记.tid' src/host/seed-home.ts --strip-private
+# 首页（改 wiki 的 🏠 主页/所有标签/标签笔记 .tid 后；默认就剥离作者私有人口 +
+# 注入「📚 插件文档」栏，确要保留私有内容才加 --keep-private）
+node scripts/gen-seed-home.mjs '<wiki>/tiddlers/🏠 主页.tid' '<wiki>/tiddlers/所有标签.tid' '<wiki>/tiddlers/标签笔记.tid' src/host/seed-home.ts
 
 # 自定义样式（改 wiki 的样式 .css + .meta 后；tag 自动收窄为 $:/tags/Stylesheet）
 node scripts/gen-seed-ui-styles.mjs '<wiki>/tiddlers/<样式.css>' … src/host/seed-ui-styles.ts
@@ -265,7 +269,7 @@ src/
     ├── tool-views.ts       # 回复流工具卡片（tool.call.toolview）
     ├── theme-sync.ts / panel.ts / sidebar-entry.ts / sync-button.ts / rightbar-tab.ts
     │                   # 共享 TW iframe 机制在 tw-frame.ts（v0.16.23：lazy-load/status/主题/互斥/live-frame 路由）；
-    │                   # better-sidebar-tab.ts 经 ctx.betterSidebar 注册 DSH Better Sidebar 的 TW tab（v0.16.23）
+    │                   # TW tab 只注册在 DSH 原生右侧栏（rightbar-tab.ts）
     └── settings-page.ts / ui-config.ts / state.ts / styles.ts / toast.ts
 scripts/                # 构建/校验/再生成脚本
 docs/seed-initialization.md  # seed 机制详解（权威）
@@ -278,6 +282,8 @@ lib/                    # 预构建产物（发布含 lib/**，提交入库；
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.18.0**（2026-09-10）：**一轮全量代码审计后的修复版**（数据安全 / 安全面 / 前端稳定性 / 工程卫生，共 40+ 项）。**数据不再静默丢失**：① seed 只在**真的 404** 时才认为条目缺失（此前任何读取错误都被当「不存在」，瞬时故障会让非 force 的启动 seed 覆盖你改过的同名笔记、`$:/DefaultTiddlers`、send-to-agent / render bundle）；② `wiki/.gitignore` 不再每次启动被整份重写（用户自定规则改前会被冲掉）；③ 配置 tiddler 读失败不再清空内存覆盖层（随后在设置页保存一项配置会丢掉其余全部覆盖）；④ 只有 **render-route 真的重写后**才重启 TW，且要等它落盘（否则重启会丢掉未 flush 的写入——这条是本版新引入又被测试抓出的回归）。**正确性**：`/render` 现在按 tiddler 自己的 `type` 渲染——**Markdown 笔记在回复流卡片/汇总里终于按 Markdown 渲染**（此前硬编码 wikitext，`## 现象` 会被当成 wikitext 列表，实测复现）。**安全**：所有写路由（`/admin/*`、`/note`、`/edit`、`/upload`、`/sync`、`/restart`、`/api`、`/tw` 的写方法）加**同源/CSRF 守卫**（跨站写请求 403，跨站 GET 不受影响）；剪藏桥图片下载加 **SSRF 守卫**（仅公网 http(s)，逐跳校验重定向，拒绝回环/内网/云元数据地址）；`bridge.port` 设置页改动现在**真的生效**（此前只读 cordis 基座）；`auth.username/password` 从此**可用**（内置 REST 客户端与就绪探测带 Basic 认证，代理转发 `WWW-Authenticate` 让浏览器弹登录框，此前配置了用户名会让插件 20s 后启动失败）。**前端**：编辑器弹窗不再因同草稿重开而整机重载、并纳入面板互斥；中央面板自愈列元素重建；右栏 Tab 重新可见会重新探测状态；侧边栏入口插入不再抛 `NotFoundError` 连带拖垮 FAB/面板；同步中不再被 30s 轮询覆盖状态；`injectStyles` 可卸载（热重载拿到新样式）；每处 mount 独立 try/catch；面板的 DOM 观察/滚动测量合并到 requestAnimationFrame（流式输出时不再每帧强制样式重算）。**工具与仓库**：`put`/`batch_put` 不再把读取失败当新条目而误打 `agent-written`，`fields` 不能覆盖 `title/text/tags`，`batch_put` 逐条报告失败；git 的 commit 与 pull 串行化（不再争 `.git/index.lock`）；`/status` 的 git 摘要加 2s 缓存（每次调用少跑 5 个 git 进程）；请求中途断开不再挂住路由；自动端口被占时会重新探测；`tiddlywiki.info` 损坏不再让后台 500；会话汇总对后代会话/条目数设上限。**工程卫生**：bundle 版本单一来源（`scripts/bundle/versions.mjs`，渲染路由 0.2.0）、生成器从 bundle 读版本（外层 0.3.2 漂移修正为 0.3.4）、发布包不再带 `client.bundle.js` 中间产物、`verify-*` 假阳性修复（未 await 的用例、被当成断言的 console.log）、selftest 失败也会回收 TW 子进程、`gen-seed-home` 默认剥离私有人口、`verify-menubar-theme` 不再默认打作者本机端口。
+- **v0.17.0**（2026-09-10）：**移除：DSH Better Sidebar（dsh-better-sidebar）Tab 集成**。旧版通过 `ctx.betterSidebar.registerTab({id:'dsh-tiddlywiki'})` 注册的 tab kind 会与其它注册方冲突，浏览器控制台报 `sidebarRight: tab kind "dsh-tiddlywiki" is already registered (extension)`；本版**整体删除**该注册路径（删除 `better-sidebar-tab.ts`、client 入口的挂载块，以及 `ui.showBetterSidebarTab` 配置项/设置页开关），插件不再引用 `ctx.betterSidebar` 服务。与 dsh-better-sidebar 的**界面共存**（中央面板 z-index 让位于其侧边栏按钮）保留；右侧边栏入口请用 DSH 原生 rightbar（`ui.showRightbarTab`）。**更新后刷新页面**生效；旧版可临时用 `ui.showBetterSidebarTab=false` 规避冲突。
 - **v0.16.28**（2026-09-10）：**修：拖拽版剪藏书签在知乎等真实页面报 `SyntaxError: Unexpected token ';'`**。根因（真实 Chrome 实验证实）：0.16.27 把书签 href 做 **HTML 实体转义**（`&quot;`/`&amp;`/`&lt;`），但浏览器的 `a.href` **不做实体还原**——拖拽成书签后存的就是实体文本，执行时即解析失败。修复：href 改为 **percent-encoding**（`CLIP_BRIDGE_DRAG_HREF`，属性里只剩 `%XX`，天然无需任何属性转义）；Chrome 执行 `javascript:` URL 前会 percent 解码（实测通过）。浏览器 E2E 升级为**直接以编码 href 走 `location.href` 执行**（完全等价拖拽书签的执行路径）并断言浮层弹出；静态验收改为 `decodeURIComponent(href) === 代码常量` 一致性校验。行为不变——**已拖过旧版书签的用户需重新初始化 seed 后重新拖一次**（旧书签仍然坏的，因为里面的代码是实体文本）。
 - **v0.16.27**（2026-09-10）：**剪藏书签支持「拖拽安装」**。seed 文档新增一个**可拖拽按钮**（markdown 内嵌原始 HTML 锚点，href 即书签代码）——按住拖到浏览器书签栏/地址栏松手即装好，免去复制粘贴；代码 fence 保留作兜底。书签代码抽成单一常量 `CLIP_BRIDGE_BOOKMARKLET`（锚点 href 做 HTML 实体转义），并新增**同步一致性校验**（`verify-clip-bridge.mjs`：href 解码后与代码逐字相等）与**浏览器 E2E**（`verify-clip-bridge-browser.mjs`：真实 TW + 无头 Chrome 渲染真实 seed 文档，断言 javascript: href 原样保留 / draggable / 解码一致 / 真浏览器里执行书签弹出浮层 / 无 JS 异常）。
 - **v0.16.26**（2026-09-10）：**修：剪藏书签在真实页面上崩溃**（`Cannot set properties of null (setting 'value')`）。根因：浮层字段在 `p` 尚未挂到 document 前就用 `document.getElementById` 取值（脱离文档树查不到 → null）；同时 `cb_*` id 可能与页面自身元素冲突。修复：所有浮层字段改为 `p.querySelector` 作用域内查找 + 字段赋值挪到 `appendChild` 之后；并把书签放进 **jsdom 真实 DOM 端到端跑通**（浮层/填充/选图/提交载荷/结果态 12 项全过）作为验证，`verify-clip-bridge.mjs` 新增静态回归断言（禁未限定 getElementById + 挂载时序）。行为无变化，仅书签代码（seed 文档）修复。

package/docs/seed-initialization.md

@@ -57,9 +57,10 @@ interface SeedDef {
 | `all-articles` | `seed-all-articles.ts` → `seedAllArticles` / `unseedAllArticles` | 「所有文章」（tag `索引`）——两列分页总览，每页条数实时读 `ui.allArticles.pageSize`（默认 10） | `$:/plugins/dsh-tiddlywiki/seed-all-articles` | 可选 |
 | `ui-styles` | `seed-ui-styles.ts` → `seedUiStyles` / `unseedUiStyles` | 5 张通用样式表（只带功能 tag `$:/tags/Stylesheet`，剥离 wiki 本地标签与个人数据）：编辑器美化、标题与按钮区分开、侧边栏窄屏自动隐藏、批注弹窗、menubar 顶栏加高 | `$:/plugins/dsh-tiddlywiki/seed-ui-styles` | 可选 |
 | `menubar-theme` | `seed-menubar-theme.ts` → `seedMenubarTheme` / `unseedMenubarTheme` | `$:/plugins/dsh-tiddlywiki/menubar-theme`（tag `$:/tags/Stylesheet`）——覆盖 tiddlywiki/menubar 顶栏：把 `<<colour menubar-background>>` 的「默认色映射蓝色」改为跟随活动 palette 的 `background`/`foreground`，随 DSH 主题切换（`$:/palette` 翻转）自动换色 | `$:/plugins/dsh-tiddlywiki/seed-menubar-theme` | 可选 |
+| `clip-bridge` | `seed-clip-bridge.ts` → `seedClipBridge` / `unseedClipBridge` | 「本地剪藏桥 + 书签小工具」使用说明（Markdown 文档，带书签代码 / 启用步骤 / 安全说明，tag `dsh-docs`）——真功能在 `clip-bridge.ts` 运行时代码里 | `$:/plugins/dsh-tiddlywiki/seed-clip-bridge` | 可选 |
 | `tw-web-host` | `seeds.ts` 内联 | `$:/config/tiddlyweb/host` → `/dsh-tiddlywiki/tw/` | 无 marker（ensure 型，见 §4） | **核心** |
 
-> ℹ️ `home-index` 的 seed 版首页是**通用版**：生成时用 `--strip-private` 剥离了作者 wiki 里的个人元素（主题页 tabs、书籍书架入口等），并内置「📚 插件文档」tabs 栏（`[tag[dsh-docs]!is[system]]`，默认展开插件说明）。作者自己的 wiki 首页不受影响（seed 是 ONE-SHOT，不会覆盖）。
+> ℹ️ `home-index` 的 seed 版首页是**通用版**：生成脚本**默认**剥离作者 wiki 里的个人元素（主题页 tabs、书籍书架入口等，仅 `--keep-private` 才原样嵌入），并内置「📚 插件文档」tabs 栏（`[tag[dsh-docs]!is[system]]`，默认展开插件说明）。作者自己的 wiki 首页不受影响（seed 是 ONE-SHOT，不会覆盖）。
 
 ### 统一入口（`src/index.ts` 导出）
 
@@ -210,13 +211,22 @@ DSH 设置 →「TiddlyWiki 知识库」→ 最底部「**初始化（一次性
 seed 的内容以**内嵌常量**形式随插件发布，修改来源后需重新生成：
 
 ```bash
-# 改了 wiki 里的「发送给 Agent」按钮 bundle（$:/plugins/dsh/send-to-agent）：
-node scripts/gen-seed-send-to-agent.mjs '<wiki>/tiddlers/$__plugins_dsh_send-to-agent.json' src/host/seed-send-to-agent.ts
+# 改了「发送给 Agent」按钮的源件（scripts/bundle/send-to-agent/ 下 startup.js / button.tid /
+# icon.svg / item-template.tid）——三段式：build → gen → verify：
+node scripts/build-send-to-agent-bundle.mjs                                                     # 1) build → scripts/bundle/send-to-agent.bundle.json
+node scripts/gen-seed-send-to-agent.mjs scripts/bundle/send-to-agent.bundle.json src/host/seed-send-to-agent.ts   # 2) gen → 内嵌常量（外层 version 从 bundle 内层 plugin.info 读取）
+node scripts/verify-send-to-agent-bundle.mjs                                                    # 3) verify（字段 + 源件逐字一致 + 版本常量）
+
+# 改了原生渲染路由源件（scripts/bundle/render/server-routes/render.js）——同样三段式：
+node scripts/build-render-bundle.mjs                                                            # 1) build → scripts/bundle/render.bundle.json
+node scripts/gen-seed-render.mjs scripts/bundle/render.bundle.json src/host/seed-render.ts      # 2) gen（外层 version 同样从 bundle 内层 plugin.info 读取）
+# 3) verify：无独立 verify 脚本，/render 行为由 selftest 5c2 段覆盖
+#    （两个 bundle 的版本号单一来源：scripts/bundle/versions.mjs）
 
 # 改了 wiki 首页（🏠 主页 / 所有标签 / 标签笔记）：
-#   推荐带 --strip-private：剥离作者私有人口（主题页 tabs / 主题汇总死链 / 书籍书架）
-#   并注入「📚 插件文档」tabs 栏，产出通用版 seed 首页
-node scripts/gen-seed-home.mjs '<wiki>/tiddlers/🏠 主页.tid' '<wiki>/tiddlers/所有标签.tid' '<wiki>/tiddlers/标签笔记.tid' src/host/seed-home.ts --strip-private
+#   默认即剥离作者私有人口（主题页 tabs / 主题汇总死链 / 书籍书架）并注入「📚 插件文档」tabs 栏，
+#   产出通用版 seed 首页；仅作者本机想原样嵌入时才传 --keep-private（绝不用于发布）。
+node scripts/gen-seed-home.mjs '<wiki>/tiddlers/🏠 主页.tid' '<wiki>/tiddlers/所有标签.tid' '<wiki>/tiddlers/标签笔记.tid' src/host/seed-home.ts
 
 # 改了 wiki 里的自定义样式（.css + .meta，tag 只保留 $:/tags/Stylesheet）：
 node scripts/gen-seed-ui-styles.mjs '<wiki>/tiddlers/编辑器美化 CSS.css' '<wiki>/tiddlers/标题与按钮区分开.css' '<wiki>/tiddlers/侧边栏窄屏自动隐藏.css' '<wiki>/tiddlers/批注弹窗样式.css' '<wiki>/tiddlers/menubar 顶栏加高样式.css' src/host/seed-ui-styles.ts
@@ -232,7 +242,7 @@ node scripts/gen-seed-ui-styles.mjs '<wiki>/tiddlers/编辑器美化 CSS.css' '<
 npm run typecheck && npm run build && npm run selftest
 ```
 
-> PowerShell 注意：含 `$` 的路径（如 `$__plugins_dsh_send-to-agent.json`）要用**单引号**包裹，否则 `$` 会被当作变量展开。
+> PowerShell 注意：含空格/中文的 wiki 路径（如 `'<wiki>/tiddlers/menubar 顶栏加高样式.css'`）要用**单引号**包裹，否则会被拆成多个参数。
 
 **文档合集约定（日常新增文档 seed 时）**：任何新的 TW 侧说明/模板/示例类内容，都走 seed（ONE-SHOT + 同名跳过），并给 tiddler 打 **`dsh-docs`** 标签——首页「📚 插件文档」栏自动收录，用户无需配置。doc-note 与 starter-docs 是 `startup: true` 起步项（首次安装默认写入），其余文档类内容按需要可设起步或可选。
 
@@ -249,8 +259,8 @@ npm run typecheck && npm run build && npm run selftest
 ## 8. 验证
 
 - `npm run typecheck` / `npm run build`：编译与打包；
-- `npm run selftest`：5d 段覆盖注册表清单（9 项，含 `core` / `removable` / `startup`）、**启动只 seed 核心 + 起步项（5 项）且不碰可选项**、手动全跑只写缺失、单跑幂等、force 重写、unknown id、tw-web-host 三分支（custom 保留 / force 写回 / legacy 修复）、**反初始化**（单移除 / 核心拒绝 / unknown / 全部移除保留核心）——另含 starter-docs 安全跳过、ui-styles 仅功能 tag、seed 版首页剥离私有人口 + 文档栏等断言；
-- `node scripts/verify-seeds-admin.mjs`：全新 wiki + 真实 HTTP，端到端验证 `GET /admin/seeds` 状态流转（9 项全缺失 → 启动后核心+起步就绪、可选项仍缺失）与 `POST /admin/seeds/run`（force 单跑恢复被改坏的首页、非 force 不覆盖用户内容、force-all 恢复代理基址、unknown id 400）+ `POST /admin/seeds/remove`（移除非核心、核心 400、remove-all 仅剩核心）。
+- `npm run selftest`：5d 段覆盖注册表清单（10 项，含 `core` / `removable` / `startup`）、**启动只 seed 核心 + 起步项（5 项）且不碰可选项**、手动全跑只写缺失、单跑幂等、force 重写、unknown id、tw-web-host 三分支（custom 保留 / force 写回 / legacy 修复）、**反初始化**（单移除 / 核心拒绝 / unknown / 全部移除保留核心）——另含 starter-docs 安全跳过、ui-styles 仅功能 tag、seed 版首页剥离私有人口 + 文档栏等断言；
+- `node scripts/verify-seeds-admin.mjs`：全新 wiki + 真实 HTTP，端到端验证 `GET /admin/seeds` 状态流转（10 项全缺失 → 启动后核心+起步就绪、可选项仍缺失）与 `POST /admin/seeds/run`（force 单跑恢复被改坏的首页、非 force 不覆盖用户内容、force-all 恢复代理基址、unknown id 400）+ `POST /admin/seeds/remove`（移除非核心、核心 400、remove-all 仅剩核心）。
 
 ---