slumberpavilion 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AngleNaris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# 沉眠阁 · slumberpavilion
 
-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 里「已归档」的会话**真正搬出加载路径**，并内置读取归档内容的能力。
+
+## 它为什么需要存在
+
+DSH 的「归档」只是一个标签，写进 `storages/workspace.json` 的 `archivedSessionIds`。
+官方 `archived-session-gate` 的原话是：
+
+> an archived Session ... must not run a model step until it is restored.
+
+它拦的是**能不能跑**，不是**占不占地方**。归档之后：
+
+- 会话日志仍留在 `.dsh/sessions/<工作区>/<会话id>/`
+- 投影记录仍留在 `.dsh/storages/session_projcache/sessions/<id>.json`
+
+而 `session_projcache` 用的是 JSON 存储后端，官方注释写明「读写共享存储域内一致的内存状态」——
+**全部记录常驻内存**。实测：2395 条记录 / 169.5 MB JSON，其中 126 条已归档的占 40.8 MB（24.1%），
+而它们只占条目数的 5%。归档的大多是长篇会话，正是最占地方的那批。
+
+本插件做三件事：
+
+1. 每隔一段时间检查 `archivedSessionIds`，发现新归档的会话
+2. 把它的日志目录与投影记录**移动**到 `~/DSH-Archive`（不是删除）
+3. `manifest.json` 记下来源与去向，随时可还原
+
+## 安装
+
+```bash
+npm install slumberpavilion
+```
+
+然后在 profile 的 `package.json` 里把包装进 bundles：
+
+```json
+"dependencies": {
+  "slumberpavilion": "^0.1.0"
+},
+"dsh": {
+  "profile": {
+    "bundles": [
+      "...",
+      "slumberpavilion"
+    ]
+  }
+}
+```
+
+重启 DSH。本地开发时可以用 `file:` 依赖 + 一条符号链接代替 npm 安装：
+
+```bash
+ln -s ../plugins/slumberpavilion ~/.dsh/profiles/desktop/node_modules/slumberpavilion
+```
+
+## 配置
+
+在 `cordis.patch.yml` 里，全部字段都是 volatile（改完热生效）：
+
+| 字段 | 默认 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 总开关 |
+| `archiveRoot` | `''` | 归档根目录，留空 = `~/DSH-Archive` |
+| `checkIntervalMs` | `20000` | 检查间隔（毫秒） |
+| `moveLogs` | `true` | 是否移动 `sessions` 下的日志目录 |
+| `moveProjections` | `true` | 是否移动 `session_projcache` 记录（**内存收益主要来自这里**） |
+
+## 读取归档
+
+### 方式一：命令行（不依赖 DSH，随时可用）
+
+```bash
+node lib/cli.js list 20
+node lib/cli.js read f8ab825e 上下文压缩 50
+node lib/cli.js info f8ab825e
+```
+
+### 方式二：Agent 工具
+
+注册五个工具，对话里可直接调用：
+
+| 工具 | 作用 |
+|---|---|
+| `archive_list` | 列出归档会话（按体积降序） |
+| `archive_read` | 读一个归档会话；`keyword` 过滤、`compact` 只留对话轮次、`maxChars` 逐条截断 |
+| `archive_session` | **执行归档**：标记 + 立刻搬走，不用等后台扫描；先 `dryRun=true` 看清目标 |
+| `archive_restore` | **还原归档**：搬回 `.dsh`、撤销归档标记、清清单；同样支持 `dryRun` |
+| `archive_delete` | 永久删除一个归档会话；先 `dryRun=true` 看清目标再动手 |
+
+`archive_session` 走的是宿主的 `ctx.workspaceRegistry.archiveSession()`，所以归档状态
+是 DSH 自己写进 `workspace.json` 的，不靠手改文件；标记落盘后插件立刻 `sweep()` 一轮，
+把日志与投影搬进归档区，返回里会报出最终目录。
+
+- 只认唯一命中：ID 或片段模糊命中多条时**拒绝执行**并列出候选，免得搬错会话。
+- 活跃会话默认拒绝（`WorkspaceActiveSessionError`）；确认要归档正在跑的会话，加
+  `stopActivity=true`，宿主会先请求停掉它的工作再归档。
+- 拒绝归档「正在执行这条工具的那个会话」，不然等于自断。
+
+`archive_restore` 是它的逆操作，顺序是「搬文件 → `unarchiveSession()` → 清清单」：
+
+- 目标位置已有同名目录时**拒绝**，让你先确认是不是重复还原。
+- 清单里记着原始的 `from`，还原优先搬回原位；没有记录时退回
+  `.dsh/sessions/<工作区>/<会话 ID>`。
+- 投影记录（`projcache`）跟着一起搬回；目标已存在的不覆盖。
+- 撤销标记失败时仍然搬文件，并在返回里明确警告「它仍算已归档，请在界面取消归档」。
+
+这层曾经整个是哑的，原因是三个叠在一起的问题，现在都修了：
+
+1. **没有声明 `inject`**。Cordis 里不 `export const inject = ["tools"]` 就读不了
+   `ctx.tools`，一读抛 `cannot get property "tools" without inject`；原来的代码把这句
+   写在 `try` 里，异常被吞掉，只剩一条 warn，工具永远静默缺席。
+2. **`await import("@deepseek-ai/dsh-tools")` 解析不到**。这个包只随宿主打包在
+   `app.asar` 里，profile 的 `node_modules` 没有它，Node 的 ESM 解析器又不认 asar。
+   改用 `createRequire(import.meta.url)`（Electron 主进程认得 asar 路径），同步取。
+3. **工具定义形状不对**。`defineTool` 收的是「属性表」，必填用 `required: true` 标在
+   属性上；`output.render(args, value)` 必须返回 `ContentBlock[]`。原来传的是完整
+   JSON Schema、`render` 直接返回字符串。
+
+取不到 `defineTool` 时还有一层本地兜底：`normalizeToolDefinition()` 自己把属性表
+展开成完整 JSON Schema，所以换机器/换宿主也不会两头空。
+
+> 排障：插件往 `%TEMP%\slumber-pavilion-diag.log` 记一行 apply、一行
+> defineTool 是否取到、每个工具是否注册成功。改了代码重载插件后先看这个文件。
+
+## 还原
+
+两种方式，效果一样：
+
+- 对话里 `archive_restore`（推荐）：搬文件、撤销标记、清清单一次做完，先跑 `dryRun` 看目标。
+- 手动：`manifest.json` 里每个条目都记着 `from`（原路径）与 `to`（归档路径），把 `to` 移回
+  `from`，再去界面里取消归档、从清单删掉那一条。
+
+## 已知边界
+
+- **扫描只处理「已归档」的会话**。归档标记由 DSH 写；`archive_session` 只是替你把这个
+  标记写进去，然后立刻搬文件。
+- 移动后 `workspace.json` 里的 `archivedSessionIds` 不会清理，指向一个不存在的会话。
+  实测这不影响启动（列表按投影记录渲染，记录没了就不显示）。
+- 若会话日志已被 DSH 重新折叠出新的投影记录，下次扫描会再搬一次。
+- 「已搬过」的判据覆盖**顶层与各批次目录**的 `manifest.json`。早先只读顶层那份，老批次
+  条目会被当成没搬过、每轮空转一次；现在不会了。
+- `archive_session` 只认磁盘上还在 `.dsh/sessions` 里的会话；只剩归档副本的请用
+  `archive_list` / `archive_read`。
+
+## 为什么解压要手写
+
+DSH 的 `session.v4.jsonl.zstd` 是**多帧** zstd（边写边追加，每追加一次一个独立帧）。
+Node 的 `zstdDecompressSync` 和 `createZstdDecompress` 都只解第一帧就收工——
+实测 1.1 MB 只解出 285 字节，恰好是会话头。
+
+所以 `reader.js` 按帧魔数 `28 B5 2F FD` 切开逐个解，切错就往后找下一个魔数重试。
+实测那个 60.6 MB 的会话：**31,528 帧，56,701 行，零失败**，压缩比约 ×3.8。
+
+## License
+
+MIT

package/assets/icon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128" role="img" aria-label="沉眠阁：浅底深形，旋转四十五度后四瓣呈菱形排列，中央一枚金点，四角紫色直角折线大幅出血出画">
+  <rect width="128" height="128" fill="#F3F0E9"/>
+
+  <g transform="translate(64 64) rotate(45) scale(0.95) translate(-64 -64)">
+    <rect x="30" y="30" width="28" height="28" fill="#1B1725"/>
+    <rect x="70" y="30" width="28" height="28" fill="#1B1725"/>
+    <rect x="30" y="70" width="28" height="28" fill="#1B1725"/>
+    <rect x="70" y="70" width="28" height="28" fill="#1B1725"/>
+
+    <rect x="60" y="60" width="8" height="8" fill="#B08A3E"/>
+
+    <g fill="none" stroke="#6B5CA5" stroke-width="2" stroke-linecap="butt" stroke-linejoin="miter">
+      <path d="M58 14 L14 14 L14 58"/>
+      <path d="M70 14 L114 14 L114 58"/>
+      <path d="M58 114 L14 114 L14 70"/>
+      <path d="M70 114 L114 114 L114 70"/>
+    </g>
+  </g>
+</svg>

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# 沉眠阁 / slumberpavilion 的 bundle 补丁层。
+#
+# 安装：把本包加进 profile 的 dsh.profile.bundles，下次启动加载器会自动应用这一层。
+#
+# 归档根目录留空（''）时使用默认值 ~/DSH-Archive。
+# 所有字段都是 volatile：在运行时改完立即生效，不需要重启。
+- insert:
+    - id: slumber-pavilion
+      name: slumberpavilion
+      config:
+        enabled: true
+        archiveRoot: ''
+        checkIntervalMs: 20000
+        moveLogs: true
+        moveProjections: true

package/lib/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// 归档会话的命令行入口。不依赖 DSH 运行时，任何 node 都能跑。
+//
+//   node lib/cli.js list [条数]
+//   node lib/cli.js read <会话ID或片段> [关键词] [行数]
+//   node lib/cli.js info <会话ID或片段>
+
+import path from "node:path";
+import { archiveRoot, findArchivedSession, listArchivedSessions, readArchivedSession } from "./reader.js";
+
+const [, , cmd = "list", a1, a2, a3] = process.argv;
+const ROOT = archiveRoot(process.env.DSH_ARCHIVE_ROOT || "");
+
+function mb(n) {
+	return ((n || 0) / 1048576).toFixed(1);
+}
+
+if (cmd === "list") {
+	const all = listArchivedSessions(ROOT);
+	const limit = Math.max(1, Math.min(500, Number(a1) || 30));
+	console.log("归档根目录：" + ROOT);
+	console.log("共 " + all.length + " 个会话，列出前 " + Math.min(limit, all.length) + " 个：\n");
+	for (const [i, x] of all.slice(0, limit).entries()) {
+		console.log(String(i + 1).padStart(3) + ". " + mb(x.bytes).padStart(8) + " MB  " + x.id + "  @" + x.workspace);
+	}
+} else if (cmd === "info") {
+	const hit = findArchivedSession(ROOT, a1);
+	if (!hit) {
+		console.log("找不到：" + a1);
+		process.exit(1);
+	}
+	const r = readArchivedSession(hit.dir, { limit: 1 });
+	console.log("会话：" + hit.id);
+	console.log("工作区：" + hit.workspace);
+	console.log("体积：" + mb(hit.bytes) + " MB");
+	console.log("目录：" + hit.dir);
+	console.log("总行数：" + r.total + "，压缩帧：" + r.frames);
+} else if (cmd === "read") {
+	const hit = findArchivedSession(ROOT, a1);
+	if (!hit) {
+		console.log("找不到：" + a1 + "\n先用 list 看看有哪些。");
+		process.exit(1);
+	}
+	const keyword = a2 && a2 !== "-" ? a2 : "";
+	const limit = Number(a3) || 40;
+	const r = readArchivedSession(hit.dir, { keyword, limit });
+
+	console.log("会话 " + hit.id + "  @" + hit.workspace);
+	console.log("总行数 " + r.total + "，匹配 " + r.matched + "，压缩帧 " + r.frames);
+	console.log("-".repeat(50));
+	for (const x of r.items) {
+		const tag = (x.kind ? "[" + x.kind + "]" : "") + (x.where || "");
+		console.log(tag + " " + x.body);
+	}
+	if (r.hasMore) console.log("… 还有更多，加大行数或用关键词过滤。");
+} else {
+	console.log("用法:");
+	console.log("  node lib/cli.js list [条数]");
+	console.log("  node lib/cli.js read <会话ID或片段> [关键词| - ] [行数]");
+	console.log("  node lib/cli.js info <会话ID或片段>");
+}