常驻 Worker 编排 EliasVahlberg/dsh-workers-mcp

dsh-workers-mcp

dsh-workers-mcp：把长期存活的 dsh 会话当作常驻 worker 来驱动

一个 MCP 服务器，把长期存活的 DeepSeek Harness（dsh）会话当作常驻 worker 来驱动。任意工作目录里的编排智能体都能用它把活派给 worker、回答卡住 worker 的问题、查看 worker 干了什么。

前提是这样的：dsh worker 会话会积累起对项目的熟悉度，而这份熟悉度很贵。在作者的测试里，一个 57 轮的会话累计了大约 13 小时的模型时间，缓存命中率 97%。那个会话是私有的，所以你没法复现这个数字。每接一个任务就把这些丢掉，纯属浪费。这些工具把 worker 当队友，长期留着；不把 worker 当函数，用完就扔。

运行时只用标准库。没有任何依赖，连 WebSocket 读取器都是我们手写的。

第一次来？ 看 docs/QUICKSTART.md。大约 15 分钟，带你用一个 worker 跑完一个任务。

它不是什么

- 和 DeepSeek 没有隶属关系。 这是独立项目。DeepSeek 没有开发、认可或支持它。它通过 DeepSeek Harness 这个开源程序的 HTTP API 来驱动它。
- 不是 A2A 实现。 没有 Agent Card，没有 SendMessage 操作，也没有 Task 生命周期。我们评估过 A2A，故意不用：A2A 把智能体当成黑盒，而这些工具会暴露上下文压力、缓存命中率和步数，好让编排方贴身监督。docs/A2A_EVAL.md 里有理由。
- 不是通用工具。 每个操作都针对 dsh 的 HTTP API、事件类型和投影，不是对智能体框架的抽象。

状态

这是 alpha（0.1.0）。工具名、工具参数和状态格式都可能变。状态格式有兼容性测试，会拿旧版本的文件来跑。

跑过什么
- 测试跑在替身 dsh 上，CI 覆盖 Python 3.10 到 3.13。CI 还会跑 ruff、mypy、复杂度棘轮和导入层检查。
- 只读命令（dshctl list、dshctl pending、host.describe、dsh-wake 的 dry run，以及走 MCP 服务器的 dsh_list）跑在真实 dsh 上，包版本 0.1.1-rc.2，commit b150a55。
- 发布版 v0.1.0 能从自己的 tag 和 wheel 装进干净环境，服务器能应答 MCP 握手。装好的副本没再跑别的。
- 最初的工具在真实 dsh 上跑过一个长期项目。测试是作者做的。docs/DSH_API.md 里写了是哪些。

没跑过什么
- 会改状态的调用（dsh_create、dsh_fork、dsh_name、dsh_cancel、dsh_permission、dsh_task、dsh_ask）只跑过替身，因为客户端接口是后来加的。形状检查不覆盖它们。
- 形状检查覆盖 7 个只读方法。它不覆盖流帧，也不覆盖两个 POST 端点。
- 快速开始只在脚本化 worker 下跑通了全流程。没有模型参与，也没有别人照着做过。
- dsh-wake 还没在真实客户端上跑过。
- 沙箱包装器通过了自检。它里面嵌套的 bwrap 起不来（见 docs/SANDBOX.md）。包装器有两个测试在 CI 里跳过，因为 runner 上用不了 bubblewrap。它们在作者机器上能过。

如果你发现这些说明和你看到的不一致，提个 issue。

安装

你需要 Python 3.10 或更高版本，以及一个正在运行的 dsh web 服务器（默认 http://127.0.0.1:3080）。

从 release 安装。 最新版是 v0.1.0。用 uv，MCP 客户端可以直接从 tag 启动服务器。把下面这段放进它的配置：

{
"mcpServers": {
"dsh-workers": {
"command": "uvx",
"args": ["--from", "git+https://github.com/EliasVahlberg/dsh-workers-mcp@v0.1.0", "dsh-workers-mcp"],
"timeout": 600000
}
}
}

或者从 release 页面下载 wheel，然后运行 uv tool install dsh_workers_mcp-0.1.0-py3-none-any.whl。这样会把 dsh-workers-mcp、dshctl 和 dsh-wake 装进你的 path。我们在干净环境里两种方式都跑过，服务器都回应了 MCP 握手。wheel 里只有服务器和 tool-policy overlay。技能、方法和模板都在仓库里，所以请按 tag 去读。

从 clone 安装。 开发时用这个，或者想对照代码读方法时用：

uv sync # or: pipx install -e .

有三个入口点：

| 命令 | 用途 |
| dsh-workers-mcp | MCP stdio 服务器 |
| dshctl | 同样的操作，以命令行形式提供，方便调试 |
| dsh-wake | 可选的循环，在需要时再次运行 lead 的客户端（见 docs/WAKE.md） |

接入智能体

用 release 的话，用 安装 里的 uvx 配置。用 clone 的话，用这个： {
"mcpServers": {
"dsh-workers": {
"command": "uv",
"args": ["run", "--project", "/abs/path/to/dsh-workers-mcp", "dsh-workers-mcp"],
"timeout": 600000
}
}
}

用绝对路径。相对路径会按智能体的工作目录解析。这就是这个服务器单独放在自己仓库里的原因。

用 uv run --project。不要用 uv --directory。--directory 选项会把工作目录切到这个仓库。那样默认状态目录就跑到这里，离开了智能体工作的 workspace。

服务器参数：
- --base <url> 设置 dsh 服务器（默认 http://127.0.0.1:3080）。
- --state-dir <path> 设置服务器写 orchestrator 状态的位置。
- --no-state 不记录任何东西，并隐藏 dsh_roster、dsh_tasks、dsh_digest 和 dsh_brief。
- --allow-full-access 让 dsh_permission 和 dsh_create 可以应用 danger-full-access。服务器默认拒绝。

配套技能在 skills/dsh-workers/SKILL.md，记录了协议、操作陷阱和压缩的语义。它是一个带 frontmatter 的纯 markdown 文件。用你的 MCP 智能体加载技能或常驻指令的方式加载它。例如，kiro-cli 把它引用为 skill:///abs/path/to/dsh-workers-mcp/skills/dsh-workers/SKILL.md。没有技能功能的客户端可以把该文件放进自己的指令里。

工作单元与权限

该方法按监督级别雇佣工作单元：read-only、supervised 或 autonomous。overlays/tool-policy/ 里的 tool-policy 覆盖层提供这些级别。它们控制的是范围，不是安全。读取主目录下任何文件、访问网络、写入另一个工作单元的区域，这些操作都保持开放。docs/PERMISSIONS.md 有预设和完整的限制清单。docs/SANDBOX.md 有 dsh 服务器可选的 bubblewrap 包装器。

文档

| 阅读 | 用途 |
| docs/QUICKSTART.md | 一个工作单元，一个任务，15 分钟 |
| docs/TOOLS.md | 21 个工具，以及哪些会改变工作单元状态 |
| orchestration/METHOD.md | 主控智能体的工作方法：会话启动、雇佣、任务生命周期、审批、合并与发布 |
| orchestration/PLAYBOOKS.md | 该方法引用的手册：规划、派发、评审、规模闸门。orchestration/templates/ 有每个项目的文件 |
| orchestration/REMINDER.md | 一页最重要的规则。把它作为主控的常驻资源加载 |
| docs/STATE.md | 编排器状态目录：名册、任务、摘要 |
| docs/WAKE.md | dsh-wake，唤醒主控的循环 |
| docs/PERMISSIONS.md | 预设，以及工作单元能做和不能做的事 |
| docs/SANDBOX.md | bubblewrap 包装器，以及它已知的问题 |
| docs/DSH_API.md | 本包依赖 dsh 的哪些部分，以及哪些实际跑过 |
| docs/DEVELOPMENT.md、CONTRIBUTING.md | 检查、分层、如何添加工具 |
| SECURITY.md、CHANGELOG.md | 如何报告问题，以及有哪些变更 |

License

MIT