如何把已有的 DeepSeek Harness(dsh)接入 CodeWhale?
如何把已有的 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映射到 DSHread-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-aiadapter 上声明一条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。