外观
DeepSeek Harness 使用教程
一、它是什么
DeepSeek Harness(dsh) 是 DeepSeek AI 官方开源的 Agent Harness(智能体执行框架),采用 "一切皆插件"(Everything is a plugin) 架构,底层由 Cordis 驱动。
一句话:它解决"模型会回答,但不会稳定干活"的问题——把模型、工具和工作环境组织成一个执行闭环,让 AI 能真正读写工作区、运行命令、维护计划、委派子任务并持续执行直到完成任务。
注意:它不是本地大模型,也不要求部署 DeepSeek 权重。Harness 在本机操作工作区,模型推理仍走你配置的 API。
关键信息
| 项目 | 说明 |
|---|---|
| GitHub | https://github.com/deepseek-ai/deepseek-harness(15.6k+ Star,MIT 协议) |
| 官网 | https://deepseek.com/harness |
| 文档 | https://deepseek-harness.github.io/deepseek-harness/ |
| 状态 | Developer Preview(0.1.0-rc.x),会有破坏性兼容变更,升级前锁版本、跑回归 |
二、安装前准备
1. Node.js
官方开发环境支持 Node.js 22.19+ 和 24+(不要用奇数版本):
bash
node -v
npm -v
# 没有的话用 nvm 装
nvm install 22
nvm use 222. DeepSeek API Key
前往 DeepSeek 开放平台 创建 API Key,确认账户有可用余额。
Key 只在首次配置时复制一次;不要发进聊天记录、不要写进 Git 仓库、不要截图带 Key 的设置页。
3. 一个可放心修改的项目副本
第一次使用不要直接选生产目录。准备一个已提交 Git、能本地跑测试的练习仓库——改错了能看到 diff、能恢复。
三、安装与启动
方式一:npx 一条命令(推荐体验)
bash
cd /你的项目绝对路径
npx @deepseek-ai/dsh web- 默认地址:http://127.0.0.1:3080,自动打开浏览器
- 指定端口:
npx @deepseek-ai/dsh web --port 3081 - 不自动开浏览器:
npx @deepseek-ai/dsh web --no-open
关键:从哪个目录启动,哪个目录就是默认工作区位置。不要在用户主目录或包含大量项目的父目录启动。
方式二:全局安装(可选)
bash
npm install -g @deepseek-ai/dsh
dsh --version # 验证安装方式三:源码运行(定制/二次开发)
bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh webDeveloper Preview 阶段更新很快,建议先用
npx体验当前版本,不必急着全局安装。
四、首次配置(三步)
第一步:配置模型
打开 Web UI → 设置 → 模型 → 填入 DeepSeek API Key → 保存。
- 除 DeepSeek 官方外,还支持 Anthropic、OpenAI 及自定义 OpenAI 兼容端点(模型路由即时生效,无需重启);
- 首次体验建议先用官方 DeepSeek 路线,少加一层排查变量。
第二步:选择工作区
回到首页点击 Choose workspace,添加并选中启动 dsh 时的项目目录。
没有选中工作区时,会话输入框不可用——这不是 Bug,是防止 Agent 在未确认的目录里执行。
第三步:先跑最小任务
先只读、后修改。第一次别上来就说"重构整个项目":
text
请先不要修改文件。阅读这个仓库,告诉我:
1. 项目解决什么问题;
2. 主要模块分别负责什么;
3. 本地启动和测试命令是什么;
4. 你的结论分别来自哪些文件。通过后再给小型修改任务:
text
请修复当前失败的单元测试。
要求:
- 先复现失败,再定位原因;
- 只修改与根因有关的文件;
- 不新增依赖,不提交 Git;
- 修复后运行相关测试;
- 最后列出修改文件、验证命令和仍未解决的风险。发送前检查四处:左侧工作区是否目标项目 / 顶部是否标准模式 / 输入框下方是否 Workspace Write / 右下角模型与推理等级——先把执行边界选对,再发送。
五、Agent 预设(设置 → Agent 预设)
| 预设 | 能力 | 适用 |
|---|---|---|
| 标准模式 | 完整编码 Agent:文件编辑、Shell、文件与网页检索、Stella、计划、目标、子代理、工作流 | 第一次使用选它 |
| PTC 模式 | 标准模式全部能力 + 通过 Code Mode SDK 用 TypeScript 程序组合多步操作 | 步骤多、工具调用密集的任务 |
| 极简模式 | 仅持久 bash + str_replace_editor 两个工具 | 基准测试、严格限制工具面 |
| 创造模式 | 标准模式全部能力 + 运行时检查、组件实验、preset 创作指导 | 创建自定义 Agent 预设 |
别看名字选花哨的:普通仓库开发先用标准模式,确认现有能力不够再叠加复杂度。
六、高效使用技巧
- 一次只给一个可验证目标 —— 任务写清四项:
目标(改变什么)/范围(允许读写哪些目录)/约束(不能改什么)/验收(执行什么命令算完成)。 - 先调查,再动手 —— 陌生项目先让它复现问题、画调用链、给根因与最小修改范围,你确认方向后再执行。数据库迁移、鉴权、支付、部署脚本尤其如此。
- 验收命令写进任务 —— 明确要求跑测试/Lint/构建;"Agent 说完成,不算完成;验证器通过,才算完成"。
- 缩小工作区 —— 无关文件越多,搜索噪声、Token 消耗和误改风险越大;可禁止修改生成目录、构建产物、第三方代码。
- 先读项目规范 —— 有
AGENTS.md/CLAUDE.md时,第一轮要求 Agent 先读取并复述与任务相关的约束。 - 一个会话一条主线 —— 同一 Bug 的验证继续原会话;换功能、换仓库、换目标就新开会话。
- 探索用快模型,关键修改用强模型 —— 仓库搜索、日志归类用快模型;跨模块修复、架构决策、高风险审查切强模型。
- 审批是最后一道边界 —— 安装依赖、访问工作区外文件、高风险命令不要闭眼放行;删除、数据库写入、部署、Git 提交始终由人确认。
七、Headless 模式(重复任务自动化)
任务稳定后,用官方 headless profile 跑一次性任务,无需一直开着浏览器:
bash
npx @deepseek-ai/dsh --profile headless "运行测试,修复失败用例,并输出验证结果"- 创建一段可持久化的新会话,打印最终答复后退出;
- 适合场景:每晚扫描一批仓库生成报告、CI 失败后自动收集日志定位根因、批量补文档/补测试/格式迁移、外层脚本调度多个独立任务。
建议:先在 Web UI 把任务跑稳定,再搬到 Headless——否则只是把一个不稳定的 Prompt 自动执行很多次。
八、插件机制("一切皆插件")
模型适配器、工具注册、会话日志、Agent 循环、文件系统、沙箱、审批策略——全部是插件。意义:可替换其中任意一层,不必 Fork 整套代码。
- 模型换成公司网关,执行层不动;
- 本地文件系统换成远程沙箱,Agent 循环不动;
- 增加内部工单、数据库、发布工具,不改核心;
- 换会话存储、审批策略、日志系统,模型工具仍复用。
排查配置时可查看最终组合出的插件树:
bash
npx @deepseek-ai/dsh --profile web --dump-config开发插件:给仓库打 dsh-plugin topic 便于被发现,教程见官方插件开发文档。
九、安全红线(这些别交给它无人值守)
- 直接改生产数据库、线上配置、云资源;
- 无测试和审批门禁的自动提交 / 合并 / 发布;
- 把密钥、客户数据、未脱敏日志交给外部模型;
- 需求本身不清楚时做大范围架构重写;
- 把 Agent 的最终文字当成测试结果或安全审计结论。
常见问题速查
| 问题 | 处理 |
|---|---|
| 端口被占用 | --port 3081 指定其他端口 |
| 会话输入框不可用 | 还没选中工作区,先添加并选中项目目录 |
| 版本升级后不兼容 | Developer Preview 特性,先锁版本、跑回归测试再升 |
| 想临时体验 | 用 npx 而非全局安装,随时跟随最新版 |
| 模型配置后不生效 | 保存后立即可用,无需重启;确认 Key 有余额 |