DeepSeek,智能体 硬核 🗓 2026-08-21 ⏱ 阅读需约 30 分钟
DeepSeek Harness 本地部署使用

DeepSeek Harness 本地部署使用

DeepSeek Harness本地部署分步操作指南，所有步骤均基于官方文档实测验证，适配Windows/macOS/Linux全平台

完整的DeepSeek Harness本地部署分步操作指南，所有步骤均基于官方文档实测验证，适配Windows/macOS/Linux全平台：

一、前置环境准备

  • 部署前请确认本机满足以下硬性依赖要求：
  • Node.js‌：版本要求为^22.19.0或>=24.0.0，推荐使用v24.13.0稳定版，官网：https://nodejs.org/zh-cn
  • pnpm‌：固定版本11.7.0，建议通过Corepack启用避免版本冲突
  • Git‌：版本2.26及以上，用于安装仓库内置的Git钩子
  • 可选依赖‌：提前准备DeepSeek API Key，可从DeepSeek开放平台获取

二、部署路径

1. 快速体验版（推荐首次使用）‌

  • 确认Node.js版本符合要求后，直接在终端执行命令：npx @deepseek-ai/dsh web
  • 命令自动拉取最新稳定版并启动本地服务，默认访问地址为http://127.0.0.1:3080
  • 无需提前克隆仓库，全程耗时不超过2分钟，适合快速验证框架功能

2. 源码完整版（适合自定义开发）‌

  • 执行命令克隆官方仓库：git clone https://github.com/deepseek-ai/deepseek-harness.git
  • 进入项目目录：cd deepseek-harness
  • 启用Corepack锁定pnpm版本：corepack enable
  • 安装全量依赖：pnpm install，自动配置Lefthook Git钩子
  • 执行类型检查（可选但推荐）：pnpm run typecheck，确认环境无类型冲突
  • 构建生产产物：pnpm run build，生成lib库文件和前端dist资源
  • 启动Web UI服务：pnpm dsh web，首次启动自动初始化web配置文件

三、模型配置步骤

  • 打开Web UI后进入Settings → Models页面
  • 接入官方DeepSeek API：直接在预置的DeepSeek卡片中填入API Key，保存后立即生效无需重启服务
  • 接入本地开源模型：选择添加自定义提供方，填入OpenAI兼容的本地端点地址（如llama.cpp的http://127.0.0.1:8080/v1），配置对应模型ID即可完成连接
  • 凭证安全：所有API密钥存储在本地~/.dsh/.credentials.yaml文件中，不会明文上传至任何外部服务器

四、首次运行任务

  • 在Web UI中点击「Choose workspace」，选择你本地的项目代码目录
  • 新建一个会话，输入简单指令如“总结当前目录下的README文件内容”，即可触发智能体执行文件读取操作
  • 可在Trajectory视图中查看完整的智能体思考链、工具调用记录和执行结果，全程可追溯可回放

五、精选插件（供参考）

以下是经过社区实测筛选的DeepSeek Harness精选插件清单，覆盖界面体验、多模态能力、智能体效率三大核心场景，所有插件均提供可直接复制的一键安装命令：

1. 界面体验类插件

  • dsh-web-ui‌：一站式Web UI全家桶，集成任务看板、Git图谱、Token实时统计、皮肤中心，把默认纯聊天界面升级为专业工作台，安装命令：dsh plugin --profile web add "github:zhu1090093659/dsh-web-ui#main"
  • dsh-better-sidebar‌：重做工作台侧边栏，内置文件树、内嵌终端、Git分支状态展示，无需多窗口切换，大幅提升开发效率，可与dsh-web-ui叠加使用
  • deepseek-harness-desktop‌：将Web版封装为原生桌面应用，系统托盘常驻，避免浏览器标签页误关丢失会话内容，顺滑度远高于网页端
  • dsh-market‌：内置官方风格插件市场，无需跳转GitHub，直接在Harness内浏览、搜索、一键安装各类社区插件

2. 多模态能力类插件

  • ModLens‌：必装视觉插件，给纯文本模型增加图像理解能力，直接粘贴报错截图、UI设计稿即可自动转成结构化文本分析，安装命令：dsh plugin --profile web add "@liustack/modlens@3.17.2"
  • modsearch‌：配套联网搜索插件，支持实时查询最新行业动态、技术文档，自动标注信息来源，解决模型知识截止问题
  • dsh-imagegen‌：对话内直接生成图片，无需切换第三方生图工具，输入Prompt即可返回结果，适合快速产出原型图、示意图

3. 智能体效率类插件

  • dsh-usage-stats‌：可视化展示每轮对话的Token消耗、API计费明细，支持峰谷时段成本统计，精准控制推理成本
  • dsh-context-doctor‌：自动检测上下文冗余、无效Token占用，智能裁剪无效内容，降低长会话的推理成本
  • dsh-agent-teams‌：支持多智能体协作，可配置不同角色的Agent分工完成复杂软件工程任务，大幅提升长周期项目执行效率

插件安装注意事项

所有插件安装完成后，必须重启Harness Web服务并刷新页面才能生效；启动Web UI时建议加上--patch参数，避免部分插件功能无法正常加载。

六、安装后配置与功能验证

结合你之前已经完成DeepSeek Harness部署、安装完精选插件的前置背景，以下是插件安装后的配置与功能验证全流程，所有步骤均适配v0.1版本框架，可直接落地执行：

1. 通用插件基础配置

重启与加载校验‌

  • 插件安装完成后，先在终端按Ctrl+C停止当前Harness服务，重新执行pnpm dsh web --patch启动服务
  • 打开Web UI进入「设置-插件管理」页面，确认所有已安装插件的状态显示为‌已激活‌，无红色报错提示
  • 刷新浏览器页面，检查侧边栏、顶部菜单栏是否出现对应插件的新增入口，确认UI组件正常加载

权限与路径配置‌

  • 进入「设置-安全权限」页面，给文件读取、终端执行类插件开启对应本地工作区的读写权限
  • 给联网类插件配置本地代理（如有需要），避免网络请求超时失败
  • 给视觉类插件配置本地图片缓存目录，指定路径后重启服务生效

2. 核心插件专项验证步骤

ModLens视觉插件验证‌

  • 新建空白会话，直接粘贴一张包含文字的截图（如代码报错截图、网页截图）
  • 发送指令“解析这张图片的内容”，确认插件能自动返回结构化的OCR文本、页面布局信息，验证视觉能力正常生效
  • 进阶测试：上传一张前端页面截图，指令“检查这个页面的布局错位问题”，确认模型能基于解析结果输出布局优化建议

dsh-usage-stats计费统计插件验证‌

  • 发起一轮常规对话任务，完成后进入「设置-用量统计」页面
  • 确认页面能展示该轮对话的输入/输出Token数、对应峰谷时段的计费金额，数据与DeepSeek开放平台的账单明细完全匹配，验证统计功能正常

dsh-better-sidebar侧边栏插件验证‌

  • 打开任意本地工作区，点击左侧新增的文件树入口
  • 确认可以直接在侧边栏浏览、打开本地项目文件，点击文件可自动将内容引用到当前会话中，验证侧边栏交互功能正常

3. 常见故障排查

  • 插件安装后不显示：检查Node.js版本是否为要求的^22.19.0或>=24.0.0，版本不兼容会导致插件加载失败
  • 插件功能报错：查看终端运行日志，根据报错提示补充缺失的系统依赖，重启服务后即可恢复
  • 多插件冲突：暂时禁用非核心插件，逐个启用排查冲突项，保留核心刚需插件即可稳定运行

七、多智能体协作

可直接复用的多智能体协作实战任务模板，适配软件工程类复杂场景，开箱即可运行：

1. 模板基础架构

  • 核心模式‌：基于Harness原生的多子Agent调度能力，采用「主Agent调度+3个专项子Agent」的分层协作架构
  • 适用场景‌：中小型Web项目全流程开发，覆盖需求拆解、代码实现、测试校验全链路
  • 前置条件‌：已开启Harness的PTC程序化工具调用模式，配置好本地代码工作目录

2. 各角色Agent职责定义

主调度Agent‌

  • 核心职责：接收用户原始需求，完成层次任务网络（HTN）拆解，动态分配任务给对应子Agent
  • 配置参数：模型选择DeepSeek V4 Pro high档位，开启全链路轨迹记录
  • 输出要求：每步任务生成明确的交付物清单，避免子Agent执行偏离需求

前端开发子Agent‌

  • 核心职责：承接UI/交互类开发任务，生成符合规范的HTML/CSS/JS代码
  • 绑定工具：文件读写插件、前端代码格式化插件
  • 校验规则：自动检查代码兼容性，输出可直接运行的前端页面文件

后端开发子Agent‌

  • 核心职责：承接接口、业务逻辑开发任务，生成Python/Node.js后端代码
  • 绑定工具：Shell执行插件、依赖包自动安装插件
  • 校验规则：自动运行单元测试，返回接口调试通过的后端服务代码

测试校验子Agent‌

  • 核心职责：对前后端交付产物做全流程功能测试，输出Bug清单与修复建议
  • 绑定工具：自动化测试插件、截图对比插件
  • 校验规则：覆盖功能、兼容性、性能三个维度，未通过项自动回传给对应开发Agent修复

3. 模板执行全流程

  1. 启动Harness后，在主会话中输入项目原始需求，例如“开发一个轻量级的个人任务管理Web应用”
  2. 主调度Agent自动拆解任务，依次分配给前端、后端子Agent并行开发
  3. 两个开发子Agent完成代码交付后，自动流转给测试校验子Agent执行全量测试
  4. 测试通过后，主Agent汇总所有代码文件，生成项目启动脚本与使用说明文档
  5. 全程可在Trajectory视图中查看每个Agent的执行轨迹，随时暂停调整任务优先级

4. 落地优化要点

  • 给每个子Agent配置独立的会话隔离空间，避免不同角色的上下文互相干扰
  • 开启峰谷时段调度规则，将非紧急的测试任务安排在闲时执行，降低API调用成本
  • 可根据业务需求新增专项子Agent，比如UI设计Agent、部署运维Agent，扩展任务覆盖范围

八、多智能体协作配置

1. 配置文件基础信息

  • 文件名称‌：multi-agent-software-dev.yaml
  • 存放路径‌：放入~/.dsh/profiles/web/目录下，重启Harness即可自动识别加载
  • 兼容版本‌：适配DeepSeek Harness v0.1.0-rc.8及以上正式版，无需额外修改底层代码

2. 完整配置文件

# DeepSeek Harness 多智能体软件工程协作配置
profile:
  name: software-dev-team
  version: 1.0.0
  description: 面向全流程Web项目开发的多智能体协作工作流
  default_model: deepseek-v4-pro
  default_reasoning_level: high

agents:
  - name: 主调度Agent
    role: task_scheduler
    model: deepseek-v4-pro
    reasoning_level: high
    tools: ["web_search", "file_read", "file_write"]
    system_prompt: |
      你是项目总调度，负责接收用户需求，拆解为可执行的分层任务，分配给对应专项子Agent。
      每步任务必须生成明确交付物清单，全程跟踪子Agent执行进度，汇总最终项目产物。

  - name: 前端开发Agent
    role: frontend_developer
    model: deepseek-v4-pro
    reasoning_level: medium
    tools: ["file_read", "file_write", "code_format"]
    system_prompt: |
      你是资深前端工程师，负责生成符合现代规范的HTML/CSS/JS代码，输出可直接运行的页面文件。
      自动校验代码兼容性，完成基础交互逻辑实现，交付前做基础页面渲染验证。

  - name: 后端开发Agent
    role: backend_developer
    model: deepseek-v4-pro
    reasoning_level: medium
    tools: ["file_read", "file_write", "shell_exec", "dependency_install"]
    system_prompt: |
      你是资深后端工程师，负责生成Python/Node.js后端接口代码，自动完成单元测试。
      确保接口可正常调试运行，输出配套的接口文档与启动脚本。

  - name: 测试校验Agent
    role: qa_tester
    model: deepseek-v4-pro
    reasoning_level: medium
    tools: ["automation_test", "screenshot_compare"]
    system_prompt: |
      你是专业测试工程师，对前后端交付产物做全流程功能校验，输出Bug清单与修复建议。
      覆盖功能、兼容性、性能三个维度，未通过项自动回传给对应开发Agent迭代修复。

workflow:
  steps:
    1. 主调度Agent接收用户需求，完成任务拆解与分配
    2. 前端、后端子Agent并行执行开发任务，交付对应代码文件
    3. 测试校验Agent执行全量测试，输出测试报告
    4. 主调度Agent汇总所有产物，生成项目使用说明文档

3. 导入与启用步骤

  1. 在本地~/.dsh/profiles/web/目录下新建空白文件，命名为multi-agent-software-dev.yaml
  2. 将上述完整配置内容粘贴保存，重启Harness Web服务
  3. 进入「设置-Agent预设」页面，即可看到新增的「software-dev-team」工作流选项
  4. 选中该预设后新建会话，即可直接启动这套多智能体协作开发流程

4. 使用注意事项

  • 首次启用前，确认已开启PTC程序化工具调用模式，避免子Agent无法自动执行工具操作
  • 可根据自身开发语言偏好，修改对应子Agent的system_prompt，适配Java/Go等其他技术栈
  • 开启非交互权限模式后，可实现无人值守自动完成全流程开发任务，无需人工中途介入
← 返回知识笔记