Ouroboros × DeepSeek Harness 双向集成指南:dsh 插件与 dsh LLM 后端完整配置实战

原创2026-10-09 18:16:331,973 阅读
文章标签:人工智能AI Agent代码智能体Agent 编排Agent 工作流MCP 服务MCP ClientsCLI工具调用提示工程

Ouroboros × DeepSeek Harness 双向集成指南:dsh 插件与 dsh LLM 后端完整配置实战

导读:本文围绕 Ouroboros 项目与 DeepSeek Harness(dsh)之间的两条独立集成方向展开——一是把 Ouroboros 的全部 MCP 工具以插件形式装进 dsh profile(dsh → Ouroboros),二是让 Ouroboros 的 interview/Seed/QA 补全调用由 DeepSeek 的模型通过 dsh-acp-demo 子进程回答(Ouroboros → dsh)。读完本文,你将掌握插件安装、凭据转发规则、ACP 后端搭建、composition 指向与后端选择的全流程,并理解两条通路在运行时为何互不相关、以及回环(loopback)组合时的注意事项。

一、两条方向,一个原则:运行时互不相关

Ouroboros 与 DeepSeek Harness(dsh)通过两个相互独立的方向连接。按你希望所处的位置二选一:

你想…… 方向 配置方式
在 dsh 对话里工作,并从那里调用 Ouroboros dsh → Ouroboros 安装插件(见下文)
在 Ouroboros 里工作,让 DeepSeek 的模型回答 interview/Seed/QA 调用 Ouroboros → dsh 配置 dsh LLM 后端(见下文)

两条通路在运行时互不相关:安装插件不会改变 Ouroboros 使用哪个 LLM;选择 dsh 后端也不会把任何东西装进你的 dsh profile。 这是理解整个集成体系的第一原则,也是后续所有配置决策的前提。

从源码层面看,这种隔离是刻意设计的。DshAcpClient._build_env(src/ouroboros/providers/dsh_acp_client.py)在拉起 dsh-acp-demo 子进程时,会从环境中剔除 OUROBOROS_AGENT_RUNTIME、OUROBOROS_LLM_BACKEND、OUROBOROS_RUNTIME、OUROCODE_MODEL 等选择器变量——防止 dsh 里嵌套的 ooo 调用搞混自己正在使用哪个后端;而插件方向则通过 cordis.patch.yml 的显式 env 层精确控制哪些变量能到达 ouroboros mcp serve。两条方向的变量隔离共同保证了“各回各家”。

二、dsh → Ouroboros:把 Ouroboros 装进 dsh 对话

2.1 一条命令安装

Ouroboros 的所有 MCP 工具可以通过一条命令出现在你的 dsh profile 里:

dsh plugin --profile <your-profile> add "github:Q00/ouroboros#main&path:integrations/dsh-plugin"

--profile 是 dsh plugin 的必填项,它指定要安装进哪个 profile。安装完成后照常启动(dsh --profile <your-profile>,若 profile 名为 web 也可用 dsh web),而 dsh --profile <your-profile> --dump-config 会显示一个 # == dsh-ouroboros 层,表示 bundle 已成功合成进配置。

这个 bundle 位于 Ouroboros 主仓库的 integrations/dsh-plugin/ 子目录,是纯配置 bundle:它不包含任何自定义插件代码,只有一行把 dsh 自带的 @deepseek-ai/dsh-mcp-client 挂到 ouroboros mcp serve 上的配置(见 integrations/dsh-plugin/package.json 与 integrations/dsh-plugin/cordis.patch.yml)。

2.2 在对话里直接使用

装好后直接在 dsh 对话里输入你想做的事:

ooo interview I want a CLI that keeps my dotfiles in sync
ooo auto add retry-with-backoff to the fetch layer

模型会自己找到匹配的 mcp__ouroboros__* 工具——共 36 个工具,各自都带描述,所以不需要额外提示。工具命名空间为 ouroboros,例如 mcp__ouroboros__ouroboros_interview、mcp__ouroboros__ouroboros_auto、mcp__ouroboros__ouroboros_evaluate、mcp__ouroboros__ouroboros_ralph 等。bundle 把 toolCallTimeoutMs 设置为 1800000(30 分钟),因为 ooo auto 在无轮询调用时会同步跑完「interview → Seed → execute → grade」整条流水线,需要远大于 dsh 默认 60 秒的余量。

2.3 前置条件

  • PATH 上有 uv。这是唯一的前置条件:插件会拉起 uvx --from 'ouroboros-ai[mcp]' ouroboros mcp serve,首次启动时把 Ouroboros 取进一个隔离环境,无需单独的 pip install 步骤(Python >= 3.12,由 uv 解析)。
  • 如果你想让 ooo auto 执行它的执行步骤,需要一个可执行的 agent runtime(claude-cli、codex、opencode……)。要么先跑一次 ouroboros setup,要么导出 OUROBOROS_AGENT_RUNTIME。MCP 子进程无法承载进程内的 claude SDK runtime,所以这里必须用可执行的。

关于执行 runtime,bundle 的默认行为值得一提:cordis.patch.yml 中 OUROBOROS_AGENT_RUNTIME 的取值是 !!js process.env.OUROBOROS_AGENT_RUNTIME || 'host'——默认回落到字面量 'host',即由 dsh 自己的模型代为执行 ooo run/ooo auto 的执行步骤(dsh 没有可安装的执行 CLI)。?? '' 则让其他变量保持字符串类型(行 schema 是字符串字典),Ouroboros 把空白的凭据视为未设置。相关变量的完整清单见下表:

变量 作用
OUROBOROS_AGENT_RUNTIME ooo run/ooo auto 执行步骤所用的 agent runtime。默认 host(dsh 自己的模型执行);设为 claude-cli、codex、opencode 等则改用对应 CLI
OUROBOROS_LLM_BACKEND interview/Seed/QA 的 LLM 后端。不设则沿用 ouroboros setup 的默认值;设为 dsh 会把这类调用路由回 DeepSeek Harness(见下文,还需两个额外变量)
OUROBOROS_DSH_CONFIG_PATH 受信任的 Cordis composition 的绝对路径。只要 OUROBOROS_LLM_BACKEND=dsh 就必须提供
OUROBOROS_DSH_CLI_PATH dsh-acp-demo bin 不在 PATH 时,用此变量指名

2.4 凭据不会隐式传递(关键安全设计)

dsh 会按设计把子进程环境里所有凭据形状的变量——任何匹配 /KEY|PASSWORD|SECRET|TOKEN/i 的——全部擦除,以免 harness 的凭据泄漏进被拉起的程序。插件的显式 env 层在擦除之后才合并,这是凭据到达 ouroboros mcp serve 的唯一途径。

因此 bundle 只转发一份刻意精简的允许清单,而不是转发一切:

  • ANTHROPIC_API_KEY —— Ouroboros 的默认 LLM 后端
  • DEEPSEEK_API_KEY —— 下文的 dsh 后端回环(loopback)

要再多转发一个(OPENAI_API_KEY、OPENROUTER_API_KEY、GOOGLE_API_KEY……),就在你自己 profile 的 cordis.patch.yml 里覆写 mcp-ouroboros 这一行,把那个额外的名字放进 env。后加的 patch 层会整体替换一行的整个 config,而不是深度合并,所以要把 bundle 的 config 块原样复制过来,再加上你的一行。所有非凭据形状的东西——PATH、HOME、OUROBOROS_* 选择器——原样通过,完全不需要条目(cordis.patch.yml 中列出 OUROBOROS_* 各行只是为了把契约显式化在一处)。

2.5 启动失败时:软失败与恢复

启动失败是非致命的(failOnStartupError: false):没有 uv 的机器仍然能启动 dsh,其他插件照常工作,只是没有 Ouroboros 工具。恢复一般不是自动的——mcp-client 是否重试取决于你的 dsh 构建:已发布的 0.0.1-rc.1 没有重连循环;当前 main 分支带有一个有界的指数退避重连循环,会在有限次连续失败后放弃。无论哪种情况,修好原因(安装 uv、设置 runtime)之后,重载插件或重启 dsh,不要干等重连。

完整 bundle 参考:integrations/dsh-plugin/README.md。

三、Ouroboros → dsh:把 DeepSeek 模型接成 LLM 后端

3.1 边界:dsh 是纯 LLM 后端

dsh 是一个纯 LLM 后端:它回答 interview、Seed 撰写和 QA 调用。它不能用作 orchestrator.runtime_backend——dsh 的 ACP 表面刻意做成纯文本、fresh-session,对补全(completions)合适,对会使用工具的执行 runtime 则不合适。这一点在源码里有明确印证:后端能力表中 dsh 被标注为“仅 LLM 补全后端”,它通过 dsh 的 automation-only ACP server(dsh-acp-demo)流式返回单个文本轮次、无工具使用(见 src/ouroboros/backends/capabilities.py)。

选它不是拨一个变量开关那么简单。Ouroboros 会拉起它自己的 dsh-acp-demo 子进程(一个进程只跑一轮,不复用你正在对话的那个 dsh),而那个子进程在你给它一个可加载的 composition 之前会 fail closed,报 invalid_config。从源码看,DshAcpClient._spawn_argv(src/ouroboros/providers/dsh_acp_client.py)在 config_path 缺失或非绝对路径时都会直接抛 invalid_config 错误——这是 fail-closed 的具体实现。

3.2 步骤 1:获取 ACP server 二进制

从源码构建 DeepSeek Harness(pnpm install && pnpm run build,Node.js >= 22),并让它的 dsh-acp-demo bin 可达——放进 PATH,或者用 OUROBOROS_DSH_CLI_PATH / orchestrator.dsh_cli_path 指名。安装已发布的 @deepseek-ai/dsh-acp-demo 包目前仍会在它自己的 dsh-tool-bash 依赖链上遇到 peer-dependency 冲突,所以源码构建是当前可用的路径。仓库的 spawn 失败提示(_spawn_failure_hint)也指向同一结论:从源码在已验证提交构建(pnpm install && pnpm run build,Node.js >= 22),再把 bin 放入 PATH 或设置 OUROBOROS_DSH_CLI_PATH。

3.3 步骤 2:指向一个 composition

export OUROBOROS_DSH_CONFIG_PATH=/absolute/path/to/cordis.yml

客户端强制或继承的两条规则:

  • 只接受绝对路径。 相对路径会被有意拒绝——它会相对于不可信的项目 cwd 解析,而 composition 决定 Node 进程加载哪些插件,这等于代码执行。源码中 _spawn_argv 对非绝对路径显式抛错,注释写明“相对路径可能相对不可信的项目 cwd 解析”。
  • 它必须位于 dsh 的 node_modules(或 workspace)可达的地方。 composition 里的插件包名相对于 composition 文件自身的目录解析。

OUROBOROS_DSH_CLI_PATH 和 OUROBOROS_DSH_CONFIG_PATH 都在项目 .env 的拒绝清单(denylist)上(见 src/ouroboros/config/untrusted_env.py),原因相同:被 checkout 的仓库不得重定向 Ouroboros 要加载哪个可执行文件或插件树。请在你的 shell 里或 ~/.ouroboros/config.yaml 里设置它们。

3.4 步骤 3:提供 composition 里指名的凭据

通常是 DEEPSEEK_API_KEY。被拉起的子进程继承你的环境,减去 Ouroboros 的选择器变量(OUROBOROS_AGENT_RUNTIME、OUROBOROS_LLM_BACKEND、OUROBOROS_RUNTIME、OUROCODE_MODEL),这样 dsh 里嵌套的 ooo 就不会搞混自己在用哪个后端;dsh 自身的 DEEPSEEK_API_KEY(或 composition 指名的其他凭据)则从环境中读取。

3.5 步骤 4:选择后端

ouroboros mcp serve --runtime claude-cli --llm-backend dsh
# or
export OUROBOROS_LLM_BACKEND=dsh

这里 --runtime 不是可选项。dsh 只回答纯 LLM 的调用,所以执行 runtime 仍然是另一个独立选择——而 MCP 2 server 会拒绝 SDK 支持的 claude / claude-sdk 默认值,所以要指定一个可执行的(claude-cli、codex、opencode……)。

或者持久化到 ~/.ouroboros/config.yaml:

llm:
  backend: dsh
orchestrator:
  dsh_cli_path: /absolute/path/to/dsh-acp-demo
  dsh_config_path: /absolute/path/to/cordis.yml

dsh_cli_path / dsh_config_path 这两个配置键在 src/ouroboros/config/models.py 中有定义,并由 src/ouroboros/providers/factory.py 的 _create_dsh_adapter 读取后传入 DshLLMAdapter。

3.6 别名 deepseek_harness:运行时才接受

deepseek_harness 作为 dsh 的别名,只在运行时解析后端名的地方被接受——OUROBOROS_LLM_BACKEND=deepseek_harness 和编程方式 create_llm_adapter(backend="deepseek_harness")。类型化表面会拒绝它:--llm-backend deepseek_harness 过不了参数校验,llm.backend: deepseek_harness 过不了配置校验。在 CLI 和 config.yaml 里请写 dsh。这与后端能力表中的定义一致:dsh 的别名是 deepseek_harness,CLI 名是 dsh-acp-demo,CLI 配置键是 dsh_cli_path。

3.7 模型选择:composition 说了算

ACP 线上不携带模型参数——Cordis composition 拥有 provider 和模型。Ouroboros 如实报告 dsh-composition 哨兵值(sentinel),而不是编造一个模型名,并且因为协议不返回用量计数而报告零 token 用量。要换模型,就改 composition。

源码把这一纪律落实得很彻底:DshLLMAdapter(src/ouroboros/providers/dsh_llm_adapter.py)中 _COMPOSITION_MODEL = "dsh-composition",注释明确写道“composition 文件拥有真正的 provider/model 选择,而 ACP 线上从不回显它,任何更具体的值都是编造的审计元数据”;UsageInfo 三个 token 计数全部为零;reasoning_effort 与采样参数在 ACP 上没有对应物,被有意忽略。

值得了解的实现细节还有:

  • 超时兜底:工厂的默认签名会传 timeout=None,但 DshLLMAdapter 会把它合并为 600 秒的每轮墙钟超时,避免卡死的 dsh 轮次在持有子进程的情况下无限挂起;startup_timeout 默认 30 秒,用于 initialize/session/new 握手。
  • 结构化工件:dsh 后端不原生支持 response_format,结构化响应通过“提示词指令 + 适配器侧 JSON 提取与校验”协作达成(_STRUCTURED_RESPONSE_ATTEMPTS = 3 次尝试),无法符合则返回格式错误。
  • ACP 协议细节:session/new 必须携带 mcpServers 字段(dsh 的 server 无条件索引 params.mcpServers.length,拒绝非空列表),所以总是发送空列表;stdout 是纯协议 JSON-RPC,诊断信息走 stderr。
  • 空响应 fail-closed:一轮没有产出任何文本视为失败轮次,返回 Empty response from dsh,而不是把空字符串当答案交给调用方。
  • finish_reason 翻译:ACP 的 max_tokens / max_turn_requests 被翻译为调用方测试用的 "length" 标记,end_turn → "stop",未知值原样透传以免把新语义静默吞掉。

四、同时使用两者:回环(loopback)

两者可以组合:装上插件,让 dsh 对话可以驱动 Ouroboros;再设置 OUROBOROS_LLM_BACKEND=dsh,让返回的 interview 问题由 DeepSeek 自己的模型撰写。这个回环正是 bundle 显式转发 DEEPSEEK_API_KEY 的原因——没有它,工具列表一切正常,而第一次调用就会失败。

注意,回环会拉起第二个 dsh-acp-demo 进程;它不会复用你正在对话的那个 dsh,所以上面的「获取二进制 → 指向 composition → 提供凭据」三个步骤仍然适用。也正因如此,DEEPSEEK_API_KEY 必须在 dsh 宿主环境里存在,bundle 才会把它显式转发给 ouroboros mcp serve。

一个可参考的排障顺序:装好插件后先确认 dsh --profile <your-profile> --dump-config 里有 # == dsh-ouroboros 层、工具列表正常列出;此时如果没有设置 OUROBOROS_LLM_BACKEND,interview/Seed/QA 仍走 ouroboros setup 的默认后端。真正把后端切到 dsh 后,第一个 interview/Seed/QA 调用才是验证 composition 与凭据是否就绪的试金石——前两步缺失时,工具照样注册和列出,首次调用才会失败。

五、延伸阅读

登录后查看全文
ouroboros