ARTICLE · 1130969
DeepSeek Harness 保姆级教程:从安装到实战,全网最详细上手指南
DeepSeek 又放大招了。
这次不是模型，而是一个能让 AI 在你电脑上真正干活的开源框架——DeepSeek Harness（简称 dsh）。
上线不到一个月，GitHub 已经拿下 22 万+ Star，成为国内开源项目的新标杆。但很多人下了代码却不知道怎么用，配置文件一堆，模式看得头晕。
别急，这篇教程带你从零开始，一步步搞定 DeepSeek Harness 的安装、配置和实战，看完你就能让 AI Agent 真正为你干活。
一、DeepSeek Harness 是什么？
简单说，DeepSeek Harness 是 DeepSeek 官方的 Agent 框架。
如果说 DeepSeek 模型是 AI 的大脑，那 Harness 就是给大脑配上的身体和手脚。有了它，AI 才能：
读取你电脑上的文件 执行命令行操作 修改代码 搜索网页信息 管理自己的任务流程
核心理念就八个字：一切皆插件。
框架的所有能力——模型适配、工具注册、会话管理、沙箱环境、Agent 循环本身——全部由插件提供。你可以自由替换、组合、扩展任何功能，不需要改一行源码。
另一个亮点是 可追溯性。Agent 做的每一步操作、调用每个工具、产生的每个结果，都记录在追加式日志中。你可以随时回溯、搜索、甚至分叉重来。
二、四种运行模式，总有一款适合你
DeepSeek Harness 预置了四种运行模式，它们的核心区别不是模型不同，而是开放的插件和能力不同。
标准模式（Standard Mode）—— 默认选择
功能最完整，适合日常编码工作。
内置能力包括：
文件编辑器，支持查找替换 持久化 Shell 终端，可以跑任意命令 文件和网页搜索 Skills 技能系统 规划与目标管理 子代理并行处理 工作流编排
适合场景：日常开发辅助、代码重构、Bug 修复、项目分析。
代码模式（Code Mode）—— 高级用户首选
在标准模式基础上，额外暴露了 Code Mode SDK。
模型可以通过生成 TypeScript 代码来编排多轮工具调用，把多个步骤合并成一个程序执行，适合复杂的多步骤任务。
适合场景：自动化工作流、复杂任务编排、需要精确控制执行流程的场景。
极简模式（Minimal Mode）—— 测试专用
只保留两个核心工具：
持久化 bash 终端 文件编辑器
没有其他花里胡哨的功能，专为基准测试设计。
适合场景：模型能力评测、研究、轻量级任务。
创造者模式（Creator Mode）—— 插件开发者的天堂
包含标准模式全部能力，还额外提供运行时检查和插件实验环境。
你可以在内存中测试 Cordis 插件，查看当前运行时状态，结合它们创建新的预设模式。
适合场景：自定义插件开发、构建专属 Agent 预设、探索框架边界。
三、一键安装，3 分钟启动
方式一：npx 一键启动（推荐）
这是最简单的方式，一条命令搞定：
npx @deepseek-ai/dsh web执行后会：
自动下载并安装依赖 启动本地服务（默认端口 3080） 自动打开浏览器访问 http://127.0.0.1:3080
国内用户如果遇到下载慢的问题，可以先切换镜像源：
npm config set registry https://registry.npmmirror.com npx @deepseek-ai/dsh web方式二：DSH Desktop 桌面版（新手友好）
如果你不想折腾命令行，官方社区推出了桌面客户端。
访问 https://dshdesktop.com/zh/ 根据你的系统下载：
Windows：下载 .exe 安装包 macOS Apple Silicon：下载 ARM64 的 .dmg macOS Intel：下载 x64 的 .dmg
下载安装后双击启动，界面更直观，不用碰终端。
方式三：源码安装（开发者专用）
如果你想深入研究或二次开发：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web四、首次配置，两步搞定
安装完成后，第一次启动需要做两步配置。
第一步：配置 API Key
进入 Settings → Models，在 DeepSeek 卡片中填入你的 API Key。
API Key 可以从 DeepSeek 开放平台 申请，免费额度足够个人使用。
如果是其他模型服务商（OpenAI、Anthropic 等），也可以在这里配置，Harness 支持多种模型适配。
第二步：选择工作区
点击 Choose workspace，选择一个项目目录作为 Agent 的工作空间。
注意：没有选择工作区之前，会话编辑器是不可用的。这不是 Bug，选上就好。
两件事做完，你就可以开始和 Agent 对话了。
五、实战演示：让 Agent 真正干活
配置完成后，我们来体验一下 Agent 的实际能力。
示例一：分析项目结构
在对话框中输入：
分析当前项目的所有 TypeScript 文件，统计各模块的代码量，生成一份汇总报告Agent 会：
使用搜索工具找到所有 .ts/.tsx 文件 逐一读取并统计代码行数 按模块分类汇总 生成报告展示给你
示例二：批量查找并替换
找到项目中所有 console.log 语句，替换为统一的日志函数调用Agent 会：
搜索所有 console.log 的使用位置 分析上下文确定合适的日志级别 批量替换为标准日志函数 每步操作前弹出确认框
示例三：代码审查
审查最近一次提交的所有变更，检查潜在的安全问题和代码规范问题Agent 会：
获取 git diff 查看变更内容 扫描安全风险模式（如硬编码密钥、SQL 注入等） 检查代码规范问题 生成详细的审查报告
六、进阶玩法
自定义插件
Harness 的强大之处在于它的插件系统。每个插件包含四个导出：
name：插件名称 inject：依赖注入 Config：配置定义 apply：应用逻辑
你可以开发自己的插件来扩展能力，也可以从社区下载别人写的插件。在 GitHub 搜索 dsh-plugin 标签就能找到大量社区插件。
自定义 Profile
你可以基于现有模式创建自己的 Profile，选择需要的插件组合，保存为自定义预设。这样每次启动都可以快速加载自己定制的工作空间。
工作流自动化
Harness 内置了 Workflow 系统，可以编排多步骤的自动化任务。支持条件分支、循环、子代理调度，适合把重复性工作自动化。
七、安全与注意事项
权限控制
Harness 提供了三种权限级别：
- Always Allow
：自动允许，无需确认 - Ask First
：每次执行前弹出确认 - Always Deny
：拒绝执行
建议对新项目使用 Ask First 模式，熟悉后再考虑调整为 Always Allow。
高危操作确认
删除文件、执行带权限的命令、修改系统配置等高危操作，Agent 会先弹出确认框等你点头。你不确认，它就不动手。
Developer Preview 阶段
目前 Harness 仍处于 developer preview 阶段，会有破坏性更新。不建议直接在生产环境使用，可以先在个人项目中试用。
写在最后
DeepSeek Harness 的出现，让 AI Agent 从云端走进了你的本地电脑。
它不是另一个 ChatGPT 网页版，而是一个真正能在你机器上跑起来、帮你干活的智能体框架。你可以训练它熟悉你的项目、你的工作习惯、你的代码风格，让它成为你的专属开发助手。
从安装到实战，这篇教程覆盖了所有入门知识点。 如果你已经装好了，不妨在评论区分享一下你用 Agent 做了什么有趣的事。
如果觉得这篇文章对你有帮助，点个【在看】，让更多人看到。
欢迎关注我，下期更精彩。