MCP 遥控桥 Leawind/dsh-carrot-on-a-stick

DSH Carrot on a Stick

通过 MCP 操作 DeepSeek Harness（dsh）：在 dsh 进程内启动一个 MCP server，把会话执行、任务队列、工作区管理能力暴露出来，任何 MCP 客户端都能调用。

npm version
license

📖 English · 中文（当前页）

它解决什么问题

dsh 自带完整的 agent 运行时——模型路由、工具沙箱、预设、会话持久化——但它是一个 Cordis 应用，外部程序无法直接调用。dsh-carrot-on-a-stick 把它「由内向外」翻转：插件在 dsh 进程内启动 MCP server（StreamableHTTP），通过 ctx.agents / ctx.agentPresets / ctx.tools 桥接运行中的 harness。

你的 MCP 客户端是指挥官，dsh 是执行者。 适配的客户端包括且不限于：Claude Code、Codex CLI、Cursor、另一个 dsh 实例（经官方 dsh-mcp-client 挂接）、任何自动化脚本。

MCP 客户端（Claude Code / Codex / 另一个 dsh / …）
│ agent_run / task_inbox / task_result / model_list / select_model (HTTP + Bearer)
▼
dsh-carrot-on-a-stick（MCP server, 127.0.0.1:8090） │ ctx.agents.create → 挂载 preset ▼
dsh agent —— 完整工具集：bash、fs、todo、web…

agent_run 生命周期（进度与取消均为规范原生机制）：

sequenceDiagram
participant C as MCP 客户端 participant S as dsh-carrot-on-a-stick participant A as dsh Agent C->>S: tools/call agent_run (task, cwd, _meta.progressToken) S->>S: 锁(cwd/session) → 池命中或新建 S->>A: followup(userMessage)
S-->>C: notifications/progress (已启动, events=0)
loop 每 progressIntervalMs
S-->>C: notifications/progress (events N)
end
Note over C,A: 取消(notifications/cancelled) → 官方 agent.cancel({kind:user})
A-->>S: turn/end (completed | error | cancelled)
S-->>C: CallToolResult (isError?, sessionId, changes/verification/leftovers…)

工具

| 工具 | 用途 |
| echo | 验证 MCP 连通性 |
| dsh_list_tools | 列出 dsh 全局工具注册表（name + description；模型工具在 preset 作用域，通常为空） |
| model_list | 列出当前可路由的 provider、模型 id、推理档与缺省选择（选模型前先查这里） |
| agent_run | 同步执行任务，返回结构化结果；sessionId 续接会话；provider/model/reasoningEffort 指定本次模型；detail 分级控制返回体积；支持 MCP notifications/cancelled 取消（走宿主官方 agent.cancel）；调用方传 _meta.progressToken 时发 notifications/progress 心跳 |
| task_inbox | 把结构化任务（任务+上下文+cwd+模型）推入异步队列，返回 taskId |
| task_result | 取回队列任务结果；detail=status 轻量轮询，不重复注入 payload |
| task_list | 列出队列中的任务（排队/执行中/已结束；队列可观测） |
| task_cancel | 取消排队或执行中的任务（执行中走宿主官方 agent.cancel） |
| session_list | 列出已知会话元数据（live+持久化合并，按创建时间倒序），供挑选续接的 sessionId |
| session_history | 读 live 会话的对话纪要（user/assistant/tool 轮次，从最新往回取，文本截断） |
| select_model | 切换已存在会话使用的模型（官方 sessionController.selectModel 路径） |
| attach_session | 把会话归组到其 cwd 对应的工作区 |
| rename_session | 给已有会话改名 |

模型选择

优先级：单次调用参数 > 插件 config（provider+model） > 宿主默认选择（ctx.agentDefaultModel.currentSelection()，与 Web UI 建会话同源）。只给一边时用低优先级来源补另一边；补齐不了会明确报错，而不是留个空模型（否则 persona 里的 {{model}} 变量无值，整个 turn 在组装期失败）。

推理强度（reasoningEffort）与模型同源：调用参数 > 插件 config > 宿主默认选择里的档位。但若调用方或插件 config 已显式钉住 provider+model，就不再继承宿主那个"为别的模型选的"档位（宿主对不支持的显式 effort 直接拒绝，不做 clamp/别名，继承反而会把本来能跑的部署弄挂）。

三条改模型的路径：

| 想要什么 | 怎么做 |
| 这次任务换个模型跑 | agent_run / task_inbox 带 provider+model（可加 reasoningEffort） |
| 同一个会话中途换模型、保留历史 | select_model（官方 sessionController.selectModel：校验 + 写一条持久通知，在下一个 step 生效；历史不丢） |
| 整台部署固定用一个模型 | 插件 config 里成对配 provider+model，并设 allowModelOverride: false 锁死调用方覆盖 |

两个来源语义要分清：

- 常驻会话池按 cwd + 模型三元组 分组。同一目录下用 A 模型跑任务 1、B 模型跑任务 2，是两个独立会话（上下文不串联），这样"哪个会话在用哪个模型"始终可预期；想在一个会话里换模型就用 select_model。
- 结果里新增 model: {provider, model, reasoningEffort?}，调用方不用猜这次是谁答的。

model_list 的 source 说明目录口径：sessionController = 官方口径（与 Web UI 模型选择器同一数据源，含 default / routableProviders / 各 provider 的加载失败与推理档）；llm = 回退口径（llm.listProviders() + 逐个 listModels()，用于没有 sessionController 的部署，如 headless，不含推理档元数据）。同时回报插件自身的模型配置与 allowModelOverride，调用方一眼能看出"我能不能自己选"。

结果分级（token 预算）——本插件的存在意义是省调用方（operator）的上下文：dsh 内部执行细节不进调用方上下文，读回按 detail 投影：

- summary（默认，~数百 token）：changes/verification/leftovers 三行总结 + 回答尾部（总结 JSON 在末尾）+ 工具名列表 + error
- normal（~2k token）：上述 + 截断的工具调用参数与结果
- full（最坏数万 token，排查用）：完整原文
- task_result 另有 status 档：轮询只返回 {taskId, status, error?}，完成后再取一次 summary——避免轮询把结果 payload 重复灌进上下文

续接同一 sessionId 时，executor 已记得此前内容，context 建议只发增量。

每个任务结果都是结构化的：sessionId / model / assistantText / toolCalls / toolResults / changes / verification / leftovers——调用方可以直接写回自己的记忆系统或工单。

会话按 cwd + 模型 复用（LRU，默认 8 个），避免每次调用都重新加载项目上下文。

典型工作流

1. 一次性任务（同步）——直接拿结构化总结：

{ "name": "agent_run", "arguments": { "task": "修复 src/auth 里挂掉的测试", "cwd": "/workspace/app" } }

之后用 "sessionId": "" 续接同一会话——context 只发增量。

2. 异步队列——提交、轻量轮询、按需取消：

{ "name": "task_inbox", "arguments": { "task": "…", "cwd": "/workspace/app", "provider": "deepseek-official", "model": "…" } }
→ { "taskId": "…" }
{ "name": "task_result", "arguments": { "taskId": "…", "detail": "status" } } // 轮询: 不重复注入 payload { "name": "task_cancel", "arguments": { "taskId": "…" } } // 可选 { "name": "task_result", "arguments": { "taskId": "…" } } // 完成后取一次总结

task_list 一览全部排队/执行中/已结束的任务。

3. 发现并驾驭会话——找到对的会话、确认它的模型、回看发生了什么：

{ "name": "session_list", "arguments": { "limit": 10 } } // sessionId / 标题 / cwd / 模型 { "name": "session_history", "arguments": { "sessionId": "…" } } // 最近轮次（截断） { "name": "select_model", "arguments": { "sessionId": "…", "provider": "…", "model": "…" } }

4. 长时同步任务——agent_run 原生支持 MCP 进度与取消：客户端传 _meta.progressToken 即收到 notifications/progress 心跳，任意客户端都可用标准 notifications/cancelled 取消（两者都接到宿主 agent 的官方 cancel），无需自定义轮询协议。

安装与运行

要求 dsh 宿主运行在 Node.js >= 18（插件的 engines 字段已声明）。

插件以包形式装进 dsh 的 profile 目录（loader 从那里解析插件名；在仓库根直接 --patch 是找不到本地包的——见 E2E 记录 发现 1）：

git clone https://github.com/Leawind/dsh-carrot-on-a-stick.git
cd dsh-carrot-on-a-stick
npm install && npm run build
npm pack # 产出 dsh-carrot-on-a-stick-.tgz

装进 profile(Windows 注意: 用 tarball, pnpm 对 file:D:/... 形式会拼坏路径)
pnpm -C ~/.dsh/profiles/ add -w

export DEEPSEEK_API_KEY=... # 模型凭证(或用 ~/.dsh 里已保存的)
dsh --profile --patch ./cordis.yml --no-open --port 3081

MCP server 监听 127.0.0.1:8090（StreamableHTTP）。任意 MCP 客户端指向 http://127.0.0.1:8090/mcp 即可。

客户端配置示例

通用（任何支持 streamable-http 的 MCP 客户端）：

{
"mcpServers": {
"dsh": {
"url": "http://127.0.0.1:8090/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}

让另一个 dsh 操作这个 dsh（对端 profile 的 cordis.patch.yml，走官方 dsh-mcp-client）：

- id: dsh-carrot-on-a-stick
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: dsh
transport: streamable-http
url: http://127.0.0.1:8090/mcp
headers:
Authorization: 'Bearer '

cordis.yml（patch 格式）

- insert:
- id: dsh-carrot-on-a-stick
name: 'dsh-carrot-on-a-stick'
config:
http: true
port: 8090
host: 127.0.0.1 # 默认仅本机; 暴露前必须加认证 authToken: 'your-secret-token' # Bearer token 认证(常数时间比较)
workspaceRoots: ['/workspace'] # cwd 白名单(跨平台分隔符/大小写安全)
allowedHosts: ['my-box.lan'] # Host 头白名单追加项(防 DNS rebinding)
preset: 'standard' # 挂载的 agent preset model: '' # 空 = 跟随 dsh 用户/默认设置 provider: '' # 与 model 成对; 空 = 跟随宿主默认 reasoningEffort: '' # 默认推理强度(空 = 适配器默认) allowModelOverride: true # false = 锁死模型, 拒绝调用方的覆盖 sessionTtlMs: 86400000 # 空闲 MCP 传输会话超过该时长即被回收(0 = 永不)

| 字段 | 默认值 | 含义 |
| host / port | 127.0.0.1 / 8090 | MCP server 监听地址；监听失败（如端口被占）会让插件启动显式失败 |
| authToken | — | Bearer token；设置后所有请求强制校验（常数时间比较） |
| workspaceRoots | — | cwd 白名单；agent 只能在列出的目录（含子目录）下干活 |
| allowedHosts | — | Host 头白名单追加项；默认放行绑定地址与 loopback 别名，其余 403 |
| provider / model | 跟随宿主用户设置（agentDefaultModel） | 生成 agent 的模型选择；需成对配置，只配一边会用宿主默认补全另一边 |
| reasoningEffort | 适配器默认 | 默认推理强度（适配器定义的 id，见 model_list 的 reasoningEfforts） |
| allowModelOverride | true | 是否允许调用方（agent_run/task_inbox/select_model）覆盖模型；false = 部署锁死，覆盖请求被明确拒绝 |
| preset | standard | 挂载的 agent preset |
| defaultDetail | summary | agent_run/task_result 的默认详略级别（单次调用可用 detail 覆盖） |
| reattachOrphans | false | 启动时把未分组会话补挂到工作区（批量写用户数据，默认关；attach_session 工具随时可用） |
| maxQueue / taskTtlMs / maxAgents | 100 / 10 分钟 / 8 | 队列容量、结果保留时长、会话池 LRU 上限 |
| taskTimeoutMs | 0（关闭） | agent turn 自动超时；到点走官方 agent.cancel({kind:'hook'})，结果 error 注明超时。长任务部署请调大或保持关闭 |
| progressIntervalMs | 5000（最小 250） | agent_run 的 notifications/progress 心跳间隔——仅当调用方传 _meta.progressToken 时生效 |
| queuePersistPath | —（关闭） | 任务队列持久化文件：每次变化即落盘；重启后 done/error/cancelled 连结果取回、queued 重新执行、running 如实标记 interrupted by restart |
| sessionTtlMs | 86400000（24 小时） | 空闲超过该时长的 MCP 传输会话被服务端回收；客户端对旧会话 id 得到 404，按规范重新 initialize 即可（0 = 永不回收） |

每个任务结果都是结构化的：sessionId / model / changes / verification / leftovers / error / toolCallCount …（按 detail 分级投影）；error 承接 turn 的非正常收场（模型调用失败/取消/blocked），不会再出现"成功"的空结果；空的 error/taskId 字段直接省略（不再是空串）。工具级失败（未知 taskId、覆盖被拒、服务不可用、cwd 越界、turn 失败）按 MCP 规范以 isError: true 的工具结果返回——严格客户端与模型无需解析载荷即可识别为失败。

零宿主副本

插件运行时对 @deepseek-ai/ 零依赖：所有 dsh 能力都经注入的宿主服务（ctx.agents / ctx.tools / ctx.agentPresets …）访问；类型只在编译期做声明合并（import type，构建后擦除），@deepseek-ai/ 全部是 devDependencies。
因此插件自带的新旧依赖副本永远不会与宿主进程内的私有 Symbol/类标识错位——上游 0.1.x 时代 scopeOf 副本不匹配导致 agent 静默失去全部工具的根因就此消除。
事件读取走公开 API session.snapshotEvents()，消息构造用与宿主 createUserMessage 逐字段一致的本地实现。

安全

⚠️ 这个插件暴露的是本机执行能力（等价于远程代码执行）。默认只监听 127.0.0.1。启用时务必：

1. 配置 authToken——防本机其他进程与 DNS rebinding 攻击（常数时间比较）；
2. 配置 workspaceRoots——限定 agent 可操作的目录；
3. 不要绑定 0.0.0.0 或暴露到局域网/公网，除非前面有反代 + TLS + 认证。

内置防护：Host 头白名单（默认绑定地址 + loopback 别名，防 DNS rebinding，缺失 Host 400）；同一白名单上的 Origin 头校验（带跨域或非法 Origin——如 Origin: null——一律 403；不发 Origin 的非浏览器 MCP 客户端不受影响）；HTTP 入口只服务 /mcp，其余路径 404；401 响应带 WWW-Authenticate: Bearer 挑战；空闲传输会话超过 sessionTtlMs（默认 24 小时）自动回收。
工具同时携带协议元数据（title、annotations.readOnlyHint 等，2025-06-18 协议字段），便于客户端标注与沙箱判断。注意：queuePersistPath 会把任务载荷（任务文本、调用方上下文、结果）以明文写入指定文件——请放在文件系统权限合适的路径。

Web 设置面板

bundle 还会向 dsh Web UI 注入一个设置区（设置 → dsh-carrot-on-a-stick）：

- 实时状态徽章（监听中 / 已软停 / http 关闭）与运行时长；
- MCP 端点（点击复制）与停止 / 启动按钮——软停止会排空并干净关闭，启动重新监听（重启后的真实握手有测试覆盖）；
- 已连接的 MCP 客户端：会话 id、User-Agent、连接时间、最近活跃、请求数；
- 模型 / preset / 认证 / 会话 TTL / 队列持久化摘要，以及队列计数（活跃 / 完成 / 失败 / 取消）。

面板经同源路由 /_dsh/dsh-carrot-on-a-stick/ 与宿主通信；变更类路由要求同源标识，无需额外端口或 CORS 暴露。

源码来源

本项目的初始源码复制自 chushixixin/dsh-harness-mcp-server（MIT，感谢 @chushixixin），随后作为独立项目演进：不保留 git fork 关系，也不计划向上游贡献。主要改造方向：

- 去 Hermes 化：面向任意 MCP 客户端（Claude Code / Codex / Cursor / 另一个 dsh / 自动化脚本）；
- 贴合当前版本 dsh：见下方 Roadmap；
- 独立命名与仓库：dsh-carrot-on-a-stick。

Roadmap / 已知限制（对 dsh 0.1.5-rc.2）

0.2.0 Roadmap 的兼容性问题已在 0.3.0 处理；0.3.1 完成真机 E2E 验证（全绿，见 docs/e2e-0.1.5-rc.2.zh.md），并修复 E2E 发现的问题：{{model}} 提示词变量（模型选择现经 agentDefaultModel 补全）、turn 失败透出、池会话 flush、存量捞回默认关闭、安装流程文档修正。
0.5.0 补齐模型选择面：model_list（官方目录 / llm 回退）、agent_run+task_inbox 的按调用覆盖、select_model（会话内换模型）、reasoningEffort、allowModelOverride 门禁、结果自报 model、会话池按 cwd + 模型 分组。
本批次（未发布）覆盖六个方向，逐批细节见 CHANGELOG：

- 协议一致性：工具错误结果带 isError: true、DNS rebinding 防护补上 Origin 头校验、401 带 WWW-Authenticate 挑战、工具暴露 title + annotations、空闲传输会话自动回收（sessionTtlMs）、10MB 请求体上限；
- 取消：agent_run 支持 MCP notifications/cancelled 与客户端超时（都接到宿主官方 agent.cancel）；
- 可观测：notifications/progress 进度心跳（规范 _meta.progressToken）、task_list、只读 session_list（含当前模型）与 session_history（可翻页）；
- 异步队列：task_cancel、可选持久化（queuePersistPath，原子写）、running/interrupted 状态如实上报；
- 韧性：锁表清理、LRU 淘汰跳过活跃会话、损坏持久化文件启动存活；
- 协议审查报告见 docs/protocol-audit-2026-09-24.zh.md。

仍然存在的限制：

- [x] 任务队列在进程内存中，进程重启丢失——可选持久化（queuePersistPath）已加；不配置时仍是内存队列。
- [x] 无服务端自动超时——可选的 taskTimeoutMs（默认关闭）已加；调用方仍可主动取消（agent_run 用 MCP notifications/cancelled，队列任务用 task_cancel）。
- [x] 队列不能列举/取消——已补（task_list / task_cancel）。
- [x] 只读查询面不完整：没有 session_list——已补（列会话元数据 + session_history 纪要；仅持久化的会话读整日志仍需宿主侧 API）。
- [ ] preset 仍是部署级配置（一个 MCP server 实例一种 persona），不能按调用指定。
- [ ] spawn 出的会话里工具调用走宿主 approval 策略（ask 下敏感操作可能弹窗或 fail-closed；本次 E2E 的只读操作未受影响）。
- [ ] dsh_list_tools 只列宿主全局注册表；按 agent 作用域列出实际可用工具需要宿主侧 API（ScopeKey 私有符号，零副本原则下拿不到）。
- [ ] select_model 依赖 web profile 的 sessionController；该服务缺席时（如 headless）只有目录回退与按调用覆盖可用，工具会明确报不可用。
- [ ] 协议原生 task augmentation（2025-11-25 草案，SDK 接口标注 experimental）：把 agent_run 暴露为规范原生任务，走 tasks/get / tasks/result 轮询。有意缓做——task_inbox / task_result / task_cancel 已对所有客户端覆盖同一工作流，等规范离开草案再评估。
- [ ] dsh 未来版本升级时，devDeps 里的 @deepseek-ai/ 类型版本需同步（仅影响编译期，运行时零依赖不受影响）。

开发

npm install
npm run build # 独立构建(纯 tsc), 产出 lib/
npm run smoke # 端口 8099/8098/8096/8095/8094/8093/8092/8091/8089/8088/8087/8086/8085 假 ctx 冒烟(132 项, 真实 MCP 协议往返 + 官方 SDK Client 对接) + 端口冲突专项

真机 E2E（需要本机 dsh 与模型凭证，会花少量 token）：按 docs/e2e-0.1.5-rc.2.zh.md 的方式起一个独立 profile，然后 E2E_WITH_AGENT=1 node e2e.mjs。

License

MIT —— 见 LICENSE（保留上游版权声明）。