DeepSeek Harness in Depth

外观

前置条件 ​

来自根 README.md 与 docs/development.md：

需求值 / 说明
Node.js^22.19.0 || >=24.0.0（CI 还覆盖 26）
pnpm固定 11.7.0；若 pnpm --version 无法经 Corepack 解析，运行 corepack enable
Git2.26+
DeepSeek API 密钥Web/headless/ACP 演示与真实 API e2e 测试需要（DEEPSEEK_API_KEY 或 .env）

从 npm 运行 dsh 不需要 TypeScript 或构建工具——已发布的 @deepseek-ai/dsh 包自带构建好的 lib/*.js。只有在从源码运行时才需要构建工具链。

安装与 npm 渠道 ​

dsh 还没有稳定版发布——已发布的每个版本都是预发布，实验性包从不发布。启动器以 @deepseek-ai/dsh 发布到 npm，带三个 dist-tag：

dist-tag承载当前版本
alphaalpha 预发布0.1.2-alpha.2
canarycanary 构建—
next其他所有预发布（含 rc）0.1.1-rc.2

在 0.1.2-alpha.2 之前，所有预发布都走 next；如今 alpha 标签接收 alpha 预发布。latest 上 没有稳定版。请显式安装某个预发布渠道：

sh
npm i -D @deepseek-ai/dsh@alpha      # 或：@deepseek-ai/dsh@next

从 npm 运行 ​

先安装 Node.js，然后：

sh
npx @deepseek-ai/dsh web

启动器会启动 web profile 并在默认 http://127.0.0.1:3080 提供 Web UI（端口由 web 应用自己的标志决定， 默认为 3080）。进程以你调用它的目录作为默认文件系统根，随后 Web UI 会请你选择工作区并在 Settings → Models 中添加模型，之后会话才完全可用。参见用户指南。

同一个启动器处理所有模式——apps/cli/src/bin.ts 按模式动态导入，因此 --help/--version/解析错误会 打印并退出，只有有效模式才会进入真正的分发。

从源码运行 ​

克隆并构建：

sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
  • pnpm install 还会接线工作区本地的 Lefthook hooks 与翻译配对 Git 合并驱动（若缓存恢复的安装跳过了 postinstall，可运行 node scripts/install-lefthook.mjs）。
  • pnpm run build 构建 Host 库阶段、Client 库阶段与 Web 前端。dsh 根脚本定义是 node --import tsx/esm apps/cli/src/bin.ts，因此 pnpm dsh <args...> 直接运行 TypeScript 入口并转发所有参数。
  • 从 npm 的生产运行无需源码检出；源码路径供贡献者使用。

Profile：五个模板 ​

dsh 并不是一个带内置模式的单一程序；它启动一个 profile——存储在 Harness home 中的命名组合。五个 profile 作为模板随附（packages/boot/app-boot/src/profile.ts 中的 PROFILE_TEMPLATES）并在首次使用时 自动初始化。每个模板还固定了它的 patchReload——用户 cordis.patch.yml 编辑如何生效：web 用 live （热重载），其余四个用 startup（下次启动时应用）：

Profile带来什么典型调用
webdsh-base + dsh-web-app：服务器、浏览器 UIdsh web 或 dsh --profile web
headlessdsh-base + dsh-headless：一次性运行器，无服务器dsh --profile headless "task"
acpdsh-base + dsh-acp-app：纯自动化的 ACP stdio 服务器dsh --profile acp
sdkdsh-base + dsh-sdk-app：基于 stdio 的 JSON-RPC SDK 运行时dsh --profile sdk
sdk-minimal只有 dsh-sdk-minimal：不带共享 base 的极简双工具编码 agentdsh --profile sdk-minimal

任何其他 profile 名都必须先通过 plugin 子命令创建：

sh
dsh plugin --profile myname add <package>

常用命令 ​

启动器的命令文法位于 apps/cli/src/args.ts。它只解析自己的标志，并把其后的一切都交给被启动的 profile—— 因此应用标志（--port、--help）属于那个应用，而非启动器：

命令效果
dsh web启动 web profile（--profile web 的别名）
dsh --profile web同上，显式写法
dsh --profile headless "task"在任务上运行一个会话、打印答案并退出
dsh --profile web --helpweb 应用的帮助文本，而非启动器的
dsh --help启动器自己的帮助
dsh --profile <name> --patch extra.yml以额外补丁覆盖启动（可重复）
dsh --profile web --dump-config打印组合后的 web 树并退出（含用户层与 --patch）
dsh --profile web --dump-default-config只打印 bundle 层（不含用户层）
dsh plugin --profile <name> add <pkg>向 profile 安装插件（转发给 pnpm）

启动器标志是 --profile、--patch、--dump-config、--dump-default-config 与 --version。配置 dump 不启动树：app-boot 中的 renderConfigDump 使用 include 自身的 applyEntryPatches 组合树，因此 打印出来的树正是将要挂载的内容——在编写自己的补丁之前，这是观察插件如何层层叠加的好方法。

数据存放在哪里 ​

所有用户数据都位于 Harness home 下，由 @deepseek-ai/dsh-home-paths 解析：

  • resolveDshHome() → 显式配置的路径，否则 $DSH_HOME，否则 ~/.dsh。
  • Profile 位于 $DSH_HOME/profiles/<name>（每个都是一个 package.json 清单 + cordis.patch.yml）。
  • 家目录级覆盖是 $DSH_HOME/cordis.patch.yml；分层环境位于 $DSH_HOME/.env。
  • 托管凭据单独存放在 $DSH_HOME/.credentials.yaml。

调用目录是会话的默认工作区；Harness home 是存放 profile、凭据与用户补丁的地方。区分两者很重要：home 是机器本地状态，workspace 是 agent 处理的对象。

示例覆盖 ​

源码构建后，可运行的演示以 cordis.patch.yml 覆盖的形式位于 apps/cli/config/examples/（顶层 examples/ 层已被上游退役——commit 4125514a08）：

覆盖演示什么
cordis能检查并编辑自己实时插件树的自指 agent
github-review签名 GitHub webhook → Session 评审规则
mcp-memory经由通用 MCP 客户端的第三方内存服务器（每个服务器一个覆盖）
scheduleWeb 会话的持久提醒

它们的测试位于 apps/cli/tests/profiles/{acp,headless,sdk}。对于需要凭据的演示，在环境或仓库根 .env 中设置 DEEPSEEK_API_KEY（可选 DEEPSEEK_BASE_URL）；没有密钥时，真实 API 套件会自动跳过。

延伸阅读 ​

DeepSeek Harness in Depth