前言¶
在 DeepSeek Harness（DSH）裏切換工程，依賴側欄的工作區註冊表。若你同時在 Cursor、Claude Code、Codex 等工具裏開過大量項目，那些工具各自會記下「最近打開的路徑」，而 DSH 側欄不會自動對齊這份清單。手工把路徑逐條加入側欄，成本高，也容易漏。
更早的社區插件 Workspace Hub 曾做多工具掃描、賬本與定時同步，但長期維護成本高，產品被收束爲「用戶最常要的一次性導入」。dsh-import-once 只保留掃描配方與這一動作：只讀讀取各工具本地狀態，把尚未出現在 DSH 側欄的項目文件夾登記進去，不做後臺同步、不寫獨立賬本。
下面介紹插件定位、能力邊界、安裝方式與典型用法。事實以倉庫 README 與 package.json 爲準。
這是什麼¶
dsh-import-once 是 DSH 的客戶端插件（維護者 dongsheng123132），版本 0.1.0，許可證 MIT。它通過一次模型工具調用（或你直接調用同名工具），把其他 AI 工具已在本地記錄的項目目錄導入 DSH 側欄。
調用形態在 README 中寫明：
dsh_import_once({ dryRun = false, maxAdd = 50 })
→ { dryRun, tools: [{ id, found }], scanned, missing, added, skipped, errors }
插件安裝後不會自行掃描；只有調用 dsh_import_once 時側欄纔會變化。它是 Workspace Hub 的「一次性導入殼」，Hub 側長期同步已不再維護，本倉庫只保留掃描配方與實際有用的單一動作。
核心功能¶
單一動作，無附帶狀態機¶
README 明確列出「不是什麼」：無賬本文件、無間隔定時器、無後臺隊列、無 Git 同步、無 pin/排除列表、無狀態目錄、無 CLI 子命令。每次調用自給自足，不依賴插件自己的持久化狀態。
只讀掃描¶
各適配器只只讀打開對應 AI 工具自己的狀態文件（如 ~/.claude.json、VS Code 系 state.vscdb、Codex SQLite 等），提取項目文件夾路徑與展示標題。不復制項目內容、不上傳、無網絡代碼。
個別適配器會把正在使用的 SQLite 庫複製到系統臨時目錄再讀，讀後立即刪除，不修改原工具狀態文件。
只增不改¶
唯一寫操作是對缺失路徑調用與官方側欄相同的 workspaceRegistry.create(path, title)。不重命名、不重排、不刪除已有工作區；誤導入只能手工在側欄移除。
無狀態冪等¶
DSH 已擁有的文件夾按真實路徑匹配，第二次調用應得到 added: 0。調用之間插件不記任何東西，側欄註冊表即權威狀態。
真實 dry-run¶
dryRun: true 時按真實邏輯規劃並返回與正式執行一致的數字，不寫任何工作區。
多工具適配器¶
README 表格列出可讀來源，涵蓋 dsh、codex-app、claude-code、claude-desktop、trae / cursor / antigravity、workbuddy、kimi、uking、qwenwork、codebuddy、pi、qoder、deepseek-tui、hermes 等；doubao / doubao-work 僅探測且無本地工作目錄。各平臺路徑由適配器自行解析（例如 Windows 上 WorkBuddy 使用 %USERPROFILE%\.workbuddy）。未出現在表中的工具不會被導入。
掃描後會過濾：僅仍存在於磁盤上的目錄；跳過 app-managed 類臨時(scratch)目錄；跨工具重複路徑會去重。因此 sum(tools.found) 可以遠大於 scanned。
安裝與啓用¶
在 DSH 中安裝（README 原文命令）：
dsh plugin --profile desktop add dsh-import-once # or --profile web
安裝後重啓 DSH。安裝本身只註冊一個工具，不觸發掃描。
若使用 DSH 0.2.2 實驗性插件市場 Discover，可把本倉庫索引加入後再搜索 import-once（README 給出的索引 URL）：
https://raw.githubusercontent.com/dongsheng123132/dsh-import-once/main/plugin-index.json
路徑：Plugins → Discover → Add index source，粘貼 URL。
package.json 標明運行需 Node >= 22，並與 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-workspace 0.2.2-rc.1 等 peer 依賴對齊；你本機 DSH 版本應與插件聲明兼容。
典型用法¶
參數¶
| 參數 | 類型 | 默認 | 含義 |
|---|---|---|---|
dryRun |
boolean | false |
僅規劃；彙報數字且不寫入 |
maxAdd |
integer | 50 |
本次調用最多創建工作區數；0 表示不限制 |
建議流程¶
1、先 dry-run，確認 missing、skipped 與 errors。
2、再正式調用，按需設置 maxAdd 分批導入。
可對模型說（README 示例）：
Import my projects from other AI tools into DSH. Dry run first.
或直接在對話裏讓模型調用 dsh_import_once。
返回字段¶
| 字段 | 含義 |
|---|---|
dryRun |
本次是否僅規劃 |
tools[] |
每個適配器一行：id 與 found（該工具上報的原始記錄數；0 表示未安裝、無文件或不適用） |
scanned |
過濾與真實路徑去重後的不重複項目目錄數 |
missing |
其中側欄尚未登記的數量 |
added |
本次創建數（dry-run 下爲「將會創建」數） |
skipped |
因超 maxAdd、中止或失敗而留待下次的缺失數 |
errors[] |
適配器錯誤 { tool, message } 與創建失敗 { path, message } |
恆等式：missing = added + skipped；sum(tools.found) ≥ scanned（差額來自跨工具重複、scratch 與已不存在目錄）。
README 在 2026-11-09、macOS、DSH 0.2.2-rc.1 上對 live store 的一次 dry-run：約 1.2 s 讀完 18 個適配器，1304 條原始記錄歸併爲 364 個不重複項目目錄，其中 349 已在側欄，故 missing: 28；maxAdd: 50 的正式調用可一次補全這 28 個。該數字隨你本機工具與歷史記錄變化，僅作量級參考。
適用場景與注意¶
適合誰： 剛接入 DSH、已在多種 AI 客戶端裏積累項目路徑，希望側欄一次對齊「磁盤上仍存在的工程」，且不需要 Hub 式賬本與定時同步的用戶。
能力邊界（README Limits）：
- 本版本說明中僅在 macOS 26.2 + DSH 0.2.2-rc.1 上實測；Windows / Linux 分支代碼來自 Hub 同源適配器，但本 release 未在真機跑通。
- 只導入仍存在的文件夾；陳舊記錄會被靜默丟掉。
- 新工作區在註冊表中 prepended，側欄順序跟掃描順序有關，不一定等於其他工具裏的「最近活躍」順序。
- 工具描述與界面渲染文本以英文爲主；本地化以倉庫
README.zh-CN.md等爲補充。
安全與權限： 插件在當前 DSH 進程權限下讀你家目錄下的各工具狀態文件，並向 DSH 工作區註冊表寫入。安裝前宜瀏覽 GitHub 倉庫 源碼與 MIT 許可證；適配器實現部分自 Workspace Hub 逐字節複製（見 vendor/README.md）。
社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；DSH 生態以「一切皆插件」爲方向，Discover 亦無官方固定目錄，需用戶自行添加索引源。
結尾¶
dsh-import-once 把「多工具本地項目清單 → DSH 側欄」收斂成一次只讀掃描加只增登記：無賬本、無定時、無跨設備同步，靠 dry-run 和 maxAdd 控制風險。需要持續對齊時，應另選方案或手工維護側欄。
- 目錄頁：https://www.skillhub.cn/plugins/dongsheng123132/dsh-import-once
- 源碼與完整說明：https://github.com/dongsheng123132/dsh-import-once
