DeepSeek Harness 插件：dsh-agent-project-sync

前言¶

DeepSeek Harness (DSH) 採用插件化架構。開發者在本地開發時，常需要在 Codex、Claude Code 等智能體工具間切換。儘管各工具保存會話的方式不同，但它們通常都會記錄當前的工作目錄 (cwd)。本插件通過讀取這些元數據，將分散在各個工具中的項目目錄匯聚到 DSH 的管理下，註冊爲原生的 Workspace，以便在 DSH 中統一管理和使用。

核心功能¶

harzva/dsh-agent-project-sync 是一個工作流插件，主要實現以下功能：

自動發現：自動發現 Codex 和 Claude Code 的項目目錄。
註冊 Workspace：將發現的目錄註冊爲 DeepSeek Harness 原生 Workspace。
清單管理：管理共享項目清單 ($DSH_HOME/agent-project-sync/projects.json)，支持通過公開的 ctx.workspaceRegistry API 註冊。
CLI 工具：提供本地命令行工具 (dsh-agent-project-sync)，用於掃描、列表和手動登記項目。
安全邊界：
- 只讀取每個 JSONL 文件開頭最多 128 KiB，並僅提取 cwd 元數據。
- 默認全部寫操作均爲 dry-run。
- 同步僅新增或複用 Workspace，絕不刪除現有數據、會話或項目目錄。
- 清單使用原子寫入、進程鎖和用戶私有文件權限，包含本機絕對路徑，不應提交到公開倉庫。

安裝與啓用¶

通過官方安裝命令添加插件：

dsh plugin --profile web add https://github.com/Harzva/dsh-agent-project-sync/releases/latest/download/dsh-agent-project-sync-0.1.0.tgz

安裝完成後，重新啓動對應的 profile 即可使用。

典型用法¶

插件提供了本地 CLI 和 DSH 內置工具兩種方式來操作項目清單。

本地 CLI 工具¶

本地 CLI 工具用於掃描目錄並管理清單文件。

只讀掃描：
查看當前發現的 Codex 和 Claude 項目，以及哪些已是 Workspace。

    dsh-agent-project-sync scan

掃描並寫入清單：
將掃描結果保存到共享清單文件中。

    dsh-agent-project-sync scan --save --confirm

讀取清單：
查看當前 DSH home 的共享項目清單。

    dsh-agent-project-sync list

手動登記項目：
手動添加一個目錄到清單中。不加 --confirm 時僅預覽。

    dsh-agent-project-sync add /path/to/project --confirm

DSH 工具¶

在 DSH 環境中，可以通過內置工具直接操作 Workspace 註冊。

agent_projects_scan：只讀掃描，顯示發現的項目。
agent_projects_list：只讀讀取當前 DSH home 的共享項目清單。
agent_projects_sync：合併發現結果並註冊缺失的 Workspace（默認 dry-run）。
agent_projects_add：手動添加一個現有目錄（默認 dry-run）。

若要執行真實寫入，需在調用時設置參數：

{
  "dryRun": false,
  "confirm": true
}

配置說明¶

插件支持通過配置文件或環境變量調整行爲。

字段	默認值	說明
`sources`	`codex, claude`	啓用的發現適配器列表
`codexHome`	`CODEX_HOME` 或 `~/.codex`	Codex 數據根目錄
`claudeHome`	`CLAUDE_CONFIG_DIR` 或 `~/.claude`	Claude Code 數據根目錄
`dshHome`	`DSH_HOME` 或 `~/.dsh`	共享清單所屬的 DSH home
`excludePaths`	空	不導入的目錄根及其子目錄
`maxFilesPerSource`	`20000`	每個來源最多檢查的 JSONL 文件數
`maxHeaderBytes`	`131072`	每個 JSONL 最多讀取的開頭字節數

注意事項與兼容性¶

權限與安全：插件通過當前 DSH 進程運行，需確保 DSH 進程有權限讀取源智能體（如 Codex、Claude Code）的數據目錄。
數據保留：卸載插件不會刪除已有的 Workspace、項目目錄或共享清單文件。
清單安全：清單文件包含本機絕對路徑，屬於機器本地數據，不應提交到公開代碼倉庫。
兼容基線：DeepSeek Harness / dsh 0.1.0-rc.8、Cordis ^4.0.1、Node.js ^22.19 || >=24。