DeepSeek Harness 实战:从零搭建你的第一个 AI Agent 工作流
DeepSeek Harness (dsh) 是一款开源的 Agent 运行框架,它让 AI 能够直接操作你的本地文件系统和终端。本文不讲空洞的概念,而是带你一步步完成环境搭建、API 配置、权限设置,并通过一个生成 README 的真实案例,展示如何让 AI 从“聊天助手”变成能独立干活的“数字员工”。适合希望提升开
为什么你需要 DeepSeek Harness
过去两年,大模型的能力大家有目共睹。但大多数时候,我们和 AI 的交互还停留在“你问我答”的对话框里。你想让它改代码,得复制粘贴;想让它跑个脚本,得手动执行。这种割裂感让 AI 始终像个“顾问”,而不是“员工”。
DeepSeek Harness(简称 dsh)的出现,试图打破这个局面。2026 年 8 月,DeepSeek 正式开源了这款 Agent 产品,直接对标 Claude Code。它的核心逻辑很简单:把 AI 放进你的电脑里。它不仅能读你的文件,还能执行命令、调用工具,甚至按照你设定的流程自动完成任务。
更重要的是,它基于 MIT 协议开源。这意味着你可以完全掌控它,不用担心数据隐私,也能根据自己的需求定制插件。对于开发者来说,这不仅是一个工具,更是一个可以扩展的自动化平台。
本文将跳过晦涩的理论,直接带你从零开始,在一个晚上内搭建好 dsh,并让它帮你完成一个真实的开发任务。
第一部分:dsh 到底是个什么角色
在动手之前,先搞清楚 dsh 的定位,能帮你避开很多误区。
它不是另一个聊天机器人
很多人会把 dsh 和网页版 ChatGPT 或 IDE 里的 AI 插件混淆。其实它们的分工完全不同:
- 网页版 ChatGPT:像是一个博学的图书馆员。你问它问题,它给你答案。但它碰不到你的电脑,也改不了你的代码。
- IDE 插件:像是坐在你旁边的结对编程伙伴。它能看懂当前打开的文件,给你建议,但它的权限受限,通常不能随意执行系统命令或跨文件操作。
- DeepSeek Harness:像是一个拥有完整权限的远程助理。它运行在你的本地环境或服务器上,可以读写任意指定目录的文件,执行终端命令,甚至联网搜索。它的工作对象是你真实的文件系统,而不是一段被粘贴进来的文本。
它能帮你干什么
一旦配置好,dsh 可以承担以下类型的任务:
- 代码工程维护:读懂一个陌生的开源仓库,定位 Bug,重构模块,补充单元测试,或者生成项目文档。
- 自动化脚本执行:批量处理文件,定时清洗数据,生成报表,或者执行复杂的部署流程。
- 信息调研与汇总:并行搜索多个信息源,交叉验证数据,输出结构化的调研报告。
- 运维辅助:在受控环境中排查日志,检查服务状态,验证部署结果。
关键在于,所有这些操作都在你的控制之下。dsh 提供了细粒度的权限管理和审批机制,确保 AI 不会“自作主张”。
第二部分:十分钟搭建开发环境
搭建 dsh 的环境非常简单,你只需要两样东西:Node.js 和 dsh 本体。不需要数据库,也不需要复杂的配置。
1. 安装 Node.js
dsh 是基于 TypeScript 开发的,运行在 Node.js 环境中。因此,第一步是确保你的机器上安装了 Node.js。
- 版本要求:由于 dsh 仍处于快速迭代阶段,官方要求 Node.js 22 及以上版本。如果你之前的版本较老,建议升级到最新的 LTS 版本。
- 验证安装:打开终端,输入以下命令:
node -v
npm -v如果看到类似 v24.11.1 和 11.6.2 的版本号,说明环境准备就绪。
2. 启动 dsh
你不需要单独下载安装包,直接使用 npm 即可运行。推荐新手使用 npx 命令,它会自动下载并启动最新版本的 dsh,无需全局安装。
在终端中输入:
npx @deepseek-ai/dsh web第一次运行时,终端会滚动下载依赖包,这可能需要一两分钟。当看到如下输出时,说明启动成功:
Harness web UI running at: http://127.0.0.1:3080此时,打开浏览器访问 http://127.0.0.1:3080/,就能看到 dsh 的主界面。
小贴士:如果下载速度慢,可以临时切换 npm 镜像源:
npm config set registry https://registry.npmmirror.com
第三部分:配置大脑——连接模型服务
刚打开界面时,你会发现输入框是灰色的,无法使用。这是因为 dsh 本身只是一个“躯壳”,它需要连接到大模型服务才能思考。
1. 获取 API Key
dsh 默认支持 DeepSeek 的模型服务。你需要前往 DeepSeek 开放平台 注册账号,并在“API Keys”页面创建一个新的密钥。
注意:API Key 只会显示一次,请务必复制保存到安全的地方。不要将其截图发到公共群组,也不要提交到 Git 仓库。
2. 在 dsh 中配置密钥
回到 dsh 界面,点击右上角的设置图标,选择“模型”标签页。在列表中找到 DeepSeek 提供商,填入刚才复制的 API Key,点击保存。
保存后,界面顶部的模型状态栏会显示当前使用的模型(如 DeepSeek-V4-Flash)。如果显示正常,说明配置成功。
3. 接入其他模型(可选)
如果你习惯使用其他模型,dsh 也支持 OpenAI 兼容的接口。例如,你可以在本地运行 Ollama,然后通过自定义提供商接入。
在“模型”设置页点击“添加自定义提供方”,填写以下信息:
- Base URL:
http://localhost:11434/v1(以 Ollama 为例) - API Key: 留空(本地服务通常不需要)
- Models:
qwen2.5:7b(你本地运行的模型名称)
保存后,你就可以在会话中随时切换模型了。
第四部分:划定地盘——理解工作区
在 dsh 中,“工作区”(Workspace)是一个核心概念。你可以把它理解为 AI 助手的“办公桌”。只有明确了办公桌在哪里,AI 才知道去哪里找文件,把做好的东西放在哪。
1. 为什么必须有工作区
如果没有工作区,AI 就无法访问你的文件系统。这是出于安全考虑,防止 AI 随意读取或修改你电脑上的任何文件。
2. 创建第一个工作区
在左侧边栏,点击“+”号添加工作区。系统会弹出文件选择器,让你选择一个文件夹。
建议:选择你的项目根目录。例如,如果你正在开发一个 Next.js 博客,就选择该博客的源码文件夹。避免选择 C 盘根目录或用户主目录,因为范围太大不仅会让 AI 检索变慢,还会增加误操作的风险。
选中目录后,dsh 会自动记录路径,并创建该工作区下的初始会话。此时,你会发现底部的输入框解锁了,可以开始输入指令。
第五部分:发出第一条指令
现在,让我们让 AI 动起来。点击左上角的“新会话”按钮,创建一个独立的对话窗口。
1. 一个简单的只读任务
为了测试环境,我们先发一个安全的、只读的指令:
列出当前工作区目录下的所有文件,并简要说明这个项目是做什么的。按下回车后,你会看到对话区开始出现内容。与普通聊天不同,dsh 会展示它的“思考过程”和“工具调用记录”。
2. 解读工具调用树
在对话下方,你会看到一个展开的工具调用树,类似这样:
[Think]:AI 正在分析指令,决定下一步行动。[ReadDir]:AI 调用了读取目录工具,查看工作区文件。[ReadFile]:AI 读取了package.json或README.md等关键文件。[Reply]:AI 综合信息,生成最终回答。
你可以点击每一行展开查看详情。例如,点开 [ReadFile],你可以看到 AI 具体读了哪个文件,以及文件的内容。这种透明度让你清楚知道 AI 到底做了什么,而不是黑盒操作。
3. 查看统计信息
任务完成后,底部会显示一行统计信息,包括耗时、Token 消耗、缓存命中率等。这些数据有助于你优化后续的使用策略。例如,如果 Token 消耗过高,可能需要精简指令或清理上下文。
第六部分:进阶功能——让 AI 更听话
掌握了基本操作后,以下几个进阶功能能让你的工作效率倍增。
1. 权限管理:安全第一
AI 在你电脑上干活,权限控制至关重要。dsh 提供了三种权限模式:
- Read Only:只读模式。AI 只能查看文件,不能修改或执行命令。适合调研代码。
- Workspace Write:工作区写入。AI 可以读写工作区内的文件,但修改工作区外的文件或执行危险命令时需要你审批。这是日常推荐的模式。
- Full Access:完全访问。AI 拥有所有权限,无需审批。仅在高度信任的自动化场景下使用。
在输入框左侧可以切换权限模式。当 AI 尝试执行超权限操作时,会弹出审批卡片,你需要确认后才能继续。
2. 设定目标:防止跑偏
有时候,AI 会过度发挥。比如你让它修一个 Bug,它可能顺便重构了整个模块。为了避免这种情况,你可以设定“目标”(Goal)。
在对话开始时,明确告诉 AI:
本次会话的目标是:修复登录页在手机端显示错乱的问题。只做这一件事,不要进行其他优化。dsh 会将这个目标记住,并在 AI 每一步决策时进行校验,确保它不偏离主线。
3. 计划模式:先审方案再动手
对于高风险任务,如数据库迁移或大规模重构,建议使用“计划模式”。
输入 /plan 进入计划模式。此时,AI 不会直接执行操作,而是先输出一份详细的执行计划,包括步骤、影响文件等。你审阅确认无误后,AI 才会按步骤执行。
4. 子代理与后台任务
- 子代理:对于复杂任务,可以让主 AI 委派子代理并行处理。例如,“用两个子代理分别调研官方文档和社区案例,最后汇总”。
- 后台任务:耗时较长的任务(如全量测试)可以放到后台运行,不会阻塞当前的对话。你可以在侧边栏查看后台任务的状态。
第七部分:实战演练——自动生成 README
理论讲得再多,不如动手做一次。我们来完成一个真实任务:为一个已有项目生成一份标准的 README.md 文件。
步骤 1:准备工作
- 确保已配置 API Key。
- 已将项目目录添加为工作区。
- 权限模式设置为
Workspace Write。
步骤 2:新建会话并设定目标
点击“新会话”,输入:
设定目标:为当前工作区的项目生成一份专业的 README.md 文件。步骤 3:下达具体指令
接着输入:
请分析当前项目的结构和关键文件(如 package.json, src/index.ts 等),生成一份 README.md。
内容需包含:
1. 项目简介
2. 主要功能特性
3. 安装与运行指南
4. 贡献指南
请先读取相关文件,再生成内容。生成后直接写入工作区根目录。步骤 4:监控与审阅
观察工具调用树,你会看到 AI 依次读取文件、思考结构、最后调用 WriteFile 工具生成 README.md。
任务完成后,打开项目根目录,检查生成的 README.md 文件。如果内容有偏差,比如安装命令错误,可以直接在对话中反馈:
安装命令应该是 pnpm install,请修正。AI 会立即修改文件。满意后,这个任务就完成了。
第八部分:脱离界面——CLI 玩法
除了图形界面,dsh 还提供了强大的命令行工具(CLI),适合集成到脚本或 CI/CD 流程中。
Headless 模式
你可以直接在终端运行任务,无需打开浏览器:
dsh run "分析当前目录的代码结构,生成一份架构说明文档"运行结束后,结果会直接打印在终端上。这种方式非常适合自动化场景。
环境变量传参
在 CLI 模式下,可以通过环境变量传递 API Key,避免硬编码:
export DEEPSEEK_API_KEY="sk-xxx"
dsh run "..."第九部分:常见问题与安全建议
1. 密钥泄露怎么办?
如果不小心泄露了 API Key,请立即前往 DeepSeek 平台吊销该密钥,并重新生成一个新的。不要在代码库中明文存储密钥。
2. AI 执行了意外操作?
dsh 的权限机制是最后一道防线。保持 Workspace Write 模式,并在审批弹窗中仔细检查 AI 的操作意图。如果发现异常,立即拒绝。
3. 响应速度慢?
检查网络状况,或尝试切换更快的模型(如 Flash 版本)。另外,过长的上下文也会拖慢速度,定期归档旧会话是个好习惯。
结语
DeepSeek Harness 的出现,标志着 AI 助手从“对话”走向“行动”。它不仅仅是一个工具,更是一种新的工作方式。通过合理配置权限、设定清晰目标,你可以让 AI 成为你得力的数字员工,处理那些重复、繁琐但又必要的开发任务。
现在,环境已经搭好,第一份 README 也已生成。接下来,去你的项目中,让 AI 帮你干点真正的活吧。遇到问题,随时回来查阅这份指南,或者在社区中寻找更多插件和工作流模板。AI 的进化很快,早点上车,才能早点享受红利。