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 运行 ​

先安装 Node.js，然后：

sh
npx @deepseek-ai/dsh web

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

同一个启动器处理所有模式——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：web 与 headless ​

dsh 并不是一个带内置模式的单一程序；它启动一个 profile——存储在 Harness home 中的命名组合。两个 profile 作为模板随附并在首次使用时自动初始化：

Profile带来什么典型调用
webdsh-base + dsh-web-app：服务器、浏览器 UIdsh web 或 dsh --profile web
headlessdsh-base + dsh-headless：一次性运行器，无服务器dsh --profile headless "task"

任何其他 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 处理的对象。

示例速览 ​

源码构建后，examples/（见 examples/README.md）中有可运行的演示：

示例演示什么
headless-agent可选中输出格式的非交互式一次性 agent
jsonrpc-agent通过 Python SDK / JSON-RPC 驱动的无人值守编码 agent
web-cordis能检查并编辑自己实时插件树的自指 agent
web-schedule持久提醒的可选 Web 覆盖（dsh web --patch examples/web-schedule/cordis.yml）
acp-agentAgent Client Protocol 自动化服务器
mcp-memory经由通用 MCP 客户端的第三方内存服务器

对于需要凭据的演示，在环境或仓库根 .env 中设置 DEEPSEEK_API_KEY（可选 DEEPSEEK_BASE_URL）；没有 密钥时，真实 API 套件会自动跳过。

延伸阅读 ​

DeepSeek Harness in Depth