DeepSeek 官方开源 Agent 框架 DeepSeek Harness(dsh)已进入开发者预览阶段,主打"一切皆插件"架构,从安装到权限到插件生态,这篇手册带你一次跑通。 DeepSeek Harness是什么?
dsh 由 DeepSeek AI 官方开源,MIT 协议,仓库地址 github.com/deepseek-ai/deepseek-harness。8 月 13 日发布当天就冲上 2 万星标,往后几天涨势没停,目前已经突破 16 万星、1.7 万 fork,创下 GitHub 历史上罕见的增长速度——不过星标涨得快不代表生产可用,官方自己也反复提醒这还是开发者预览版,接口和插件随时可能推倒重来。 它的架构核心叫 Cordis,脱胎于 Koishi 生态的插件内核。跟 Claude Code、Codex 这类把核心逻辑写死、只留几个接口给你改的产品不一样,dsh 把模型接入、工具注册、会话存储、审批策略、界面组件全部做成插件,换个搜索引擎或者接自家模型服务,改配置就行,不用碰框架代码。 DeepSeek Harness安装与运行
Node.js 版本要 22.19 及以上,Windows/macOS/Linux 都能跑。装法有四种:
1、图省事就 npx @deepseek-ai/dsh web 直接跑;
2、日常用建议全局装 npm install -g @deepseek-ai/dsh;
3、想改代码就 clone 源码用 pnpm 编译;
4、手头已经有能操作终端的 AI 工具(Claude Code、Cursor 之类),也可以直接甩一段指令让它帮你把环境检查、安装、启动全流程跑完。 启动之后有几件事要记牢:
1、跑 dsh web 的那个终端窗口不能关,网页只是操作界面,终端一关网页立刻失联,这不是 bug 是设计;
2、默认只监听本机 127.0.0.1:3080,局域网设备访问不到;
3、端口冲突就加 --port 换一个。排错第一步永远是回头看那个终端窗口的报错输出。
接模型:BYO 模式
dsh 本身不带模型,得自己配。去 DeepSeek 开放平台注册、充值、在 API Keys 页面创建密钥——密钥只在创建那一刻显示明文,关掉页面就再也看不到,务必当场复制保存。
回到 Web UI 的"设置→模型"里粘贴密钥、选模型(比如 DeepSeek V4 Flash),保存即生效,不用重启。密钥字段是只写的,保存后界面只显示脱敏描述符,永远不回显明文,实际存在本地的 .credentials.yaml 里。
不想用 DeepSeek 官方接口也行,Anthropic、OpenAI 等主流提供方直接在目录里选就能接;用 Bedrock、Vertex、Azure 这类原生认证的服务,得填各自专属的凭据(AWS 密钥和区域、ADC 项目等),光填 API Key 是不够的。
公司自建网关或者目录里没有的服务,走"添加自定义提供方",填 Provider ID(这个一旦定了就不能改,重命名等于重建)、基础 URL、API 协议、凭据、模型 ID,可以点"获取可用模型"自动发现。默认模型只认文本,想让某个自定义模型能读图,得去 settings.yaml 里手动给它加 input: [text, image]。
DeepSeek Harness工作区和权限
Workspace 是 Agent 读写文件的边界目录,不是聊天窗口。选中工作区之前,输入框是灰的,逼你先划边界再干活。权限分三档:
| |
|---|
| |
| |
Full Access(danger-full-access) | |
有个容易被忽略的点:权限限制的是"写",不是"看"。
即使你选了 Workspace Write,Agent 照样能读工作区以外的文件、能联网、能看系统进程,涉及敏感操作会弹审批窗等你确认,不会静默放行。
底层有真实的系统级沙箱撑着——Linux 上是 bwrap/Landlock,macOS 是 Seatbelt,Windows 是 ACL 受限令牌,另外还挂了重复无效动作检测和超时强制中断两个常驻插件防止 Agent 空转。
四种模式,岗位不同
新建会话时要选Preset,开始运行后锁定,中途不能换——模式决定工具集,切换会破坏可复现性。
Standard模式最完整,文件编辑、Shell、检索、Skills、计划、子代理、工作流全都有,拿不准就选它。PTC模式让模型写TypeScript,把多步工具操作组合成一段程序一次执行,适合步骤多、追求速度的任务。Minimal只留持久Bash和文件编辑器两个工具,跑基准测试或教学用。Creator模式可读写运行时本身,执行的代码能直接修改DSH,信任等级等同于Shell访问,只在受信任环境用。
还有计划模式,输入/plan进入,Agent只调查出方案,不修改任何内容,等你确认后才动手。输入/plan off退出。
怎么跟Agent把话说清楚
任务效果七成取决于你的描述质量。要说清楚四个东西:目标(要什么结果)、范围(可以碰哪些文件)、禁区(绝对不能动什么)、验收(怎样算完成)。别只说"帮我弄一下这个报告",Agent只能猜。
反复要交代的规则,写进工作区根目录的AGENTS.md,DSH每次会话开始都会读它,一次配置永久生效。
任务跑一半想介入,有三种方式。停止/取消,终止当前轮次,方向错了及时止损。Queue,新消息排在当前任务结束后处理,不想打断它但先表达诉求。Steer,新指令立即插入正在执行的工作,发现跑偏立刻纠正。
插件:DSH的灵魂,也是风险点
"一切皆插件"不是口号。你看到的整个Web UI就是一百多个插件组合的——权限审批、计划模式、上下文压缩、Skills、侧边栏,全是插件。装插件用dsh plugin --profile web add <包地址>,装完必须重启。
社区已有两百多个公开插件仓库。代表性项目包括:dsh-better-sidebar(侧边栏完整工作台)、dsh-open-in-vscode(一键在VS Code打开工作区)、dsh-at-file(Codex风格@file引用)、dsh-notification(任务完成桌面通知)、dsh-annotation(网页选中批注)。
但要记住:插件能执行任意代码,三档权限体系管不住它。装插件前务必确认来源可信,当成装系统软件对待。
无界面运行与多Agent
不开网页也能跑:dsh run "把docs/目录下所有md文件合并为一个README.md",输出结果后退出。适合CI/CD流水线、定时脚本、批量处理。
多Agent协作方面,Subagent是可续跑的后台子代理,结果自动回传;Subagent_fork是一次性的,任务结束即回收;Workflow是脚本化的确定性编排;Ralph循环每轮启用全新子代理试错直到通过。配合Skills,复杂任务可以拆解给多个Agent并行。
还支持MCP服务器接入、Hooks桥复用Claude Code/Codex脚本、ACP内置服务端、官方Python SDK。
DeepSeek Harness目前还是开发者预览版,接口和插件API可能随时变,不适合直接上生产。但它给出的"模型+Harness=Agent"公式很有意思——模型负责思考,Harness负责执行,中间用插件缝合。如果你愿意折腾,它是个值得长期关注的底座。