ARTICLE · 993226

DeepSeek Harness 源码导读 01|它不是模型,也不只是聊天框

发布时间：2026-09-15 19:15:00 最近访问：2026-09-15 19:14:59

2026 年 8 月 28 日，DeepSeek Harness 发布到0.1.2-alpha.1。仓库里的packages/已经有 247 个包目录。

它不是聊天网页，也不是 DeepSeek 新模型的源码。

DeepSeek Harness 是一个开源 Agent Harness。说人话，它负责把模型装进真实的工作环境：给模型工具，保存任务过程，控制执行权限，再把结果呈现在 Web、命令行或 SDK 里。

模型负责判断下一步做什么。Harness 负责让这一步真的发生，而且留下记录。

01先分清四个东西

阅读一个陌生仓库，找到登录失败的原因，修改代码并运行测试。

模型只能接收消息并生成消息。它可以建议你“搜索登录逻辑”，但单靠模型 API，它不能自己打开仓库，更不能在你的电脑上运行测试。工具把这个缺口补上；Agent 让“模型判断、工具执行、结果返回模型”循环起来；Harness 则托住整个 Agent 的运行环境和生命周期。

层次	职责
模型	决定下一步
工具	完成一个具体动作
Agent	反复组织模型与工具
Harness	管理 Agent 的运行环境和生命周期

同一个任务，四层怎样接力

现场动作	负责人	Harness 的工作
决定先搜索登录入口	模型	提供工具说明
搜索与读取文件	工具	校验参数、限定工作区、记录结果
提出并执行修改	模型 + 编辑工具	检查审批与文件规则，保存 diff
运行测试并收尾	Shell + Agent Loop	沙箱执行，确认没有后续工作

“模型能力强”不等于“Agent 系统完整”。模型可以更聪明地选择下一步，但参数是否合规、命令是否真的执行、执行失败怎样恢复，都属于宿主软件必须承担的工程责任。聊天框只是入口，不是整个系统。

02它解决的不是“聊什么”

普通对话产品关注一问一答。工程 Agent 还要处理五类麻烦：执行、状态、安全、恢复和扩展。

执行与状态

模型说“我来改文件”不算改完。系统要校验工具参数，执行写入，把成功或失败交回模型，还要知道现在处于哪个轮次、哪个步骤。

安全与恢复

读、写、运行命令的风险不同。程序重启后，工具调用、审批结果、模型用量和轮次边界也必须能够重建。

扩展

今天接 DeepSeek，明天可能接公司网关；本机用 Bash，云端可能用隔离环境。每换一个提供方都改主循环，系统很快就无法维护。

DeepSeek Harness 的答案：把这些能力做成插件，把可恢复事实写进会话日志，把运行时策略放进工具流水线。

03一张图看懂仓库

目录	职责
`packages/core/`	会话、提示词、工具、Agent 和默认 Agent Loop
`packages/llm/`	模型能力与适配器
`packages/session/`	持久化、投影、标题、统计和遥测
`packages/shell/ fs/ web/ lsp/`	Agent 可用的现实能力
`interaction/ sandbox/`	审批、权限与进程文件效果约束
`subagent/ workflow/ skill/`	复杂任务组织
`packages/bundle/`	把插件组合成 Web、headless、SDK 和 ACP 产品层

别被 247 个包吓住

247 是二级包目录数量，不等于读者要同时理解 247 个概念。大量包只是在把“接口、具体实现、模型工具、Web 展示、测试组合”拆开。第一次读仓库，只沿三条主线走：

请求主线：用户输入 -> Agent Loop -> LLM -> assistant/message动作主线：tool/call -> 工具流水线 -> 文件或进程能力 -> tool/result记录主线：SessionEvent -> 持久化 -> UI / SDK / 恢复投影

等三条线接起来，再看压缩、Subagent、Workflow 和遥测。读到一个新包时，先问“它接在哪条线上”，不要先背包名。

04最快的上手方式

准备符合要求的 Node.js 后，只需一条命令：

npx @deepseek-ai/dsh web

默认地址是http://127.0.0.1:3080。进入“设置 → 模型”配置密钥，再选择工作区并新建会话。没有工作区时，文件工具不知道应该在哪个目录工作，输入框不会开放。

建议先发一个低风险任务

阅读这个仓库，只做分析，不修改文件。告诉我主要目录、启动入口和测试命令。

一条启动命令背后发生了什么

dsh
解析webprofile，找到声明的 bundle。
应用共享的dsh-base，装入模型、工具、会话、沙箱、审批、设置和凭据。
应用dsh-web-app，装入 HTTP 服务和浏览器客户端。
叠加 profile、Harness home 和命令行--patch配置。
Cordis 根据依赖启动插件，把它们注册到同一个 Context。
浏览器输入经 inbox 进入 Agent Loop，UI 持续订阅会话事件和状态。

Web、headless 和 SDK 复用相同基础能力，只是最外层输入、输出和生命周期不同。想查看机器最终启动了什么：

dsh --profile web --dump-config

05三个常见误解

误解一：只能使用 DeepSeek 模型

默认组合提供 DeepSeek 路由，也能添加 Anthropic、OpenAI 和自定义兼容端点。Harness 与模型是两层。

误解二：只是命令行包装器

命令执行只是能力之一，会话日志、审批、压缩、子 Agent 和 SDK 同样属于运行时。

误解三：Web UI 是唯一入口

headless适合一次性任务，sdk服务外部程序，acp面向自动化协议。它们共享基础能力，但应用层不同。

06它适合谁

如果只想调用一次聊天 API，Harness 可能太重。如果任务需要读写真实项目、运行命令、持续多轮、留下可回放记录，它就进入了主场。

它也适合平台开发者：可以替换模型、文件系统、沙箱或 Subagent 后端，再通过 SDK 接入自己的应用。项目采用 MIT 许可证。

Developer Preview 提醒

当前版本不承诺兼容旧磁盘格式，内部接口也可能调整。学习架构很有价值，生产接入要固定版本并准备迁移。

07第一篇源码定位卡

想确认的问题	先看哪里
为什么是 all-plugin harness	`docs/architecture.zh.md`
一次任务怎样循环	`docs/agent-lifecycle.zh.md`
不同应用装了什么	`packages/bundle/*/cordis.patch.yml`
会话怎样成为事实来源	`docs/subsystems/session.zh.md`

给自己一个小目标：找到ctx.tools、ctx.llm、ctx.sessions和ctx.agentLoop分别由哪个插件提供，又被哪些插件消费。能回答这四个问题，骨架就立起来了。

✓记住三句话

DeepSeek Harness 不是大模型，它是让模型完成工程任务的运行框架。

它把模型、工具、会话、安全策略和界面组织成一个持续运行的 Agent。

启动 Web UI 只需一条命令，但真正有意思的部分藏在消息发出以后。

下一篇，我们跟着一条消息进入 Agent Loop，看一次任务为什么会经历多个步骤，又在什么时候停下来。

项目主页：

https://github.com/deepseek-ai/deepseek-harness

官方文档：

https://deepseek-harness.github.io/deepseek-harness/

本文基于 DeepSeek Harness 0.1.2-alpha.1。项目仍在开发者预览阶段，请以当前官方文档与源码为准。

谢谢你读我的文章。

如果觉得不错，随手点个赞、在看、转发三连吧🙂

如果想第一时间收到推送，也可以给我个星标⭐～