什么是 DeepSeek Harness?一份实用入门指南

DeepSeek 在 2026 年 8 月开源了 DeepSeek Harness——大家习惯叫它 DSH——发布头几天就收获了超过 15 万 GitHub star。对一个开发者工具来说,这绝不寻常。这篇入门基于官方文档和代码级分析,讲清 DSH 到底是什么、它的架构在底层怎么运作、以及为什么一个叫 preset 的小 YAML 文件会成为整个生态的分享单位。

一句话版本

DSH 是一个开源(MIT)的 agent 运行时,用 TypeScript 写成,核心理念是一切能力皆插件——模型适配器、工具、沙箱、会话日志、调度循环、甚至 UI——所以你通过组合插件来组装 agent,而不是 fork 一个产品。

项目自己的表述是一个等式:Agent = Model + Harness。模型负责推理,harness 负责其余一切——让它理解环境、使用工具、在真实条件下持续工作。

它本地就能跑:

npx @deepseek-ai/dsh web   # 打开 http://127.0.0.1:3080 的 Web UI

同一个包里还有 headless、CLI 和 Python SDK;dsh 进程把你启动它的目录当作默认工作区。

“Everything is a plugin”,具体指什么

大多数 agent CLI 是一个带扩展点的硬核核心。DSH 把这个结构倒了过来:Cordis 内核只管插件的挂载、卸载和依赖,而配置组合作用于一个空根之上:profile → bundle(携带配置补丁的 npm 包)→ 你的 home 补丁 → --patch 覆盖层,按顺序叠加。没有值得 patch 的特权内核——模型适配器、工具注册表、会话持久化、agent 循环、甚至 Web UI,全部以插件形式挂载。

两件事让这不只是口号:

• 卸载是一等公民。 Cordis 论文(A Programming Paradigm for Spatiotemporal Composability,预印本)把”时间可组合性”形式化——插件注册的每个副作用都有被追踪的逆操作,移除它就是真正回滚系统;还有”空间可组合性”,即插件间依赖的响应式管理。VS Code 扩展活在共享宿主里、无法动态移除,而这里的组件随取随用、无需重启。
• DeepSeek 拥有整个技术栈。 对发布版本的代码分析发现,dsh 把自己打过补丁的 Cordis fork 以 @deepseek-ai 作用域 vendor 进了仓库——约 45.3 万行 TypeScript、约 219 个 workspace 包,全部经同一套插件机制挂载。框架层不是依赖,是它自己的。

最贴切的历史类比不是 IDE,而是”agent 的操作系统”:一个内核加一组用户态程序,连看似承重的部分都能换。

四种运行模式

DSH 自带四个内置配置,展示了它的弹性:

1. Standard(标准)——日常完整形态:文件编辑、shell、文件与网页搜索、技能、规划、目标、子代理、工作流。
2. Code(代码)——标准形态之外增加 Code Mode SDK:模型写一段 TypeScript 程序来编排多步工具调用,而不是一次一个工具调用。
3. Minimal(极简)——刻意只留两个工具(常驻 bash 和 str_replace_editor),用于在受控环境里做模型基准测试。
4. Creator(创造)——为创作新 preset 而生:运行时检查、内存中的插件实验、以及 preset 创作指引,让 agent 帮你造 agent。

模型与提供方

默认模型目录接好了 DeepSeek V4-Flash 和 V4-Pro(同周发布,API 默认开启思考模式),配置为 1M token 上下文窗口、最高 256K 输出、推理力度 off / high / max 三档。

上手流程刻意做得无聊:npx @deepseek-ai/dsh web,然后在 UI 里 Settings → Models → 填入 DeepSeek API key——无需重启。因为模型适配器是插件,文档的 providers 页覆盖了其他提供方和自定义 OpenAI 兼容端点。另有面向 Claude Code 与 Codex 的 hook 桥接,以及 MCP 支持——仅客户端方向(dsh 能消费 MCP server,不把自己暴露为 MCP server)。

会话日志:竞品难以复制的一环

模型看到的一切都记录在 append-only 会话日志里:系统提示、推理过程、工具调用与结果、子代理调度、每一段上下文注入。不变量被表述为*“model 看得见 = 被记录”*——模型看到过的,就必须能从日志重建。代码层面,agent 循环硬性执行这一点:每次 LLM 分发,外发消息必须与从会话派生的消息列表逐字节一致。

恢复(resume)、fork、搜索、重放全部作用于同一条事件流,UI 的 Trajectory 视图按来源检视它。一个工件就是重放、调试和 UI 的唯一事实来源。对比一下就知道这意味着什么:Anthropic 只展示摘要后的思考轨迹,OpenAI 对闭源模型隐藏原始思维链。你掌控的全保真轨迹,是实打实的差异化。

沙箱与权限

每次工具调用都会解析一个沙箱策略,阶梯清晰:read-only、workspace-write、danger-full-access。执行依托操作系统:Linux 上用 bubblewrap 或 Landlock,macOS 上用 seatbelt,Windows 上用写受限令牌;UI 按当前权限策略请求批准。(代码分析给出的诚实告诫:Windows 沙箱只限制写入——读取、网络和进程可见性仍然开放。)

Preset 登场

**Preset(预设)**是一组命名的插件组合 + 人设 + 提示词段——把通用运行时变成你的专属 agent 的那层配置。上面的内置模式本身就是 preset,你复制一份、在 .agent-presets/ 里改两个小 YAML 文件,就有了自己的版本。

全部诀窍就在于 preset 只是文件:

• 你可以在运行之前读到一个 agent 会做什么、不会做什么;
• 一条 curl 命令就能分享;
• fork 一份不碰任何人的代码。

最诚实的起点就是上面的内置模式:复制一套、保持组结构不动、逐行裁剪,直到工具集恰好是你想要的 agent 形态。DSH 还在开发者预览期,版本间必然有破坏性变更——锁定你运行的版本,每次升级后重新验证。

诚实的那部分:当下的弱点

这么年轻的运行时有真实的毛边,装作没有对谁都没好处:

• 版本漂移——GitHub 仓库和 npm 包一度不同步(rc.5 对 rc.6),许可证还在 RC 中途从 BSD-3 改成了 MIT。预期会有折腾。
• BENCHMARK.md 是个三行占位文件——没有方法论、没有评测工具链。
• Python SDK 是 0.0.0.dev0——目前只是 Node 二进制的 stdio 包装。
• 还没有评测工具、工件(artifacts)界面、会话分享或计量。
• 日志不变量有吞吐代价——每次分发都完整序列化消息历史。
• git 历史是单个 squash 提交——部分被 .agents/notes/ 里 1,372 条双语、由 agent 撰写的决策记录抵消。

但业界的反应说明了一切:Armin Ronacher——Earendil 联合创始人、Pi agent 的主导者——写道,DSH 并不完美,但这是*“我第一次在这个领域看到新东西,并且真的被激励去重新审视我们自己的一些选择。“*当造竞品的人都这么说时,这些想法值得研究。

现在就该关注吗?

• 有凭据的模型自由——适配器是插件,会话日志归你。
• 工程是认真的——无密钥 CI 把提交进仓库的会话日志同时当作重放输入和期望输出,这是真正聪明的测试策略。
• 生态时机——现在成形的范式(插件 id、preset 格式、dsh-plugin GitHub topic、Discord)会定义未来多年的工具链。早期参与者有话语权。

下一步

• 创建你的第一个预设——手把手实操
• DeepSeek Harness 对比 Claude Code——该用哪个框架