dsh-tiddlywiki 0.16.18 → 0.16.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +267 -263
  2. package/lib/client.bundle.js +23 -16
  3. package/lib/client.js +23 -16
  4. package/lib/index.js +133 -24
  5. package/lib/index.js.map +1 -1
  6. package/package.json +1 -1
  7. package/src/client/session-summary.ts +279 -478
  8. package/src/client/styles.ts +18 -11
  9. package/src/host/seed-home.ts +92 -92
  10. package/src/host/tools.ts +40 -5
  11. package/src/host/tw-api.ts +323 -231
  12. package/src/index.ts +4 -4
package/README.md CHANGED
@@ -1,263 +1,267 @@
1
- # dsh-tiddlywiki
2
-
3
- > 把 **TiddlyWiki 5** 变成 DSH 的**持久知识库**：Agent 用 `tiddlywiki_*` 工具读写笔记，你在界面里用完整 TW 编辑器或快速笔记记录，一切通过 **git** 自动同步备份。
4
-
5
- [![npm](https://img.shields.io/npm/v/dsh-tiddlywiki)](https://www.npmjs.com/package/dsh-tiddlywiki)
6
- [![license](https://img.shields.io/npm/l/dsh-tiddlywiki)](https://github.com/bbqisbbq/dsh-tiddlywiki/blob/main/LICENSE)
7
- [![GitHub](https://img.shields.io/github/stars/bbqisbbq/dsh-tiddlywiki)](https://github.com/bbqisbbq/dsh-tiddlywiki)
8
-
9
- ---
10
-
11
- ## ✨ 特性一览
12
-
13
- | 能力 | 说明 |
14
- |---|---|
15
- | 🤖 **Agent 工具** | 10 个 `tiddlywiki_*` 工具：检索、读写、批量、重命名、删除、git 同步与冲突解决 |
16
- | 📊 **回复流卡片** | 工具结果显示原生 TW 卡片；`[标题](/dsh-tiddlywiki/tw/#标题)` 点击直达 TW 面板 |
17
- | 📤 **发送给 Agent** | TW 笔记工具栏一键把当前笔记注入所选 dsh 会话（可选工作模式/权限/附加说明） |
18
- | 🧭 **内嵌编辑器** | 中央列内嵌完整 TW 5 编辑器（同源代理，Tailscale/内网/域名/HTTPS 均可） |
19
- | 📚 **会话知识库 Tab** | 每个会话顶部汇总本会话读写过的 wiki 笔记，TW 原生渲染 |
20
- | 📝 **快速笔记** | 输入框上方快捷按钮或右下角「知识库」FAB；原生编辑页或 Markdown 卡片两种模式 |
21
- | 🌗 **跟随主题** | 内嵌 TW 自适应 DSH 深浅主题（纯内存切换，不进 git） |
22
- | 🔄 **一键同步** | FAB「同步」一键 pull→commit→push，状态点实时反映 git 状态 |
23
- | 💾 **数据即备份** | wiki 文件夹本身就是 git 仓库，自动 commit（60s 防抖） |
24
-
25
- ---
26
-
27
- ## 📦 安装
28
-
29
- ```bash
30
- # ① npm 发布包（推荐）
31
- dsh plugin --profile web add dsh-tiddlywiki
32
-
33
- # ② 直接从 GitHub 安装
34
- dsh plugin --profile web add github:bbqisbbq/dsh-tiddlywiki
35
-
36
- # ③ 本地开发（link 方式，改完 src 后 npm run build 即生效）
37
- dsh plugin --profile web add link:/path/to/dsh-tiddlywiki
38
- ```
39
-
40
- 装完**重启 dsh web** 生效。首次启动自动完成：初始化 wiki 目录、`git init` 并提交基线、写入**功能必需**的 seed（「发送给 Agent」按钮 + 同源代理基址）。可选项（说明笔记/首页/所有文章/menubar 主题）需在设置页「初始化」手动写入。
41
-
42
- ---
43
-
44
- ## 🚀 快速开始
45
-
46
- 1. **安装并重启** dsh web。
47
- 2. 侧边栏「**TiddlyWiki**」→ 中央打开完整 TW 编辑器。
48
- 3. **随手记**：点输入框上方「📝」或右下角「知识库」→「快速笔记」，写完保存即成为 tiddler 并自动进 git。
49
- 4. **收工同步**：「知识库」→「🔁 同步」一键 push 备份。
50
- 5. **让 Agent 参与**：直接说「把刚才的会议纪要存进知识库」——Agent 用 `tiddlywiki_*` 工具读写。
51
- 6. **发笔记给 Agent**：TW 里打开笔记 → 工具栏「发送给 Agent」→ 选会话 → 作为消息注入。
52
-
53
- ---
54
-
55
- ## 📖 使用指南
56
-
57
- ### 🤖 Agent 工具（10 个）
58
-
59
- | 工具 | 说明 |
60
- |---|---|
61
- | `tiddlywiki_search` | 检索（`query` + 可选 `tags[]/tag/since/type/limit`），返回标题/标签/修改时间/摘要 |
62
- | `tiddlywiki_recent` | 最近修改的笔记（倒序），开工快速了解动态 |
63
- | `tiddlywiki_list_tags` | 现有非系统 tag 及计数 |
64
- | `tiddlywiki_get` | 读单个 tiddler 全文 |
65
- | `tiddlywiki_put` | 写/覆盖；未指定类型时自动默认 `text/markdown`（`$:/` 系统条目除外） |
66
- | `tiddlywiki_batch_put` | 批量写入（`overwrite=false` 跳过已存在） |
67
- | `tiddlywiki_rename` | 重命名 + 尽量同步其他条目里的引用 |
68
- | `tiddlywiki_delete` | 删除（幂等） |
69
- | `tiddlywiki_git_sync` | `action: pull\|push\|sync` |
70
- | `tiddlywiki_git_resolve` | pull 冲突后按 tiddler 二选一（`keep-local\|keep-remote`） |
71
-
72
- **知识库同步纪律**：
73
- 1. 开工先 `tiddlywiki_git_sync action=pull`（rebase + autostash，真冲突会 abort 并报文件）。
74
- 2. 冲突后用 `tiddlywiki_git_resolve` 二选一解决，再重新 sync（**绝不自动覆盖**）。
75
- 3. 收工 `tiddlywiki_git_sync action=sync`（pull → commit → push）。
76
-
77
- > ⚠️ `fields.type` 是 TW 的**内容类型保留字段**（`text/markdown` 等），业务分类请放 `tags`，别写进 `fields.type`。
78
-
79
- ### 🧑💻 界面操作
80
-
81
- - **📤 发送给 Agent**：TW 工具栏按钮（首次启动自动写入 wiki，ONE-SHOT）。弹层可选**附加说明**（位于消息末尾）、**工作模式**（Agent 预设）、**权限**（权限预设），按工作区分组选会话或新建。消息自带待办说明。
82
- - **🧭 中央列编辑器**：侧边栏「TiddlyWiki」开关（显示名可改 `ui.sidebarLabel`）。
83
- - **📝 快速笔记**：输入框上方快捷按钮（`ui.showQuickNoteDock`）或 FAB；`ui.quickNoteMode` 选打开方式——**native**（默认，直达 TW 原生编辑页，草稿自动续写）或 **card**（CodeMirror 6 Markdown 高亮、文件上传、多选 tag、草稿自动保存、「🕘 最近」载入、Ctrl+Enter 保存）。
84
- - **📚 会话知识库 Tab**：会话顶部 Tab（`ui.tabLabel` 改名、`ui.showSessionTab` 关闭），自动汇总本会话读写过的 wiki 笔记（写入 volatile `$:/temp`，不落盘不进 git），不可编辑。
85
- - **🌗 跟随 DSH 主题**：内嵌 TW 随 DSH 深浅切换 palette，纯内存不写回 wiki（`ui.followDshTheme`/`ui.darkPalette`）。
86
- - **🔧 知识库 FAB**：统一入口（TW 面板开关/重载、快速笔记、同步、TW 服务状态悬停 tip）。同步拉取到新内容会自动重启 TW（同端口）。
87
- - **⚙️ 设置页**：DSH 设置 →「TiddlyWiki 知识库」：状态/重启、常规配置、插件/主题/语言管理、**初始化**（seed 状态与重新初始化）。配置写入 `$:/plugins/dsh-tiddlywiki/config` tiddler，覆盖 cordis `config:` 块（tiddler 优先）。
88
-
89
- ### 🧩 初始化（一次性预置）
90
-
91
- seed 注册表分两层（详细见 [docs/seed-initialization.md](docs/seed-initialization.md)）：
92
-
93
- - **核心项**（功能必需，首次启动自动写入、不可移除）：`send-to-agent`（发送按钮）、`render-route`（原生渲染路由）、`tw-web-host`（同源代理基址）。
94
- - **可选项**（默认不写，设置页可「重新初始化」/「反初始化」）：`doc-note`（说明笔记）、`home-index`（首页 🏠 主页/所有标签/标签笔记 + `$:/DefaultTiddlers`）、`all-articles`（所有文章两列分页）、`menubar-theme`（menubar 顶栏跟随主题）。
95
-
96
- 语义：**ONE-SHOT**——只写缺失、绝不覆盖你的改动；删掉重启不会自动恢复（用「重新初始化」找回）。
97
-
98
- ---
99
-
100
- ## 🛠 配置
101
-
102
- 插件行默认配置（缺省即默认，无需手动配置）：
103
-
104
- ```yaml
105
- - id: dsh-tiddlywiki
106
- config:
107
- wikiRoot: "$DSH_HOME/tiddlywiki" # 缺省自动展开
108
- wiki: "main"
109
- port: 0 # 0 = 自动探测空闲端口
110
- git:
111
- autoCommit: true
112
- debounceMs: 60000
113
- remote: "" # 空 = 仅本地 commit；填了才 push
114
- branch: "main"
115
- note:
116
- tag: "inbox" # 快速笔记默认 tag
117
- ui:
118
- showQuickNote: true # FAB 里显示快速笔记入口
119
- showQuickNoteDock: true # 输入框上方快捷按钮
120
- quickNoteMode: "native" # native=TW 原生编辑页 / card=Markdown 卡片
121
- sidebarLabel: "TiddlyWiki" # 侧边栏入口显示名
122
- showPanelStatus: true
123
- showSyncButton: true
124
- followDshTheme: true # 跟随 DSH 深浅主题
125
- darkPalette: "$:/palettes/CupertinoDark"
126
- tabLabel: "知识库" # 会话 Tab 名
127
- showSessionTab: true
128
- sendToAgent: { enabled: true }
129
- uiLanguage: "" # 留空不干预；"zh-Hans" 自动启用简体
130
- auth:
131
- username: "" # 默认 loopback 匿名；暴露到非回环才需要
132
- password: ""
133
- ```
134
-
135
- > **运行时配置**：设置页写入的 `$:/plugins/dsh-tiddlywiki/config` tiddler 是 `config:` 块之上的覆盖层（tiddler 优先、随 wiki git 同步），改 note tag / git / ui 开关无需动 cordis。
136
-
137
- ---
138
-
139
- ## 🌐 远程访问
140
-
141
- TW 子进程只监听 **127.0.0.1 回环**；Agent 工具/快速笔记/同步都走 DSH 宿主进程→回环 TW，不受访问入口影响。浏览器里的 TW 编辑器 iframe 经**同源代理** `<DSH origin>/dsh-tiddlywiki/tw/` 访问（v0.6.0 起），所以通过 Tailscale / 内网 / 域名 / HTTPS 访问 DSH 时编辑器照常工作，且 TW 重启不打断编辑中的内容。
142
-
143
- ---
144
-
145
- ## 👨‍💻 开发
146
-
147
- 需要 **Node.js ≥ 22**。
148
-
149
- ```bash
150
- npm install
151
- npm run typecheck # tsc --noEmit
152
- npm run build # clean + host tsdown + client tsdown + wrap
153
- npm run selftest # headless：spawn TW → REST 读写 → git → 退出回收
154
- ```
155
-
156
- **改 bundle/seed 的再生成流水线**（不要手改 `seed-*.ts` 里的生成常量）：
157
-
158
- ```bash
159
- # 发送给 Agent 按钮（改 scripts/bundle/send-to-agent/ 后）
160
- node scripts/build-send-to-agent-bundle.mjs
161
- node scripts/gen-seed-send-to-agent.mjs scripts/bundle/send-to-agent.bundle.json src/host/seed-send-to-agent.ts
162
- node scripts/verify-send-to-agent-bundle.mjs
163
-
164
- # 渲染路由（改 scripts/bundle/render/server-routes/render.js 后）
165
- node scripts/build-render-bundle.mjs
166
- node scripts/gen-seed-render.mjs scripts/bundle/render.bundle.json src/host/seed-render.ts
167
-
168
- # 首页（改 wiki 的 🏠 主页/所有标签/标签笔记 .tid 后）
169
- node scripts/gen-seed-home.mjs '<wiki>/tiddlers/🏠 主页.tid' '<wiki>/tiddlers/所有标签.tid' '<wiki>/tiddlers/标签笔记.tid' src/host/seed-home.ts
170
-
171
- # 随后 npm run build
172
- ```
173
-
174
- **产物约定**：`lib/` 内**零** `@deepseek-ai` 运行时 import；client 必须 minify（否则 >1MB 被注册表校验拒绝）；`react`/`tiddlywiki` 不打包（运行时解析）。
175
-
176
- ### 路由参考（开发者）
177
-
178
- | 路由 | 方法 | 用途 |
179
- |---|---|---|
180
- | `/dsh-tiddlywiki/status` | GET | 面板健康（service/url/git/tag/ui） |
181
- | `/dsh-tiddlywiki/note` `/edit` `/tags` `/recent` `/get` `/search` | POST/GET | 快速笔记、打开编辑器、tag/最近/单个/搜索 |
182
- | `/dsh-tiddlywiki/sync` `/upload` `/restart` | POST | 一键同步、文件上传、重启 TW |
183
- | `/dsh-tiddlywiki/session/summary` | POST | 会话「知识库」Tab 汇总 |
184
- | `/dsh-tiddlywiki/agent/sessions` `/modes` `/send` `/create` | GET/POST | TW「发送给 Agent」：会话/模式/发送/新建 |
185
- | `/dsh-tiddlywiki/api/*` | any | 透传 TW 服务（JSON） |
186
- | `/dsh-tiddlywiki/tw/*` | any | 同源 TW 代理（远程访问核心） |
187
- | `/dsh-tiddlywiki/admin/seeds` `/run` `/remove` | GET/POST | seed 状态 / 运行 / 反初始化 |
188
-
189
- ### 项目结构
190
-
191
- ```
192
- src/
193
- ├── index.ts # host 入口：装配 WikiServer/路由/工具/提示词/自动 commit
194
- ├── sdk.ts # 自包含 defineTool + dshHomePath（零 @deepseek-ai 运行时依赖）
195
- ├── host/
196
- │ ├── wiki.ts # WikiServer：spawn/kill/自愈/端口探测/就绪轮询；TW_PROXY_PATH 同源代理
197
- │ ├── tw-api.ts # TiddlyWeb REST 客户端
198
- │ ├── git.ts # git init/commit/pull/push/sync/status + AutoCommitter
199
- │ ├── routes.ts # 全部 DSH 路由 + agent-send/create/modes + session/summary
200
- │ ├── http.ts # 共用 HTTP 助手（readBody/json）
201
- │ ├── session-summary.ts # 会话「知识库」Tab 后端
202
- │ ├── admin.ts # 设置页后台：tiddlywiki.info 读写 + /admin/*
203
- │ ├── config.ts # ConfigStore：cordis config 基底 + 配置 tiddler 覆盖层
204
- │ ├── seeds.ts # 统一 seed 注册表（7 项：check/run(force)/remove）
205
- │ ├── seed-*.ts # 各 seed 实现（bundle/首页常量由脚本生成，勿手改）
206
- │ └── tools.ts # 10 个 tiddlywiki_* 工具（列表式注册）
207
- └── client/ # 浏览器半部
208
- ├── index.ts # client 入口（inject ['slots']，纯 DOM，永不 throw）
209
- ├── endpoints.ts # 客户端同源端点常量
210
- ├── knowledge-fab.ts / quick-note-dock.ts / note-widget.ts / editor-popup.ts
211
- │ # 知识库 FAB / 快捷按钮 / 快速笔记 / 原生编辑弹窗
212
- ├── markdown-editor.ts # CodeMirror 6 Markdown 编辑器
213
- ├── session-summary.ts # 会话「知识库」Tab（conversation.view 槽位）
214
- ├── tool-views.ts # 回复流工具卡片（tool.call.toolview）
215
- ├── theme-sync.ts / panel.ts / sidebar-entry.ts / sync-button.ts
216
- └── settings-page.ts / ui-config.ts / state.ts / styles.ts / toast.ts
217
- scripts/ # 构建/校验/再生成脚本
218
- docs/seed-initialization.md # seed 机制详解（权威）
219
- lib/ # 预构建产物（发布含 lib/**，提交入库；零 @deepseek-ai 运行时 import）
220
- ```
221
-
222
- ---
223
-
224
- ## 🕘 版本记录
225
-
226
- > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
227
-
228
- - **v0.16.18**（2026-09-07）：README 全面精简重写；seed 优化——首页 seed 跟随 wiki 现状（🏠 主页）、修「所有文章」回主页死链、doc-note 文案修正。
229
- - **v0.16.17**（2026-09-07）：点击快速笔记可选直达 TW 原生编辑页（`ui.quickNoteMode`）+ 修「在 TW 中编辑」弹窗 ✕ 关不掉。
230
- - **v0.16.16**（2026-09-07）：修会话知识库 Tab 误入编辑草稿显示源码——三层防误编辑（清残留草稿/吞草稿创建/禁 ✏️）。
231
- - **v0.16.15**（2026-09-07）：`put`/`batch_put` 未指定类型自动默认 `text/markdown`；警告 `fields.type` 是内容类型保留字段。
232
- - **v0.16.14**（2026-09-07）：修知识库 Tab「佚失条目」根因——浏览器端 TW 天生排除 `$:/temp`，改为 iframe 就绪后注入 + 原生 hash 导航。
233
- - **v0.16.11**（2026-09-06）：新增会话顶部「知识库」Tab（本会话相关 wiki 汇总，volatile `$:/temp`）。
234
- - **v0.16.0**（2026-09-05）：回复流原生 TW 工具卡片 + 可点击 wiki 链接（新增 `render-route` seed）。
235
- - **v0.15.0**（2026-09-05）：初始化不强制 + 可反初始化（seed 拆核心/可选两层）。
236
- - **v0.14.0**（2026-09-05）：「发送给 Agent」按钮独立图标 + 附加说明 + 权限选择。
237
- - **v0.13.0**（2026-09-04）：menubar 顶栏主题自适应。
238
- - **v0.12.0**（2026-09-04）：新默认主页 + 「所有文章」两列分页页。
239
- - **v0.11.0**（2026-09-04）：「发送给 Agent」支持选择工作模式（Agent 预设）。
240
- - **v0.10.0**（2026-09-04）：统一 seed 注册表 + 设置页「初始化」。
241
- - **v0.8.0**（2026-09-04）：嵌入式 TW 跟随 DSH 深浅主题。
242
- - **v0.7.0**（2026-09-03）：TW 一键把当前笔记发送到 dsh 会话。
243
- - **v0.6.0**（2026-09-03）：同源代理（远程访问核心）。
244
- - **v0.5.0**（2026-09-03）：Agent 工具扩充 + 快速笔记草稿自动保存 + 统一知识库 FAB。
245
-
246
- ---
247
-
248
- ## 📦 发布
249
-
250
- ```bash
251
- npm publish # 版本号在 package.json；文件白名单见 files 字段
252
- ```
253
-
254
- `tiddlywiki` 依赖体较大（含全部语言包/插件）。
255
-
256
- ---
257
-
258
- ## 🔗 仓库与发布元数据
259
-
260
- - **GitHub**：https://github.com/bbqisbbq/dsh-tiddlywiki
261
- - **npm**：`dsh-tiddlywiki`（https://www.npmjs.com/package/dsh-tiddlywiki）
262
- - 说明笔记、首页、所有文章等预置内容由 seed 机制写入 wiki（见 [🧩 初始化](#🧩-初始化一次性预置)）
263
- - MIT；Node ≥ 22；GitHub topics：`dsh` `dsh-plugin` `tiddlywiki` `knowledge-base` `note-taking` `git-sync` `agent-tools` 等
1
+ # dsh-tiddlywiki
2
+
3
+ > 把 **TiddlyWiki 5** 变成 DSH 的**持久知识库**：Agent 用 `tiddlywiki_*` 工具读写笔记，你在界面里用完整 TW 编辑器或快速笔记记录，一切通过 **git** 自动同步备份。
4
+
5
+ [![npm](https://img.shields.io/npm/v/dsh-tiddlywiki)](https://www.npmjs.com/package/dsh-tiddlywiki)
6
+ [![license](https://img.shields.io/npm/l/dsh-tiddlywiki)](https://github.com/bbqisbbq/dsh-tiddlywiki/blob/main/LICENSE)
7
+ [![GitHub](https://img.shields.io/github/stars/bbqisbbq/dsh-tiddlywiki)](https://github.com/bbqisbbq/dsh-tiddlywiki)
8
+
9
+ ---
10
+
11
+ ## ✨ 特性一览
12
+
13
+ | 能力 | 说明 |
14
+ |---|---|
15
+ | 🤖 **Agent 工具** | 10 个 `tiddlywiki_*` 工具：检索、读写、批量、重命名、删除、git 同步与冲突解决（v0.16.20 起检索/最近在**服务端**排除二进制附件，大 wiki 上从 515MB/17s 降到 ~0.4s） |
16
+ | 📊 **回复流卡片** | 工具结果显示原生 TW 卡片；`[标题](/dsh-tiddlywiki/tw/#标题)` 点击直达 TW 面板 |
17
+ | 📤 **发送给 Agent** | TW 笔记工具栏一键把当前笔记注入所选 dsh 会话（可选工作模式/权限/附加说明） |
18
+ | 🧭 **内嵌编辑器** | 中央列内嵌完整 TW 5 编辑器（同源代理，Tailscale/内网/域名/HTTPS 均可） |
19
+ | 📚 **会话知识库 Tab** | 每个会话顶部汇总本会话读写过的 wiki 笔记，TW 原生渲染（`/tw/render` 片段管线，v0.16.19） |
20
+ | 📝 **快速笔记** | 输入框上方快捷按钮或右下角「知识库」FAB；原生编辑页或 Markdown 卡片两种模式 |
21
+ | 🌗 **跟随主题** | 内嵌 TW 自适应 DSH 深浅主题（纯内存切换，不进 git） |
22
+ | 🔄 **一键同步** | FAB「同步」一键 pull→commit→push，状态点实时反映 git 状态 |
23
+ | 💾 **数据即备份** | wiki 文件夹本身就是 git 仓库，自动 commit（60s 防抖） |
24
+
25
+ ---
26
+
27
+ ## 📦 安装
28
+
29
+ ```bash
30
+ # ① npm 发布包（推荐）
31
+ dsh plugin --profile web add dsh-tiddlywiki
32
+
33
+ # ② 直接从 GitHub 安装
34
+ dsh plugin --profile web add github:bbqisbbq/dsh-tiddlywiki
35
+
36
+ # ③ 本地开发（link 方式，改完 src 后 npm run build 即生效）
37
+ dsh plugin --profile web add link:/path/to/dsh-tiddlywiki
38
+ ```
39
+
40
+ 装完**重启 dsh web** 生效。首次启动自动完成：初始化 wiki 目录、`git init` 并提交基线、写入**功能必需**的 seed（「发送给 Agent」按钮 + 同源代理基址）。可选项（说明笔记/首页/所有文章/menubar 主题）需在设置页「初始化」手动写入。
41
+
42
+ ---
43
+
44
+ ## 🚀 快速开始
45
+
46
+ 1. **安装并重启** dsh web。
47
+ 2. 侧边栏「**TiddlyWiki**」→ 中央打开完整 TW 编辑器。
48
+ 3. **随手记**：点输入框上方「📝」或右下角「知识库」→「快速笔记」，写完保存即成为 tiddler 并自动进 git。
49
+ 4. **收工同步**：「知识库」→「🔁 同步」一键 push 备份。
50
+ 5. **让 Agent 参与**：直接说「把刚才的会议纪要存进知识库」——Agent 用 `tiddlywiki_*` 工具读写。
51
+ 6. **发笔记给 Agent**：TW 里打开笔记 → 工具栏「发送给 Agent」→ 选会话 → 作为消息注入。
52
+
53
+ ---
54
+
55
+ ## 📖 使用指南
56
+
57
+ ### 🤖 Agent 工具（10 个）
58
+
59
+ | 工具 | 说明 |
60
+ |---|---|
61
+ | `tiddlywiki_search` | 检索（`query` + 可选 `tags[]/tag/since/type/limit`），返回标题/标签/修改时间/摘要 |
62
+ | `tiddlywiki_recent` | 最近修改的笔记（倒序），开工快速了解动态 |
63
+ | `tiddlywiki_list_tags` | 现有非系统 tag 及计数 |
64
+ | `tiddlywiki_get` | 读单个 tiddler 全文 |
65
+ | `tiddlywiki_put` | 写/覆盖；未指定类型时自动默认 `text/markdown`（`$:/` 系统条目除外） |
66
+ | `tiddlywiki_batch_put` | 批量写入（`overwrite=false` 跳过已存在） |
67
+ | `tiddlywiki_rename` | 重命名 + 尽量同步其他条目里的引用 |
68
+ | `tiddlywiki_delete` | 删除（幂等） |
69
+ | `tiddlywiki_git_sync` | `action: pull\|push\|sync` |
70
+ | `tiddlywiki_git_resolve` | pull 冲突后按 tiddler 二选一（`keep-local\|keep-remote`） |
71
+
72
+ **知识库同步纪律**：
73
+ 1. 开工先 `tiddlywiki_git_sync action=pull`（rebase + autostash，真冲突会 abort 并报文件）。
74
+ 2. 冲突后用 `tiddlywiki_git_resolve` 二选一解决，再重新 sync（**绝不自动覆盖**）。
75
+ 3. 收工 `tiddlywiki_git_sync action=sync`（pull → commit → push）。
76
+
77
+ > 🔍 **检索/最近跳过二进制附件**（v0.16.20）：`search`/`recent` 在**服务端**只取文本 tiddler（无 `type` 字段或 `text/*`），图片/音频/视频/PDF/zip 等二进制 tiddler（base64 正文）不参与检索、不出现在结果里——大 wiki（如数千张书籍扫描页图）从此从 515MB/17s 降到 ~0.4s，也不会被同名书页图刷屏。`get` 对二进制 tiddler 只返回元数据（`binary=true` + 类型/大小 + 链接），不返回 base64 正文。
78
+
79
+ > ⚠️ `fields.type` 是 TW 的**内容类型保留字段**（`text/markdown` 等），业务分类请放 `tags`，别写进 `fields.type`。
80
+
81
+ ### 🧑💻 界面操作
82
+
83
+ - **📤 发送给 Agent**：TW 工具栏按钮（首次启动自动写入 wiki，ONE-SHOT）。弹层可选**附加说明**（位于消息末尾）、**工作模式**（Agent 预设）、**权限**（权限预设），按工作区分组选会话或新建。消息自带待办说明。
84
+ - **🧭 中央列编辑器**：侧边栏「TiddlyWiki」开关（显示名可改 `ui.sidebarLabel`）。
85
+ - **📝 快速笔记**：输入框上方快捷按钮（`ui.showQuickNoteDock`）或 FAB；`ui.quickNoteMode` 选打开方式——**native**（默认，直达 TW 原生编辑页，草稿自动续写）或 **card**（CodeMirror 6 Markdown 高亮、文件上传、多选 tag、草稿自动保存、「🕘 最近」载入、Ctrl+Enter 保存）。
86
+ - **📚 会话知识库 Tab**：会话顶部 Tab（`ui.tabLabel` 改名、`ui.showSessionTab` 关闭），自动汇总本会话读写过的 wiki 笔记（写入 volatile `$:/temp`，不落盘不进 git），**TW 原生渲染**（v0.16.19 起 `/tw/render` 片段管线，与回复流工具卡同链路，不再用 iframe/story view），链接点击直达中央 TW 面板，不可编辑。
87
+ - **🌗 跟随 DSH 主题**：内嵌 TW 随 DSH 深浅切换 palette，纯内存不写回 wiki（`ui.followDshTheme`/`ui.darkPalette`）。
88
+ - **🔧 知识库 FAB**：统一入口（TW 面板开关/重载、快速笔记、同步、TW 服务状态悬停 tip）。同步拉取到新内容会自动重启 TW（同端口）。
89
+ - **⚙️ 设置页**：DSH 设置 →「TiddlyWiki 知识库」：状态/重启、常规配置、插件/主题/语言管理、**初始化**（seed 状态与重新初始化）。配置写入 `$:/plugins/dsh-tiddlywiki/config` tiddler，覆盖 cordis `config:` 块（tiddler 优先）。
90
+
91
+ ### 🧩 初始化（一次性预置）
92
+
93
+ seed 注册表分两层（详细见 [docs/seed-initialization.md](docs/seed-initialization.md)）：
94
+
95
+ - **核心项**（功能必需，首次启动自动写入、不可移除）：`send-to-agent`（发送按钮）、`render-route`（原生渲染路由）、`tw-web-host`（同源代理基址）。
96
+ - **可选项**（默认不写，设置页可「重新初始化」/「反初始化」）：`doc-note`（说明笔记）、`home-index`（首页 🏠 主页/所有标签/标签笔记 + `$:/DefaultTiddlers`）、`all-articles`（所有文章两列分页）、`menubar-theme`（menubar 顶栏跟随主题）。
97
+
98
+ 语义：**ONE-SHOT**——只写缺失、绝不覆盖你的改动；删掉重启不会自动恢复（用「重新初始化」找回）。
99
+
100
+ ---
101
+
102
+ ## 🛠 配置
103
+
104
+ 插件行默认配置（缺省即默认，无需手动配置）：
105
+
106
+ ```yaml
107
+ - id: dsh-tiddlywiki
108
+ config:
109
+ wikiRoot: "$DSH_HOME/tiddlywiki" # 缺省自动展开
110
+ wiki: "main"
111
+ port: 0 # 0 = 自动探测空闲端口
112
+ git:
113
+ autoCommit: true
114
+ debounceMs: 60000
115
+ remote: "" # 空 = 仅本地 commit；填了才 push
116
+ branch: "main"
117
+ note:
118
+ tag: "inbox" # 快速笔记默认 tag
119
+ ui:
120
+ showQuickNote: true # FAB 里显示快速笔记入口
121
+ showQuickNoteDock: true # 输入框上方快捷按钮
122
+ quickNoteMode: "native" # native=TW 原生编辑页 / card=Markdown 卡片
123
+ sidebarLabel: "TiddlyWiki" # 侧边栏入口显示名
124
+ showPanelStatus: true
125
+ showSyncButton: true
126
+ followDshTheme: true # 跟随 DSH 深浅主题
127
+ darkPalette: "$:/palettes/CupertinoDark"
128
+ tabLabel: "知识库" # 会话 Tab 名
129
+ showSessionTab: true
130
+ sendToAgent: { enabled: true }
131
+ uiLanguage: "" # 留空不干预；"zh-Hans" 自动启用简体
132
+ auth:
133
+ username: "" # 默认 loopback 匿名；暴露到非回环才需要
134
+ password: ""
135
+ ```
136
+
137
+ > **运行时配置**：设置页写入的 `$:/plugins/dsh-tiddlywiki/config` tiddler 是 `config:` 块之上的覆盖层（tiddler 优先、随 wiki git 同步），改 note tag / git / ui 开关无需动 cordis。
138
+
139
+ ---
140
+
141
+ ## 🌐 远程访问
142
+
143
+ TW 子进程只监听 **127.0.0.1 回环**；Agent 工具/快速笔记/同步都走 DSH 宿主进程→回环 TW，不受访问入口影响。浏览器里的 TW 编辑器 iframe 经**同源代理** `<DSH origin>/dsh-tiddlywiki/tw/` 访问（v0.6.0 起），所以通过 Tailscale / 内网 / 域名 / HTTPS 访问 DSH 时编辑器照常工作，且 TW 重启不打断编辑中的内容。
144
+
145
+ ---
146
+
147
+ ## 👨‍💻 开发
148
+
149
+ 需要 **Node.js ≥ 22**。
150
+
151
+ ```bash
152
+ npm install
153
+ npm run typecheck # tsc --noEmit
154
+ npm run build # clean + host tsdown + client tsdown + wrap
155
+ npm run selftest # headless：spawn TW → REST 读写 → git → 退出回收
156
+ ```
157
+
158
+ **改 bundle/seed 的再生成流水线**（不要手改 `seed-*.ts` 里的生成常量）：
159
+
160
+ ```bash
161
+ # 发送给 Agent 按钮（改 scripts/bundle/send-to-agent/ 后）
162
+ node scripts/build-send-to-agent-bundle.mjs
163
+ node scripts/gen-seed-send-to-agent.mjs scripts/bundle/send-to-agent.bundle.json src/host/seed-send-to-agent.ts
164
+ node scripts/verify-send-to-agent-bundle.mjs
165
+
166
+ # 渲染路由（改 scripts/bundle/render/server-routes/render.js 后）
167
+ node scripts/build-render-bundle.mjs
168
+ node scripts/gen-seed-render.mjs scripts/bundle/render.bundle.json src/host/seed-render.ts
169
+
170
+ # 首页（改 wiki 的 🏠 主页/所有标签/标签笔记 .tid 后）
171
+ node scripts/gen-seed-home.mjs '<wiki>/tiddlers/🏠 主页.tid' '<wiki>/tiddlers/所有标签.tid' '<wiki>/tiddlers/标签笔记.tid' src/host/seed-home.ts
172
+
173
+ # 随后 npm run build
174
+ ```
175
+
176
+ **产物约定**：`lib/` 内**零** `@deepseek-ai` 运行时 import；client 必须 minify（否则 >1MB 被注册表校验拒绝）；`react`/`tiddlywiki` 不打包（运行时解析）。
177
+
178
+ ### 路由参考（开发者）
179
+
180
+ | 路由 | 方法 | 用途 |
181
+ |---|---|---|
182
+ | `/dsh-tiddlywiki/status` | GET | 面板健康（service/url/git/tag/ui） |
183
+ | `/dsh-tiddlywiki/note` `/edit` `/tags` `/recent` `/get` `/search` | POST/GET | 快速笔记、打开编辑器、tag/最近/单个/搜索 |
184
+ | `/dsh-tiddlywiki/sync` `/upload` `/restart` | POST | 一键同步、文件上传、重启 TW |
185
+ | `/dsh-tiddlywiki/session/summary` | POST | 会话「知识库」Tab 汇总 |
186
+ | `/dsh-tiddlywiki/agent/sessions` `/modes` `/send` `/create` | GET/POST | TW「发送给 Agent」：会话/模式/发送/新建 |
187
+ | `/dsh-tiddlywiki/api/*` | any | 透传 TW 服务（JSON） |
188
+ | `/dsh-tiddlywiki/tw/*` | any | 同源 TW 代理（远程访问核心） |
189
+ | `/dsh-tiddlywiki/admin/seeds` `/run` `/remove` | GET/POST | seed 状态 / 运行 / 反初始化 |
190
+
191
+ ### 项目结构
192
+
193
+ ```
194
+ src/
195
+ ├── index.ts # host 入口：装配 WikiServer/路由/工具/提示词/自动 commit
196
+ ├── sdk.ts # 自包含 defineTool + dshHomePath（零 @deepseek-ai 运行时依赖）
197
+ ├── host/
198
+ │ ├── wiki.ts # WikiServer：spawn/kill/自愈/端口探测/就绪轮询；TW_PROXY_PATH 同源代理
199
+ │ ├── tw-api.ts # TiddlyWeb REST 客户端
200
+ │ ├── git.ts # git init/commit/pull/push/sync/status + AutoCommitter
201
+ │ ├── routes.ts # 全部 DSH 路由 + agent-send/create/modes + session/summary
202
+ │ ├── http.ts # 共用 HTTP 助手（readBody/json）
203
+ │ ├── session-summary.ts # 会话「知识库」Tab 后端
204
+ │ ├── admin.ts # 设置页后台：tiddlywiki.info 读写 + /admin/*
205
+ │ ├── config.ts # ConfigStore：cordis config 基底 + 配置 tiddler 覆盖层
206
+ │ ├── seeds.ts # 统一 seed 注册表（7 项：check/run(force)/remove）
207
+ │ ├── seed-*.ts # 各 seed 实现（bundle/首页常量由脚本生成，勿手改）
208
+ │ └── tools.ts # 10 个 tiddlywiki_* 工具（列表式注册）
209
+ └── client/ # 浏览器半部
210
+ ├── index.ts # client 入口（inject ['slots']，纯 DOM，永不 throw）
211
+ ├── endpoints.ts # 客户端同源端点常量
212
+ ├── knowledge-fab.ts / quick-note-dock.ts / note-widget.ts / editor-popup.ts
213
+ │ # 知识库 FAB / 快捷按钮 / 快速笔记 / 原生编辑弹窗
214
+ ├── markdown-editor.ts # CodeMirror 6 Markdown 编辑器
215
+ ├── session-summary.ts # 会话「知识库」Tab（conversation.view 槽位）
216
+ ├── tool-views.ts # 回复流工具卡片（tool.call.toolview）
217
+ ├── theme-sync.ts / panel.ts / sidebar-entry.ts / sync-button.ts
218
+ └── settings-page.ts / ui-config.ts / state.ts / styles.ts / toast.ts
219
+ scripts/ # 构建/校验/再生成脚本
220
+ docs/seed-initialization.md # seed 机制详解（权威）
221
+ lib/ # 预构建产物（发布含 lib/**，提交入库；零 @deepseek-ai 运行时 import）
222
+ ```
223
+
224
+ ---
225
+
226
+ ## 🕘 版本记录
227
+
228
+ > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
229
+
230
+ - **v0.16.20**（2026-09-09）：**修：`search`/`recent` 在大 wiki 上超时**。根因：列表请求把全部 tiddler（含图片等二进制附件）的 base64 正文拉回来（2418 个 tiddler ≈ 515MB/17s，超过 10s 请求超时）。修复：`search`/`recent`/`get` 在**服务端**只取文本 tiddler（无 `type` 或 `text/*`）——用外部 filter `[all[tiddlers]!is[system]!has[type]] [all[tiddlers]!is[system]regexp:type[(?i)^text/]]`（含 `$:/config/Server/ExternalFilters/<filter>` 白名单自愈，403 时自动 PUT 重试，仍 403 降级瘦身列表）；二进制 tiddler 完全排除（含标题命中，防同名书页图刷屏），`get` 对二进制只回元数据（`binary=true`/`binaryType`/`binaryChars` + 链接）。实测线上 wiki（2418 tiddler/958 图）：515MB/17s → **6.24MB/0.3s**，图片零泄漏。⚠️ 白名单 tiddler 文件名含整个 filter 串——filter 必须短（此前 180 字符版在 Windows 上把文件名顶到 217 字符，撑爆 MAX_PATH 使 `git add` 报 "Filename too long"、自动 commit 失效；selftest 已把该场景纳入回归）。代价：`application/json` 等类型 tiddler 不进检索（本 wiki 无此类，且多为配置数据）。
231
+ - **v0.16.19**（2026-09-07）：**修：会话「知识库」Tab 把汇总当源码显示（整页 wikitext、像包在代码标签里）**。根因（headless $tw 实测）：TW 5.4.1 核心的视图模板级联（`$:/config/ViewTemplateBodyFilters/system` 的 system 规则）把所有 `$:/temp/` 前缀 tiddler 一律按**代码块**渲染（`$:/core/ui/ViewTemplate/body/code` → `<pre><code>`）——因此即便 v0.16.14+ 把 volatile 条目注入 iframe store 再原生导航，story view 仍把汇总当源码展示。修复：客户端**不再用 iframe / story view**，改走与回复流工具卡同一条原生渲染管线——`POST /tw/render {title}`（服务端把汇总 wikitext 块解析成 HTML 片段，`[[链接]]` 重写为 `/dsh-tiddlywiki/tw/#标题`）→ 注入滚动容器（样式复用 `.dsh-tw-toolcard-native` 的 tc-* 重主题）；片段内链接点击仍打开中央 TW 面板。无 iframe → 无编辑按钮/草稿，v0.16.16 的三层防误编辑随之不再需要；保留 30s 自愈（volatile 条目被清自动重建）与「🔄 刷新」。**刷新页面**即生效。
232
+ - **v0.16.18**（2026-09-07）：README 全面精简重写；seed 优化——首页 seed 跟随 wiki 现状（🏠 主页）、修「所有文章」回主页死链、doc-note 文案修正。
233
+ - **v0.16.17**（2026-09-07）：点击快速笔记可选直达 TW 原生编辑页（`ui.quickNoteMode`）+ 修「在 TW 中编辑」弹窗 ✕ 关不掉。
234
+ - **v0.16.16**（2026-09-07）：修会话知识库 Tab 误入编辑草稿显示源码——三层防误编辑（清残留草稿/吞草稿创建/禁 ✏️）。
235
+ - **v0.16.15**（2026-09-07）：`put`/`batch_put` 未指定类型自动默认 `text/markdown`；警告 `fields.type` 是内容类型保留字段。
236
+ - **v0.16.14**（2026-09-07）：修知识库 Tab「佚失条目」根因——浏览器端 TW 天生排除 `$:/temp`，改为 iframe 就绪后注入 + 原生 hash 导航。
237
+ - **v0.16.11**（2026-09-06）：新增会话顶部「知识库」Tab（本会话相关 wiki 汇总，volatile `$:/temp`）。
238
+ - **v0.16.0**（2026-09-05）：回复流原生 TW 工具卡片 + 可点击 wiki 链接（新增 `render-route` seed）。
239
+ - **v0.15.0**（2026-09-05）：初始化不强制 + 可反初始化（seed 拆核心/可选两层）。
240
+ - **v0.14.0**（2026-09-05）：「发送给 Agent」按钮独立图标 + 附加说明 + 权限选择。
241
+ - **v0.13.0**（2026-09-04）：menubar 顶栏主题自适应。
242
+ - **v0.12.0**（2026-09-04）：新默认主页 + 「所有文章」两列分页页。
243
+ - **v0.11.0**（2026-09-04）：「发送给 Agent」支持选择工作模式（Agent 预设）。
244
+ - **v0.10.0**（2026-09-04）：统一 seed 注册表 + 设置页「初始化」。
245
+ - **v0.8.0**（2026-09-04）：嵌入式 TW 跟随 DSH 深浅主题。
246
+ - **v0.7.0**（2026-09-03）：TW 一键把当前笔记发送到 dsh 会话。
247
+ - **v0.6.0**（2026-09-03）：同源代理（远程访问核心）。
248
+ - **v0.5.0**（2026-09-03）：Agent 工具扩充 + 快速笔记草稿自动保存 + 统一知识库 FAB。
249
+
250
+ ---
251
+
252
+ ## 📦 发布
253
+
254
+ ```bash
255
+ npm publish # 版本号在 package.json；文件白名单见 files 字段
256
+ ```
257
+
258
+ `tiddlywiki` 依赖体较大（含全部语言包/插件）。
259
+
260
+ ---
261
+
262
+ ## 🔗 仓库与发布元数据
263
+
264
+ - **GitHub**：https://github.com/bbqisbbq/dsh-tiddlywiki
265
+ - **npm**：`dsh-tiddlywiki`（https://www.npmjs.com/package/dsh-tiddlywiki）
266
+ - 说明笔记、首页、所有文章等预置内容由 seed 机制写入 wiki（见 [🧩 初始化](#🧩-初始化一次性预置)）
267
+ - MIT；Node ≥ 22；GitHub topics：`dsh` `dsh-plugin` `tiddlywiki` `knowledge-base` `note-taking` `git-sync` `agent-tools` 等