DeepSeek Harness 集成图灵平台指南

DeepSeek Harness（命令名 dsh）是 DeepSeek 官方开源的 Agent Harness：模型、工具、技能、会话、沙箱、循环、调度、UI 全部以插件形式挂载，可以逐个替换。它提供 Web UI 与 headless CLI 两个入口，模型来源支持任意 OpenAI 兼容端点，因此可以直接对接图灵平台。

模型就用 deepseek-v4-flash-0731

它在图灵上直连 DeepSeek 官方，走 DeepSeek 自家的 KV Cache，长会话命中连贯稳定 —— 实测固定前缀连打 8 发，除首发冷启外逐发稳定命中 99.0%；缓存命中价 ¥0.1，只有输入价的 1/30，正是 Agent 场景的主成本项。详见 推荐模型。

开发者预览版

dsh 目前是 0.1.0-rc.x 开发者预览，官方明确会有不兼容变更。本文的命令、配置字段与报错文案均在 dsh v0.1.0-rc.8 + Node v22.22.2 + 图灵 live 环境实测（2026-08-20），升级后请对照上游文档复核。

前置要求

• 已获得图灵平台 API Key（获取方式）

• macOS / Linux / WSL2

• Node 必须带 node:zlib 的 zstd 支持（dsh 用 zstd 压缩会话记录）。该 API 自 Node v23.8.0 提供并回移到 22.x LTS：实测 v22.22.2 正常，v23.6.0 启动即失败：

  SyntaxError: The requested module 'node:zlib' does not provide an export named 'createZstdDecompress'

• 首次安装要拉 60+ 个 @deepseek-ai/dsh-* 插件包，国内网络建议先把 registry 指到镜像：

  npm config set registry https://registry.npmmirror.com

用 pnpm 装更快

实测同一台机器上 npm i @deepseek-ai/dsh 在依赖树解析阶段卡了十几分钟仍未落盘，换 pnpm add @deepseek-ai/dsh 68 秒装完（503 个包）。npx 走的是 npm，第一次执行慢属于正常现象。

两种接线方式

方式	配置量	可用模型	适用场景
自定义 provider（推荐）	一段 YAML 或一个 UI 表单	图灵上的全部模型	需要显式指定模型、或在多条线路之间切换
覆盖内置 deepseek 路由	两个环境变量	仅 DeepSeek 系模型名	只用 DeepSeek、想最快跑通

两种方式可以共存。

方式一：配置自定义 provider（推荐）

1. 启动 dsh

npx @deepseek-ai/dsh@latest web

Web UI 默认监听 http://127.0.0.1:3080 并自动打开浏览器。dsh 用启动它的当前目录作为默认文件系统位置，建议先 cd 到项目目录再启动。

Web 入口支持的参数（dsh web --help）：

参数	作用
--no-open	只起服务，不自动打开浏览器
--port <port>	换监听端口，传 0 让系统随机分配
--host <host>	换绑定地址
--trusted-host <authority...>	给 /api 的浏览器信任栅栏追加可信来源，可重复

2. 在 UI 里添加图灵 provider

打开 Settings → Models → Add a custom provider，按下表填写：

字段	填写值	说明
Provider ID	turing	小写、字母开头，创建后不可改（会话记录、默认模型、凭据引用都按它索引）
Display name	Turing	仅显示用
Base URL	https://live-turing.cn.llm.tcljd.com/api/v1	图灵中国区地址，见 获取 API Key
API protocol	openai-completions	对应 v1/chat/completions
API key	你的图灵 API Key	保存后只回读脱敏描述，落在 ~/.dsh/.credentials.yaml

保存后模型路由立即可用，不需要重启服务。

图灵支持模型自动拉取

图灵实现了 OpenAI 兼容的 GET /v1/models（实测返回 160+ 个模型 id），UI 里可以直接点自动拉取，不必手抄模型名。列表里没有的模型手填即可，模型 id 以 模型列表 为准。

3. 或直接写配置文件

配置在 $DSH_HOME/settings.yaml（DSH_HOME 默认 ~/.dsh），顶层 key 是插件 id，模型路由归 llm-pi-ai：

llm-pi-ai:
  providers:
    turing:
      displayName: Turing
      api: openai-completions
      baseURL: https://live-turing.cn.llm.tcljd.com/api/v1
      apiKeyEnv: TURING_API_KEY
      models:
        - id: deepseek-v4-flash-0731
        - id: aliyun/deepseek-v4-flash-0731

对应地把 Key 放进环境变量：

echo 'export TURING_API_KEY="your-api-key"' >> ~/.zshrc   # bash 用户改 ~/.bashrc
source ~/.zshrc

不要把明文 Key 写进 settings.yaml

上游推荐用 apiKeyEnv 引用环境变量，或者用 UI 保存（写进 ~/.dsh/.credentials.yaml，只写不读）。settings.yaml 里只应出现引用。

models 里每项的 id 就是发给图灵的模型名，与 模型列表 中的接口模型 ID 完全一致。手填的模型默认按纯文本处理，要传图片必须显式声明 input: [text, image]。

图灵上 deepseek-v4-flash-0731 三个协议都通（实测 v1/chat/completions、v1/responses、v1/messages 均返回 200），所以 api 也可以填 openai-responses 或 anthropic-messages；没有特殊需求就用 openai-completions。

4. 选默认模型并跑第一个任务

1. 在 Settings → Models 里点选一个模型，它会成为新建会话的默认模型（已有会话仍用自己记录的模型）
2. 点 Choose workspace 选一个项目目录 —— 没选 workspace 前会话输入框不可用
3. 提个任务试试，例如「读一遍这个仓库并总结它的结构」

方式二：覆盖内置 deepseek 路由

dsh 自带 deepseek-official 路由，只认两个环境变量，把它们指向图灵即可：

export DEEPSEEK_BASE_URL=https://live-turing.cn.llm.tcljd.com/api/v1
export DEEPSEEK_API_KEY=your-turing-api-key
npx @deepseek-ai/dsh@latest web

不用改任何配置文件。代价是模型名必须落在图灵的 DeepSeek 系 id 上 —— dsh 出厂默认模型是 deepseek-v4-flash，图灵上正好有这个 id，所以配完环境变量可以直接跑（实测 headless 任务正常返回）。要指定 deepseek-v4-flash-0731 这类具体版本，按下一节改默认模型，或在 UI 里选。

headless：跑一次性任务

dsh --profile headless "读一遍 src/ 并列出对外导出的模块"

headless profile 新建一个持久化会话、打印最终答案后退出，适合脚本和 CI。它默认走 deepseek-official 路由，所以要么按方式二配好环境变量，要么把默认模型改到你的 turing provider —— 后者改 profile 的补丁层 $DSH_HOME/profiles/headless/cordis.patch.yml（首次启动 dsh 时自动生成，内容是一个 YAML 数组）：

- id: agent-default-model
  config:
    provider: turing
    model: deepseek-v4-flash-0731

改完用 dsh --profile headless --dump-config 确认补丁已生效（会打印合成后的插件树）。

其余启动参数：

参数	作用
dsh --profile <name>	启动 $DSH_HOME/profiles/<name> 下的 profile；dsh web 是 --profile web 的别名
dsh plugin --profile <name> <pnpm args>	管理某个 profile 的插件（透传给该目录下的 pnpm）
--patch <path>	追加一层配置覆盖，可重复
--dump-config / --dump-default-config	只打印合成后的插件树（含 / 不含用户层），不启动

推荐模型

Agent 场景优先用 deepseek-v4-flash-0731：直连 DeepSeek 官方，输入 ¥3 / 输出 ¥9 / 缓存命中 ¥0.1，1M 上下文，工具调用与思考都支持。

同一份模型快照在图灵上有两条线路，输入/输出单价相同，差别只在缓存命中价与闲时时段：

模型 id	上游	缓存命中价	闲时时段（东八区）
deepseek-v4-flash-0731	DeepSeek 官方直连	¥0.1	忙时只有 09:00-12:00、14:00-18:00，其余全算闲时
aliyun/deepseek-v4-flash-0731	阿里云百炼	¥0.3	22:00 至次日 08:00

官方直连除了命中价更低，长会话的命中也更稳定（见下）；缓存复用率高、或调用集中在白天非高峰时段，走官方直连更省，深夜批量任务两边闲时价一致。完整单价、上下文上限与协议支持以 模型列表 → Deepseek 为准，计费口径见 按时段计费。

缓存命中实测

Agent 每一轮都要把系统提示 + 工具定义 + 完整历史重发一遍，公共前缀极长，缓存命中价才是主成本：¥0.1 只有输入价 ¥3 的 1/30。

在 live 环境上用逐字节相同的 ~6.6k token 固定前缀、单线程、间隔 4s 连打 8 发 deepseek-v4-flash-0731：

第 N 发	prompt_tokens	cached_tokens	命中率
#1	6592	0	0%（冷启）
#2 – #8	6592	6528	99.0%

冷启之后逐发稳定在 99.0%，没有回退也没有锯齿 —— 官方直连线路由 DeepSeek 自家缓存服务，长会话里公共前缀是连贯累积的。同一份快照的百炼线路在同一组测试里命中来得更晚、也吃不满整段前缀，所以缓存敏感的 Agent 场景优先用官方直连那条。

未命中的那 64 个 token 不是误差：实测命中量按块对齐（都是 64 的整数倍），前缀尾部凑不满一块的零头不进缓存。

怎么把命中率吃满

DeepSeek 的上下文缓存默认开启、不需要传任何参数，但它要求整段前缀完整匹配 —— 官方说明里写得很直接：先发过 A + B，再发 A + C 是命不中的。所以能不能吃满命中，取决于你的请求前缀有多稳定：

1. 稳定内容放最前：system prompt、工具定义、AGENTS.md 一类的项目规范、长参考文档，全部排在会话开头且逐字节固定。
2. 易变内容放最后：时间戳、随机 id、当前分支名、每轮都变的检索结果，放在消息尾部。前缀里嵌一个当前时间，等于每轮都把缓存作废。
3. 历史只在尾部追加：不要中途裁剪、重排或改写已有消息。Agent 的上下文压缩（compaction）会重写历史前缀，压缩之后的第一发相当于一次冷启，属于正常现象。
4. 同一会话串行发：并发把同一前缀打散到不同后端实例时，命中会明显滞后。
5. 别指望短会话命中：前缀太短不进缓存（各厂商的起步长度见 提示词缓存），冷启第一发必然 0%。
6. 缓存是尽力而为：官方明确不保证 100% 命中，且缓存在不再使用后几小时到几天会被清空 —— 长时间空闲后回来重新冷启是预期行为，不要按「一定命中」做成本模型。

记账口径以响应里的 usage.prompt_tokens_details.cached_tokens 为准（对应 DeepSeek 官方的 prompt_cache_hit_tokens），不要按估算算钱。上游说明见 DeepSeek KV Cache。

两个容易踩的点

• 上下文上限：dsh 对手填模型按 262144 tokens 估算，而 deepseek-v4-flash-0731 在图灵上是 1M 输入，它不会自动放大 —— 超长会话触发压缩（compaction）的时机会偏早。
• 思考模型：DeepSeek V4 系默认带思考，输出预算先被 reasoning 占用。最大输出设得过小（实测 max_tokens: 16）会出现只有思考、没有正文的响应。

常见问题

报错 / 现象	处理
dsh: MISSING_CREDENTIAL: llm-pi-ai: no credential for provider route "turing"	provider 没拿到 Key：在 Settings → Models 里保存，或让 apiKeyEnv 指向的环境变量在启动 dsh 的那个 shell 里可见
启动即报 does not provide an export named 'createZstdDecompress'	Node 太旧，换带 zstd 支持的版本（见前置要求）
HTTP 401 + API key not exist	Key 与环境不匹配（live 的 Key 不能用于测试网关），或 Key 已失效
Model not exist. / Unknown LLM provider	该模型 id 在当前环境未开通，换用 模型列表 里已上线的 id
Provider ID 想改名	只能新建一个再删旧的；旧会话仍指向旧 ID

参考文档

• DeepSeek Harness 官方文档 - 快速开始与插件开发
• 模型配置参考 - settings.yaml 完整字段
• DeepSeek Harness GitHub
• 图灵平台模型列表
• 提示词缓存 - 各厂商缓存机制与命中判定

返回

← 返回 AI 编程工具概述