[AI/Agent/驾驭工程] DeepSeek Harness(dsh)：一切皆插件的开源 Agent 运行时底座——未来AI Agent/Harness工程领域的“Linux”

数据知音2026-09-02 0:16

0 序

  • DSH 绝对创下了 Github 开源社区的历史之最，从2026.08.13发布至今短短半个月，已经获得 207K star（截止于2026.09.01笔者写下这句话时），且每天仍以几千的速度狂揽 star。这种极致开放的架构、及DeepSeek这种极致开放的公司理念，真的是把开源社群的优势发挥到了极致。

笔者个人断言------ DSH，极大概率成为AI Agent/Hardness工程领域的"Linux" ！

绝非笔者危言耸听、或搞标题党。

  • 先一起瞅瞅部署后的 WEB-UI:

让它执行一个调研任务：

  • 内容有点多、且杂，可以在【文章目录】上自主选择自己感兴趣的章节选择性阅读即可。

1 概述: DeepSeek-Hardness

产品介绍

产品定位

  • DeepSeek Harness 是 DeepSeek AI（杭州深度求索）开发、并于2026年8月13日开源的 AI Agent 运行时框架（Agent Harness） ，采用 MIT 协议，2026 年 8 月 13 日以开发者预览版（v0.1）开源。

    • 它不是单一编码助手，而是可组装、可替换、可扩展的智能体基础设施 ，用于构建各类 LLM 驱动的自主任务执行系统。

  • 官方给出核心公式与口号：

    • Model（模型）+ Harness（底座）= AI Agent（智能体）

      • 模型 = Agent 的"灵魂"（思考推理）
      • Harness = Agent 的"身体"（理解环境、调用工具、执行任务、管理状态）

    • Slogan：Everything is a Plugin（一切皆插件）

      • 回想一下数十年前，计算机操作系统 扛把子级开源项目的 Linux（开源/发布于1991年）的设计哲学/Slogan------"Everything is File "（一切皆文件）。
      • 是不是有那味儿了------DeepSeek-Hardness ，可能会成为 开源 AI Agent/Hardness工程 的扛把子！（我们拭目以待。）

诞生的背景与原因

传统 Agent 框架/产品存在 5 大痛点，正是 DeepSeek Harness 的解决对象：

  1. 框架耦合严重：模型调用、工具执行、会话管理硬编码在核心循环中，扩展要改框架本体；
  2. 能力替换困难：换模型厂商、换沙箱、换文件系统实现，往往要 fork 框架或写大量适配代码；
  3. 会话状态管理粗放：缺乏精确的事件日志，难以可靠回放、分叉、上下文压缩；
  4. 安全边界模糊：工具执行缺统一安全策略管道，沙箱与审批各自为政；
  5. 多代理协作缺基础设施：子代理委托、工作流编排需从零构建。

DeepSeek 的选择是把重心放在"模型之外的那层工程底座"，并彻底开源、拆成零件------用**"无特权核心"**的激进架构回应"不想被单一厂商锁死"的行业焦虑。

URLs

发展历程

DeepSeek Harness 的故事是一条"伏笔回收"的剧本，核心脉络来自其底层内核 Cordis（作者 Shigma / 史一凡 / 崔添翼，北京大学出身，前 Jane Street 量化工程师，2026 年进入 DeepSeek，名字出现在 DeepSeek V3 技术报告中）：

时间 事件
2020 年 Koishi（QQ 聊天机器人框架）发布，四年间积累 4000+ 社区插件，成为中文社区最成功的机器人生态之一
2022-05-18 作者把 Koishi 的插件管理内核抽出为独立元框架 Cordis（拉丁语"心"）
2023 年 作者发表《可逆的插件系统》设计文章------"可逆"成为后续全部故事的主线
2026 年 作者加入 DeepSeek，名字出现在 DeepSeek V3 技术报告
2026-08-13 DeepSeek Harness v0.1 开源（仓库转公开），MIT 协议；同天发布配套论文《A Programming Paradigm for Spatiotemporal Composability》（北大 + DeepSeek 联合，88 页）
2026-08-13 当天 Star 数 24 点冲到 2.8 万+，Fork 2100+
发布 12 小时 Star 破 5 万
发布 24 小时 Star 破 7 万，带 dsh-plugin 标签的第三方插件 288 个（随后迅速破千、破 4000）
发布 3 天 Star 破 10 万 / 约 11.6 万
发布约 6 天 Star 约 16.5 万 / 15 万+，Fork 1.5 万+，Hacker News 冲上 TOP 1

增长对比：OpenAI Codex CLI 用了约 16 个月才到 10 万 Star，而 DeepSeek Harness 只用了一两天。社区称之为"Agent 领域的 Linux 时刻"、"Agent 界的 Android"。

开源后项目持续快速迭代（截至 2026-08-19 已有 12,940 个 commit、25 位 contributors，release 已到 0.1.0-rc.8）。

主要功能

  • 全插件架构：模型适配器、工具注册表、会话日志、Agent 循环本身、Web UI、存储、沙箱、调度全部是插件，无特权核心。
  • 多模型适配 ：内置 DeepSeek 模型适配器（deepseek-v4-pro / deepseek-v4-flash），支持 OpenAI 兼容端点，40+ 家模型厂商可换（DeepSeek、Anthropic、OpenAI、Bedrock、Vertex、Azure、Gemini 等），默认 DeepSeek。
  • 工具执行管道 ：pre-execute → 守卫 → 审批 → execute（超时/重试）→ post-execute → 结果规范化 → result 全链路，每个环节可被插件拦截/增强。
  • 会话持久化：append-only 事件日志（JSONL，zstd 压缩），支持分叉（fork）、恢复（resume）、上下文压缩（compaction）、回放（replay）。
  • 子代理委托 ：spawn（全新子会话，不继承上下文）与 fork（继承历史分叉）双模式，支持后台任务与工作流编排；甚至可把 Claude Code 或 Codex 当作子代理接入 （subagent-claude-code / subagent-codex provider）。
  • 沙箱安全策略 ：文件系统写隔离、进程执行限制、审批策略分级（workspace-write / read-only / danger-full-access）；OS 级真实隔离（Windows CreateRestrictedToken，Linux Landlock+bwrap，macOS Seatbelt）。
  • Web UI 与无头模式：内置浏览器交互界面（默认端口 3080），支持 headless 一次性任务执行与 ACP（Agent Client Protocol）JSON-RPC 自动化服务。
  • Python SDK：提供 Python SDK 与捆绑运行时。
  • 四种 Agent 预设模式（per-session 级，可同进程并存）：
模式 能力 定位
标准模式 Standard 文件编辑、Shell、文件/网页检索、Skills、计划、目标、子代理、工作流 功能完整的编码 Agent
PTC 模式 标准全部能力 + Code Mode SDK，模型直接写 TypeScript 程序组合多步工具调用（多轮往返压成一轮） 让模型"写程序"调工具
极简模式 Minimal 仅 bash + str_replace_editor 两个工具 最小环境模型基准测试
创造模式 Creator 标准全部能力 + 运行时自省、插件实验、preset 创作 自定义 Agent preset

注意：DeepSeek V4 系列模型的官方 Agent 基准成绩，就是在 Harness 极简模式下跑出的------框架与模型互相验证。

核心优势

  1. 真正的可热插拔、无锁死：包括 Agent Loop 在内的一切都是插件，换模型/工具/沙箱/循环都不改内核、不改源码，只改配置。
  2. 模型无关、打破厂商绑定：40+ 模型厂商、OpenAI 兼容端点，甚至能把 Claude Code / Codex 当子 Agent，中立姿态是生态想象力来源。
  3. 可审计、可回放：强制"模型可见 = 必入日志（Model-visible means logged）"运行时不变量，append-only 日志支持 resume/fork/检索/replay，可精确重建"Agent 当时看到什么、为何这样决策"------这是封闭产品（Claude Code 等）不具备的审计能力。
  4. 有硬理论支撑（Cordis） ：88 页论文《A Programming Paradigm for Spatiotemporal Composability》解决"插件装上后拔不干净"的痛点；可逆副作用 + 依赖反应式管理，插件热插拔、卸载自动回滚、加载路径不影响终态（路径无关性）。已在 Koishi 跑四年、被 4000+ 插件生产验证。
  5. 完整安全体系：OS 级沙箱 + 分级审批管道 + 权限模式，安全逻辑共享同一条工具流水线主干道。
  6. 生态飞轮 ：MIT + 模型无关 + 插件化，社区插件 288 → 4000+，有人让 Agent 现场"给自己造出新器官"（cordis_define / cordis_run 自我扩展）。
  7. 模型+框架同日发布的组合叙事：V4-Pro 正式版 + Harness 同天上线，"大脑+身体"互相证明。

主要短板

  1. 仅是 v0.1 开发者预览版：官方明确警告"将会有破坏兼容性的变更"，插件 API 与配置结构未稳定，不适合直接上生产。
  2. 对普通用户不友好：更偏"开发者底座"，上手门槛高于 Claude Code / Codex。
  3. 安全与供应链风险：插件化程度越高权限治理成本越高，社区曾出现"插件误删 400G 数据"事件，装第三方插件必须审查权限。
  4. 绝对能力仍落后：相比 Claude Code / Codex，在 coding agent 打磨、权限模型、diff 审查、IDE 集成方面仍有差距------"赢了架构这一栏，输了成熟度这一栏"。
  5. 协作门槛：项目当前阶段不接受外部 Pull Request（单一作者/团队主导），社区主要以插件形式参与。

局限性

  • 需 Node.js ^22.19.0 或 >=24.0.0、pnpm 11.7.0，技术栈限定 TypeScript/Node（Python 仅 SDK 层）。
  • 会话格式不向后兼容：SESSION_FORMAT_VERSION 保持 0，升级后旧会话日志可能无法加载。
  • 依赖 DeepSeek 模型能力发挥（弱模型上手效果差）；默认 DeepSeek API Key（可配 OpenAI 兼容端点替代）。
  • Windows 上 bash 执行链自动禁用，改用 pwsh。
  • 早期版本尚未内置长期记忆体/知识库（社区以插件方式补充，如第三方 DDW 插件为 dsh 加上记忆与知识库能力）。
  • 动态自修改（self-modification）当前仍是"会话内临时叠加 + 写盘重启挂载"，并非运行中热替换当前装配。

适用场景

  • 编码助手平台搭建：构建可读写文件、执行命令、运行测试的 AI 编码智能体；
  • 自动化任务编排：通过子代理委托与工作流引擎实现多步骤、多代理协作的复杂任务自动化；
  • LLM 应用基础设施：为上层 LLM 应用提供会话管理、工具调用、安全沙箱等底座；
  • Agent 协议对接：通过 ACP JSON-RPC 将 Agent 能力暴露为标准化服务（编辑器 / CI 集成）；
  • 插件生态开发：开发自定义工具、模型适配器、能力提供者，扩展框架能力边界；
  • 研究与评测：极简模式下跑模型 Agent 基准，日志可逐轮回放做对照实验。

不适合：只需简单 LLM 问答的场景（过重）；不熟 TypeScript/Node 的团队；需要生产级稳定性的场景（预览版）。

同类竞品：LangChain / AutoGPT / Claude Code

维度 DeepSeek Harness LangChain AutoGPT Claude Code
架构模式 全插件架构，无特权核心 链式调用，模块化 单体应用 封闭产品
能力替换 配置文件替换，零代码修改 需编写适配代码 修改源码 不支持
会话模型 append-only 事件日志，可回放分叉 内存状态为主 简单持久化 封闭
安全策略 结构化沙箱管道，分级审批 无内置安全策略 无 内置但封闭
插件开发 Cordis 标准化插件协议 自由格式 无标准 不支持
子代理 spawn/fork 双模式 需自行实现 无 无
开源协议 MIT MIT MIT 闭源

同类竞品：Pi-Agent / DeepAgents / Claude Agent SDK / Codex

以下四者均属"Agent Harness / Agent SDK"赛道，但定位、架构哲学、生态归属差异明显。

竞品速览

项目 出品方 定位 开源 模型绑定 技术栈
DeepSeek Harness DeepSeek AI 全插件化通用 Agent 运行时底座 MIT 全开源 模型无关，40+ 厂商 TS/Node monorepo（49 包），Python SDK
Pi-Agent Mario Zechner（Earendil-Works 维护） 极简终端 Coding Agent 内核 MIT 全开源 模型无关，含本地 Ollama TS monorepo（pi-ai/core/coding-agent/tui），核心约 1500 行
DeepAgents LangChain 基于 LangChain+LangGraph 的企业级"成品 harness" MIT 全开源 模型无关（工具调用类 LLM） Python + JS/TS（deepagents.js），v0.6.12 / 26M 下载
Claude Agent SDK Anthropic 复用 Claude Code 能力的官方 SDK（库） MIT 绑定 Claude 模型生态 Python + TypeScript
Codex OpenAI 产品级编码 Agent + 开放 harness 平台 CLI 等 Apache-2.0 开源，产品闭环 绑定 OpenAI 模型（gpt-5.x） TypeScript（CLI/SDK/App Server）

核心区别

vs Pi-Agent（同赛道最像的"轻量派"）

维度 DeepSeek Harness Pi-Agent
架构哲学 富内置 + 一切皆插件、无特权核心：模型/工具/会话/沙箱/循环/UI 全部插件，标准模式开箱即带全套能力 极简内核 + 能力外置：内核仅 4 工具（read/write/edit/bash），系统提示词 <1000 token，高级能力全靠 Skill/Extension 按需装配
核心循环 Turn/Step 驱动器本身是可替换插件 ReAct 变体循环以 Hook 事件暴露（before_tool/after_tool 等），循环本体固定
内置能力 子代理、沙箱、审批、Web UI、ACP、Python SDK、4 种 preset 全内置 沙箱/MCP/子代理/权限弹窗全部不内置，靠扩展包（如 pi-mcp-adapter、pi-subagents）
安全 OS 级沙箱 + 分级审批管道，安全内建 默认继承宿主用户权限，安全靠钩子/容器自行治理（生产需自己加白名单/Docker 隔离）
Token 开销 标准模式富提示，开销较高 极低（约为 Claude Code 的 30-40%）
场景侧重 通用多场景 Agent 基础设施、平台搭建 极致轻量 coding、私有化部署、学习 Agent 源码
关系 ------ OpenClaw 的底层内核就是 Pi-Agent

总结：都是"模型无关 + MIT + harness"思路，但 Pi 把"克制"做到极致（毛坯房，好用但裸奔），dsh 把"可组合"做到极致（精装积木，安全与审计内建但重）。

vs DeepAgents（同为"成品级 harness"的另一派）

维度 DeepSeek Harness DeepAgents
底层内核 Cordis 插件元框架（自研，可逆副作用） LangGraph 状态图（图编排运行时）
可扩展性 一切皆插件，含 Agent Loop 本身，配置层即可替换 可 override/replace 任意组件但需代码层定制，核心循环由 LangGraph 提供
开发范式 配置驱动（cordis.yml 四层管道），TypeScript 代码驱动（Python/JS），依赖 LangChain 生态
能力侧重 全插件、可审计日志、OS 级沙箱、审批管道 长时任务规划（write_todos）、子代理隔离上下文、上下文自动压缩、持久化记忆、人在回路
可观测 append-only 会话日志 + "模型可见=已记录"不变量 LangGraph streaming/checkpointing + LangSmith tracing/eval
生态 dsh-plugin 插件市场（4000+） LangChain/LangGraph 生态（26M 下载、v0.6.12、Deep Agents Code 终端 agent）

总结：DeepAgents 是"LangChain 生态里开箱即用的企业级深链 Agent"，规划/子代理/记忆是它的卖点；dsh 的核心差异是架构级**的------连循环都能换、配置即重组、审计是机械强制的不变量，且不绑定任何 LangChain 式框架。

vs Claude Agent SDK（同为"可编程 harness/SDK"）

维度 DeepSeek Harness Claude Agent SDK
出品方定位 中立底座，模型无关 Anthropic 官方 SDK，绑定 Claude 生态
循环 Claude Code 式循环做成可替换插件，无特权核心 复用 Claude Code 的 agent loop（黑盒循环，作为库暴露），不可替换
内核原则 一切皆插件 + 可逆副作用 "Give your agents a computer"（给 agent 一台电脑：文件/命令/浏览器/MCP/computer use）
模型 40+ 厂商，OpenAI 兼容端点，甚至可把 Claude 生态当子代理 仅 Claude 模型（含 Bedrock/Vertex 接入）
内建能力 内置沙箱/审批/审计日志/Web UI/ACP 提供权限控制、MCP、上下文管理、多 agent 编排（需自行组装）
形式 可运行底座 + CLI + Web UI 纯 SDK（库），需开发者自己写应用层

总结 ：Claude Agent SDK 是"把 Claude Code 能力库化给 Claude 生态开发者"；dsh 是"中立、无特权核心、连 Claude Code 都能作为其子代理的底座"------两者存在"下层底座 vs 生态 SDK"的错位竞争，甚至可嵌套使用（subagent-claude-code）。

vs Codex（同为"开放 harness 平台"）

维度 DeepSeek Harness Codex
开源面 MIT 全开源，一切皆插件 harness 组件开源（Codex CLI Apache-2.0、codex exec、Codex SDK、App Server），产品闭环绑定 OpenAI
架构 无特权核心，循环可替换 "核心固定 + 接口扩展"：开放了集成层，但 agent 主循环/模型仍围绕 OpenAI 产品
模型 模型无关 40+ 厂商 绑定 OpenAI 模型（gpt-5.x / Codex 模型）
集成 ACP、Python SDK、配置重组 codex exec（CI/脚本）、Codex SDK（TS 程序化编排）、App Server（生命周期/事件协议）
成熟度 预览版 v0.1 成熟产品（Plus 订阅含入、16 个月到 10 万星）

总结 ：OpenAI 2026 年 8 月"Codex as a platform"全面开源 harness，与 dsh 几乎同期引爆；但 Codex 是"开放给开发者集成、仍以自家模型为核心的产品平台"，dsh 是"模型无关、连循环都可换的开放底座"------dsh 同样可以把 codex 当子代理（subagent-codex）。

DeepSeek Harness 的核心优势（相对四者综合）

  1. 架构级自由（无特权核心）：唯一把"包括 Agent 循环在内的所有能力"都做成可替换插件的框架。Pi 换不了循环、DeepAgents 换不了 LangGraph 循环、Claude Agent SDK / Codex 的核心闭环也不可换；dsh 改配置即可重组任何能力。
  2. 模型无关 + 厂商中立：40+ 厂商、OpenAI 兼容端点、甚至接入 Claude Code / Codex 作子代理------相对 Claude Agent SDK / Codex 的生态绑定是最大差异化。
  3. 可逆插件系统（Cordis 理论背书）：热插拔 + 卸载即回滚 + 路径无关性，为"Agent 自进化"提供安全带；有 88 页论文 + Koishi 4 年 / 4000+ 插件生产验证，这是 Pi 的 Hook 注入、DeepAgents 的 LangGraph 组装所没有的范式级保障。
  4. 审计与回放是机械强制：append-only 日志 + "模型可见=已记录"不变量，回放/分叉/评测/合规底座完整------Pi 靠事件暴露、DeepAgents 靠 LangSmith trace，均非框架级强制。
  5. 安全内建：OS 级沙箱（Landlock/bwrap/CreateRestrictedToken/Seatbelt）+ 统一审批管道 + 权限分级，且所有工具调用（含 PTC/subagent 子调用）无法绕过------比 Pi 默认裸奔、比 LangChain 系无内置安全策略都更完整。
  6. 生态飞轮 + 官方协同：15万+ star、4000+ 插件、2 周建生态；与 DeepSeek V4 模型同日发布、官方 Agent 基准在极简模式下跑出，互相验证。

选型建议

诉求 推荐
想搭建自己的 Agent 平台/底座、要求可换模型不锁死、要审计与安全内建 DeepSeek Harness
极致轻量 coding、私有化/离线（Ollama）、学习 Agent 内核源码 Pi-Agent
已在 LangChain/LangGraph 生态、要企业级长时任务编排 + 人在回路 DeepAgents
深度绑定 Claude 生态、要把 Claude Code 能力嵌入自有产品 Claude Agent SDK
深度使用 OpenAI 生态、要产品级编码 agent 且可编程集成 Codex

发展趋势

  • 开源社区活跃度 ：极速爆发------12h 5 万星、24h 7 万星、3 天 10 万+、约 6 天 15-16.5 万星，Fork 1.5 万+；dsh-plugin 标签插件 24h 内 288 个、随后破千破 4000；GitHub 12,940 commits / 25 contributors，release 快速推进到 0.1.0-rc.8。
  • 生态走势：社区插件围绕"官方缺什么补什么"（记忆、知识库、Web UI、桌面端、沙箱方案如 sandbox-micro / sandbox-mxc / sandbox-nono、E2B 远端沙箱 PoC）。
  • 总结：DeepSeek Harness 正以"MIT + 模型无关 + 一切皆插件"的底层叙事，从 v0.1 毛坯房快速长成 Agent 生态底座，方向是"让 Agent 能安全地改造自己的运行时"（自进化），但成熟度仍在爬坡。

2 工作原理与架构

概念术语

术语 含义
Harness Agent 运行时底座，连接模型与环境的"身体"层
Cordis 驱动 dsh 的插件元框架内核（vendor 进主仓库，改名 @deepseek-ai/cordis，附 18 条本地补丁）；源自 Koishi 生态
Everything is a 【Plugin】 dsh 架构原则：一切能力（含 Agent Loop）都是可替换插件，无特权核心
Context（ctx） Cordis 共享上下文对象，插件通过 ctx 注册服务/事件/副作用，通过 inject 声明依赖
ctx.effect() 可逆副作用原语：副作用操作返回清理函数（disposer），插件卸载时按注册逆序全部执行（运行时级 RAII）
Turn / Step Turn=一次输入消费周期；Step=一次模型请求+其引发的工具调用，一个 Turn 含 0..N 个 Step
SessionEvent 追加写入的事件日志类型（user/message、assistant/chunk、tool/call、tools/result、turn/、step/ 等），是系统唯一真相来源
Model-Visible ⟺ Logged 运行时不变量：任何到达模型的内容都必须可从会话日志重建
Capability Seam 能力接缝：每个能力由 Service Definition（接口）/ Provider（实现）/ Consumer（消费方）三角色构成
Profile / Bundle / Patch 配置组合机制：四层配置管道（bundle 分发 → profile 补丁 → 用户主目录补丁 → 命令行 --patch），后写覆盖
PTC 模式 工具列表 塌缩成一个 run_code，模型直接写 TypeScript 程序编排多步工具调用
ACP Agent Client Protocol，通过 JSON-RPC stdio 暴露 Agent 能力给外部的编辑器 /CI AI/Agent/编辑器/ACP Agent Client Protocol：AI 编程时代的 LSP------编辑器与编码 Agent 的标准化桥接通信协议 - 博客园/数据知音
spawn / fork 子代理 spawn=全新子会话 （不继承父上下文，经共享工作区+结构化报告传状态）；fork=继承已完成历史的分叉

架构与运行原理

基于 Cordis 插件核心的微内核架构

image from: https://deepseek.csdn.net/6a7ed13c10ee7a33f29aedfb.html

总体分层

flowchart TB subgraph 前端与协议层 UIWeb UI 服务\
端口 3080 Hheadless 一次性执行 ACPACP JSON-RPC 服务 PYPython SDK end subgraph Cordis 插件上下文 Context LLMctx.llm\
模型适配器 Tctx.tools\
工具注册表+执行管道 Sctx.sessions\
会话事件日志 AGctx.agentLoop\
Turn/Step 驱动器 SPctx.systemPrompt\
提示段落组装 FSctx.fs / ctx.shell / ctx.sandbox SUBctx.subagent\
spawn/fork APPctx.approval\
审批服务 end subgraph 能力提供者层 P1dsh-llm-deepseek P2dsh-bash-sandbox / dsh-fs-sandbox / dsh-sandbox-local P3dsh-session-persistence-jsonl / dsh-compaction-basic P4dsh-tool-bash / fs / subagent / todo / workflow / ralph end subgraph 持久化层 JSONL(JSONL 事件日志\
zstd 压缩) end UI --> Context H --> Context ACP --> Context PY --> Context Context --> P1 & P2 & P3 & P4 Context --> JSONL

  • 框架启动时按 Profile 加载有序 Bundle 层，构建插件树；每个插件实现 Service 接口，通过 apply(ctx) 挂载，按服务依赖自动排序加载。
  • 每个能力 = Service Definition + Provider + Consumer 三角色；换一个 Provider 即可改变整条能力链。
  • "执行世界"抽象：文件系统与子进程共享同一 provider，可把 provider 指向远端沙箱（已有 E2B PoC），消费方零改动。

Agent Loop 循环执行流程

复制代码 
用户输入 → turn/start → agent/pre-step(waterfall，可拒绝/改写) → step/start
→ 组装系统提示+工具schema → agent/request → llm/stream(模型流式响应)
→ assistant/chunk* → assistant/message → tool/call*
→ 工具执行管道 → tool/result* → step/end → 判断是否需要下一步 → turn/end
  • 工具执行管道：tools/pre-execute（前置策略/权限/沙箱）→ 单调守卫(deny/abstain) → ctx.approval（一次性审批）→ tools/execute（超时/重试/指标）→ 文件系统守卫 → tools/post-execute（接受/阻止/替换/追加上下文）→ 结果规范化 → tools/result（不可变结果通知）。
  • 所有执行路径（模型驱动调用、workflow 脚本调用、subagent 调用、PTC 子调用）都过同一个 ToolRuntime.execute 闸门，无法绕过审批与沙箱。
  • 会话日志：deriveMessages() 纯函数从 append-only 日志投影模型历史；每次派发请求前用 JSON.stringify 比对"即将发出的请求"与"从日志重建的结果"，不一致直接 fail，机械强制"模型看到的 = 日志记录的"。

运行时模式x4

https://deepseek.csdn.net/6a7ed13c10ee7a33f29aedfb.html

txt 复制代码 
+----------------------------------------------------------------------+
|                           DeepSeek Harness                           |
+---------------------+------------------+------------------+----------+
|  Standard Mode    |    Code Mode     |   Minimal Mode   | Creator    |
| (全功能终端 Agent) | (代码编排复杂任务) | (基准测试/高性能) | (插件开发) |
+------------------+------------------+------------------+-------------+

Cordis 时空可组合性（理论内核）

  • 时间维度（Temporal Composability） ：副作用可逆。ctx.effect() 要求副作用返回清理函数，卸载时按逆序执行，系统恢复到"插件没来过"的状态。等价于把 RAII / Rust Drop 从语言层提升到运行时层。
  • 空间维度（Spatial Composability）：依赖反应式管理。声明式依赖 + 反应式响应：B 依赖 A 则 B 在 A 就绪后才启动、A 停止时 B 先卸载、A 起不来 B 不启动；A 变化时只重启真正依赖它的插件（fiber + epoch 指纹 + inertia 锁）。
  • 两维合成 → 路径无关性：系统终态只取决于"开了哪些插件"，与加载顺序/装卸历史无关------这是热重载和"agent 改自己运行时不留烂摊子"的数学前提。
  • 事件系统 5 种分发模式：emit / parallel / serial / bail / waterfall，统一到一条内部路径；waterfall 让监听者链式 next() 委托，可拦截或包装。

DeepSeek‑Harness（DSH）Cordis 插件机制｜设计理念 & 落地实现

仓库： https://github.com/deepseek‑ai/deepseek‑harness

Cordis上游仓库： https://github.com/cordiverse/cordis
核心命题：一切皆插件 。AI Agent运行时没有特权内核；模型适配器、工具、Agent循环、会话存储、WebUI全部是【普通插件】；【用户插件】与【官方插件】地位完全平等。

Cordis顶层设计理念

  • Cordis本身不是Agent框架，它是【通用元框架】，只解决插件的加载、依赖解析、生命周期、可逆副作用；完全不理解 LLM/Agent 业务逻辑。

五大核心理念

1. 无硬编码导入，基于上下文协作
  • 插件之间禁止直接import互相引用；全部通过共享ctx(Context)访问服务。需要什么能力就声明inject依赖，【运行时注入】。

目的：组件可以直接替换，不用修改调用方代码。

2. 可逆副作用（时间可组合）
  • 插件加载 产生的所有副作用（事件监听、定时器、注册工具、网络连接）交给ctx.effect()登记；插件卸载/热重载时，框架自动执行【回滚清理】 ，杜绝内存泄漏 ，不需要【插件开发者】手写完整销毁函数。
3. 响应式依赖（空间可组合）
  • 插件声明依赖列表inject:['tools','llm']。
  • 只有全部依赖就绪，插件才执行apply()；依赖被卸载，该插件自动失活；依赖恢复，插件自动重新激活。
  • 支持运行时动态插拔替换组件。
4. Fiber状态机，完整生命周期
  • 每一个插件实例对应一个Fiber对象，拥有完整状态流转：PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED。
  • 支持热重载、部分失败隔离，单个插件故障不会直接搞垮整个运行时。
5. 配置驱动组装，不侵入源码

通过cordis.yml配置文件完成插件的启用、禁用、替换、打补丁；扩展DSH不需要修改仓库源码，只修改配置与编写外部插件。

插件契约（极简，源码真实接口）

  • 插件 就是TS模块，只需要导出约定字段，没有需要继承的抽象类。
typescript 复制代码 
import type { Context } from '@deepseek-ai/cordis'

// 元信息
export const name = "demo-plugin"
// 声明依赖：必须等这些服务就绪，apply才执行
export const inject = ["tools", "session"]

// 唯一入口：插件加载时被Cordis内核调用
export function apply(ctx: Context) {
    // 1. 注册服务：对外暴露能力 ctx.provide()
    // 2. 监听事件：ctx.on("xxx/event", callback)
    // 3. 注册工具、挂载子插件
    // 4. 所有副作用交给 ctx.effect() 包裹，用于自动清理
}

关键点：插件不是去实现某个接口的类；本质是一个接收上下文的函数，在ctx上注册副作用与服务。

五大核心原语（落地实现）

1. Context 上下文 ctx

整个系统唯一交互媒介，相当于服务容器+事件总线。

  • ctx.provide(name, service)：对外注册服务，供其他插件通过inject依赖使用
  • ctx.on(event, handler)：注册类型化事件监听；返回的句柄自动被effect跟踪
  • ctx.effect(setupFn)：登记可逆副作用；返回清理函数，插件卸载自动执行
  • ctx.extend()：派生子上下文，形成插件树；隔离作用域。

2. Fiber：插件实例状态机

每一份插件加载实例对应一个Fiber，记录状态、依赖、注册的effect清理函数、错误信息。

  • 当依赖不满足时，自动进入失活；依赖恢复自动重新激活。
  • 插件异常，Fiber标记FAILED，其他不受影响，实现故障隔离。

3. inject 依赖声明机制

typescript 复制代码 
export const inject = ["tools", "llm"]
  1. Cordis内核扫描inject数组；等待对应服务全部被其他插件provide出来。
  2. 全部就绪，才调用apply(ctx)；此时ctx.tools、ctx.llm一定可用。
  3. 如果提供tools的插件被卸载，本插件Fiber自动进入UNLOADING，所有effect自动回滚。

现实效果：直接替换shell工具插件，所有依赖shell的插件会自动重启使用新实现，一行代码不用改。

4. effect 可逆副作用（Cordis最核心工程创新）

传统插件痛点：插件注册定时器、事件监听，卸载时忘记清理，内存泄漏。

typescript 复制代码 
export function apply(ctx: Context) {
    ctx.effect(()=>{
        const timer = setInterval(()=>{},1000)
        // 返回清理函数，插件卸载自动调用
        return ()=> clearInterval(timer)
    })
}
  • 通过Cordis内置API（ctx.on等）注册的监听，自动纳入effect追踪，不用手动包。
  • 自定义外部资源（socket、定时器）必须手动包ctx.effect()返回销毁逻辑。
  • 卸载插件时，按照注册逆序执行全部清理函数，完整回滚插件带来的全部改变。

5. Registry & cordis.yml 配置加载

DSH启动流程：

  1. 读取profile/bundle配置（cordis.yml），得到插件清单；
  2. Registry解析插件依赖关系，构建插件树，计算加载顺序；
  3. 逐个实例化为Fiber；等待inject依赖就绪，调用apply(ctx)；
  4. 全部插件进入ACTIVE，Agent运行时就绪；
  5. 热重载：卸载旧Fiber（执行全部effect清理），加载新版本插件Fiber，完成替换，无需重启整个进程。

DSH业务层如何基于Cordis构建（真实业务落地）

Cordis只是底层内核；DSH在它之上，把Agent全部能力封装为普通Cordis插件：

插件 作用
llm‑deepseek 模型适配器插件，provide llm服务
tools 工具注册表插件，provide tools服务，其他插件注册工具到此
agent‑loop Agent思考循环本体，也是普通插件，可以整体替换
session 会话存储、日志服务插件
sandbox 代码沙盒执行插件
web WebUI服务插件

震撼点：Agent循环本身不是写死内核，只是一个可替换插件。你可以写自己的agent‑loop插件，在配置替换，完全改写Agent思考逻辑，不需要修改DSH源码。

完整启动数据流

复制代码 
读取cordis.yml配置
    ↓
Registry 解析依赖，构建插件树拓扑排序
    ↓
逐个生成Fiber实例，等待inject依赖就绪
    ↓
调用每个插件 apply(ctx)；插件执行provide/on/effect注册能力
    ↓
全部插件ACTIVE → Agent运行时就绪，接收任务
    ↓
任务执行过程中，插件之间通过ctx服务 + 事件总线通信
    ↓
卸载/热重载插件 → Fiber执行全部effect清理函数，回滚所有副作用

工程权衡与短板

  1. 依赖动态失活带来复杂度：某个核心服务插件被卸载，大量依赖它的插件会自动失活；运维调试需要看懂Fiber状态。
  2. effect必须规范使用 ：如果插件绕过ctx.effect()直接创建定时器、网络连接，卸载不会自动清理，产生泄漏；这是插件开发者需要遵守的契约，框架无法强制拦截原生API。
  3. 运行时依赖解析，启动会有依赖拓扑计算开销；插件数量极多时启动速度下降。
  4. 没有沙箱隔离，插件可以执行任意TS代码，不可信外部插件存在安全风险。

总结设计本质

Cordis插件体系的核心：把模块间编译期硬编码依赖，改为运行时上下文+响应式依赖；把插件加载的单向逻辑升级为可完整回滚的可逆系统；以此实现组件的可插拔、热替换，让整个Agent运行时全部由普通插件组装而成。

关键链接（必读）

  1. 主仓库： https://github.com/deepseek‑ai/deepseek‑harness
  2. Cordis官方教程： https://github.com/deepseek‑ai/deepseek‑harness/blob/main/docs/cordis‑tutorial/index.zh.md
  3. 上手写第一个插件： https://github.com/deepseek‑ai/deepseek‑harness/blob/main/docs/user/develop/basic/index.zh.md
  4. 上游Cordis仓库： https://github.com/cordiverse/cordis

DSH（deepseek‑harness）最小自定义插件示例

环境前提：已完成 dsh 项目本地部署，Node.js >=22

参考官方文档：docs/user/develop/basic/index.zh.md

https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/index.md

插件功能示例：注册一个简单工具 echo_tool，Agent 可以调用该工具做回显；同时监听会话事件打印日志。

1、目录结构

复制代码 
deepseek-harness/
├─ src/
│  └─ plugins/
│     └─ my‑echo‑plugin.ts   # 我们编写的自定义插件
└─ cordis.yml               # 修改配置启用插件

2、插件完整代码 src/plugins/my-echo-plugin.ts

typescript 复制代码 
import type { Context } from '@deepseek-ai/cordis'
import type { ToolDefinition } from '../types'

// 插件元信息
export const name = 'my-echo-plugin'
// 声明依赖：需要 tools 服务，工具注册依赖该服务
export const inject = ['tools']

/**
 * 插件入口函数，Cordis内核会在依赖就绪后调用 apply
 * @param ctx Cordis上下文对象
 */
export function apply(ctx: Context) {
  // -------- 1. 注册一个 Agent 可调用工具 echo_tool --------
  const echoTool: ToolDefinition = {
    name: 'echo_tool',
    description: '简单回显传入的字符串，用于演示自定义工具',
    parameters: {
      type: 'object',
      properties: {
        message: {
          type: 'string',
          description: '要回显的消息文本'
        }
      },
      required: ['message']
    },
    // 工具执行逻辑
    async execute(args: { message: string }) {
      return {
        success: true,
        output: `[my‑echo‑plugin] 收到消息: ${args.message}`
      }
    }
  }

  // 使用 effect 包裹注册逻辑，插件卸载时自动注销工具
  ctx.effect(() => {
    // 向tools服务注册工具
    ctx.tools.register(echoTool)
    // 返回清理函数：卸载时执行注销
    return () => {
      ctx.tools.unregister('echo_tool')
      console.log('[my‑echo‑plugin] 工具已注销')
    }
  })

  // -------- 2. 监听会话完成事件，打印日志 --------
  ctx.effect(() => {
    const handler = (event: { sessionId: string; result: string }) => {
      console.log(`[my‑echo‑plugin] 会话 ${event.sessionId} 完成，结果摘要：${event.result.slice(0, 80)}`)
    }
    ctx.on('session:finish', handler)
    // 返回清理函数，卸载时取消事件监听
    return () => ctx.off('session:finish', handler)
  })

  console.log('[my‑echo‑plugin] 插件加载完成 ✅')
}

3、修改 cordis.yml 启用自定义插件

在插件列表追加你的插件名称：

yaml 复制代码 
plugins:
  # ...其他官方插件保持不变
  - my-echo-plugin

4、启动 dsh

bash 复制代码 
npm run dev

启动日志会输出：

复制代码 
[my‑echo‑plugin] 插件加载完成 ✅

5、验证插件生效

向 Agent 下发任务：

使用 echo_tool，输出文本 hello dsh plugin

Agent 会调用我们注册的 echo_tool，返回回显内容；会话结束控制台打印会话完成日志。

关键契约要点（必须记住，Cordis 插件规范）

  1. 不要直接 import 其他插件模块 ，全部依靠 inject + ctx.xxx 获取服务。
  2. 所有副作用（注册工具、事件监听、定时器、socket）必须包在 ctx.effect()，返回清理函数；插件卸载/热重载时自动回滚，防止内存泄漏。
  3. 导出 name（插件唯一标识）、inject（依赖声明）、apply()（入口函数），这三者是插件的最小契约。
  4. 如果卸载插件，会自动执行所有effect返回的清理函数，工具注销、事件解绑。

扩展：无工具，仅提供自定义服务的极简插件

typescript 复制代码 
import type { Context } from '@deepseek-ai/cordis'

export const name = 'simple-service-plugin'
export const inject = []

// 自定义服务类型
interface HelloService {
  sayHello(name: string): string
}

export function apply(ctx: Context) {
  const service: HelloService = {
    sayHello(name: string) {
      return `Hello, ${name}!`
    }
  }
  // 对外提供服务，其他插件可以通过 inject:["helloService"] 使用
  ctx.provide('helloService', service)
  console.log('[simple-service-plugin] service provided')
}

其他插件就可以声明 inject:["helloService"]，通过 ctx.helloService.sayHello("test") 调用。

注意：TS 类型需要自行补充模块扩展，否则会报类型缺失。

补充:DSH 外部独立包插件示例（不放入 src/plugins）

场景：把插件做成独立 npm 包，可本地目录开发，不需要修改 dsh 源码目录，直接在 cordis.yml 引用。
2种方式：

  1. 本地文件包（pnpm link，开发调试用）
  2. 发布后的 npm 包
    前提：deepseek‑harness 使用 pnpm，Node≥22。

目录布局（完全脱离 dsh 源码）

复制代码 
./my-dsh-external-plugin/     # 独立插件包，和 deepseek‑harness 文件夹平级
├─ package.json
├─ tsconfig.json
└─ src/
   └─ index.ts                # 插件主入口

1. my-dsh-external-plugin/package.json

json 复制代码 
{
  "name": "my-dsh-external-plugin",
  "version": "0.0.1",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc"
  },
  "dependencies": {},
  "peerDependencies": {
    "@deepseek-ai/cordis": "workspace:^"
  }
}

peerDependencies 声明依赖 cordis，复用 dsh 内部的 cordis，不重复打包。

2. my-dsh-external-plugin/tsconfig.json

json 复制代码 
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "declaration": true
  },
  "include": ["src/**/*"]
}

3. 插件源码 my‑dsh‑external‑plugin/src/index.ts

typescript 复制代码 
import type { Context } from '@deepseek‑ai/cordis'

// 插件元信息
export const name = 'my-external-echo'
export const inject = ['tools']

export function apply(ctx: Context) {
  console.log('[外部独立插件] my‑external‑echo 已加载')

  ctx.effect(() => {
    // 注册一个简单工具
    ctx.tools.register({
      name: 'external_echo',
      description: '来自外部npm包的回显工具',
      parameters: {
        type: 'object',
        properties: {
          content: { type: 'string', description: '待回显内容' }
        },
        required: ['content']
      },
      async execute(args: { content: string }) {
        return { success: true, output: `【外部插件返回】${args.content}` }
      }
    })

    return () => {
      ctx.tools.unregister('external_echo')
      console.log('[外部独立插件] my‑external‑echo 已卸载')
    }
  })
}

4. 本地开发链路（pnpm link，无需发布到npm）

步骤1：编译插件
bash 复制代码 
cd my-dsh-external-plugin
pnpm install
pnpm build
步骤2：建立本地软链接
bash 复制代码 
# 在插件目录执行：注册全局link
pnpm link --global

# 切到 deepseek‑harness 项目目录
cd ../deepseek-harness

# 将本地包link到dsh项目
pnpm link --global my-dsh-external-plugin

此时 dsh 项目可以 import('my-dsh-external-plugin')。

5. 在 dsh 的 cordis.yml 加载【外部包插件】

直接写包名，Cordis 会从 node_modules 解析该包。

yaml 复制代码 
plugins:
  # 官方内置插件保留
  - llm-deepseek
  - tools
  - agent-loop

  # 外部独立npm包插件
  - my-dsh-external-plugin

启动 dsh：

bash 复制代码 
pnpm run dev

控制台输出：

复制代码 
[外部独立插件] my‑external‑echo 已加载

Agent 即可调用工具 external_echo。

另一方式：直接引用本地文件路径（不需要 link，适合快速原型）

不做 npm 包，直接指向 ts/js 文件，cordis 支持本地路径加载。

修改 cordis.yml，填写相对 dsh 根目录的路径：

yaml 复制代码 
plugins:
  - ./../my-dsh-external-plugin/dist/index.js

⚠️ 注意：必须是编译后的 js，不能直接丢 ts；dsh运行时不会做ts编译。

热重载说明

  1. 修改外部插件源码后，需要重新执行 pnpm build；
  2. dsh dev模式下，触发插件热重载，即可加载新版本；
  3. 所有 ctx.effect() 注册的副作用会自动清理，旧工具注销，新版本注册。

关键坑点

  1. peerDependencies 必须写 @deepseek‑ai/cordis，避免插件包里打包一份独立cordis，造成上下文实例不相等、inject失效。
  2. 外部插件不能直接导入dsh内部业务模块 （如 ../types）；类型需要从 dsh 包导出的类型定义获取。
  3. 路径引用方式必须使用编译后的 js，ts 文件运行时无法直接被 node 读取。
  4. 外部插件没有 src/plugins 目录下的特殊处理，完全遵循 cordis 标准插件契约：导出 name、inject、apply。

发布为公开npm包

把上面这个包正常发布到 npm，其他人使用 dsh，只需要：

bash 复制代码 
pnpm add my-dsh-external-plugin

再在 cordis.yml 添加 - my-dsh-external-plugin 即可直接启用。

3 安装部署 & 使用指南

参见: AI/Agent DeepSeek Hardness 使用指南 - 博客园/数据知音

Z FAQ for DSH

Q1: DeepSeek Harness 和 DeepSeek 模型是什么关系？

它是 DeepSeek AI 开源的 Agent 运行时底座，不是模型本身。公式：Model + Harness = Agent。默认内置 DeepSeek V4 系列适配器，官方 Agent 基准成绩（如 DSBench-Hard 等）即在 Harness 极简模式下跑出，框架与模型互相验证。

Q2: "一切皆插件"到底意味着什么？

模型适配器、工具注册表、会话日志、沙箱、存储、Web UI，连驱动 Agent 的核心循环本身都是可替换插件，没有特权核心。扩展方式是"在配置层挂新插件"，而非 fork 源码或改核心代码。媒体评价："别的框架让你在循环里插钩子，dsh 让你把整个循环拧下来。"

Q3: 能接非 DeepSeek 的模型吗？

能。官方支持 40+ 家模型厂商（Anthropic、OpenAI、Bedrock、Vertex、Azure、Gemini 等）及任意 OpenAI 兼容端点，甚至可以把 Claude Code、Codex 作为子 Agent 接入。

Q4: 适合直接上生产吗？

不适合。目前是 v0.1 开发者预览版，官方明确声明"将会有破坏兼容性的变更"，插件 API/配置结构/会话格式（SESSION_FORMAT_VERSION=0）均未稳定。

Q5: 插件安全风险大吗？

插件化程度越高权限治理成本越高。社区曾出现"插件误删 400G 数据"事件，装第三方插件务必审查权限声明，生产环境建议配合沙箱与审批策略。

Q6: 和 Claude Code / Codex 比成熟度如何？

架构上赢（可换循环、可审计、模型无关），成熟度上输（预览版、coding agent 打磨/权限模型/diff 审查/IDE 集成仍有差距）。社区共识："赢了架构这一栏，输了成熟度这一栏。"

Q7: 我需要写代码才能用吗？

不需要。一条命令 npx @deepseek-ai/dsh web 即可启动 Web UI；深度定制才需要了解 cordis.yml 配置或写插件（TypeScript）。

Y 推荐文献

X 参考文献

热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接04ZCode 周末送额度活动开启：3 亿 Token 免费领取05历年考研数学一、数学二、数学三真题试卷及答案PDF062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费10VSCode+CodeX扩展，无法启动