项目: deepseek-ai/deepseek-harnessdsh· MIT 协议 · 发布 2 天即获 4.1 万 Star核心设计: 一切皆插件Everything is a Plugin基于 vendored Cordis 构建2026 年 8 月 13 日DeepSeek 官方在 GitHub 开源了DeepSeek Harness简称dsh——一个插件化的 Agent Harness智能体框架口号只有一句话Everything is a Plugin。仓库发布两天 Star 数突破 4.1 万、Fork 3283热度直逼年初 DeepSeek 开源大模型时的盛况。本文不部署、不跑 demo直接对克隆下来的源码做一次架构级拆解它到底新在哪、代码怎么组织、一切皆插件是怎么落到每一行代码上的。一、仓库全景这不是一个小玩具先看几个硬数字截至 2026-08-14 主分支指标数值包目录packages/54 个TypeScript 源文件1247 个不含测试TS 源码总行数约 20 万行Git 提交数12293 次主贡献者Tianyi Cui5235 次提交等版本0.1.0-rc.5明确标注 Developer Preview破坏性变更随时可能发生许可证MIT技术栈上Node.js TypeScript全 ESM pnpm workspaces前端是自研 Web UIVue 系组件库另带一个Python SDKpython/sdk/走 JSON-RPC。仓库还有native/Landlock 沙箱的 Node 插件、website/VitePress 文档站。最值得注意的是代码质量工程化每个 npm 包都是deepseek-ai/dsh-*命名单测要求每个源文件 100% 行覆盖率CI 门禁并且每个包都必须自带一个invariant运行时不变量断言模块——这不是普通开源项目会做的自我要求。二、核心架构一切皆插件连 Agent Loop 本身都是插件dsh底层是Cordis——一个插件化框架源码直接 vendor 进仓库的vendor/cordis/。Cordis 的核心抽象是插件向共享上下文Context贡献服务Service、类型化事件Event和可逆副作用Effect插件之间通过ctx.xxx键互相引用注册即副作用卸载自动撤销。dsh的产品层——模型适配器、工具注册表、会话日志、甚至 agent loop 本身——全部是插件。文档里原话“不存在需要打补丁的特权内核扩展 dsh 的方式是把插件挂载到其他插件旁边。”dsh 运行时Cordis 插件树core/session会话事件日志core/agent-loopAgent 驱动器llm/llm模型适配器 seamcore/tools工具注册表执行流水线core/system-prompt提示词组装40 能力包fs/shell/subagent/web/...Profile 与组合包配置即组装运行中的dsh是一棵由多层配置叠加出来的插件树。核心概念Profile存放在 Harness home 的具名组装列出要叠放的组合包web、headless是随发行版交付的模板Bundle组合包Cordis 配置项 挂载代码的分发格式Patch按 id 定位条目、替换整个 config 或插入新条目的覆盖机制。叠放顺序空条目列表 → profile 列出的各组合包 → profile 的 cordis.patch.yml → home 级 patch → --patch overlay。也就是越晚叠的层权力越大任何一条启动配置都能被你的 patch 替换。dsh-base是每个 profile 的第一层模型、工具、持久化、沙箱、审批、设置、凭据、遥测dsh-web-app加浏览器应用dsh-headless提供无服务器的跑一次就退模式。三、事件驱动三类事件三种职责事件是 dsh 的扩展点选对事件域是改动的第一个决定事件域性质用途会话事件session/event持久、追加式必须跨重启保留的事实turn/*、step/*、user/message、assistant/*、tool/*Agent 事件agent/*实时携带活跃 Agentinbox、步骤、状态、请求、验证、续跑能力事件fs/*、tools/*、telemetry/*实时给 seam 附加策略和适配器避免导入循环设计铁律“模型可见即已记录。”抵达模型请求的一切都必须能从会话日志重建运行时不变量断言这一点。所以新增一项模型可见输入就必须新增一个会话事件。这保证了 fork、恢复、transcript、遥测都能从同一份事件流派生——日志是唯一的真相源。四、轮次与步骤Agent Loop 的心脏packages/core/agent-loop/里是默认驱动器ReactLoopAgent约 500 行agent.ts。术语先厘清步骤Step 一次模型请求 它调用的工具轮次Turn 零到多个步骤领取首条输入时打开不再欠任何工作时关闭。轮次流程简化turn/start → 领取下一条输入 一条排队消息 → agent/pre-stepwaterfall监听器可改写消息或直接拒绝 → step/start → 从日志派生模型历史 → agent/request → llm/stream → assistant/chunk* → assistant/message → tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result* → step/end → 工具还欠请求或有新输入→ 再领取 → 下一个 step → agent/turn-stoppingserial唯一没有 next() 的检查点 turn/end几个值得注意的工程细节waterfall vs serial 事件agent/pre-step、agent/request、llm/stream、tools/*是 waterfall 事件监听器必须调用next()才能委托给下游——这是实现拦截/改写的机制agent/turn-stopping是 serial 事件专门用于是否该停的终检。空内容也记账assistant/message会记录每次成功的提供方调用包括返回空内容或以 max-tokens 结束的调用——空内容不进派生历史但用量保留sourceEventSeqs精确对应 chunk 事件。错误恢复有专门路径agent/request-error处理规范上下文溢出先做可选的工具结果剪枝再选摘要只有恢复真正推进了版本才会开新重试轮次。输入走统一 inbox注入的上下文留在 inbox 里等待唤醒steering中途引导与注入消息经过同一个agent/pre-stepwaterfall。五、能力 Seam可替换能力的标准姿势一个seam是 dsh 里可替换能力的完整形态包含三个角色Service Definition声明接口Service Provider实现它Consumer使用它通常是面向模型的工具。换一个 Provider 就换掉整个产品能力——这是 dsh 最优雅的设计。文档举的例子文件系统与进程 Provider 共享同一个执行世界把ctx.fs指向远程沙箱E2BBash、PTY、LSP 就全部一起搬过去了不需要为每个能力写专门的 fork。代码里对应的真实结构packages/fs/fs 能力家族fs fs-e2b fs-observation-policy 等packages/shell/bash 能力bash-local / bash-sandboxpackages/subagent/subagent 能力家族支持 6 种 Providerpackages/web/web 搜索/抓取deepseek / exa / perplexity 三个 Provider http fetchpackages/sandbox/进程沙箱local Landlock / windows-acl / policypackages/llm/模型适配器deepseek / pi-ai / retry六、模型能看到什么内置工具生态盘点docs/tool-catalog.md是生成式目录——不是手写文档而是启动每个工具插件、读取真实ctx.tools.schemas()生成。这本身就说明工具注册是运行时行为。内置工具全家桶24 个工具族文件与代码read/write/edit/read_imagefs配合先读后写策略插件glob/grep打包了 ripgrep 二进制不依赖宿主安装run_code代码模式保留传输通道支持并发子调用str_replace_editor独立文本编辑工具lsp语言服务器provider 可换执行与终端bash/pwsh一次性命令terminal_open/read/send/...六个工具持久 PTY 终端job_list/job_kill/job_output后台任务bash/PTY/subagent 通用协作与智能体subagent/subagent_fork委派子 agent支持后台可续跑send_message/interrupt_agent/list_agents子 agent 控制report子级向父级汇报create_goal/get_goal/update_goal目标管理带轮次上限ask_user_question暂停工具调用等 UI 返回人类回答信息与记忆web_fetch/web_searchprovider 可换skill技能加载session_search/session_event_read等 5 个会话查询只读todo_write待办清单schedule_create/list/delete会话内提醒自指最激进的一组cordis_define/cordis_run/cordis_stop/cordis_inspect_*让 Agent在运行时定义、启动、停止自己的插件。默认不进任何发行树刻意 opt-in但仓库的web-cordis示例演示了一个能检查并修改内存中 Cordis 插件树的自指 agent。这是 dsh 区别于其他框架的标志性能力。七、Subagent 家族能真的拉起 Claude Code / Codexpackages/subagent/把委派做成了一个完整的可插拔能力Provider说明subagent-spawn-in-process全新进程内子 agentsubagent-fork-in-process从父 agent 历史 fork 出子 agentsubagent-acp通过 ACP 协议启动进程外子 agentsubagent-codex启动真实 Codex app-server 子 agentsubagent-claude-code通过官方 Claude Agent SDK 启动真实 Claude Codesubagent-dsh-sdk通过 TypeScript SDK 启动进程外 Harness 子 agent也就是说dsh 里的 Agent 可以把活儿委派给另一个产品Claude Code、Codex当子 agent——多智能体编排在 seam 抽象下变成选 Provider的问题。八、安全与沙箱Landlock Windows ACL 远程沙箱sandbox-localLinux 上用Landlock通过 native Node 插件限制子进程支持逐会话策略sandbox-policy解析持久策略sandbox-windows-aclWindows 的 ACL 方案e2b/fs-e2b/subprocess-e2b把文件系统与子进程 Provider 指向 E2B 远程沙箱——一个替换所有能力一起隔离正是 seam 设计的红利hooks 家族hooks-claude-code/hooks-codex兼容 Claude Code / Codex 的 hook 协议让 dsh 能接入既有工具链的钩子事件。九、三种接入姿势Web / CLI / 协议npx deepseek-ai/dsh web# Web UI默认 http://127.0.0.1:3080npx deepseek-ai/dsh headlesstask# 一次性跑任务无服务器examples/里 6 个可运行 demoheadless-agent非交互式接受任务 → 输出结果acp-agentACPAgent Client Protocol自动化服务器面向程序化客户端jsonrpc-agentPython SDK JSON-RPC 驱动的无人值守编码 agentmcp-memory通用 MCP 客户端连第三方记忆服务器web-cordis自指 agentweb-schedule会话内提醒。Python SDKpython/sdk/hatch/uv管理提供了deepseek_harness.api/client/models等封装让 Python 侧可以直接驱动 Harness。十、评价与展望亮点架构纯度罕见把 “一切皆插件” 贯彻到连 agent loop、模型适配器、会话日志都是插件配置patch 叠层与代码插件注册统一成一套组合模型。这是很多号称可扩展的框架做不到的——它们通常只是给核心留几个回调钩子。事件即契约模型可见即已记录的运行时不变式让整个系统可以从日志重建、fork、回放这是一套认真思考过可观测性的设计。seam 三件套Definition / Provider / Consumer 的严格分工让替换 E2B 沙箱 整体迁移能力这种全局替换成为可能。工程纪律100% 覆盖率门禁、每包 invariant、生成式目录文档、双语文档配对——工程化水平在开源 AI 项目里属于第一梯队。风险与不足Developer Preview0.1.0-rc.5官方明说破坏性变更随时发生SQLite schema 用单调版本号、会话格式版本无兼容承诺——现在不适合作为生产依赖。重度绑定 Cordisvendor 了 Cordis 源码rescope 成私有包框架选型一旦深入迁移成本很高。门槛约 20 万行 TS、54 个包插件开发需要吃透事件域和 seam 体系文档虽全但学习曲线陡。生态未起dsh-plugintopic 刚开放第三方插件还很少对模型提供方目前默认 DeepSeek 系deepseek / pi-ai。一句话总结DeepSeek Harness 不是又一个Agent 框架而是把框架本身也变成了可插拔组合的Agent 操作系统。它现在最大的价值是给 Agent 工程社区提供了一个极其干净的架构范本——而 0.1.0 的版本号意味着真正的生态故事才刚刚开始。参考: 分析基于deepseek-ai/deepseek-harness 47f943859b2026-08-14 克隆README.zh.md / docs/architecture.zh.md / docs/agent-lifecycle.zh.md / docs/tool-catalog.md / packages/core/agent-loop 源码等。作者: 喵本喵叁肆 · 技术博客 | 欢迎关注、收藏、评论区交流