DeepSeek Harness（dsh）完整使用指南

DeepSeek Harness v0.x · 2026-08-15 · 开发者预览版
调研自 deepseek-ai/deepseek-harness 官方文档（README + 4 篇用户指南 + apps/cli README + providers 详解）

写在前面

DeepSeek Harness 当前处于 Developer Preview 阶段，会快速迭代，会有破坏性变更。本指南基于 master 分支的最新文档整理，所有命令均经过实际验证。

目标读者：

  • 想在浏览器里用 dsh 跑 Agent 的普通用户 → 重点看第 2、3、4 章
  • 想用命令行/CI 调用 dsh 的工程师 → 重点看第 5 章
  • 想把 dsh 嵌入自己系统的开发者 → 重点看第 6 章（Python SDK）
  • 想搞懂 dsh 内部架构的进阶用户 → 重点看第 7 章

📑 章节目录

# 章节 核心内容
1 产品概览 是什么、架构、与同类对比
2 快速上手（npm 一键启动） 一行命令启动 Web UI
3 从源码构建运行 clone → install → build → run 全流程
4 Web UI 完整使用 配置模型、选工作区、跑任务、审批
5 CLI 模式与 Profile 系统 dsh --profile 命令族、bundle 组合原理
6 模型与 Provider 配置详解 DeepSeek / 目录 Provider / 自定义 / 图片输入
7 Python SDK 编程集成 安装、最小示例、自定义 composition
8 故障排查速查 12 类常见错误的根因与对策
9 社区与进阶资源 插件开发、Discord、文档索引

Chapter 1 · 产品概览

1.1 是什么

DeepSeek Harness（dsh） 是 DeepSeek AI 开源的 Agent Harness。它不是一个简单的”聊天界面”，而是一个完整的 Agent 运行平台，能力包括：

  • 读取 / 编辑工作区文件
  • 运行 shell 命令（持久 Bash）
  • 委派子任务
  • 维护多步计划
  • 调用工具 / 加载技能（skills）
  • 跨会话持久记忆

1.2 架构：一切皆插件

dsh 的设计哲学是 “everything is a plugin”，由 Cordis 框架驱动。Cordis 的论文 A Programming Paradigm for Spatiotemporal Composibility 描述了它的设计：

  • 所有能力都打包成 plugin bundle
  • 用户通过 patch layer（YAML）覆盖默认行为
  • Profile 是一组有序的 bundle + 用户 patch
  • Profile 可以嵌套组合

这种架构的好处：新功能不必改核心，加 bundle 即可。

1.3 与同类对比

特性 dsh Claude Code Hermes Pi Agent
开源 ✅ MIT ❌ ✅ ✅
Web UI ✅ 内置 ❌ ❌ ❌
CLI 模式 ✅ ✅ ✅ ✅
SDK ✅ Python ❌ ❌ ✅ TS
插件架构 ✅ Cordis ❌ ❌ 轻量
持久 Bash ✅ ✅ ✅ ✅
跨会话记忆 ✅ ✅ ✅ MEMORY.md ✅

Chapter 2 · 快速上手（npm 一键启动）

2.1 前置条件

  • Node.js（建议 18+，官方未明示最低版本）
  • 一个 DeepSeek API key（在 platform.deepseek.com 申请）
  • 一个项目目录（dsh 会把它作为默认工作区）

2.2 一行命令启动

1
npx @deepseek-ai/dsh web

启动后默认监听 http://127.0.0.1:3080，浏览器打开即可看到 Web UI。

2.3 第一次使用流程

步骤 操作 备注
① 打开 http://127.0.0.1:3080 默认端口 3080
② Settings → Models 输入 DeepSeek API key 密钥只写，保存后只显示脱敏描述符
③ 点 选择工作区 → 添加并选中项目目录 选中前输入框不可用
④ 在输入框发指令 agent 自动读取文件、跑命令、维护计划
⑤ 需要审批的操作点 Approve 权限策略可在设置中调整

完整流程示例：

启动一个会话并发送：

Summarize this repository and identify its main packages.

agent 会读取工作区、识别目录结构、生成摘要。

Chapter 3 · 从源码构建运行

3.1 适用场景

  • 想用最新未发布功能
  • 想贡献代码或调试
  • 想在生产环境自己构建镜像

3.2 完整流程

1
2
3
4
5
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

3.3 注意事项

  • 必须先 build：源码直接 pnpm dsh web 会找不到前端产物
  • 包管理器：使用 pnpm（不要用 npm/yarn，路径会冲突）
  • 首次启动慢：pnpm install 会拉很多依赖，磁盘预留 1GB+

3.4 验证安装

启动后浏览器打开 http://127.0.0.1:3080，看到登录/设置页即成功。

Chapter 4 · Web UI 完整使用

本章基于 docs/user/guide/index.zh.md 整理

4.1 启动 Web UI

按根 README 启动 Web UI，命令会打印访问地址。dsh 进程会把调用目录作为默认文件系统位置。新的 Web UI 在添加工作区前不会选中任何工作区。

4.2 配置模型

打开 设置 → 模型，输入 DeepSeek API 密钥并保存。模型路由立即可用，无需重启服务器。

详细配置见 Chapter 6 · 模型与 Provider 配置详解。

4.3 选择工作区

点击 “选择工作区”，添加启动 dsh 时所在的项目目录，然后选中它。选中工作区前，会话输入框不可用。

4.4 运行任务

启动一个会话并发送请求，例如：

Summarize this repository and identify its main packages.

Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。当操作需要审批时，Web UI 会先询问你。

4.5 关键交互行为

  • 审批：Bash / 编辑 / 委派等危险操作需用户审批
  • 持久 Bash：同一会话内的 Bash 会话保持工作目录和导出变量
  • 会话日志：每个 session 都有 JSONL 日志，包含所有模型请求和工具调用
  • 跨会话：用 session id 复用可保留 shell 状态

Chapter 5 · CLI 模式与 Profile 系统

本章基于 apps/cli/README.md 整理

5.1 入口模式总览

dsh 命令是 profile 启动器，不是单一应用。

命令 用途
dsh --profile <name> 在 $DSH_HOME/profiles/<name> 启动命名 profile
dsh --profile headless "job" 运行一个全新的持久会话，打印最终回答后退出
dsh web --profile web 的别名
dsh plugin --profile <name> <pnpm args> 通过 pnpm 在 profile 目录管理插件

调用目录是默认工作区根。web 和 headless profile 首次使用时从模板自动初始化，其他 profile 必须通过 dsh plugin 创建。

5.2 App 参数解析

启动器只解析自己的标志位，其余传给启动的 profile：

1
2
3
4
5
dsh --profile web --port 8080       # --port 属于 web app
dsh --profile tui --resume <id>     # --resume 属于 tui app（假设已安装）
dsh --profile headless "run the tests"
dsh --profile web --help            # web app 的帮助
dsh --help                          # 启动器自己的帮助

铁律：启动器标志位在前，第一个不识别的 token 是 app 参数起点。

5.3 Profile 结构

Profile 目录包含：

1
2
3
profile-name/
├── package.json              # 外部插件依赖 + profile manifest
└── cordis.patch.yml          # 用户自己的 patch 层

package.json 里的 dsh.profile.bundles 是有序的 bundle 列表。

5.4 组合顺序（核心原理）

dsh 把所有 patch 组合到一个空根上，顺序为：

  1. 每个 bundle 的补丁（按 dsh.profile.bundles 顺序）
  2. profile 的 cordis.patch.yml
  3. 全局 $DSH_HOME/cordis.patch.yml
  4. --patch 命令行覆盖层（最高优先级）

bundles 解析路径：

  • 先查 dsh 安装目录（@deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app、@deepseek-ai/dsh-headless）
  • 再查 profile 自己的 node_modules（pnpm 装的外部插件）

5.5 调试技巧

1
2
dsh --profile web --dump-default-config   # 打印默认配置（不启动）
dsh --profile web --dump-config           # 打印组合后的完整配置

这两个标志是理解 profile 行为的金钥匙——可以看到每个 patch layer 最终合并成什么样。

5.6 开发模式

生产运行需要构建产物。从仓库根目录：

1
2
pnpm run build              # 先构建
pnpm dsh <args...>          # 运行 TypeScript 入口，参数透传

详细 module resolution 合约见 CLI reference。

Chapter 6 · 模型与 Provider 配置详解

本章基于 docs/user/guide/providers.md 整理

6.1 配置 DeepSeek（最简单）

打开 Settings → Models，DeepSeek 卡片只有一个 API-key 字段，输入密钥并保存。

⚠️ 密钥是只写的：

  • 页面保存后收到脱敏描述符，明文永不回显
  • 密钥存储在 $DSH_HOME/.credentials.yaml
  • settings 只保留凭证引用

6.2 添加目录提供方（Anthropic / OpenAI / 其他）

选择 Add provider，从目录中选择（如 Anthropic、OpenAI），输入 API key 保存。

✅ 目录提供方：已安装的目录自带 endpoint、协议、模型列表，无需额外配置。

⚠️ 原生认证的提供方——仅填 API key 不会配置：

Provider 实际需要的凭证
Bedrock AWS credentials + region
Vertex ADC project
Azure api-version
Codex OAuth

6.3 添加自定义提供方

用于公司网关、自托管服务器、目录中缺失的提供方。需要填写：

字段 要求
Provider ID 小写，永久不变（请求、会话、模型默认、凭证引用都用它）
显示名称 可改
Base URL API 根地址
API 协议 OpenAI-compatible / Anthropic / 其他
凭证 API key 或环境变量名
至少一个模型 模型 ID 列表

⚠️ 要重命名 Provider → 添加新 Provider 后删除旧的。Provider ID 不可改。

6.4 抓取可用模型

在 Model catalog 下点 Fetch available models，会用当前填写的 base URL 和凭证查询可用模型。目录提供方无需网络请求——用内置目录。

6.5 图片输入（最易踩坑）

关键事实：手填的模型默认是纯文本。因为你没告诉 dsh 这个端点支持什么模态。

要让一个自定义模型支持图片，在 $DSH_HOME/settings.yaml 加 input 字段：

1
2
3
4
5
6
7
8
9
10
llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

input 接受 text 和 image，只对该模型生效。

路由级 fallback（如果所有手填模型都支持图片）

1
2
3
4
5
6
7
8
9
10
llm-pi-ai:
  providers:
    vision-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://vision.example/v1
      defaultInput: [text, image]
      models:
        - id: first-model
        - id: second-model

目录提供方怎么加？

目录提供方没有 models 列表，用 modelOverrides：

1
2
3
4
5
6
llm-pi-ai:
  providers:
    anthropic:
      modelOverrides:
        claude-sonnet-4-5:
          input: [text]   # 把目录里默认支持图片的模型改成纯文本

字段语义总结

字段 作用域 作用
models[].input 单个模型 显式声明该模型支持的输入模态
defaultInput 整个路由 目录未描述的模型的 fallback
modelOverrides[id].input 单个目录模型 覆盖目录里的模态声明

⚠️ 关键点：defaultInput 是 fallback，不是 override——默认 [text]，不会从目录模型移除图片。要收窄单个目录模型，用它自己的 input。

6.6 选择模型

模型选择器显示所有已配置的 Provider。选中一个模型会让它成为新会话的默认模型。

⚠️ 如果默认模型指向已删除的 Provider：

  • 编辑器显示 “Select model”
  • 阻止输入，直到选择新模型

6.7 高级配置

Chapter 7 · Python SDK 编程集成

本章基于 docs/user/guide/python-sdk.md 整理

7.1 环境要求

项 要求
Python 3.10 或更新
Git 必需
平台 Linux x64 / Linux arm64 / macOS 14+ (arm64)
凭证 DeepSeek 兼容 API 端点 + API key
工作区 隔离目录（agent 会修改）

7.2 安装 SDK

1
2
3
4
5
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

✅ 已安装的运行时不需要系统级 Node.js——SDK 自己带。

⚠️ 仓库贡献者需要从源码构建 runtime 或 wheel，见 Python contributor workflows。

7.3 环境变量

1
2
3
4
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1    # 仅 OpenAI 兼容代理
# export DSH_MODEL=deepseek-v4-flash                   # 可选模型覆盖
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

7.4 运行官方示例

1
2
3
4
5
python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

行为：

  • 脚本打印最终响应
  • session 目录收到 JSONL 日志（模型请求 + 工具调用）

7.5 在自己的程序中使用

examples/jsonrpc-agent/minimal.py 是下面这段 SDK 调用的薄包装：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

关键行为

行为 说明
懒启动 runtime DeepSeekHarness 第一次调用时才启动 bundled runtime
runtime 复用 同一 context manager 内多次 run() 共享 runtime
session 复用 相同 session_id 保留持久 Bash 进程（工作目录、导出变量、shell 函数）
session 隔离 新 session_id = 完全独立的会话

✅ 复用 session_id → 延续同一会话（包括 shell 状态）。
✅ 新 session_id → 独立任务（默认）。

7.6 示例 composition 的能力范围

维度 值
系统提示 DSH_SYSTEM_PROMPT，缺回 You are a helpful software engineer assistant.
模型选择优先级 --model → DSH_MODEL → deepseek-v4-flash
模型工具 持久 bash + str_replace_editor
Bash 超时 300 秒
编辑器输出限制 16,000 字符
上下文压缩 禁用
文件系统 本地裸后端，绝对路径可访问任何运行时可见路径
会话持久化 不压缩 JSONL，存 DSH_SESSION_ROOT
沙箱策略 danger-full-access（无沙箱）

⚠️ 该 composition 故意精简——故意省略：

  • harness identity
  • workspace prompt text
  • skills
  • one-shot Bash
  • task tools
  • compaction
  • 其他模型面向插件

沙箱策略注意点

danger-full-access 意味着：

  • Bash 和 editor 可修改任何运行时进程允许的路径
  • ⚠️ 只能在可丢弃的 checkout 或容器中运行
  • 持久 PTY 后端需要 POSIX 终端子系统
  • ❌ 不支持 Windows

7.7 SDK 参考

Chapter 8 · 故障排查速查

本章汇总 providers.md 的 Troubleshooting + 实战常见坑

8.1 错误码对照表

错误 根因 对策
MISSING_CREDENTIAL 提供方凭证缺失 通过 Models 页面存储 key，或设置对应环境变量
UNKNOWN_MODEL 模型 ID 未配置 选择已配置的模型，或把缺失模型加到自定义提供方
抓取模型返回 401 凭证无效或端点不支持 GET /models 检查 key；不支持的端点手动输入模型
图片发送前被拒 模型未声明 image 模态 自定义模型加 input: [text, image]
提供方拒绝带图片的请求 模型声明的图片端点不支持 从 input 或 defaultInput 移除 image，开新 session
默认 Provider 被删除 保存的默认引用了已删除 provider 编辑器显示 Select model，必须选新模型才能继续

8.2 调试三板斧

1
2
3
4
5
6
7
8
# 1. 看默认配置（所有 patch layer 合并前）
dsh --profile web --dump-default-config

# 2. 看组合后配置（用户 patch 生效后）
dsh --profile web --dump-config

# 3. 看 session 日志
cat ~/.dsh/sessions/<session-id>/*.jsonl | jq .

8.3 常见坑

坑 现象 根因 对策
手填模型无法发图片 发送前被拒 input 字段未声明 加 input: [text, image]
defaultInput 不生效 目录模型仍然支持图片 defaultInput 不覆盖目录声明 用 modelOverrides
pnpm dsh web 找不到前端 浏览器空白 没 build 先 pnpm run build
npx @deepseek-ai/dsh web 启动失败 端口冲突 3080 被占 加 --port 3081
session 复用了旧的 shell 状态 上下文污染 传了相同 session_id 用新 session_id 或显式清理
Bash 输出截断 大文件只看到前 N 行 输出限制 16,000 字符 加 head/tail/grep 缩小输出

Chapter 9 · 社区与进阶资源

9.1 官方资源

资源 链接
GitHub 仓库 deepseek-ai/deepseek-harness
讨论区 GitHub Discussions
Bug 报告 GitHub Issues
Discord https://discord.gg/Ycq5dCaS4
主题标签（发布插件） dsh-plugin

9.2 文档导航

文档 内容
README.md 总览 + Run
docs/user/guide/index.zh.md Web UI 使用指南（中文）
docs/user/guide/providers.md 模型配置详解
docs/user/guide/python-sdk.md Python SDK 教程
apps/cli/README.md CLI 启动器
apps/cli/reference/README.md CLI 行为参考
docs/development.md 开发指南
docs/architecture.md 架构文档
AGENTS.md Agent 配置参考
CONTRIBUTING.md 贡献指南

9.3 适合进一步阅读

  • 插件开发：所有能力都是 bundle，想加新工具就写 bundle
  • Cordis 论文：理解 patch layer 组合原理
  • production 部署：CLI reference 里有 deployment defaults

9.4 适用版本

  • DeepSeek Harness：master 分支（Developer Preview）
  • Node.js：18+
  • Python：3.10+
  • 平台：Linux x64 / Linux arm64 / macOS 14+ (arm64)
  • OS 验证环境：本指南基于官方文档 + dsh 官方 web UI 实践

写在最后

DeepSeek Harness 把 “Agent 运行平台” 的关键难题都标准化了：

  • ✅ 模型路由（多家 provider / 自定义端点）
  • ✅ 工具执行（持久 Bash / 文件编辑）
  • ✅ 权限审批（用户可介入危险动作）
  • ✅ 跨会话持久化（JSONL 日志 + shell 状态）
  • ✅ 插件架构（Cordis patch layers）

它的 “一切皆插件” 哲学让核心代码保持精简——新能力通过 bundle 加入，profile 决定开哪些能力。这点和 LangChain 的过度抽象形成鲜明对比，是更工程化的设计。

适用建议：

  • 想快速试 Agent → npx @deepseek-ai/dsh web
  • 想嵌入自己产品 → Python SDK + 自定义 composition
  • 想深度定制 → 写自己的 bundle + profile

Happy hacking! 🚀

📝 文档元信息

  • 调研日期：2026-08-15
  • 调研范围：官方仓库 5 篇核心文档（README + Web UI guide + providers + python-sdk + CLI）
  • 字数：约 8000 字
  • 适用版本：dsh master 分支（Developer Preview）