dsh-tiddlywiki

TiddlyWiki 5 as the DSH persistent knowledge base — a shared long-term memory for AI and human: the agent reads/writes tiddlers through tiddlywiki_* tools, you edit in a full TiddlyWiki editor or jot notes in a floating widget, and everything syncs/backs up through git.

等 Agent 干活的时候，人常是干坐着的——想随手写点什么，又不想切来切去。TiddlyWiki 单文件、纯文本、wiki 语法、自带 git 同步，天生适合随手写点小东西。于是把它做成 DSH 原生插件：不用离开当前界面，聊天区右下角就有快速笔记；要正经编辑，弹出 TW 原生编辑器；写下的内容自动进 git，既是知识库也是备份。

✨ 特性一览

📦 安装

插件随 dsh 插件系统安装，三种方式任选（装完重启 dsh web 生效；把 --profile web 换成你自己的 profile 名）：

# ① npm 发布包（推荐）
dsh plugin --profile web add dsh-tiddlywiki

# ② 直接从 GitHub 安装（需要 git；仓库已含预构建 lib，开箱即用）
dsh plugin --profile web add github:bbqisbbq/dsh-tiddlywiki

# ③ 本地开发 / 改源码（link 方式：改完 src 后 npm run build 即生效，免重装）
dsh plugin --profile web add link:/path/to/your/dsh-tiddlywiki

首次启动会自动完成三件事：初始化 wiki 目录、git init 并提交基线、向 wiki 写入一次「dsh-tiddlywiki 插件说明」笔记（tag docs）。

🚀 快速开始（2 分钟上手）

1. 安装并重启 dsh web（见上）。
2. 点左侧侧边栏「TiddlyWiki」→ 中央打开完整 TW 编辑器；此时右下角已有「知识库」悬浮按钮（内含快速笔记/同步/TW 面板入口）。
3. 随手记：点右下角「知识库」→「📝 快速笔记」，写两行、打上 tag，Ctrl+Enter 保存——它成为一个独立 tiddler，并自动进入 git；草稿会自动保存到本地，关掉/刷新都不丢。
4. 正经排版：在笔记里点「✏️ 在 TW 中编辑」，弹出 TW 原生编辑器小窗继续写；想接着改旧笔记，点「🕘 最近」一键载入。
5. 收工同步：点「知识库」→「🔁 同步」，一键 pull → commit → push，把今天的记录推到远端备份。
6. 让 Agent 参与：直接在聊天里说「把刚才的会议纪要存进知识库」——Agent 会用 tiddlywiki_* 工具读写。

想直接看 Agent 侧完整能力？跳到 📖 使用指南。

📖 使用指南

🤖 给 Agent：10 个工具

知识库同步纪律（四条）：

1. 开工先 tiddlywiki_git_sync action=pull（rebase + autostash；真冲突会自动 abort 并报冲突文件）。
2. 冲突后：tiddlywiki_git_resolve files=[冲突文件] strategy=keep-local|keep-remote 按 tiddler 二选一解决，再重新 sync。
3. 收工 tiddlywiki_git_sync action=sync（pull → commit → push）。
4. 插件自动 commit 兜底（60s 防抖，可关），手动 sync 用于需要主动推送的场合。

⚠️ pull 若拉到新内容，pull / sync 会自动重启 TW（同端口），后续读写/搜索都是最新快照，不会读到旧缓存。

建议：把 wiki 当作长期记忆库——会议纪要、决策记录、调研笔记、随手的想法都可存成独立 tiddler（tag 建议 inbox / meeting / decision 等便于检索）；自动建笔记时，除业务 tag 外也带上当前 workspace 名，方便按项目归集。

🧑‍💻 给人：界面操作

🧭 中央列编辑器 — 侧边栏「TiddlyWiki」按钮开关中央编辑器面板（同源代理：iframe 指向 <DSH origin>/dsh-tiddlywiki/tw/，由 DSH 转发到回环上的 TW 服务），完整 TW 5 编辑器。

📝 快速笔记 — 右下角「知识库」悬浮按钮 →「📝 快速笔记」（可折叠）：

• CodeMirror 6 编辑器：真正的 Markdown 语法树高亮（标题/列表/代码/链接/表格/任务清单/删除线等，GFM），支持撤销/重做与行内编辑体验；
• 草稿自动保存：正文/标题/标签 500ms 防抖写入本地，关掉卡片或刷新页面都不丢；重开自动恢复，可一键「丢弃」；
• 🕘 最近：一键列出最近修改的笔记，点标题直接载入编辑器继续改（不需要开完整 TW 去找）；
• 文件上传：点「📎 上传」或直接把文件拖进编辑器——文件存到 wiki 的 files/ 文件夹并随 git 同步；图片插入 ![名](https://cdnimage-cache.doubi.ren/?url=https://raw.githubusercontent.com/bbqisbbq/dsh-tiddlywiki/main/dsh-tiddlywiki/tw/files/名)、其它文件插入 [名](https://github.com/dsh-tiddlywiki/tw/files/名)（同源代理 URL，在 TW 与快速笔记预览里都能打开）；
• Ctrl+Enter 保存为独立 tiddler；笔记 type 自动设为 text/markdown，所以上传的图片/链接在 TW 里按 Markdown 正常渲染；
• 点「✏️ 在 TW 中编辑」→ 保存后弹出独立小窗（可拖动/缩放）加载 TW 原生编辑器编辑该条。

🔧 一键同步 + 面板 —「知识库」按钮是一个统一入口，替代了旧版三个叠在右下角的悬浮按钮：

• 🖥 打开/收起 TW 面板 与 🔄 重载 TW 面板（ui.showPanelStatus 控制）；
• 📝 快速笔记（ui.showQuickNote 控制）；
• 🔁 同步：pull → commit → push；FAB 右下角的状态点实时反映 git 状态：
  🟢 已同步 · 🟡 有未提交改动 · 🔴 落后于远端 · ⚪ 离线；悬停可看分支/领先/落后/上次同步时间；每 30s 自动刷新。
  若这次 pull 拉到了新内容，TW 服务自动重启（同端口），界面立即显示最新快照（无需手动去面板点「重启 TW」）。

🔧 面板异常 — 面板服务异常时显示错误 +「重试」按钮（POST /dsh-tiddlywiki/restart）。

⚙️ 设置页（DSH 设置 →「TiddlyWiki 知识库」）

• 配置写入 wiki 内的 $:/plugins/dsh-tiddlywiki/config tiddler（JSON），随 git 同步，作为 cordis config: 块之上的覆盖层（tiddler 优先）。
• git 类配置修改后重启 dsh web 生效（bootstrap 时读取）。
• 插件/主题/语言只管理 tiddlywiki 包自带的官方清单（plugins/tiddlywiki/*、themes/tiddlywiki/*、包根 languages/*），全部离线、官方原版。

主题机制（重点）：TW 视觉主题由 $:/theme tiddler 决定，info.themes 只决定加载哪些主题插件。主题之间有依赖链（plugin.info 的 dependents）：vanilla ← snowwhite ← heavier/centralised/readonly/starlight，vanilla ← tight/seamless。设置页因此是两层：每行主题一个 ☑ 加载（多选 = TW 里可用的主题）+ ◉ 活动（单选 = 当前视觉主题）。应用时插件会：

1. 把加载集（含所选活动主题）的完整依赖链写入 info.themes（如 heavier → [vanilla, snowwhite, heavier]），否则激活 heavier 时会丢掉 70KB 的 vanilla 基座样式；
2. 把 $:/theme 设为所选活动主题，然后重启 TW。

样式为空壳的主题（如 tight-heavier）会自动从清单里隐藏，避免选了没效果。

🌐 界面语言（中文）

TW 的界面语言由语言插件决定，不是某个配置字符串。tiddlywiki 包自带全部官方语言包（node_modules/tiddlywiki/languages/，含 zh-Hans 简体、zh-CN、zh-Hant、en-GB、ja-JP…），本插件离线启用即可：

• 设置页 → 语言管理：勾选 zh-Hans（简体）→「应用语言（重启 TW）」——写入 tiddlywiki.info 的 languages 数组并固定 $:/language 为 $:/languages/zh-Hans，重启后 TW 界面即简体中文（持久化，重启仍在）。
• 配置自动应用：在常规配置写入 uiLanguage: "zh-Hans"，每次启动 dsh web 时自动启用该语言并固定 $:/language（若尚未启用）。留空则不干预。
• 想换繁中：语言管理里改勾 zh-Hant / zh-TW 再应用。

🌐 远程访问（Tailscale / 内网 / 域名 / HTTPS）

TW 子进程只监听 127.0.0.1 回环（更安全），agent 工具、快速笔记、git 同步本来就全程走 DSH 宿主进程→回环 TW，所以无论你从哪个入口访问 DSH，这些能力都不受影响。唯一受影响的是浏览器里的 TW 编辑器 iframe：早期版本让 iframe 直接指向 http://127.0.0.1:<port>——只有浏览器和 DSH 在同一台机器时才行；一旦通过 Tailscale / 内网 IP / 域名访问 DSH，127.0.0.1 会指向浏览器自己那台机器，编辑器就加载不出来了。

从 v0.6.0 起，内嵌编辑器改为同源代理：

• 浏览器里的 TW 编辑器 iframe 指向 <DSH origin>/dsh-tiddlywiki/tw/（与 DSH 同源），DSH 把整个 TW 前端（页面 + /files/* + TiddlyWeb API）透传到回环上的 TW 服务；
• TW 前端的 API 基址由 wiki 内的 $:/config/tiddlyweb/host 控制，插件启动时把它固定为 /dsh-tiddlywiki/tw/（仅当缺失或仍是旧默认值时写入，用户自定义会被保留）；
• 因为代理 URL 与端口无关，TW 重启也不会让编辑器 iframe 重新加载，编辑中的内容不丢。

效果：DSH 跑在服务器上、你用 Tailscale / 域名 / 内网 IP 从任意设备打开 DSH Web 时，中央列编辑器和「在 TW 中编辑」弹窗都正常工作；以后 DSH 挂到域名 + HTTPS 反向代理后面也同样成立（同源、无 mixed-content、无 CORS）。

⚠️ 迁移说明：v0.6.0 之前上传的文件在笔记里写的是根路径 /files/名，本插件不再占用 DSH 根命名空间（避免与其他插件冲突），所以这些旧链接在嵌入编辑器里会失效；新上传的文件使用 /dsh-tiddlywiki/tw/files/名 前缀 URL，可直接打开。若需要旧链接，可在 TW 里把对应笔记的 /files/ 前缀改回 /dsh-tiddlywiki/tw/files/。

🔄 同步与数据

• wiki 文件夹本身就是一个 git 仓库（默认 $DSH_HOME/tiddlywiki，wiki 子目录为内容）。插件自动维护 .gitignore（忽略 TW 临时文件）与自动 commit（默认 60s 防抖）。
• 同步模型：单线程交替——开工 pull，收工 commit + push；冲突策略是 rebase + autostash，真冲突 abort 并报文件，绝不自动吞数据。
• 配置远端（git.remote）后，插件首次启动会 ensureRemote 并尝试首次 push；失败可稍后用 tiddlywiki_git_sync 或「同步」按钮重试。
• 插件配置（config tiddler）随 wiki 的 git 同步；插件本体（cordis 行与配置块）随 profile 被 dsh-market 带走。

🛠 配置

插件行默认如下（缺省即用默认值，无需手动配置）。如需自定义，编辑 profiles/web/cordis.patch.yml 或 profile 的 bundle 层，给该行加 config:：

- id: dsh-tiddlywiki
  name: dsh-tiddlywiki
  config:
    wikiRoot: "$DSH_HOME/tiddlywiki"   # 缺省自动展开
    wiki: "main"
    port: 0                            # 0 = 自动探测空闲端口
    git:
      autoCommit: true
      debounceMs: 60000
      remote: ""                       # 空 = 仅本地 commit；填了才 push
      branch: "main"
    note:
      tag: "inbox"
    ui:
      showQuickNote: true           # 是否显示「知识库」按钮里的「快速笔记」入口
      showPanelStatus: true         # 是否显示「知识库」按钮里的 TW 面板/重载入口与状态行
      showSyncButton: true          # 是否显示「知识库」按钮里的「同步」入口与 git 状态点
    auth:
      username: ""                     # 默认 loopback 匿名；暴露到非 loopback 时才需要
      password: ""

运行时配置：设置页写入的 $:/plugins/dsh-tiddlywiki/config tiddler 是 config: 块之上的覆盖层（tiddler 优先、随 wiki 的 git 同步）。无需改动 cordis 也能改 note tag / git 开关 / ui 开关等。
config: 块随 profile 被 dsh-market 带走；wiki 数据走 git，不走 dsh-market。

远程访问（v0.6.0）：TW 前端的 API 基址来自 $:/config/tiddlyweb/host，插件启动时固定为 /dsh-tiddlywiki/tw/（同源代理）。TW 子进程始终只监听 127.0.0.1；auth.username/password 仅在你想把 TW 直接暴露到非回环地址（绕过 DSH）时才需要，正常情况下无需配置。

👨‍💻 开发

需要 Node.js ≥ 22（DSH 本身已满足）。

npm install
npm run typecheck     # tsc --noEmit
npm run build         # clean + host tsdown + client tsdown + wrap
npm run selftest      # headless：spawn TW → REST 读写 → git → 退出回收

产物约定（发布必守）：lib/ 内零 @deepseek-ai 运行时 import（src/sdk.ts 自实现 defineTool / dshHomePath，类型用结构接口）。发布前用 grep -r "@deepseek-ai" lib/ 验证。

客户端依赖：快速笔记编辑器用 CodeMirror 6（@codemirror/*、@lezer/*）做 Markdown 高亮，构建时由 tsdown 打包进 lib/client.bundle.js（它们放在 devDependencies，因为运行时用的是预构建 bundle，用户安装无需拉取）。「零依赖自研高亮」已成历史——浏览器端只要求构建产物自包含。

路由参考（开发者）

同源路由（走 DSH web server），Client 直连、无 CORS：

📦 发布

# 版本号在 package.json；文件白名单见 files 字段
npm publish

tiddlywiki 依赖体较大（含全部语言包/插件），发布文档需注明。

🗂 项目结构

src/
├── index.ts            # host 入口：装配 WikiServer/路由/工具/prompt/自动 commit
├── sdk.ts              # 自包含 defineTool + dshHomePath（零 @deepseek-ai 运行时依赖）
├── host/
│   ├── wiki.ts         # WikiServer：spawn/kill/自愈/端口探测/就绪轮询；TW_PROXY_PATH 同源代理路径
│   ├── tw-api.ts       # TiddlyWeb REST 客户端
│   ├── git.ts          # git init/commit/pull/push/sync/status + AutoCommitter
│   ├── routes.ts       # /status /note /edit /tags /sync /upload /restart /api/* /tw/* 路由
│   ├── admin.ts        # 设置页后台：tiddlywiki.info 读写 + 目录枚举 + /admin/* 路由
│   ├── config.ts       # ConfigStore：cordis config 基底 + 配置 tiddler 覆盖层
│   ├── seed-notes.ts   # 首次启动一次性写入「插件说明」笔记
│   └── tools.ts        # 5 个工具（列表式注册，可扩展）
└── client/
    ├── index.ts        # client 入口（纯 DOM + settings.section 注册，永不 throw）
    ├── styles.ts / state.ts / toast.ts
    ├── sidebar-entry.ts  # 侧边栏入口
    ├── panel.ts          # 中央列 iframe 面板（fixed 覆盖层，钉住整列）
    ├── note-widget.ts      # 悬浮快速笔记
    ├── markdown-editor.ts  # 快速笔记编辑器（CodeMirror 6 + Lezer Markdown 高亮）
    ├── sync-button.ts      # 一键同步悬浮按钮
    ├── editor-popup.ts     # 原生编辑器弹出小窗
    └── settings-page.ts    # 设置页（插件/主题/语言管理 + 常规配置）

🔗 仓库与发布元数据

• GitHub（公开）：https://github.com/bbqisbbq/dsh-tiddlywiki
• npm：dsh-tiddlywiki（https://www.npmjs.com/package/dsh-tiddlywiki）
• 说明笔记：插件在首次启动时向 wiki 写入一次「dsh-tiddlywiki 插件说明」笔记（tag docs）——只写一次、手动编辑不被覆盖、删除后重启不会自动恢复（一次性标记；清空 wiki 重装会再写入）。

可被检索的标准字段（为 GitHub / npm / 搜索引擎发现）：

GitHub topics 规范（官方文档）：仅小写字母/数字/连字符、≤50 字符、每仓库 ≤20 个；用官方 Replace all repository topics 端点（PUT /repos/{owner}/{repo}/topics）设置。上表已按此执行并覆盖「用途 / 主题 / 语言 / 技术栈」。