5.1 从源码构建与开发

本章概览：从 GitHub 克隆 DSH 源码、安装依赖、构建并运行；掌握仓库的常用命令、开发工作流与源码启动方式。这是成为贡献者的第一步。

环境要求

Node.js ^22.19 || >=24（本仓库 CI 使用 Node 24）；
pnpm（workspaces 包管理）。

从源码运行

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web        # 从源码启动 Web UI

生产运行需要已构建的包与前端产物：先在仓库根单独 pnpm run build，然后用 pnpm dsh <args...> 运行 TypeScript 入口并转发所有参数；
pnpm dsh --profile headless "task" 从源码跑一次性任务（需要 DEEPSEEK_API_KEY）。

出处：README.zh.md（deepseek-harness-src/README.zh.md）与 packages/boot/app-boot/README.md 的源码执行一节

源码启动的模块解析约定

仓库 bin 安装 Loader 的可选 node-addon-require-builtin peer；pnpm dsh 源码路径把 manifest 声明的 workspace 包映射到其 TypeScript 源码；
dsh CLI 源码启动走 tsx 的 ESM-only 钩子（node --import tsx/esm）——模块必须保持 ESM（无 CJS-only 导出）；Node 原生 TS 模式在引擎范围内不可用；
它的配置门要求每个发布的 raw/Web 裸插件出现在 resolver manifest 的 dependencies 中（verify-cordis-config 强制执行）。

出处：packages/boot/app-boot/README.md 与 dsh-source-launch-tsx-esm Agent Note

常用命令

命令	用途
`pnpm install`	安装依赖（pnpm workspaces）
`pnpm run clean`	清理构建产物与已删包的残留
`pnpm run test`	vitest 单元测试
`pnpm run test:coverage`	CI 覆盖率门：`packages///src` 每文件 100%
`pnpm run test:e2e`	真实 API 测试（无 key 自行跳过）
`pnpm run test:snapshot`	免 key 的 ACP/headless 回放快照
`pnpm run typecheck` / `lint` / `duplication`	类型检查 / lint / 跨文件克隆检测
`pnpm run build`	tsc 产出 lib/types + tsdown 打包 runtime
`pnpm run hygiene`	knip + publint + workspace 约束 + NodeNext 消费检查
`pnpm run doc-sync`	全部文档门（生成目录新鲜度、链接、预算）
`pnpm run website:build`	VitePress 构建（兼作死链检查）
`pnpm run demo:cordis` / `demo:acp`	示例（需 key）

出处：AGENTS.md（deepseek-harness-src/AGENTS.md）

开发指南要点（docs/development.md）

TypeScript 项目布局：源码平面 vs 产物平面绝不混用——静态门与测试通过 tsconfig paths 解析到 src，消费构建产物的门声明该依赖；
编译器面保持显式：每个包用一个聚合面（aggregate），除 api/remotes；全仓库程序播种一个面配置，不用根 solution；
TODO 标记：FIXME/TODO/XXX 按紧迫度区分（development.md 有语义表）；
文档纪律：见 4.5 不变式、测试与文档规范。

出处：docs/development.md（deepseek-harness-src/docs/development.md）

沙箱失败时的处理

当必需的 gh、pnpm、构建、测试或生成器命令因 agent 沙箱阻挡凭据、网络、IPC、文件监视或嵌套 sandbox-exec 而失败时：以最窄的主机升级原样重试后再诊断认证或项目问题；要求有沙箱证据，绝不绕过真实测试失败或被测产品沙箱。

出处：AGENTS.md

源码布局速查

vendor/      Vendored Cordis 源码（manifest + 同步流程在 vendor/README.md）
packages/    @deepseek-ai/dsh-<pkg> workspaces：packages/<group>/<pkg>/
apps/        cli（dsh bin）、web（app 入口）
docs/        架构、生成目录、事后分析、cookbook
scripts/     仓库门与生成器
website/     VitePress 投影（官方文档网站）
examples/    可运行 cordis.yml 叶子
.agents/     Agent 工作流与 Agent Notes（notes/）
python/      Python SDK 与内置运行时
native/      node-addon-landlock-run 源码

出处：AGENTS.md（deepseek-harness-src/AGENTS.md）

小结

源码开发的关键心智：构建产物与源码分离、生成器防漂移、门齐全（doc-sync/website:build/hygiene）。下一章 5.2 设计哲学与决策记录从"为什么"的角度回看整个架构。

参考资料

README.zh.md — 运行与贡献（deepseek-harness-src/README.zh.md）
docs/development.md — 开发指南（deepseek-harness-src/docs/development.md）
AGENTS.md — 仓库约定与命令（deepseek-harness-src/AGENTS.md）
CONTRIBUTING.md — 贡献指南（deepseek-harness-src/CONTRIBUTING.md）

5.1 从源码构建与开发 ​

环境要求 ​

从源码运行 ​

源码启动的模块解析约定 ​

常用命令 ​

开发指南要点（docs/development.md） ​

沙箱失败时的处理 ​

源码布局速查 ​

小结 ​

参考资料 ​