如何把已有的 DeepSeek Harness(dsh)接入 CodeWhale?

原创2026-09-09 21:19:241,814 阅读
文章标签:人工智能AI Agent代码智能体CLI开发工具工具调用MCP ClientsAgent 编排AI 技能Agent 沙箱本地部署

如何把已有的 DeepSeek Harness(dsh)接入 CodeWhale?

如果你已经在终端里装了官方 DeepSeek Harness(dsh,npm 包 @deepseek-ai/dsh),并且希望让它跑在 CodeWhale 选定的 provider 路由和模型上,而不是维护两套配置,codewhale integrations dsh … 这条命令路径可以把两者接起来。接入后,DSH 保持一个完整的 harness 表面,CodeWhale 继续持有 Fleet 配置、provider/model 选择、权限、凭据和生命周期;DSH 不会变成第二个调度器,也不是任何权限旁路。整个过程对 $DSH_HOME 只读:CodeWhhale 只在 $CODEWHALE_HOME/integrations/dsh/ 下写入 overlay 和回执文件,你自己的凭据、会话和 profile 全部保留在你手上。

前提条件

  • 已经通过 npm 全局安装了官方 @deepseek-ai/dsh,且 dsh 在 PATH 上。检测是只读的(dsh --version / dsh --help),不会初始化任何 profile。
  • 版本兼容性:该集成对照 dsh 0.1.0-rc.6(写作时的最新已发布版本)验证。dsh 是开发者预览版,文档明确警告会有兼容性破坏性变更:
    • 比 0.1.0-rc.6 更新的版本:报告为 stale-version,可以启动,但未经验证;
    • 更老的版本,或 --patch 参数不被支持的版本:报告为 incompatible,启动被拒绝。
  • 你不需要提前准备 API key 给 CodeWhale:DSH 自己解析自己的凭据,CodeWhhale 不读取、不复制 $DSH_HOME 里的任何密钥值(它只检查 .credentials.yaml 是否存在且权限为 0600)。

第一步:确认当前状态

codewhale integrations dsh status [--json]

status 没有任何副作用,输出当前状态。状态机如下,它决定了你下一步该做什么:

状态 含义 能否启动
not-installed dsh 不在 PATH 上 拒绝
offline dsh 存在但 --version 失败 拒绝
incompatible 早于 0.1.0-rc.6 或不支持 --patch 拒绝
detected 有可用的 dsh,但没有 Codewhale overlay 拒绝(先 connect)
connected overlay 与当前 Codewhale 路由一致 允许
stale-config 路由变更、overlay 被外部修改或缺失 拒绝(需要 update)
stale-version 已连接,但 dsh 版本比已验证版本新 允许,未验证
disabled overlay 保留,但启动被拒 拒绝(需要 enable)

如果 status 是 detected,说明检测到了 dsh 但还没写入 overlay,进入下一步。status、plan、TUI 里的 /setup tools(Tools and MCP 步骤)和 codewhale doctor 都是无副作用的,可以随便跑。

第二步:预览连接计划

codewhale integrations dsh plan [--profile web|headless] [--allow-full-access] [--skin] [--json]

plan 打印精确的计划:要写的文件、映射的身份、权限模式、披露说明以及 overlay 全文。计划中有几项披露需要留意:

  • 用户侧 settings.yaml 的遮蔽风险:DSH 会把用户 settings.yaml 里的 agent-default-model、llm-deepseek、llm-pi-ai 段落按字段叠在 overlay 之上。如果这些段落存在,DSH 里保存的选择会在其被清除之前盖过 CodeWhale 钉住的模型身份。status/plan 会列出这些段落。
  • base URL 拒绝规则:内嵌凭据(userinfo 或 query/fragment)的 base URL 永远不会被复制进 overlay;此时 plan 会失败,并指明当前 provider/model 和原因。status 在跑 plan 之前就会显示当前路由的可携带性。
  • 权限映射:CodeWhhale 的 read-only 映射到 DSH read-only;其他一律映射为 workspace-write;只有同时给出 --allow-full-access 且 Codewhale 自身处于 full-access 姿态(sandbox_mode = "danger-full-access" / yolo)时才会到 danger-full-access。
  • wire 方言按原样携带:Chat Completions 路由声明 api: openai-completions,OpenAI Responses 路由(例如默认的 deepseek/deepseek-v4-flash)声明 api: openai-responses,Anthropic Messages 路由声明 api: anthropic-messages。推理档位(off|high|max)只在原生 DeepSeek 路由上映射;手工声明的路由不发送 effort 参数。

第三步:执行连接

codewhale integrations dsh connect [--profile web|headless] [--allow-full-access] [--skin] [--yes]

connect 会先打印与 plan 相同的完整计划,然后要求确认;当 stdin 不是终端时加 --yes 跳过确认。成功后 CodeWhale 只写入 $CODEWHALE_HOME/integrations/dsh/ 下的:

  • codewhale.patch.yml — overlay,只含身份:provider 路由、模型、base URL,以及(原生 DeepSeek 路由)reasoningEffort。对每个非原生路由,它在 DSH 的 llm-pi-ai adapter 上声明一条 codewhale-<provider> 路由,api: 写明该路由自己的 wire 方言,apiKeyEnv 只写 provider 规范环境变量的名字(openai-completions、openai-responses 或 anthropic-messages),从不写值。无凭据的本地回环路由(Ollama / LM Studio / vLLM / SGLang)不携带任何凭据引用;
  • receipt.json — 当前连接记录加上 connect / update / disable / enable / remove 事件的追加式历史,含 overlay SHA-256、dsh 版本、$DSH_HOME、映射身份、权限模式和时间戳。每个事件同时追加到 $CODEWHALE_HOME/audit.log(回执机制见 docs/RECEIPTS.md 的说明)。

第四步:启动并验证

codewhale integrations dsh launch [--profile web|headless] [--dry-run] [-- <dsh app args>]

launch 在 CodeWhale 工作区中执行 DSH_PERMISSION_MODE=<mode> dsh --profile <p> --patch <overlay> …,使用你自己的 $DSH_HOME,所以凭据、会话、profile 仍然归你。先用 --dry-run 检查将要执行的调用是安全的验证手段。

接入完成的判断:再跑一次 codewhale integrations dsh status,状态从 detected 变为 connected,且 plan 不再报告路由不一致,说明 overlay 与当前 Codewhale 路由匹配、启动被允许。

路由变更后:update

如果之后你切换了 provider/model 路由,overlay 会过期,status 报 stale-config,此时用:

codewhale integrations dsh update [--profile …] [--allow-full-access] [--skin true|false] [--ocean true|false] [--yes]

update 与 connect 一样先打印计划并要求确认。此外,connect/update 还会顺手删除 0.9.8 时代遗留的 skin/preview 文件(如果存在)。

可选路径:DSH 插件机制(install-bundle)

--patch 是默认路径,因为它只需要 launcher 就能工作。DSH 文档化的插件机制作为显式 opt-in 提供:

codewhale integrations dsh install-bundle [--app web|headless] [--yes]
codewhale integrations dsh remove-bundle [--yes]

这条路径有额外前提:

  • 必须已有连接;
  • pnpm 必须在 PATH 上(dsh 会 shell out 调用它)。没有 pnpm 时 status 显示 plugin path: not available: pnpm missing …,命令直接拒绝。

install-bundle 会在 $CODEWHALE_HOME/integrations/dsh/bundle/ 下物化一个 npm 形态的 bundle 包(package.json、cordis.patch.yml、README 等),然后运行两次文档化的 dsh plugin --profile codewhale add <path>:先是 DSH 自带的 app bundle(@deepseek-ai/dsh-web-app 或 dsh-headless,从已安装的 launcher 链接,不走网络),再是 Codewhale bundle。DSH 会创建专用 profile $DSH_HOME/profiles/codewhale,你原有的 web/headless profile 不受影响。

安装后的验证方式:dsh --profile codewhale 单独一条就携带完整身份,可以用 dsh --profile codewhale --dump-config 核对。此后的 launch 优先走该 profile、不再带 --patch;launch --profile web|headless 仍走 overlay。

这条路径同时承载 CodeWhale skin(调色板与海洋场景,经 ThemeService.overrideTokens 令牌级主题叠加,只作用于 bundle profile)。皮肤默认随 install-bundle 开启;关掉的最小手段依次是:浏览器端 localStorage["codewhale.ocean"] = "off",或 codewhale integrations dsh update --ocean false 重新生成不含场景的 client.js;update --skin false 则整体移除 client 半部。remove-bundle 会运行 dsh plugin --profile codewhale remove codewhale-dsh-bundle 并只删除 CodeWhale 拥有的 bundle 文件;profile 目录本身归 DSH 所有,保留不动。

断开与清理

codewhale integrations dsh disable   # 保留 overlay,拒绝启动
codewhale integrations dsh enable    # 恢复启动
codewhale integrations dsh remove [--yes]

remove 只删除 $CODEWHALE_HOME/integrations/dsh/ 下的 overlay(及 0.9.8 遗留文件),追加一条 remove 回执,从不触碰 $DSH_HOME 或已安装的 @deepseek-ai/dsh 包文件。DSH 在移除后和连接之前完全一样地工作。注意:bundle 安装状态下 remove 会被拒绝,需要先 remove-bundle。

边界:与 external-consent 是两回事

如果目标是让 CodeWhale 直接读取 DSH 里保存的 DEEPSEEK_API_KEY($DSH_HOME/.credentials.yaml),那是另一条机制——codewhale auth external-consent --provider deepseek --mode read-only,授予的是精确路径的只读凭据访问(见 docs/PROVIDERS.md)。它和本文的 harness 集成互不替代:harness 集成两个方向都不碰凭据,只做路由身份的 --patch 覆盖,让 DSH 自己去解析自己的 key。

限制汇总

  • CodeWhhale 永远不写入 $DSH_HOME、不编辑已安装的 @deepseek-ai/dsh 包文件、不复制或打印任何 API key 或环境变量密钥值。
  • DSH 是开发者预览版;高于已验证版本的 stale-version 状态可启动但未验证,低于 0.1.0-rc.6 或不带 --patch 的版本直接被拒。
  • 这不是 CodeWhale 的原生功能:所有界面都会将其标注为 "DeepSeek Harness connected through Codewhale"。

完整的命令参考、状态定义与 overlay 字段说明见 docs/INTEGRATIONS_DSH.md。

登录后查看全文
Codewhale