GitHub 263.4K+ Star！DSH 如何定义 Agent 框架

2026年8月13日晚，DeepSeek悄悄开源了一个重磅项目。 3小时GitHub星标破3万，一夜直接冲到6万。

它不是新大模型，也不是又一款代码助手。 它是一套把可替换性刻进底层骨架的Agent运行时框架：DeepSeek Harness，简称dsh，MIT开源协议。

这篇文章不讲虚头巴脑的噱头，只聊一件核心事： 为什么智能体的护城河从来不在模型，而在架构？这套架构强在哪、怎么上手、适合谁来用。

01 底层命题：智能体赛道的「接口经济」

最近两年，AI编程工具、Agent框架层出不穷。 但绝大多数产品，都在同一个赛道内卷： 模型跑分高一点、内置工具多几个、Benchmark数据好看一点。

这都属于零件层面的竞争。 零件迟早过时，模型持续迭代，工具列表几个月就被对手抄完。

DeepSeek Harness换了一条赛道押注：接口层。 整套运行时由Cordis内核驱动，配套论文《A Programming Paradigm for Spatiotemporal Composability》，由北大和DeepSeek联合发布。

翻译成大白话： 框架里每一个组件，都能单独替换，而且替换的时候不会弄坏其他模块。

这不是宣传口号，是架构底层设计。 官方文档原话：不存在需要打补丁的特权内核。 扩展dsh的方式就是新增插件，和原有插件并排挂载；所有注册动作都是可逆副作用，插件卸载，注册信息自动清除。

想查看当前环境到底加载了什么？一条命令打印完整配置树：

dsh --profile web --dump-config

打印出来的任意配置项，都可以用patch文件覆盖，不用修改框架源码。

✅ 商业价值一眼看懂： 客户升级不用等官方发版。银行可以把审批层换成自研风控，SaaS厂商可以替换沙箱环境，其余整套系统照常运行。 对To B企业来说，每层都可替换，等于不被厂商架构绑架，这是企业采购最看重的信任筹码。

02 无特权内核：就连Agent思考循环，本身也是插件

市面上大部分Agent框架的“可扩展”，局限在加工具、换模型。 Agent怎么接收输入、怎么思考、什么时候停止一轮调用——这个核心循环，基本都是厂商写死的黑盒内核，开发者碰不了。

dsh直接去掉了固化内核。 在它的体系里，Agent循环 ctx.agentLoop 仅仅是一个插件。 模型适配器、工具注册表、会话日志、沙箱、审批策略、前端界面，全部都是插件，全部支持配置替换。

架构设计思路对标操作系统

• dsh-base底层：模型适配、工具注册、持久化存储、沙箱、审批、凭据、遥测，是每个profile的基础底座
• 上层：dsh-web-app网页端 / dsh-headless无服务命令行运行器

profile = 一组命名好的插件组合。 bundle是Cordis配置+代码的分发包。 配置通过patch层层叠加，顺序：官方基线 → 企业标准 → 项目定制 → 个人偏好

多层配置互不冲突。升级官方版本，客户自己写的定制层不会被覆盖，天生适配私有化、SaaS交付。

项目monorepo里面一共68个package，覆盖Agent全链路： core/session｜仅追加会话事件日志 core/system-prompt｜提示词、工具Schema组装 core/tools｜工具注册表与执行管线 core/agent｜Agent接口与注册表 core/agent-loop｜默认Agent调度逻辑 llm/llm｜消息流、模型适配器接口

4种预设运行模式

标准模式：全套工具，日常开发调试 PTC模式：程序化工具调用，模型生成代码编排多轮工具 极简模式：只保留shell、文件编辑工具，用来做模型基准测试 创造模式：运行时调试插件，在线组装新的运行Profile

03 Cordis内核深度拆解：时空可组合性的数学证明

“一切皆插件”听着像口号，但背后有硬核技术底座。想要吃透dsh，就必须读懂Cordis——内置在dsh底层的元框架。

先看一组很扎心的数据。 VS Code插件市场安装量前100的扩展（统计2026年6月9日）： 87个包含可执行代码，禁用或者卸载之后，必须重启整个扩展宿主，所有已加载插件跟着重启。 只有7个主动声明自己依赖了哪些其他扩展。 插件互相调用的 getExtension(...).exports，返回类型默认any，等于放弃编译期校验。

病根很清晰：绝大多数插件系统，擅长装，不擅长拆。 安装的时候一切顺利；卸载的时候，插件注册的事件监听、定时器、全局状态、网络连接，不会自动清理。 清理逻辑全靠开发者手动写，一旦漏掉，就会产生静默资源泄漏。

这就是时间维不可组合：组件退出，没法完整回退它对环境造成的改动。空间维同样缺失：组件依赖的声明、发现、解析，缺少一套统一标准机制。

Cordis给出了解决方案，把两个维度做形式化定义，配套运行时机制，还有数学证明保证正确性。

时间可组合性：可逆效应（Revertible Effects）

函数式领域有两个经典概念：effect（效应）和coeffect（共效应）。 简单理解：效应，就是代码对外界产生的修改；共效应，就是代码对外界能力的依赖。

传统方案里，它们只停留在编译期类型系统。 Cordis直接搬到运行时落地。

核心规则一句话： 每一次对共享上下文ctx的修改，都必须附带对应的逆操作。

注册事件监听，逆操作就是注销监听。 打开文件，逆操作就是关闭文件。 运行时会记录组件所有变更和逆操作，组件卸载时，后进先出依次撤销，环境精准回到加载之前的状态。

对比大家熟悉的React useEffect：思路相近，但限制很多。 useEffect不能放在分支、循环、嵌套函数里，不支持异步，效应也没法自由组合。 Cordis的效应是普通代码：支持嵌套、支持异步。 开发者只写原子效应的逆操作，组合效应的撤销逻辑，由运行时自动生成。 资源清理，从靠开发者自觉，升级成系统强制保障。

空间可组合性：反应式共效应（Reactive Coeffects）

依赖侧规则：每个组件提前声明自己需要的依赖集合。 比如“我需要database服务”。

环境发生变化时，运行时对照清单校验组件： 依赖齐全 → 触发激活 依赖缺失 → 自动停用 无关变更 → 不打扰组件

插件需要的服务没准备好，就安静保持未激活，等依赖就绪自动启动，不会直接报错崩溃。

还支持两种高级能力： ✅ isolation（隔离域）：同一个key，给不同组件映射独立实例，组件拥有自己独立运行空间 ✅ interception（拦截）：中间层接管组件访问依赖的请求，做权限校验、审计、限流。拦截器随时装卸，不会重启组件

Cordis五个核心概念（官方文档校准）

插件是实现Service的对象：可以是带inject、apply(ctx)的函数，也可以是Service子类，生命周期挂载到Cordis上下文。 上下文是服务容器：服务绑定稳定ctx字段（ctx.tools、ctx.llm、ctx.sessions）；插件通过key查找服务，不直接导入实现。 inject声明依赖：插件声明依赖后，等待依赖就绪才启动；加载顺序由依赖关系自动推导，不用手动编排。 类型化事件通信：服务通过TypeScript声明合并注册事件，支持emit、waterfall、parallel、serial四种分发模式。 注册属于可逆副作用：提示词片段、工具schema、适配器、监听器通过ctx.effect()、ctx.on()注册，重载、卸载时自动撤销。

四种事件分发模式： emit：不等待，顺序观察，无返回值 waterfall：不等待，顺序观察，支持返回值；支持next()下游委托，可短路，适合决策类中间件 parallel：等待全部完成，并行执行，无返回值 serial：等待全部完成，顺序执行，无返回值

waterfall是环绕中间件模式。 监听器接收(...args, next)，调用next执行下游；拥有决策权的监听器可以直接返回终止流程，纯观测类监听器必须委托下游。

五条定理，数学层面的正确性保证

这套元理论证明了五层系统保证： 保持性：转换过程不破坏系统约束，卸载后不会残留定时器、监听等资源 恢复精确性：组件卸载，环境精准还原到加载前状态，全局时间可组合 排序与解析一致性：被依赖服务先激活，依赖方后激活；加载过程中依赖实例不会偷偷替换，全局空间可组合 进展性：无环依赖图不会死锁，组件转换步数有上界，最终抵达静止状态 汇合性：无组件失败时，无论编排操作先后顺序，最终静止状态一致。动态组装、静态组装结果等价

汇合性定理价值最高。 就像插拔插线板，只要最终接线一致，结果就一样，插拔顺序不会留下副作用。 热更新、运行时改配置这类高风险操作，从理论层面拿到了正确性保障。

四年生产验证：Koishi生态

这套范式已经在Koishi落地验证。 Koishi是跨平台聊天机器人框架，社区累计4000+插件。 Koishi当前运行在Cordis v3；dsh使用Cordis v4，核心组合规则简化、加载器重构。

在Koishi控制台禁用一个插件，插件注册的定时任务会自动撤销。 对比VS Code禁用扩展必须重启宿主，本质差别就是Cordis把自动撤销做成系统底层能力。

04 能力接缝（Seam）：换底座，不用改工具

dsh最优雅的设计，就是seam，也就是能力缝合点。 框架内置二十多个接缝：文件系统、进程执行、终端、沙箱、审批、凭据、存储、技能、联网搜索、子智能体、压缩策略……

每一个接缝，由三方角色组成： Service Definition：定义接口规范 Service Provider：提供具体实现 Consumer：消费能力（大多是面向模型的工具）

工具只依赖接口定义，完全感知不到后端实现。 一条设计纪律：单一角色不构成接缝，新增能力，必须同时定义接口、实现、消费逻辑。 三者就位之后，替换Provider，就可以整体切换底层能力。

两个最直观的落地案例 ① 本地⇄云端，工具代码一行不用改。 文件系统、进程执行共享同一个执行域。 把接缝Provider从本机切换成E2B云端沙箱，Bash、PTY、LSP代码导航全部迁移，工具层完全不用修改。 交付本地版、云端隔离版，业务代码零改动。

② 存储、检索、遥测都可以随时替换。 会话持久化可选JSONL、SQLite；遥测对接OpenTelemetry；联网搜索可切换Exa、Perplexity、DeepSeek；模型适配器兼容多家后端。 应用只选择Provider，业务代码无感知。

✅ 商业价值： 创业者不用绑定单一AI底座。 基于dsh搭建的底座，模型、执行环境、存储、遥测都可以按需切换，切换成本极低，这就是接口经济的价值。

05 会话日志即真相：把「可审计」做成运行时约束

企业客户真正关心的，从来不是AI能不能输出漂亮答案。 而是AI的所有行为，能不能被证明、被追溯。

dsh给出的方案：会话日志即真相。 会话日志是仅追加（append-only）事件流。 模型接收的全部信息：系统提示词、思维链、工具调用、返回结果、子Agent调度、上下文注入，全部记录。

运行时强制一条铁律：模型可见即已记录（Model-visible means logged）

任何送入模型的信息，都可以从日志完整重建；运行时内置断言校验，违反直接报警。 这不是文档里的一句承诺，是运行时强制规则。 新增模型可见输入，必须新增会话事件，不存在隐藏后门。

在日志之上，衍生出全部核心能力： fork：从历史节点分叉全新会话 ctx.sessions.fork(source, boundary, childSessionId) 恢复：任意会话精准回滚 检索：历史会话检索 回放：重放任意时间点执行流程 转录：导出完整文字记录 遥测：统计token、耗时、成本 会话标题，也是基于日志折叠生成

事件系统分为三个域 会话事件：持久化日志，重启后仍然保留 Agent事件（agent/*）：绑定活跃Agent实例，观察、拦截正在运行的任务 能力事件：不需要侵入Agent循环，向seam附加策略、适配器

事件语义做了分级： waterfall事件必须显式调用next委托下游；serial事件没有next。 谁能中断流程、谁只能观测，在设计阶段就确定。

✅ 商业价值： 金融、医疗、法律这类行业采购AI，优先要求可证明、可审计、可回放。 这套机制，是智能体从内部测试玩具，升级为生产系统的门槛。

06 运行时自我进化：现场改造自己

dsh有一个很多框架不敢做的能力： 运行过程中动态加载插件，全程不用重启进程。

完整生命周期： define（定义）→ run（运行）→ update（更新）→ rollback（回滚）→ undefine（删除）

插件版本管理规则： pluginId对应多个不可变packageId快照，版本只读、不会覆盖。 授权分两级：单次授权当前版本、或者授权该插件后续所有版本。

更新失败不会破坏旧版本，支持手动回滚任意历史版本。 新增Host侧代码隔离在vm沙箱运行；前端页面通过远程命名空间访问同一套服务。

底层支撑依旧是可逆副作用。 插件注册的服务、事件、定时器、UI、主题全部绑定自身生命周期纤维Fiber，卸载时自动清理干净。 停止、更新、回滚都是干净操作，不存在热更新残留脏状态。

✅ 商业价值： 别的框架是让AI使用平台能力。 dsh支持AI改造平台本身。 对创业者，交付的产品可以在客户现场持续迭代。 对产品经理，工具即服务的雏形显现，能力可以版本化、授权、回滚。

07 企业落地手册：审批、沙箱与组合式配置

技术骨架讲完，企业落地可以拆成三层理解。

第一层：组合式配置 配置不是单一大文件，是分层叠加：profile（具名组装）→ bundle（插件包）→ patch（自定义覆盖层）。 叠加顺序：官方基线→公司标准→项目定制→个人偏好，互不冲突。

一条命令打印完整配置树，树上任意节点都可以用patch覆盖。 升级官方基线，客户定制内容不会被覆盖。

第二层：双层运行平面 共享基础设施（持久化、沙箱、审批栈、模型路由、子智能体注册表）放在Host组合。 会话专属能力（工具、人设、提示词）放在agent preset；preset私有服务使用isolate realm隔离，不会污染其他会话。

同一套底座，给不同客户交付独立能力，不需要维护多套产品。

第三层：安全治理参数化 沙箱分级：只读、工作区写入、完全访问 审批策略按场景配置 一键权限预设：workspace-write / danger-full-access开关，同步联动沙箱模式、审批策略，安全基线统一管控 凭据接缝实现引用与真值分离：配置只存引用，Provider保管密钥；密钥轮换后，下一次请求自动生效

配套交付组件： 技能系统：行业Know-how封装成可版本化、可复用模块，沉淀经验跨客户复用 三种形态：Web界面、命令行headless、Python SDK，覆盖个人使用、嵌入式集成场景

08 硬核工程细节：藏在底层的硬货

Spill外溢：工具输出超长时，自动溢出到存储，只给模型返回定位取回标识，避免粗暴截断，长任务上下文稳定

无模型工具结果修剪：上下文压缩前，用可回放节点替换超长工具返回，不消耗模型token，直接降本

冷读阶梯：会话列表加载不需要读取全部日志，依靠checkpoint+尾部回放，万级会话不卡顿 Typert类型安全RPC：zod运行时类型注册 + API网关，远程调用全程类型校验

长会话成本治理：token计量、压力触发自动压缩、跨轮次目标驱动goal、自动续跑，长跑任务开销可控、进度可恢复 并行编排引擎：工作流脚本独立线程运行，一个脚本批量派发给大量子智能体再收拢结果

前端也是插件树：浏览器UI本身是插件图，支持热更新，修改界面无需全量编译打包

09 互操作时代：和整个生态做同事

dsh不把其他AI产品当成对手，而是生态伙伴。

子智能体接缝支持多种后端：进程内派生spawn、会话fork、ACP、Codex CLI、Claude Code、DSH SDK。 会话中途可以把任务交给其他Agent执行，执行完成无缝回流，审计链不会断掉。

ACP（Agent Client Protocol）是互操作传输层，不是展示层。 既可以把dsh智能体暴露给任意ACP客户端调用，也可以把外部ACP智能体作为子节点接入dsh。 同时提供hooks桥接Claude Code、Codex，复用同一套沙箱、持久化能力。

模型侧灵活：默认DeepSeek，原生兼容OpenAI接口，修改配置立即生效，模型路由不绑定单一厂商。

✅ 商业价值： 保护企业已有投入，渐进式落地。 贵模型处理高难度推理，低成本模型处理简单任务；新任务上新智能体，老流程继续跑原有工具；验证稳定后再整体切换。 互操作，就是企业AI落地进可攻退可守的方案。

10 实战上手：从安装到自定义配置

环境要求 Node.js（推荐最新LTS版本，官方要求Node.js 22.19+ / 24+） 可选：pnpm（源码编译安装）

一键启动

npx @deepseek-ai/dsh web

默认访问地址 http://127.0.0.1:3080

源码安装

git clone [https://github.com/deepseek-ai/deepseek-harness.git](https://github.com/deepseek-ai/deepseek-harness.git)cd deepseek-harnesspnpm installpnpm run buildpnpm dsh web

查看与修改配置树

# 打印当前完整插件树dsh --profile web --dump-config# 通过patch覆盖配置dsh --profile web --patch ./my-patch.yaml

Loader配置机制 @deepseek-ai/cordis-plugin-include 解析!!js表达式节点。 Loader在注入激活后，基于ctx.serviceName插值配置；每次挂载决策时，基于loader上下文插值disabled字段。 环境选择插件优先使用overlay。

第一个插件基础结构

import { Context } from 'cordis'export function myPlugin(ctx: Context) {ctx.effect(() => {// 注册定时器const timer = setInterval(() => {console.log('tick')}, 1000)// 卸载时自动执行逆操作return () => {clearInterval(timer)}

实践规则（官方校准） 能力按领域拆分插件：工具流水线事件归属ctx.tools，模型流式输出归属ctx.llm，Agent协调归属ctx.agents 策略拦截优先使用事件；直接调用能力优先使用服务方法 所有注册配套销毁逻辑，通过ctx.effect返回disposer，或者Cordis内置辅助方法自动处理 销毁顺序有依赖时，统一放到同一个effect，保证资源释放顺序

踩坑提醒 开发者预览版：官方明确标注处于开发者预览，持续迭代，后续会出现破坏性API变更（README加粗提示），不建议直接上生产环境MIT协议，TypeScript开发：支持商用，但是需要留意版本升级带来的兼容性改动 生态尚在起步：官方推荐插件作者给仓库打上dsh-plugin主题标签，方便检索；第三方插件陆续涌现，但是成熟度不足

11 选型方案：四类读者判断参考

给投资人 护城河在架构，不在模型。 模型持续迭代、工具容易复刻，但「二十多个接缝 + 无特权内核 + 日志即真相」这套工程体系很难快速复刻。 MIT开源+DeepSeek流量，给生态冷启动提供基础；Harness属于Agent赛道的基础设施卖水人，不管哪家模型胜出，这套运行时都可以承载。

客观风险：产品处于开发者预览，API不稳定，商业化路径还在早期。

给创业者 不要从零自研Agent运行时。 自研要同时维护模型适配、沙箱、会话持久化、审批、遥测多套系统，dsh把这些封装成可替换积木。 核心杠杆：基于seam做深度定制（私有模型、私有沙箱、行业技能），多模型委派实现成本优化，本地部署打出数据主权卖点。

给产品经理 Web界面 / 命令行headless / Python SDK三种形态覆盖个人、嵌入式集成；审批、沙箱、审计日志支撑企业交付；技能系统沉淀行业知识，垂直场景的壁垒可以基于这套底座持续搭建。

给企业AI落地负责人 企业交付最大痛点：一套方案无法适配所有客户，安全基线、数据主权、存量系统各不相同。 dsh提供四样工具： 分层配置：每个客户独立patch，基线不动 审批、沙箱、一键权限预设：安全基线参数化 会话日志即真相 + 遥测：交付给客户CIO的审计凭证 技能系统：客户沉淀的行业经验，复用给其他项目

加上接缝支持替换私有模型、内网沙箱，ACP兼容存量AI工具，不用推倒重来。 交付的不再是一次性集成，而是可以跟随客户业务持续演化的架构图纸。

12 边界与展望（坦诚）

单独看工具能力，读写文件、执行命令、联网搜索，很多框架都具备。 dsh独有的，是可组合性六件套：无特权内核、能力接缝、日志即真相、运行时自我改造、组合式配置、可逆副作用。

它不是万能的：Agent推理上限由底层模型决定，模型本身的短板无法靠框架补齐。 dsh提供的，是让任意模型更安全、可控、可组合的运行载体。

Cordis范式本身也有明确边界： 对比DSU动态更新、Webpack HMR，Cordis组件重载是从干净状态重建；组件内存状态不会跨reload保留，状态迁移属于后续规划工作 依赖环可以自动检测，但细粒度拆环会让组件数量快速膨胀，系统复杂度上升 当前依赖绑定依靠key名称，缺少版本语义校验，依靠npm peer dependencies兜底，结构化兼容检查是待解决问题

dsh刚刚开源，还在快速迭代。 今天版本有局限，但是整套架构设计是开放的，开发者可以持续扩展。

13 写在最后

智能体赛道正在经历从「模型驱动」到「架构驱动」的范式转移。 当模型能力逐步趋同，差异化的核心变成架构开放度、可组合能力、可审计能力、存量系统兼容能力。

DeepSeek Harness用「一切皆插件」，给出了一套带有数学证明、经过四年生产验证、完整工程落地的方案。 它不是Claude Code的竞品，而是可以承载Claude Code、Codex、自研Agent协同运行的智能体操作系统。

对于开发者，更低定制成本、更高架构自由度； 对于企业，不被单一厂商锁定的AI基础设施； 对于整个行业，Agent生态从封闭孤岛走向开放市场。

图纸已经铺开，后续的扩展，由所有开发者共同书写。

参考来源：

DeepSeek Harness GitHub:

https://github.com/deepseek-ai/deepseek-harness

DSH架构文档（中文）:

https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.zh.md

Cordis官方入门文档:

https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer

Cordis元框架:

https://github.com/cordiverse/cordis

Cordis学术论文:

https://github.com/cordiverse/paper

终身学习，深耕AI领域

持续分享，优质AI开源

感谢关注，携手AI同行