夜雨聆风DeepSeek Harness是DeepSeek推出的开源Agent底层框架，核心理念一切皆插件，基于Cordis内核实现运行时热插拔插件、Agent自进化能力，GitHub上线单日Star突破3.7万。本文面向零基础小白，一步一步完成环境安装→一键启动→API配置→工作区设置→四种模式实操→插件安装全流程，全程无晦涩术语，跟着操作即可跑通本地AI智能体工作台。
一、前置准备：2个必备工具
1. 安装Node.js（硬性要求，最低v22.19，推荐v24 LTS）
Harness依赖Node运行环境，Windows/macOS/Linux三系统安装方法：
Windows系统
1. 打开官网 https://nodejs.org/ 下载LTS长期支持版（.msi安装包）
2. 双击安装，全程下一步，务必勾选Add to PATH（自动配置环境变量）
3. 安装完成后，关闭所有终端重新打开，输入校验命令：
出现v22.x/v24.x代表安装成功；若提示node不是内部命令，重启电脑重试。
macOS系统
方式1（官网安装）：官网下载.pkg安装包双击安装；
方式2（Homebrew一键安装），终端执行：
校验依旧使用node -v。
Linux系统
2. 申请DeepSeek API Key（调用模型必需）
没有密钥无法使用AI能力，申请步骤：
1. 浏览器打开DeepSeek开放平台：https://platform.deepseek.com/
2. 手机号/微信登录，完成实名认证（不实名无法创建密钥）
3. 左侧菜单栏点击「API Keys」→右上角创建API Key
4. 自定义密钥名称（如本地Harness测试），点击创建
5. ⚠️重点：密钥仅显示一次，立刻复制保存到记事本，关闭页面无法找回
6. 账户余额：新用户有免费测试额度，用完后可充值，V4 Pro高峰期调用价格偏高
二、两种安装启动方式（新手优先选一键npx）
方式一：一键启动（推荐新手，无需下载源码）
1. 在桌面新建空文件夹（作为Agent工作目录，避免读取隐私文件）
2. 打开终端（Windows用PowerShell，Mac/Linux用终端），cd进入该文件夹
3. 执行官方启动命令：
4. 首次运行会自动下载依赖，终端询问Proceed?输入y回车等待
5. 下载完成后，终端输出本地访问地址：http://127.0.0.1:3080，复制到浏览器打开即可
端口占用解决
3080端口被占用时，自定义端口启动：
方式二：源码本地部署（适合开发者二次修改）
需要提前安装pnpm包管理器：
三、首次打开WebUI……核心配置（3步解锁全部功能）
步骤1：切换中文界面
页面左下角点击Settings（设置）→通用设置找到Language，切换简体中文，降低操作门槛。
步骤2：填入DeepSeek API密钥
1. 设置页左侧选择「模型」
2. 找到DeepSeek模型卡片，粘贴之前保存的API Key，点击保存
3. 模型可选：DeepSeek-V4-Flash（速度快、性价比高）、DeepSeek-V4-Pro（推理更强，价格更高），可调节思考强度
步骤3：绑定工作区（AI可操作的文件目录）
1. 返回首页，点击「选择工作区」
2. 选中之前创建的空测试文件夹，确认添加
3. 作用：AI仅能读写该文件夹内文件，不会篡改电脑其他目录文件，保障安全
四、四大Agent模式详解+新手使用建议
新建会话时会弹出4种预设模式，本质是不同插件组合模板，按需选择：
1. 标准模式（90%新手首选，全能通用）
• 内置全部核心插件：文件读写、Shell终端、网页搜索、代码编辑、子Agent、工作流规划
• 适用场景：日常写代码、项目重构、文档分析、批量文件处理
• 操作：直接输入自然语言指令，例如「读取项目所有JS文件，优化代码并输出修改记录」
2. PTC模式（程序化工具调用，高效批量任务）
• 拥有标准模式全部能力，新增Code Mode SDK
• 优势：模型自动生成TypeScript脚本，把多轮工具调用合并一次执行，减少模型往返、节省Token
• 适合：多步骤批量自动化、爬虫、多文件批量修改；新手不推荐，调试难度高
3. 极简模式（仅测试专用，普通用户不用）
• 仅保留2个工具：持久Bash终端、文件编辑器，删除所有附加能力
• 用途：模型基准性能对比，日常使用会缺失搜索、规划等功能，体验极差
4. 创造模式（Harness核心特色，高阶玩法）
• 完整标准能力+运行时自省插件，支持Agent自我改造
• 实操示例：
1. 输入指令：「创建一个仅允许读取代码、禁止修改文件的安全审计Agent」
2. Agent自动检测当前插件，缺少对应能力则现场生成插件，热加载到运行流程中，无需重启服务
• 适合：自定义专属智能体、开发第三方插件
五、实战操作：新建会话，让AI处理项目
1. 首页点击「新建会话」，选择标准模式（新手默认）
2. 在输入框下发任务，举2个常用案例：
案例1：代码开发任务
分析当前工作区项目结构，找出所有未捕获异常的函数，自动添加try-catch容错代码并保存文件
案例2：文档整理任务
遍历文件夹所有Markdown文件，提取标题生成目录文档，保存为summary.md
3. 执行过程：页面会实时展示AI调用工具、修改文件、执行终端命令的完整轨迹；侧边「轨迹视图」可查看每一步操作日志，失败可回溯调试
六、社区第三方插件安装（扩展功能）
Harness支持一键安装社区开源插件，大幅提升使用体验，推荐5款刚需插件：
1. dsh-at-file：输入框@文件名，快速指定AI读取文件，不用手动复制路径
仓库：https://github.com/omdsh-dev/dsh-at-file
2. dsh-genui：支持渲染图表、Mermaid流程图、表格、代码Diff面板，可视化输出
3. DSH-better-sidebar：VS Code风格侧边栏，内置文件管理器、终端、Git、浏览器
4. ModLens：给模型增加识图能力，对话直接粘贴图片解析内容
5. dsh-automation：定时自动化任务插件，支持脚本循环执行
插件安装步骤
1. 打开设置→「插件」→「社区插件」
2. 输入插件仓库地址，点击安装
3. 安装完成自动生效，无需重启Web服务；创造模式可本地开发自定义插件
七、常见报错&避坑指南
1. node版本过低报错EBADENGINE
现象：启动时提示版本不兼容、语法错误
解决：升级Node至v22.19/v24 LTS，重装后重启终端
2. npx命令下载依赖卡住
解决：切换npm国内镜像，终端执行：
3. 提示MISSING_CREDENTIAL密钥缺失
排查：①模型页面密钥是否保存成功；②刷新页面重新填写；③密钥未过期、账户无封禁
4. 浏览器打不开127.0.0.1:3080
排查：①终端窗口不要关闭，关闭即停止服务；②端口占用更换--port参数；③关闭防火墙拦截本地地址
5. 模型无法修改文件/执行终端
解决：首次操作弹窗权限确认，勾选允许文件读写、Shell执行权限
八、停止&重启服务
1. 停止：打开启动用的终端窗口，按下Ctrl + C终止服务
2. 重启：依旧执行npx @deepseek-ai/dsh web，无需重复配置API和工作区，配置自动保存
DeepSeek Harness不是普通代码助手，而是可完全自定义的Agent底层基建，「一切皆插件」的架构支持自由增减AI能力。新手先使用一键npx启动+标准模式完成基础开发任务，熟悉后再尝试创造模式自定义智能体、安装社区插件拓展功能。
官方文档：https://www.deepseek.com/harness
开源仓库：https://github.com/deepseek-ai/deepseek-harness
以上，既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～谢谢你看我的文章，我们，下次再见。