DeepSeek Harness 双模式示例启动:从 tsx 源码回路到构建产物 lib 的 CI 严格验证

原创2026-09-18 17:00:551,420 阅读
文章标签:人工智能AI AgentAgent 框架DeepSeek

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 配置都必须能从配置文件所在目录向上解析裸模块。具体拓扑规则有三条:

  1. 共享解析根:examples/ 作为 pnpm workspace 的一个成员,提供统一的 examples/node_modules 解析根。在当前仓库中,该约定落地为 packages/examples/(成员包如 packages/examples/agent-spine-demo,其 peer/devDependencies 中声明了 @deepseek-ai/cordis、@deepseek-ai/dsh-agent 等一整套 workspace 依赖)。
  2. 配置归属映射:所有签入仓库的测试 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。
  3. 双登记:示例 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 两模式解析行为不一致,而这恰恰是本机制要消灭的验证盲区。

延伸阅读

登录后查看全文
deepseek-harness