项目详情

DeepSeek Harness

DeepSeek 官方开源 Agent Harness——万物皆插件，基于 Cordis 时空可组合性框架

GitHub 地址 MIT Node.js 22.19+Cordis

更新于 2026-08-14 · 开发者预览阶段

项目速览

一句话定位

万物皆插件的开源 Agent 运行框架

DeepSeek AI 官方出品的 agent harness（dsh）。核心是「一切皆插件」架构——模型适配器、工具注册表、会话日志、甚至 agent loop 本身，全是可从配置替换的插件。底层基于 Cordis 框架（论文：《时空可组合性的编程范式》）。适合想深度定制 agent 内部机制、或研究「插件化 agent 架构」范式的开发者，目前是开发者预览版。

项目速览

核心数据

69k

GitHub Stars

5.8k

Forks

12k+

Commits

全插件

无特权内核

官方出品 + Cordis 学术背书。仓库活跃度极高（1.2 万提交），但明确标注开发者预览：会有破坏性变更。

为什么存在

Agent harness 的两个老问题

❌ 特权内核难改

多数 agent 框架有「核心 + 外围插件」之分。想换掉 agent loop、模型适配层、或会话存储，得 fork 改源码，无法从配置层替换。

❌ 插件副作用难撤销

插件注册了事件监听、工具、prompt 段落后，热重载/卸载时副作用残留——状态泄漏、监听器悬挂、行为不一致。

DeepSeek Harness 的答案：没有特权内核，每个注册都是可逆副作用。

🔥 核心页

Cordis：时空可组合性

底层框架 Cordis 来自论文《A Programming Paradigm for Spatiotemporal Composability》。它把「动态组合」拆成两个正交维度——时间与空间。

逆操作（inverse），运行时追踪它 ctx.effect(注册) → 返回 disposer(逆) 卸载/重载时：按序调用 disposer → prompt 段 / 工具 schema / 监听器全干净撤销空间可组合性（Spatial） reactive coeffects · 响应式协效应问题：插件间依赖硬编码、加载顺序难管解法：每个上下文变化，按协效应规格通知相关组件 inject 声明依赖 → 等待服务存在服务用 ctx.key 注册 → 按 key 查找非导入 → 加载顺序 = 服务需求，非手动编排统一

时间维度（可逆）

空间维度（响应式）

两者统一进单一 context 类型 = 一种编程范式

🔥 核心页

万物皆插件：没有特权内核

产品每个部分都是插件——包括模型适配器、工具注册表、会话日志、agent loop 本身。扩展 dsh 不是 patch 内核，而是在其他插件旁挂一个自己的。

--patch 命令行叠加（最高优先级）

base 层（必经）

profile 模板（web）

profile 模板（headless）

用户补丁层（可替换任何行）

Profile = 命名组合（列 bundle 栈 + out-of-tree 插件 + 自己的 patch）。dsh --profile web --dump-config 可看你机器实际启动的整棵树——任何行都能被你自己的 patch 替换。

核心包

核心子系统：每个都是 ctx 上的服务

插件通过声明 ctx.<key> 占位，其他插件按 key 查找而非导入具体实现。

包	职责	ctx 键
`core/session`	append-only `SessionEvent` 日志 + 内存存储	`ctx.sessions`
`core/system-prompt`	prompt 段 + 工具 schema 装配	`ctx.systemPrompt`
`core/tools`	带作用域的工具注册表 + 守卫执行管线	`ctx.tools`
`core/agent`	`Agent` 接口 + 活动注册表 + `agent/*` 事件	`ctx.agents`
`core/agent-loop`	实现该接口的默认驱动	`ctx.agentLoop`
`llm/llm`	消息 + 流词汇 + 适配器接缝	`ctx.llm`

注意：core/agent-loop 也是插件——你想换一套驱动逻辑，挂个新插件即可，无需 fork。

🔥 核心页

Turn 流程：一个 turn = 多个 step

step = 一次模型请求 + 它调用的工具。turn = 零或多个 step：在首次输入被领取前打开，直到不欠任何东西时关闭。

持久化会话事件

实时扩展点

工具执行管线

事件系统

四种事件分派模式

事件是扩展点。分派模式是事件公共契约的一部分，用 @mode 标签标注，生成器会校验声明与调用点一致。

模式	是否 await	分派顺序	有返回值	用途
`emit`	否	注册顺序观察	否	纯观察，副作用通知
`waterfall`	否	注册顺序	是	around-中间件，`next()` 委托
`parallel`	是	所有监听器并行	否	扇出广播
`serial`	是	注册顺序	是	有序链式（如 turn-stopping 无 next）

waterfall 是 around-中间件：监听器收到 (...args, next)，调 next() 委托可能被包装的结果；不调 next 则短路。策略监听器可拥有决策（return 不 next），只标注/观察的监听器必须委托。

会话日志

Session log：一切的真相之源

模型看到的上下文，全部派生自 append-only 会话日志。

append SessionEvent → session/event 广播 → deriveMessages() 投影 → 模型历史

事件是事实（fact）——会话事件是追加到日志的持久事实。事实必须熬过重载，就用会话事件
原始 chunk 保留——assistant/chunk 保留用于重放和 UI 保真
一切派生自日志——Fork、resume、转写、遥测、持久化全部从 session log 推导
SQLite 单调版本——SCHEMA_VERSION 单调递增，SESSION_FORMAT_VERSION 保持 0，无兼容承诺

能力全景

插件覆盖的能力子系统

🤖 模型与循环

llm/ Service Definition + DeepSeek provider
core/agent-loop 默认驱动
compaction/ 上下文压缩
subagent/ 委派 + delegation
self-modification/ agent 自检/挂载自己的插件

🛠️ 工具与执行

core/tools 守卫执行管线
fs/ 文件系统 + 策略
shell/ bash + pwsh provider
subprocess/ 进程树
e2b/ 沙箱 + FS/子进程适配
terminal/ 持久会话

📋 协调与治理

web/ 搜索/fetch provider + tool
skill/ skill 注册表 + catalog
plan/ plan 模式（日志状态）
todo/ todo_write 工具
guard/ 循环卫生 + 工具超时
interaction/ 审批/权限/ask-user

还有 native/（landlock-run node addon，Linux 沙箱）、python/（Python SDK + 运行时）、acp/（Agent Client Protocol 自动化服务器）、hooks/（Claude Code/Codex hook 桥）。

快速上手

两条启动路径

# 路径 1：npx 直接跑 Web UI（推荐试用）
npx @deepseek-ai/dsh web
# → http://127.0.0.1:3080 开浏览器应用

# 路径 2：从源码构建（开发/定制）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install          # node ^22.19 || >=24，corepack pin pnpm@11.7.0
pnpm run build
pnpm dsh web

# 查看你机器实际启动的插件树（任何行都能被 patch 替换）
dsh --profile web --dump-config

# headless 模式：一次性 runner，无服务器
pnpm dsh --profile headless "你的任务"

开发参考：docs/architecture.md（改 packages/ 前必读）、docs/development.md（TS Host/Client 双聚合布局）、docs/cordis-primer.md（Cordis 五大思想）。

适用场景

适合谁用

Agent 架构研究者——研究「插件化、无特权内核」范式的标杆样本，Cordis 论文配套实现
深度定制 Agent 的开发者——想换 agent loop / 模型层 / 会话存储，从配置层替换而非 fork
企业 Agent 平台团队——需要热重载、副作用干净撤销的插件生态，profile/bundle 分层管理多套配置

⚠️ 注意

开发者预览——明确警告「会有破坏性变更」，生产慎用
学习曲线陡——需懂 Cordis 的 effect/coeffect 概念
绑定 DeepSeek——官方主推自家模型，多 provider 是后话

风险提示

需要权衡

预览期不稳定——README 顶部红字警告「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」。无外部消费者阶段，作者优先打对的地基而非兼容垫片，重命名/重打包频繁
架构复杂度高——时空可组合性、waterfall/serial 事件、Host/Client TS 双聚合、profile/bundle/patch 多层叠加，门槛远高于「装了就用」的 harness
Cordis 是 vendored（内嵌）——框架源码在 vendor/，非独立依赖。跟随上游同步有额外维护成本，也意味着 dsh 对 Cordis 演进有强控制
沙箱能力依赖 landlock——native/node-addon-landlock-run 仅 Linux，macOS/Windows 沙箱能力受限

潜力评估

未来空间

DeepSeek 官方背书 + 69k stars + 学术级架构设计，是 2026 年 agent harness 赛道的架构派标杆。Cordis 的「时空可组合性」理论把「插件热重载无副作用残留」这个工程难题给出了形式化解法——如果这套范式跑通，会重新定义 agent harness 该怎么造。风险在于预览期 + 复杂度可能劝退普通用户，更适合作为研究 + 深度定制而非即装即用工具。

上一个
Diagram Design

下一个
Pi-Mono