还在用 LangGraph 手搓 Agent？试试 DeepSeek Harness 一行命令方案

GGS

377人浏览 · 2026-08-14 22:11:18

GGS · 2026-08-14 22:11:18 发布

8月13日，DeepSeek 在发布 V4 Pro 正式版的同时，甩出了第二记重拳——DeepSeek Harness（简称 DSH），一个 MIT 协议完全开源的 Agent 框架。GitHub Star 一天冲到近 40k，Hacker News 直接 TOP 1。

这不是又一个大模型，而是让模型"真正能干活"的基础设施。本文手把手带你从零跑通。

一、先搞清楚：DeepSeek Harness 是什么？

一句话：Model + Harness = Agent。

DeepSeek 的模型负责"思考"，Harness 负责"执行"——读文件、跑命令、调度工具、管理会话，所有模型之外的事都归它管。

你可能会想：这不就是 DeepSeek 版的 Claude Code 吗？

不完全是。Claude Code 是一个产品——你按它的规则来用。Harness 是一套元框架——你用它组装自己的 Agent 产品。模型可以换，工具可以换，循环逻辑可以换，安全策略可以换，连 UI 都可以换。

官方的设计哲学只有六个字：一切皆插件（Everything is a Plugin）。

打开架构文档你会发现：模型适配器是插件，工具注册是插件，会话日志是插件，Agent 循环本身也是插件，沙箱是插件，审批策略是插件，甚至 UI 都是插件。所有组件通过Cordis插件系统协同工作，开发者不改源码就能替换任何一个能力。

二、四种运行模式，按需选择

Harness 预置了四种模式，每种加载不同的插件集合：

模式	适合场景	特点
标准模式	日常开发	完整工具组合：文件操作、Shell、搜索、子任务委派等
PTC 模式	复杂多步任务	模型生成 TypeScript 代码编排多轮工具调用，中间数据留在运行环境里，只有最终结果进入上下文，大幅省 Token
极简模式	模型基准测试	仅保留 Shell + 文件编辑，最小化环境
创造模式	探索与实验	可检查运行时、内存中试验插件组合，甚至让 Agent 改装自身

PTC 模式特别值得关注：传统 Agent 每轮工具调用的结果都会塞进上下文窗口，几轮下来 Token 消耗爆炸。PTC 让模型写一段代码来编排多轮调用，中间结果不回传给模型，只返回最终结论。对于长链路任务，Token 消耗能降一个数量级。

三、实操开始：从安装到跑通

第 0 步：确认环境

DSH 基于 Node.js/TypeScript 构建，需要 Node.js 环境。

打开终端，执行：

node --version

如果能看到版本号（建议 v22 或以上），直接跳到下一步。如果提示找不到命令，去Node.js 官网下载 LTS 版本安装。

Windows 用户注意：安装完 Node.js 后，重新打开 PowerShell，不然环境变量可能没刷新。

第 1 步：一行命令启动（最快方式）

不想全局安装？直接用 npx 临时运行：

npx @deepseek-ai/dsh web

第一次运行会问你是否下载，输入 y 回车。下载完成后自动启动 Web 服务，浏览器打开 http://127.0.0.1:3080 即可进入界面（详见Web UI 指南）。

就这一行命令，完事。

第 1 步（备选）：全局安装

如果你打算长期使用，全局安装更方便：

npm install -g deepseek-ai/dsh

安装完验证一下：

dsh --version
# 当前版本 0.1.0-rc.6

然后启动：

dsh web

第 1 步（进阶）：从源码运行

想改源码或写插件？走源码路线：

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

项目使用 pnpm 管理依赖，如果没有 pnpm，先 npm install -g pnpm。

第 2 步：配置 API Key

进入 Web 界面后，第一件事是配置模型密钥：

打开设置 → 模型
在 DeepSeek 卡片处填入你的 API Key
保存

没有 API Key？去DeepSeek 开放平台注册账号，创建一个。

安全提醒：API Key 不要贴到公开文章、GitHub 仓库、群聊或截图里。密钥存在 $DSH_HOME/.credentials.yaml，网页上只显示脱敏形式。如果怀疑泄露，立即去平台吊销。

除了 DeepSeek 官方模型，Harness 也支持 Anthropic、OpenAI，以及任何兼容 OpenAI 接口的自建服务——都在同一个模型设置页里加。

第 3 步：选择工作区

点击选择工作区，把你想让 Agent 操作的项目文件夹加进来。

这一步很重要：工作区机制限制了 Agent 只能操作你明确选择的目录。没选中之前，会话输入框是灰的。

第 4 步：新建会话，发第一个任务

新建一个会话，选一个运行模式（先用标准模式），然后直接用自然语言描述任务。

新手建议：别上来就扔几百 GB 的项目。先拿一个小项目测试，比如：

分析这个仓库的目录结构，列出主要模块和它们的作用。

或者：

找到当前项目中的测试命令，运行测试并总结失败原因。不要修改任何文件，不要安装依赖。

Agent 会自己读文件、跑命令、分析内容，碰到超出权限的操作会先停下来问你。

四、进阶玩法

用 PTC 模式省 Token

对于多步骤任务，切换到 PTC 模式。模型会生成一段 TypeScript 代码来编排工具调用，中间结果留在运行环境里，只有最终结论进入上下文。

效果：一个需要 10 轮工具调用的任务，标准模式可能消耗 20k+ Token，PTC 模式可能只要 3k。

Headless 模式：嵌入自动化

不想开 Web UI？用 headless profile 跑一次性任务：

dsh --profile headless ”运行测试并总结失败原因”

适合嵌入 CI/CD 或批处理脚本。先用 Web 模式调通流程，再切 headless 跑自动化。

让 Agent 改装自己

切到创造模式，Agent 可以检查当前运行时、在内存中试验插件组合，甚至给自己创建一个官方 UI 没有的功能。

比如，让接入了 V4 Pro 的 Harness 给自己创建一个"三栏模式"布局——左边文件树，中间对话，右边实时事件流。这在其他 Agent 产品里几乎不可能做到。

会话日志：可追溯、可回放

模型看到的一切——系统提示词、思维链、工具调用与结果、子 Agent 调度、上下文注入——都会写入一份仅追加的会话日志。

在 Trajectory 视图中，你可以按来源查看这些信息，支持恢复、分叉、检索和回放。Agent 出了问题？回放日志，精确定位是哪一步、哪个工具调用出了岔子。

五、开发者干货：写你的第一个插件

前面是"用"，这一节是"造"。Harness 的插件开发体验相当丝滑，跟着走一遍，你会理解"一切皆插件"到底意味着什么。

5.1 插件的本质：一个导出 apply 函数的 TS 模块

在 Harness 中，插件就是一个导出 apply 函数的 TypeScript 模块。框架加载插件时调用 apply，传入 ctx 上下文对象，你在里面注册各种能力：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-world'

export function apply(ctx: Context): void {
  console.log('🎉 Hello World from dsh plugin!')
  ctx.logger.info('Hello World plugin loaded successfully')
}

这就是一个完整的插件。没有清单文件，没有构建配置，没有注册中心。

5.2 三步跑通：创建、注册、加载

第一步，从仓库根目录创建一个 scratch 项目：

mkdir -p ggs/src

把上面的 hello-plugin 代码存为 scratch-plugin/src/my-plugin.ts。

第二步，创建 scratch-plugin/cordis.yml 注册文件（注意路径必须是绝对路径）：

- insert:
    - id: hello-world
      name: /Users/gaoguosheng/workspace/ggs/ai/deepseek/deepseek-harness/ggs/src/my-plugin.ts

第三步，带补丁启动 Web UI：

pnpm dsh web --patch ./ggs/cordis.yml

打开 http://127.0.0.1:3080，终端会打印 [hello-plugin] plugin loaded!。

卸载即清理：通过 ctx 注册的一切（事件监听、工具、定时器）在插件卸载时自动清理，不需要手写 removeListener。需要显式清理的资源（如网络连接），用 ctx.effect() 注册清理函数：

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    // 插件卸载时自动执行
    return () => clearInterval(timer)
  })
}

这就是 Cordis 论文里"时间可组合性"的工程落地：注册时自动记录逆操作，卸载时框架保证干净回滚。

5.3 实战：给 Agent 写一个自定义工具

工具是插件最常见的形态。假设你想给 Agent 加一个 greet 工具：

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
 
export const name = 'greet-tool'
export const inject = ['tools']
 
export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

几个关键点：

inject: ['tools']
声明依赖——框架会等工具注册表就绪后才加载这个插件
defineTool
从 parameters 自动推断并校验 execute 的参数类型，TypeScript 全程类型安全
output.schema
声明返回值类型，output.render 把返回值转换成模型可读的内容

重启后，在 Web UI 里直接说：Use the greet tool to greet Ada.——模型会自动调用你的工具并拿到 Hello, Ada!。

想接 MCP？原理一样：一个 MCP server 就是一个插件，发现工具后逐一 ctx.tools.register()。已有的 MCP 生态可以直接搬过来用。

5.4 实战：用 Hook 做权限管控

企业场景最关心的安全问题，Harness 的解法是 tools/pre-execute 钩子——每次工具调用前都会经过这道闸门，你可以放行、拒绝或转人工审批：

import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
 
declare function isAllowed(exec: ToolExecution): Promise
 
export const name = 'permission-gate'
 
export function apply(ctx: Context) {
  ctx.on('tools/pre-execute', async (exec, next): Promise => {
    if (!(await isAllowed(exec))) {
      return { kind: 'deny', reason: 'Denied by policy.' }
    }
    return next()
  })
}

比如你在 isAllowed 里实现一条规则：所有rm -rf、git push --force类高危命令一律拒绝，写文件操作转人工确认。官方的沙箱（landlock/sandbox-exec）、审批系统、计划模式，走的都是这套相同的扩展点——没有特权代码，你的策略插件和官方插件平起平坐。

5.5 实战：做一个自己的 UI

UI 也是插件。监听 session/event 事件流拿到模型的输出，通过 agent.followup() 把用户输入喂回去：

import type { Context } from '@deepseek-ai/cordis'
import { createUserMessage } from '@deepseek-ai/dsh-llm'
import { SessionId } from '@deepseek-ai/dsh-session'
 
export const name = 'my-ui'
export const inject = ['agents']
 
export function apply(ctx: Context) {
  // 渲染模型输出的每个 token
  ctx.on('session/event', (_session, event) => {
    if (event.type === 'assistant/chunk' && event.data.chunk.type === 'text-delta') {
      render(event.data.chunk.text)
    }
  })
  // 把用户输入发回给 Agent
  onUserInput(text => ctx.agents.get(SessionId('client-session'))?.followup(
    createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
  ))
}

想做一个钉钉机器人版、微信版、甚至终端 ASCII 版的 Agent 客户端？就是几十行代码的事。

5.6 功能与机制对照表：产品能力全部可拆

官方文档里有一张"功能 → 机制"映射表，每个产品功能都对应一个扩展点上的插件，这里挑几个高频的：

产品功能	背后的插件机制
内置工具（bash/fs/web/子Agent/todo）	`ctx.tools.register()`
MCP 接入	一个 server 一个插件，发现工具后注册
上下文压缩（自动+手动）	`ctx.compaction` 扩展点
系统提示词定制	`ctx.systemPrompt.section()` ，带排序和作用域
AGENTS.md 项目规范	一个读文件的 section provider
定时任务（cron）	插件注册调度工具，定时器触发时 `followup()`
子 Agent 委派	`ctx.subagents` provider 注册表（支持进程内/fork/ACP 等多种模式）
计划模式 / 审批 / 沙箱	各自独立的插件，走 `tools/pre-execute` 等扩展点
插件热重载	每个注册都是 `ctx.effect` → HMR 开箱即用

最后一行值得划重点：插件支持热重载，改完代码即生效，不用重启整个 Harness。

六、踩坑清单

问题	原因	解决方案
`node` 命令找不到	环境变量未刷新	重新打开终端
`dsh` 命令找不到	全局安装后路径未生效	重新打开终端，或检查 npm 全局路径
启动后浏览器没自动打开	系统设置问题	手动访问 `http://127.0.0.1:3080`
对话没反应	API Key 未配置或无效	检查设置 → 模型中的 Key
Agent 执行很慢	首次请求需要预热模型	耐心等第一个请求返回
工作区无法选择	权限问题	确认目录存在且有读写权限

七、现在能上生产吗？

明确回答：不能。

当前是 v0.1 开发者预览版，官方 README 里用加粗大写写着：

THERE WILL BE COMPATIBILITY-BREAKING CHANGES

今天能用的接口明天可能就变了。建议：

可以：体验、研究、实验、学习插件开发
不可以：直接用于企业代码仓库、生产服务器、重要业务数据

把它当成一个实验工具玩明白，等版本稳定后再考虑接入正式工作流。

八、为什么值得关注？

你可能觉得：又一个 Agent 框架，跟我有什么关系？

三个理由：

1. 开源协议最宽松

MIT 协议，想怎么用怎么用。对比 Claude Code（闭源）、Codex（闭源），Harness 是目前唯一一个完全开源的 Agent 基座。你可以 fork 它、改它、拿去做自己的产品。

2. 插件生态的想象力

"一切皆插件"不是噱头。当你真正需要替换模型供应商、自定义审批流程、或者给 Agent 加一个只有你团队才需要的工具时，你会发现插件化架构的价值。在其他产品里，这些需求意味着"等官方支持"。

3. 背后有一篇严肃论文

DeepSeek 同步发布了论文《A Programming Paradigm for Spatiotemporal Composability》，解决了插件系统的两个核心难题：插件卸载时如何干净回滚（时间可组合性），依赖的插件消失时如何处理（空间可组合性）。这不是 PPT 架构，有形式化证明，有 4000+ 插件的Koishi框架做验证。

九、关键链接

核心资源

资源	地址
GitHub 仓库	https://github.com/deepseek-ai/deepseek-harness
README 中文版	https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md
API 密钥申请	https://platform.deepseek.com
官方微信公众号	DeepSeek Harness 团队

官方文档

文档	地址
Web UI 使用指南	https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.md
第一个插件教程（中文版可切换）	https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/index.zh.md
工具开发教程	https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/tool.md
架构文档	https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md
开发指南	https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
插件扩展 Cookbook	https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cookbook/extension-cookbook.md
性能基准	https://github.com/deepseek-ai/deepseek-harness/blob/master/BENCHMARK.md
贡献指南	https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md

社区与生态

资源	地址
GitHub Discussions	https://github.com/deepseek-ai/deepseek-harness/discussions
Discord 社区	https://discord.gg/Ycq5dCaS4
dsh-plugin 插件话题	https://github.com/topics/dsh-plugin