深度拆解 DeepSeek Harness：一文看懂 快速本地上手

2026 年 8 月，DeepSeek 悄悄开源了一个新项目：DeepSeek Harness（命令行叫 dsh）。不是新模型，而是一个智能体框架（Agent Harness）——简单说，就是让大模型真正"动手干活"的那层骨架：读写文件、跑命令、调工具、拆任务、派子代理，全由它来组织和管控。

装个 Node.js，一行命令就能跑：

npx @deepseek-ai/dsh web

浏览器打开 http://127.0.0.1:3080，一个功能完整的编码 Agent 就在眼前了。

这篇文章基于对 deepseek-ai/deepseek-harness 源码仓库（0.1.0-rc.5，MIT 协议）的完整通读，带你从架构到细节看懂它。

---

一、它到底是什么？

先厘清一个概念：Harness（马具）≠ Agent 框架。

LangChain、AutoGen 这类框架给你的是"搭 Agent 的积木"；而 Harness 是已经装配好的整套马具——模型是马，Harness 是套在马身上的鞍、缰、镫。DeepSeek Harness 交付的是一个开箱即用的产品级 Agent 运行时：

• Web UI：浏览器里的完整图形界面，会话管理、权限审批弹窗、模型配置、插件管理一应俱全
• Headless CLI：dsh --profile headless "帮我修了这个 bug"，跑完打印结果就退出，适合 CI 和脚本
• Python SDK：pip install deepseek-harness-sdk，不需要装 Node.js——SDK 的 wheel 里直接打包了编译成单文件 exe 的 TS 运行时，Python 通过 JSON-RPC 驱动它

它的定位非常明确：给开发者一个可拆解、可替换、可扩展的 Agent 基座，而不是又一个黑盒产品。

⚠️ 注意：项目目前处于 developer preview 阶段，官方原话是 “THERE WILL BE COMPATIBILITY-BREAKING CHANGES”，且早期暂不接受外部 PR。现在适合研究、写插件、做二次开发，不适合押注生产环境。

---

二、最核心的设计哲学：一切皆插件

README 里一句话点题：

It uses an architecture where everything is a plugin, and is powered by Cordis.

这句话不是营销话术。架构文档里写得更绝：

There is no privileged core to patch —— 没有特权核心可以打补丁。你扩展 dsh 的方式就是把一个插件挂载到其他插件旁边，插件卸载时它注册的一切都会随之回卷。

到底有多彻底？看一组数字：系统最底层的 dsh-base bundle 由 78 行插件配置组成——从 timer、hmr 开始，到 tools、system-prompt 依次排开，第 76 行才是 agent-loop（Agent 循环本体），最后一行是 llm-deepseek（官方模型适配器）。

也就是说，连"Agent 怎么循环思考"和"调用谁家模型"这两件看起来最核心的事，都只是普通的插件行，可以被你自己的配置整行替换。想换掉 Agent 循环？写个插件挂载上去就行。

底层引擎 Cordis：来自聊天机器人世界的时空可组合性

驱动这一切的是一个叫 Cordis 的插件框架，作者是 Shigma，上游是 cordiverse/cordis——也就是知名聊天机器人框架 Koishi 生态沉淀出来的元框架。它的设计被形式化为一篇论文《A Programming Paradigm for Spatiotemporal Composability》（时空可组合性编程范式），两个维度：

• 时间可组合性（Temporal）：组件被移除时，它的所有副作用能被完全撤销。每个注册都是可逆的 effect。
• 空间可组合性（Spatial）：组件之间的依赖是声明式、响应式的——插件用 inject 声明"我需要 ctx.tools 服务"，框架自动等服务就绪再激活它，加载顺序不用手工编排。

值得注意的是，DeepSeek 没有通过 npm 依赖 Cordis，而是把 9 个包的源码直接 vendor 进仓库，全部重命名进 @deepseek-ai 命名空间。vendor/README.md 解释了原因：“让 harness 完全拥有自己的框架层——可审计、可打补丁、可锁定”。里面还维护着一份 18 条的"本地修改日志"，每一处对上游的分叉都登记了理由和测试覆盖。这种把依赖当自有资产管理的做法，非常硬核。

Seam：一个可替换能力的"三角色"

架构里另一个关键概念叫 Seam（接缝）。任何一个可替换的能力都由三个角色组成：

1. Service Definition：必须是一个 Cordis Service 类（绝不能只是 TypeScript interface）
2. Service Provider：具体实现
3. Consumer：使用方

为什么要这么较真？文档一句话道破：“Seams are why one provider swap changes the whole product”——文件系统和子进程共享同一个"执行世界"这个 seam，当你把 provider 换成远程沙箱时，Bash、PTY、LSP 会一起迁到远端。一次替换，整个产品的行为随之改变。

---

三、Agent 运行时：事件日志是第一性的

拆开 Agent 循环，dsh 的层级是：step（一次模型请求 + 它触发的工具调用）→ turn（零到多个 step，直到"不欠任何东西"为止）。

一个 turn 的完整流程大致是：

turn/start → 领取输入 → 组装 prompt + 工具 schema
→ agent/pre-step（可拒绝）→ step/start
→ llm/stream → assistant/chunk → tool/call
→ tools/pre-execute → tools/execute → tools/post-execute
→ tool/result → step/end → … → turn/end

其中最硬核的一条原则，值得单独加粗：

Model-visible means logged. 凡是进入模型请求的内容，必须能从 session log 中重建出来——而且有运行时不变量断言来保证这一点。

Session log 是一个 append-only 的事件流（12 种事件变体：turn/start、assistant/chunk、tool/call、steering/message……），模型看到的历史是从日志投影出来的。fork 会话、resume、生成 transcript、遥测、持久化——全部从这一条流派生。这就是它能稳定支持"会话分叉""断点续跑"的原因。

权限与沙箱：fail-closed 的防线

安全模型分两层，而且刻意分开：

• 沙箱：只管文件副作用。三档——read-only / workspace-write / danger-full-access。后端按平台实现：Linux 用 bwrap/Landlock、macOS 用 Seatbelt、Windows 用 ACL 受限令牌。有意思的细节：native/ 目录里那个 Landlock 启动器不是 Rust，是约 300 行纯 C11，musl 静态链接，直接调内核 UAPI。执行完整度如实上报为 full / partial，不吹牛。
• 审批：ctx.approval 只回答一个问题——"这个具体操作可以执行吗？"结果是封闭集合 allowed-once / rejected / cancelled / unavailable，fail-closed：审批方出错或缺失时结果是 unavailable，绝不放行。never 策略下直接确定性返回 rejected，这是 headless/CI 场景的立场。

新会话默认 workspace-write + 逐次询问。计划模式（plan mode）则明确只是"软性引导"——只注入提示词段和 exit_plan_mode 工具，文档原话：“Plan mode is soft guidance. Sandbox mode and approval policy enforce separately.” 提示词约束和系统强制，分得很清。

---

四、四种模式：一个产品，四副面孔

Web UI 里内置了四个 Agent 预设（preset），每个 preset 本质上就是一份 Cordis 组合文件：

模式	本质	适合谁
标准模式	全功能编码 Agent：文件编辑、Shell、检索、Skills、计划、目标、子代理、工作流	大多数人
PTC 模式（英文 UI 叫 Code mode）	标准模式全量 + 工具改用 Code Mode SDK 呈现：模型面对的不是 N 个独立工具，而是一个 run_code 工具 + 一套生成的 TypeScript SDK，模型写一段程序组合多步操作	复杂多步任务，“五次往返变一次”
极简模式	只有两个工具：持久 bash + str_replace_editor，固定系统提示词，无压缩无子代理	基准测试、行为研究
创造模式	标准模式全量 + cordis_* 自指工具集：Agent 可以检视和修改自己运行时的插件树，用来创作新的自定义预设	高级玩家

两点值得展开。

PTC 模式（仓库中没有出现这个缩写的英文全称，机制上对应 programmatic tool calling 的思路）代表了工具调用范式的一个转向：从"模型每步选一个工具"变成"模型写程序编排工具"。中间结果在运行时内部流转，不用反复进出上下文，省 token 也省延迟。

创造模式大概是全网最大胆的官方功能：它给 Agent 一套 cordis_define / cordis_mount / cordis_run / cordis_inspect_self 工具，让 Agent 直接操作自己活着的运行时。配置文件头部的警告写得非常直白：

TRUST: cordis_mount evaluates model-written JavaScript against the live runtime … Treat a session on this preset as shell access.

——把这个模式下的会话当作 shell 访问来对待。官方敢这么写、这么发，本身就是对"一切皆插件"架构的自信：既然模型能改的只是插件组合，那运行时本身就是一个可编辑的产品。

---

五、工程细节：这才是最震撼的部分

如果说架构设计展示的是品位，那工程数据展示的是肌肉：

• 219 个 workspace 包（54 个分组），全部统一命名 @deepseek-ai/dsh-*、统一版本号
• 811 个测试文件，CI 覆盖率门禁是逐文件 100%（语句/分支/函数/行四项全满）
• 7 个 vitest 配置：单测、真实 API 的 e2e、无 key 回放快照、Web UI 回放/性能/压力测试，分得清清楚楚
• 根 package.json 有 120+ 个脚本，其中约 30 个 verify-* 治理门禁：检查 Markdown 换行、死链、JSDoc 完整性、Mermaid 图、文档字数预算、双语翻译配对……
• 215 篇文档全部中英双语配对，双语一致性由 git merge driver 机器维护；文档里的类型声明代码块由 verify-type-equiv 保证与源码逐字一致；工具目录是生成器真实启动每个工具插件后读出 schema 生成的——因为"工具 schema 无法静态得知"
• 连 scripts/ 目录下的治理脚本都自带 45 个测试文件——连脚本都要测
• .agents/notes/ 目录下有 1372 篇 Agent Note——AI 代理驱动的开发流程留下的成体系设计档案，非平凡改动必须附一篇

还有一个只有深度读码才会发现的精妙细节：仓库用两个隔离的 tsc 项目（tsconfig.host.json 和 tsconfig.client.json）分别编译 Host 端和 Client 端。原因是两端会在同一个 ctx 键上 declaration-merge 不同的服务类型，一个 ts.Program 同时看到两边就会冲突。这种冲突只存在于类型层面——他们用构建编排干净地解决了它。

顺便一提，BENCHMARK.md 只有三行。没有跑分脚本，只有一句话：按照 Python SDK 指南把最小 Agent 跑起来，用独立 workspace 去执行基准任务。官方把 harness 本身当作基准运行器——这很自信。

---

六、生态与上手

插件生态走 npm + GitHub：第三方插件给自己的仓库打上 dsh-plugin topic 即可被发现，安装用 dsh plugin --profile web add <包名>。组合单位分两层：bundle（插件的分发格式）和 profile（~/.dsh/profiles/ 下的具名组合，叠加 bundle + 你自己的 patch 配置）。想先看启动时到底挂了哪些插件？dsh --profile web --dump-config 打出来，任何一行都可以用你自己的 patch 替换。

模型支持不锁死 DeepSeek：内置 DeepSeek 适配器，也支持 Anthropic、OpenAI 及任何 OpenAI 兼容网关（settings.yaml 里配 baseURL 和凭证），视觉模型需要显式声明输入模态。密钥存 ~/.dsh/.credentials.yaml，UI 只回显脱敏描述符。

遥测默认只存本地，只有显式设为 FULL 或 FEEDBACK_ONLY 才会上传。

社区已经有周边项目冒出来了：容器化封装（Docker/Helm）、桌面壳，甚至有人做了"DeepSeek 娘桌宠插件"——只注册一个 UI slot，读取会话状态做 16 方向追视，不碰核心文件。这恰恰是插件架构想看到的生态形态。

---

七、怎么看这个项目？

几点个人判断：

1. DeepSeek 在下一盘"定义 Agent 时代基础设施"的棋。 模型能力趋同之后，护城河在 harness——谁的骨架成为标准，谁的模型就是默认引擎。开源 MIT + 插件生态（dsh-plugin topic）+ Python SDK，是非常典型的平台打法。
2. "一切皆插件"不是口号，是被工程纪律强制执行的宪法。 连 agent-loop 都只是第 76 行插件，这种彻底性在同类项目里罕见。Claude Code、Codex CLI 都是产品思维；dsh 是操作系统思维——它更像"Agent 界的 VS Code"，一切皆可替换，核心只是插件加载器。
3. Cordis 的 vendor 策略透露了长期主义。 宁可 fork 进仓库自己维护、逐条登记分叉，也不把命脉交给 npm 上游。框架层被视为自有资产。
4. 质量门禁的强度（逐文件 100% 覆盖、双语配对机器校验、文档类型与源码逐字比对）说明这不是一个"放出来刷存在感"的项目，而是内部已经当产品在打磨的东西。
5. 风险同样明显：developer preview + 明确警告破坏性变更 + 暂不收 PR。现在是研究和早期布局的窗口期，不是上车生产的时机。

---

快速上手清单

# 方式一：Web UI（需要 Node.js 22.19+ 或 24+）
npx @deepseek-ai/dsh web          # 打开 http://127.0.0.1:3080

# 方式二：Python SDK（不需要 Node.js）
pip install deepseek-harness-sdk  # 需要 Python 3.10+，Linux/macOS
export DEEPSEEK_API_KEY=sk-...

# 源码党
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness && pnpm install && pnpm run build && pnpm dsh web

# 看看实际启动了哪些插件（任何一行都能替换）
dsh --profile web --dump-config

进去之后：Settings → Models 填 API key → 选 workspace → 开会话。想玩点花的，切到创造模式，让 Agent 改它自己的运行时给你看。

---

一句话总结：DeepSeek Harness 不是又一个 Agent 产品，而是一套把"Agent 的一切组成都变成可插拔零件"的操作系统级基座——78 行插件配置撑起整个运行时，连 Agent 循环本身都可以被你换掉。模型是发动机，而 DeepSeek 这次开源的是整辆车的底盘图纸。

---

本文基于 deepseek-harness 0.1.0-rc.5 源码（2026-08）撰写，项目迭代迅速，细节请以最新仓库为准。