前言¶

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