DeepSeek Harness：从安装到进阶

01 项目速览：你即将认识的这个工具 DeepSeek Harness（命令行缩写 dsh）是 DeepSeek AI 官方出品的开源 Agent 框架，MIT 协议，仓库地址： · 官方仓库：https://github.com/d...

01 项目速览：你即将认识的这个工具

DeepSeek Harness（命令行缩写 dsh）是 DeepSeek AI 官方出品的开源 Agent 框架，MIT 协议，仓库地址：

· 官方仓库：https://github.com/deepseek-ai/deepseek-harness

官方页：https://www.deepseek.com/harness/en/

· 官方文档：https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart

它的核心理念只有一句话：“Everything is a Plugin“（一切皆插件）——模型接入、工具调用、会话存储、审批策略、界面组件，整个系统的每一个环节都是可替换、可组合的插件。

它的架构由 Cordis 框架驱动（Koishi 生态的插件内核，设计来源于论文《A Programming Paradigm for Spatiotemporal Composability》）。

快速了解项目的几个关键事实：

它和 Claude Code / Codex 有什么区别？ 市面上的同类工具（Claude Code、Codex、WorkBuddy 等）通常把核心逻辑写死，用户只能在预留的少数接口上做有限定制。DSH 反其道而行：从模型接入到工具注册表，从会话日志到审批策略，全部插件化。换搜索引擎、接自家模型服务，改配置即可，不用动框架代码。

02 安装与启动：先把它跑起来

1.1 环境要求

先检查环境，打开终端（Windows：Win + R 输入 powershell；macOS：Command + 空格输入“终端“）：

node -v

· 能打印出 v22.19 或更高版本 → 直接跳到 1.2

· 提示 command not found： node → 到 nodejs。org 下载 LTS 版，一路“下一步“安装。务必保留安装器默认勾选的“添加到 PATH“选项，否则终端找不到命令

· 版本低于 v22.19 → 下载新 LTS 覆盖安装

1.2 四种安装方式

方式 A：一行命令快速启动（最省事，推荐首次体验）

npx @deepseek-ai/dsh web

npx 会自动拉取并运行，不需要先安装。缺点是每次都要解析下载。

方式 B：全局安装（日常使用推荐）

npm install -g @deepseek-ai/dsh

dsh --version # 验证安装，能打印版本号即成功

dsh web # 启动

方式 C：从源码运行（开发者）

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

方式 D：让 AI 帮你装

如果你已经有 Claude Code、Codex、Cursor 这类能操作终端的 AI 工具，直接把下面这段丢给它，它会把环境检查、安装、启动全流程跑完：

在这台电脑上安装并启动 DeepSeek Harness（DSH）：

1。检查 Node。js，版本需 22.19 及以上，没有则安装 LTS 版；

2。执行 npm install -g @deepseek-ai/dsh 全局安装，并用 dsh --version 验证；

3。在 D：\projects\dsh-demo 目录执行 dsh web 启动；

4。启动后把终端打印的本地访问地址告诉我。

1.3 启动后的三个关键认知

终端窗口不能关。dsh web 这个进程是真正干活的 Host，浏览器里的网页只是操作界面（遥控器）。终端一关，网页立刻失联——这不是故障，是设计。

默认只监听本机。访问地址默认是 http://127.0.0.1:3080，局域网其他设备访问不到，这是安全设计。

端口可换。3080 被占用时：dsh web --port 8080。

1.4 安装排错速查表

02 首次配置：接入模型

DSH 是“BYO 模型“模式——框架本身不带模型，需要你自己配置一个可用的模型端点。

2.1 三步拿到 API Key

充值：进入“账户余额“，先充少量（如 10 元）即可。日常试用消耗极低，摸清用量后再决定充值规模

创建 Key：进入“API Keys“页创建。创建后立即复制保存——Key 只在创建那一刻显示明文，关掉页面就再也看不到了

2.2 填入 DSH

打开 Web UI → 设置 → 模型：

在 DeepSeek 卡片中粘贴 API Key → 保存

模型选择器中选择 DeepSeek V4 Flash

配置即时生效，模型路由在保存后立即可用，无需重启服务器。

密钥安全机制：密钥字段是只写的——保存后页面只能看到脱敏描述符，永远不会回显明文。密钥存储在 $DSH_HOME/。credentials。yaml，settings 里只保留凭据引用。Key 相当于密码，别截图、别发到公开渠道。

2.3 配置其他模型提供商

不想用 DeepSeek 官方 API？DSH 的模型接入是开放体系：

添加目录提供方（Anthropic / OpenAI 等）：

设置 → 模型 → 添加提供方 → 选择提供方 → 输入 API 密钥 → 保存。已安装的目录会提供该提供方的端点、协议和模型列表。

注意 NOTE

：使用原生认证的提供方（Bedrock、Vertex、Azure、Codex）需要各自的专属凭据——如 AWS 凭据与区域、ADC 项目、api-version、OAuth。只填 API Key 字段是无法完成配置的。

添加自定义提供方（公司网关、自建服务器、目录里没有的服务）：

设置 → 模型 → 添加自定义提供方，填写：

填写时可点获取可用模型，DSH 会调用 OpenAI 兼容的 GET /models 端点自动发现模型列表（只更新草稿，保存前不会真正存储）。不提供该端点的服务，手动输入模型 ID 即可。

视觉模型注意：自定义模型在声明能力之前一律按纯文本对待。要让它能接收图片，需在 $DSH_HOME/settings。yaml 中给该模型加 input： [text， image]：

llm-pi-ai:

providers:

my-gateway:

apiKeyEnv: GATEWAY_API_KEY

api: openai-completions

baseURL: https://gateway.example/v1

models:

- id: legacy-chat

- id: vision-preview

input: [text, image]

多个模型都支持图片时，可用路由级 defaultInput： [text， image] 统一设置（它是回退值而非覆盖值，默认 [text]）。

2.4 选择模型与会话默认值

· 已配置的提供方会出现在模型选择器中

· 选择的模型会自动成为新会话的默认值

· 已发送过请求的会话会保留日志中记录的模型（即中途换模型只影响新会话）

2.5 配置阶段排错

2.6 怎么确认配置成功

不需要研究完所有设置项。直接跑一个任务——能正常返回结果就说明一切就绪（下一章就是任务实操）。

03 工作区与权限：搞清楚它能在哪动手

3.1 Workspace：Agent 的“手“能伸到哪

Workspace（工作区）是 Agent 读写文件的边界目录，不是聊天标签页。 你希望它在哪个文件夹里干活，就把哪个文件夹添加为 Workspace。

操作路径：Web UI → 选择工作区 → 添加启动 dsh 时所在的项目目录 → 选中。

一个容易忽略的细节：选中工作区之前，会话输入框是禁用的。这是强制你先划定边界再干活。

dsh 进程会把启动时所在的目录作为默认文件系统位置，但新 Web UI 在你主动添加前不会选中任何工作区。

3.2 三档权限模型

danger-full-access 的内部名已经说明了风险等级——它是“危险模式“，不是“高级模式“。选择它之前界面会弹出确认。

3.3 一个必须建立的认知：权限限制的是“写“，不是“看“

Workspace Write 只限制写入范围。读取文件、联网、查看系统进程不受同等限制——它的“手“被绑住了，但“眼睛“是自由的。

所以不要以为选了 Workspace Write，Agent 就“看不到“工作区以外的文件。涉及敏感的操作（联网上传、系统级改动）会触发审批弹窗，由你确认后才会执行，不会静默放行。

3.4 底层沙箱实现

三档权限有真实的操作系统级沙箱支撑：

此外还有两个常驻纠偏插件：重复无效动作检测（防止 Agent 对着同一个失败方案反复重试）和超时强制中断（防止任务无限期运行）

04 日常使用：界面、会话与上下文

4.1 界面布局

DSH 的 Web UI 与主流 Agent 产品布局趋同，上手零成本：

4.2 会话（Session）管理

4.3 上下文管理

· DSH 通常会自动整理较早的对话（自动压缩）

· 需要立即压缩时手动执行 /compact，把早期对话整理成摘要

· 压缩不会删除原始历史——完整日志仍然保留（见第 8 章“可追踪性“）

4.4 快捷操作

05 模式与命令：Agent 的“岗位“与“口令“

5.1 四种 Preset 模式

Preset（预设）是能力组合包——同一种模型，挂上不同的工具集和规则，就能承担不同的岗位。新建会话时选择，开始运行后锁定（模式决定工具集，中途切换会破坏会话可复现性，所以不允许切）。

安全提醒：创造模式的信任等级等同于 Shell 访问权限——它执行的代码可以直接修改 DSH 运行时。只建议在受信任环境使用。

5.2 计划模式（Plan Mode）

计划模式让 Agent 只调查、只出方案，不修改任何内容，等你确认后才动手：

· 开启：输入 /plan（或新会话选计划模式）

· 退出：输入 /plan off

适合的场景：让 Agent 先评估一个仓库、先拆解一个复杂需求、先给出方案再决定要不要执行。

5.3 斜杠命令总表

输入框敲 / 会弹出命令列表，内置命令和已安装的 Skills 都在里面：

06 与 Agent 高效协作：把话说清楚

6.1 任务描述四要素

Agent 任务效果的好坏，七成取决于你的描述质量。高质量的任务描述包含四个要素：

6.2 好与坏的对比

❌ “帮我弄一下这个报告。“——没有格式、没有范围、没有验收，Agent 只能猜。

✅ “请重排 report。docx：正文宋体小四、1.5 倍行距，一级标题黑体三号加粗（目标）；只允许改动这一个文件（范围）；正文内容一字不改、图表原样保留（禁区）；完成后列出所有标题层级清单供我验收（验收）。“

对比之下很容易看出问题：不是模型不够聪明，而是第一句话根本没有给出足够的信息。描述越具体，返工越少，这是所有 Agent 产品的通用规律。

6.3 长期规则：AGENTS。md

需要反复交代的规则（“公司名称一律用全称““金额保留两位小数“），写进工作区根目录的 `AGENTS.md` 文件。DSH 同时识别 CLAUDE。md。每次会话开始它都会读取这份文件——一次配置，永久生效，不必每次重复强调。

6.4 任务运行中的三种介入方式

任务进行到一半，你发现了新需求或想纠偏：

07 实操示例：三个由浅入深的任务

7.1 任务一：验证环境（官方推荐）

配置完成后发第一条消息，官方文档的推荐用例：

Summarize this repository and identify its main packages.

（总结这个仓库，并指出它的主要模块）

它会读取文件、运行命令、给出结构化总结。能顺利返回，说明模型、工作区、权限链路全部打通。

7.2 任务二：生成办公文档

考验“读写文件 + 格式化输出“能力：

在当前工作区生成 Word 周报模板「本周工作周报。docx」：标题黑体二号居中；四个一级标题黑体小三加粗；正文宋体小四、1.5 倍行距、首行缩进 2 字符。

任务结束后打开工作区文件夹，本周工作周报。docx 已经躺在那里。“产出真实文件“就是 Agent 与聊天机器人的本质区别。

7.3 任务三：结合计划模式做一个改造

先不要动手（用 /plan）。分析一下 worktree 目录下的 node 项目：当前用了哪些依赖、构建脚本怎么写的、如果要加一个 lint 步骤需要改哪些文件。给出方案后我再确认执行。

先看方案、再批准执行，是日常开发中最稳妥的协作节奏。

08 看懂执行过程：它到底干了什么

8.1 对话标签的顺序

每轮对话按顺序展示：上下文注入 → 思考（Think）→ 工具调用 → 审批请求 → 最终回答。

· 上下文注入：开工前把提示词、可见工具、历史记录组装给模型

· 工具调用：点开可看到完整命令、匹配到的文件和具体行号

· 审批请求：越界操作等待你的确认

8.2 Trajectory（轨迹）视图

如果 Agent 说“改好了“但你打开文件发现没变化，去轨迹标签查——它记录了 Agent 每一步的实际行为：

· 读取过哪些文件

· 执行过哪些命令

· 完成了哪些修改

· 每一步的耗时

这是排查“嘴上说改了、实际没改“类问题的第一现场，社区评价为同类框架中最好的审查工具。

8.3 日志的不可篡改性

Session 日志是 append-only（只追加、不可改写） 的：系统提示词、模型思考、每次工具调用与返回、每次上下文注入，全部原样落盘。上下文压缩不会删历史。恢复、Fork、回放依赖的都是这份完整日志。

09 多智能体与自动化

9.1 多 Agent 协作能力

配合 Skills（可复用的技能包），复杂任务可以拆解给多个 Agent 并行处理。

9.2 Headless：无界面运行

dsh run "把 docs/ 目录下所有 md 文件合并为一个 README。md"

不开网页，一行命令跑完一个任务，输出结果后退出：

典型场景：CI/CD 流水线、定时脚本任务、批量处理。

9.3 生态兼容层

· MCP：任意 MCP 服务器可接入（复用海量现成工具）

· Hooks 桥：复用 Claude Code / Codex 的钩子脚本

· ACP：内置 ACP 服务端实现

· Python SDK：官方提供，供 Python 程序调用 DSH 能力

10 插件生态：DSH 的灵魂

10.1 “一切皆插件“到底意味着什么

你看到的整个 Web UI 就是由 122 个插件组合而成的——权限审批、计划模式、上下文压缩、Skills、侧边栏、甚至“连接模型“本身，都是插件。

意味着你可以：

· 替换默认组件（换掉侧边栏、换掉审批策略）

· 添加新能力（新工具、新渲染器、新交互）

· 改造 DSH 自身的行为

10.2 安装插件

dsh plugin --profile web add <包地址>

装完必须重启才生效。

10.3 安全警告（重要）

插件能执行任意代码，三档权限体系管不住它。 安装插件前务必确认来源可信——把装插件当成装系统软件对待。

10.4 社区生态现状

GitHub dsh-plugin topic 下已有 250+ 个公开插件仓库（数字还在增长）。以下为代表性项目：

11 进阶玩法：改造 DSH 本身

11.1 创造模式的真实用例

DSH 的独特之处在于可自我修改。一个典型场景：科研用户需要直接查看蛋白质的 PDB 三维结构，他没有去搜插件、没有手写代码，只在创造模式里提出需求——Agent 随即接入 3Dmol 渲染库，在界面中生成了可交互的结构卡片。该用户后来又接入了十几个 MCP 外部数据库，一个通用 Agent 最终变成了专属科研工作站。

这个过程展示了“一切皆插件“的最终形态：Agent 自己给自己加能力，定制门槛从“会写代码“降到“会提需求“。

11.2 面向开发者的架构速览

Cordis 内核：DSH 基于 Cordis（Koishi 生态插件内核）负责插件的加载/卸载与依赖关系管理。

配置层级（插件树）：

bundle（官方成套配置）→ profile（本机具名组装清单）→ patch（精确覆盖层）

上层配置覆盖下层。

能力三角色分离：服务定义（接口规范）/ 提供方（实现）/ 消费方（使用）三者独立。例如 bash 工具的接口、本地实现、工具暴露是三个独立包——模型看到的接口恒定，换实现不影响调用方。

执行模型：

· Turn：一条用户消息引发的完整活动

· Step：一次模型请求 + 其要求的工具调用

· 每个关键位置（开始前/工具执行前后/模型请求前）都是可拦截扩展点：审批、改写、记录都挂在这里

完整链路：用户消息 → 组装上下文 → 模型 → 工具调用 → 权限/审批 → 工具结果 → 模型 → 最终回答（循环直至完成）。

值得一读的文档：插件开发指南 docs/user/develop/、配置目录 docs/config-catalog。md、架构文档 docs/architecture。md。

12 常见问题汇总

12.1 配置类

12.2 使用类

12.3 性能参考

官方公开的性能数据（DeepSeek-V4-Flash High 实测）：缓存命中可达 100%，首 token 平均约 0.3s，输出速率约 120 tck/s。

12.4 项目现状与风险提示

· 开发者预览版：核心插件和 API 仍在演进，未来有破坏性变更的可能，生产环境接入需评估

· 认准官方仓库：网上存在同名第三方仓库与 SEO 营销内容，请以 deepseek-ai/deepseek-harness 为准

· 生态竞争：Claude Code / Codex 已占据大量开发者心智，DSH 的生态仍在建设期，但有 DeepSeek 官方战略投入

12.5 社区入口

· GitHub Discussions：反馈与讨论

· 官方企微群：扫码企微小助手填问卷入群

· 微信公众号：官方动态

· dsh-plugin topic：发现插件

# 安装与启动

node -v # 检查版本（需 ≥ 22.19）

npm install -g @deepseek-ai/dsh

dsh --version # 验证

dsh web # 启动（终端保持开启）

dsh web --port 8080 # 换端口

npx @deepseek-ai/dsh web # 免安装启动

# 插件

dsh plugin --profile web add <包地址> # 装插件（装完重启）