DeepSeek Harness 开源 45 小时 14 万 Star一句 npx 跑起你的第一个 Agent2026 年 8 月 13 日DeepSeek 在发布 V4-Pro 正式版的同时一并开源了自己的第一款 Agent 运行框架 —— DeepSeek Harnessdsh。上线 45 小时 GitHub Star 突破 10.5 万几天内逼近 14 万。这不是又一个大模型而是一套让模型「长出双手双脚」的运行时。本文带你从零上手用一句命令跑起属于你自己的 Agent。一、先说清楚Harness 到底是什么很多人第一眼会把它当成「DeepSeek 版的 Claude Code」或者「DeepSeek 版的 Codex」。这个类比对了一半错了一半。DeepSeek Harness 官方给出的定位浓缩成一句话就是Model Harness Agent模型负责「理解」和「推理」Harness 负责把能力落到真实环境里——调用工具、操作终端、读写文件、管理上下文、调度任务、分配子智能体最终把活干完、交付。换句话说模型是「大脑」Harness 是「神经系统 手脚」。它和 Claude Code、Codex 最本质的区别在于开放程度Claude Code / Codex把模型、工具、沙箱锁死在黑盒里你拿到的是一个开箱即用的成品。DeepSeek Harness把模型、工具、会话、沙箱、循环、调度、UI全部做成可插拔的插件你拿到的是一个可以任意组装的 SDK 框架。官方给它的口号叫「Everything is a Plugin一切皆插件」这个我们下一篇会深入拆解。今天先把它跑起来。关键信息速览项目说明仓库github.com/deepseek-ai/deepseek-harness协议MIT完全开源可自由二次分发语言TypeScript 为主附带 Python SDK底层框架Cordis插件元框架默认模型DeepSeek 自家模型但模型无关可接 OpenAI / Anthropic / Google 等状态开发者预览版v0.1官方明确「会有破坏性变更」入口形态Web UI / TUI / Headless / ACP / JSON-RPC二、环境准备你只需要一个 Node.jsDeepSeek Harness 是基于 Node.js 的所以第一步是确认你的机器上有 Node.js建议 LTS 版本。node -v # 确认 Node 版本 npm -v如果还没有去 nodejs.org 下载安装即可。除此之外不需要任何额外依赖——连模型 API Key 都可以用 DeepSeek 官方的。三、最快上手一句 npx 拉起 Web UI官方提供了最省事的启动方式直接通过npx运行npx deepseek-ai/dsh web这条命令会做三件事自动下载deepseek-ai/dsh包拉起一个本地 Web UI默认监听127.0.0.1:3080。启动后浏览器打开http://127.0.0.1:3080你会看到一个光秃秃的对话框——别惊讶这就是开发者预览版的真实面貌一个输入框 左侧会话历史栏没有任何花哨的面板。那些让 V4 Flash「变快变强」的智能体工具全被藏进了内置插件里需要你自己去调用、去组装。第一次跑你需要填一个模型 API Key。默认接的是 DeepSeek 官方模型配置好 Key 后在对话框里输入一个任务试试帮我看看当前目录下有哪些文件并统计每个文件的代码行数。Agent 会调用 shell 工具执行ls、wc读文件、跑命令最后把结果返回给你。这就是一个最小可用的 Agent 循环。四、从源码安装拿到完整的「洞洞板」如果只是体验npx就够了。但如果你想真正理解它、改造它还是从源码安装git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web克隆下来后你会发现一个惊人的事实这个仓库包含超过 230 个 workspace 成员代码分布在packages/、apps/、examples/、python/、native/、vendor/、website/等区域。如果把普通 Agent 项目比作一台「已经装好的电脑」那么 DeepSeek Harness 更像一块尺寸惊人的洞洞板文件系统终端子进程PTY语言服务器网页访问技能Skills子智能体Subagent工作流Workflow计划模式会话持久化设置凭据遥测……几乎每一项能力都有一个独立的包。它们都可以插上去也都可以拔下来。五、四大模式同一套代码四种完全不同的形态这是「一切皆插件」最直观的产品化表达。DeepSeek Harness 预设了四种模式profile每种默认加载不同的插件集合1. 标准模式Standard提供完整的工具组合覆盖日常开发场景。读文件、写代码、跑命令、上网搜索、派子智能体分头干活应有尽有。这是最全的一档适合「把 Agent 当开发搭子」的日常使用。2. PTC 模式Programmatic Tool Calling程序化工具调用这个模式比较有特色它让模型生成一段代码用这段代码来组合多轮工具调用。传统 Agent 是一轮一轮地「模型出调用 → 执行 → 回填 → 再出调用」慢吞吞且费 TokenPTC 模式把多次工具调用打包成一段程序一次跑完省 Token、速度快。这是 DeepSeek 在工程上很聪明的一处设计。3. 极简模式Minimal只保留一个 shell 工具 一个文件编辑工具用于最小环境下的模型基准测试。官方 V4 Flash、V4 Pro 公布的 Agent 基准成绩就是在 Harness 的极简模式下测出来的——这也意味着那些跑分是可复现的。4. 创造模式Creator这个模式最「元」Agent 可以检查当前运行时、在内存中试验 Cordis 插件并据此组合和创作新的模式。选择这个预设后Agent 能检查当前运行时的插件树动态挂载或卸载临时插件。换句话说这是让 Agent「改造自己」的入口也是通向「自进化 Agent」的关键一步。四种模式的本质是底层的模型路由、会话持久化、沙箱和审批仍由共享宿主提供预设preset只决定一个 Agent Context 中具体装入哪些能力。所以同一个 Web UI可以从双工具的极简 Agent一路切换成能编排子智能体的标准模式甚至变成能改装自身的创造模式。六、不止 Web UI四种入口形态DeepSeek Harness 的入口远不止网页。它提供四种形态背后共享同一套核心能力入口形态适用场景Web UInpx deepseek-ai/dsh web浏览器交互Headlessdsh一次性运行器完全不带服务器接任务 → 完成模型与工具轮次 → 打印答案退出ACPAgent Client Protocol 服务被其他 Agent 客户端驱动JSON-RPC / Python SDK程序化接口Python 应用启动会话、发任务、收通知尤其值得关注的是 Python SDK它让 Python 应用可以启动会话、发送任务、接收通知而不必直接嵌入内核。下一篇系列会专门讲。七、上手后你该知道的三件事1. 它是毛坯房不是精装房开发者预览版的界面只有光秃秃的对话框没有任何 Codex 式的功能面板。对非编程用户极不友好——但这恰恰是它的定位面向 Harness 开发者而不是面向普通用户。官方明说「仍在迭代会有破坏性兼容变更」生产环境建议等几个稳定版本。2. 沙箱边界要清楚Harness 把文件沙箱和操作审批分开默认预设为「工作区可写、敏感操作询问」并针对 Windows、macOS、Linux 提供了不同的隔离实现。但官方也明确这套沙箱主要约束文件操作网络访问和进程可见性不在其规则范围内。Linux 上基于 LandlockWindows 原生支持不稳建议走 WSL2。3. 它不挑模型你可以套在 DeepSeek、Anthropic、OpenAI、Google 的任何模型上。甚至本机已装好的 Claude Code、Codex也能被它「叫过来干活」——只是这个开关默认关着。八、小结与下篇预告DeepSeek Harness 不是「另一个更好用的 Claude Code」它回答的是另一个更底层的问题模型之上智能体到底该怎么被组织它用「一切皆插件」的极端开放把「智能体循环的定义权」交还给开发者。成品 Agent 只是这套 SDK 的「第一位客户」真正占据项目中心的是可替换的能力接口、事件驱动的生命周期、权威的会话日志和声明式组合。下一篇我会深入拆解它的底层框架Cordis讲清楚「一切皆插件」到底是怎么在代码层面落地的——ctx键、服务与事件、可逆副作用以及为什么连 Agent Loop 本身都可以被替换。九、补充跑通第一个真实任务完整示例光启动 Web UI 还不够这里给一个「从零到交付」的完整示例帮你建立对 Harness 工作流的第一印象。假设你的需求是给一个 Python 项目加一个命令行入口并补充 README。步骤 1准备 workspacemkdir my-demo cd my-demo git init echo def hello(): return world main.py步骤 2启动 Harness 并指向该目录npx deepseek-ai/dsh web --cwd .步骤 3在对话框下达任务请阅读 main.py为这个项目创建一个 cli.py 命令行入口支持 --name 参数 并在 README.md 里补充使用说明。完成后告诉我改了哪些文件。步骤 4观察 Agent 的工作轨迹你会看到 Agent 依次调用文件读取工具查看main.py内容调用文件写入工具创建cli.py含 argparse 逻辑写入README.md用 shell 跑一遍python cli.py --name test验证汇总「改了哪些文件」回报给你。这五步就是「模型 Harness Agent」的完整体现模型负责决策每一步干什么Harness 负责把每一步落到文件系统里。没有 Harness模型只能「说」出 cli.py 应该长什么样有了 Harness它真的把文件写出来了。常见新手卡点速查现象原因解决启动后页面空白Node 版本过低升级到 LTS提示缺 API Key未配置 DeepSeek Key在设置里填入或设DSF_API_KEY模型不回复网络到模型服务不通检查代理 / 换模型工具调用一直转圈默认 300 秒 Bash 超时任务太大时拆分关于「毛坯房」心态的最后一段话很多新手在第一次打开 Harness 后就关掉了理由是「不如 Claude Code 好用」。这个判断没错但结论下早了。Harness 的价值不在「打开那一刻」而在你用它组装出第二个、第三个自己的 Agent之后。打个比方Claude Code 像叫外卖——快、省事、味道稳定但你永远吃不到菜单之外的东西Harness 像给了你一整个厨房——第一顿饭确实做得慢、做得丑但从此你想吃什么都能做还能请别人来吃你做的菜。如果你的目标只是「让 AI 帮我写代码」外卖够了。如果你的目标是「理解 Agent 是怎么工作的」「造一个属于自己团队的 Agent」那就系好围裙从第一顿饭开始。这一篇的四条命令、四种模式就是你的第一份菜谱。十、补充常见启动报错与排查清单上手阶段的大多数报错不在模型而在环境和配置。下面按出现频率从高到低整理一份速查清单。1. npx / web 启动失败先确认网络能访问 npm registry公司内网可执行npm config set registry https://registry.npmmirror.com。若提示找不到deepseek-ai/dsh检查包名是否输错并用npx -y deepseek-ai/dsh web跳过确认。Windows PowerShell 因执行策略拦截时可改用npx.cmd或cmd /c执行。2. Node 版本过低node -v低于 20 容易出现启动报错或页面空白。升级到当前 LTS 并重启终端使用 nvm 时记得nvm use切换到正确版本。3. 模型 Key 配置错误页面提示缺 Key、鉴权失败或返回401通常是 Key 没填、填错或环境变量名不对。优先在 Web UI 设置中填入 DeepSeek Key命令行环境可导出DSF_API_KEY以 README 为准然后刷新页面或重启服务。4. 127.0.0.1:3080 端口占用报错EADDRINUSE说明 3080 已被占用。可执行lsof -i :3080Windows 用netstat -ano | findstr 3080定位并结束进程或在启动时指定其他端口。预览版默认只监听本机回环不要擅自改为公网监听。5. 沙箱与权限导致工具失败模型能回复、但一调用 shell 或写文件就失败多半是工作区不可写或沙箱受限。确认启动目录权限不要在系统保护目录直接运行Linux 检查 Landlock 是否可用Windows 建议走 WSL2。敏感操作被审批拦截属正常保护按提示确认即可不建议直接关闭审批。排查总原则先判断报错属于「环境、端口、Key、权限」哪一层逐层排除通常很快就能回到可运行状态。标签#DeepSeek #AI Agent #Harness #开源框架 #大模型