A1 · DeepSeek Harness 项目总览与心智模型

A1 · DeepSeek Harness 项目总览与心智模型

developer preview：DeepSeek Harness 当前处于开发者预览阶段，API 可能发生破坏性变更。本文基于 master 分支源码，路径以 packages/.../src/... 为准。

1. 它是什么

DeepSeek Harness（命令行 dsh）是 DeepSeek AI 开源的智能体运行时（agent harness）。与把「工具调用 / 模型路由 / 会话管理」硬编码进一个核心二进制的传统做法不同，dsh 的设计哲学是 Everything is a Plugin（一切皆插件）。

• 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• 文档站点：https://deepseek-harness.github.io/deepseek-harness/
• 许可：MIT

2. 心智模型：一棵可配置的插件树

dsh 的每一个能力——模型适配器、工具注册表、会话日志、甚至 agent loop 本身——都是一个挂载到共享 Context 上的 Cordis 插件。不存在需要 patch 的「特权内核」；要扩展 dsh，你只需在别的插件旁边再挂一个插件，所有注册都是可逆的副作用（effect），插件卸载时自动撤销。

关键推论：换一个 Provider，就换一整个产品行为。例如把 ctx.fs / ctx.shell 指向远程沙箱，Bash、PTY、LSP 会一并被搬过去，无需 provider 专用 fork。

下面这段极简代码演示了「一切皆插件」的直觉——连 agent loop 的驱动器都可以被替换：

// 替换默认 agent-loop 为自定义驱动（developer preview，API 可能变更）
import type { Context } from '@deepseek-ai/cordis'

export const name = 'custom-agent-driver'
export function apply(ctx: Context) {
  // ctx.agentLoop 是 seam：替换它 = 换整个轮次调度行为
  ctx.agentLoop = {
    async run(sessionId: string) {
      console.log(`[custom-driver] driving session ${sessionId}`)
      // 你的自定义轮次逻辑：多步规划、并行工具调用、人工确认节点……
    },
    cancel(sessionId: string, cause: string) {
      console.log(`[custom-driver] cancel ${sessionId}: ${cause}`)
    }
  }
}

3. 与「单体 agent 框架」的区别

维度	传统单体框架	dsh（Everything is a Plugin）
扩展点	继承基类 / 装饰器	挂插件到 ctx，监听事件
替换模型层	改配置或改代码	替换 ctx.llm 上的 adapter
热重载	通常不支持	每个注册都是 effect，随 HMR 生效
内核	有特权核心	无特权内核

4. 可运行示例：三种启动方式

# 方式一：预构建（最简，无需 clone）
npx @deepseek-ai/dsh web
# 默认打开 http://127.0.0.1:3080

# 方式二：源码运行（开发插件用）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

# 方式三：headless（一次性运行，不带服务器）
pnpm dsh headless "用 greet 工具问候 Ada"

5. 核心术语中英对照

中文	英文	说明
插件	Plugin	导出 apply(ctx) 的 TS 模块
上下文	Context	服务容器，按 ctx.<key> 查找
能力缝	Seam	可替换能力（定义 / 提供方 / 消费者三层）
配置档	Profile	具名组装（如 web / headless）
组合包	Bundle	Cordis 配置行 + 挂载代码的发布格式
会话事件	Session Event	追加写入日志的持久事实

6. 官方文档 vs 源码 对照表

主题	官方文档	精确源码路径
项目总览	README.md	deepseek-harness-src/README.md
架构入口	reference/#deepseek-harness-架构	docs/architecture.md
启动函数	—	packages/boot/app-boot/src/index.ts（boot / mountRootInclude / renderConfigDump）
Bundle 声明	—	packages/bundle/base/package.json（"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }）
Vendor 说明	—	vendor/README.md

7. 一句话小结

dsh 不是「一个带插件的 agent 程序」，而是「一棵由插件组成、完全靠配置拼装的 agent 运行时」——理解了这一点，后面所有架构与插件开发都顺理成章。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/u010804586/article/details/163820629