每天吃透一个 AI 知识点 —— DeepSeek Harness 从 0 到 1 保姆级教程

转载：小红书 AI产品赵哥

前言 🔖

DeepSeek Harness（简称 DSH）是 DeepSeek 在 2026 年 8 月 13 日正式开源的 AI Agent 运行框架，MIT 协议，口号是：一切皆插件。

一句话解释：模型负责思考，Harness 负责动手。光有模型只能聊天，加上 Harness，AI 就能读你的代码、跑你的命令、改你的文件。

💡 Agent = Model + Harness

目前是 v0.1 开发者预览版，功能迭代快，适合尝鲜和研究，不建议直接上生产环境。

官网 Github：https://github.com/deepseek-ai/deepseek-harness

开发者文档：https://deepseek-harness.github.io/deepseek-harness/guide/providers

第一步：安装 Node.js 🔖

DSH 基于 Node.js 运行，先确认电脑上有这个环境。

检查是否已安装

打开终端（Windows 用命令提示符或 PowerShell），输入：

node --version

如果看到版本号（比如 v22.19.0），说明已经有了。建议版本 v22.19 以上，官方要求是 ^22.19.0 || >=24.0.0。

没装咋办？

去 nodejs 官网下载 LTS 长期支持版本，傻瓜式安装就行。

装完后重新打开终端，再执行 node --version 确认一下。很多时候 “找不到命令” 就是环境变量没刷新。

第二步：一键安装并启动 DSH 🔖

这是最快的方式，一条命令搞定：

npx @deepseek-ai/dsh web

或者全局安装后使用（以后用着更方便）：

npm install -g @deepseek-ai/dsh
dsh web

两种方式选一种就行。推荐第一种 npx，适合首次尝鲜。

💡 如果卡住了怎么办？

npx 卡住，八成是网络问题 —— 换国内 npm 镜像源，或者直接从 GitHub 克隆源码安装。

跑起来后，终端会显示：

浏览器打开这个地址，就能看到 DSH 的 Web 界面了。

第三步：首次打开，三步配置 🔖

输入框默认是灰的，需要先做两件事才能开始对话。

🔹1 配置 API Key

进入 Settings → Models，找到 DeepSeek 卡片，填入你的 API Key 并保存。

还没有 Key？去任何一家开放平台注册账号，创建一个 sk‑xxx 格式的 Key。注意不要泄露给别人。

注意：可以接入其他 OpenAI 兼容的模型，不一定要用 DeepSeek 自家的。

下面的例子是添加了本地的qwen3.8 27B 模型。

🔹2 选择工作区

点「选择工作区」，添加一个你想让 AI 操作的文件夹。建议单独准备一个练习目录，避免 AI 误操作重要文件。

你在哪个目录启动 dsh web，那个目录就是默认工作区。

🔹3 选择运行模式

DSH 提供了四种预设模式，不同模式加载不同插件：

模式	特点	适合谁
标准模式	功能完整，包含文件编辑、Shell、搜索、子代理等	日常使用，大部分场景选这个
PTC 模式	允许模型写 TypeScript 程序来组合多步操作	需要处理复杂自动化任务
极简模式	仅保留 Shell 和文件编辑两个工具	做基准测试、最小化复现
创造模式	提供运行时检查和插件实验指导	想自己开发插件和预设的开发者

第一次用选标准模式就行。

🔹4 权限管理

Harness 内置了三档权限，左下角盾牌图标切换：

Read Only：适合代码审查、逻辑分析，绝对安全。
Workspace Write（推荐）：能读写当前工作区文件夹，碰不到系统其他地方。日常开发首选。
Full Access：完全放行，能执行任意系统命令。

如果 Agent 准备执行超出当前权限的操作，会弹窗让你确认。

🔹5 斜杠命令

在输入框打 /，会呼出命令面板：

/plan：进入计划模式，AI 先列方案，你确认后再动手，防止瞎改。
/goal：给长任务设定总目标，AI 会记住并持续朝目标推进，中途跑偏了会自己纠正。
/compact：压缩早期对话历史，给上下文腾空间，长会话卡顿时的救命稻草。
/permission：快速切换权限等级。
/model：临时切换当前对话用的模型。

第四步：开始你的第一次对话 🔖

配置完成后，在对话框输入任务，点击发送。

新手建议从简单任务开始，别上来就把几百 GB 的项目扔进去。

推荐先试这个：

分析当前目录的结构，生成一个简要说明

或者：

帮我看看这个项目里有哪些测试文件

DSH 会开始工作 —— 读取文件、执行命令、调用工具，并把每一步的执行过程展示给你看。

🔹进阶一：从源码安装（想读源码 / 开发插件）

如果你不满足于一键启动，想深入研究或二次开发，可以走源码安装：

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装pnpm (如果没有的话)
npm install -g pnpm
或者执行 curl -fsSL https://get.pnpm.io/install.sh | sh -

# 安装依赖并构建
pnpm install
pnpm run build

# 启动
pnpm dsh web

这样就能拿到最新代码，也可以修改插件、提交 PR。

🔹进阶二：Python SDK（程序化调用）

如果想在脚本或 CI/CD 中调用 DSH，可以用官方 Python SDK：

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows用 .venv\Scripts\activate

# 安装SDK
pip install deepseek-harness-sdk

# 设置API Key
export DEEPSEEK_API_KEY=sk-your-key-here

然后参考仓库 examples 目录下的脚本，编写自己的调用代码。

DeepSeek Harness 安装 Skill 🔖

skill 是 DSH 里”给 AI 预装技能”的机制：一个 Markdown 文件，就能教会模型一套固定的做事规范——比如”按琉璃风格写页面”“写规范 commit message”“整理 Obsidian 笔记”。之后只要对话匹配到它，模型就会自动加载并按规范执行，不用每次重复交代。

它有两个特点，决定了它很实用：

一个文件就是一个技能：创建零成本，随时改、随时生效（热加载，不用重启）；
两种触发方式：模型自动发现调用，或你手动 /skill名 强制注入；

🔹Skill 结构：一个带元数据的 Markdown 文件

skill 本质是 YAML frontmatter + Markdown 正文。frontmatter 告诉系统”这个技能叫什么、干什么、什么时候用”：markdown

---
name: my-skill            # 必填：kebab-case（小写+连字符）
description: 一句话说明这个 skill 做什么，模型靠它决定何时调用
whenToUse: 可选：补充使用时机
disable-model-invocation: false   # true 则模型目录里隐藏
user-invocable: true              # false 则 /命令 里隐藏
---
# 正文：给模型的具体操作指令

必填只有 name 和 description；name 必须 kebab-case（mySkill 会直接失效）；
⚠️ 只扫描一层，不支持嵌套目录。

skill 没有”安装”动作，放进扫描目录即被发现。

优先级	位置	说明
100	`<项目根>/.dsh/skills/`	项目级，项目根 = 最近的 `.git` 祖先
200	`<项目根>/.agents/skills/`	项目级（通用 agent 目录）
300	`customSkillDirs` 配置的目录	自定义
400	`~/.dsh/skills/`	用户级，任何会话都可见
500	`~/.agents/skills/`	用户级

<项目根>/.agents/skills/

可以看到agents目录下面有好多skill了，h3-prompt-writing 是用来写Minimax H3提示词的skill，skill的下载地址

https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing

🔹总结一下过程（三步）：

写文件：按上面结构写 SKILL.md，正文写清操作规范（最好附反例）；
放目录：<项目根>/.agents/skills/；
验证：新会话问 “你现在有哪些可用技能?”, 或者说 “加载 agent目录下的 h3-prompt-writing skill“。

🔹简单案例：把代码审查流程沉淀成技能

在项目根目录创建 .agents/skills/code-review/SKILL.md
新建一个会话（目录会在会话首个步骤注入，所以新开会话最稳妥）。
向 Agent 说：”请帮我审查一下刚才那个 PR。”
Agent 应当：在技能目录里看到 code-review 技能 → 调用 skill 加载正文 → 按流程审查 → 输出结构化的审查意见。

配置多模态能力 🔖

我们先确认大模型支持视觉，DeepSeek Harness本身不限制图片，限制的是你配置的模型是否支持多模态。关键点：DSH只是适配识图能力，能不能识图，取决于接入的模型。

比如我用的是 Qwen3.8-27B-Uncensored-IQ3_M.gguf 模型，是可以支持多模态图片识别的。只需要在

DeepSeek Harness 配置一下就可以了。

在 DeepSeek Harness web页面，依次点击设置 — 模型 — 打开配置文件。

在配置文件中，添加 defaultInput: [text, image], 然后重启web页面。

具体配置信息可以参考官方文档：https://deepseek-harness.github.io/deepseek-harness/guide/providers

ui-onboarding:
  welcomeNoticeVersion: 2026-08-13.1
llm-pi-ai:
  providers:
    {
      qwen-local:
        {
          displayName: qwen-local,
          apiKeyEnv: QWEN_LOCAL_API_KEY,
          api: openai-completions,
          baseURL: http://124.58.133.217:8000/,
          defaultInput: [text, image],
          models:
            [
              {
                  id: Qwen3.8-27B-Uncensored-IQ3_M.gguf,
                  name: Qwen3.8-27B-Uncensored-IQ3_M.gguf
                }
            ]
        }
    }
agent-default-model:
  provider: qwen-local
  model: Qwen3.8-27B-Uncensored-IQ3_M.gguf
dsh-community-market:
  sources: []

重启以后，在聊天中，上传一张图片，可以看到是可以正常的识别图片了。

安装常见问题与解决方法 🔖

我在首次安装的过程中，也遇到了一些问题，现整理如下。随着我的使用，发现更多问题再和大家分享。

🔹1 首次运行 npx 卡住不动

现象：执行 npx @deepseek‑ai/dsh web 后，终端只显示几行警告甚至完全没输出，看起来像卡死了，持续几分钟毫无反应。

终端示例：

原因：首次运行时，npx 会从 npm 仓库下载完整的依赖包。这不是卡死，而是在下载。但在 Windows 环境下，这个过程可能会好几分钟，且没有任何进度反馈。

解决方法：

耐心等待：首次下载确实需要时间，可以观察任务管理器的网络占用，确认是否在下载。

配置国内镜像源：在国内使用淘宝镜像源加速：配置后重新执行启动命令。

npm config set registry https://registry.npmmirror.com

改用全局安装：避免每次 npx 都重新下载缓存：

npm install -g @deepseek-ai/dsh
dsh web

🔹2 Node.js 版本不兼容

现象：启动时报错，提示与 Node.js 版本相关。

解决方法：

在终端运行 node --version 确认当前版本。
如果版本低于 v22.19，前往 nodejs 官网下载最新的 LTS 版本进行升级。
部分桌面应用可能要求 Node.js 24 或更高版本，注意查看对应说明。

🔹3 明明装了 Node.js，但提示找不到命令

现象：运行 node --version 时，提示 'node' 不是内部或外部命令。

解决方法：先关闭当前终端窗口，重新打开一个新的终端再试一次。这通常是因为安装 Node.js 后，环境变量没有立即刷新。如果问题依旧，需要手动将 Node.js 的安装目录添加到系统环境变量 Path 中。

🔹4 Windows 系统下 Bash 工具不可用

现象：使用极简模式时，涉及 Bash 命令的操作失败。

原因：Windows 系统默认没有内置 Bash 环境。

解决方法：

安装 Git for Windows：安装后它会提供一个可用的 Bash 环境。
切换模式：在 Windows 下使用 Bash 工具，需要将 Agent 的运行模式切换为 Full Access（完全访问）模式，全称 danger‑full‑access。
使用社区适配 Preset：社区已有开发者制作了专为 Windows 适配的 Minimal（Git Bash） 预设，可以在 Web UI 中直接切换。

🔹5 桌面版封装应用启动报错

现象：使用第三方封装的 DSH 桌面应用时，启动超时或提示缺失依赖。

解决方法：

检查应用版本：确保你使用的是最新版本（部分桌面版已修复漏打包依赖的问题）。
数据目录冲突：某些桌面版会使用独立的数据目录（如AppData\Roaming\dsh‑desktop\dsh‑home）来避免与旧的~/.dsh目录冲突。如果启动超时，检查是否有残留的 DSH 进程占用了端口，或清理旧的缓存目录。
安装路径：确保安装路径为纯英文字符，避免因中文路径导致渲染进程异常。

🔹6 插件加载失败或配置文件错误

现象：安装某个插件后，DSH 启动失败，或插件无法使用。

解决方法：

使用诊断工具：官方提供了 dsh‑doctor，可以自动扫描并尝试修复常见的配置问题：

npx dsh-doctor scan --profile web
npx dsh-doctor recover --profile web

它会创建恢复点，修复失败时自动回滚，相对安全。

手动检查：检查 ~/.dsh/profiles/web/cordis.patch.yml 等配置文件是否有语法错误（如 YAML 格式不对），或引用了不存在的插件。

🔹7 端口 3080 被占用

现象：启动时终端报错 EADDRINUSE: address already in use。

解决方法：最常见的是之前启动的 DSH 实例没有完全关闭。关闭所有终端窗口，或在任务管理器中结束所有 node 进程，然后重新启动。如果确实需要更换端口，可以查阅官方文档配置其他端口。

DeepSeek Harness 好用的插件 🔖

🔹插件 1：deepseek‑harness‑desktop

仓库：https://github.com/anywhere-labs/dsh-desktop Star：17k

安装命令：双击安装（无需命令行）

简介：社区开发的 DSH 桌面客户端，将 DeepSeek Harness 打包为 Electron 桌面应用，可自动启动、管理本地 Harness 服务，集成系统托盘与桌面窗口能力。无需安装 Node.js、无需敲代码命令，双击即可运行，同时支持可视化管理、一键安装各类社区插件，是体验 DSH 完整插件生态的核心载体。目前主要支持 macOS、Windows 系统。

适用场景：不想配置 Node.js、不愿使用命令行的轻量化开发者；需要常驻系统托盘、随时快速启动 Harness 的用户。

推荐理由：补齐官方无桌面端的短板，极致降低使用门槛，告别复杂部署流程，是新手入门 DSH 插件生态的首选载体，所有社区插件均可在该客户端内可视化操作。

🔹插件 2：dsh‑web‑ui‑all

仓库：zhu1090093659/dsh‑web‑ui Star：5.3k

安装命令：

dsh plugin --profile web add @linxin666/dsh-web-ui-all@latest

简介：DSH 全能 UI 全家桶插件，一键集成十余项实用功能，是 DSH 界面美化与功能增强的基础核心插件。彻底改造原生毛坯式聊天界面，内置自定义皮肤主题、桌面宠物、良神跑分优化模式、五列任务看板、Git 图谱、实时令牌统计、手机远程访问等能力，支持 cron 定时任务，任务卡片可自动同步会话执行状态。

适用场景：所有 DSH 使用场景，适配日常开发、任务管理、远程办公、界面个性化定制等全场景需求。

推荐理由：属于基础设施级插件，一站式补齐原生 DSH 界面简陋、功能单一的短板，大幅提升使用质感与开发效率，是装机必装的核心插件。

🔹插件 3：DSH‑better‑sidebar

仓库：omdsh‑dev/DSH‑better‑sidebar Star：2.5k

安装命令：

dsh plugin --profile web add dsh-better-sidebar@latest

简介：对标 Codex、Claude Code 的 IDE 风格侧边工作台插件。为 DSH WebUI 新增专属侧边栏，集成文件查看 / 编辑、实时终端、Git 提交记录、日志查询、内嵌浏览器、子代理管理、可扩展 Tab 等全套开发工具，无需切换窗口即可完成全流程开发操作。可与 dsh‑web‑ui 插件共存互补，专注界面布局与开发工具能力补强。

适用场景：习惯 VS Code、Codex 等 IDE 开发界面的开发者，需要在浏览器端完成全套代码开发、调试、Git 管理的场景。

推荐理由：完美复刻专业代码编辑器工作台体验，彻底解决原生 DSH 功能分散、操作繁琐的问题，大幅提升网页端开发的专业性与流畅度。

🔹插件 4：dsh‑at‑file

仓库：FSMargoo/dsh‑at‑file Star：444

安装命令：

dsh plugin --profile web add https://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.6.7.tar.gz

简介：高效文件快捷引用插件，复刻 Codex 丝滑文件调用体验。在对话输入框输入 @ 即可自动唤起全局工作区文件列表，一键选中代码文件、PDF、文档等素材，自动将文件内容附加到提示词中，无需手动输入文件路径、无需复制粘贴内容。

适用场景：频繁引用项目文件、读取 PDF 文档、批量修改代码、解析配置文件的日常开发场景。

推荐理由：极大简化文件引用操作，解决手动输入路径繁琐、粘贴内容冗余的痛点，让 DSH 文件交互体验追平主流 AI 编程工具。

🔹插件 5：modlens

仓库：liustack/modlens Star：3.5k

安装命令：

dsh plugin --profile web add "@liustack/modlens@3.17.2"

简介：DSH 首款专业视觉增强插件，专为纯文本大模型补齐图像解析能力。核心逻辑为 “视觉翻译 + 文本处理”，通过原生 modlens_read_image 工具，将图片、截图、设计稿转化为带 OCR 布局语义的结构化 JSON 文本，供大模型精准解析作答。

适用场景：报错截图分析、UI 设计稿还原、流程图解析、手写笔记识别等需要图像理解的开发场景。

推荐理由：精准弥补 DeepSeek 原生纯文本模型无法看图的核心短板，图像识别流程丝滑、解析精度高，是图文开发场景的必备插件。

🔹插件 6：dsh‑browser

仓库：Lum1104/dsh‑browser Star：360

安装命令：

curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash

简介：网页自动化操作插件，赋予 DSH 完整的人机网页交互能力，可自动读取网页全文内容、模拟人工点击页面按钮、批量填写网页表单。

适用场景：线上资料调研、网页信息抓取、自动化表单填写、线上功能调试等场景。

推荐理由：解放双手，无需人工干预即可完成各类网页操作，大幅提升信息检索与线上调试的自动化效率。

🔹插件 7：dsh‑agent‑teams

仓库：NanmiCoder/dsh‑agent‑teams Star：738

安装命令：

dsh plugin --profile web add @nanmicoder/dsh-agent-teams

简介：多智能体团队协作插件，模拟真实研发团队工作模式。通过自然语言即可驱动多 AI 协作，自动创建团队、分配子代理、拆分复杂任务、梳理任务依赖，支持成员间独立收发消息、并行执行任务，Web 面板可实时查看团队工作进度。

适用场景：市场调研、技术选型、多维度报告生成、大型复杂项目拆解等需要多任务并行的场景。

推荐理由：打破单 Agent 能力局限，实现 AI 团队自主协作、任务拆解、并行落地，大幅提升复杂任务的处理效率与完整性。

🔹插件 8：dsh‑TUI

仓库：ccch1mneyyy/dsh‑TUI Star：2.2k

安装命令

dsh plugin --profile web add "github:ccch1mneyyy/dsh-TUI#main"

简介：终端交互增强插件，为无原生 CLI 能力的 DSH 补齐全屏终端交互界面。安装后执行对应指令即可进入专属 TUI 终端界面，涵盖绝大多数常用操作命令，适配纯命令行工作流。与 better‑sidebar 互补，后者优化 Web 界面，该插件专注终端场景。

适用场景：终端爱好者、习惯 CLI 命令行工作流的开发者、远程服务器部署运行 DSH 的场景。

推荐理由：补齐 DSH 终端交互短板，满足硬核开发者、远程运维用户的使用需求，适配纯命令行高效工作流。

🔹插件 9：dsh‑genui

仓库：omdsh‑dev/dsh‑genui Star：278

安装命令：

dsh plugin --profile web add git+https://github.com/omdsh-dev/dsh-genui.git

简介：高颜值可视化渲染增强插件，彻底打破 DSH 纯文本输出局限。可在 AI 回复中自动渲染生成数据表格、统计图表、代码 DIFF 对比、Mermaid 流程图、交互画板等可视化内容，无需手动搭建图表、绘制流程，全方位升级模型输出的可视化交互体验。

适用场景：代码迭代对比、数据复盘分析、业务流程梳理、需求方案可视化展示、技术文档撰写等场景。

推荐理由：让枯燥的文本回复变得直观生动，一站式补齐 DSH 可视化能力短板，大幅提升开发复盘、方案汇报、代码迭代的展示效果与工作效率。

92IT

Just love IT.

每天吃透一个 AI 知识点 —— DeepSeek Harness 从 0 到 1 保姆级教程