前言¶
DSH 的会话会在工作区留下很多文件：写得差不多的报告、临时脚本、截图、记忆文件、共享素材。传统做法是打开文件管理器或另写脚本逐个找，看多了就会分不清哪些是交付物，哪些只是过程痕迹。
下面介绍 zmengle 维护的客户端插件 dsh-plugin-artifacts。它提供 DSH 侧栏一级入口和独立页面「我的产物」，核心不是一般的文件浏览器，而是把文件分成产物 / 过程 / 记忆 / 素材四类，默认只展示产物。插件同时提供多工作区、12 类文件类型、预览、重命名、回收站、zip 归档，以及可选的腾讯 COS 手动上传与同步。
核心设计¶
插件是 DSH 的侧栏插件，安装后点侧栏图标进入「我的产物」。它用到 DSH 的 sidebar.panellist 与 main keyed slot，要求 DSH ≥ 2.0.0，作者实测版本为 2.0.21-next；运行时要求 Node ≥ 20，插件自身零运行时依赖。
它的定位边界很清楚：
- 做：工作区产物集中管理、角色分层、本地搜索与筛选、时间分组、预览、整理、回收站、归档、可选云端备份。
- 不做：项目树、代码编辑器、版本控制、多人协作、Office 或视频缩略图、后台全量镜像同步。
产物是默认视图；过程文件需要用户主动切换才出现。这样可以避免测试脚本、截图、夹具把列表淹没。
角色与类型¶
文件先分角色，再分类型。
角色有四档：
- 产物：默认视图和默认备份范围内的目标文件。
- 过程：会话目录里的脚本、截图、夹具等中间文件。
- 记忆：命名符合
MEMORY*/PERSONA*/HANDOFF*，或路径包含memory/的文件。 - 素材：
uploads/、assets/等目录里的素材。
角色判定由 lib/roles.js 的纯函数完成。默认收录规则：
- 产物：通过产物规则且任意位置的文件。
- 记忆：符合记忆命名族或路径含
memory/的文件。 - 会话：会话目录里的过程文件，默认关闭。
文件类型有 12 类：doc / sheet / slides / image / vector / video / audio / code / config / web / archive / other。其中 .json 归为 config，.svg 归为 vector，.html 归为 web，code 只收真正的源码扩展名。
规则只能给初值，用户可以在整理模式逐条覆盖。覆盖记录写入 .artifacts.json，只保存人工改动，规则升级不会冲掉已有判断。
界面与本地操作¶
首页支持网格和列表视图，可以按创建时间或修改时间排序，并按年、月、日分组；默认按月分组。标题吸顶显示分组名和数量；选择名称或大小排序时，分组控件自动隐藏。
筛选包括类型、角色、来源与会话：
type:code 只看代码（type:doc,image 逗号多选）
role:scratch 只看过程（会覆盖「默认只看产物」）
session:<会话目录名> 只看某个会话
type:doc 报告 文档 + 文件名含「报告」
用户可以预览图片，缩放方式有适应、原尺寸和 200%；也可以新标签页打开原图。其他本地操作包括重命名、移动、下载、删除到回收站、还原、恢复、打包 zip。图片之外只显示类型图标。
搜索语法里的 type: / role: / session: 会补全；写错的 role: 值会被忽略，而 role:all 才表示不按角色过滤。多个工作区时会多出「工作区」下拉，和角色、类型、来源是「与」关系。
整理模式¶
整理模式用于规则之外的人工标注。
1、点顶部「整理」按钮，按「会话 · 目录」分组列出全部文件。
2、每行可以用「产物 / 过程 / 记忆 / 素材」四个按钮直接设置。
3、分组标题提供「全设产物 / 全设过程 / 恢复自动」等批量操作。
4、顶部筛选框按文件名或路径定位；超过 200 条时使用「加载更多」。
5、人工覆盖写入 .artifacts.json，标过的行会显示「人工」角标。
整理时可用 J/K 或方向键移动行，用 1/2/3/4 直接设为产物 / 过程 / 记忆 / 素材。人工标过的条目即使不在当前扫描范围内也会保留，否则一旦标成「过程」就从整理界面消失，无法撤销。
安装与启用¶
从市场安装：
dsh plugin --profile desktop add dsh-plugin-artifacts
本地开发时可以修改插件代码后，把 profile 目录里的依赖改成 link: 指向本地仓库。以下流程用于改代码、跑测试：
# 1) 在 profile 目录加依赖（D:\Users\<you>\.dsh\profiles\desktop\package.json）
# "dsh-plugin-artifacts": "link:D:/workspace/dsh/dsh-plugin-artifacts"
# 并把 "dsh-plugin-artifacts" 追加到 dsh.profile.bundles 末尾
cd $env:USERPROFILE\.dsh\profiles\desktop
pnpm install
# 2) 重启 DSH Desktop（host 半侧要重新组合配置树）
只改 client.js 不用重启，因为 dsh-client-hmr 每 500ms stat 一次 client bundle，改动会热替换。改 index.js 或 lib/* 必须重启宿主，host 半侧是进程内的。
工作区解析与多工作区¶
主工作区按以下顺序解析，前一条不成立才走下一步：
1、config.workspaceRoot：在 bundle patch 里写死，最可控。
2、workingDirectory.defaultDirectory：宿主给的默认工作目录。
3、$DSH_HOME/storages/workspace.json：桌面端持久化的工作区登记表。
4、DSH_WORKSPACE / DSH_WORKSPACE_ROOT：环境变量。
5、process.cwd()：最后兜底。
第 2、5 条在 Electron 下可能是 DSH 自己的 home 或 profile 目录，插件会用 looksLikeHostHome() 挡掉，避免出现「索引成功 0 条、列表永远空白」。/status 会回报 workspace 与 workspaceSource；页面在 sessions/ 不存在时的空态里也会写出实际解析到的路径。真实排查时可以先看宿主日志：
[dsh-plugin-artifacts] 索引就绪：N 条（<工作区>，来源 <source>）
主工作区之外，可以在「设置 → 工作区」添加最多 8 个根目录，自动去重并去掉被包含的子目录。主工作区不可移除，但可以改路径。所有派生数据都在主工作区的数据目录：
<主工作区>/sessions/.settings.json | .index.json | .cloud.json | .archive.json | .artifacts.json
<主工作区>/.trash/ 回收站（一直在根目录）
没有 sessions/ 的裸工作区，数据目录退到 <主工作区>/.dsh-artifacts/，不会为了存索引而创建 sessions/；.dsh-artifacts 本身不参与索引。
扫描范围有重要区别：
- 主工作区存在
sessions/时，只扫sessions/与artifacts/，和 v2 一致；outfits/、ark-output/、deliverables/等目录属于项目或素材，整棵扫会导致条目膨胀。 - 没有
sessions/的裸工作区才整棵扫。 - 显式添加的额外工作区一律整棵扫。
额外工作区的条目 id 使用 @<标签>/<相对路径>。含 package.json / pyproject.toml / Cargo.toml / go.mod 的独立项目子目录会被扫描时跳过；要管理项目目录，就把那个项目目录单独加为工作区。
云端上传与同步¶
COS 云端是可选项。必须先填好 COS 配置并手动开启，上传永远是用户手动点击，插件不会在未开启时后台上传。
备份范围只有「仅产物」和「产物 + 记忆」；过程与素材永不上传，即使手动勾选也会被备份范围过滤。自动同步关闭时不执行；开启后也只重传「已经传过、但本地改过」的文件，从不主动上传新文件。
POST /cloud/autosync { "runNow": true }
自动同步是保守实现：只处理有云端记录且 stateOf === 'conflict' 的条目；单飞、每轮最多 20 个；云端关闭时立即停表。状态里回报 last: { at, uploaded, failed, skipped, errors }，设置面板显示「上次同步 / 待同步 N 个」。
适用场景与注意¶
适合需要把 DSH 工作区里交付物、过程文件、记忆和素材分开的人。它会在现有工作区索引上做整理，不改变文件本身的内容；如果要长期跑云端备份，需要明确备份范围，不要默认开启自动同步。
需要说明的是：插件由 zmengle 在社区维护，分类是客户端，不表示 DeepSeek / 幻方官方发布。仓库许可证为 MIT，安装和启用以当前 DSH 进程权限运行，安装前应检查源码与许可证，确认命令与配置符合自己的 DSH 版本。
小结¶
dsh-plugin-artifacts 解决的问题很具体：让 DSH 用户从一堆会话文件里快速找到真正要交付的产物，同时保留过程、记忆和素材的可控入口。它把文件管理做成了角色分层加本地操作的组合，云端能力只是可选备份，不改变本地为核心。
目录页：https://www.skillhub.cn/plugins/zmengle/dsh-plugin-artifacts
GitHub：https://github.com/zmengle/dsh-plugin-artifacts
