dsh-tiddlywiki

给 DSH 装一个你自己的知识库：你在界面里读、写、记日记，Agent 用同一批笔记干活。 纯文本 + git，能读、能改、能带走。

它不是自动记忆插件。 不后台抓取、不向量召回、不在你不知道的情况下"记住"什么——每条笔记都是你能打开、能审、能 git diff 的文件。要不要让 Agent 看，由你决定。

⚡ 30 秒上手

dsh plugin --profile web add dsh-tiddlywiki

重启 dsh web。首次启动自动完成：建 wiki 目录、git init 提交基线、写入起步文档（插件说明 + 示例与文档）。不需要先配任何东西。

1. 侧边栏 TiddlyWiki → 中央列打开完整 TW 编辑器
2. 输入框上方 📝 或右下角 知识库 → 快速记一条（写完即进 git）
3. 直接说「把这段存进知识库」→ Agent 用 tiddlywiki_* 工具读写
4. 收工点 🔁 同步 → pull → commit → push

想用已有的文件夹当库？设置页「知识库位置」里切换，不用改配置、不用重装。

🎯 适合谁 / 不适合谁

适合：想要一个本地、纯文本、能随时带走的长期笔记库，并且愿意让 Agent 读写同一批文件的人；已经在用 Obsidian / Logseq、但缺"Agent 也能进"这一层的人。

不适合：想要"装完就自动记住我说过的一切"的人（那是另一类插件：自动抽取 + 向量召回 + 后台注入；本插件不做后台抓取）；完全不想碰 TiddlyWiki 心智模型的人——它需要一次五分钟的理解。

✨ 它好在哪

| | | |---|---| | 👥 人和 Agent 同一份库 | 你在 TW 里读写的，就是 Agent 读写的；不是"我写给你看"，也不是"它记它的" | | 🛡 写入不会吃掉你的东西 | 所有写路径先读后写：不传 tags 就保留原标签/字段/内容类型；同名默认拒绝覆盖；删除进回收站可恢复；可选 expectedModified 乐观并发（读后被改过就拒绝写入，而不是静默覆盖） | | 🚰 重启不丢写入 | 停/重启 TW 只有一条路：先排干 syncer 队列再停，排不干净会如实报 drained:false | | 🕰 可审计、可回溯 | 库本身就是 git 仓库（自动 commit + 一键同步）；反向链接、标签、体检（lint）；阶段性内容可标 valid-until / superseded-by，淘汰永远由人决定，插件不自动删 | | 📦 数据可带走 | 磁盘上就是 .md + .meta + .tid + files/，不需要这个插件也能读 | | 📮 可选发布 | 打开后能把笔记一键发到微信公众号草稿箱（默认关闭，不打扰） |

🤖 Agent 工具（15 个）

search（先在工作区内查、0 条才扩全库） · get · put · batch_put · append（增量追加，可指定标题段落） · rename（含引用改写） · delete（默认进回收站） · trash · backlinks · attach（图片/PDF 入库） · lint（死链/空笔记/时效） · recent · list_tags · git_sync · git_resolve

每个工具的完整参数与语义见 docs/usage.md。

🔧 配置

插件向每个会话注入一段可配置的提示词（默认精简版 ~1.9KB，可整体关掉或替换），其余配置在设置页：知识库位置、git（自动提交/远端/分支）、笔记标签与工作区标记、快速笔记、剪藏桥、公众号发布、界面语言、访问口令。

完整配置项与远程访问（Tailscale / 内网 / 域名）见 docs/usage.md。

📚 文档

| 想看什么 | 去哪 | |---|---| | 完整能力清单（每条的为什么） | docs/features.md | | 使用指南 / 工具参考 / 配置 / 远程访问 | docs/usage.md | | 发布到微信公众号（可选，需额外安装） | docs/wechat-publish-setup.md | | 把知识库拆成几个独立的小库（含可复制给 Agent 的提示词） | docs/wiki-split.md | | 开发与发布流程（给维护者） | docs/development.md | | 完整版本变更历史 | docs/CHANGELOG.md |

🕘 版本记录

• v0.28.10（2026-09-28）：修「图标弹层出现在设置弹窗后面、被遮挡」（作者 v0.28.9 重启后实测报障）。根因是层级用错了数：设置页是 DSH 的 Modal，渲染进 portal 且根层就是 position:fixed; z-index:1000（dsh-client-ui-primitives/Modal.module.css），而我把弹层写成 z-index:60 —— z-index 只在同一个层叠上下文里比较，所以"写了 60"看着有值、整层仍被 Modal 盖住。现在改为 1100：这不是随手挑的大数，而是 DSH 自己给「锚点在对话框内部的浮层」定的值（Menu.module.css 的 .portal，注释原话 "Portaled lists must layer above modal overlays (z 1000) — an anchor inside a dialog still expects its menu on top"），对齐它即高于 Modal(1000)，且与我们自己的 toast(10001) 不冲突。守门断言弹层 z-index ≥ 1100（已反向验证：改回 60 → 红）。顺带补了一条 styles.ts 模板串守门：CSS 正文里出现反引号会让模板串提前结束、构建到一半失败（本仓库踩过两次，v0.28.9 我又踩了一次 —— 在注释里用行内代码记号解释 z-index）。这条守门的第一版是错的、值得记：它检查「第一个闭引号之前有没有反引号」，可一旦正文多了反引号，那个反引号本身就变成了闭引号的位置，于是"没有反引号"永远成立 —— 用出错的输入去验证出错的解析器，必然假绿。改成检查「模板串是否被提前截断」（正文须以 CSS 注释开头、以 } 结尾；闭引号后必须紧跟正常模块代码），再注入反引号即稳定变红。

• v0.28.9（2026-09-28）：修「点击图标没有正常弹出」（作者重启后实测报障）。根因：v0.28.8 的图标弹层只写了 DOM 与接线，styles.ts 里一条 CSS 都没有 —— 弹层照样被 append 到 document.body，但它是个无宽高约束的裸块、压在页面底部，视觉上就是「点了没反应」。现在补齐 .dsh-tw-iconpicker（含 position:fixed——它挂在 body 上，用 absolute 会被页面滚动带走）、8 列网格、格子（含当前项高亮）、分页器与按钮图标位共 12 条规则。守门一并补强：verify-wiki-focus.mjs 原先只断言「TS 源码里出现过 dsh-tw-iconpicker 这个字符串」—— 而 class 名当然会出现在 TS 里（它是 make() 的参数），所以组件没样式也照样绿。现在改为双向断言：弹层/网格/格子/分页器必须真有 CSS 规则，且 picker 里 make() 出来的每个 dsh-tw-* 类都必须在 styles.ts 里有下落（下次再加子元素忘写 CSS 会当场变红）。新断言已反向验证（删掉那段 CSS → 红）。顺带被这条新守门抓出第二处漏写：按钮文字位 .dsh-tw-settings-iconbtn-label 也没样式。教训：断言「某个类名存在」不等于断言「这个组件可用」 —— 渲染型组件的守门至少要跨两个文件，一个说"我生成了这个 DOM"，一个说"这个 DOM 有样式"。

• v0.28.8（2026-09-28）：多库第五批反馈：图标真能用了、设置页分页了、新会话也能选库了 + 拆大文件（12 条反馈一次做完）。① 图标选择器用上 DSH 官方图标系统 —— 从 8 个手绘图标扩到 36 个官方图标（内联的是上游 path 数据：客户端是纯 DOM、零运行时依赖）+ 8 个自绘 + 一组 emoji，弹出网格 48 个一页分页。② 修「选了图标立刻变回默认」 —— 根因在 /admin/wikis 的读取视图漏了 icon 字段：写进去了、读回来是 undefined，客户端拿它重渲染就回落默认，看起来完全像"没保存"。补上该字段，并加源码级守门钉死它（去掉修复即红）。③ 多库下设置页分页：十几块面板挤一页既分不清"改这个库"还是"改整个插件"、改完也没有退出口 —— 现在分「总览 / 本库配置 / 全局」三个 tab，「插件管理 / 主题管理 / 语言管理 / 初始化」这些 per-库面板只在点了某个库的「配置」之后才出现，按钮变成「退出配置」；单库安装没有 tab 条，逐字不变。④ 新会话也能选知识库：选择器此前只长在输入框上方（新会话还没有输入框），现在挂在预设/模式选择旁边 —— 声明感知注入 + 2 秒回落 + blankOnly，两种布局不会同时出现两个。⑤ 剪藏可指定落哪个库（bridge.wiki，设置页下拉，留空 = 默认库）。⑥ 回复流卡片、会话「知识库」Tab 按会话作用域取数：不这样做会出现"A 库的标题在 B 库里渲染成空白卡片"。⑦ 桌面版能起 TW 了：process.execPath 在桌面版里是 Electron，TW 根本起不来 —— 现在按 DSH_TIDDLYWIKI_NODE → where/which node → execPath 解析并缓存，行为级守门进 verify:unit。⑧ 代码清理：tools.ts 1913→132、admin.ts 1265→24、index.ts 1407→1001、note-widget.ts 1245→916、settings-page.ts 1815→400（全部纯搬移，注册顺序与装配顺序逐字保持），并新增 scripts/lib/source-family.mjs 让 12 个守门按「模块族」读源码 —— 以后纯搬迁不会再假红。⑨ 复核确认无需改动的两条：注入提示词本来就是按会话求值的（换库后下一步即生效，且读的是那个库自己的 prompt.*），15 个工具在多库下全部正常（回执在可见库 >1 时标明库名）。全链路复跑：typecheck / verify:static / verify:unit / verify:e2e / verify:large 全绿（含真起两个 TW 子进程、3100 条大库 64s）。 ① 图标选择器用上 DSH 官方图标系统 —— 从 8 个手绘图标扩到 36 个官方图标（内联的是上游 path 数据：客户端是纯 DOM、零运行时依赖）+ 8 个自绘 + 一组 emoji，弹出网格 48 个一页分页。② 修「选了图标立刻变回默认」 —— 根因在 /admin/wikis 的读取视图漏了 icon 字段：写进去了、读回来是 undefined，客户端拿它重渲染就回落默认，看起来完全像"没保存"。补上该字段，并加源码级守门钉死它（去掉修复即红）。③ 多库下设置页分页：十几块面板挤一页既分不清"改这个库"还是"改整个插件"、改完也没有退出口 —— 现在分「总览 / 本库配置 / 全局」三个 tab，「插件管理 / 主题管理 / 语言管理 / 初始化」这些 per-库面板只在点了某个库的「配置」之后才出现，按钮变成「退出配置」；单库安装没有 tab 条，逐字不变。④ 新会话也能选知识库：选择器此前只长在输入框上方（新会话还没有输入框），现在挂在预设/模式选择旁边 —— 声明感知注入 + 2 秒回落 + blankOnly，两种布局不会同时出现两个。⑤ 剪藏可指定落哪个库（bridge.wiki，设置页下拉，留空 = 默认库）。⑥ 回复流卡片、会话「知识库」Tab 按会话作用域取数：不这样做会出现"A 库的标题在 B 库里渲染成空白卡片"。⑦ 桌面版能起 TW 了：process.execPath 在桌面版里是 Electron，TW 根本起不来 —— 现在按 DSH_TIDDLYWIKI_NODE → where/which node → execPath 解析并缓存，行为级守门进 verify:unit。⑧ 代码清理：tools.ts 1913→132、admin.ts 1265→24、index.ts 1407→1001、note-widget.ts 1245→916、settings-page.ts 1815→400（全部纯搬移，注册顺序与装配顺序逐字保持），并新增 scripts/lib/source-family.mjs 让 12 个守门按「模块族」读源码 —— 以后纯搬迁不会再假红。⑨ 复核确认无需改动的两条：注入提示词本来就是按会话求值的（换库后下一步即生效，且读的是那个库自己的 prompt.*），15 个工具在多库下全部正常（回执在可见库 >1 时标明库名）。全链路复跑：typecheck / verify:static / verify:unit / verify:e2e / verify:large 全绿（含真起两个 TW 子进程、3100 条大库 64s）。

• v0.28.7（2026-09-28）：会话知识库选择器改成与「快速笔记」同一行 + 单库专属配置项不再在多库下出现（两条都是作者报障）。① 选择器"没和对话框对齐" —— 上次的修法方向就错了：conversation.input.dock 是竖向 flex 列，一个条目独占一整行，选择器和快速笔记是两个条目时永远是上下两行，怎么调内边距都不可能并排。现在选择器不再是独立条目，而是由快速笔记条目通过 scope 参数渲染在自己这一行里（按钮前面），整行统一与输入框右缘对齐，一行只测一次。顺手修掉合并时的一处遗留：选择器组件里还留着上一版的 alignDockEntry 自测，并入同一行后会把右内边距补两遍——已移除（wiki-scope 也从客户端 slot 表里消失，回归由 verify-wiki-focus.mjs 断言"input.dock 只能有一个条目"守住）。② 「侧边栏 TW 入口显示名称」在多库下不该出现 —— 多库时侧边栏是每个库各占一行、各用自己 wikis.json 里的显示名，ui.sidebarLabel 只喂单库那一行，所以多库下它是个改了不生效的假配置项。现在该字段只在单库模式渲染（多库时换成一行说明"去知识库列表改各自的显示名"）；模式探测失败回落成单库（保守：宁可多给一个真能用的字段，也不要因为一次请求失败把设置项藏了），并反向断言不许写成 !== 'single'（那会把未知模式误判成多库）。两条守门断言都做了反向验证。

• v0.28.6（2026-09-28）：修两个多库界面的真机报障。① 「插件管理 / 主题管理 / 语言包 / 初始化」看起来是混在一起管理的 —— 宿主侧一直是 per-request 解析目标库的（deps.server(req)/config(req)/getClient(req)），缺的是客户端那一半：设置页只有 state/config/prompt 三处带上了 ?wiki=，而插件信息与初始化 seed 的调用没带，于是它们永远落在默认库上，「切了库、面板内容却没变」。现在 7 个 per-wiki 端点全部经 withWiki()，并有守门逐个断言（去掉任一处的作用域 → 红）。单库（未选库）时 withWiki 原样返回 URL，现有用户逐字不变。② 左侧入口点一个却三个都高亮 —— 我上一版把「面板是共享的」错解成「所有行一起高亮」，但面板一次只显示一个库（当前焦点库）。现在只有那一行点亮，并订阅焦点变化重算；单库默认行在面板打开时仍正常高亮。两条守门断言都做了反向验证。

• v0.28.5（2026-09-28）：修「多库模式下侧边栏多出一个没有库名的 TiddlyWiki 入口」（作者报障）。根因是同一个 CSS 陷阱踩了第 12 次：hidden 属性在 CSS 里只是 display:none，而 .dsh-tw-entry 有显式 display:flex —— 显式 display 盖掉了 hidden，于是那行让位给每库入口的默认行照样渲染。这次不再给它单独补一条规则，而是收敃成一条全局兜底 [hidden] { display: none !important; }，并删掉本仓库历史上为此在不同元素上各补的 12 条逐元素规则（面板 iframe / 错误块 / 快速笔记 / FAB 菜单与提示 / 右侧栏 / 目标库下拉 / 草稿栏 / 最近列表…）。守门同时改为断言「全局兜底存在 + 不允许再出现逐元素版本」，并反向验证（把全局规则改成挂在类名下 → 红）。

• v0.28.4（2026-09-28）：每库自定义图标 + 修「右键菜单切库后选中项不更新」。① 右侧「知识库」菜单的选中项停在旧值 —— 根因是选中标记（●/○）只在菜单构建时算了一次，之后无论怎么切都不重画；现在改为从当前焦点重算，并在 setFocusWiki 订阅里即时重画、每次打开菜单前再兜一次（切库也可能来自侧边栏入口或快速笔记卡片）。② 每个库的入口图标可自定义：wikis.json 的条目新增可选 icon 字段，值可以是内置图形名（book / briefcase / home / notebook / flask / globe / star / archive，各是一枚继承 currentColor 的手写 16×16 线性 SVG，两套主题下都对）或一个短 emoji（📚 / 💼 / 🏠 …，用来一眼区分四五个库，不用下载任何资源）。设置页「知识库列表」每行多了图标下拉（当前值若不在候选里会保留，不会被抹掉）。校验口径：名字或 ≤8 字符的可打印短串，超长与控制字符一律拒绝；空值 = 清除自定义回落默认。emoji 用 textContent 渲染而不是 innerHTML —— 这个值来自用户可编辑的文件，绝不能变成注入点。缺省不设 = 内置默认图标，升级用户看到的一模一样。

• v0.28.3（2026-09-28）：修三个真机报障 + 插件说明补「多库 / 升级」两节（作者拆库实测中发现）。① 单库模式下快速笔记露出一个没有选项的下拉 —— 根因是 CSS hidden 只是 display:none，被显式 display 盖掉（修法：显式 [hidden]{display:none} + 组件兜底）。② 会话级选择器没和输入框对齐 —— 对齐规则原本只写在 quick-note 条目内部，已抽成 client/dock-align.ts 两处共用。③ 左侧入口按库显示：多库时每个在运行的库一个入口行、用各自显示名，点该行先切焦点库再开面板。④ 插件说明新增「多知识库」与「从旧版本升级上来」两节：明确升级后不会自动变成多库、wikis.json 在哪、旧指针文件何时还权威。守门扩到 19 条（含反向验证）。

• v0.28.2（2026-09-28）：设置页去掉重复的「知识库位置」（作者反馈：多库配置做完后它重复且逻辑冲突）。这一块的语义是「把唯一的那个库换到别处」——写的是 wiki 之外的指针文件 location.json，措辞也是单库时代的（"切换到这个位置" / "恢复为配置默认"）。现在按模式二选一：单库模式保留它（那里它是唯一正确入口）；多库模式整块不渲染，某个库换目录收到「知识库列表」那一行的**「改目录」（默认库经 /admin/wiki/switch → 改清单 + farm 收敛 + 校验；非默认库直接 update）。宿主接口没有冲突也没有改动：/admin/wiki/switch|reset 从 v0.28.0 起就按模式分派。守门：verify-wiki-focus 新增"多库模式下不得渲染该块"的断言；farm-boot 补上 location 面接线（22 条），保证藏了界面之后接口仍按模式正确分派**。

• v0.28.1（2026-09-28）：修「拆库 skill 在 wiki 启动慢 / 起不来时永远装不上」+ 快速笔记的目标库可切换（R7）。① 真实事故（作者升级 0.28.0 后重启宿主时发现，测试没拦住）：技能安装写在了 farm.startAll() 之后，而那个 wiki 很大、启动要几十秒 —— 于是"技能装没装"取决于"wiki 起得快不快"；更糟的是 wiki 若因配置问题永远起不来，技能就永远不装，而它跟 wiki 毫无关系（只往 $DSH_HOME/skills/ 写一个文件）。已挪到启动任务最前面并新增顺序守门（verify-skill-install 断言安装早于 startAll()，已反向验证）。② 快速笔记卡片新增「写入」目标库：默认跟随你在 GUI 里看的那个库（焦点库），卡片内可临时改、改过后不再被焦点带走。要点是整张卡片一起换库：标签建议 / 最近 / 草稿读取 / 附件上传 / 保存 / 随后弹出的 TW 编辑器必须落在同一个库 —— 只改保存那一处会产出"标签列表来自 A、笔记写进 B"，比不做还糟（弹窗那条另有一条守门：写入 A、编辑器打开 B（空白）是典型的"看起来成功了"的失败）。目标库没在运行时卡片先讲清楚，而不是让你写完一段再失败。单库安装不显示选择器、请求 URL 逐字不变。

• v0.28.0（2026-09-28）：多知识库——同一进程内可同时运行多个 TiddlyWiki，每个库独立配置、独立 git、按会话选择作用域，且可对 Agent 彻底隐身。起因是作者自己的库：书籍 语料 2468 条与日常笔记挤在一个 800MB 仓库里，Agent 检索/lint/backlink 每天在约 30 倍于工作集的内容上跑。拆库需要同时在线——只切换位置的话，你切到语料库翻资料时 Agent 也跟着切过去了。要点：① 三个模块各司其职（wiki-registry 清单/模式/动作、wiki-instance 单库运行时、wiki-farm 谁该在跑 + 会话作用域）；② 模式开关 wikis.json 的 mode（缺省 single，升级用户逐字不变）；③ 路由按库定向 /tw/<id>/…（每个库 seed 自己的同源基址——不区分 id 就会「页面显示 A、读写落在 B」），裸 /tw/ 仍是默认库别名，为此引入保留 id 名单；④ git 按仓库重构：多库可共用一个仓库，git add -A 只允许一个 committer，pull 后只重启受影响的库；⑤ Agent 侧：会话单选作用域 + agentVisible，工具回执在可见库多于一个时标明库名，注入提示词按会话求值并读作用域库的 prompt.*；两条刻意拒绝（隐身库→忽略；没在跑→报错而非静默换库）；⑥ GUI：输入框上方的会话选择器、FAB 的知识库分组、设置页「知识库列表」与显式配置作用域；⑦ 拆库引导 docs/wiki-split.md + 随包 skill（安装时只覆盖带标记的文件）。新增 6 个守门脚本（共约 96 条断言，含真起两个 TW 子进程与真 git 仓库两类集成验证），全部反向验证；4 个既有守门跟着间接层更新。未做：per-wiki 认证（auth.* 仍全局）、快速笔记目标切换策略。

• v0.27.3（2026-09-28）：修 v0.27.1 拆文档时打断的 6 个相对链接（docs/ 内的链接仍按仓库根写成 docs/xxx.md，从 docs/ 内部点击打不开）；新增守门 scripts/verify-doc-links.mjs（校验 README + docs/** 的全部相对链接，已挂进 verify:static，让这类错误下次发不出来）；修 CI 偶发假红：verify-wiki-switch 的回滚断言会抢在 TW 载入 store 之前读取，改为 15s 有界轮询后再断言。无运行时行为改动。

• v0.27.2（2026-09-28）：修本页一处指向不存在内容的死链（"不适合"那段曾让人去看 docs/features.md 末尾的说明，那里并没有）。纯文案，无代码改动。

• v0.27.1（2026-09-28）：README 从 175KB 精简成本页——原来 68% 的篇幅是变更历史。能力清单 / 使用指南 / 开发发布 / 完整变更历史拆到 docs/（内容未删），首页只留"是什么、怎么装、好在哪、适不适合你"。无代码改动。

更早版本 → docs/CHANGELOG.md

🔗 仓库与发布元数据

• GitHub：https://github.com/bbqisbbq/dsh-tiddlywiki ｜ npm：dsh-tiddlywiki
• 用得不顺请来提 issue：https://github.com/bbqisbbq/dsh-tiddlywiki/issues —— 这插件原本是作者给自己做的，现在有同道人用；你不报，我就不知道哪里不对。
• MIT；Node ≥ 22；GitHub topics：dsh dsh-plugin tiddlywiki knowledge-base knowledge-management note-taking journal git-sync local-first agent-tools publishing wechat 等