dsh-tiddlywiki 0.30.65 → 0.31.0

package/docs/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.31.0**（2026-10-26）：**对齐 DSH 0.2.1 的一轮改造 + 两条真实回归修复**。① **选库入口搬到官方座位**：`conversation.input.selector.context` 在 0.2.1 里**不存在**（v0.28.8 起的 `scope-seat.ts` 整个是死代码），选库改挂官方内联座位 `conversation.input.left`（`id: 'wiki-scope'`），`scope-seat.ts` 删除、dock 里那套 `scope` 内联渲染与自测量一并清掉；右侧栏 guide 条目补 `id` + `keepMounted: true`（0.2.1 的分页约定）。② **新增 `scripts/verify-dsh-contract.mjs`**：解析宿主 `app.asar` 里的 `dsh-cordis-client-runner`，把 103 条官方座位目录与我们源码里注册的 6 个座位逐一比对（存在性 / kind / `tool.call.toolview` 的 54 个已占 key 是否撞车），并断言 `engines.dsh` 已声明 —— 此前"座位名写错"只会静默不渲染。③ **`tiddlywiki_get` 支持分页**（`offset`/`limit`，默认 12000 字符）：超长笔记一次读全会撞宿主的 12500 token 回执上限；回执明确写"正文 a–b / 共 N 字符"并给出下一步 `offset`。`search`/`lint` 的回执也加了同量级的体量预算（命中条数与计数结论**永不截断**，只截示例并说明省略了多少）。④ **16 个工具补 `output.schema`**：DSH 0.2.1 在每次调用后用 `validateJsonSchemaValue` 校验返回值，不过即抛 `ToolOutputError` —— 而 `sdk.ts` 的 `output.schema` 自 v0.20.0 起写死成 `{}`（当时注释断言"没人读它"，**实测为假**）。现在按"只声明必定存在且类型稳定"的规则为 16 个工具各写一份，并加两条守门：每个工具必须声明非空 object schema；**用 E2E 里每一次真实返回值反查声明**（抓"schema 比现实更严"这种线上致命错误）。⑤ **skill 改用 `ctx.skills.register`**：拆库 skill 过去只能往 `$DSH_HOME/skills` 写文件，现在优先注册到宿主 skill 注册表（内存、随插件卸载消失、不碰用户目录），只有宿主没有该服务时才回落写文件；新增 `scripts/verify-embedded-skill.mjs`（解析/坏输入/disposer/注册表抛错/**启动顺序必须"先注册后回落"**）。⑥ **新增 `/note` 斜杠命令**：一句话记笔记，直接写进当前会话的知识库、不产生模型消息；同名笔记**已存在就拒绝**并指路（"同一件事写多份互相矛盾"是最难收拾的失败形态），且写成 `inbox` + 工作站标记、**不打 `agent-written`**（那是人写的）；守门 `scripts/verify-note-command.mjs`。⑦ **提示词两处修订**：新增「### 先查再答」（模型可见工具从 57 涨到 243 之后，新会话不再主动检索 —— 注入本身没坏，`system/message` 里逐字可查，坏在提示词只讲"怎么写"、从不讲"什么时候该来查"）与「### 时效与去重」（作者原话：agent 爱写短命内容、同一件事写多份有差异的、正文里堆变更流水）—— 钉子：一件事只留一处权威表述（先搜、命中就**原地改那一节**）、每条笔记必须看得出"还有效到什么时候"（`valid-until`/`review-after`/"长期有效"，说不清时效的别写）、**不写流水账**、**读到就先判时效**。slim 正文 1079 → **1390 字符**（预算 1000 → 1470，与逐条断言绑定），并把提示词正文的拼装从"硬编码数组 + 导出的块清单"两份实现收成 `governanceBlocks()` 单一来源 —— 加规则时 `verify-prompt` 当场抓到这个双份实现。
+
 - **v0.30.65**（2026-10-09）：**新增 `tiddlywiki_replace` 工具（笔记正文局部替换）**。Agent 想只改笔记里的几处文字（比如把 Markdown 圆括号内链批量改成双括号 `[[x]]`）此前没有对应工具：要么整篇 `tiddlywiki_put` 重写（易出错、费 token），要么绕过插件手写 HTTP PUT（会踩「`modified` 是 UTC、别写本地时间」这类坑）。新工具 `replace(title, old, new, all?, expectedModified?, expectedRevision?, force?)`：读全文 → 精确替换子串 → 整篇回写；默认只换第一处、`all:true` 换全部；`old` 未命中回执 `replaced:0` 且不报错（别把「没命中」当「改好了」）；与 put/append 同一套乐观并发保护与写策略（保留 type/tags/字段、二进制附件拒绝）。工具数 15 → 16：`full` 提示词目录、`verify-prompt`/`verify-tool-views` 的工具数断言、AGENTS.md §2、package.json 描述、docs/development.md 同步；客户端新增「局部替换」工具卡与徽标（`tool-views` / `i18n-card`）。
 
 - **v0.30.63**（2026-10-09）：**默认提示词整理（「聊天引用」与「笔记内引用」分家）+「整段替换」配置说明勘误**。① **笔记约定的链接规则拆成两条**：旧版只有一条 `[标题](/dsh-tiddlywiki/tw/#标题)`——那是**聊天回复**专用写法，模型会照抄进笔记正文，于是 URL 一旦带未转义空格就被 markdown-it 整条拒绝渲染成纯文本，即便渲染成功也是外链、点开另起标签页（正是「笔记里的链接偶尔是 Markdown 格式、不是 `[[…]]`」的根因）。现在拆成「**笔记内引用**」写 `[[标题]]`（文字不同写 `[[标题|文字]]`，两种内容类型下都能正确渲染成站内链接、无需 URL 编码）与「**聊天里引用笔记**」写带作用域 base 的链接形式（多库时自动带库 id）。slim 正文 866 → 937 字符（仍 < 预算 1000，`verify-prompt.mjs` 预算/链接/多库断言全绿）。② **`config.prompt.override` 设置页说明勘误**（zh+en）：原「非空时取代上面的内置文本」有歧义，改为「非空时替换内置提示词，附加说明仍会追加在末尾」。纯文案，无行为变化。

package/docs/features.md

@@ -8,11 +8,13 @@
 | 🗂 **多知识库（v0.28.0）** | **多个 TiddlyWiki 同时在线**，每个库独立配置、独立 git 仓库（或共用仓库按文件夹物理划分 —— 「工作 + 个人」同仓、「书籍」独立仓，两种拓扑都支持）。开关是 `wikis.json` 的 `mode`，**缺省 `single`**：升级用户的行为逐字不变（位置仍由旧指针文件 > cordis 默认决定）。每个库有自己的编辑器与入口（右下角「知识库」菜单的分组、每个库自己的 `/tw/<id>/` 同源基址），设置页「知识库列表」负责增删改 / 启停 / 设为默认 / 开局自启 / 对 Agent 可见性；「移出列表」明确**不会删除目录**。快速笔记卡片也能选目标库（默认跟随你在 GUI 里看的那个库；**整张卡片一起换库**：标签建议 / 最近 / 附件 / 保存 / 弹窗编辑器同库）。**左侧边栏每个在运行的库一行**（各用自己在「知识库列表」里配的显示名与图标，当前显示的那个高亮）：**点另一个库 = 立刻切过去**（v0.28.13 起面板保持打开），点当前那个库才收起 —— 入口同时也是开关。切换 = 换成那个库的整份 TW 文档（10–30MB，TW 回 `no-store` 缓存不了），v0.28.14 起**点击即开始换**（不再先等一次 `/status`）、高亮即时跟上、界面底部显示「正在载入知识库「X」…」。 |
 | 🎨 **每库图标用 DSH 官方图标系统（v0.28.8）** | 知识库列表里每行的图标是个**弹出式网格**：收录 **DSH 官方的 36 个图标**（内联的是上游的 path 数据，客户端保持纯 DOM、零运行时依赖）+ 本插件自绘的 8 个 + 一组 emoji，超出 **48 个一页**分页展示；选中即写入 `wikis.json` 的 `icon`。同时修掉一个真 bug：`/admin/wikis` 的读取视图漏了 `icon` 字段，导致「选了图标、界面立刻变回默认」（写进去了、读回来是 `undefined`）—— 守门钉死该字段并反向验证过。 |
 | 📑 **设置页分页：总览 / 本库配置 / 全局（v0.28.8）** | 多库模式下十几块面板挤在一页里，既分不清「改这个库」还是「改整个插件」，改完也没有退出口。现在按作用域分成三个 tab：「**总览**」（名册 + 全局项）、「**本库配置**」（点某个库的「配置」才出现；按钮变成「**退出配置**」，再点一次就回到总览）、「**全局**」。「插件管理（自带官方插件）/ 主题管理 / 语言管理 / 初始化」这些**per-库**面板只在本库配置里渲染（此前它们混在全局项中，看着像所有库共用一个设置）。**单库安装没有 tab 条**，就是原来那一页，逐字不变。 |
-| 🆕 **新会话也能选知识库（v0.28.8 / v0.28.11）** | 会话知识库选择器此前只长在输入框上方；空白会话（还没发过消息、输入框尚未出现）里它挂在**预设/模式选择旁边**。实现是**声明感知**的：DSH 声明了 `conversation.input.selector.context` 就注入那里（那一格只对空白会话渲染），声明不到**就留在 dock 里那一行** —— 任何情况下都只有**一个**选择器（v0.28.11 修：旧实现"2 秒没等到就回落到 dock"会**再注册一个条目**，而 dock 里本来就有同一个选择器，于是新会话里出现两个、其中一个和快速笔记同一行）。 |
+| 🆕 **新会话也能选知识库** | 会话知识库选择器长在输入框左侧的官方内联座位 `conversation.input.left`（v0.31.0 起；此前挂的 `conversation.input.selector.context` 在 **DSH 0.2.1 里根本不存在**，那段代码只会静默不渲染）。**空白会话里同样可用**，且任何情况下都只有**一个**选择器；可见库 ≤1 时不渲染。 |
 | 🏷 **「默认库」不再是一个名字（v0.28.12）** | 设置过默认知识库之后，界面**不再显示「默认库」这个字样**——被设为默认的那个库一律直接用**它自己的显示名**（后缀「（默认）」只作身份标记）。会话选择器里它排在最前、**新会话打开时它已经是选中项**（选中它 = 清空显式作用域，所以以后改了默认库，没动过选择器的会话会跟着走）；剪藏目标下拉里它代表"不指定"，同一个库不会出现两次；快速笔记「写入」目标、设置页「单库（只跑 X）」与切单库的确认文案同样直呼其名。只读清单失败时给中性说法，绝不退回「默认库」。 |
 | 🖥 **桌面版（DSH Desktop）能起 TW 了（v0.28.8）** | TW 子进程需要真正的 `node`，而桌面版里 `process.execPath` 是 Electron —— 以前直接拿它 spawn，TW 起不来。现在按 `DSH_TIDDLYWIKI_NODE` → `where node` / `which node` → `process.execPath` 的顺序解析并缓存，启动日志写明用了哪个；`scripts/verify-desktop-node.mjs` 以行为级断言守门（进 `verify:unit`）。 |
 | 🔒 **对 Agent 的可见性（v0.28.0）** | 每个库可设「对 Agent 隐身」= **彻底不可达**：不进会话选择器、不进注入提示词、`tiddlywiki_*` 工具永不触及（人在 GUI 里照常用它）。会话级作用域**单选**（输入框上方的选择器，选择存在 `$DSH_HOME/dsh-tiddlywiki/sessions.json` 并跨重启存活），工具按会话路由，**可见库多于一个时每条回执都标明库名**，注入提示词按会话求值并读**该库自己**的 `prompt.*`。两条刻意的拒绝：作用域指向隐身库 → 忽略（隐身是硬边界）；指向可见但**没在跑**的库 → **报错并带上库名**，绝不静默落到别的库 —— 静默换库会让笔记落进你没指定过的库，而且看起来一切正常。 |
-| 🧩 **拆库引导（v0.28.0）** | 想把现有库按用途拆开（语料/归档 vs 工作集）时有一份现成流程：[docs/wiki-split.md](wiki-split.md) 顶部是**一整段可直接复制给 Agent 的话**；Agent 会先只读体检、再问五个问题（每个都给默认建议）、出方案表格等你确认，然后备份 → `git mv` 保历史 → 登记进插件 → 校验，**旧库一个都不删**。随包 skill `dsh-tiddlywiki-wiki-split` 会在启动时装进 `$DSH_HOME/skills/`（**只覆盖带标记的文件**，你自己写的 skill 不被碰），也可以直接说「用拆库 skill 帮我拆」。 |
+| 🧩 **拆库引导（v0.28.0）** | 想把现有库按用途拆开（语料/归档 vs 工作集）时有一份现成流程：[docs/wiki-split.md](wiki-split.md) 顶部是**一整段可直接复制给 Agent 的话**；Agent 会先只读体检、再问五个问题（每个都给默认建议）、出方案表格等你确认，然后备份 → `git mv` 保历史 → 登记进插件 → 校验，**旧库一个都不删**。随包 skill `dsh-tiddlywiki-wiki-split` 在启动时**注册进宿主 skill 注册表**（v0.31.0 起：内存注册、随插件卸载消失、不写你的 `$DSH_HOME`；宿主没有该服务时才回落到 `$DSH_HOME/skills/`，且**只覆盖带标记的文件**），也可以直接说「用拆库 skill 帮我拆」。 |
+| ⚡ **`/note` 一句话记笔记（v0.31.0）** | 输入框里打 `/note 标题` 换行写正文，直接写进当前会话的知识库：**不产生模型消息**（不占上下文、不用等回复），自动打 `inbox` 标签 + 工作区标记，**不打 `agent-written`**（那是人写的）。同名笔记**已存在就拒绝**并指路 —— 静默覆盖正是「同一件事被写成多份互相矛盾」的来源。 |
+| 🧭 **提示词里的读写纪律（v0.31.0）** | 注入提示词新增两块：**「先查再答」**（问题可能已沉淀成笔记时先 `tiddlywiki_search`，别凭记忆答）与**「时效与去重」**（一件事只留一处权威表述、命中就**原地改那一节**；每条笔记要能看出还有效到什么时候 —— `valid-until` / `review-after` / 「长期有效」，说不清时效的别写进 wiki；**不写流水账**，正文不追加「某日改了什么」，git 历史里有；**读到就先判时效**，过期/被取代就更新或明说已过期）。目的是治「agent 爱写短命内容、同一件事写多份、正文越堆越长」。 |
 | 📍 **知识库位置可切换** | 设置页「知识库位置」可把插件切换到**任意本地文件夹**（不用改 cordis 配置、不用重装）：就地停/起 TW 子进程，目标目录没有 `tiddlywiki.info` 时自动 `--init server` 建一个全新知识库；选择记在 `$DSH_HOME/dsh-tiddlywiki/location.json`——一个**在 wiki 之外**的指针文件（所以切到新 wiki 后仍记得「我用的是哪个」），「恢复为配置默认」一键清除；**切换失败自动回滚**到原知识库并如实告知（v0.22.0）。⚠️ 它一次只有一个库在线；要**多库同时在线**见上面的「多知识库」（v0.28.0） |
 | 🔄 **seed 更新检测** | seed 标记记录**内容哈希**：内置内容在本 wiki 预置之后更新过 → 设置页显示「⬆ 有更新」；被你改过 → 显示「✏️ 本地已修改」，且「重新初始化」前**二次确认**；两者都基于哈希判定，绝不猜（旧格式标记会明确显示「尚未启用更新检测」，不会误报为「你改过」，v0.22.0） |
 | 🎨 **自定义样式** | 「自定义样式」seed：编辑器美化 / 窄屏侧栏隐藏 / menubar 加高 / 批注弹窗等 5 张通用样式表，新 wiki 也能一键初始化（可选，v0.16.22） |