DeepSeek Harness 开发环境与贡献指南

搭建 DeepSeek Harness 开发环境，需要准备受支持的 Node.js、Corepack、pnpm 和 Git。官方目前要求 Node.js 22.19 或更高版本，同时支持 Node.js 24；CI 会在 22.19、24 和 26 上运行。本文不逐句翻译官方文档，而是按照国内开发者常见的“安装—检查—构建—调试—提交”路径，整理成一套可操作的源码开发流程。

本文依据 DeepSeek Harness 官方中文开发文档 二次编写。项目仍处于 Developer Preview，准备提交代码前请再次核对官方原文。

开发 DeepSeek Harness 需要什么环境

建议提前准备：

• Node.js 22.19 或更高版本，日常开发可优先使用 Node.js 24；
• Corepack，用来启用项目锁定的包管理器版本；
• Git 2.26 或更高版本；
• 只有在运行 Agent 演示时，才需要配置模型服务商的 API 密钥。

先检查本机版本：

node --version
corepack --version
git --version

仓库锁定了 pnpm@11.7.0。建议让 Corepack 按项目声明启用对应版本，不要随意使用另一套全局 pnpm，以免产生无意义的 lockfile 变化，或者出现“本地能装、CI 失败”的情况。

克隆源码并安装依赖

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

pnpm install 后的 postinstall 不只是普通的依赖安装，它还会配置 Lefthook 和翻译文件使用的 Git 合并驱动。完成后应立即运行：

pnpm run typecheck

如果全新克隆的仓库在这里报错，先比较 Node.js、pnpm 与官方要求，不要急着修改生成文件或锁文件来“消除”错误。工具链版本不一致，往往才是首要原因。

理解 Host、Client 与 Web 的构建顺序

DeepSeek Harness 的根构建并非所有包同时执行，而是有明确依赖顺序：

1. 编译 Host TypeScript；
2. 打包 Host；
3. 编译 Client TypeScript；
4. 打包 Client；
5. 构建 Web 应用。

当改动跨越 Host 与 Client 的远程接口时，Client 报错不一定来自前端代码，也可能是 Host 描述或生成类型没有更新。准备修改远程方法前，建议先阅读 API Gateway 远程调用指南；判断功能应该落在哪个包，则可参考 DeepSeek Harness 架构解析。

安全配置模型 API 密钥

运行 Agent 演示时，可以通过环境变量提供密钥：

export DEEPSEEK_API_KEY="你的密钥"

如果使用自定义兼容端点，可按官方说明配置 DEEPSEEK_BASE_URL。不要把密钥写进源码、示例、准备公开的终端记录，或可能被 Git 提交的环境文件。提交前应检查 diff，确认没有本机路径、私人对话和访问凭证。

提交前运行哪些检查

项目通过 Lefthook 配置 pre-commit、pre-merge 和 pre-push 检查。推送前可以主动运行完整检查：

pnpm run check:all

开发过程中可先运行与改动范围最相关的检查，准备评审时再跑完整流程。如果 Hook 失败，应先理解失败原因，而不是默认绕过。

源码中的标记也有约定：FIXME 表示已知缺陷，TODO 表示后续计划，XXX 用来提醒读者某段行为反直觉或风险较高。保持语义一致，维护者才能通过搜索快速判断问题性质。

选择合适的开发演示

通过类型检查并配置好密钥后，应选择能覆盖改动层级的最小演示。官方文档列出了这些入口：

pnpm dsh --profile headless "summarize this workspace"
pnpm run demo:cordis
pnpm run demo:acp

建议在可丢弃的测试工作区运行 Agent。类型检查通过，只能说明静态契约基本成立，不能证明工具权限、事件顺序和流式输出在运行时完全正确。让任务保持小而明确，查看工具调用，并检查最终 diff。

DeepSeek Harness 贡献检查清单

提交 PR 前，至少确认：

• 当前 pnpm 版本与仓库声明一致，lockfile 只包含有意变更；
• pnpm run typecheck 与相关包测试通过；
• Host 改动先于 Client、Web 层完成验证；
• diff 中不存在 API 密钥、本机绝对路径或私人记录；
• 新行为放在正确的插件、能力接缝或应用层；
• 至少有一个聚焦的运行时演示覆盖本次行为。

继续阅读 Agent 生命周期详解，可以理解一次演示任务为何可能产生多个模型请求和工具阶段。

官方原文

本文依据 DeepSeek Harness 官方开发文档（中文） 独立整理，核对日期为 2026-08-20。支持版本、脚本、Git Hooks 和贡献规则以官方仓库最新内容为准。