DeepSeek Harness：从零装跑，让 AI 真的动手干活

最近 DeepSeek Harness（DSH）——DeepSeek 开源的编码智能体框架——发布了。它不只是陪你聊天，而是能直接读写你电脑里的文件、执行命令、联网查资料、拆解任务并行跑。开源十几小时 Star 就冲到 6 万多，核心卖点是 「一切皆插件」：每个能力都能像积木一样拔插组合。

这篇教程从零带你装到跑通，所有命令都可直接复制。

目录

• 一、它到底是什么
• 二、准备 Node.js 环境
• 三、安装 DSH
• 四、第一次启动 Web 界面
• 五、配置模型和 API Key
• 六、熟悉 Web 界面
• 七、第一次对话：让它真改文件
• 八、核心功能怎么选
  • 四种 Agent 预设
  • 工具集
  • Plan 模式和 Goal
  • 子代理与工作流
  • 斜杠命令速查
• 九、权限与安全：这步别跳过
• 十、命令行模式：headless 和 plugin
• 十一、配置文件在哪
• 写在最后

一、它到底是什么

DSH 由两部分组成：一个叫 dsh 的命令行工具负责启动和管理智能体，一个浏览器 Web 界面让你像聊天一样派活。

它的设计核心是 Profile（配置档）。一个 Profile 由多个「插件组合包」按顺序叠加，再叠上你的个性化配置。标准模式、极简模式、创造模式，本质上就是同一套引擎挂了不同的插件组合。

二、准备 Node.js 环境

DSH 基于 Node.js 运行，需要 Node 22 LTS 或更高版本。

1. 打开 https://nodejs.org 下载最新版，一路下一步安装。
2. 打开终端验证：

node --version
npm --version

能打印出版本号（例如 v24.x 和 11.x）就说明环境就绪。习惯用 pnpm 的也可以，后面命令把 npm 换成 pnpm 即可。

三、安装 DSH

一条命令全局安装：

npm install -g @deepseek-ai/dsh

装完验证：

dsh --version
dsh --help

--version 打印版本号，--help 列出 web、headless、plugin 等入口。

四、第一次启动 Web 界面

Web 界面是最常用入口。在你想当作「工作目录」的文件夹里打开终端，执行：

dsh web

终端会打印一个本地地址，默认 http://127.0.0.1:3080，浏览器打开就行。

五、配置模型和 API Key

DSH 默认用 DeepSeek 官方模型（默认 deepseek-v4-flash），需要 API Key 才能对话。最方便的是在界面里配——你第一次进入 DSH 时系统会强制填写：

1. 点右上角 Settings（设置）。
2. 进 Models（模型） 页。

3. 填你的 DeepSeek API Key，选默认模型，保存。

Key 需要去 DeepSeek 开放平台 https://platform.deepseek.com 充值后新建。

偏好命令行的话，用环境变量：

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"

凭证解析优先级是：环境变量 → 托管凭证文件 → 项目/用户 .env。所有数据都统一放在 ~/.dsh 目录，也可以用 DSH_HOME 环境变量换位置。

六、熟悉 Web 界面

先花一分钟认一下布局，后面效率高很多。

输入框里打 / 会弹出斜杠命令菜单：/compact 压缩上下文、/plan 计划模式、/goal 建目标、/model 切模型、/export 导出会话。

七、第一次对话：让它真改文件

工作目录里放一个 hello.js，然后输入：

帮我读一下 hello.js，在结尾加一行 console.log('done')，然后运行它。

提交后你会看到完整过程：先 read 读文件，再 edit 改文件，然后 pwsh/bash 运行脚本，最后汇报结果。每一步工具调用都透明地展示在对话流里，可以点开看详情。

新手建议先从只读任务开始，比如「帮我看看这个项目是干什么的」，熟悉交互后再放手让它改代码。

八、核心功能怎么选

四种 Agent 预设

在设置 → 通用，或新建会话时切换，决定 Agent 带了哪些能力：

预设	适用场景
标准模式	日常编码、读写文件、跑命令的默认选择
极简模式	只做纯对话，不碰文件和命令，适合问答
创造模式	放开更多工具与网络，适合探索性/跨模块任务
自定义	自己拼装插件组合，按需叠加

工具集

AI 会按任务自动挑工具：文件类有 read / write / edit / glob / grep；命令行走 bash 或 pwsh，可前台可后台；联网用 web_search；任务管理有 todo_write、ask_user_question；后台任务用 job_* 系列。

Plan 模式和 Goal

• Plan 模式（/plan）：先只做只读探查，不碰任何文件，产出一份实施计划等你审批，批准了才动手。改别人代码、动生产目录前先开它。
• Goal 目标（/goal）：适合「重构整个项目」这种需要跨多轮自动推进的长任务，DSH 会自己续跑到目标达成或遇阻塞。

子代理与工作流

复杂任务可以分身并行——主 Agent 把活扇出给多个子代理，再汇总结果。

还有一个 Ralph loop 模式：每轮用一个无记忆的新子代理推进同一目标，靠工作目录当持久记忆，适合需要反复重新审视、避免钻牛角尖的长期任务。

斜杠命令速查

命令	作用
/compact	压缩当前上下文，省 token
/plan	进入计划模式，先出方案再执行
/goal	设定长期目标自动续跑
/model	切换模型
/export	导出当前会话
/clear	清空当前会话

九、权限与安全：这步别跳过

AI 真能动你的文件，所以 DSH 内置了沙箱和审批机制，共三档：

模式	权限范围
read-only	只读，不写文件、不执行命令
workspace-write	可写工作目录，越界需审批（默认）
full-access	全盘访问，风险最高

默认是 workspace-write + 审批。AI 尝试越界时会弹审批框，你决定放行还是拒绝。也可以用环境变量强制指定：

export DSH_PERMISSION_MODE="workspace-write"

新手保持默认即可，务必在专用目录里运行 DSH，别一上来就在家目录或系统盘开 full-access。子代理同样受这套沙箱约束。

十、命令行模式：headless 和 plugin

除了 Web，还有两个实用入口。

headless 适合脚本化和 CI——一句话任务，跑完即退：

dsh headless "把 src 下所有 .js 文件里的 var 改成 const"

plugin 用来给某个 Profile 增删插件，参数转发给 pnpm：

dsh plugin add @dsh/plugin-git
dsh plugin remove @dsh/plugin-git

web 和 headless 是内置 Profile，首次使用自动从模板初始化；自定义 Profile 要通过 dsh plugin 创建。其他常用启动器参数：

dsh web --port 4000          # 换端口
dsh web --profile minimal   # 指定 Profile
dsh --dump-config           # 查看当前合并后的配置

十一、配置文件在哪

所有用户数据都在 ~/.dsh（或 $DSH_HOME）下：

~/.dsh/
├── profiles/          # 各 Profile 配置
│   └── standard/
│       └── cordis.patch.yml
├── credentials/       # 托管的 API Key
└── sessions/          # 会话历史

配置树按优先级叠加：组合包 patch → profile 的 cordis.patch.yml → 家目录级 cordis.patch.yml → --patch 覆盖层，后写覆盖前写。

cordis.patch.yml 是深度定制的关键。先用 dsh --dump-config 看当前组合结果，再用 patch 层按行 id 覆盖任意插件配置。这部分建议熟悉基础后再摸。

写在最后

DSH 把「聊天」升级成「真正动手干活」，又用沙箱权限和透明的工具调用过程把风险关在笼子里。给新手的建议很明确：从标准模式 + workspace-write 开始，在专用目录里先做只读分析，再逐步放手让它改代码、跑任务。等你玩熟了插件叠加和工作流，它就不只是个编码助手，而是一个可以自己组装的自动化团队。