附件库 ZZZZZZZ-ZZZZZ/dsh-attachment-library

dsh-plugin-attachment-library · 附件库

DeepSeek Harness（DSH）插件：在 设置 → 附件库 中查看本机保存的所有图片和文件附件、它们占用的空间，以及哪些对话仍在使用它们（正常、已归档、等待移入回收站、在回收站）。

只读。 目前不提供删除：插件不会创建、修改、移动或删除任何附件、会话记录、回收站文件或缓存；“在访达中显示”只选中文件，不打开、不执行。插件唯一的写入是“用预览打开”时在系统临时目录（DSH 数据之外）放置的只读副本，插件停用时删除。它的用途是先核对引用统计，为以后是否安全清理附件提供依据。

- 兼容 DSH 0.2.x（engines.dsh: >=0.2.0-rc.2 <0.3.0，含 0.2.1-alpha 预览版）
- 会话回收站的统计需要配合 dsh-plugin-session-trash；没有安装它时，只统计现存对话

安装

桌面版：打开侧栏的 插件 → 添加插件，在“包名或地址”中填入以下任一项，点 安装，完成后点 立即启用（新装的插件默认关闭）：

- GitHub 地址：https://github.com/ZZZZZZZ-ZZZZZ/dsh-attachment-library，指定版本可写 github:ZZZZZZZ-ZZZZZ/dsh-attachment-library#v0.4.1
- npm 包名：dsh-plugin-attachment-library
- 本地安装包的绝对路径，例如 /path/to/dsh-plugin-attachment-library-0.4.1.tgz（由 pnpm pack 生成）

不要填写源码目录：源码目录的 node_modules 里有开发用的 DSH 包副本，会和 DSH 自身的包冲突。

命令行（可选）：完全退出 DSH 后运行 dsh plugin --profile desktop add dsh-plugin-attachment-library。

卸载：在 插件 页面卸载“附件库”。插件不保存任何数据，卸载不影响附件。

页面内容

- 统计：附件总数与总占用；其中图片、文件各多少；被现存对话使用、只被回收站里的对话使用、无任何对话引用各多少（个数和占用）；被引用但文件已缺失的数量；可再生的缩放缓存占用。
- 列表：类型图标（图片为图片图标，文件按扩展名显示）、类型、文件名（同一内容有多个文件名时全部保留）、大小、图片尺寸与格式、存入时间，以及引用它的每个对话的标题和状态。同一附件被多个对话共用时全部列出。
- 用预览打开（仅 macOS）：已保存图片行的箭头图标按钮（悬停显示“用预览打开”），在主机上用“预览”打开这张图片。打开的是带正确扩展名的只读副本，不是 DSH 的原文件（原因见下文）。文件行没有这个按钮。
- 在访达中显示：每个已保存附件行右侧的文件夹图标按钮（悬停显示“在访达中显示”），在主机的访达（Windows 资源管理器、Linux 默认文件管理器）中选中该文件：文件附件显示为它的真实文件名，图片显示为按内容命名的对象文件。只有页面连接的是本机 DSH、主机有桌面文件管理器且 DSH 允许桌面打开时才显示；失败原因显示在该行下方。
- 重新统计：右上角的刷新图标按钮（悬停显示“重新统计”）；统计进行中按钮不可用，并显示“正在重新统计…”。
- 筛选：类型（全部 / 仅图片 / 仅文件）和引用情况（全部 / 现存对话 / 仅被回收站引用 / 无人引用）；排序：按时间或按大小（都是从新到旧、从大到小）。列表每次显示 100 条，可继续展开。
- 读取不完整的提示：如果有会话记录读不全（损坏、被截断），页面会列出它们，并提示“无人引用”等统计可能偏多。

图片为什么在访达里没有预览

DSH 按内容保存图片：文件名就是图片的 SHA-256 摘要（例如 attachments/v1/objects/3f/3f9a…），没有扩展名，权限为只读（0400）。内容是普通的 JPEG、WebP、PNG 或 GIF（经过归一化），没有加密；只是 macOS 靠扩展名判断文件类型，所以访达不显示缩略图，双击也不会当作图片打开。文件附件不同：它们另有一个带真实文件名的只读硬链接，在访达里正常显示。

统计规则

| 规则 | 说明 |
| 附件身份 | DSH 按内容（SHA-256）去重保存附件；图片与文件分别保存，同样的字节作为图片和作为文件是两条记录 |
| 引用来源 | 扫描每条会话记录中的所有 { type: 'image' \| 'file', attachment: { attachmentId } }：用户消息、工具结果、系统消息都包括 |
| 归属到对话 | 子智能体会话的引用算在发起它的对话上；fork 出的会话是独立对话（它继承了父对话的前缀，所以两者都会列出） |
| 现存对话 | 由会话存储列出的全部会话（通过官方只读句柄读取），状态为正常、已归档或等待移入回收站 |
| 回收站 | 直接读取回收站目录中的会话日志（原始 JSONL 或 Zstandard 压缩），标题取移入回收站时记录的标题 |
| 使用中 / 仅回收站 / 无人引用 | 有任意一个回收站外的对话引用即为“使用中”（等待移入回收站的也算）；只有回收站里的对话引用为“仅回收站”；都没有为“无人引用” |
| 占用 | 图片对象和文件对象各计一次；文件名链接是硬链接，不额外占空间；缺失的附件不计入占用 |
| 存入时间 | 附件对象的修改时间（第一次保存该内容的时间） |

缓存

第一次打开页面会读取全部会话记录，记录很多时可能较慢。之后：

- 现存会话按会话存储给出的 revision 判断是否变化，只重新读取有变化的会话；
- 回收站会话按日志文件的设备号、inode、大小和修改时间判断；
- 图片尺寸按对象文件的同一组信息缓存。

缓存只保存在 DSH 进程内存中，不写入磁盘；重启 DSH 后的第一次统计会重新读取全部记录。

配置

DSH 的所有目录都只读不写。

| 字段 | 默认值 | 说明 |
| attachmentDirectory | <DSH home>/attachments/v1 | 附件存储目录；如果给 dsh-attachment-local 配置了 dshHome，这里要改成对应路径 |
| trashDirectory | <DSH home>/session-trash | 会话回收站目录；应与 dsh-plugin-session-trash 的 trashDirectory 一致 |
| requestCacheDirectory | <DSH home>/cache/attachments/request-images | 按模型缩放的图片缓存（可再生），只统计大小 |
| previewDirectory | 系统临时目录 | 在其中创建存放“用预览打开”副本的私有临时目录；这是插件唯一会写入的位置 |

“在访达中显示”如何工作

- 使用 DSH 自己的打开能力：主机端调用官方 @deepseek-ai/dsh-native-command 的 revealNativePath（macOS 为 open -R，Windows 为资源管理器 /select，Linux 打开所在目录），与 DSH 内置“在访达中显示”使用同一个函数；可用性按同一套检查（nativeFileManager()、canOpenNativePath()）判断，浏览器端还要求 ctx.remote.$host.isLoopback 为真，并遵从 DSH 官方的 session.canOpenWorkspacePath() 开关。
- 没有直接复用官方的 session.openWorkspacePath：它要求浏览器传入绝对路径，并且只接受已映射到工作区文件系统的路径，附件目录不在其中。
- 浏览器只发送附件类型和 id（sha256: 加 64 位小写十六进制），经过认证的 /api 网关严格校验，任何多余字段（包括路径）都会被拒绝。
- 路径由主机根据 id 推出：文件为 attachments/v1/files/<前缀>/<摘要>/<文件名>（取按名称排序的第一个文件名；没有时用 file-objects 中的对象），图片为 attachments/v1/objects/<前缀>/<sha256>。目标必须是附件目录内的普通文件，路径上不能有符号链接；否则返回“找不到”。

“用预览打开”如何工作

- 浏览器只发送图片的 id（sha256: 加 64 位小写十六进制），网关严格校验，多余字段（包括路径）一律拒绝。主机按 id 找到 attachments/v1/objects/<前缀>/<sha256>，要求它是附件目录内的普通文件、路径上没有符号链接；文件附件、缺失的图片和链接都返回“找不到”。
- 主机读取图片头确定格式，把图片复制到私有临时目录（<previewDirectory>/dsh-attachment-preview-<随机>/，权限 0700）中，副本名为摘要前 16 位加扩展名（.jpg、.webp、.png、.gif），权限 0400；复制前核对内容与摘要一致，同一张图片重复打开时复用副本。
- 打开副本而不是原文件，是因为原文件没有扩展名，而且虽然是只读（0400），文件所有者仍可在“预览”里“解锁”修改它，系统打开文件时也可能给它附加元数据；副本让 DSH 的原文件完全不被触碰。
- 用 DSH 官方的 @deepseek-ai/dsh-native-command：先用 nativeFileApplications 确认“预览”已登记为该副本的处理程序，再用 openNativeFileApplication 打开，它执行固定参数的 open -a /System/Applications/Preview.app <副本路径>（execFile，不经过 shell）。
- 只在 macOS 主机（访达可用）且页面连接本机 DSH、DSH 允许桌面打开时显示；插件停用时删除整个私有临时目录。

只涉及本机数据

附件库只列出本机上保存的内容；删除本机副本（例如用会话回收站永久删除对话）不会删除 DSH 已经发送给 DeepSeek 的内容：

- 使用 DeepSeek 官方 API 时，DSH 默认随每次请求上传会话记录（官方插件 @deepseek-ai/dsh-session-log-deepseek）。在设置中关闭“在使用官方模型 API 时上传 Session Log”只会停止之后的上传；重新打开时，关闭期间记录的内容也会被上传。
- 发送给官方 API 的图片会作为文件上传，DSH 请求 DeepSeek 在 7 天后使其过期，但不保证远端一定删除。

本插件不发出任何网络请求，不向任何地方发送数据；页面通过 DSH 带认证的 /api 只收到附件名、大小和对话标题，不会收到文件路径。

已知限制

- 不统计、也无法管理已上传到 DeepSeek 服务端的图片（索引在 <DSH home>/llm-deepseek/files-v3.json）。
- 只认识 DSH 0.2.x 的附件存储布局（v1）和 dsh-plugin-session-trash 的回收站格式（manifest 版本 1）；之后的大版本需要重新验证。
- 不校验附件内容的 SHA-256，只按文件存在与大小统计；被引用但文件缺失的附件会单独标出。
- 会话存储无法读取的会话（例如更新版本 DSH 写入、或已损坏）不计入引用，会出现在“读取不完整”的提示中。
- 一次统计结果包含完整列表；附件数以万计时，返回数据较大、首次统计较慢。
- 在访达中打开附件所在文件夹时，访达自身可能在该文件夹写入 .DS_Store（界面状态文件）；这是访达的行为，插件本身不写任何文件。
- Linux 上只能打开所在目录，不能选中文件。通过远程访问打开 DSH 页面时不显示该按钮。
- “用预览打开”只支持 macOS；副本保留到插件停用（或 DSH 退出后由系统清理临时目录），DSH 异常退出时可能留在系统临时目录中。
- 只在 macOS 上测试过；插件对 DSH 数据只读，预计在 Linux 和 Windows 上同样可用。

相关插件

会话回收站 · dsh-plugin-session-trash：在侧栏会话菜单里加入“移到回收站”，会话可以恢复，或再次确认后永久删除；本次启动中打开过的会话会先隐藏、下次启动时再移入。两个插件同时安装时，附件库会显示哪些附件只被回收站里的对话使用。

安装：在 插件 → 添加插件 中填 github:ZZZZZZZ-ZZZZZ/dsh-session-trash#v0.2.1。

开发

pnpm install
pnpm run typecheck
pnpm test # 构建 lib/ 后运行全部测试

lib/ 随仓库提交，供从 GitHub 安装时直接使用；修改源码后请运行 pnpm run build 并一起提交 lib/。

测试使用 npm 上发布的 DSH 0.2.0-rc.2 包：真实 JSONL 会话存储、真实工作区注册表与 Typert 网关。附件按 dsh-attachment-local 的目录布局生成（含硬链接文件名），回收站条目按 dsh-plugin-session-trash 的格式生成（含 Zstandard 多帧压缩、被截断的帧和不完整的行），全部在临时目录中；每个场景都会对比附件、会话和回收站目录在统计、“在访达中显示”和“用预览打开”前后逐字节、逐 inode 不变。测试中把官方 revealNativePath 替换为记录调用；“用预览打开”运行真实的官方 nativeFileApplications / openNativeFileApplication，只把它们的命令执行器换成记录器，并断言传给它的固定参数，不会真的打开访达或预览。客户端测试从 tests/vendor/ui-primitives 加载真实的 0.2.0-rc.2 界面组件（DSH 源码原样副本，MIT 许可证，见 tests/primitives-shim.ts）；不需要 DSH 源码目录。