DeepSeek Harness 深度体验：一个让你重新认识 Agent 框架的东西

📝

Alan Hsu 对 DeepSeek 官方 Agent 框架 dsh 的深度体验：一切皆插件的 Cordis 架构、三层插件树、能力缝（Capability Seam）、headless 模式与 Python SDK，以及几个让人眼前一亮的细节。

原文作者：Alan Hsu（公众号「Alan の手札」）｜本文为转载整理
相关阅读：《DeepSeek Harness 开发者预览版：一切皆插件》（官方发布文）

一句话结论：DeepSeek Harness 是 DeepSeek 官方出的一个 Agent 框架，但它的「一切皆插件」设计，让它在可玩性上跟其他框架不是一个画风。

一、DeepSeek Harness 到底是什么？

DeepSeek 官方仓库多了一个东西——deepseek-harness，GitHub 上叫 deepseek-ai/deepseek-harness，npm 包名是 @deepseek-ai/dsh。

官方定义很简单：DeepSeek Harness（dsh）是一个开源 Agent 框架，由 DeepSeek AI 开发。但真正让它跟市面上其他 Agent 框架拉开差距的，不是它「能做什么」，而是它「怎么做的」。

它背后站着一个叫 Cordis 的插件框架，设计理念来自论文《A Programming Paradigm for Spatiotemporal Composability》。核心哲学：一切皆插件——模型适配器是插件，工具注册表是插件，会话日志是插件，甚至 Agent 循环本身也是插件。

没有「核心要你去改」的概念，只有「插件在旁边挂上去」的概念。每一层都可插拔、可叠加、可覆盖，跟 Docker 镜像层的理念有点像。

二、安装：简单到有点不像话

前提条件：Node.js 22.19+ 或 24+（CI 甚至覆盖了 26）。然后一行命令：

1	npx @deepseek-ai/dsh web

npx 会帮你下载、启动，默认在 http://127.0.0.1:3080 开一个 Web UI。从源码跑也简单：

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

整个仓库用 pnpm workspaces 管理，分了 40 多个包，但编译完跑起来就一个命令。只想快速体验用 npx 就够了。

三、核心架构：一个插件树是怎么长出来的

dsh 的运行时本质是一个三层堆叠的插件树：

层	职责	说明
Profile	命名组合配置	存在 `~/.dsh/` 下，记录用了哪些 bundle 和自己的补丁
Bundle	配置行的分发格式	一组插件配置，如 `dsh-base` 管基础能力、`dsh-web-app` 管 Web 界面
Patch	用户覆盖层	通过 `cordis.patch.yml` 替换任意一行配置

想看你机器上实际启动了哪些插件？一行命令：

1	dsh --profile web --dump-config

它会打印完整插件树，每一行都可以被你的 patch 替换掉。

核心包职责（每个包都通过 ctx.effect() 或 ctx.on() 注册到 Cordis 上下文，删掉插件它的副作用自动回收）：

包名	管什么	在 ctx 上的 key
core/session	会话日志（只追加）	ctx.sessions
core/system-prompt	Prompt 段和工具 schema 组装	ctx.systemPrompt
core/tools	带作用域的工具注册和执行	ctx.tools
core/agent	Agent 接口与事件	ctx.agents
core/agent-loop	默认 Agent 执行器	ctx.agentLoop
llm/llm	消息流 + 模型适配器	ctx.llm

一次 Agent 执行发生了什么：一个「step」（一次模型请求 + 它调用的工具）经历精心设计的事件链：

turn/start 和 turn/end 包围一次完整交互回合，可能包含多个 step
agent/pre-step 是 waterfall 事件——监听器可改写输入消息甚至直接拒绝，所有监听器必须调用 next() 让链继续
llm/stream 也是 waterfall，可拦截/修改模型流式输出
tools/* 三个事件（pre-execute、execute、post-execute）构成完整工具执行管道
agent/turn-stopping 是 serial 事件，没有 next()，可在里面决定是否阻止回合结束

Model-visible = logged 是一条硬性约束：任何能到达模型的信息，必须能从会话日志中重建出来。想给模型新增输入源，必须先扩展 SessionEventMap 再加日志事件。这保证所有 Agent 行为可审计、可回放。

四、能力缝（Capability Seam）：最让人眼前一亮的抽象

一个完整的缝由三个角色构成：

Service Definition：声明接口（如 fs/read、fs/write、fs/list）
Service Provider：可以是本地文件系统，也可以是远程沙箱实现
Consumer：一个工具（如 read_file tool）调用这个接口

为什么这么设计？因为换一个 Provider，整个系统的行为就变了。把文件系统 Provider 从本地换成远程沙箱，Shell 能力、子进程能力、LSP 能力——所有依赖文件系统的模块——全部跟着迁移，不改任何一行消费者代码。

dsh 内置的能力缝：

能力	接口	内置 Provider
Shell	执行 shell 命令	本地 bash、pwsh
子进程	管理子进程	本地进程树
文件系统	读写文件、目录操作	本地文件系统
Web	搜索、抓取网页	搜索 + fetch
子 Agent	生成子 Agent	同进程子 Agent
终端	持久化终端会话	本地终端
LSP	语言服务器协议	本地 LSP
技能	执行技能	本地技能注册表

五、写一个插件到底有多简单？

一个最简单的工具插件长这样：

import { Context } from '@deepseek-ai/cordis';
import { definePlugin } from '@deepseek-ai/dsh';

export function apply(ctx: Context) {
  ctx.tools.register('my_custom_tool', {
    type: 'function',
    function: {
      name: 'my_custom_tool',
      description: '一个自定义工具',
      parameters: {
        type: 'object',
        properties: {
          query: { type: 'string', description: '查询内容' },
        },
        required: ['query'],
      },
    },
    async execute(args) {
      return `你查询了：${args.query}`;
    },
  });
}

export default definePlugin(apply);

把插件挂到 cordis.yml 或 bundle 里，Agent 就能自动发现并使用它。官方还给了一个 GitHub Topic dsh-plugin，社区生态已经开始长起来了。

六、Headless 模式：一个命令跑完一个任务

不需要 Web UI，先设 DEEPSEEK_API_KEY，然后：

1	dsh --profile headless "帮我看看这个目录里有什么文件，整理成一份清单"

这个模式特别适合 CI/CD 自动跑 Agent 任务、脚本自动化处理、批量处理场景。跑完任务就退出，不启动任何 HTTP 服务，与 web 模式共享同一个 dsh-base 基础包。

七、Python SDK：从 Python 里驱动 dsh

dsh 有官方 Python SDK，直接把整个 Agent 运行时以子进程形式跑起来，Python 通过 JSON-RPC 与它通信。

1	pip install deepseek-harness-sdk

安装时会自动装上同版本的 deepseek-harness-runtime-bin（单文件可执行程序，打包了 Node 运行时 + 整个核心插件栈，机器上甚至不需要装 Node.js）。

最简单的例子：

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness() as harness:
    result = harness.run("Say hi, and tell me what time it is in Beijing.")
    print(result.final_response)

输出大概长这样：

1	Hi! The current time in Beijing is 2026-08-14 20:22 (CST, UTC+8).

不用写 API 调用代码、不用拼 messages 数组、不用处理工具调用循环——DeepSeekHarness() 上下文管理器启动子进程，run() 发消息，退出时自动关进程。

普通编码 vs dsh Python SDK 的核心差异：

维度	自己写代码	dsh Python SDK
消息组装	手动拼 JSON 数组	自然语言，run() 直接传
工具调用	自己写 loop、解析 function_call	内置 Agent Loop 自动处理
文件系统访问	自己写 os.read/open	内置工具自动执行
Shell 执行	自己写 subprocess	内置 shell 工具自动执行
会话持久化	自己写数据库/文件	自动记录 JSONL 日志
上下文管理	手动拼接历史消息	自动从会话日志推导
多轮工具调用	手动写 while 循环	内置 step/turn 循环

进阶可传 cordis 参数指向自定义配置，max_tokens 控制每次请求最大输出。SDK 还能处理子 Agent 层级——RunResult 里携带所有子 Agent 通知，finish_reason 告诉你最后一次 turn/end 的原因（completed / max-tokens / error）。

底层走的是基于 stdio 的 JSON-RPC：进程隔离（Python 崩了子进程还在，反之亦然）、不需要 Python 侧加载 Node 依赖、可替换运行时（DSH_RUNTIME_MODE 切换 exe/node 模式）。

八、几个让人「卧槽」的设计细节

8.1 AGENTS.md —— 给 AI Agent 写的操作手册：仓库里有个 AGENTS.md，不是给人看的，是给 AI Agent（Codex、Claude Code）看的。写了目录结构、每个包职责、构建/测试命令、代码规范、事件系统设计约束、提交规范。AI Agent 读它就能快速理解项目结构，做出正确修改。这是 DeepSeek 在「AI 原生开发」上走得很前面的信号。

8.2 会话日志即真相：整个模型上下文从会话日志推导出来，而不是从「内存状态」读。deriveMessages() 从日志投影出模型能看到的历史，assistant/chunk 保留原始流式输出。Fork 会话、恢复会话、生成转录、做遥测，全从这个日志流来。

8.3 自修改 Agent：self-modification 包允许 Agent 运行时检查、挂载、卸载自己的插件——一边跑一边改自己当前行为，加工具或换 Provider 不用重启。

8.4 双语文档与配对合并：文档中英双语，不是简单各一份，而是用自动配对合并驱动——两个语言文档同时修改时，Git 合并驱动自动推导配对记录。

九、但也有几个现实问题

开发者预览阶段：README 自己写了 THERE WILL BE COMPATIBILITY-BREAKING CHANGES，现在上生产要谨慎。
文档还在建设中：架构文档扎实，但面向普通用户的教程和 cookbook 还在补充。
生态刚起步：dsh-plugin 话题下插件还不多，很多场景要自己写。
依赖 Node.js 22+：还在用 Node 18/20 的老版本需要先升级。

十、它适合谁

Agent 框架研究者和架构师：能力缝设计和事件驱动架构值得深研。
想为 DeepSeek 生态做贡献的开发者：写一个 dsh 插件，比写独立框架容易得多。
需要可定制 Agent 的团队：现有框架（LangChain、AutoGPT 等）在灵活性上满足不了你时。
AI 原生开发的早期实践者：从 AGENTS.md 到自修改插件，dsh 走得很远。

作者的理解很精辟：DeepSeek 在下一盘棋——API 是入口，模型是大脑，Harness 是躯体。 当模型能力越来越强，控制模型的「躯体」就变得至关重要，而一个插件化、可定制、可扩展的 Harness，就是这个躯体的最佳形态。现在还太早（开发者预览、生态未起），但方向是对的。