每日一仓

ONE OPEN-SOURCE REPO A DAY

每天 08:00 更新 数据来源 · Atlas 精选榜 2026 年 11 月 18 日

第 18 期 · 2026-11-18

deepseek-ai/deepseek-harness — DeepSeek 官方 Agent 骨架:万物皆插件的智能体底座

第 18 期:deepseek-ai/deepseek-harness——DeepSeek 官方出品的 Agent 骨架,三个月 28 万 Star,把“万物皆插件”做成了一套可运行的智能体操作系统。

一句话定位

DeepSeek Harness(简称 dsh)是 DeepSeek 官方 2026 年 8 月 13 日开源的智能体骨架:它本身几乎不实现任何具体能力,而是提供一套以 Cordis 插件框架为底座的运行环境——模型适配、工具注册、会话日志、Agent 循环这些通常被写死在核心里的东西,在这里全部是可替换的插件,启动时由 profile 与 bundle 像搭积木一样组合出来。Atlas 快照时它只有 266,298 Star,16 天后实测已涨到 282,981,平均每天新增一千多个 Star,是榜单上增长最快的项目之一。

源码结构

实测浅克隆 256 MB、工作区 22,143 个文件,是本栏目至今结构最庞大的一个代码仓(上一期最大的 openclaw 是 1.1 GB 但文件数 6.5 万,本期文件数 2.2 万、代码密度更高)。

  • packages/:55 个包目录,是仓库的心脏。按职责分六组:core/(agent、agent-loop、session、tools、system-prompt、scope 等 7 个子包)、llm/(模型适配层,含 deepseek、pi-ai 等)、session/(会话格式与持久化,含 v0→v4 四个相邻迁移包)、host/(认证、Web 服务器、插件清单等)、boot/(启动器、配置编辑器、HMR、插件管理器与插件市场)、bundle/(web、headless、sdk、sdk-minimal、acp 五个启动形态的组合定义),其余是 fs、shell、sandbox、mcp、skill、subagent、workflow、team 等能力包。packages/ 下非测试 TypeScript 共 3,352 个文件、约 265,302 行;全仓 .ts 文件 6,725 个、.tsx 914 个,另有 Python 84 个文件(Python SDK)。
  • apps/:6 个应用。cli(dsh 命令行入口)、web(浏览器端应用)、desktop(Electron 桌面版,内含 desktop-host 与 desktop-publisher)、plugin-market-generator(插件市场生成器)。
  • vendor/:内联的 Cordis 框架源码(vendor/cordis,9 个 TypeScript 文件)及 cosmokit、schemastery 等配套库——框架不是外部依赖,而是直接收进仓库、随仓库一起演进的。
  • docs/:795 个 Markdown 文件、共 172,783 行,其中 docs/subsystems/ 下 210 个文件把每个子系统讲透;每篇文档都有 .zh.md 中文版与 .i18n.yaml 翻译元数据,翻译规则写在 docs/i18n/translation-rules.md。
  • benchmarks/:12 个基准套件(agent-continuation、long-session-browser、terminal-io、session-open 等),覆盖长会话续跑、终端 IO、会话打开等关键路径。
  • .agents/skills/:22 个随仓发布的 Agent 技能(dsh-code-review、dsh-doc-writing、dsh-pre-push-checks、dsh-translate-docs 等),把代码评审、文档写作、提交前检查这些工程规范写成了可执行的技能文件。
  • 测试:2,479 个 .spec.ts 文件,vitest 配置分主配置、e2e、快照、Web 性能等多个入口;snapshots/ 下 2,016 个快照文件。GitHub Actions 有 35 个工作流。
  • 构建与包管理:pnpm workspace(pnpm-workspace.yaml,锁文件 127 万字节)、tsdown 打包、oxlint + lefthook 做提交前检查;根 package.json 版本为 0.2.2-rc.4,npm 上 @deepseek-ai/dsh 已有 45 个版本,latest 标签是 0.2.2-rc.1,next 标签是 0.2.2-rc.4。

量化上,全仓文件 22,143 个;GitHub API 口径约 2.8 万次提交、约 71 位贡献者(含匿名)、30 个 Release,最近一次是 2026 年 11 月 17 日的 v0.2.2-rc.4。三个月发 30 个 Release、平均三天一个,迭代速度在 Atlas 榜单上也是罕见的。

架构图

flowchart TB
    User[用户 终端或浏览器] --> CLI[dsh 命令行]
    CLI --> Profile[Profile 层 web headless sdk acp]
    Profile --> Bundle[Bundle 层 dsh-base 加形态包]
    Bundle --> Patch[Patch 层 cordis patch yml]
    Patch --> Cordis[Cordis 上下文 ctx]
    Cordis --> Core[核心服务层]
    Core --> Session[ctx sessions 会话日志]
    Core --> Tools[ctx tools 工具注册]
    Core --> Agent[ctx agents Agent 循环]
    Core --> LLM[ctx llm 模型适配]
    Core --> Prompt[ctx systemPrompt 提示词组装]
    Cordis --> Seam[能力缝层]
    Seam --> FS[ctx fs 文件系统]
    Seam --> Shell[ctx shell 命令执行]
    Seam --> Sandbox[ctx sandbox 沙箱]
    Seam --> MCP[ctx mcp 协议接入]
    Seam --> Skill[ctx skill 技能系统]
    Tools --> Plugin[插件生态 dsh-plugin]
    Plugin --> Market[插件市场与管理器]
    Session --> Persist[持久化 JSONL SQLite]

分层设计说明

这座仓库的分层答案就写在口号里:Everything is a Plugin。最底层是 Cordis——一个只有“插件、上下文、服务、事件”五个概念的微框架:插件是一个实现 Service 的对象或带 inject 与 apply(ctx) 的函数;上下文是服务的仓库,服务通过稳定的 ctx.<key>(如 ctx.tools、ctx.llm、ctx.sessions)被发现,而不是被 import;插件用 inject 声明依赖,加载顺序由服务依赖关系推导,不用手写启动顺序;插件之间用类型化事件通信,分 emit、waterfall、parallel、serial、bail 五种派发模式;所有注册都是可逆的 effect,插件卸载时自动反注册。

往上一层是“组合层”,这是 dsh 最有特色的地方。一次运行不是启动一个写死的主程序,而是从空的插件列表出发,按顺序叠四层:profile 自带的 bundle、profile 的 cordis.patch.yml、用户家目录的 patch、--patch 指定的覆盖。dsh-base 是 web、headless、sdk、acp 四个 profile 共享的第一层,实测 packages/bundle/base/cordis.patch.yml 里有 101 行插件声明;dsh-web-app 再叠加浏览器应用,dsh-headless 叠加一次性运行器,dsh-sdk-app 叠加 SDK 的 JSON-RPC 服务器,dsh-acp-app 叠加自动化专用的 ACP 服务器,只有 sdk-minimal 例外,自己拥有一棵完整显式的 SDK 树。任何一行都可以用自己的 patch 替换,dsh --profile web --dump-config 能把整棵树打印出来——配置本身就是可检查、可覆盖的数据,而不是藏在代码里的启动逻辑。

再往上是“核心服务层”,即 packages/core 的七个子包:core/session 管追加式 SessionEvent 日志与内存存储;core/system-prompt 管提示词段落与工具 schema 的组装;core/tools 管带作用域的工具注册与受 guard 保护的执行管线;core/agent 与 core/agent-loop 分别是 Agent 接口与默认驱动;core/scope 是按 Agent 隔离注册的原语;llm/llm 是消息与流式词汇表加适配器缝。架构文档明确写着“没有需要打补丁的特权核心”——模型适配器、工具注册表、会话日志、Agent 循环本身都是插件,扩展 dsh 的方式是在旁边挂一个插件,而不是改核心。

最外层是“能力缝”与“插件生态”。能力缝(capability seam)是三角色设计:服务定义声明接口、服务提供者实现它、消费者使用它,三个角色缺一不可。文件系统与子进程提供者共享同一个执行世界,所以把它们指向远程沙箱,就能一次性把 Bash、PTY、LSP 都搬过去,不用逐个 fork。插件生态则由 packages/boot/plugin-manager(含 git-transport、github-connection、版本管理、构建审批)与 plugin-market 支撑,社区插件打上 dsh-plugin topic 即可被发现;docs/tool-catalog.md 显示,内置的 36 个包向模型提供了 77 个工具,从 bash、ask_user_question 到 stagehand_* 浏览器操作与 plugin_manager 自身管理工具。

技术亮点

亮点一:插件注册是可逆的 effect,热重载与卸载因此是结构性的,而不是补丁。 Cordis primer 明确要求:提示词段落、工具 schema、适配器、提供者、监听器都要经过 ctx.effect() 或 ctx.on() 安装,卸载时按相反顺序自动反注册。证据有三处:一是 docs/cordis-primer.md 把“每个注册都要有 disposer”列为实践规则;二是 base bundle 默认开启仅配置层面的 dsh-hmr,headless、SDK 与 ACP 显式关闭,packages/boot/hmr 负责监听与重载协调;三是 plugin-manager 的 operations.ts 与 run-tree.ts 把安装、构建审批、版本切换都做成可回滚的操作。代价是心智负担:写插件要时刻想着“卸载时会发生什么”,事件派发模式(emit 还是 waterfall、要不要调 next())是公开契约的一部分,写错就不是小 bug——agent/pre-step 这类 waterfall 事件里忘记调 next() 会直接短路整个步骤。适用边界也很清楚:这套机制服务于“长期运行、可热更新的 Agent 宿主”,如果只是写个一次性脚本,Cordis 的抽象反而是 overhead。

亮点二:会话日志是唯一事实来源,模型能看到什么,日志里就必须有什么。 core/session 把一切写成追加式 SessionEvent:turn/*、step/*、system/message、user/message、assistant/message、assistant/attempt、tool/* 是持久事件,其余是实时扩展点;deriveMessages() 从日志投影出模型历史,分叉、续跑、转录、遥测都从这些已结算的事件派生。证据在 packages/session/ 的迁移包:v0 到 v4 每个相邻版本各有一个专属包(session-format-v0-to-v1 直到 session-format-v3-to-v4),打开旧会话时按链逐级迁移,写打开时先编码、校验、独占发布新一代文件,源文件原地不动、永不改名替换删除;docs/architecture.md 的原话是“Model-visible means logged”,新加的模型可见输入必须先有对应的会话事件。代价是格式演进成本高:三个月已经走到 v4,每个版本都要维护一条迁移链;边界是硬性进程丢失——结算前崩溃的流式内容不会留下持久的 attempt 记录,这在架构文档里是明确写出的已知取舍。

亮点三:工具目录是“启动真实上下文读出来的”,而不是手写的清单。 docs/tool-catalog.md 开头就声明:它由生成器在真实 context 上启动每个工具插件、读 ctx.tools.schemas() 得到,因为工具 schema 在静态上不可知(运行时展开的枚举、拼接的描述、配置驱动的名字、MCP 的原始 JSON Schema)。更关键的是完整性守卫:生成器用 glob 扫所有 packages/*/tool-* 包,缺一个就让校验失败,新工具无法悄悄漏文档。实测 packages/ 下 tool-* 包有 32 个,目录覆盖 36 个包、77 个工具名。代价是文档构建依赖一次真实启动,改工具就要跑 pnpm run verify-tool-catalog;但对一个“工具即产品界面”的 Agent 骨架来说,文档与运行时 schema 永远一致,比手写清单可靠得多。

值得参考的设计或实现

  • Profile / Bundle / Patch 四层组合:把“这是什么应用”拆成可叠加的数据层,而不是 if-else 分支。想给自己的 Agent 换模型、换持久化后端、换沙箱,写一个 patch 文件即可;--dump-config 让整棵组合树可打印、可 diff。做多形态产品(Web、桌面、SDK、自动化)时,这比“一个 main 函数加一堆 flag”干净得多。
  • 能力缝的三角色模板:加能力先设计定义、提供者、消费者三者,再写代码。fs 与 subprocess 共享执行世界的设计尤其值得学:一次 provider 替换搬走整类能力,而不是逐个工具改实现。
  • 相邻版本迁移链:每个 vN → vN+1 一个包,迁移逻辑与业务逻辑彻底分离;“已提交的代际文件永不改名替换删除”是一条可以抄走的持久化铁律。
  • 文档即契约的校验:工具目录、Cordis API 目录都由生成器产出并有校验守卫;i18n 上每篇文档配 .i18n.yaml 元数据与 .zh.md 译文,翻译规则成文(docs/i18n/translation-rules.md),中英双语不是事后补的。
  • 随仓 Agent 技能:.agents/skills/ 的 22 个技能把评审、写文档、提交前检查、翻译这些流程写成机器可执行的技能文件,等于把团队规范放进了仓库,值得任何多人协作的开源项目借鉴。

适合谁

  • 想自己做 Agent 产品、又不想从零写循环、工具管线与会话持久化的开发者:dsh 是目前 Star 最高的现成骨架之一,直接 npx 就能跑。
  • 研究 Agent 架构的人:Cordis 的“时空可组合性”有配套论文(arXiv:2608.25512),仓库里 210 篇子系统文档把每个设计决策都写清了来龙去脉。
  • DeepSeek API 用户:内置 llm-deepseek 适配器与账号、用量计量(token-meter)包,接自己的 DeepSeek 模型最顺。
  • 想写 Agent 插件的开发者:dsh-plugin topic 与插件市场是官方留好的分发口,插件可以只依赖 ctx 上的服务键,不用 fork 主仓。

怎么上手

最快是直接跑 npm 包(需先装 Node.js):

npx @deepseek-ai/dsh web

默认在 http://127.0.0.1:3080 打开 Web 界面;加 --no-open 只起服务不打开浏览器。想看它到底由哪些插件组成,跑 dsh --profile web --dump-config,打印出的每一行都能用自己的 patch 替换。从源码跑则:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

想换个形态,把 web 换成 headless(一次性运行,无服务器)、sdk(SDK 的 JSON-RPC 服务器)或 acp(自动化专用)。写插件前先读 docs/cordis-primer.md 与 docs/cordis-tutorial/,再看 docs/cookbook/extension-cookbook.md 里按目标索引的四篇指南(加包、加工具、加 LLM 适配器、加设置页)。注意先读 SAFETY.md:项目处于开发者预览期,明确写着未经安全审计、不得视为安全或可用于生产,跑的时候用最小权限,最好放在一次性虚拟机或容器里。

数据卡

  • 仓库:deepseek-ai/deepseek-harness(官网 https://deepseek.com/harness,文档 https://deepseek-harness.github.io/deepseek-harness/)
  • Star:282,981(Atlas 快照 266,298,16 天涨约 16,683)
  • Fork:35,073
  • 主要语言:TypeScript(另有少量 Python,Python SDK)
  • 许可证:MIT
  • Atlas 分类:AI智能体与大模型 / 其他专业
  • 创建时间:2026-08-13
  • 最近更新:2026-11-17(最近推送同日;当前版本 0.2.2-rc.4)
  • 默认分支:master
  • 订阅者:1,185;公开 Issue 数:0(反馈走 GitHub Discussions,另有 Discord 社区)
  • 规模实测:浅克隆 256 MB、22,143 文件;packages+apps 非测试 TS 约 265,302 行;2,479 个测试文件;55 个包、6 个应用、32 个工具包、77 个内置工具;795 篇文档共 172,783 行;约 2.8 万次提交、约 71 位贡献者、30 个 Release

← 返回仓库目录