DeepSeek Harness 安装与使用指南 —— 一切皆插件的开源 Agent 框架

2026 年 8 月 13 日，DeepSeek 正式发布开发者预览版 DeepSeek Harness（dsh）——官方首个开源 Agent 框架，代码完全公开、MIT 许可证、TypeScript 编写。它的核心理念只有一句话：Everything is a Plugin（一切皆插件）。

模型是大脑，Harness 就是身体。DeepSeek 官方把 Agent 拆成 Agent = Model + Harness：模型负责思考，Harness 负责工具调用、文件读写、命令执行、记忆、调度、UI 这些”身体能力”。而 DeepSeek Harness 的特殊之处在于——身体的每一块都可以自由拆卸、替换、重组，无需改源码，纯靠配置层就能拼出你想要的那个 Agent。

本文带你从零安装、跑通第一个任务，再到 CLI 进阶与插件生态，一篇文章上手。

一、核心概念：什么是 Harness？

Harness（缰绳/线束）：在 AI 领域指”把模型包起来、给它干活能力的那层框架”。模型只负责生成文本，能不能读文件、执行命令、调用 API、记住上下文，全看 Harness 给不给力。

DeepSeek Harness 的架构由 Cordis 插件系统驱动（有学术论文支撑，事件驱动设计）。Cordis 内核只负责插件的加载、卸载与依赖管理，其余一切能力都是插件：

可插拔组件	说明
模型（models）	DeepSeek / Anthropic / OpenAI / 任意 OpenAI 兼容端点
工具（tools）	文件编辑、Shell、检索、技能、子代理……
技能（skills）	可复用的能力包
会话（sessions）	会话的存储与生命周期
沙箱（sandboxes）	代码/命令的隔离执行环境
存储（storage）	状态与记忆的持久化
循环（loops）	Agent 主循环（思考→行动→观察）
调度（scheduling）	定时/计划任务
UI	Web UI、CLI、TUI 都是插件

flowchart TB
    subgraph Core[内核 · Cordis]
        K[插件加载 / 卸载 / 依赖管理]
    end
    subgraph Plugins[能力插件层]
        M[模型 · LLM]
        T[工具 · 文件/Shell/检索]
        S[技能 Skills]
        SE[会话 Sessions]
        SA[沙箱 Sandboxes]
        ST[存储 Storage]
        L[循环 Loops]
        SC[调度 Scheduling]
        U[UI · Web/CLI]
    end
    K --> M & T & S & SE & SA & ST & L & SC & U
    M -->|事件流| T
    T -->|工具结果| L
    L -->|观察| M
    U -->|用户输入| L

任何组件都可以被 patch 替换——这正是”配置即定制”的底气。

二、环境要求

Node.js（必需，npx / pnpm 都靠它）
操作系统：Linux / macOS / Windows 均可
基础命令行能力；准备一个 API Key（DeepSeek 在 platform.deepseek.com 申请）

三、安装（两种方式）

方式一：npm 一行启动（推荐，最快）

npx @deepseek-ai/dsh web

默认在 http://127.0.0.1:3080 启动 Web UI；
本机启动会自动用默认浏览器打开页面；
通过 SSH 启动时只打印宿主机 URL（本地转发地址由 SSH 客户端或编辑器持有）；
加 --no-open 只跑服务器、不弹浏览器。

方式二：从源码运行（适合二次开发/贡献）

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

pnpm run build 准备仓库产物；之后 pnpm dsh web 直接用已构建产物，不会重复构建。

⚠️ 当前处于开发者预览阶段，迭代很快，未来会有破坏兼容性的变更，升级前留意 changelog。

四、快速上手：Web UI 三步走

dsh 进程会把启动时所在的目录作为默认文件系统位置；全新 Web UI 不会自动选中任何工作区，需要手动添加。

第 1 步：配置模型

打开 设置 → 模型，输入 DeepSeek API 密钥并保存：

模型路由立即可用，无需重启服务器；
密钥是只写的：保存后页面只显示脱敏描述符，永远拿不到明文；密钥存储在 $DSH_HOME/.credentials.yaml，settings 里只留凭据引用；
想用别的模型？选择”添加提供方”可配 Anthropic、OpenAI 等；公司网关/自建服务器则选”添加自定义提供方”（填小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型）。Bedrock、Vertex、Azure、Codex 需要各自的原生凭据（AWS 凭据、ADC 项目、api-version、OAuth）。

第 2 步：选择工作区

点击”选择工作区”，添加启动 dsh 时所在的项目目录并选中。选中工作区之前，会话输入框是不可用的——先选目录再聊天。

第 3 步：跑第一个任务

启动一个会话，发送：

Summarize this repository and identify its main packages.

Agent 会读取和编辑工作区文件、运行命令、委派工作、维护计划；如果某操作按当前权限策略需要审批，Web UI 会先询问你。

sequenceDiagram
    participant U as 用户
    participant A as Agent 主循环
    participant T as 工具（文件/Shell/检索）
    participant P as 权限审批
    A->>A: 规划任务（计划/目标）
    loop 思考→行动→观察
        A->>T: 调用工具
        T-->>A: 结果/输出
        alt 需要审批的操作
            A->>P: 请求审批
            P-->>U: 询问用户
            U-->>P: 允许/拒绝
            P-->>A: 放行
        end
    end
    A-->>U: 最终答案

五、CLI 进阶用法

dsh 是启动 profile 的命令。profile = 多个插件组合包的 patch 层按顺序叠加 + 你自己的覆盖配置。

命令	用途
`dsh --profile <name>`	启动 `$DSH_HOME/profiles/<name>` 下的指定 profile
`dsh --profile headless "job"`	无头模式：跑一个全新的持久化会话，打印最终答案并退出（CI/脚本神器）
`dsh web`	`--profile web` 的别名
`dsh plugin --profile <name> <pnpm args>`	通过转发给 pnpm 来管理该 profile 的插件

启动器 flag 规则：launcher 的 flag 必须写在最前面，它不认识的第一个 token 之后都是应用参数：

dsh --profile web --port 8080        # --port 属于 web 应用
dsh --profile headless "run the tests"
dsh --profile web --help             # 显示 web 应用的帮助，而不是启动器的
dsh --help                           # 启动器自己的帮助

配置树分层叠加（从下到上，上层覆盖下层）：

flowchart TD
    A[空根配置] --> B[dsh.profile.bundles 组合包 patch]
    B --> C[profile 自身 cordis.patch.yml]
    C --> D[$DSH_HOME/cordis.patch.yml 用户级]
    D --> E[--patch 指定覆盖层]
    E --> F[最终生效配置]

不启动也能检查配置树：dsh --profile web --dump-config（实际生效配置）/ --dump-default-config（默认值）。

六、插件生态与四种运行模式

插件从哪来？

社区插件打上 dsh-plugin 话题即可被发现；社区已有插件市场/hub 收录 3,100+ 个 dsh 插件（含搜索、排行、安装命令与公共 API）；
用 dsh plugin --profile <name> <pnpm args> 在 profile 里安装/卸载；
官方组合包：@deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app、@deepseek-ai/dsh-headless。

四种运行模式

模式	定位	说明
标准模式	功能完整的编码 Agent	日常主力：读改写文件、跑命令、规划、委派
PTC 模式	程序化工具组合	模型用一段 TypeScript 程序组合多轮工具调用，减少往返
极简模式	双工具	只留两个工具，用于模型基准测试
创造模式	插件试验场	运行时检查 + 插件试验 + 自定义 preset 创作

SDK 接入

除了 Web UI 和 CLI，还提供 Python SDK 和 TypeScript SDK，可以把 Agent 直接嵌进你自己的应用/脚本里。

七、可观测性：每次运行都有迹可循

模型看到的一切——系统提示词、思维链、工具调用与结果、子 Agent 调度、上下文注入——都写入仅追加的会话日志；
Trajectory（轨迹）视图按来源查看，恢复、分叉、检索与回放共享同一份事件流；
事件驱动扩展点分会话 / Agent / 能力三级，任何能力都能被 patch 替换；
无特权内核，所有注册皆可逆——研究 Agent 行为的理想底座。

八、常见问题排查

现象	处理
`MISSING_CREDENTIAL`	通过模型页存密钥，或提供被引用的环境变量
`UNKNOWN_MODEL`	选择已配置的模型，或给自定义提供方添加缺失模型
“获取可用模型”返回 401	检查密钥；模型发现调用 OpenAI 兼容的 `GET /models`，不提供该端点的服务请手动输入模型
密钥地址都对，网关却拒绝每个请求	网关请求形状与 OpenAI 不同，在路由上加 `compat.supportsDeveloperRole: false` 与 `compat.maxTokensField: max_tokens`
只有推理模型失败	系统提示词以 `developer` 角色发出被拒，设 `compat.supportsDeveloperRole: false`
图片在发送前被拒绝	该模型未声明图片模态，给自定义提供方的模型加 `input: [text, image]`

九、总结

DeepSeek Harness 是目前少见的**”全组件可替换”**的开源 Agent 框架：MIT 许可、无遥测、无云锁定，模型无关，配置即定制。对开发者，它是能力边界完全可控的本地编码助手；对研究者，它是完整可观测的 Agent 实验台；对效率爱好者，Web UI / headless / Python SDK 三种姿势任选。

上手三步： 装 Node.js → npx @deepseek-ai/dsh web → 填 API Key、选工作区、开聊。

~/blog