Qoder 云端代理 QoderAI/dsh-qoder-cloud-agents

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，并且已经把要处理的提交推送到远端：云端只能拿到已推送的提交。

安装与配置

1. 克隆仓库并构建安装包（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/），配置档里记录的是这个路径。

2. 安装到 dsh 的 web 配置档（其他配置档换成对应名字），路径必须是绝对路径：

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 源或其镜像。

3. 把令牌写进 ~/.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

4. 通用 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

5. 其他可选配置也写在同一段 config 下（补丁会整体替换 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。

6. 重启 dsh：在 dsh web 的终端按 Ctrl+C 停掉再运行 dsh web；客户端用户完全退出（⌘Q）后重新打开。dsh 只在启动时读取插件和令牌。

运行

云端模式

1. 在 dsh web 左侧工作区选一个本地 git 仓库，点「新会话」。
2. 打开输入框上方最右侧的「云端模式」开关，左边的模式标签会同步变成「云端模式」。
3. 输入任务并发送，例如「把 README 的问候语改成中英双语，提交并推送到新分支」。第一次使用会弹窗选择 Qoder 环境，一般选托管 cloud 环境（如 Default），选择会保存到 profile。

首次使用：选择 Qoder 环境
4. 继续输入就是追问，始终在同一个云端沙箱里，上一轮的改动都还在。
5. 在本地拿回云端推送的分支，分支名写在回复里：

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 | 安装插件时写入配置档的 bundle 配置 |

许可证

MIT