dsh-tiddlywiki 0.4.0 → 0.6.0

package/README.md

@@ -14,10 +14,10 @@
 
 | 能力 | 说明 |
 |---|---|
-| 🤖 **Agent 工具** | `tiddlywiki_search` / `get` / `put` / `delete` / `git_sync` 五个工具：检索、读写、删除、git 同步 |
-| 🧭 **内嵌编辑器** | 侧边栏「TiddlyWiki」入口 → 中央列内嵌完整 TW 5 编辑器（iframe 直连 TW 服务） |
-| 📝 **快速笔记** | 聊天区右下角悬浮控件：**CodeMirror 6** Markdown 编辑器（语法高亮 + 撤销/重做）、文件上传、多选/自动补全 tag，Ctrl+Enter 保存；可整体隐藏 |
-| 🔄 **一键同步** | 右下角「同步」按钮：pull → commit → push；状态点实时反映 git 状态（已同步/待提交/可更新/离线） |
+| 🤖 **Agent 工具** | `tiddlywiki_search` / `get` / `put` / `batch_put` / `rename` / `delete` / `recent` / `list_tags` / `git_sync` / `git_resolve` 十个工具：检索、读写、批量、重命名、删除、git 同步与冲突解决 |
+| 🧭 **内嵌编辑器** | 侧边栏「TiddlyWiki」入口 → 中央列内嵌完整 TW 5 编辑器（**同源代理**，经 DSH origin 访问，Tailscale/内网/域名/HTTPS 均可用） |
+| 📝 **快速笔记** | 右下角「知识库」悬浮按钮 → 快速笔记卡片：**CodeMirror 6** Markdown 编辑器（语法高亮 + 撤销/重做）、文件上传、多选/自动补全 tag、**草稿自动保存（刷新不丢）**、**「🕘 最近」一键载入旧笔记**，Ctrl+Enter 保存；可整体隐藏 |
+| 🔄 **一键同步** | 「知识库」按钮 →「🔁 同步」：pull → commit → push；FAB 上的状态点实时反映 git 状态（已同步/待提交/可更新/离线） |
 | ⚙️ **设置页** | DSH 设置 →「TiddlyWiki 知识库」：插件/主题/语言管理与运行配置，应用后自动重启 TW |
 | 🛡 **零摩擦生命周期** | 随 dsh 自动启停；TW 子进程崩溃自动重启（退避）；端口/目录/首次 git init 全自动 |
 | 💾 **数据即备份** | wiki 文件夹本身就是一个 git 仓库；自动 commit（60s 防抖，可关），配置随 dsh-market 迁移 |
@@ -46,10 +46,10 @@ dsh plugin --profile web add link:/path/to/your/dsh-tiddlywiki
 ## 🚀 快速开始（2 分钟上手）
 
 1. **安装并重启** dsh web（见上）。
-2. 点左侧侧边栏「**TiddlyWiki**」→ 中央打开完整 TW 编辑器；此时右下角已有「📝 快速笔记」和「🔄 同步」两个悬浮按钮。
-3. **随手记**：点右下角「快速笔记」，写两行、打上 tag，`Ctrl+Enter` 保存——它成为一个独立 tiddler，并自动进入 git。
-4. **正经排版**：在笔记里点「✏️ 在 TW 中编辑」，弹出 TW 原生编辑器小窗继续写。
-5. **收工同步**：点右下角「同步」按钮，一键 pull → commit → push，把今天的记录推到远端备份。
+2. 点左侧侧边栏「**TiddlyWiki**」→ 中央打开完整 TW 编辑器；此时右下角已有「**知识库**」悬浮按钮（内含快速笔记/同步/TW 面板入口）。
+3. **随手记**：点右下角「知识库」→「📝 快速笔记」，写两行、打上 tag，`Ctrl+Enter` 保存——它成为一个独立 tiddler，并自动进入 git；草稿会自动保存到本地，关掉/刷新都不丢。
+4. **正经排版**：在笔记里点「✏️ 在 TW 中编辑」，弹出 TW 原生编辑器小窗继续写；想接着改旧笔记，点「🕘 最近」一键载入。
+5. **收工同步**：点「知识库」→「🔁 同步」，一键 pull → commit → push，把今天的记录推到远端备份。
 6. **让 Agent 参与**：直接在聊天里说「把刚才的会议纪要存进知识库」——Agent 会用 `tiddlywiki_*` 工具读写。
 
 > 想直接看 Agent 侧完整能力？跳到 [📖 使用指南](#-使用指南)。
@@ -58,21 +58,27 @@ dsh plugin --profile web add link:/path/to/your/dsh-tiddlywiki
 
 ## 📖 使用指南
 
-### 🤖 给 Agent：5 个工具
+### 🤖 给 Agent：10 个工具
 
 | 工具 | 参数 | 说明 |
 |---|---|---|
-| `tiddlywiki_search` | `query`, `tag?` | 检索非系统 tiddler，返回标题/标签/摘要 |
+| `tiddlywiki_search` | `query`, `tags?[]`, `tag?`, `since?`, `type?`, `limit?` | 检索非系统 tiddler，返回标题/标签/修改时间/摘要；`tags` 为 AND 标签，`since` 按修改时间过滤，`limit` 上限 200 |
+| `tiddlywiki_recent` | `limit?`, `since?` | 最近修改的笔记（倒序），开工快速了解近期动态 |
+| `tiddlywiki_list_tags` | — | 现有非系统 tag 及各自计数（按使用次数降序） |
 | `tiddlywiki_get` | `title` | 读单个 tiddler 全文 |
 | `tiddlywiki_put` | `title`, `text`, `tags?`, `fields?` | 写/覆盖 tiddler；`fields` 可带业务字段（如 `{"type":"meeting","date":"2026-09-02"}`） |
+| `tiddlywiki_batch_put` | `items[]`, `overwrite?` | 批量写入；`overwrite=false` 跳过已存在标题 |
+| `tiddlywiki_rename` | `oldTitle`, `newTitle`, `updateRefs?` | 重命名 + 尽量更新其他 tiddler 里的 `[[旧]]`/`{{旧}}` 引用 |
 | `tiddlywiki_delete` | `title` | 删除 tiddler（幂等） |
 | `tiddlywiki_git_sync` | `action: pull\|push\|sync`, `message?` | git 操作 |
+| `tiddlywiki_git_resolve` | `files[]`, `strategy: keep-local\|keep-remote\|list` | pull 冲突后按 tiddler 二选一解决（keep-remote 需已配置远端） |
 
-**知识库同步纪律（三条）**：
+**知识库同步纪律（四条）**：
 
 1. 开工先 `tiddlywiki_git_sync action=pull`（rebase + autostash；真冲突会自动 abort 并报冲突文件）。
-2. 收工 `tiddlywiki_git_sync action=sync`（pull → commit → push）。
-3. 插件自动 commit 兜底（60s 防抖，可关），手动 sync 用于需要主动推送的场合。
+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（同端口）**，后续读写/搜索都是最新快照，不会读到旧缓存。
 
@@ -80,17 +86,22 @@ dsh plugin --profile web add link:/path/to/your/dsh-tiddlywiki
 
 ### 🧑‍💻 给人：界面操作
 
-**🧭 中央列编辑器** — 侧边栏「TiddlyWiki」按钮开关中央编辑器面板（iframe 直连 TW 服务），完整 TW 5 编辑器。
+**🧭 中央列编辑器** — 侧边栏「TiddlyWiki」按钮开关中央编辑器面板（**同源代理**：iframe 指向 `<DSH origin>/dsh-tiddlywiki/tw/`，由 DSH 转发到回环上的 TW 服务），完整 TW 5 编辑器。
 
-**📝 快速笔记** — 聊天区右下角悬浮控件（可折叠）：
+**📝 快速笔记** — 右下角「**知识库**」悬浮按钮 →「📝 快速笔记」（可折叠）：
 - **CodeMirror 6 编辑器**：真正的 Markdown 语法树高亮（标题/列表/代码/链接/表格/任务清单/删除线等，GFM），支持撤销/重做与行内编辑体验；
-- **文件上传**：点「📎 上传」或直接把文件拖进编辑器——文件存到 wiki 的 `files/` 文件夹并随 git 同步；图片插入 `![名](/files/名)`、其它文件插入 `[名](/files/名)`，在 TW 里可直接打开；
+- **草稿自动保存**：正文/标题/标签 500ms 防抖写入本地，关掉卡片或刷新页面都不丢；重开自动恢复，可一键「丢弃」；
+- **🕘 最近**：一键列出最近修改的笔记，点标题直接载入编辑器继续改（不需要开完整 TW 去找）；
+- **文件上传**：点「📎 上传」或直接把文件拖进编辑器——文件存到 wiki 的 `files/` 文件夹并随 git 同步；图片插入 `![名](/dsh-tiddlywiki/tw/files/名)`、其它文件插入 `[名](/dsh-tiddlywiki/tw/files/名)`（**同源代理 URL**，在 TW 与快速笔记预览里都能打开）；
 - **Ctrl+Enter 保存**为独立 tiddler；笔记 `type` 自动设为 `text/markdown`，所以上传的图片/链接在 TW 里按 Markdown 正常渲染；
 - 点「**✏️ 在 TW 中编辑**」→ 保存后弹出**独立小窗**（可拖动/缩放）加载 TW 原生编辑器编辑该条。
 
-**🔄 一键同步** — 右下角「同步」悬浮按钮：点一下做 pull → commit → push，按钮上的状态点实时反映 git 状态：
-🟢 已同步 · 🟡 有未提交改动 · 🔴 落后于远端 · ⚪ 离线；悬停可看分支/领先/落后/上次同步时间；每 30s 自动刷新。
-若这次 pull 拉到了新内容，TW 服务自动重启（同端口），界面立即显示最新快照（无需手动去面板点「重启 TW」）。
+**🔧 一键同步 + 面板** —「知识库」按钮是一个**统一入口**，替代了旧版三个叠在右下角的悬浮按钮：
+- **🖥 打开/收起 TW 面板** 与 **🔄 重载 TW 面板**（`ui.showPanelStatus` 控制）；
+- **📝 快速笔记**（`ui.showQuickNote` 控制）；
+- **🔁 同步**：pull → commit → push；FAB 右下角的**状态点**实时反映 git 状态：
+  🟢 已同步 · 🟡 有未提交改动 · 🔴 落后于远端 · ⚪ 离线；悬停可看分支/领先/落后/上次同步时间；每 30s 自动刷新。
+  若这次 pull 拉到了新内容，TW 服务自动重启（同端口），界面立即显示最新快照（无需手动去面板点「重启 TW」）。
 
 **🔧 面板异常** — 面板服务异常时显示错误 +「重试」按钮（POST `/dsh-tiddlywiki/restart`）。
 
@@ -99,7 +110,7 @@ dsh plugin --profile web add link:/path/to/your/dsh-tiddlywiki
 | 区块 | 内容 |
 |---|---|
 | 状态/重启 | TW 运行状态 + git 概览 + 「同步」按钮 + 「重启 TW」按钮 |
-| 常规配置 | 快速笔记默认 tag、git 自动 commit/防抖/远端/分支、ui 开关（快速笔记/面板状态/同步按钮）——改了什么保存什么 |
+| 常规配置 | 快速笔记默认 tag、git 自动 commit/防抖/远端/分支、ui 开关（快速笔记/面板状态/同步按钮——分别控制「知识库」按钮里的对应入口）——改了什么保存什么 |
 | 插件管理 | 自带官方插件勾选（可搜索）→ 应用并自动重启 TW |
 | 主题管理 | 自带主题**多选加载 + 单选活动** → 应用并自动重启 TW |
 | 语言管理 | 自带官方语言包勾选（含 zh-Hans 简体）→ 应用并自动重启 TW |
@@ -123,6 +134,20 @@ TW 的界面语言由**语言插件**决定，不是某个配置字符串。tidd
 - **配置自动应用**：在常规配置写入 `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/`。
+
 ---
 
 ## 🔄 同步与数据
@@ -153,9 +178,9 @@ TW 的界面语言由**语言插件**决定，不是某个配置字符串。tidd
     note:
       tag: "inbox"
     ui:
-      showQuickNote: true           # 是否显示右下角「快速笔记」按钮
-      showPanelStatus: true         # 是否显示 TW 面板右下角「状态/重载」悬浮按钮
-      showSyncButton: true          # 是否显示右下角「同步」悬浮按钮
+      showQuickNote: true           # 是否显示「知识库」按钮里的「快速笔记」入口
+      showPanelStatus: true         # 是否显示「知识库」按钮里的 TW 面板/重载入口与状态行
+      showSyncButton: true          # 是否显示「知识库」按钮里的「同步」入口与 git 状态点
     auth:
       username: ""                     # 默认 loopback 匿名；暴露到非 loopback 时才需要
       password: ""
@@ -163,6 +188,8 @@ TW 的界面语言由**语言插件**决定，不是某个配置字符串。tidd
 
 > **运行时配置**：设置页写入的 `$:/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）时才需要，正常情况下无需配置。
 
 ---
 
@@ -191,10 +218,13 @@ npm run selftest      # headless：spawn TW → REST 读写 → git → 退出
 | `/dsh-tiddlywiki/note` | POST | 快速笔记 → 独立 tiddler |
 | `/dsh-tiddlywiki/edit` | POST | 打开 TW 原生编辑器（draft） |
 | `/dsh-tiddlywiki/tags` | GET | 现有非系统 tag（自动补全） |
+| `/dsh-tiddlywiki/recent` | GET | 最近修改的笔记（快速笔记「最近」入口） |
+| `/dsh-tiddlywiki/get` | GET | 读单个 tiddler（快速笔记「最近」载入） |
 | `/dsh-tiddlywiki/sync` | POST | 一键 pull → commit → push |
 | `/dsh-tiddlywiki/upload` | POST | 文件上传到 `files/`（原始 body + `X-Filename`） |
 | `/dsh-tiddlywiki/restart` | POST | 重启 TW 子进程 |
 | `/dsh-tiddlywiki/api/*` | any | 透传到 TW 服务（JSON） |
+| `/dsh-tiddlywiki/tw/*` | any | **同源 TW 代理**：整个 TW 前端（index + `/files/*` + TiddlyWeb API）→ 回环 TW（v0.6.0，远程访问核心） |
 
 ---
 
@@ -216,10 +246,10 @@ src/
 ├── index.ts            # host 入口：装配 WikiServer/路由/工具/prompt/自动 commit
 ├── sdk.ts              # 自包含 defineTool + dshHomePath（零 @deepseek-ai 运行时依赖）
 ├── host/
-│   ├── wiki.ts         # WikiServer：spawn/kill/自愈/端口探测/就绪轮询
+│   ├── 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/* 路由
+│   ├── 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   # 首次启动一次性写入「插件说明」笔记