空间账本 wojiao42/dsh-space-optimizer

dsh-space-optimizer

侧栏底部常驻的 「优化空间」 按钮：点开是一份空间账本——每个任务占了多少、其中多少能优化、以及不属于任何任务的无主垃圾——核对清楚之后再逐项勾选确认。

占用 5.0 MB · 可优化 3.0 MB · 无主垃圾 8.3 MB · 已释放 11.7 MB

它只回收“无主垃圾”，绝不裁剪对话记录。 每个任务占的大头（会话日志）是规范状态，被用量、上下文、耗时等多个投影读取，因此账本只把它列出来、不提供任何瘦身手段。
能优化的只有三类附属产物：落盘的超大工具输出、被取代的旧格式日志、无人引用的附件。

截图

| 空间账本（浅色） | 优化完成 |
| 账本 | 已释放 |

| 按钮位置（侧栏底部） | 深色主题 |
| 按钮 | 深色 |

截图由 node tools/render-panel.mjs 生成：把真实组件渲染成 HTML（主题变量取自已安装的 dsh-client-ui-theme），再用无头 Chrome 出图。图中的任务名与路径是虚构样本，不是任何人的真实数据。

快速上手

1. 装：dsh plugin --profile web add github:OWNER/dsh-space-optimizer，刷新页面。
2. 点侧栏底部 「优化空间」，等 1～2 秒扫描（实测 9 个任务约 170 ms）。
3. 看清每一行之后：无主垃圾默认已勾选，任务级项目要你自己勾，然后点 「确认优化」。

面板底部实时显示「已选 N 项 · 可释放 X」；优化完成后给出「已释放 X（N 个文件）」。
不放心就先别勾——扫描是纯只读的，不点确认不会动任何一个字节。

界面

按钮挂在 sidebar.footer.action（和 token 费用徽标同一排，侧栏收起时只剩图标）。
点开面板分两段：

任务（每个会话一行，当前任务置顶并标注）

| 列 | 含义 |
| 占用 | 该任务在磁盘上独占的字节 = 日志 + 投影缓存 + 可优化项 |
| 日志 | ~/.dsh/sessions///session.v4.jsonl.zstd 当前 generation |
| 临时暂存 | 该任务落盘的超大工具输出（%TEMP%\dsh-spill-\session-\） |
| 可优化 | = 临时暂存 + 被取代的旧 generation |
| 引用附件 | 该任务引用的附件；共享的会标出来，合计里只算一次 |

标签：当前（主视图打开的那个）、运行中、子任务（origin: subagent，侧栏不显示但确实占空间）。
运行中与当前任务不可勾选——它的临时文件可能还在被读。

无主垃圾（不属于任何任务）

| 类别 | 判定 |
| 插件市场目录缓存 | 纯缓存，删了下一次打开插件市场会重新下载 |
| 无主临时文件 | ① 对应会话已不存在的 spill；② 闲置超过门槛、且不是当前进程在用的 %TEMP%\dsh- |
| 失效的投影缓存 | session_projcache 里对应会话已经不存在的行 |
| 无主附件对象 | 没有任何会话日志引用的附件 |

底部显示「已选 N 项 · 可释放 X」，确认后才发回收请求。

默认勾选策略：无主垃圾默认勾上（本来就是垃圾）；任务级项目默认不勾——清理任务级 spill 会让那段超大工具输出的全文只剩摘要，得由你自己点头。

口径：什么算“这个任务占的空间”

- 会话日志不是垃圾。 dsh-session 的事件契约里 assistant/message.stream 是必填字段，而 dsh-token-meter、dsh-client-ui-chat、dsh-session-stats、dsh-api-session-controller、 dsh-subagent、dsh-session-persistence-jsonl、dsh-client-connection 都靠它重算用量 / 上下文 / 首 token 耗时。任何“拆字段瘦身”都会打坏这些投影，所以日志只统计、不裁剪。
- 因此一个任务真正能安全优化的只有两处附属产物：落盘的临时暂存、以及被取代的旧格式日志。
- 附件是内容寻址存储（相同字节只存一份），所以按引用归属到任务，但总量只算一次；一个任务被删之后它独占的附件才变成无主垃圾。

安全设计

- 路径不出 Host。 渲染进程只能回传 Host 生成的 targetId（sha1(路径) 前 16 位）；回收时 Host 重新扫描一遍，只删本次仍然存在、且本次判定为可回收的目标。
认不出来的 id 一律忽略并如实回报 stale 数量（说明界面上的账本已经过期）。
- 不接受“清空一切”。 回收接口要求显式列出 targets，没有省略即全删的写法。
- 回收接口要求一个自定义头（x-space-optimizer）。这条路由挂在无需授权的本地 web server 上：浏览器对跨源简单请求不拦发送（只是不让读响应），所以一个被访问的网页原本可以匿名 POST 过来造成删除。带自定义头必然触发预检，而 Host 不应答预检，于是浏览器不会发出真实请求。同时拒绝 sec-fetch-site: cross-site。
（本地进程仍可调用，但它本来就能直接删这些文件，不是这条防线要挡的东西。）
- 删除前重新确认。 按闲置时长判定的条目会在删除前再 stat 一次，避免和刚写入的进程抢；删不掉的文件（被占用）记录进 failures，不中断整次回收。
- 保守优先。 只要有一份会话日志读不通，就无法证明某个附件“无主”——该类别整体放弃回收，并在界面上标注原因。同理，最新 generation 校验失败时，它下面的旧 generation 一律不删（无法证明“高版本能读”）。
- 不跟随符号链接；空的 %TEMP%\dsh- 根目录在内容清空后一并收走。
- spill 归属靠复现官方哈希：session- + sha256(sessionId) 前 12 位（见 dsh-spill-local 的会话目录规则），所以“属于仍在的会话”和“真孤儿”能分得清——这条规则是必需的：日志里存的是 spill 文件路径，删错就是那条对话永久读不回那段输出。

安装

方式一：直接从 GitHub 装（发布后的正式方式）

dsh plugin --profile web add github:OWNER/dsh-space-optimizer

刷新页面，侧栏底部出现「优化空间」。卸载：dsh plugin --profile web remove dsh-space-optimizer。

方式二：本地源码开发

| 位置 | 说明 |
| D:\deepseek workspace\plugins\dsh-space-optimizer | 源码，改这里 |
| D:\dsh-plugins\dsh-space-optimizer | 指向源码目录的目录联接（junction），作为安装源路径 |
| …\.dsh\profiles\desktop\node_modules\dsh-space-optimizer | 指向 D:\dsh-plugins\… 的目录联接 |

profile 的 package.json 里登记为组合包（必须用 pnpm 的 link: 协议， file: 会把目录复制进 node_modules，之后改源码不生效）：

"dependencies": { "dsh-space-optimizer": "link:D:/dsh-plugins/dsh-space-optimizer" },
"dsh": { "profile": { "bundles": [ "…", "dsh-space-optimizer" ] } }

文件

| 文件 | 作用 |
| package.json | 插件清单：dsh.bundle.patch 与 dsh.client（platform: web、immediately、inject: dsh-client-ui-sidebar） |
| lib/space.js | 账本与回收核心（纯文件系统，无 Cordis / 无 React 依赖） |
| index.js | Host 半侧：/space-optimizer/ledger、/space-optimizer/reclaim、/space-optimizer/config |
| client.js | 浏览器半侧：侧栏按钮 + 账本面板（构建产物直接提交，git 安装不跑构建） |
| cordis.patch.yml | 组合包 patch：插入 space-optimizer 行 |
| screenshots.json | 市场商店页截图声明（1–8 张仓库内相对路径） |
| assets/ | 截图与出图用的中间 HTML |
| tools/space-report.mjs | 只读命令行账本：node tools/space-report.mjs [--json] |
| tools/space-optimizer-test.mjs | 30 项离线断言（账目 + 回收语义） |
| tools/client-panel-test.mjs | 34 项离线断言（假 React 真渲染面板、交互请求体、协议异常） |
| tools/lib/harness.mjs | 共用的假 React / 模块加载 harness |
| tools/render-panel.mjs | 从真实组件出截图（无头 Chrome/Edge） |
| PUBLISHING.md | 投稿到插件市场的完整流程与检查表 |

对宿主 Node 的依赖：账本要解开 Zstandard 帧，用的是 Node 内置 zlib.zstdDecompressSync。
这不是额外要求——官方 dsh-session-persistence-jsonl 写这些日志用的就是同一套内置 API，所以任何能写出这种日志的 DSH 运行时都必然具备它。

可调配置

Host 半侧的 apply(ctx, config) 接受：

| 字段 | 默认 | 说明 |
| home | $DSH_HOME | Harness 家目录 |
| tempDir | 系统临时目录 | 扫描 dsh- 暂存的位置 |
| minIdleHours | 24 | 无会话归属的临时文件要闲置多久才算过期 |
| marketCacheMinAgeHours | 1 | 市场缓存的最小年龄（它有 6 小时 TTL） |

改完代码怎么生效

客户端半侧（client.js）不用重启：客户端模块表在条目被移除后重新加入时会重新读文件。

1. 不重启（推荐）：侧栏「插件」页找到 dsh-space-optimizer，开关关掉再打开。
2. 等价的文件做法：把该包从 profile 的 dsh.profile.bundles 里删掉，等几秒（dsh-hmr 会重新组合 profile，旧路由立刻 404），再加回末尾。

Host 半侧（index.js / lib/）必须重启 Harness。 实测结论：摘掉插件行再挂回去（/space-optimizer/ledger 先 404、再 200）之后，index.js 里的改动依然没生效——因为 Node 的 ESM 模块缓存命中了同一个模块 URL，重组 Loader 行不会重新 import 文件。
所以改了 Host 逻辑要重启 Harness（会中断正在执行的会话），或者先只按上面的流程验证客户端改动的样式与交互。

版本错配是安全的：新版客户端会带上防跨源自定义头，旧版 Host 直接忽略它；新版 Host 要求该头，而新版客户端一定会带。两种组合都能正常工作。

测试

node tools/space-optimizer-test.mjs # 30 项：账目口径、spill 归属、附件引用归属、
坏日志保守规则、只删点名项、全选也不碰会话日志
node tools/client-panel-test.mjs # 29 项：假 React 真渲染面板，默认勾选策略与请求体
node tools/space-report.mjs # 只读账本；确认这个脚本永远不会删东西
两个套件的退出码都必须为 0。

投稿到插件市场

社区精选目录 awesome-dsh-plugin （dsh-plugin.org 的 11029 条已验证条目即由它同步）用 一个仓库一个 YAML 收录，规则是：

| 要求 | 本仓库状态 |
| package.json 声明 dsh.bundle（只声明 dsh.client 不可安装） | ✅ dsh.bundle.patch |
| 仓库创建满 1 天 | ⏳ 发布后需等 1 天再提 PR |
| 仓库带 dsh-plugin topic | ⏳ 建仓后设置 |
| 构建产物已提交（git 安装不跑构建） | ✅ client.js 即产物 |

投稿内容是 data/plugins/__dsh-space-optimizer.yml 这一个文件：

url: https://github.com/OWNER/dsh-space-optimizer
name: OWNER/dsh-space-optimizer
category: session
description:
en: Per-task disk-space ledger in the sidebar with opt-in reclamation of unowned junk; session logs are never trimmed.
zh: 侧栏里的每个任务磁盘占用账本，可勾选回收无主垃圾；会话日志绝不被裁剪。

分类选 session（「💬 会话与消息」）：账本按会话组织，同类条目 dsh-session-sweeper、 dsh-session-delete、dsh-archived-conversations 都在这个分类下。
描述里若含英文冒号加空格必须加引号，否则 YAML 会解析失败。

常见问题

为什么我的任务几乎都显示“无可优化项”？
因为一个任务占的大头是会话日志，而它没有安全瘦身空间（见上方口径）。能优化的是三类附属产物，多数任务本来就不产生它们。这个插件的首要价值是让你第一次看清空间去哪了，其次才是释放。

清理“临时暂存”会毁掉那段对话吗？
不会毁掉对话。日志里存的是 spill 文件的路径，删掉后那段超大工具输出的全文读不回来（界面上只剩摘要），但对话正文、思考过程、工具调用、最终答案、代码改动都完好。
正因如此，这类项目默认不勾选，需要你逐个任务点头。

为什么运行中和当前任务不能勾？
它的临时文件可能还在被读，删了会打坏正在跑的任务。面板会把它们标成 运行中 并禁用勾选，但占用照常统计，所以你能看到当前任务的体积。

为什么各类数字加起来和“总占用”对不上？
附件是内容寻址存储（相同字节只存一份），所以按引用归属到任务、总量只算一次：被多个任务引用的附件会在多行出现，并在行内标注“共享 X，合计里只算一次”。
每个任务的「占用」是它独占的字节，相加不会重复计数。

删掉的东西能恢复吗？
不能，回收不走回收站（这样才真的释放空间）。所以界面上不做“全选任务级项目”的默认行为，也不提供“清空一切”的接口——每次都要显式列出要删什么。

会把我的数据发出去吗？
不会。Host 半侧只做本地文件系统操作，插件自身不发任何网络请求；扫描结果是本地 JSON，只回给本机的这个页面。

扫描会不会很慢或很吃 CPU？
实测 9 个任务、约 8 MB 日志，扫描 170 ms。它要解开每个会话日志的 Zstandard 帧（帧是官方按批次追加的）来统计附件引用，所以任务很多时是线性的，但只在打开面板和点扫描时跑。

改了 Host 代码为什么不生效？
client.js 摘挂插件行即可热更新；index.js / lib/ 因为 Node 的 ESM 模块缓存（junction 会解析到同一真实路径）必须重启 Harness。详见「改完代码怎么生效」。

已知边界

- 面板上的数字会随任务增长：会话日志本身占大头（约 0.8 MB/任务），而它无法安全瘦身；真正随任务稳定产生的可回收垃圾不到 0.2 MB/任务。
- 插件市场缓存是一次性收益：删掉之后下一次打开插件市场会重新下载，第二次点就没得清了。
- 归档会话的日志不会被回收：官方 dsh-session-persistence-jsonl 明确写着「Nothing deletes session files」，归档也没有取消归档的入口，所以这些会话仍按普通任务计入账本，只是侧栏不显示。
- 跨进程的临时文件只能按时间猜：dsh-subprocess- / dsh-workspace-changes-* 的文件名里没有会话归属信息，只有 pid（能判断“当前进程在用”），所以这两类走闲置时长门槛；太新的会被如实标为“还太新，保留”。