[AI/Agent/驾驭工程] DeepSeek Harness(dsh)：一切皆插件的开源 Agent 运行时底座——未来AI Agent/Harness工程领域的“Linux”
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 的解决对象：
- 框架耦合严重：模型调用、工具执行、会话管理硬编码在核心循环中，扩展要改框架本体；
- 能力替换困难：换模型厂商、换沙箱、换文件系统实现，往往要 fork 框架或写大量适配代码；
- 会话状态管理粗放：缺乏精确的事件日志，难以可靠回放、分叉、上下文压缩；
- 安全边界模糊：工具执行缺统一安全策略管道，沙箱与审批各自为政；
- 多代理协作缺基础设施：子代理委托、工作流编排需从零构建。
DeepSeek 的选择是把重心放在"模型之外的那层工程底座"，并彻底开源、拆成零件——用"无特权核心"的激进架构回应"不想被单一厂商锁死"的行业焦虑。
URLs
- GitHub：https://github.com/deepseek-ai/deepseek-harness
- 官网/Web UI：
npx @deepseek-ai/dsh web后访问http://127.0.0.1:3080（官网 deepseek.com/harness） - npm 包：
@deepseek-ai/dsh - 社区：GitHub Discussions、Discord 社区、企微/公众号
发展历程
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-codexprovider）。 - 沙箱安全策略：文件系统写隔离、进程执行限制、审批策略分级（
workspace-write/read-only/danger-full-access）；OS 级真实隔离（WindowsCreateRestrictedToken，LinuxLandlock+bwrap，macOSSeatbelt）。 - 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 极简模式下跑出的——框架与模型互相验证。
核心优势
- 真正的可热插拔、无锁死：包括 Agent Loop 在内的一切都是插件，换模型/工具/沙箱/循环都不改内核、不改源码，只改配置。
- 模型无关、打破厂商绑定：40+ 模型厂商、OpenAI 兼容端点，甚至能把 Claude Code / Codex 当子 Agent，中立姿态是生态想象力来源。
- 可审计、可回放：强制"模型可见 = 必入日志（Model-visible means logged）"运行时不变量，append-only 日志支持 resume/fork/检索/replay，可精确重建"Agent 当时看到什么、为何这样决策"——这是封闭产品（Claude Code 等）不具备的审计能力。
- 有硬理论支撑（Cordis）：88 页论文《A Programming Paradigm for Spatiotemporal Composability》解决"插件装上后拔不干净"的痛点；可逆副作用 + 依赖反应式管理，插件热插拔、卸载自动回滚、加载路径不影响终态（路径无关性）。已在 Koishi 跑四年、被 4000+ 插件生产验证。
- 完整安全体系：OS 级沙箱 + 分级审批管道 + 权限模式，安全逻辑共享同一条工具流水线主干道。
- 生态飞轮：MIT + 模型无关 + 插件化，社区插件 288 → 4000+，有人让 Agent 现场"给自己造出新器官"（
cordis_define/cordis_run自我扩展）。 - 模型+框架同日发布的组合叙事：V4-Pro 正式版 + Harness 同天上线，"大脑+身体"互相证明。
主要短板
- 仅是 v0.1 开发者预览版：官方明确警告"将会有破坏兼容性的变更"，插件 API 与配置结构未稳定，不适合直接上生产。
- 对普通用户不友好：更偏"开发者底座"，上手门槛高于 Claude Code / Codex。
- 安全与供应链风险：插件化程度越高权限治理成本越高，社区曾出现"插件误删 400G 数据"事件，装第三方插件必须审查权限。
- 绝对能力仍落后：相比 Claude Code / Codex，在 coding agent 打磨、权限模型、diff 审查、IDE 集成方面仍有差距——"赢了架构这一栏，输了成熟度这一栏"。
- 协作门槛：项目当前阶段不接受外部 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 的核心优势（相对四者综合）
- 架构级自由（无特权核心）：唯一把"包括 Agent 循环在内的所有能力"都做成可替换插件的框架。Pi 换不了循环、DeepAgents 换不了 LangGraph 循环、Claude Agent SDK / Codex 的核心闭环也不可换；dsh 改配置即可重组任何能力。
- 模型无关 + 厂商中立：40+ 厂商、OpenAI 兼容端点、甚至接入 Claude Code / Codex 作子代理——相对 Claude Agent SDK / Codex 的生态绑定是最大差异化。
- 可逆插件系统（Cordis 理论背书）：热插拔 + 卸载即回滚 + 路径无关性，为"Agent 自进化"提供安全带；有 88 页论文 + Koishi 4 年 / 4000+ 插件生产验证，这是 Pi 的 Hook 注入、DeepAgents 的 LangGraph 组装所没有的范式级保障。
- 审计与回放是机械强制：append-only 日志 + "模型可见=已记录"不变量，回放/分叉/评测/合规底座完整——Pi 靠事件暴露、DeepAgents 靠 LangSmith trace，均非框架级强制。
- 安全内建：OS 级沙箱（Landlock/bwrap/CreateRestrictedToken/Seatbelt）+ 统一审批管道 + 权限分级，且所有工具调用（含 PTC/subagent 子调用）无法绕过——比 Pi 默认裸奔、比 LangChain 系无内置安全策略都更完整。
- 生态飞轮 + 官方协同：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 前端与协议层
UI[Web UI 服务<br/>端口 3080]
H[headless 一次性执行]
ACP[ACP JSON-RPC 服务]
PY[Python SDK]
end
subgraph Cordis 插件上下文 Context
LLM[ctx.llm<br/>模型适配器]
T[ctx.tools<br/>工具注册表+执行管道]
S[ctx.sessions<br/>会话事件日志]
AG[ctx.agentLoop<br/>Turn/Step 驱动器]
SP[ctx.systemPrompt<br/>提示段落组装]
FS[ctx.fs / ctx.shell / ctx.sandbox]
SUB[ctx.subagent<br/>spawn/fork]
APP[ctx.approval<br/>审批服务]
end
subgraph 能力提供者层
P1[dsh-llm-deepseek]
P2[dsh-bash-sandbox / dsh-fs-sandbox / dsh-sandbox-local]
P3[dsh-session-persistence-jsonl / dsh-compaction-basic]
P4[dsh-tool-bash / fs / subagent / todo / workflow / ralph]
end
subgraph 持久化层
JSONL[(JSONL 事件日志<br/>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
+----------------------------------------------------------------------+
| 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模块，只需要导出约定字段，没有需要继承的抽象类。
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 依赖声明机制
export const inject = ["tools", "llm"]
- Cordis内核扫描inject数组；等待对应服务全部被其他插件provide出来。
- 全部就绪，才调用
apply(ctx)；此时ctx.tools、ctx.llm一定可用。 - 如果提供
tools的插件被卸载，本插件Fiber自动进入UNLOADING，所有effect自动回滚。
现实效果：直接替换shell工具插件，所有依赖shell的插件会自动重启使用新实现，一行代码不用改。
4. effect 可逆副作用（Cordis最核心工程创新）
传统插件痛点：插件注册定时器、事件监听，卸载时忘记清理，内存泄漏。
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启动流程：
- 读取profile/bundle配置（cordis.yml），得到插件清单；
- Registry解析插件依赖关系，构建插件树，计算加载顺序；
- 逐个实例化为Fiber；等待inject依赖就绪，调用
apply(ctx)； - 全部插件进入ACTIVE，Agent运行时就绪；
- 热重载：卸载旧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清理函数，回滚所有副作用
工程权衡与短板
- 依赖动态失活带来复杂度：某个核心服务插件被卸载，大量依赖它的插件会自动失活；运维调试需要看懂Fiber状态。
- effect必须规范使用：如果插件绕过
ctx.effect()直接创建定时器、网络连接，卸载不会自动清理，产生泄漏；这是插件开发者需要遵守的契约，框架无法强制拦截原生API。 - 运行时依赖解析，启动会有依赖拓扑计算开销；插件数量极多时启动速度下降。
- 没有沙箱隔离，插件可以执行任意TS代码，不可信外部插件存在安全风险。
总结设计本质
Cordis插件体系的核心：把模块间编译期硬编码依赖，改为运行时上下文+响应式依赖；把插件加载的单向逻辑升级为可完整回滚的可逆系统；以此实现组件的可插拔、热替换，让整个Agent运行时全部由普通插件组装而成。
关键链接（必读）
- 主仓库： https://github.com/deepseek‑ai/deepseek‑harness
- Cordis官方教程： https://github.com/deepseek‑ai/deepseek‑harness/blob/main/docs/cordis‑tutorial/index.zh.md
- 上手写第一个插件： https://github.com/deepseek‑ai/deepseek‑harness/blob/main/docs/user/develop/basic/index.zh.md
- 上游Cordis仓库： https://github.com/cordiverse/cordis
DSH（deepseek‑harness）最小自定义插件示例
环境前提：已完成 dsh 项目本地部署，Node.js >=22
参考官方文档：docs/user/develop/basic/index.zh.mdhttps://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
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 启用自定义插件
在插件列表追加你的插件名称：
plugins:
# ...其他官方插件保持不变
- my-echo-plugin
4、启动 dsh
npm run dev
启动日志会输出：
[my‑echo‑plugin] 插件加载完成 ✅
5、验证插件生效
向 Agent 下发任务：
使用 echo_tool，输出文本 hello dsh plugin
Agent 会调用我们注册的 echo_tool，返回回显内容；会话结束控制台打印会话完成日志。
关键契约要点（必须记住，Cordis 插件规范）
- 不要直接 import 其他插件模块，全部依靠
inject+ctx.xxx获取服务。 - 所有副作用（注册工具、事件监听、定时器、socket）必须包在
ctx.effect()，返回清理函数；插件卸载/热重载时自动回滚，防止内存泄漏。 - 导出
name（插件唯一标识）、inject（依赖声明）、apply()（入口函数），这三者是插件的最小契约。 - 如果卸载插件，会自动执行所有effect返回的清理函数，工具注销、事件解绑。
扩展：无工具，仅提供自定义服务的极简插件
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种方式：
- 本地文件包（pnpm link，开发调试用）
- 发布后的 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
{
"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
{
"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
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：编译插件
cd my-dsh-external-plugin
pnpm install
pnpm build
步骤2：建立本地软链接
# 在插件目录执行：注册全局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 解析该包。
plugins:
# 官方内置插件保留
- llm-deepseek
- tools
- agent-loop
# 外部独立npm包插件
- my-dsh-external-plugin
启动 dsh：
pnpm run dev
控制台输出：
[外部独立插件] my‑external‑echo 已加载
Agent 即可调用工具 external_echo。
另一方式：直接引用本地文件路径（不需要 link，适合快速原型）
不做 npm 包，直接指向 ts/js 文件，cordis 支持本地路径加载。
修改cordis.yml，填写相对 dsh 根目录的路径：
plugins:
- ./../my-dsh-external-plugin/dist/index.js
⚠️ 注意：必须是编译后的 js，不能直接丢
ts；dsh运行时不会做ts编译。
热重载说明
- 修改外部插件源码后，需要重新执行
pnpm build； - dsh dev模式下，触发插件热重载，即可加载新版本；
- 所有
ctx.effect()注册的副作用会自动清理，旧工具注销，新版本注册。
关键坑点
- peerDependencies 必须写
@deepseek‑ai/cordis，避免插件包里打包一份独立cordis，造成上下文实例不相等、inject失效。 - 外部插件不能直接导入dsh内部业务模块（如
../types）；类型需要从 dsh 包导出的类型定义获取。 - 路径引用方式必须使用编译后的 js，ts 文件运行时无法直接被 node 读取。
- 外部插件没有 src/plugins 目录下的特殊处理，完全遵循 cordis 标准插件契约：导出
name、inject、apply。
发布为公开npm包
把上面这个包正常发布到 npm，其他人使用 dsh，只需要：
pnpm add my-dsh-external-plugin
再在 cordis.yml 添加 - my-dsh-external-plugin 即可直接启用。
3 安装部署 & 使用指南
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 推荐文献
- DeepSeek Harness 官方 GitHub 仓库
- DeepSeek Harness 中文 README
- 《A Programming Paradigm for Spatiotemporal Composability》（Cordis 配套论文，北大+DeepSeek，88 页，随开源同日发布于 arXiv，检索 "Spatiotemporal Composability" 即可定位）
- Pi-Agent（badlogic/pi）GitHub
- DeepAgents GitHub（langchain-ai/deepagents）
- DeepAgents 论文
- Claude Agent SDK 官方文档
- Anthropic：Building agents with the Claude Agent SDK
- OpenAI：Codex as a platform
- Codex SDK 文档
- Codirs: Meta-Framework of Spatiotemporal Composability
X 参考文献
- DeepSeek Harness - GitHub
- DeepSeek Harness 开源项目深度介绍 - CSDN
- 一夜爆火 15 万 Star！DeepSeek Harness 深度解析 - CSDN
- 为什么 DeepSeek Harness 选择了 Cordis 作为 Agent 的内核 - 硅基深思/前途科技
- 厉害了 DeepSeek Harness！村内又一开源倔起的地标 - DeepSeek 技术社区
- 千呼万唤始出来：DeepSeek Harness 开源当天狂揽近 3 万 Star - 掘金
- DeepSeek Harness 深度解析（guoqi_666）- CSDN
- DeepSeek Harness 开放使用了 - 腾讯云开发者社区
- Pi-Agent 深度硬核解析 - 技术栈
- Pi Agent 完整指南 - SegmentFault
- DeepAgents 框架介绍与应用实战 - 博客园
- DeepAgents 概述 - LangChain 文档
- Claude Agent SDK overview - Claude
- Claude Agent SDK 深度入门指南 - CSDN
- Codex Harness 全面开源：OpenAI 的 AI Agent 底层执行框架 - CSDN
- Codex as a platform - OpenAI
- 开源杀出重围！OpenAI 亲述：如何把 Codex 变成"智能体引擎" - Tony Bai
- Codex Harness 全面开源：三层集成接口完整解析 - 博客园
浙公网安备 33010602011771号