DSH 插件开发教程

外观

第 1 章 环境搭建与启动 ​

本章带你从零搭好 DeepSeek Harness（下文简称 DSH）的开发环境：检查前置要求、克隆仓库、安装依赖、通过类型检查，然后用 dsh 命令以 Web UI 和 headless 两种模式启动它，最后学会查看插件树并配置模型。这是后续所有章节的共同起点。

本章目标 ​

  • 检查并补齐前置要求：Node.js、pnpm、Git
  • 克隆 deepseek-harness 仓库，完成依赖安装与首次类型检查
  • 以 Web UI（--profile web）和 headless（--profile headless "任务"）两种模式启动 dsh
  • 配置 DeepSeek API key，并用 --dump-config 验证插件树

前置要求 ​

DSH 官方支持 Node.js 22.19+ 与 24+（CI 覆盖 22.19、24、26 三个版本）。包管理器使用启用了 Corepack 的 pnpm，仓库在 package.json 中固定 pnpm@11.7.0；如果 pnpm --version 无法通过 Corepack 解析，请先运行 corepack enable。Git 需要 2.26+，因为仓库钩子用到了 worktree 专属配置扩展。最后是可选但推荐的 DeepSeek API key，用于 Web、headless 与 ACP 演示以及真实 API 的 e2e 测试。

先运行这三条命令确认环境：

sh
node --version   # 期望 22.19+ 或 24+
pnpm --version   # 期望 11.7.0（由 Corepack 解析）
git --version    # 期望 2.26+

克隆仓库与安装依赖 ​

sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

pnpm install 除了安装依赖，还会通过 scripts/install-lefthook.mjs 配置 worktree 本地的 Lefthook 钩子与 dsh-translation-pairing Git 合并驱动。如果依赖是从缓存恢复或 postinstall 被跳过而导致任一集成缺失，手动补一次：

sh
node scripts/install-lefthook.mjs

首次类型检查 ​

sh
pnpm run typecheck

typecheck 成功退出即表示搭建完成。它内部先完成包含 Typert 生成在内的 Host lib 阶段，再运行 Client 侧的 TypeScript 检查——DSH 仓库刻意把 Host 与 Client 放在两个相互隔离的 aggregate（tsconfig.host.json / tsconfig.client.json）里，避免两侧对 Cordis Context 接口的声明合并互相冲突。

从源码启动 dsh ​

从源码 checkout 运行完整应用或演示前，需要先构建一次（README 的 run-from-source 路径）：

sh
pnpm run build

然后启动 Web UI：

sh
pnpm dsh --profile web

打开 http://127.0.0.1:3080。--profile web 选择名为 web 的 profile（简写形式为 pnpm dsh web）。profile 是存放在 Harness home（$DSH_HOME，默认 ~/.dsh）中的具名组装：它列出叠放的组合包（bundle）、存放树外插件，并持有用户自己的 cordis.patch.yml。web 与 headless 是随发行版交付的两个模板。

headless 模式不启动任何服务器，运行一次任务后退出：

sh
pnpm dsh --profile headless "summarize this workspace"

该模式把任务作为普通用户消息提交给 agent，需要配置 API key（见下节）。

配置模型与 API key ​

在 Web UI 的 设置 → 模型（Settings → Models）页面填入 DeepSeek API key，即可在界面中配置模型。命令行模式（headless、ACP）则从环境变量或仓库根目录一个被 gitignore 的 .env 文件读取凭证：

sh
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_BASE_URL=https://...   # 可选，默认使用公开 API

两种方式二选一或并存均可；请勿把真实凭证提交进版本控制。

验证插件树：--dump-config ​

DSH 的产品哲学是"一切都是插件"。运行中的 dsh 是一棵插件树，由启动时按序叠加的各层（组合包 → profile 的 cordis.patch.yml → home 级 patch → 任意 --patch overlay）组合而成。查看你的机器实际启动的配置树：

sh
pnpm dsh --profile web --dump-config

命令打印合成后的完整 YAML（每层带 # == 注释标明来源）。打印出的任何条目，都可以由你自己的 patch 替换或插入——这正是后续章节把插件挂进 Web UI 的入口。

小结 ​

  • 环境就绪的标志：pnpm run typecheck 成功退出。
  • 两种启动方式：pnpm dsh --profile web（浏览器界面）与 pnpm dsh --profile headless "任务"（一次性任务）。
  • 凭证两种来源：Web UI 的设置页面，或 DEEPSEEK_API_KEY 环境变量 / .env 文件。
  • pnpm dsh --profile web --dump-config 展示实际启动的插件树，是验证与调试配置的第一站。

下一步 ​

环境已经跑通。下一章 Cordis 插件基础 将介绍插件框架的核心概念——插件、Context、依赖注入、事件与 effect——这些是编写任何 DSH 插件的地基。