dsh-session-index-lau 0.0.0-stage → 2.5.1

package/README.md

@@ -1,3 +1,449 @@
-# Temporary Holding Version
+# dsh-session-index
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> DSH（DeepSeek Harness）+ WorkBuddy 的**全会话索引与跨会话记忆** MCP 插件。
+> 拉取仓库 → 双击安装 → 之后全自动。零第三方依赖，源会话文件全程只读。
+
+| 项目 | 值 |
+|---|---|
+| 版本 | **v2.5.1** |
+| 运行要求 | Node **≥ 22.15**（需要 `zlib.zstdDecompressSync`） |
+| MCP 能力 | **14 个工具** / 4 个提示词 / 8 个资源 |
+| 第三方依赖 | **0**（只用 Node 标准库） |
+| 完整手册 | [`操作使用手册.html`](./操作使用手册.html)（单页 14 章，导航 / 搜索 / 一键复制） |
+
+---
+
+## 它解决什么问题
+
+DSH 的会话存在 `~/.dsh/sessions/` 下，是**上千个独立 zstd 帧拼接**的 `session.v4.jsonl.zstd`，单文件可达 20 MB。
+想在新会话里回顾旧结论，只能整包解压翻全文——慢，而且极耗 token。
+
+本插件把全部会话**预先索引成结构化记忆单元**（会话卡：提问、结论、涉及路径、工具、关键词、血缘），
+之后一次工具调用就能拿到结论速览，用关键词只取命中片段，**不必再把几十 MB 历史灌进上下文**。
+
+---
+
+## 安装
+
+### 方式 A：DSH 插件页（推荐 · 零命令行）
+
+1. 打开 DSH → **插件页**
+2. 粘贴仓库地址：`https://github.com/Lau-Jin/DSH`
+3. 点安装，按提示**完全退出 DSH 再打开**（最小化无效）
+
+装完就是可用状态，不用改配置、不用跑脚本、不用管 Node 路径。「已安装」列表与详情页会显示插件图标（`icon.svg`，卡片 + 放大镜）。
+
+> 地址带不带 `.git` 都能装：不带时 pnpm 直接走 codeload 下 tarball，**不依赖本机 git**；
+> 带上 `.git` 会先做一次 `git ls-remote` 解析版本。网络抖动时前者更稳。
+> 实测这两条路都能装成（本机约 80–100 秒，主要是 GitHub 往返延迟，包本身只有 83 KB）。
+
+**它为什么能自己找到入口**——插件包里的 `cordis.patch.yml` 会随 bundle 自动应用，挂两行：
+
+| 行 id | 包 | 作用 |
+|---|---|---|
+| `session-index-host` | `dsh-session-index` | 宿主半身（`lib/index.mjs`）：用 `import.meta.url` 解析**真实安装目录**，把 `server.mjs` 绝对路径写进 `~/.dsh/session-index/server-path.txt` |
+| `mcp-session-index` | `@deepseek-ai/dsh-mcp-client` | MCP stdio 客户端：14 工具 / 4 提示词 / 8 资源 |
+
+那行配置里的 `command`、`args`、`DSH_HOME` 三处都是 `!!js` 表达式，**在 DSH 加载配置时求值**（不是安装时），
+按「显式环境变量 → 宿主记下的路径文件 → profile 标准安装位置」依次探测。
+所以仓库放哪、pnpm 装到哪、换了 Node 版本，都不需要改文件。
+
+宿主行排在前、MCP 行排在后，路径文件先落盘，MCP 侧首次 spawn 就能命中——**一次重启即生效**。
+
+### 方式 B：clone + 一键脚本（想自己控制目录 / 离线分发）
+
+```bash
+git clone https://github.com/Lau-Jin/DSH.git
+cd DSH
+```
+
+然后：
+
+- **Windows**：双击 `install.cmd`
+- **macOS / Linux / Git Bash**：`./install.sh`
+
+`install.mjs` 会先判断 profile 是否已经以 bundle 方式注册了本插件：
+
+- **已注册**（你从插件页装过）→ 不再写 profile 配置，只把残留的旧配置块清掉，避免出现两条同 id 的 MCP 行；
+- **未注册**（纯 clone 用户）→ 往 `~/.dsh/profiles/desktop/cordis.patch.yml` 写一个带标记的配置块。
+
+两种情况都会：写好 `server-path.txt`、装 Skill、生成可分发包。
+
+### 方式 C：手动加 MCP（不推荐，仅排障用）
+
+DSH「MCP 与技能」→ MCP 里添加 stdio server：
+
+| 字段 | 值 |
+|---|---|
+| 名称 | `session-index` |
+| command | `node` 的绝对路径（需 ≥ 22.15） |
+| args | `<仓库目录>/server.mjs` |
+
+### 前置条件
+
+1. **Node ≥ 22.15** —— 需要 `zlib.zstdDecompressSync`。插件页安装时会自动挑 DSH 自带的 Node（`~/.dsh/dsh-runtimes/*/dependencies/node`），通常不用你操心。
+2. 方式 B 需要 **Git**；仓库已转公开，无需 SSH key。
+
+### 安装脚本做了什么
+
+`install.cmd` / `install.sh` 只是包装，实际调用 `node install.mjs`：
+
+1. 解析可用的 Node（含 zstd 支持校验）
+2. 判断安装方式（bundle / patch），必要时**备份**并写入 `cordis.patch.yml` 的标记块
+3. 写 `~/.dsh/session-index/server-path.txt`，记下 MCP 入口绝对路径
+4. 安装 Skill 到 `~/.dsh/skills/session-index/SKILL.md`
+5. 自动生成插件包与技能包到 `dist/`
+6. 打印 6 项校验结果
+
+幂等：重复运行不会产生重复条目；**更新后重跑会保留你手工改过的 env 值**（除非显式加 `--reset-env`）。
+
+---
+
+## 插件页装不上？先跑环境体检
+
+DSH 插件页装任何东西，底层都是一次 `pnpm install`。装不上时提示常常被归类成
+「没有写入权限，无法安装」，但**真实原因通常在 pnpm 那一步**。装上本插件后可以直接体检：
+
+```bash
+node install.mjs --doctor
+```
+
+七项检查，每项给出结论与修法（只读，不改任何文件）：
+
+| 检查 | 会导致的现象 |
+|---|---|
+| Node 支持 zstd | 索引建不起来 |
+| git 全局 URL 重写 | 走第三方镜像时 codeload 返回 403 / 认证失败 |
+| pnpm `fetch-timeout` | 超过 60000 会让 pnpm 11 直接抛 `UND_ERR_INVALID_ARG`，**所有安装失败** |
+| 远端 git 依赖 | 每次安装都要重下，大仓库必然超时 |
+| lockfile 残留 `git+ssh` | 仓库已删或缺 SSH key 时必失败 |
+| bundle 是否注册 | 插件没被 DSH 加载 |
+| 索引状态 | 装完但没建索引 |
+
+### 三个已确认的坑
+
+1. **`fetch-timeout` 有硬上限。** pnpm 11.28 + undici 在 `fetch-timeout > 60000` 时直接报
+   `UND_ERR_INVALID_ARG`（实测 60000 正常、65000 就失败）。调大超时不仅没用，还会让所有安装全挂。
+2. **大 tarball 装不完。** GitHub 直连在本机约 70–350 KB/s，28 MB 的包需要数分钟，
+   永远超不过 60 秒上限，于是 `UND_ERR_DESTROYED` 反复重试直到失败。
+   正解不是调超时，而是**把这类依赖本地化**：复制到本地目录，依赖写成 `link:`，
+   之后安装完全离线（实测整份 profile 8 秒装完）。
+3. **`insteadOf` 镜像规则会连坐。** `url.https://<镜像>/https://github.com/.insteadOf`
+   会重写所有 GitHub HTTPS 地址，而镜像一般不代理 `codeload.github.com`（返回 403）。
+   直连可用时建议去掉：
+   ```bash
+   git config --global --get-regexp "url\..*\.insteadof"     # 先看有没有
+   git config --global --unset-all "url.https://<镜像前缀>.insteadOf"
+   ```
+
+> 本次修复的完整做法（复制包 → `link:` → 离线重建 lockfile）见
+> `操作使用手册.html` 第 13 章「排障」。
+
+---
+
+## 装上之后是自动的
+
+| 行为 | 说明 |
+|---|---|
+| 首次建索引 | server 启动时后台子进程构建，**不阻塞 MCP 握手**；未就绪时工具会提示稍候 |
+| 新会话识别 | `fs.watch` 递归监听 DSH 与 WorkBuddy 会话目录，写入停止约 3.5 秒后增量纳入 |
+| 定时兜底 | 每 60 秒增量刷新，只处理 size/mtime 变化的文件 |
+| 安静期保护 | 已有索引的活跃会话需静止 45 秒才重建，避免反复解压正在写入的大文件 |
+| 客户端通知 | 索引更新后发 `notifications/resources/list_changed`，客户端无需重启即可感知 |
+| 自愈 | 索引缺失或损坏时，下次启动自动重建 |
+
+本机实测（31 个会话）：全量构建 **约 10 秒**、索引 **约 12 MB**（源文件 55 MB+）；
+增量刷新 **约 0.85 秒**，无变化时 **约 30 ms**；新会话从写入到可检索 **约 70 ms**。
+
+---
+
+## 工具速览
+
+推荐调用链：`status → brief → related/thread → search → get`，逐级放大，避免一上来灌全文。
+
+| 工具 | 用途 |
+|---|---|
+| `session_index_status` | 索引与自动维护状态（含监听、下次刷新倒计时） |
+| `session_index_brief` | 跨会话结论速览；带 `query` 只取相关主题 |
+| `session_index_list` | 会话清单（标题 / 时间 / 工作区 / 应用） |
+| `session_index_related` | 相关会话 + 关联理由（共享路径 / 关键词 / 工具 / 血缘 / 同工作区） |
+| `session_index_thread` | 父子血缘链（compact 上游、subagent 下游、同源兄弟） |
+| `session_index_search` | 语义检索，**只返回命中片段**；默认排除系统注入噪声 |
+| `session_index_get` | 先看会话骨架，再按 `seq` 精确取原文 |
+| `session_index_remember` | 写入长期记忆（类型 / 标签 / 重要度） |
+| `session_index_recall` | 召回长期记忆（时间衰减排序） |
+| `session_index_forget` | 归档或删除记忆（默认归档） |
+| `session_index_refresh` | 手动增量刷新 |
+| `session_index_package` | 重新生成分发包 |
+| `session_index_vectors` | 可选的向量索引管理 |
+| `session_index_stage` | 会话整理成 Markdown → 思源桥「待入库」（两步确认，绝不自动写库） |
+
+另提供提示词 `session-context` / `resume-topic` / `catch-up` / `quickstart`，
+资源 `session-index://guide`、`://plugin.json`、`://status`、`://brief`、`://memory` 等。
+`initialize` 会返回 `instructions`，客户端不读外部文档也能正确上手。
+
+**搜索模式**：`semantic`（默认，本地同义词扩展 + BM25，零 token）、`keyword`（精确 AND）、
+`hybrid` / `vector`（需配置 embedding，未配置自动降级为本地语义检索）。
+
+---
+
+## 会话整理 → 思源桥「待入库」
+
+`session_index_stage` 把索引里的会话卡、结论、检索片段整理成一篇 Markdown，**投递到思源桥的待入库队列**。
+它只做「投递」这一步，**绝不调用 `/api/stage/commit`**——写进思源笔记库永远由你在思源桥界面点确认。
+
+### 为什么不用再做一个插件
+
+DSH 的插件之间**不共享会话数据**：会话本体只有一份磁盘文件，各插件各自解析、各自维护私有目录。
+但会话卡与结论已经在 `session-index` 手里，而思源桥是独立的 HTTP 服务（默认 `127.0.0.1:5599`），
+所以一次 HTTP 调用就能对接，不需要 DSH 内核级的插件通信，更不需要第三个插件重新解一遍 zstd。
+
+### 三步用法
+
+```text
+1) 只读探测（可选）
+   session_index_stage { "status": true }
+   → 返回思源桥内核版本、队列篇数、自动接入目录
+
+2) 预览（默认，不产生任何写入）
+   session_index_stage { "query": "插件", "template": "brief", "limit": 5 }
+   → 返回 title / chars / preview / token / target / confirmWith
+
+3) 用户看过预览、点头后，把 confirmWith 原样回传
+   session_index_stage { ...confirmWith }
+   → 投递到「待入库」；返回 id 与落点
+```
+
+第 2 步**永远只是预览**。第 3 步的 `confirmToken` 绑定了「标题 + 落点 + 正文」，
+参数被改动或索引刚更新导致内容变化时令牌失配，会直接拒绝投递并要求重新预览——不会出现「预览 A、投递 B」。
+
+### 主要参数
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `status` | false | 只读探测服务与队列，不做任何写入 |
+| `query` | 空 | 主题词，按主题聚合会话 |
+| `sessionIds` | 空 | 精确指定会话 id（支持前缀），不传则取最近/相关会话 |
+| `app` / `workspace` / `since` / `until` | all / 空 | 范围过滤 |
+| `template` | `brief` | `brief` 速览 / `decisions` 只要结论 / `detail` 附检索片段 |
+| `title` | 自动生成 | 自定义文档标题（确认时回传预览给出的值） |
+| `hpath` / `notebook` | `/会话札记/思源` / `思源桥` | 落点；**写入前仍可在思源桥界面改** |
+| `note` / `limit` / `maxChars` | 自动 / 8 / 12000 | 备注、会话数、篇幅上限 |
+| `confirmToken` | 空 | 预览返回的令牌；带上且匹配才真正投递 |
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `SIYUAN_BRIDGE_PORT` / `SIYUAN_BRIDGE_URL` | `5599` / `http://127.0.0.1:5599` | 服务地址；**只允许回环地址**，不接受任意内网 URL |
+| `SESSION_INDEX_STAGE` | `1` | 设 `0` 彻底禁用该工具 |
+| `SESSION_INDEX_STAGE_TIMEOUT_MS` | `5000` | 单次请求超时（1000–60000） |
+| `SESSION_INDEX_STAGE_HPATH` / `_NOTEBOOK` | `/会话札记/思源` / `思源桥` | 默认落点 |
+
+### 安全边界
+
+- 只调用 `/api/status`、`/api/stage`（GET/POST）、`/api/autostage`，**不调用 commit**
+- 投递前按「标题 + 字数」查队列，已有同稿则不重复入队
+- 服务不可达时返回结构化错误（`BRIDGE_UNREACHABLE`），不抛堆栈、不影响其它 13 个工具
+- 文档硬上限 60000 字；Markdown 里明确标注「未写入笔记库」
+
+> 实测提醒：思源桥 `/api/autostage` 返回的实际 `session-docs` 目录可能与 `config.json` 里的
+> `dataDir` 不一致（服务走 `SIYUAN_BRIDGE_DATA` 推导）。本工具走 HTTP 接口，不受这个差异影响。
+
+### 推送已有文档（手册 / README）
+
+`session_index_stage` 整理的是**索引里的会话**；如果要把仓库里现成的文档送进待入库，
+用独立脚本 `tools/push-doc.mjs`（不需要重启 DSH、不依赖 MCP 服务）：
+
+```bash
+node tools/push-doc.mjs                                   # 只读预览《操作使用手册.html》
+node tools/push-doc.mjs --send                            # 投递到待入库（绝不写库）
+node tools/push-doc.mjs --file README.md --dry            # 推别的文件
+node tools/push-doc.mjs --hpath "/会话札记/运维" --send    # 指定落点
+```
+
+**批量：WorkBuddy 所有会话生成的文档**
+
+```bash
+node tools/push-doc.mjs --from-workbuddy                  # 只列清单（默认，零写入）
+node tools/push-doc.mjs --from-workbuddy --send           # 全部投递到待入库
+node tools/push-doc.mjs --from-workbuddy --no-exclude     # 连临时/备份目录一起
+node tools/push-doc.mjs --from-workbuddy --include-txt    # 连 .txt 一起
+node tools/push-doc.mjs --from-workbuddy --source PresentFiles --limit 10 --send
+```
+
+数据源是 `~/.workbuddy/artifact-index/<会话id>.json` 里 `contentType: document` 的条目
+（`WORKBUDDY_ARTIFACT_INDEX` 可改）。默认会**排除** `node_modules/dist/.git`、`.verify-*`、
+`DSH-probe`、旧开发副本 `dsh-session-index`、备份与 UI 源码，并按**内容哈希 + 路径**去重，
+避免同一份 README 被推十几遍。每篇标题带相对路径、备注带来源会话，落点统一可在界面改。
+
+实测（2026-11-14）：70 条文档命中 → 排除 26 条临时/依赖 → 文件已不存在 4 →
+路径或内容重复 18 → **唯一 22 篇全部投递成功**，队列 23 篇（含此前单推的手册），
+重复执行 22 篇全部被同名去重拦截。可用 `--limit`（默认 60）与 `--since` 收窄。
+
+- **默认只预览**，加 `--send` 才入队；预览写到 `dist/push-doc-preview.md`
+- HTML 会先裁掉侧栏导航、复制按钮、脚本、样式与统计卡，再用思源桥自带的
+  `/api/paste/html`（只读）转成 Markdown，不会把界面文字塞进笔记
+- 队列里已有同名稿时**默认不重复投递**；手册更新后要再投一份需显式 `--force`
+- 同样**只入队、不 commit**，写入仍由你在思源桥界面确认
+
+### 插件怎么更新（DSH 插件页有没有「更新」按钮）
+
+**有，但只对特定安装来源显示**，这是 DSH 插件页的规则（从 DSH 内置文档确认）：
+
+| 安装来源 | 更新方式 |
+|---|---|
+| 注册表（npm）安装的第三方组合包 | 详情页有「版本」区块与**更新**按钮，可查新版本并升级 |
+| Git 仓库安装的组合包（`update: 'git'`） | 通过「发现」页 / 详情页的**更新到**升级 |
+| 官方按需插件 | 有显式**更新**（版本或开发链接来源不同时） |
+| **本地路径 / `link:` / 压缩包安装的** | **不显示版本区块**，文档写明「通过卸载后重新安装升级」 |
+
+本仓库插件在本机是 **`link:` 挂载**（`node_modules/dsh-session-index` 是指向仓库目录的
+junction），所以插件页**不会有更新按钮**——但也不需要：
+
+```bash
+git -C <仓库目录> pull     # 代码就在 junction 指向的目录里，pull 完即更新
+# 然后完全退出 DSH 再打开（MCP 子进程在启动时加载）
+```
+
+不需要卸载、不需要重新安装、不需要发布 npm 包。若你以后改成从插件页输入
+`github:Lau-Jin/DSH` 安装，才会变成 Git 来源、出现「更新」入口，但那样就不再跟随本地
+开发目录，且每次更新要走一遍 GitHub 下载（本机实测 80–100 秒）。
+
+> 发布给别人用只需要 `git push`；本机生效只需要 `git pull` + 重启 DSH。
+
+---
+
+## 更新 / 校验 / 回滚
+
+```bash
+# Windows
+update.cmd              # git pull + 重装（保留 env 自定义）
+
+# macOS / Linux
+./update.sh
+```
+
+```bash
+node install.mjs --doctor        # 环境体检（7 项，装不上时先跑这个）
+node install.mjs --verify        # 6 项状态校验
+node install.mjs --dry-run       # 预览改动，不写文件
+node install.mjs --uninstall     # 移除配置块与自动装的 Skill（先备份）
+node install.mjs --reset-env     # 用默认值覆盖 env 自定义
+node smoke.mjs                   # 80 项端到端自测
+```
+
+---
+
+## 分发包（离线 / 无 git 环境）
+
+`install.mjs` 每次运行会自动生成：
+
+| 文件 | 内容 | 用途 |
+|---|---|---|
+| `dist/dsh-session-index-v2.5.1.zip` | 全部源码 + 清单 + 文档 + 手册 + 脚本 + `MANIFEST.json` + `INSTALL.md` | 完整分发，解压后双击 `install.cmd` |
+| `dist/session-index-skill-v2.5.1.zip` | 根 `SKILL.md` + 说明 | 直接导入 DSH「MCP 与技能」 |
+
+包内**排除**：索引分片 `*.jsonl.gz`、`meta/cards/notes/vectors.json`、备份与临时文件、已有 zip。
+已验证包内无任何会话数据与密钥，可安全分发。也可随时 `node pack.mjs` 重打，或调 MCP 工具 `session_index_package`。
+
+---
+
+## 配置项
+
+全部通过配置块的 `env` 设置。改哪里取决于安装方式：
+
+- **插件页安装**：改插件包内的 `cordis.patch.yml`（`<profile>/node_modules/dsh-session-index/cordis.patch.yml`），改完重启 DSH；
+- **clone + 脚本**：改 `~/.dsh/profiles/desktop/cordis.patch.yml` 里 `>>> session-index` 标记块内的 `env`，重跑 `node install.mjs` 会保留你写的值。
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `SESSION_INDEX_AUTO` | `1` | 总开关，`0` 关闭后台自动维护 |
+| `SESSION_INDEX_AUTO_INTERVAL_MS` | `60000` | 定时增量刷新间隔（最小 15000） |
+| `SESSION_INDEX_AUTO_QUIET_MS` | `45000` | 已有会话的静止期（活跃时不重建） |
+| `SESSION_INDEX_WATCH` | `1` | 文件事件监听开关 |
+| `SESSION_INDEX_WATCH_DEBOUNCE_MS` | `3500` | 写入事件防抖 |
+| `SESSION_INDEX_WATCH_QUIET_MS` | `6000` | 监听路径的静止期 |
+| `SESSION_INDEX_APPS` | `all` | 只索引 `dsh` 或 `workbuddy` |
+| `SESSION_INDEX_DIR` | `~/.dsh/session-index` | 索引产物目录 |
+| `SESSION_INDEX_EMBED_URL` / `_MODEL` / `_KEY` | 空 | 可选，OpenAI 兼容 embedding；不配则纯本地 |
+
+> 改完这些值后**不要加 `--reset-env`**；正常重跑安装会保留它们。
+
+---
+
+## 目录结构
+
+```text
+dsh-session-index/                  # 仓库根 = 插件根
+├── server.mjs                      # MCP stdio server（14 工具 / prompts / resources）
+├── cordis.patch.yml                # bundle patch：挂宿主行 + MCP 行（含 !!js 自解析路径）
+├── build-index.mjs                 # 索引构建（多帧 zstd → 可检索记录 + 会话卡）
+├── install.mjs                     # 安装 / 校验 / 卸载 / 自动打包
+├── pack.mjs                        # 打包 CLI（零依赖 ZIP writer）
+├── smoke.mjs                       # 80 项端到端自测
+├── install.cmd / install.sh        # 一键安装（双击 / 执行）
+├── update.cmd / update.sh          # 更新（git pull + 重装）
+├── icon.svg                        # 插件页图标（package.json 的 icon 字段指向它）
+├── plugin.json                     # 机器可读能力清单（也通过 MCP 资源暴露）
+├── package.json                    # 元信息 + dsh.bundle.patch + dsh.plugin 声明
+├── 操作使用手册.html                # 自包含单页手册（14 章）
+├── lib/
+│   ├── index.mjs                   # 宿主半身：解析自身安装路径（ESM，供 bundle 挂载）
+│   ├── reader.mjs                  # 多帧 zstd 读取
+│   ├── extract.mjs                 # 事件 → 文本记录（含系统注入降噪）
+│   ├── cards.mjs                   # 会话卡 / 关联度 / 血缘
+│   ├── index-store.mjs             # 分片存储与增量签名
+│   ├── source-workbuddy.mjs        # WorkBuddy 会话适配器
+│   ├── semantic.mjs                # 同义词扩展 + BM25
+│   ├── embedding.mjs               # 可选向量检索
+│   ├── notes.mjs                   # 长期记忆库
+│   ├── auto.mjs                    # 自动建索引 / 定时刷新
+│   ├── watch.mjs                   # 文件事件监听
+│   ├── pack.mjs                    # ZIP writer
+│   └── stage.mjs                   # 会话整理 → 思源桥待入库（渲染 + HTTP 投递）
+├── skill/SKILL.md                  # 自动接入用技能
+├── tools/push-doc.mjs             # 推送任意 md/html 到思源桥待入库（默认只读预览）
+└── dist/                           # 自动生成的分发包（git 忽略）
+```
+
+索引产物写入 `~/.dsh/session-index/`，**与仓库目录分离**，所以换 clone 位置不会丢索引。
+
+---
+
+## 隐私与安全
+
+- **源会话只读**：任何操作都不修改 `~/.dsh/sessions/` 与 `~/.workbuddy/projects/` 下的原始文件。
+- **配置写前备份**：每次改 `cordis.patch.yml` 都先复制为 `.bak-<时间戳>`。
+- **不入库**：索引、长期记忆、备份、验证产物均在 `.gitignore` 中排除。
+- **索引含会话原文**：`~/.dsh/session-index/` 是会话全文的本地副本，**不要打包外传**；分发请用 `dist/` 里的 zip（已自动排除）。
+
+---
+
+## 卸载
+
+- **插件页安装的**：插件页里禁用或卸载 `dsh-session-index`，重启 DSH 即可（MCP 行随 bundle 一起消失）。
+- **clone + 脚本安装的**：`node install.mjs --uninstall`，移除配置块与自动安装的 Skill（先备份）。
+
+两种情况下索引目录 `~/.dsh/session-index/` 都保留（不影响原始会话），需要时手动删除。
+
+---
+
+## 变更记录
+
+| 版本 | 变更 |
+|---|---|
+| **v2.5.1** | `tools/push-doc.mjs` 增加 **`--from-workbuddy` 批量模式**：扫描 WorkBuddy 全部会话产出的文档，按内容哈希去重、排除临时/依赖目录、逐篇查重后一次性投递到思源桥待入库；默认只读预览，`--send` 才入队，`--no-exclude` / `--include-txt` / `--source` / `--limit` / `--since` / `--force` 可控。修掉按 `chars` 判重不稳的问题（思源桥会规整正文）。README 补「插件怎么更新」章节。 |
+| **v2.5.0** | 新增第 14 个工具 `session_index_stage`：**会话整理文档 → 思源桥「待入库」队列**。两步确认（预览返回令牌，原样回传 `confirmWith` 才投递）、按标题+字数去重、支持主题/指定会话/三种模板/落点配置，**绝不自动写入思源笔记库**。读取状态与队列可传 `status: true`。 |
+| **v2.4.1** | 新增 `install.mjs --doctor` **环境体检**（7 项，只读），覆盖插件页安装失败的四个真实成因：git URL 重写镜像、pnpm `fetch-timeout` 超上限、远端大 tarball、lockfile 残留 `git+ssh`。README 增加「插件页装不上」排障章节。 |
+| **v2.4.0** | 支持 **DSH 插件页直接安装**：新增 `dsh.bundle.patch` 声明与 `cordis.patch.yml`（含 `!!js` 自解析表达式），新增宿主半身 `lib/index.mjs`。安装路径由运行时探测，不再依赖手工配置；`install.mjs` 自动识别 bundle 模式，避免与插件页安装重复注册。仓库转公开。 |
+| v2.3.0 | 仓库收敛为单插件，仓库根即插件根；新增 `install.cmd/sh`、`update.cmd/sh`；重装保留手工改过的 env。 |
+| v2.2.0 | 新增文件事件驱动的免重启识别（`fs.watch` + 静止期）、MCP 变更通知。 |
+| v2.1.0 | 新增跨会话关联 / 血缘链 / 长期记忆（`remember` / `recall` / `forget`）。 |
+| v2.0.0 | 从「全文检索」重构为「会话卡 + 结构化速览」。 |
+
+---
+
+## 许可
+
+MIT