DeepSeek Harness 实战：从零安装到跑起 Web UI 的全流程避坑指南

DeepSeek 在 2025 年开源了自家 Agent 框架 DeepSeek Harness（命令名 dsh），主打「一切皆插件」架构，由 Cordis 驱动。它目前处于开发者预览阶段，迭代很快，官方 README 给的启动命令只有三行：pnpm install && pnpm run build && pnpm dsh web。但在 Windows 上从源码跑通这三行，坑比想象的多。本文记录一次完整的安装、构建、启动过程，把踩过的坑和正确顺序写清楚，帮你少走弯路。

这个项目是什么

DeepSeek Harness 是 DeepSeek AI 开源的 agent harness（智能体框架），核心设计有两点：

• 一切皆插件：工具、LLM 后端、沙箱、UI 组件全是插件，通过 Cordis 组装。
• Cordis 驱动：Cordis 是一套「时空可组合」编程范式，论文见 cordiverse/paper 仓库。

仓库是 pnpm monorepo，规模不小：246 个 workspace 项目、7903 个文件，涵盖 CLI、Web 前端、SDK、沙箱、LSP、MCP client、多种 LLM 后端（DeepSeek、pi-ai）、多种 shell（bash/pwsh）、子 Agent 调度等。技术栈是 Node 22 + TypeScript 6 + tsdown/rolldown 打包 + Vitest 测试 + oxlint 检查。

环境准备

先确认本机环境。项目 package.json 里写死了引擎要求：

"engines": { "node": "^22.19.0 || >=24.0.0" },
"packageManager": "pnpm@11.7.0"

实测本机：

工具	要求	实测	结果
Node	≥22.19	v22.23.2	通过
pnpm	11.7.0	11.7.0	通过
npm	—	10.9.8	仅 npx 受影响

Node 和 pnpm 版本必须匹配，否则 pnpm install 会报引擎不兼容。

第一步：克隆与安装依赖

git clone https://atomgit.com/gh_mirrors/de/deepseek-harness.git
cd deepseek-harness
pnpm install

pnpm install 耗时 56 秒，装了 935 个包。有几个非致命警告：

• Linux 平台的 landlock-run 包在 Windows 上跳过（正常）。
• 循环 workspace 依赖（项目已知，cordis/include 等）。
• 两个 demo bin 创建失败（examples 和 python/sdk-runtime，非核心功能）。

node-pty 的 postinstall 会自动把 conpty.dll 和 OpenConsole.exe 拷到 build 目录，这是 Windows 上 PTY 后端需要的，不用手动处理。

安装阶段没有阻塞问题。

第二步：构建——坑最多的一步

官方说 pnpm run build 就行。直接跑，失败。

坑一：增量构建状态损坏

pnpm run build 内部执行 build:lib:host，即 tsc -b tsconfig.host.json && tsdown --env.DSH_BUILD_FACE host。第一次跑时 tsc -b 退出码 1，报 Class extends value undefined is not a constructor or null。

排查发现是增量构建的 .tsbuildinfo 状态文件损坏，导致部分项目产物缺失（vendor/cordis/lib 为空）。解决办法是先清理：

pnpm run clean

这会删掉 196 个产物路径。清理后重新构建，tsc -b tsconfig.host.json 退出码 0，所有产物正常生成。

坑二：npx/npm 自身报错

尝试用 README 推荐的 npx @deepseek-ai/dsh web 快速启动，报：

npm error Class extends value undefined is not a constructor or null

这是 npm/npx 自身的问题，不是项目代码的问题。改用 pnpm exec 或 pnpm dsh 调用就不受影响。如果你本机也遇到这个错，别怀疑项目，换 pnpm 调用即可。

坑三：tsc client 必须在 tsdown host 之后

这是最隐蔽的坑。build:lib:client 里的 tsc -b tsconfig.client.json 会报几十个类型错误，全是 TypertClientRemote 缺少属性（commands、goals、fileReferences、dynamicCordisRunner 等）。

原因是：client 的类型依赖一个叫 dsh-typert-generator 的插件生成的类型注册表，而这个插件在 tsdown --env.DSH_BUILD_FACE host 阶段才运行（占 host 构建时间的 29%）。如果跳过 tsdown host 直接跑 tsc client，类型注册表不存在，自然报错。

正确的构建顺序

综合以上三个坑，Windows 上从源码构建的正确顺序是：

# 1. 清理（首次或构建失败后必须）
pnpm run clean

# 2. host 阶段：先生成类型，再打包
pnpm exec tsc -b tsconfig.host.json
pnpm exec tsdown --env.DSH_BUILD_FACE host

# 3. client 阶段：依赖 host 生成的 typert 注册表
pnpm exec tsc -b tsconfig.client.json
pnpm exec tsdown --env.DSH_BUILD_FACE client

# 4. 前端
pnpm run build:web

各步耗时实测：

步骤	耗时	产物
tsc host	~45s	150+ 项目的 lib/types
tsdown host	~17s	host 打包产物 + typert 注册表
tsc client	~10s	client 类型
tsdown client	~2s	client 打包产物
build:web (vite)	4.09s	336 模块 → dist/

build:web 用的是 vite 6.4.3，336 个模块转成 dist，含 KaTeX 字体、代码高亮语言包（cpp 637KB 最大）、vendor chunk 744KB。

第三步：启动 Web UI

构建完成后启动：

pnpm dsh web --no-open

--no-open 表示不自动打开浏览器。不加会默认用系统浏览器打开。启动成功会打印：

dsh web: http://127.0.0.1:3080

浏览器访问 http://127.0.0.1:3080 即可看到 Web UI。SSH 远程场景只打印 URL，因为本地转发地址由 SSH 客户端持有。

架构亮点

跑通之后回头看几个设计值得说的地方：

一切皆插件。246 个 workspace 项目里，LLM 后端有 5 个（DeepSeek、pi-ai、perplexity、exa、deepseek-search）、shell 有 bash/pwsh 各 local/sandbox 变体、沙箱有 local/windows-acl/e2b、UI 组件 40+ 个 ui-* 包，全是独立插件。想换 LLM 后端或沙箱实现，改插件配置就行，不动核心。

typert 类型注册表。这是框架的枢纽。host 构建时由 dsh-typert-generator 插件扫描所有 remote 接口，生成统一的 TypertClientRemote 类型，client 端通过这个类型拿到所有远端能力。这也是为什么构建顺序不能乱——client 的类型完整性依赖 host 先跑完 typert 生成。

Cordis 时空可组合。vendor/cordis 是框架内核，提供 Fiber（协程）、loader（插件加载）、include（依赖注入）等能力。app-boot 通过 mountRootInclude 把所有插件挂载到一棵树上，启动时整棵树一起 init。

不足与注意

如实说几个当前阶段的问题：

• 开发者预览：官方明确说会有破坏性变更，别在生产环境依赖。
• Windows 构建不顺畅：pnpm run build 一把过的概率不高，至少要手动 clean 一次，构建顺序也要自己理清。
• 文档偏少：README 只有最简启动，构建排错、插件开发、配置项说明都要翻 docs/ 目录。
• 产物体积大：前端 dist 里单个 vendor chunk 744KB、cpp 语言包 637KB，首屏加载不轻。

总结

DeepSeek Harness 的设计思路——一切皆插件 + Cordis 时空可组合——在 Agent 框架里很独特。当前阶段从源码构建体验还比较粗糙，尤其在 Windows 上，但只要理清构建顺序（clean → tsc host → tsdown host → tsc client → tsdown client → build:web），就能跑起来。启动后 http://127.0.0.1:3080 的 Web UI 可用，接下来就是配置 LLM 后端、挂插件、跑 Agent 的事了，那是另一篇文章。

如果你只是想快速体验不想折腾构建，用 npx @deepseek-ai/dsh web 拉预构建包是最快路径（前提是你本机的 npm/npx 没有那个 Class extends value undefined 的问题）。想深入看源码、改插件、跑测试，再走本文的源码构建路线。