dsh-qoder-cloud-agents
dsh-qoder-cloud-agents 是一个 DeepSeek Harness（dsh）插件，把任务交给 Qoder Cloud Agents 在云端沙箱里执行。它提供三个入口：
| 入口 | 用法 | 适合 |
|---|
| 云端模式 | 新会话输入框上方最右侧的「云端模式」开关 | 整个会话在云端执行，回复实时显示，可在同一个云端沙箱里连续追问 |
子代理工具 subagent_qoder_cloud_agents | 普通会话里由 DeepSeek 调用 | 把某个子任务委派到云端，跑完后结果交回 DeepSeek |
斜杠命令 /qoder-cloud-agents | 在对话框输入 | 查看和切换 Qoder 环境、Agent |
工作区是 git 仓库时，插件按 Qoder 控制台的方式把 origin 挂载到云端 /data/workspace/<仓库名>，并要求云端 Agent 把改动推送到新分支 qoder-cloud-agents/<随机8位>。
新会话页：输入框上方最右侧的「云端模式」开关
云端执行的工具调用和结果实时回到对话，追问还在同一个云端沙箱里：
云端回复：工具调用与结果
前置条件
- Node.js 22 或更高版本，以及 npm。
- DeepSeek Harness 0.2.x（
dsh --version 可查看），或内置 dsh 0.2.x 的 Mac / Windows 客户端。
- Qoder 个人访问令牌（PAT）：登录 qoder.com，在 Settings → Personal Access Tokens 中创建，形如
pt-…，只显示一次。
- 可选：代码仓库令牌。仓库是私有的，或者要让云端
git push 时才需要：
- GitHub：fine-grained PAT 授予 Contents 读写，或 classic PAT 授予
repo。
- GitLab.com、Gitee 等通用 Git：该平台的个人访问令牌（GitLab 需要
read_repository 和 write_repository），并在插件配置里写上用户名 gitUsername。
- 在本机打开的 git 仓库需要配置好
origin，并且已经把要处理的提交推送到远端：云端只能拿到已推送的提交。
安装与配置
-
克隆仓库并构建安装包（npm pack 会先执行构建）：
git clone https://github.com/QoderAI/dsh-qoder-cloud-agents.git
cd dsh-qoder-cloud-agents
npm ci
npm pack
得到 dsh-qoder-cloud-agents-0.1.0.tgz。把它放到一个固定目录（例如 ~/dsh-plugins/），profile 里记录的是这个路径。
-
安装到 dsh 的 web profile（其他 profile 换成对应名字），路径必须是绝对路径：
dsh plugin --profile web add ~/dsh-plugins/dsh-qoder-cloud-agents-0.1.0.tgz
Mac / Windows 客户端：在侧边栏「插件」→ 安装插件，填 tgz 的绝对路径。
安装时 dsh 会用 pnpm 从 npm 源拉取插件的运行时依赖 Qoder Cloud Agents TypeScript SDK，需要能访问 npm 源或其镜像。
-
把令牌写进 ~/.dsh/.env，不要写进仓库或 yml 配置：
echo 'QODER_PAT=pt-<your-qoder-pat>' >> ~/.dsh/.env
echo 'QODER_GIT_TOKEN=<your-git-token>' >> ~/.dsh/.env # 公开仓库、只读可以不配
chmod 600 ~/.dsh/.env
-
通用 Git（GitHub 跳过）：打开 ~/.dsh/profiles/web/cordis.patch.yml，加上用户名。文件里已有 id: qoder-cloud-agents 时只在它的 config 下补字段；文件只有一行 [] 时先删掉它：
- id: qoder-cloud-agents
name: dsh-qoder-cloud-agents
config:
gitUsername: your-git-user
-
其他可选配置也写在同一段 config 下（patch 会整体替换 config，已有字段要一起保留）：
- id: qoder-cloud-agents
name: dsh-qoder-cloud-agents
config:
baseURL: https://api.qoder.com/api/v1/cloud
environmentId: env_xxx # 不填：首次使用时弹窗选择并记住
agentId: agent_xxx # 不填：自动选择或新建插件管理的 Agent
repository: auto # auto | none
branchPrefix: qoder-cloud-agents/
archiveOnFinish: false # true：子代理回合结束后归档云端 session
timeoutMs: 7200000 # 单次委派上限，超时会取消云端回合
全部字段见 src/index.ts 中的 Config。
-
重启 dsh：在 dsh web 的终端按 Ctrl+C 停掉再运行 dsh web；客户端用户完全退出（⌘Q）后重新打开。dsh 只在启动时读取插件和令牌。
运行
云端模式
-
在 dsh web 左侧工作区选择一个本地 git 仓库，点击「新会话」。
-
打开输入框上方最右侧的「云端模式」开关，左边的模式标签会同步变成「云端模式」。
-
输入任务并发送，例如「把 README 的问候语改成中英双语，提交并推送到新分支」。第一次使用会弹窗选择 Qoder 环境，一般选托管 cloud 环境（如 Default），选择会保存到 profile。
首次使用：选择 Qoder 环境
-
继续输入就是追问，始终在同一个云端沙箱里，上一轮的改动都还在。
-
在本地拿回云端推送的分支，分支名写在回复里：
git fetch origin && git checkout qoder-cloud-agents/xxxxxxxx
子代理工具
在普通会话里点名让 DeepSeek 使用这个工具最可靠：
用 subagent_qoder_cloud_agents 把这个任务交给云端：给 src/utils/date.ts 补单元测试，跑通后推送到新分支。
工具调用立即返回，云端跑完后结果（含云端 session id、结果分支、交付文件和本地未推送提醒）自动回到对话。一次委派是一个独立的云端 session，不能追问；需要来回交流时用云端模式。
斜杠命令
| 命令 | 作用 |
|---|
/qoder-cloud-agents | 查看当前环境、Agent 和网关 |
/qoder-cloud-agents env | 列出环境（* 为当前） |
/qoder-cloud-agents env <id或名称> | 切换环境并保存 |
/qoder-cloud-agents agent | 列出 Agent |
/qoder-cloud-agents agent <id或名称或 new> | 切换 Agent；new 使用插件管理的 Agent |
/qoder-cloud-agents reset | 清除已保存的选择，下次重新选择 |
验证结果
单元测试不访问外部网络：它在本机起一个模拟 Qoder Cloud 网关，覆盖环境与 Agent 的选择、仓库挂载、SSE 断线续传、取消、云端模式的请求路由和系统提示词变量。
npm ci
npm test
预期 2 个测试文件、37 个测试全部通过。
端到端验证（会消耗 Qoder 额度）：
- 云端模式会话的输入框右下角显示「云端模式（Qoder Cloud Agents）」。
- 回复下展开「已完成」→「已完成分析」，能看到云端 session id、仓库地址、结果分支，以及
› Read、› Bash: git push … 这样的工具调用。
- 第二轮追问的回复说明仍在同一个沙箱，结果推送到同一个分支。
- 本地
git fetch 后 git log --oneline -3 能看到云端的提交。
- 轨迹页里，云端模式会话不会在第二轮出现「系统提示词已更新」。
清理资源
- 云端 session：子代理工具在配置
archiveOnFinish: true 时会自动归档；云端模式和默认配置下 session 保留在 Qoder 控制台，可在控制台归档或删除。
- 结果分支：不需要时删除远端分支，例如
git push origin --delete qoder-cloud-agents/xxxxxxxx。
- 插件：
dsh plugin --profile web remove dsh-qoder-cloud-agents，然后重启 dsh。cordis.patch.yml 里保存的 environmentId、agentId、gitUsername 不会随卸载删除，不需要时手动删掉那一段。
- 令牌：从
~/.dsh/.env 删除 QODER_PAT、QODER_GIT_TOKEN，并在 Qoder 与 Git 平台吊销不再使用的令牌。
- 本地构建产物：删除仓库根目录下的
node_modules/、lib/ 和生成的 .tgz。
成本与安全
- 每次云端执行都会消耗 Qoder 额度。作者实测一个只读小任务加一次追问约 5.8 credits，实际消耗取决于任务和模型。
QODER_PAT 可以代表你调用 Qoder Cloud Agents API；QODER_GIT_TOKEN 会作为仓库凭据随 session 发送到 Qoder Cloud，云端 Agent 可以用它向你的仓库推送。请使用最小权限、可随时吊销的令牌，只把令牌放在 ~/.dsh/.env（chmod 600）或环境变量里。- 云端 Agent 会在新分支上提交并推送，不会改动当前分支；合并前请像审查同事的 PR 一样审查改动。
- 云端模式只把你新输入的文字（以及首轮的仓库与分支说明）发送给 Qoder Cloud，不会发送 dsh 的系统提示词；本地附加的图片和文件不会上传。
- 插件以 dsh 宿主进程的权限运行，请只从可信来源安装。
开发
npm ci
npm run typecheck # TypeScript 类型检查
npm test # vitest，使用本机模拟网关，不访问外部网络
npm run build # 产出 lib/
npm pack # 打包 tgz（会先执行 build）
代码结构：
| 文件 | 作用 |
|---|
src/index.ts | 插件入口：配置、子代理提供方、云端模式模型路由 |
src/cloud-mode.ts / src/cloud-route.ts | 云端模式：把会话的每一轮转发到 Qoder Cloud Agents |
src/run.ts | 子代理工具的一次委派：建 session、挂载仓库、跟踪 SSE |
src/target.ts / src/command.ts | 环境与 Agent 的选择、/qoder-cloud-agents 命令 |
src/client.ts | 基于 Qoder Cloud Agents TypeScript SDK 的 ManagedClient，收窄到插件用到的接口并统一错误格式 |
src/git.ts / src/github.ts | 识别本地仓库、GitHub 预检 |
client.js | Web / 客户端里的「云端模式」开关 |
cordis.patch.yml | 插件安装时写入 profile 的 bundle 配置 |
许可证
MIT
