DeepSeek Harness 入门指南：从零到运行你的第一个 AI Agent

本教程能教你什么

DeepSeek Harness（dsh）是深度求索推出的开源 AI Agent 平台，基于 Cordis 插件系统构建。说得通俗一点：它能让你指挥一个 AI，在你的电脑上读取文件、修改文件、执行命令，真正帮你干活。

本教程假设你什么都不会——不懂终端、不懂 Node.js、没接触过 AI Agent 都没关系。我们会在用到每个概念之前先把它讲清楚。学完之后，你将跑起来 Harness 的网页界面、配好模型、完成你的第一个 Agent 任务。最后还会介绍命令行（CLI）模式和 Python SDK，供进阶使用。

本篇覆盖哪个版本？ 本教程覆盖 2026 年 8 月发布的公开开发者预览版（0.1.0-rc.5）——与 deepseek.com/harness 和 @deepseek-ai/dsh npm 包相同的代码。

所需时间： 30–45 分钟   难度： 入门

开始前你需要准备

要花钱吗？ 软件本身完全免费开源（MIT 许可证）。你只需要按 AI 用量给模型提供方付费，按 token 计费（token 大致相当于单词的一小部分）。

什么是 "AI Agent"？

普通聊天机器人：你问一句，它答一句。Agent（智能体）更进一步——它能*动手做事*：读文件、改文件、跑命令、联网搜索，把许多小步骤串联起来，完成你用自然语言描述的目标。DeepSeek Harness 就是给模型装上"手"的身体；模型是大脑。

什么是 "模型"？

AI 的"大脑"叫模型。DeepSeek 的模型就是开发这个平台的同一家公司做的。使用模型需要两样东西：API 端点（软件对话的"地址"）和 API 密钥（进入这个地址的"私人密码"，关联你的计费账号）。

什么是 "终端"？

终端（Windows 上叫 PowerShell，macOS 上叫 终端/Terminal，Linux 上叫 Konsole/GNOME 终端等）是一个让你输入命令而不是点击按钮的窗口。本教程的所有安装步骤都在这个窗口里完成。如果没用过，按下面的章节一步一步来。

如何打开终端（手把手教学）

步骤 1：检查 Node.js 是否已安装（没装就装上）

安装 DeepSeek Harness 最快的方式用到一条叫 npx 的命令，它随 Node.js 一起提供。先检查你电脑上有没有 Node.js。

在终端里输入下面这行，按回车：

node --version

• 如果看到类似 v20.x.x 或 v22.x.x 的版本号——说明已安装，跳到步骤 2。
• 如果看到 command not found（Windows 上是 node is not recognized）——说明没安装，继续往下看。

安装 Node.js

前往 nodejs.org，下载 LTS 版本（"长期支持版"，稳妥的推荐选项）。像安装普通程序一样安装：打开下载的文件，一路点"下一步"，保持默认选项即可。装完后，关闭并重新打开终端（让系统识别新装的软件），再运行 node --version 确认。

什么是 Node.js？ Node.js 是一个免费运行时，让你的电脑能运行 JavaScript 程序。很多像 Harness 这样的开发工具都通过它的包管理器 npm 分发。本教程不需要你学 JavaScript——Node.js 只是默默在后台支撑这些工具。

步骤 2：安装并启动网页版（Web UI）

关键的一行来了。在终端中运行：

npx @deepseek-ai/dsh web

什么是 `npx`？ 运行 npx <包名> 时，它会先下载这个包（第一次要花一两分钟）再运行它。所以这一行命令=下载 DeepSeek Harness + 启动它。

会发生什么： 你会看到一些日志文字，其中一行类似：

DeepSeek Harness is running at: http://127.0.0.1:3080

这个 http://127.0.0.1:3080 就是 Harness 网页界面在你电脑本机的地址。这个终端窗口不能关——只要窗口还开着，服务就一直在运行。

然后用浏览器（Chrome、Edge、Safari…）打开这个地址：http://127.0.0.1:3080，你会看到 DeepSeek Harness 的欢迎界面。

`127.0.0.1` 是什么意思？ 它是"本机"的通用地址——相当于你自己电脑的电话号码。:3080 是端口号，相当于分机号。这个地址只在你机器上有效，别人访问不到。

另一种方式：从源码运行

想要最新代码，可以克隆 GitHub 仓库自己构建（需要 pnpm——npm 的更快的兄弟）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

步骤 3：获取 DeepSeek API 密钥（如果还没有）

要让 Harness 能跟真正的模型对话，你需要一个密钥。密钥是一长串秘密字符——可以理解为 AI 用量的密码。

1. 1打开 platform.deepseek.com（DeepSeek 开发者开放平台），登录或注册账号。
2. 2在账号里找到 API Keys（API 密钥）页面。
3. 3点击创建 API key，复制密钥，存到安全的地方——离开这个页面后你就再也看不到完整密钥了。

请保管好这个密钥。任何人拿到它，都能消耗你的额度（大多数情况下就是你的钱）。

步骤 4：在网页界面里配置模型

Web UI 启动时默认没有配置任何模型。模型变更会在下一次请求时生效——无需重启服务。

1. 1在 Harness 网页界面（http://127.0.0.1:3080）中，打开设置 → 模型。
2. 2找到 DeepSeek 卡片，把 DeepSeek API 密钥粘贴进去。
3. 3点击保存。

DeepSeek 路由立即可用。

出于安全考虑，密钥是只写存储的：保存后界面上只会看到脱敏的展示形式，真正的密钥存放在 $DSH_HOME/.credentials.yaml（你主目录下的私有文件）里，设置里只有它的引用。

添加其他提供方

你也可以用别家公司的模型（比如 Anthropic、OpenAI）：

• 目录提供方 — 点击添加提供方，从已安装目录中选择 Anthropic、OpenAI 等。端点、协议和模型列表都预置好了。
• 自定义提供方 — 点击添加自定义提供方，用于公司网关、自建服务器或任意 OpenAI 兼容端点。需要提供小写的 Provider ID（永久性标识——请求、已保存会话、模型默认值和凭据引用都会使用它）、基础 URL、API 协议、凭据，以及至少一个模型。保存前可以点获取可用模型来探测端点。

原生认证提供方 — Bedrock、Vertex、Azure 和 Codex 各自需要原生凭据（AWS 密钥+区域、ADC 项目、api-version、OAuth）。只往通用字段里填 API 密钥是没有用的。

自定义提供方下的视觉模型

手动录入的模型在自我声明之前一律按纯文本对待。要在自定义提供方上声明图片支持，编辑 $DSH_HOME/settings.yaml：

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，只作用于该模型。要为整个路由设置回退值，在提供方层级使用 defaultInput: [text, image]。DeepSeek 自身的 chat-completions 路由是纯文本的，无法通过配置改变。

步骤 5：选择工作区

新启动的 Web UI 默认没有选中任何工作区——在你选定之前，输入任务消息的输入框是禁用状态。

什么是"工作区"？ 就是允许 Agent 触碰的电脑文件夹。文件夹里的一切——文件、代码、文档——Agent 都可以读取、修改、执行。选一个你信任的项目文件夹即可，别选整个电脑。

1. 1在界面中点击选择工作区。
2. 2添加你启动 dsh 时所在的项目目录。
3. 3选中它。

这时输入框亮起，可以开工了。

步骤 6：运行你的第一个 Agent 任务

1. 1点击启动会话（或直接使用消息输入框）。
2. 2发送一个提示词。对一个全新的项目文件夹，一个不错的起步任务：

> Summarize this repository and identify its main packages.

（如果文件夹是空的或不是项目，可以试试：*新建一个叫 hello.txt 的文件，里面写上 "Hello from DeepSeek Harness!"*）

1. 1观察 Agent 工作。它可以：

• 读取和编辑工作区文件
• 运行 Shell 命令（通过持久化的 Bash 进程）
• 委派工作给子 Agent
• 执行过程中维护计划

在当前权限策略下，Web UI 会在任何需要审批的操作（例如删除文件或安装包）之前先询问你。这是正常的设计，逐个点允许即可。

四种 Agent 模式

用会话输入框的模式选择器来切换 Agent 的行为方式：

Trajectory 视图

每一次模型交互——系统提示、思维链、工具调用与结果、子 Agent 调度、上下文注入——都会以仅追加事件流形式记录在会话日志中。Trajectory 视图让你可以按来源查看整个过程，同一份日志还支撑恢复、分叉、检索和完整回放。想搞清楚 Agent 到底做了什么、为什么这么做，就看它。

步骤 7：进阶——Headless CLI

除了图形界面，dsh 还提供 headless（无头）入口模式，适合脚本和 CI：一条命令从头到尾跑完一个任务，不需要浏览器，打印最终回答后退出：

dsh --profile headless "Inspect the repository and fix the failing tests."

headless 配置文件在首次使用时从随附模板自动初始化。

启动器共支持四种入口模式：

什么是"配置文件（profile）"？ 一份命名好的配置：用哪些插件、哪些模型、什么设置。配置文件目录包含 package.json（树外插件依赖 + dsh.profile 清单）和 cordis.patch.yml（你自己的补丁层）。组合树的合并顺序：

1. 1按 dsh.profile.bundles 顺序合并每个 bundle 的补丁
2. 2合并配置文件的 cordis.patch.yml
3. 3合并 $DSH_HOME/cordis.patch.yml
4. 4叠加 --patch

用 --dump-default-config 和 --dump-config 可以在不启动的情况下检查组合树。

步骤 8：Python SDK（给会写 Python 的人）

如果你写 Python，想把 Agent 嵌入自己的程序，DeepSeek 发布了官方 Python SDK。

前置条件

• Python 3.10 或更新版本
• Linux x64/arm64，或 macOS 14+（arm64）
• Git（获取示例代码）

安装

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——无需系统级 Node.js。

设置凭据

export DEEPSEEK_API_KEY="sk-…"
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1     # 使用代理时
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

运行内置示例

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-root 目录下会生成 JSONL 日志，包含组装好的模型请求和工具调用。

在自己的程序中使用 SDK

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)

DeepSeekHarness 会按需启动捆绑的运行时，并在上下文管理器退出前一直复用。复用同一个 harness 且同一个 session id 时，会保留会话专属的 Bash 进程、工作目录、导出的变量和 Shell 函数。独立任务用全新的 session id；只有希望延续同一持久会话时才复用 id。

理解示例组合

注意：这个示例组合省略了 Harness 身份、工作区提示文本、技能、一次性 Bash、任务工具、压缩以及所有其他面向模型的插件。它使用 danger-full-access，所以只能在一次性 clone 或容器内运行。持久 PTY 后端需要 POSIX 终端基础，因此该组合不支持 Windows Agent。

常见问题排查

下一步

• 添加更多提供方 — 在「设置 → 模型」中接入 Bedrock、Vertex、Azure、Codex 及任意 OpenAI 兼容网关
• 开发插件 — docs/user/develop/basic/ 教你编写自己的 Cordis 插件
• Python SDK 参考 — python/sdk/README.md 覆盖生命周期、结果、通知、运行时选择与配置
• Cordis 入门 — docs/cordis-primer.md 解释 Harness 核心的组合语法

总结

你从零开始，跑起了属于自己的 AI Agent。在本教程中你：

1. 1弄清了终端、Node.js、API 密钥、模型、Agent 到底是什么
2. 2通过 npx（或源码）安装了 dsh
3. 3创建了 DeepSeek API 密钥，并在「设置 → 模型」中配置好
4. 4为 Agent 选择了一个工作区
5. 5在会话中运行了第一个 Agent 任务
6. 6探索了四种 Agent 模式与 Trajectory 视图
7. 7通过 CLI 运行了一次 headless 会话
8. 8安装并使用了 Python SDK

DeepSeek Harness 的一切都是插件——而且全部 MIT 许可、完全免费。欢迎来到 Agent 的世界。