深度拆解 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.5MIT 协议的完整通读带你从架构到细节看懂它。一、它到底是什么先厘清一个概念Harness马具≠ Agent 框架。LangChain、AutoGen 这类框架给你的是搭 Agent 的积木而 Harness 是已经装配好的整套马具——模型是马Harness 是套在马身上的鞍、缰、镫。DeepSeek Harness 交付的是一个开箱即用的产品级 Agent 运行时Web UI浏览器里的完整图形界面会话管理、权限审批弹窗、模型配置、插件管理一应俱全Headless CLIdsh --profile headless 帮我修了这个 bug跑完打印结果就退出适合 CI 和脚本Python SDKpip 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 whereeverything is a plugin, and is powered by Cordis.这句话不是营销话术。架构文档里写得更绝There is no privileged core to patch—— 没有特权核心可以打补丁。你扩展 dsh 的方式就是把一个插件挂载到其他插件旁边插件卸载时它注册的一切都会随之回卷。到底有多彻底看一组数字系统最底层的dsh-basebundle 由78 行插件配置组成——从timer、hmr开始到tools、system-prompt依次排开第 76 行才是agent-loopAgent 循环本体最后一行是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接缝。任何一个可替换的能力都由三个角色组成Service Definition必须是一个 CordisService类绝不能只是 TypeScript interfaceService Provider具体实现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 行纯 C11musl 静态链接直接调内核 UAPI。执行完整度如实上报为full/partial不吹牛。审批ctx.approval只回答一个问题——这个具体操作可以执行吗结果是封闭集合allowed-once / rejected / cancelled / unavailablefail-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_mountevaluates 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-plugintopic 即可被发现安装用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.yamlUI 只回显脱敏描述符。遥测默认只存本地只有显式设为FULL或FEEDBACK_ONLY才会上传。社区已经有周边项目冒出来了容器化封装Docker/Helm、桌面壳甚至有人做了DeepSeek 娘桌宠插件——只注册一个 UI slot读取会话状态做 16 方向追视不碰核心文件。这恰恰是插件架构想看到的生态形态。七、怎么看这个项目几点个人判断DeepSeek 在下一盘定义 Agent 时代基础设施的棋。模型能力趋同之后护城河在 harness——谁的骨架成为标准谁的模型就是默认引擎。开源 MIT 插件生态dsh-plugintopic Python SDK是非常典型的平台打法。一切皆插件不是口号是被工程纪律强制执行的宪法。连 agent-loop 都只是第 76 行插件这种彻底性在同类项目里罕见。Claude Code、Codex CLI 都是产品思维dsh 是操作系统思维——它更像Agent 界的 VS Code一切皆可替换核心只是插件加载器。Cordis 的 vendor 策略透露了长期主义。宁可 fork 进仓库自己维护、逐条登记分叉也不把命脉交给 npm 上游。框架层被视为自有资产。质量门禁的强度逐文件 100% 覆盖、双语配对机器校验、文档类型与源码逐字比对说明这不是一个放出来刷存在感的项目而是内部已经当产品在打磨的东西。风险同样明显developer preview 明确警告破坏性变更 暂不收 PR。现在是研究和早期布局的窗口期不是上车生产的时机。快速上手清单# 方式一Web UI需要 Node.js 22.19 或 24npx deepseek-ai/dsh web# 打开 http://127.0.0.1:3080# 方式二Python SDK不需要 Node.jspipinstalldeepseek-harness-sdk# 需要 Python 3.10Linux/macOSexportDEEPSEEK_API_KEYsk-...# 源码党gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web# 看看实际启动了哪些插件任何一行都能替换dsh--profileweb --dump-config进去之后Settings → Models 填 API key → 选 workspace → 开会话。想玩点花的切到创造模式让 Agent 改它自己的运行时给你看。一句话总结DeepSeek Harness 不是又一个 Agent 产品而是一套把Agent 的一切组成都变成可插拔零件的操作系统级基座——78 行插件配置撑起整个运行时连 Agent 循环本身都可以被你换掉。模型是发动机而 DeepSeek 这次开源的是整辆车的底盘图纸。本文基于 deepseek-harness 0.1.0-rc.5 源码2026-08撰写项目迭代迅速细节请以最新仓库为准。