DeepSeek Harness 是什么：建仓三天、13 万 star 的 Agent 框架

2026-08-16

第一次看到 deepseek-ai/deepseek-harness 这个仓库的人，多半会先被一组数字晃一下：截至 2026-08-16 我们采集时，GitHub API 返回的 star 是 132,054、fork 是 13,235，而 open issues 是 0。同一次采集里，这个仓库的建仓时间写着 2026-08-13T11:56:32Z——距离我们采集当天，前后只差三天。

这三个数字是并列的事实，不是因果链。star 高不代表成熟，issues 为 0 也不代表没有问题；这只是我们在那个时间点从 GitHub API 上读到的返回值。顺带说一句，star 数变动很快——我们采集当天的几十分钟内，它就从 131,928 变成了 132,054，所以本文里这个数字只有配上「2026-08-16」才有意义，实际以仓库当前显示为准。

真正能拿来判断「这是什么」的，是仓库里那些可以逐个文件核对的东西。下面全部依据快照 47f9438（默认分支 master）。

它自称是什么

README.md:5 的第一句原文是 DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI。GitHub 仓库的 description 更短，只有一句：DeepSeek Harness: Everything is a Plugin.

紧接着 README.md:7 交代了这句话的技术底座：它跑在 Cordis 上，链接指向 github.com/cordiverse/cordis，并引用了一篇叫 A Programming Paradigm for Spatiotemporal Composability 的论文。

「一切皆插件」这句宣传语在 docs/architecture.md:11 被展开成了一个更具体的声明：模型适配器、工具注册表、会话日志、以及 agent loop 本身，全部都是插件，因此每一部分都能从配置里替换掉。同一份文档 :13 还补了一句 There is no privileged core to patch——没有一个享有特权、需要你去打补丁的内核。

这不是一句只写在 README 里的口号。docs/architecture.md:100 给「能力接缝」（capability seam）下了三角色定义：一个 Service Definition 声明接口、一个 Service Provider 实现它、一个 Consumer 使用它（通常是一个模型可见的工具）；一个包可以兼任多个角色，但单独一个角色不构成 seam。根 AGENTS.md:109 把同一条写成了硬约定。想看这套说法在仓库里被登记成什么样，最省事的入口是 docs/capability-seams.md——它从 :414 到 :469 有一张 56 行的表，每行对应一个 ctx key。需要说明的是，这份文档末行自述维护模式是 hybrid：服务从 Cordis 声明里发现，而接口／实现／消费者三种角色是在 scripts/gen-doc-graphs.ts 里分类的；我们没有回 packages/*/*/src 逐个核对这 56 个服务的实现。

49 个目录，219 个包：数字最容易在这里翻车

packages/ 下面用 ls 能数出 49 个目录。但如果你据此写「dsh 有 49 个包」，就错了。

原因在 pnpm-workspace.yaml 里：工作区 glob 写的是 packages/*/*，两层，不是 packages/*。所以那 49 个目录是组目录，它们自己没有 package.json；真正的 npm 包在第二层。我们实数 packages/*/* 共 219 个目录，219 个全部带 package.json，0 个缺失。根 AGENTS.md:13 把这条规则写成一行：packages/ @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/。

我们把这 219 份 package.json 逐个读了 name 与 version：

219 个包的 version 全部是 0.1.0-rc.5，与根 package.json 完全一致，无一例外；
219 个包的 name 全部以 @deepseek-ai/dsh- 开头，不合规数量为 0。

但「包名尾段等于目录名」这条不成立。packages/host/* 与 packages/client/* 两组的包名必须带组前缀而目录名不带——host/apiproxy 的包名是 @deepseek-ai/dsh-host-apiproxy，client/runtime 是 @deepseek-ai/dsh-client-runtime。这条约定写在 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md:74。此外还有跨组不同名的例子：test-support/client-runtime 的包名是 @deepseek-ai/dsh-client-test-runtime。

组的规模差得很远。按我们的统计口径（递归数该组下所有 .ts/.tsx，排除 node_modules/dist/lib/.turbo），client 组有 39 个子包、785 个 TS 文件、137,889 行；而 identity 组只有 1 个子包、4 个文件、248 行。整个 packages/ 合计 2,240 个 .ts/.tsx 文件、496,340 行，其中 /src/ 227,637 行、/tests/ 268,040 行——测试行数比 src 还多。

一个能侧面印证「插件化」的数字来自生成物 docs/module-graph.md（1638 行，首行注明由 scripts/gen-module-graph.ts 生成、不许手改）：按各包 peerDependencies 画出的依赖图里，入度最高的节点是 invariants，被 218 个包依赖。219 减去它自己正好是 218，与 packages/AGENTS.md:18 那句「Every package owns ./invariant」在数字上对得上。

官方文档给的三条运行路径，以及必须先知道的限定

先把限定摆在前面：README.md:9-11 有一节标题就叫 Developer preview，正文原文是「DeepSeek Harness is currently in developer preview and is iterating rapidly. THERE WILL BE COMPATIBILITY-BREAKING CHANGES.」中文版 README.zh.md:9-11 对应写的是「未来将出现破坏兼容性的变更」。根 AGENTS.md:5-7 还有一节「Pre-release stance」，首句是「Remove this section at the first tagged release.」，并写明 SESSION_FORMAT_VERSION 保持在 0、不作任何兼容承诺。加上仓库版本停在 0.1.0-rc.5、/releases 接口返回空数组——下面这些命令随时可能变。

README 一共给了三条路径。不克隆仓库的那条（README.md:15-23）：

npx @deepseek-ai/dsh web

README.md:23 紧跟着写：该命令启动 Web UI，默认地址是 http://127.0.0.1:3080。前置条件只有一句 Install Node.js。

从源码跑的那条（README.md:29-35）：

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

第三条是 Python SDK（docs/user/guide/python-sdk.md:19-25），走 python -m pip install deepseek-harness-sdk；它的前置条件里明写了平台限制：Linux x64, Linux arm64, or macOS 14 or newer on arm64。也就是说这条路径的文档没有把 Windows 列进去。至于前两条路径在 Windows 上的支持面，我们没能在仓库里找到一处完整清单，只见到若干 Windows 相关的痕迹：根 package.json:58 的 check:windows-wine、ci.yml:661 的 runs-on: [self-hosted, dsh-win-ci, windows]、以及 apps/cli/tests/windows-shell.spec.ts 这个测试文件。所以别默认三条路径在 Windows 上等价可用。

那个 3080 不是文档里随口写的数字，它有明确出处：packages/bundle/web-app/cordis.patch.yml:118-120 里 port: !!js ctx.webStartup.port ?? 3080，packages/boot/cmdline/src/index.ts:14 的注释同样以它为例，测试也把它固化在 packages/bundle/web-app/tests/startup.spec.ts:59。这是配置里的默认值，不是对运行表现的承诺。

工程门槛写在根 package.json:7-10：packageManager 钉 pnpm@11.7.0，engines.node 是 ^22.19.0 || >=24.0.0。docs/development.md:11-14 补充 CI 覆盖 22.19、24、26 三个版本。这里有一处值得留意的错位：我们扫过 packages/*/*、apps/*、vendor/* 共 230 份 manifest，没有任何一份带 engines 字段；全仓只有根 package.json 声明了 Node 门槛，而根包是 private: true。

有几件事它自己就写明了

看一个 agent 框架，比看它宣传什么更有用的是看它承认了什么。这些都在仓库里写着：

默认权限档不是全封闭的。 apps/cli/reference/README.md:70 写：新会话默认 workspace-write；bash 与文件系统写入被限制在会话 workspace 与平台临时目录内，但「reads, network access, and process visibility are not confined」——读取、网络访问和进程可见性不受限制。这个项目会在你本机执行工具、跑 shell、起子进程，这一点必须照实知道。

MCP 默认不开。 同一份文档 :80 说明，CLI 把 @deepseek-ai/dsh-mcp-client 作为依赖随包发出，但默认不启用任何 MCP server，理由原文是每个 server 命令都是「trusted executable code outside the agent sandbox」。

--host 0.0.0.0 目前拒绝。 packages/bundle/web-app/src/startup.ts:69-70 里直接 program.error，报错原文含 intentionally not supported yet for safety: it would expose remote code execution to the network。

每个包都被要求写「已知限制」。 packages/README.md:69 规定包 README 必须带 ## Known Limitations and Deferred Work 小节，我们逐个 grep 219 个包 README，218 个有，只有 packages/util/brand 没有。

E2B 那组明标 POC。 packages/e2b/README.md:5 自述是 experimental 的 POC，packages/README.md:21 该组的 Release expectation 列直接写 POC（表里其余行多为 Product — stable API）。

几处文档与磁盘对不上的地方

这类差异我们只陈述、不推断原因，也不用它去评价项目：

其一，根 AGENTS.md:11-55 那段 Repository layout 里列了 34 个组名，其中 AGENTS.md:35 的 self-modification/ 与 :46 的 support/ 在 packages/ 下没有对应目录；磁盘上对应位置分别是 extensions/ 与 test-support/。反过来，磁盘上存在而这段清单未列出的组有 17 个。

其二，packages/README.md:11-59 的分组表共 47 行数据行，而真实组目录是 49 个，差的两个是 mcp/ 与 runtime-diagnostics/。同一文件 :61 自陈规则是「new groups update their README and this table」。

其三，docs/subsystems/core.md:9 首句写「A turn flows through the six packages in one loop」并列了 6 个包，而 packages/core/ 目录下实际是 8 个子包；作为对照，docs/architecture.md:41 的引导句用了限定词「Here are some core packages」，其表是 7 行。三处的口径各不相同，以我们实读的仓库状态为准。

想读这个仓库，从哪开始

docs/architecture.md 只有 129 行，开篇第一句就是「Read this before changing anything under packages/.」——它是唯一一份适合当入口的文档。读完再去 packages/README.md 看分组表，然后按你关心的方向翻对应组的 README（packages/README.md:9 明写「Group READMEs own package/ctx-key maps」）。

还有两件事影响你的预期：CONTRIBUTING.md:9 原文写着「We are sorry that we cannot accept external pull requests at the moment.」——目前不接受外部 PR；以及这个仓库是中英双语并行维护的，1078 个 .i18n.yaml 记录着每一对文档两侧的 git blob hash，docs/i18n/README.md:9 声明「Both languages carry equal authority」，所以中文侧文档不是英文的附属翻译。

回到开头那三个数字。13 万 star、0 open issues、建仓三天——它们各自都是真的，但拼不出「这个项目成不成熟」的答案。能回答那个问题的是 0.1.0-rc.5 这个版本号、空的 Release 列表、README 里那句全大写的破坏性变更警告，以及 218 份写着「已知限制与待办」的包 README。

本专题全部 45 篇

下面这份目录与专题页一致，按主题分组；每篇都是独立的，可以只挑你现在要用的那几篇看。

认识与工程门槛

Cordis 内核与「一切皆插件」

架构与包体系：数字最容易在这里翻车

会话、上下文与压缩

工具体系、执行管线与权限审批

LLM 适配、流式与重试

运行时与隔离：仓库自己说「这不是安全边界」

扩展、编排与调度

本文依据 DeepSeek Harness 官方仓库（github.com/deepseek-ai/deepseek-harness）的 README、docs/ 下的架构与子系统文档、以及 packages/ 下的源码整理，核对日 2026-08-16，对应仓库快照 47f9438（版本 0.1.0-rc.5）。本文内容为仓库源码与文档口径，我们没有安装、也没有运行过这个项目，因此不涉及界面外观、操作手感与运行速度的任何描述。该仓库建立于 2026-08-13，README 自述处于开发者预览阶段并明确说明未来会有破坏兼容性的变更，文中出现的命令、配置与默认值随时可能变动，请以仓库最新内容为准。该仓库的开源协议为 MIT，许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。该项目会在本机执行工具、运行 shell 与子进程，安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。