dsh-session-index-lau 2.4.1 → 2.5.2

package/README.md

@@ -1,13 +1,13 @@
-# dsh-session-index-lau
+# dsh-session-index
 
 > DSH（DeepSeek Harness）+ WorkBuddy 的**全会话索引与跨会话记忆** MCP 插件。
 > 拉取仓库 → 双击安装 → 之后全自动。零第三方依赖，源会话文件全程只读。
 
 | 项目 | 值 |
 |---|---|
-| 版本 | **v2.4.1** |
+| 版本 | **v2.5.2** |
 | 运行要求 | Node **≥ 22.15**（需要 `zlib.zstdDecompressSync`） |
-| MCP 能力 | **13 个工具** / 4 个提示词 / 8 个资源 |
+| MCP 能力 | **14 个工具** / 4 个提示词 / 8 个资源 |
 | 第三方依赖 | **0**（只用 Node 标准库） |
 | 完整手册 | [`操作使用手册.html`](./操作使用手册.html)（单页 14 章，导航 / 搜索 / 一键复制） |
 
@@ -41,8 +41,8 @@ DSH 的会话存在 `~/.dsh/sessions/` 下，是**上千个独立 zstd 帧拼接
 
 | 行 id | 包 | 作用 |
 |---|---|---|
-| `session-index-host` | `dsh-session-index-lau` | 宿主半身（`lib/index.mjs`）：用 `import.meta.url` 解析**真实安装目录**，把 `server.mjs` 绝对路径写进 `~/.dsh/session-index/server-path.txt` |
-| `mcp-session-index` | `@deepseek-ai/dsh-mcp-client` | MCP stdio 客户端：13 工具 / 4 提示词 / 8 资源 |
+| `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 标准安装位置」依次探测。
@@ -176,6 +176,7 @@ node install.mjs --doctor
 | `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` 等。
@@ -186,6 +187,150 @@ node install.mjs --doctor
 
 ---
 
+## 会话整理 → 思源桥「待入库」
+
+`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
+node tools/push-doc.mjs --from-workbuddy --seed         # 只记状态基线，不投递任何文档
+```
+
+数据源是 `~/.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 篇（含此前单推的手册）。
+可用 `--limit`（默认 60）与 `--since` 收窄。
+
+**判重：对齐思源桥 `autoStage` 的 `.auto-staged.json`，但丢弃后不重新获取。**
+
+状态文件 `~/.dsh/session-index/push-doc-state.json`（`PUSH_DOC_STATE` 可改）按
+「文档路径 + 内容 sha256」记录已推送过的文档，**判重不看队列里还在不在**：
+
+- 在思源桥里「丢弃」某篇 → 下次自动化**不会**把它重新推送回来
+- 队列被清空、服务重启、定时任务重跑 → 同样不会重复入队
+- 内容真的改了 → 作为新版本投递一次，之后又不再重复
+- `--force` 可强制绕过；`--seed` 只写状态基线、不投递（首次启用或迁移时用）
+
+- **默认只预览**，加 `--send` 才入队；预览写到 `dist/push-doc-preview.md`
+- HTML 会先裁掉侧栏导航、复制按钮、脚本、样式与统计卡，再用思源桥自带的
+  `/api/paste/html`（只读）转成 Markdown，不会把界面文字塞进笔记
+- 同样**只入队、不 commit**，写入仍由你在思源桥界面确认
+
+### 插件怎么更新（DSH 插件页有没有「更新」按钮）
+
+**有，但只对特定安装来源显示**，这是 DSH 插件页的规则（从 DSH 内置文档确认）：
+
+| 安装来源 | 更新方式 |
+|---|---|
+| 注册表（npm）安装的第三方组合包 | 详情页有「版本」区块与**更新**按钮，可查新版本并升级 |
+| Git 仓库安装的组合包（`update: 'git'`） | 通过「发现」页 / 详情页的**更新到**升级 |
+| 官方按需插件 | 有显式**更新**（版本或开发链接来源不同时） |
+| **本地路径 / `link:` / 压缩包安装的** | **不显示版本区块**，文档写明「通过卸载后重新安装升级」 |
+
+**本机当前是 npm registry 来源**：profile 依赖 `dsh-session-index-lau: ^2.5.2`，
+属于上表第一行，所以插件页**有「版本」区块与「更新」按钮**——以后发新版后
+**点更新即可，不需要卸载重装**。命令行 `pnpm update <包名>` 与点按钮是同一条路径。
+
+发布侧走 `dist/publish/` 下的标准流程（`插件发布标准流程.md`）：
+
+```bash
+node sync-publish.mjs session-index                       # 生成改名后的发布副本并自检
+cd dsh-session-index-lau && npm publish --access public
+# 等 npm staged publishing 生效（实测约 1 分钟）
+cd ~/.dsh/profiles/desktop && npx -y pnpm@11.28.5 update dsh-session-index-lau@<新版本>
+```
+
+注意 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 要同步登记新版本，
+否则供应链冷却期会让 pnpm 静默回退旧版。更新后**完全退出 DSH 再打开**，
+运行中的 MCP 子进程才会换成新版。
+
+> 只有从本地路径 / `link:` / 压缩包安装的才没有更新按钮（需卸载重装）；
+> 这类挂载因为直接指向仓库目录，`git pull` + 重启即生效，同样不用重装。
+> 发布给别人用需要 `git push` + `npm publish`；本机开发目录则 `git pull` 即可。
+
+---
+
 ## 更新 / 校验 / 回滚
 
 ```bash
@@ -202,7 +347,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                   # 66 项端到端自测
+node smoke.mjs                   # 80 项端到端自测
 ```
 
 ---
@@ -213,8 +358,8 @@ node smoke.mjs                   # 66 项端到端自测
 
 | 文件 | 内容 | 用途 |
 |---|---|---|
-| `dist/dsh-session-index-lau-v2.4.1.zip` | 全部源码 + 清单 + 文档 + 手册 + 脚本 + `MANIFEST.json` + `INSTALL.md` | 完整分发，解压后双击 `install.cmd` |
-| `dist/session-index-skill-v2.4.1.zip` | 根 `SKILL.md` + 说明 | 直接导入 DSH「MCP 与技能」 |
+| `dist/dsh-session-index-v2.5.2.zip` | 全部源码 + 清单 + 文档 + 手册 + 脚本 + `MANIFEST.json` + `INSTALL.md` | 完整分发，解压后双击 `install.cmd` |
+| `dist/session-index-skill-v2.5.2.zip` | 根 `SKILL.md` + 说明 | 直接导入 DSH「MCP 与技能」 |
 
 包内**排除**：索引分片 `*.jsonl.gz`、`meta/cards/notes/vectors.json`、备份与临时文件、已有 zip。
 已验证包内无任何会话数据与密钥，可安全分发。也可随时 `node pack.mjs` 重打，或调 MCP 工具 `session_index_package`。
@@ -225,7 +370,7 @@ node smoke.mjs                   # 66 项端到端自测
 
 全部通过配置块的 `env` 设置。改哪里取决于安装方式：
 
-- **插件页安装**：改插件包内的 `cordis.patch.yml`（`<profile>/node_modules/dsh-session-index-lau/cordis.patch.yml`），改完重启 DSH；
+- **插件页安装**：改插件包内的 `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` 会保留你写的值。
 
 | 变量 | 默认 | 说明 |
@@ -247,13 +392,13 @@ node smoke.mjs                   # 66 项端到端自测
 ## 目录结构
 
 ```text
-dsh-session-index-lau/                  # 仓库根 = 插件根
-├── server.mjs                      # MCP stdio server（13 工具 / prompts / resources）
+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                       # 66 项端到端自测
+├── smoke.mjs                       # 80 项端到端自测
 ├── install.cmd / install.sh        # 一键安装（双击 / 执行）
 ├── update.cmd / update.sh          # 更新（git pull + 重装）
 ├── icon.svg                        # 插件页图标（package.json 的 icon 字段指向它）
@@ -272,8 +417,10 @@ dsh-session-index-lau/                  # 仓库根 = 插件根
 │   ├── notes.mjs                   # 长期记忆库
 │   ├── auto.mjs                    # 自动建索引 / 定时刷新
 │   ├── watch.mjs                   # 文件事件监听
-│   └── pack.mjs                    # ZIP writer
+│   ├── pack.mjs                    # ZIP writer
+│   └── stage.mjs                   # 会话整理 → 思源桥待入库（渲染 + HTTP 投递）
 ├── skill/SKILL.md                  # 自动接入用技能
+├── tools/push-doc.mjs             # 推送任意 md/html 到思源桥待入库（默认只读预览）
 └── dist/                           # 自动生成的分发包（git 忽略）
 ```
 
@@ -292,7 +439,7 @@ dsh-session-index-lau/                  # 仓库根 = 插件根
 
 ## 卸载
 
-- **插件页安装的**：插件页里禁用或卸载 `dsh-session-index-lau`，重启 DSH 即可（MCP 行随 bundle 一起消失）。
+- **插件页安装的**：插件页里禁用或卸载 `dsh-session-index`，重启 DSH 即可（MCP 行随 bundle 一起消失）。
 - **clone + 脚本安装的**：`node install.mjs --uninstall`，移除配置块与自动安装的 Skill（先备份）。
 
 两种情况下索引目录 `~/.dsh/session-index/` 都保留（不影响原始会话），需要时手动删除。
@@ -303,6 +450,9 @@ dsh-session-index-lau/                  # 仓库根 = 插件根
 
 | 版本 | 变更 |
 |---|---|
+| **v2.5.2** | 发布流程标准化：新增发布前/后核验门禁（`dist/publish/check-release.mjs`），把「检查并核验 → 确认版本可用 → 才推进标准流程」固化为强制步骤；标准流程文档同步新机制（批量推送、持久化判重、定时自动化）与版本统一矩阵。把源仓库已生效的持久化判重脚本同步进发布包与 DSH 安装，消除「同版本号、内容不同」的分叉。 |
+| **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。 |

package/install.cmd

@@ -3,13 +3,13 @@ rem Pure ASCII output on purpose: cmd.exe mis-parses UTF-8 .cmd files
 rem (multibyte chars break the parser), so keep every echo line ASCII.
 setlocal EnableExtensions EnableDelayedExpansion
 chcp 65001 >nul 2>nul
-title dsh-session-index-lau installer
+title dsh-session-index installer
 
 set "PLUGIN_DIR=%~dp0"
 if "%PLUGIN_DIR:~-1%"=="\" set "PLUGIN_DIR=%PLUGIN_DIR:~0,-1%"
 
 echo ============================================================
-echo   dsh-session-index-lau installer
+echo   dsh-session-index installer
 echo   Plugin dir: %PLUGIN_DIR%
 echo ============================================================
 echo.

package/install.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# dsh-session-index-lau 一键安装（macOS / Linux / Git Bash）
+# dsh-session-index 一键安装（macOS / Linux / Git Bash）
 # 用法: ./install.sh              安装
 #       ./install.sh --verify     校验
 #       ./install.sh --uninstall  回滚
@@ -9,7 +9,7 @@ PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$PLUGIN_DIR" || exit 1
 
 echo "============================================================"
-echo "  dsh-session-index-lau 一键安装"
+echo "  dsh-session-index 一键安装"
 echo "  插件目录: $PLUGIN_DIR"
 echo "============================================================"
 echo

package/lib/index-store.mjs

@@ -54,7 +54,26 @@ export function loadCards(indexDir) {
 function atomicWrite(filePath, data) {
   const tmp = `${filePath}.tmp-${process.pid}`;
   fs.writeFileSync(tmp, data);
-  fs.renameSync(tmp, filePath);
+  // Windows 上目标文件被另一进程短暂占用时 rename 会抛 EPERM/EACCES。
+  // DSH 的 MCP 服务与冒烟/手动构建可能同时写同一份索引，做短退避重试。
+  const delays = [0, 40, 120, 300];
+  let last;
+  for (const delay of delays) {
+    if (delay) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+    try {
+      fs.renameSync(tmp, filePath);
+      return;
+    } catch (err) {
+      last = err;
+      if (!['EPERM', 'EACCES', 'EBUSY'].includes(err.code)) break;
+    }
+  }
+  try {
+    fs.unlinkSync(tmp);
+  } catch {
+    // 清理失败不影响错误上报
+  }
+  throw last;
 }
 
 export function saveMeta(indexDir, meta) {

package/lib/stage.mjs

@@ -0,0 +1,231 @@
+/**
+ * 会话整理文档 → 思源桥「待入库」队列（服务层 + 仓储层）。
+ *
+ * 边界（刻意为之）：
+ *   - 本模块**不读索引、不碰会话文件**，源数据由 server.mjs 控制器组装后传入；
+ *   - 只调用 /api/status、/api/stage（GET/POST），**绝不调用 /api/stage/commit**；
+ *     写进思源笔记库这一步永远留给人在思源桥界面确认；
+ *   - 只允许回环地址，避免工具被误用来打任意内网服务。
+ *
+ * 两步确认（无状态）：预览返回 token = sha256(标题 + 落点 + 正文)。
+ * 确认时按同一组参数重新渲染、重算 token，一致才真正投递，防止「预览 A、投递 B」。
+ */
+import { createHash } from 'node:crypto';
+
+const DEFAULT_PORT = 5599;
+const MAX_MARKDOWN = 60000;
+const DEFAULT_TIMEOUT = 5000;
+
+/** 配置集中解析：全部来自环境变量，启动时不需要外部依赖。 */
+export function stageConfig(env = process.env) {
+  const port = String(env.SIYUAN_BRIDGE_PORT || DEFAULT_PORT);
+  const url = String(env.SIYUAN_BRIDGE_URL || `http://127.0.0.1:${port}`).replace(/\/+$/, '');
+  return {
+    url,
+    enabled: env.SESSION_INDEX_STAGE !== '0',
+    timeoutMs: Math.min(60000, Math.max(1000, Number(env.SESSION_INDEX_STAGE_TIMEOUT_MS) || DEFAULT_TIMEOUT)),
+    defaultHpath: env.SESSION_INDEX_STAGE_HPATH || '/会话札记/思源',
+    defaultNotebook: env.SESSION_INDEX_STAGE_NOTEBOOK || '思源桥',
+    maxMarkdown: MAX_MARKDOWN,
+  };
+}
+
+/** 拒绝非回环地址：这个工具只应该跟本机的思源桥说话。 */
+export function assertLoopback(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error('SIYUAN_BRIDGE_URL 不是合法 URL');
+  }
+  const host = parsed.hostname;
+  const ok = parsed.protocol === 'http:' && (host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]');
+  if (!ok) throw new Error('思源桥地址必须是本机回环地址（127.0.0.1 / localhost）');
+  return parsed;
+}
+
+/** 类型化错误：客户端只看到规范化结构，不暴露堆栈与内部细节。 */
+export class StageError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'StageError';
+    this.code = code;
+    this.detail = detail;
+  }
+  toJSON() {
+    return { ok: false, code: this.code, error: this.message, detail: this.detail };
+  }
+}
+
+const clean = (s, max = 200) => String(s ?? '').replace(/[\\/:*?"<>|\r\n]+/g, ' ').trim().slice(0, max);
+const stamp = (ts) => {
+  if (!ts) return '时间未知';
+  const d = new Date(ts);
+  return Number.isNaN(d.getTime()) ? '时间未知' : d.toLocaleString('zh-CN', { hour12: false });
+};
+
+/** 渲染会话整理文档：纯函数，无副作用，便于单测。 */
+export function buildStageDocument(sources = {}, opts = {}) {
+  const template = ['brief', 'decisions', 'detail'].includes(opts.template) ? opts.template : 'brief';
+  const sessions = Array.isArray(sources.sessions) ? sources.sessions : [];
+  const memories = Array.isArray(sources.memories) ? sources.memories : [];
+  const hits = Array.isArray(sources.hits) ? sources.hits : [];
+  const topic = clean(opts.query || '', 60);
+  const date = new Date();
+  const day = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  const hhmm = `${String(date.getHours()).padStart(2, '0')}时${String(date.getMinutes()).padStart(2, '0')}分`;
+  const title = clean(opts.title || `会话整理 · ${day} ${hhmm} · ${topic || `${sessions.length} 个会话`}`, 120)
+    || `会话整理 · ${day} ${hhmm}`;
+
+  const dshCount = sessions.filter((s) => (s.app || 'dsh') === 'dsh').length;
+  const wbCount = sessions.length - dshCount;
+  const lines = [
+    `# ${title}`,
+    '',
+    `> 来源：session-index · ${sessions.length} 个会话（DSH ${dshCount} / WorkBuddy ${wbCount}）· 生成于 ${stamp(date.getTime())}`,
+    `> 模板：${template} · 范围：${opts.app || 'all'}${topic ? ` · 主题：${topic}` : ''}`,
+    '> 本稿仅投递到思源桥「待入库」队列，**未写入笔记库**，需人工确认。',
+    '',
+  ];
+
+  if (!sessions.length && !memories.length && !hits.length) {
+    lines.push('（没有可整理的内容：换个主题词、放宽时间范围，或先确认索引已建好）', '');
+  }
+
+  if (sessions.length) {
+    if (template === 'decisions') {
+      lines.push('## 结论与决策', '');
+      let n = 0;
+      for (const s of sessions) {
+        for (const d of (s.decisions || [])) {
+          lines.push(`- ${String(d).replace(/\s+/g, ' ').trim()}  — ${clean(s.title, 60)}`);
+          n++;
+        }
+      }
+      if (!n) lines.push('（这些会话卡里没有抽取到结论，可改用 template=detail 看原文片段）');
+      lines.push('');
+    } else {
+      lines.push('## 会话速览', '');
+      sessions.forEach((s, i) => {
+        lines.push(`### ${i + 1}. ${clean(s.title || '（无标题）', 90)}`, '');
+        lines.push(`- 应用：${s.app || 'dsh'} · 更新：${stamp(s.updatedAt)} · 会话：\`${clean(s.id, 48)}\``);
+        if (s.workspace) lines.push(`- 工作区：\`${clean(s.workspace, 90)}\``);
+        if (s.digest) lines.push(`- 摘要：${String(s.digest).replace(/\s+/g, ' ').trim()}`);
+        if ((s.decisions || []).length) {
+          lines.push('- 结论：');
+          for (const d of s.decisions) lines.push(`  - ${String(d).replace(/\s+/g, ' ').trim()}`);
+        }
+        if ((s.questions || []).length) lines.push(`- 提问：${s.questions.map((q) => String(q).replace(/\s+/g, ' ').trim()).join('；')}`);
+        if ((s.keywords || []).length) lines.push(`- 关键词：${s.keywords.join('、')}`);
+        lines.push('');
+      });
+    }
+  }
+
+  if (memories.length && template !== 'decisions') {
+    lines.push('## 长期记忆', '');
+    for (const m of memories) lines.push(`- [${m.type || 'note'} · 重要度 ${m.importance ?? 0}] ${String(m.text).replace(/\s+/g, ' ').trim()}`);
+    lines.push('');
+  } else if (memories.length) {
+    const decisions = memories.filter((m) => ['decision', 'fact', 'pitfall'].includes(m.type));
+    if (decisions.length) {
+      lines.push('## 相关长期记忆', '');
+      for (const m of decisions) lines.push(`- [${m.type}] ${String(m.text).replace(/\s+/g, ' ').trim()}`);
+      lines.push('');
+    }
+  }
+
+  if (template === 'detail' && hits.length) {
+    lines.push('## 检索命中片段', '');
+    for (const h of hits) {
+      lines.push(`**${clean(h.title || h.sessionId || '片段', 80)}** · ${h.app || ''} · seq ${h.seq ?? '-'}`, '');
+      lines.push('```text', String(h.snippet || h.text || '').trim(), '```', '');
+    }
+  }
+
+  lines.push('---', '', `共 ${sessions.length} 个会话 · ${memories.length} 条记忆 · ${hits.length} 个片段`);
+  const markdown = lines.join('\n');
+  if (markdown.length > MAX_MARKDOWN) {
+    throw new StageError('DOC_TOO_LARGE', `文档超过 ${MAX_MARKDOWN} 字上限`, `${markdown.length} 字，请调小 limit / maxChars`);
+  }
+  return { title, markdown, chars: markdown.length };
+}
+
+/** 预览令牌：把标题、落点与正文一起绑定，避免确认时内容被换掉。 */
+export function stageToken(doc, opts = {}) {
+  const raw = [doc.title, opts.notebook || '', opts.hpath || '', opts.note || '', doc.markdown].join('\n');
+  return createHash('sha256').update(raw).digest('hex').slice(0, 24);
+}
+
+async function requestJSON(url, path, { method = 'GET', body, timeoutMs } = {}) {
+  assertLoopback(url);
+  let res;
+  try {
+    res = await fetch(url + path, {
+      method,
+      headers: body ? { 'content-type': 'application/json' } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    throw new StageError('BRIDGE_UNREACHABLE', '思源桥服务不可达', `${url}${path} · ${err.name}: ${err.message}`);
+  }
+  const text = await res.text().catch(() => '');
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    throw new StageError('BRIDGE_BAD_RESPONSE', '思源桥返回了非 JSON 响应', `${path} · HTTP ${res.status}`);
+  }
+  if (!res.ok) {
+    const msg = data.error || data.message || `HTTP ${res.status}`;
+    throw new StageError('BRIDGE_ERROR', '思源桥拒绝了请求', `${path} · ${msg}`);
+  }
+  return data;
+}
+
+/** 只读探测：服务是否活着、队列里有多少篇、自动接入目录在哪。 */
+export async function bridgeOverview(cfg) {
+  const [status, queue, autostage] = await Promise.all([
+    requestJSON(cfg.url, '/api/status', { timeoutMs: cfg.timeoutMs }),
+    requestJSON(cfg.url, '/api/stage', { timeoutMs: cfg.timeoutMs }),
+    requestJSON(cfg.url, '/api/autostage', { timeoutMs: cfg.timeoutMs }).catch(() => null),
+  ]);
+  return {
+    ok: true,
+    service: cfg.url,
+    kernel: status.kernel || null,
+    queued: Array.isArray(queue.items) ? queue.items.length : (status.staged ?? 0),
+    discarded: queue.discarded ?? 0,
+    autoStageDir: autostage?.dir || null,
+    autoStageEnabled: autostage?.enabled ?? null,
+    note: '只读取状态，未做任何写入',
+  };
+}
+
+/** 按「标题 + 字数」检查队列里是否已有同一份稿，避免重复入队。 */
+export async function findDuplicate(cfg, doc) {
+  const queue = await requestJSON(cfg.url, '/api/stage', { timeoutMs: cfg.timeoutMs });
+  const items = Array.isArray(queue.items) ? queue.items : [];
+  return items.find((it) => String(it.title || '').trim() === doc.title && Number(it.chars) === doc.chars) || null;
+}
+
+/** 唯一允许的写操作：投递到待入库队列。绝不 commit。 */
+export async function postStage(cfg, doc, opts = {}) {
+  const payload = {
+    title: doc.title,
+    markdown: doc.markdown,
+    notebook: opts.notebook || cfg.defaultNotebook,
+    hpath: opts.hpath || cfg.defaultHpath,
+    note: clean(opts.note || `session-index · ${opts.template || 'brief'} · 预览确认后投递`, 200),
+  };
+  const result = await requestJSON(cfg.url, '/api/stage', {
+    method: 'POST', body: payload, timeoutMs: cfg.timeoutMs,
+  });
+  return {
+    ok: true, staged: true,
+    id: result.id || null, title: result.title || doc.title,
+    chars: doc.chars, notebook: payload.notebook, hpath: payload.hpath,
+    next: '在思源桥「待入库」里勾选写入；本工具不会自动写库',
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-index-lau",
-  "version": "2.4.1",
+  "version": "2.5.2",
   "type": "module",
   "description": "完全化的 DSH + WorkBuddy 全会话 MCP 插件：装到 DSH 里即用（bundle 自动挂载，无需手工改配置）、自动建索引、文件事件驱动识别新会话、MCP 变更通知、自动打包插件与技能。零第三方依赖，源会话只读。",
   "engines": {
@@ -37,7 +37,8 @@
     "*.yml",
     "lib/",
     "skill/",
-    "!dist/*.zip"
+    "tools/",
+    "dist/*.zip"
   ],
   "dsh": {
     "bundle": {

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-index-lau",
-  "version": "2.4.1",
+  "version": "2.5.2",
   "icon": "icon.svg",
   "displayName": {
     "zh": "全会话索引与跨会话记忆",
@@ -34,7 +34,7 @@
     "entry": "server.mjs",
     "resolvedBy": "cordis.patch.yml 的 !!js 表达式（按 环境变量 → 宿主记下的路径文件 → profile 标准安装位置 依次探测）",
     "capabilities": ["tools", "prompts", "resources", "instructions", "listChanged"],
-    "toolCount": 13,
+    "toolCount": 14,
     "tools": [
       "session_index_status",
       "session_index_brief",
@@ -48,7 +48,8 @@
       "session_index_forget",
       "session_index_package",
       "session_index_vectors",
-      "session_index_refresh"
+      "session_index_refresh",
+      "session_index_stage"
     ],
     "prompts": ["session-context", "resume-topic", "catch-up", "quickstart"],
     "resources": [
@@ -83,8 +84,8 @@
   },
   "packages": {
     "directory": "dist",
-    "plugin": "dsh-session-index-lau-v2.4.1.zip",
-    "skill": "session-index-skill-v2.4.1.zip",
+    "plugin": "dsh-session-index-lau-v2.5.2.zip",
+    "skill": "session-index-skill-v2.5.2.zip",
     "generator": "lib/pack.mjs (zero dependency ZIP writer)",
     "contents": ["MANIFEST.json", "INSTALL.md"],
     "excludes": ["会话索引分片 *.jsonl.gz", "meta/cards/notes/vectors.json", "备份与临时文件", "已有 zip"]