DeepSeek Harness 双模式示例启动:从 tsx 源码回路到构建产物 lib 的 CI 严格验证
DeepSeek Harness 双模式示例启动:从 tsx 源码回路到构建产物 lib 的 CI 严格验证
本篇技术指南以仓库归档决策笔记 .agents/notes/archived/process/2026-07-17-run-ci-examples-from-built-lib.md(状态:implemented)为核心骨架,讲解 DeepSeek Harness 中示例与 Cordis 测试项目在 CI 与本地开发中的双模式启动机制。读者将掌握 src(tsx 源码回路)与 lib(构建产物 strict 模式)两种启动方式的工作原理、DSH_EXAMPLE_MODE 环境变量的选择策略、共享 Loader 测试 harness 的落地实现,以及如何在仓库中配置、运行并验证这类示例冒烟测试。
背景问题:为什么 CI 必须与本地使用不同的启动方式
在双模式机制引入之前,CI 通过 node --import tsx 配合根 tsconfig 的 paths 映射来启动示例以及加载 Cordis 配置的测试项目。该做法存在两个结构性问题:
- TypeScript 转换开销:每次子进程启动都要经过 tsx 的运行时转换;
- 包解析行为失真:由于
paths映射的存在,import语句解析到的是 workspace 中的源码,而不是经包exports字段进入构建后的lib/目录。
后者的影响最为致命:测试运行的代码与解析路径,和真实安装消费方实际经历的完全不同。其后果正如笔记所总结的——一个包即使构建导出图不完整或解析结果不同,CI 仍可能通过("A package can pass CI while its built export graph is incomplete or resolves differently")。这正是该决策笔记要消除的验证盲区。
核心决策:src / lib 双模式执行机制
笔记确立的执行机制包含两种模式,彼此互补:
| 模式 | 用途 | 启动方式 | 包解析方式 | 典型场景 |
|---|---|---|---|---|
src |
本地开发默认模式 | node --import tsx <srcBin>,并设置 TSX_TSCONFIG_PATH |
通过 tsconfig paths 映射解析到 workspace 源码 |
免构建的本地开发回路 |
lib |
严格 CI 模式 | plain Node 直接启动构建后的 bin(node <libBin>) |
不加载 tsx、不使用 paths 映射,裸包经真实 exports 进入 lib/ |
CI 验证构建产物 |
模式的适用边界非常明确:
- CI 中启动示例、或启动签入仓库的
cordis.yml的子进程,一律使用lib模式; - 仅实现 ACP 或 MCP 对端、且不加载 Cordis 的 TypeScript fixture,直接由 Node 运行(依赖 Node 内置的类型剥离能力);
- 只有显式验证源码路径的回归测试可以保留
src模式。
这一设计的核心动机是:测试必须覆盖已安装消费方实际运行的代码与解析路径,而不是让 CI 反复通过一套与消费体验脱节的模拟环境。
源码落地:dsh-loader-smoke 的 mode-aware 启动解析器
双模式机制的共享实现位于 packages/test-support/loader-smoke/src/index.ts,该包在 README 中定位为"support-tier test infrastructure, not a product API"。
模式解析:resolveExampleMode
环境变量名与解析规则在源码中有严格定义:
EXAMPLE_MODE_ENV = 'DSH_EXAMPLE_MODE'(src/index.ts);resolveExampleMode()读取该变量:undefined/ 空串 /'src'返回src;'lib'返回lib;其余任何值直接抛错——"a typo in a gate's env fails loud",避免拼写错误被静默吞掉。
也就是说:CI 设置 DSH_EXAMPLE_MODE=lib,本地开发不设置该变量即自动退回 src 的快速源码回路。
启动解析:resolveExampleLaunch
核心函数 resolveExampleLaunch 根据模式生成完整的 spawn 参数(command / args / env),其两种分支的行为如下:
src 模式:
node --import <tsx> <srcBin> <configArgs>
# env 中额外设置 TSX_TSCONFIG_PATH=<tsconfigPath>
其中 tsx loader 通过 import.meta.resolve('tsx')(或 'tsx/esm')解析,TSX_TSCONFIG_PATH 指向仓库根 tsconfig,使 workspace 内未构建的裸包 import 经 paths 映射解析到源码。此模式要求调用方必须传入 tsconfigPath,否则直接抛错。
lib 模式:
node <libBin> <configArgs>
# 不附加任何 tsx 相关 env
裸包插件通过真实 exports 解析到构建后的 lib/;相对路径的 example-local TypeScript 插件则以源码形式由 Node 内置类型剥离加载。libBin 可由 srcBin 自动推导:toLibBin 将 <pkg>/src/<name>.ts 中的 /src/ 段替换为 /lib/ 并把 .ts 换成 .js(src/index.ts);测试 fixture 也可通过 libBin 显式指定 plain-Node 入口。
解析拓扑:让每个测试 Cordis 配置都能解析裸模块
笔记规定了一条全局约束:每个测试 Cordis 配置都必须能从配置文件所在目录向上解析裸模块。具体拓扑规则有三条:
- 共享解析根:
examples/作为 pnpm workspace 的一个成员,提供统一的examples/node_modules解析根。在当前仓库中,该约定落地为 packages/examples/(成员包如 packages/examples/agent-spine-demo,其 peer/devDependencies 中声明了@deepseek-ai/cordis、@deepseek-ai/dsh-agent等一整套 workspace 依赖)。 - 配置归属映射:所有签入仓库的测试 Cordis 配置(含快照配置与包内 fixture)都放在对应的
examples/<agent>/目录树下;归属packages/<group>/<package>/的配置映射为examples/<agent>/tests/fixtures/<group>/<package>/cordis.yml,而测试驱动与断言仍留在包内。当前仓库中可以观察到大量该约定的实例,例如 apps/cli/tests/fixtures/github-webhook/cordis.yml、packages/subagent/subagent-acp/tests/fixtures/loader/cordis.yml、packages/session/session-telemetry-otel/tests/fixtures/cordis.yml。 - 双登记:示例 Cordis 配置中引用的每个包,都同时登记在
examples/package.json(支持lib模式下的裸包解析)与根tsconfig.json的 references(支持src模式的 paths 映射)中。当前 loader-smoke README 也重申了这一约束:"the owning package manifest must also declare every package named by the config"。
这套拓扑的设计意图很朴素:与其为每个测试单独构造一份消费方脚手架(重复且容易漂移),不如让每个 Cordis 配置共享同一条真实且显式声明的解析路径。
启动策略:DSH_EXAMPLE_MODE 如何串联测试与 CI
共享 Loader harness:runLoaderSmoke
模式选择由共享的 Loader 测试 harness 统一完成。runLoaderSmoke(src/index.ts)负责完整的子进程生命周期:创建隔离临时 cwd、注入隔离的 DSH_HOME 与 DSH_AGENTS_HOME、立即关闭 stdin、等待干净退出、在任何结局下清理临时目录。其核心参数如下:
| 参数 | 含义 |
|---|---|
label |
失败诊断中的人类可读示例名 |
tempDirPrefix |
隔离临时 cwd 前缀 |
binScript |
app bin 的 TS 源码入口(<pkg>/src/bin.ts),lib bin 由它推导 |
libBinScript |
lib 模式显式 plain-Node 入口(用于包外 fixture) |
configPath |
真实 Loader 配置路径,默认作为唯一 bin 参数 |
binArgs |
完整 argv(覆盖默认的 [configPath]) |
tsconfigPath |
仓库 tsconfig 路径,src 模式必需 |
mode |
显式指定 src / lib,默认取环境变量 |
env |
叠加在隔离 home 之上的环境覆盖 |
processTimeoutMs |
进程截止时间(默认 30s) |
prepare / inspect |
启动前世界状态准备 / 清理前断言钩子 |
expectedExitCode |
期望退出码;用于固定"设计中的失败面",任何其他结局(包括成功)都判失败 |
harness 的失败诊断非常完备:超时(timedOut)、退出码不符、spawn 错误都会同时携带完整 stdout/stderr 抛错,且通过 SIGKILL 保障截止时间的强制执行。
CI 门禁中的接线
模式选择在 CI 门禁层面由 scripts/run-gates.ts 统一接线,所有需要构建产物的门禁都显式设置 DSH_EXAMPLE_MODE: 'lib' 并依赖 build 门禁:
snapshotGate():pnpm run test:snapshot,env: { DSH_EXAMPLE_MODE: 'lib' },needs: <a href="https://link.gitcode.com/i/deb4414cb199eabb84001565cc015d47" target="_blank">'build']([run-gates.ts);expectedOutputGate():pnpm run test:expected,同样设置DSH_EXAMPLE_MODE: 'lib'(run-gates.ts);builtBinSmokeGate():针对 built-bin 冒烟测试的 e2e 集合设置DSH_EXAMPLE_MODE: 'lib'(run-gates.ts);- 在
ci-consumers聚合中,build→built-package-invariants→ snapshot / expected-output 的依赖顺序,确保了"先构建、后以 lib 模式验证"的严格链路。
此外,vitest.snapshot.config.ts 中 DSH_EXAMPLE_MODE === 'lib' 还会额外纳入 Web 端快照测试(apps/web/tests/**/*.snapshot.ts),而 scripts/ci-workflow.spec.ts 也对这一环境变量组合做了工作流级断言。
手动运行与本地回路
- 本地快速验证:不设置
DSH_EXAMPLE_MODE,直接pnpm run test:snapshot,即走src的免构建源码回路; - 手动验证构建产物:先
pnpm run build(package.json 中build脚本为tsx scripts/build.ts),再DSH_EXAMPLE_MODE=lib pnpm run test:snapshot; - 注意:手动执行
lib模式时可能读取到陈旧的本地构建产物,因此必须在每次代码变更后重新构建。
测试验证:harness 自身的契约用例
packages/test-support/loader-smoke/tests/loader-smoke.spec.ts 通过真实 spawn 路径逐条验证了 harness 契约:
- 隔离性:
src模式下子进程 stdout 中回显的DSH_HOME/DSH_AGENTS_HOME必须位于临时 cwd 之下,且运行结束后临时目录被彻底清理; - 任意 argv 透传:
binArgs: ['--config', configPath, '--output-format', 'json', ...]原样到达子进程,prepare/inspect钩子可写入并断言世界状态; - 非零退出诊断:退出码 7 且未声明
expectedExitCode时,错误信息携带完整双流输出; - 预期失败面:声明
expectedExitCode: 7后,进程以 7 退出则通过;反而以 0 退出仍判失败("exited 0 (expected 7)"); - 截止时间强制:挂起 fixture 在
processTimeoutMs: 100下被SIGKILL,错误信息为 "did not exit within 0.1s."。
在真实消费方侧,packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts 展示了 resolveExampleLaunch 的典型用法:以 apps/cli/src/bin.ts 为 srcBin,sourceImport: 'tsx/esm',configArgs: <a href="https://link.gitcode.com/i/4818e8826596fad6fd26e4cee91ba11d" target="_blank">'--profile', 'acp', '--patch', exampleConfig],tsconfigPath 指向根 [tsconfig.json。该 e2e 用真实子进程驱动 ACP 对端完成一次模型回合,并独立断言文件系统副作用(proof.txt 内容包含约定标记),与模型响应文本互相印证——这正是"lib 模式验证真实解析路径"设计目标在跨进程边界上的体现。
曾考虑的替代方案
笔记明确记录了三个被评估后否决的方案:
| 方案 | 否决理由 |
|---|---|
| CI 继续使用 tsx | 保留转换开销与仅适用于源码的解析行为,问题依旧存在 |
| 所有环境一律使用 lib | 本地开发每次运行前都必须构建,把成本带入了开发回路 |
每个测试单独构造私有 node_modules |
重复消费方脚手架,且易与实际安装行为漂移;以 examples/ 作为 workspace 根提供单一真实解析路径更优 |
双模式方案正是对这三者的取长补短:CI 的严格性不牺牲本地开发的速度。
工程后果与维护约束
决策落地后带来如下明确的后果(也是后续维护者必须遵守的约束):
- 收益:CI 验证构建后的包导出,不再受 tsx 改变模块解析的影响;本地开发保留免构建的源码回路。二者各得其所。
- 代价一:构建前置。CI 必须在这些测试之前先构建;手动
lib运行可能观察陈旧的本地产物。 - 代价二:依赖同步。常规 TypeScript import 分析无法识别 Cordis 配置的依赖,因此
examples/package.json(当前为各成员包的 workspace 依赖声明)、根 tsconfig references 与配置文件三者必须保持同步——任何一方遗漏都会造成src/lib两模式解析行为不一致,而这恰恰是本机制要消灭的验证盲区。
延伸阅读
- 决策笔记中文版:.agents/notes/archived/process/2026-07-17-run-ci-examples-from-built-lib.zh.md
- 共享 harness 实现:packages/test-support/loader-smoke/src/index.ts 与 使用文档
- CI 门禁接线:scripts/run-gates.ts(
snapshotGate/expectedOutputGate/builtBinSmokeGate) - 快照测试配置:vitest.snapshot.config.ts、vitest.expected.config.ts
- 跨进程消费示例:packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
- 测试策略总览:docs/testing.md