前言¶
DeepSeek Harness (DSH) 的插件化架構允許擴展本地工作區能力。本地 DSH 側邊欄通常管理本地目錄。dsh-codespace-workspace 插件將 GitHub Codespace 集成爲虛擬工作區。Agent 在雲端 Codespace 內部操作文件和命令，而不是通過 SSH 連接遠程主機。它不往 DSH 的 SSH 主機列表裏塞任何東西，因此不會和其他雲工作區插件衝突。
核心功能¶
設置與配置¶
在 DSH 設置頁新增 Codespace 面板，用於集中管理連接參數和運行策略：
- GitHub 用戶名：用於校驗與展示；留空則從 token 讀取登錄名。
- 默認分支：新建 Codespace 時使用，默認
main。 - 自動暫停等待時間（分鐘）：一輪對話結束後開始倒計時，默認 30。
- SSH 密鑰（可選）：僅保存路徑；值永不回顯，只顯示「已設置 / 未設置」。
- 始終顯示雲端工作區按鈕：開關，默認關；開啓後按鈕不再跟隨 hover 隱藏。
- 自動初始化空倉庫：開關，默認開；空倉庫先提交一個 README 再建 Codespace。
- README 初始內容：可選；留空則創建空 README。
設置通過 DSH 標準設置存儲持久化，不佔用 localStorage。
工作區列表交互¶
雲端工作區沿用原工作區的文件夾圖標位置，把那裏的文件夾字形換成雲朵。位置、尺寸、顏色以及懸停時“讓位給展開箭頭”的行爲都和原來一致。行首始終只有一個圖標。
操作按鈕位於倒數第三個——在三個點菜單和新建對話按鈕之前。顯示邏輯跟隨宿主默認行爲，不 hover 時隱藏；開啓“始終顯示”後常顯。
| 狀態 | 圖標 | 懸停提示 | 點擊 |
|---|---|---|---|
| 已停止 | 播放 | 啓動 Codespace | 啓動 |
| 運行中 | 暫停 | 暫停 Codespace | 暫停 |
| 倒計時中 | 鬧鐘 | 還剩 X 分鐘自動暫停 | 取消倒計時 |
| 啓動/暫停中 | 轉圈 | 正在切換狀態… | 不可點 |
雙擊時鐘圖標 = 立即暫停。
正在使用的工作區，雲朵圖標會繼承宿主的 folderActive 顏色。工作區行的標題用倉庫短名（owner/name 裏的 name）。
新建雲端工作區流程¶
新建雲端工作區採用分步窗口流程，不彈窗堆疊：
- 拉取 GitHub 倉庫列表，選擇倉庫。
- 檢查該倉庫的 Codespace：多個 → 選擇；一個 → 直接用；沒有 → 創建。
- 創建前檢查 prebuild，採用三態邏輯：
- 有 → 提示“已配置預構建”。
- 明確沒有 → 提示“未配置預構建，創建可能較慢”，提供取消/直接創建選項。
- 讀不出來 → 提示“無法確認預構建狀態，創建可能需要 1–3 分鐘”，不提供按鈕（由插件自己讀取失敗，不強行斷言）。
- 空倉庫 → 自動提交一個空 README，然後繼續創建。
- 機器規格可選，默認最小。
- 啓動失敗 → 窗口內報錯，可重試。
生命週期管理¶
- DSH 啓動時：不自動啓動任何 Codespace。檢查上次遺留的運行中 Codespace 並提示用戶（帶“停止”按鈕），但不自動停。
- 退出 DSH 時：嘗試自動關閉所有本插件管理的 Codespace。
- 自動暫停：一輪對話結束後開始倒計時；倒計時期間用戶發新消息 → 取消倒計時；點時鐘 → 取消；雙擊時鐘 → 立即暫停。
Agent 集成¶
- 自動就緒檢查：發消息前，系統會自動檢查並啓動 Codespace。如果 Codespace 處於自動暫停或啓動中，會等待其變爲
Available才真正發送給模型。 - Git 能力：Agent 擁有完整的
git命令執行能力。插件不干預 Git 操作，不封裝 push 邏輯。僅在創建會話時向系統提示詞注入一條規則，提示 Agent 完成改動後git push回倉庫。
前置條件¶
| 依賴 | 必需 | 說明 |
|---|---|---|
git |
是 | Agent 用它 push 回倉庫 |
ssh |
是 | 連接 Codespace 的數據通道 |
gh（GitHub CLI） |
推薦 | 用於 gh codespace ssh；未安裝時插件仍可用，改用設置頁配置的 SSH 別名 |
| GitHub token | 是 | 控制面（REST API）。取值順序：設置 → GITHUB_TOKEN → gh auth token |
所需 GitHub 權限範圍：codespace、repo。
安裝與啓用¶
安裝命令如下：
dsh plugin --profile desktop add dsh-codespace-workspace
注意：dsh plugin add 只改寫 profile 的 package.json 依賴與 pnpm-lock.yaml，不會登記 dsh.profile.bundles 數組。必須手動編輯配置：
# 1. 編輯 %USERPROFILE%\.dsh\profiles\desktop\package.json
# 2. 在 dsh.profile.bundles 數組裏加入 "dsh-codespace-workspace"
# 3. 重啓 DSH（插件文件改動不會熱生效）
也可以從本地克隆裝（改代碼時用這個）：
git clone <this-repo> dsh-codespace-workspace
dsh plugin --profile desktop add "link:<絕對路徑>\dsh-codespace-workspace"
dsh plugin add 會報一條 peer dependency 警告（@deepseek-ai/cordis、@deepseek-ai/schemastery 由宿主提供），可以忽略。
典型用法¶
- 在 DSH 設置頁配置 GitHub 用戶名、默認分支（默認 main）和自動暫停等待時間（默認 30 分鐘）。
- 點擊工作區標題欄的雲朵圖標啓動 Codespace，雙擊時鐘圖標立即暫停。
- 新建工作區時，系統會自動檢查倉庫的預構建狀態，若未配置則提示創建可能較慢。
- 在 Codespace 會話中發送消息，如果 Codespace 處於自動暫停或啓動中，系統會等待其變爲
Available才真正發送給模型。 - 在 Codespace 中操作 Git，插件會在會話創建時注入規則，提示 Agent 完成改動後 push 回倉庫。
注意事項¶
- 安裝限制：
dsh plugin add只改寫 profile 的 package.json 依賴，必須手動編輯dsh.profile.bundles數組。 - Profile 限制：
desktopprofile 由 Electron 應用獨佔管理，CLI 無法使用--dump-config-schema。 - 權限範圍：GitHub Token 必須擁有
codespace和repo權限範圍。 - 降級方案：未安裝
gh時插件仍可用，改用設置頁配置的 SSH 別名。
結語¶
該插件通過佔位目錄和按 cwd 路由的設計，將 DSH 的本地工作區機制無縫擴展至雲端。它提供了完整的工作區生命週期管理和 Agent 工具集成能力，適合需要在雲端進行代碼開發與調試的場景。
