前言¶
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 工具集成能力，适合需要在云端进行代码开发与调试的场景。
