会话产物清理 ShirohaChan/dsh-session-artifacts

dsh-session-artifacts

这个包由 DeepSeek-v4.1 flash 构建！

English ·

清理会话留在你工作区里的东西 —— 需要的话，连会话记录一起删掉。全程可选、先预览、确认无误再动手。

对话结束之后，会话留下的脚本、报告和生成文件还留在原地。DSH 里没有任何地方记录这些文件是哪些，所以这个插件从会话日志里把它们还原出来，在删除之前把完整清单和总大小摆给你看。

它能做三件事，由同一个对话框里的两个复选框决定：

- 删掉产物，留下对话 —— 收拾会话留下的烂摊子，但会话本身不动。
- 删掉会话记录 —— 产物删不删都行。
- 两件事都不默认做：产物这一步默认关闭。

它自成一体：自己动手删会话记录，不走 dsh-chat-manager 的 /plugins/dsh-session-delete 路由，所以那个插件被禁用或根本没装，它照样能用。

它做什么

1. 打开会话的 ⋯ 菜单，选 Delete session and artifacts…
2. 对话框在你确认之前就列出完整文件清单和总大小。
3. 勾选你要删的东西。至少得勾一个。
4. 确认。要删会话记录的话它先走，然后是预览过的那些文件。
5. 有文件没删掉，对话框会给出 Retry the files left behind —— 只重试那几个路径，不是整个预览清单。

只删产物这种模式根本不需要动会话：Host 把预览清单藏在一个 nonce 后面，所以文件能删，会话和它的日志原封不动。

删除会话记录

持久化接缝故意没有删除 API —— 它自己的约定写得很清楚：日志会一直堆在会话根目录下，直到被外部删掉。所以这个插件自己动手删，按固定布局来：

<sessionRoot>/<project>/<sessionId>/session[.vN].jsonl[.zstd]

位置通过持久化后端（resolveCurrentLog）解析出来，然后动手之前每一项都要重新检查：

- 根目录下正好三段，叶子名是会话日志；
- 每个目录都是真目录，日志是真文件 —— 不能是符号链接；
- 没有任何东西解析到根目录外面；
- 删除走两步隔离：先把目录改名到一个同级的临时目录，在那里重新核对身份，然后才真删。中途失败会把原目录恢复回去，不会留下删了一半的残局。

停掉一个开着的会话

会话开着的时候，它在 host 注册表里是活的，哪怕什么都没在跑它还在里面，所以它的日志写入器仍然挂着，它的行会重新出现在侧边栏。必须先把它拆掉，它的存储才能移除——而注册表没有暴露 dispose。

唯一受支持的拆除方式是返回给 Agent 创建者 的 AgentHandle，所以这个插件保留了自己的句柄跟踪器：它观察共享 agents 服务上的 Agent 创建，并保留每个句柄。删除随后：

1. 取消正在运行的一轮（与 Stop 按钮使用的路径相同）；
2. 通过句柄 dispose 该 Agent——这一步会注销它并分离它的 Session；
3. 等待两个注册表排空，然后移除存储。

跟踪器属于这个插件自己，而不是另一个插件的，所以那个插件消失时这项能力不会跟着消失。

有一种情况无法处理： 在插件加载之前就已经存活的 Agent 没有捕获到句柄（句柄只给过它的创建者）。这种删除会被拒绝，并提示你重启 DSH——重启后插件从一开始就能看到每个 Agent。之所以拒绝而不是在它的写入器底下删掉，是因为报告一次并未发生的删除，比不删除更糟。

文件如何归属到会话

持久会话日志是会话接触过什么的唯一权威记录，所以归属关系从它读取：

| 证据 | 含义 | 可删除 |
| write 结果带 meta.operation: "create" | 会话物化了该文件 | 是 |
| shell 命令窗口 + 文件创建时间 | 文件在命令运行期间创建 | 是，如果唯一 |
| present 调用 | 会话交付了该文件 | 否（仅报告） |
| write 结果带 meta.operation: "update" | 会话重写了已存在的文件 | 否 |
| edit 调用 | 会话只重写了已存在的文件 | 否 |

重写你已经拥有的文件永远不会让它变得可删除，所以 update 和 edit 结果会被报告，但永远不会被提供。失败的工具调用（FS_SANDBOX_DENIED、FS_NOT_OBSERVED、FS_STALE_VERSION、……）不贡献任何东西，因为工具从未物化任何内容。

present 是交付，不是创作：会话被要求把一份你已经有的论文交给你，否则会让那份论文变得可删除。仅交付的文件会在对话框中计数，并被放过。设置 includeDelivered: true 可选择加入更早、更激进的行为。

Shell 创建的文件

文件工具写入会被显式记录。Shell 命令不会：pwsh 调用只记录其命令文本，它的 tool/result 完全不携带 meta，所以没有任何持久记录能指明 python foo.py 运行产生了哪些文件。实践中这是残留物的主要来源——一个通过 shell 写二十个脚本的会话会产生二十个产物，而只读文件工具的读者永远看不到它们。

剩下的证据是创建时间。在 NTFS 上 birthtime 是真正的创建时间戳，与 mtime 不同，并且它在后续编辑后仍然保留——所以它回答「这个文件是不是在这条命令运行期间创建的？」。把每个 shell tool/call 和它的 tool/result 配对，就能给每条命令划出一个紧凑的时间窗口。

三条规则保证安全：

- 窗口要紧凑。 只算命令真正运行的那段时间。整个会话的窗口没法用：一个会话跑了两条命令，然后花了二十分钟浏览网页，否则它就会把这段时间里创建的每个文件都算成自己的。（在真实日志上实测：这样一个会话，会话级时间跨度内有 90 个文件，而它真正的命令窗口内是 0 个。）
- 唯一性。 落在两个会话窗口内的文件，两边都不认领，因为认错就会删掉这个会话从没创建过的东西。并发会话因此只会让结果变少，不会把它弄脏。
- 失败即关闭。 如果无法枚举同级的其他会话，这一轮就什么都不认领，并在对话框里说明。「只有我的窗口覆盖了它」这句话，不知道别的窗口就立不住。

只认领创建。文件只是在窗口内改动过，不算这个会话产出的，不动它。推断出来的文件在列表里标为 命令行 / shell，因为它的证据比记录在案的写入要弱。

安全

- 工作区围栏。 会话只能提议自己记录的工作目录里的文件。
- DSH home 围栏。 ~/.dsh 下的任何东西都永远不算产物，不管会话的工作目录是什么。工作区围栏本身是相对 cwd 的，所以一个在 ~ 或 C:\ 打开的会话，否则就能碰到已安装的插件、构建好的技能、配置档和凭据存储。真正嵌套在 home 里的工作区（比如 ~/.dsh/scratch）仍然拥有自己的文件，但碰不到旁边的邻居。
- 包围栏。 文件所在目录如果是 DSH 包——里面有 SKILL.md、cordis.patch.yml、cordis.yml，或者带 dsh/cordis 块的 package.json——就不提议，这样会话在自己工作区里构建的插件或技能能活下来。设 protectPackages: false 可关闭。
- 符号链接。 候选文件的真实路径如果通过符号链接逃出工作区，预览和删除时都会跳过。
- 不删陈旧文件。 每个文件在 unlink 之前都会重新检查一遍；预览之后大小或身份变过的文件，跳过而不是删除。
- 相对路径按会话的 cwd 解析，绝不用 Host 进程的工作目录，所以 report.md 指的就是会话真正写入的那个文件。
- 客户端从不指定路径。 Host 把预览过的集合藏在一个一次性、10 分钟有效的 nonce 后面。用户从没见过的路径删不掉，nonce 也不能重放。
- 重试是钉住的。 重试条目会重新取文件的基准大小（预览时的大小按定义已经过期），但钉住它的设备 + 文件索引，所以两轮之间路径被换成另一个文件的，会被拒绝。
- 目录永远不会作为产物被删除。 只提供常规文件；删除后变空的目录会被清理，清理到工作区根目录为止。
- 不做安全擦除。 删除就是普通的 unlink。备份、云端副本、快照，以及文件系统层面的恢复，都不在它的处理范围内。

配置

所有字段都是可选的；默认值就是安全的那些。

| 字段 | 默认值 | 含义 |
| dshHome | 推导得出 | 覆盖 home fence 使用的 DSH home。否则用 DSH_HOME，再否则用 <home>/sessions 存储的父目录。 |
| extraExcludes | [] | 额外的绝对路径，永远不会被提供。 |
| protectPackages | true | 拒绝 DSH 插件/技能包内的文件。 |
| includeDelivered | false | 同时提供会话只是投递过的文件。 |
| includeShell | true | 运行 shell 创建窗口那一轮检查。 |
| shellSlackMs | 5000 | 命令窗口前后的余量，用来吸收事件时钟与文件系统时钟之间的偏差。 |
| deleteSession | true | Host 是否提供会话记录删除。设为 false 时插件只处理产物：记录复选框隐藏，整个流程不再碰日志。 |
| lifecycleTimeoutMs | 20000 | 等待已停止的会话离开活跃注册表的时间。 |

要求

- 每个会话的 JSONL 会话持久化后端（sessionPersistence），所有随附的组合都会挂载它。
- 活跃 Agent 注册表（agents），由 @deepseek-ai/dsh-agent 提供。它是声明的依赖，因为 handle tracker 必须在任何 Agent 创建之前安装——装晚了就什么都捕获不到。
- DSH core 0.2.x，用于它扩展的会话菜单和 overlay 槽位。

不需要其他插件。
sessions 存在时会被使用，用来在拆除前停止正在运行的回合。

限制

- shell 归属依赖 birthtime。如果文件系统不记录真正的创建时间，shell 那一轮检查会什么都找不到，而不是去猜。
- 只检测创建文件的会话。一个会话创建、另一个会话后来编辑的文件，仍然归属创建者。
- 会话如果在窗口快结束时启动了长时间运行的后台任务来创建文件，可能落在窗口之外。凡是以后打算删除的东西，尽量用文件工具创建。
- 目录永远不会被提供，所以只创建了目录（里面什么都没建）的会话会把它们留下。
- 预览是快照。之后创建的文件不包含在内。
- 子代理会话记录自己的写入；删除父会话不会自动删除子会话的产物。
- 在本插件加载之前就已经打开的会话无法拆除（没有捕获到 handle），所以它的记录要等 DSH 重启后才能删除。删除它的产物仍然有效。
- handle tracker 观察的是共享的 agents 服务，所以它只能看到通过它创建的智能体。用其他方式创建智能体的组合，行为与上面已有的情况相同。

安装

dsh plugin --profile <profile> add dsh-session-artifacts

或者从本地检出安装：

dsh plugin --profile <profile> add <path-to-this-directory>

然后重启 DSH，让 Host 与客户端两半完成组合。

卸载

dsh plugin --profile <profile> remove dsh-session-artifacts

卸载只会移除这个插件。它绝不会自行删除会话或产物。

测试

npm test

测试套件覆盖归属规则、shell 创建窗口这一轮（包括 fail-closed 路径和双会话歧义规则）、workspace / DSH home / package 三层围栏、跨盘路径、符号链接逃逸、身份重新校验、相对路径解析、空目录清理、nonce 单次使用、重试 nonce、请求围栏，以及真实 apply() 的端到端接线。

许可证

MIT