DeepSeek Harness in Depth

外观

DeepSeek Harness 把运行时不变量当作一等、半声明式的工程纪律：每个 workspace 包都可以注册小型的“契约检查”，这些检查在活跃的 agent 运行时内部运行，一旦某条跨记录关系被破坏，便会抛出按包归因的 InvariantError。本页剖析注册表服务（@deepseek-ai/dsh-invariants）、各包的 ./invariant 伴生包如何注册检查、实际受保护的关系套件，以及单元测试如何借用同一理念。

不变量理念 ​

核心理念（记录在 docs/defensive-patterns.md 与 dsh-invariants README 中）是：产品包应当在开发期响亮地失败，当某条事件流或可变数据的契约破裂时就抛错，而不是静默劣化。两个决定让它廉价且低侵入：

  • 注册是穷尽的；断言刻意不造假。 每个 workspace 包都发布一个 ./invariant 伴生包，登记其确切 npm 包名。但只有在其拥有可观察的事件关系或相关可变数据时，伴生包才安装真实检查。确认某个所需方法、插件名、注入或固定的纯函数结果，属于类型/加载/单元测试范畴，不算运行时不变量。
  • 服务本身不含任何产品检查。 @deepseek-ai/dsh-invariants 是纯注册表；单独加载它不安装任何东西。产品检查位于各所有者的伴生包里。

服务 ​

packages/runtime-diagnostics/invariants/src/index.ts 导出 InvariantRegistry，作为 Cordis 服务 ctx.invariants 安装。其配置：

ts
export interface Config {
  readonly enabled?: boolean
  readonly package_allowlist?: string[]
  readonly package_blocklist?: string[]
}

默认是 enabled: true、空 allowlist、空 blocklist。选择逻辑为：启用且（allowlist 为空或某模式匹配完整 npm 名）且（无 blocklist 模式匹配）。blocklist 覆盖 allowlist。模式默认未锚定（new RegExp(source)），除非调用方提供 ^/$。

两个核心 API：

ts
class InvariantRegistry extends Service {
  register(packageName: string, installer: InvariantInstaller): () => void
}

export type InvariantFailure = (message: string) => never
  • register(packageName, installer) 首先预留该包名（重复时报 Error），然后在被过滤器选中时于一个专属的 Cordis 子 fiber 中运行安装器。它返回一个 disposer；dispose 释放预留、移除监听器并 dispose 该子 fiber——因此伴生包可以重载并重新登记同名，而不残留任何状态。
  • installer 收到一个子 ctx 与一个 fail(message) 报告器，后者抛出绑定到登记包的 InvariantError。InvariantError 带稳定的 code: 'INVARIANT' 与 packageName：
ts
export class InvariantError extends Error {
  readonly code = 'INVARIANT' as const
  readonly packageName: string
  constructor(packageName: string, message: string) {
    super(`invariant violated by "${packageName}": ${message}`)
    this.name = 'InvariantError'
    this.packageName = packageName
  }
}

强制执行：抛错而非记录 ​

违规通过抛错浮现。fail(message) 的类型是 never 返回，所以不变量被破坏会中止违规操作，抛出按包归因的错误，而不是被吞进日志。这正是让它成为真正“开发期断言”门禁的原因——回归会响亮地触发 InvariantError，而挂载这些伴生包的运行时测试会捕获到它。

verify-package-invariants 过滤 ​

根目录有一个卫生门禁 scripts/verify-package-invariants.ts，静态发现每个 workspace 包并拒绝：生成的标记、无解释的空安装器、非空安装器却省略或忽略报告器、错误的登记名，以及不完整的导出/依赖/TypeScript 接线。这是最低所有权检查；每个可执行伴生包的语义由针对性的 .spec.ts 套件证明。

检查什么 ​

README 的伴生包表格归纳了受保护的关系（以下穷尽，直接来自源码）：

伴生包受保护的关系
dsh-session、dsh-agent、dsh-scope、dsh-agent-loop会话包裹与调用/结果轨迹、agent 状态迁移、收件箱 FIFO 守恒、受限主体、模型请求重构
dsh-llm、dsh-llm-retry、dsh-tools、dsh-system-prompt流语法、持久重试位置/上界、工具流水线阶段与冻结结果、提示词汇编数据
dsh-compaction、dsh-hook-protocol、dsh-sandbox-policy持久压缩与 hook 配对、压缩元数据、沙箱模式词汇表
dsh-fs、dsh-subagent、dsh-workflow文件系统事件身份、提供者/子代理配对、workflow/agent 生命周期身份
dsh-goal、dsh-goal-round-driver持久目标来源/内容一致、修订与生命周期迁移、时间戳、顺序受理轮次
dsh-permission-presets、dsh-user-approval活动预设引用、审批 ask/decided 审计配对
dsh-jobs、dsh-tool-todo任务快照生命周期/所有权、持久整表 todo 结构
dsh-time-context持久时钟读数与开放轮/下一预步骤位置一致；渲染时间可解析且不晚于其事件

一个真实检查：LLM 流语法 ​

packages/llm/llm/src/invariant.ts 包裹每个 provider 流，强制终止 finish契约——正是 docs/defensive-patterns.md 中记载的“双向遵守公共契约”：

ts
// packages/llm/llm/src/invariant.ts（节选）
const install: InvariantInstaller = (ctx, fail) => {
  ctx.on('llm/stream', (_options, next) => validateStream(next(), fail), { global: true, prepend: true })
  ctx.on('llm/adapters-updated', () => {
    const llm = ctx.get('llm')
    if (llm === undefined) return
    for (const provider of llm.listProviders()) {
      try {
        llm.providerRetryPolicy(provider.id)
      } catch {
        // 走到这里正是违规：通知承诺了可读注册表。
        fail(`llm/adapters-updated fired while provider "${provider.id}" has no readable registration`)
      }
    }
  }, { global: true })
}

在普通未加标记的流上，校验器最终：

ts
if (!finished) fail('LLM stream ended without a terminal finish chunk')

空安装器是有意为之 ​

许多伴生包使用带 No runtime invariant: 注释的空安装器。例如 test-support 包 @deepseek-ai/dsh-agent-loop-testkit/invariant.ts：

ts
/** No runtime invariant: this test-support package owns no production event stream or mutable data;
 *  consuming test suites exercise its behavior. */
const install: InvariantInstaller = () => {}
export const apply = (ctx: Context): Promise<() => void> =>
  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

测试如何依赖不变量 ​

主要的 Vitest 配置（单元、e2e、快照）设置 setupFiles: ['./scripts/test-invariants.ts']；三个 web/浏览器配置不设。标准 agent 组合挂载 enabled: true 的服务外加四个核心有状态伴生包（dsh-session、dsh-agent、dsh-scope、dsh-agent-loop）；针对性套件证明有效与无效观测，另一个穷尽拓扑挂载所有伴生包，以证明登记/dispose 接线。因为违规会抛错，测试可用 expect(() => …).toThrow(InvariantError) 钉住一处回归——不变量本身就是跨记录一致性的 oracle，单元测试无需再手工推导。

一个防御性工具：packages/util/timeout ​

不变量思维延伸到防御性原语。@deepseek-ai/dsh-timeout 是一个零依赖的超时/截止时间助手——clampTimeout、deadline、timeoutOf，以及携带能力所属代码与已到期限的 TimeoutReason。它只通过 AbortSignal 通知（每个能力自行拥有停止其工作的机制），clampTimeout 严格校验调用方提示：非有限或非正数会抛错，有效值为 min(requested ?? def, max)，上限 MAX_TIMER_DELAY_MS（2_147_483_647）。它与不变量服务一样，沿用“先校验再快速失败、通过类型化代码分类”的模式。

延伸阅读 ​

  • 测试策略— 针对性套件如何证明每个伴生包的语义。
  • CI 与发布— verify-package-invariants 卫生门禁与 verify-built-package-invariants。
  • 官方 docs/defensive-patterns.md— 部分不变量编码的 bug 类规则。
  • packages/runtime-diagnostics/invariants/README.md— 穷尽的伴生包表格与配置语义。
  • packages/runtime-diagnostics/invariants/src/index.ts— 注册表实现。
  • packages/llm/llm/src/invariant.ts— 一个具体的非空不变量伴生包。

DeepSeek Harness in Depth