企业官网建设流程全解析

DeepSeek Harness 包级运行时不变量的意义化契约：从“空断言”回归可观测关系

【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness

运行时不变量（runtime invariant）的价值在于它能捕捉“不可能发生的运行状态”——而不是复述类型系统与单元测试已经验证过的事实。DeepSeek Harness 的dsh-invariants服务要求每个工作区包都发布一个./invariant伴生插件，但早期自动生成的基线里塞满了关于插件名、注入服务、方法存在性的“空断言”。本文基于仓库内 invariant runtime contracts 架构记录，详解该项目的“意义化契约”决策：哪些关系才算运行时不变量、21 个可执行伴生分别保护什么、82 个空伴生为何是显式架构结论，以及verify-package-invariants机械门禁如何保证注册穷尽而断言绝不敷衍。读完你将掌握在 DeepSeek Harness 组合式架构中设计、评审与门禁包级运行时诊断的完整方法论，并能在自己的自定义组合里挂载这些检查。

背景：包属主不变量服务的演进困局

DeepSeek Harness 采用“Everything is a Plugin”的组合式架构，其不变量体系的核心是**包属主（package-owned）**原则：每个包自己声明自己拥有的运行时关系，中心服务只做注册与调度。这条原则在一份前置架构记录 package-owned invariant service 设计 中确立。

问题出在“注册穷尽”与“断言有意义”之间的张力：

• 包属主不变量服务让发布与注册变得穷尽，但第一版自动生成的基线接受了空 installer；
• 后续一轮补丁把那些空占位替换成“通用断言”——插件名字正确、注入服务存在、effect 生效、service 方法存在、固定纯库示例返回值正确。

这些断言让每一个伴生插件都“可执行”了，却没有让系统更安全：TypeScript 类型检查、Cordis 启动、包测试和模块加载测试早已强制了这些形状。不变量服务的职责是检测不可能的运行时状态，而不是复述声明形状。

什么才是真正有用的运行时不变量

一份有用的运行时不变量，关联的是随时间推进或跨可变数据结构的观测。文档给出了三类典型例子：

• 一个终端事件缺少与之配对的启动事件；
• 一个 LLM delta 指向一个并未打开的流块；
• 一个持久化结果的身份与产生它的请求不一致。

反之，以下情况不是这样的关系，属于被淘汰的“合成断言”：

• 声明的方法确实存在；
• 插件有预期的名字；
• 常量示例仍然返回已知值。

没有可观测关系的包怎么办

文档明确承认：部分包确实不拥有任何持续可观测的关系。纯工具函数、纯组合包、薄适配器、二进制和测试支持包，可能有重要的契约，但这些契约更适合由以下机制来强制，而不是捏造一个运行时断言：

• 类型（TypeScript 类型系统）；
• 加载检查（Cordis 可加载性、模块加载）；
• 聚焦的单元测试；
• 集成测试。

如果强行给这些包要求合成断言，就是在“满足门禁”而不是“检测损坏”上做优化。

决策：注册穷尽，断言必须有意义

每个包都有./invariant伴生，二选一

每一个工作区包都发布一个单独构建的./invariant伴生，并以精确的 npm 包名注册。一个伴生只做两件事之一：

1. 安装一个包属主的检查：监听事件流或相关的可变数据结构，并通过其绑定的fail(message)报告器上报违规；或
2. 使用空 installer：其声明以一个属主特定的No runtime invariant:注释开头，解释为什么该包没有可观察的运行时关系。

空表单是显式的架构结论，不是生成占位符

这是本决策最微妙的一点：空伴生不是“没写完”，而是经过论证的架构结论。未来如果某个包引入了可变状态或事件协议，必须把这条解释替换为对应的检查——否则机械门禁会直接拒绝。

中心服务只做调度，不做断言

dsh-invariants服务只拥有以下职责：

• 配置（全局开关与包名过滤）；
• 注册唯一性（名字预留）；
• 子 fiber 生命周期；
• 回滚与释放；
• 包属主归因的失败报告。

它不暴露任何通用的插件形状、服务形状或启动断言辅助函数，也不导入任何产品包。产品词汇、依赖、测试与变更所有权都归属产出数据的那个包。

21 个可执行伴生的运行时关系清单

记录该决策时，仓库是 103 包工作区，其中21 个可执行伴生与82 个有理由的空伴生。下表完整列出每个可执行伴生所保护的运行时关系（原文表格）：

两类伴生的行为方式不同：

• 会话背书的伴生（session-backed）在加载时校验已有的持久化事件，凡是依赖事件顺序的关系，都使用每个候选事件之前的那个前缀；
• 其他检查观察权威的实时事件边界或可变服务结果。

校验发生在发布（写入持久化）之前——如果接受了一个非法事件，就等于把坏状态提交了。

仓库当前状态的扩展

从仓库当前状态看，README 中 dsh-invariants 包说明 的可执行伴生清单已经比这份记录时的 21 个更进一步，覆盖了dsh-credentials、dsh-settings、dsh-storage-domain、dsh-workspace、dsh-agent-presets、dsh-session-title、dsh-plan-mode、dsh-schedule、dsh-webserver、dsh-tool-workflow、dsh-commands以及浏览器/Node 半区的dsh-client-hmr、dsh-client-modules、dsh-client-runtime等伴生——可以推断，后续包在引入可变状态或事件协议时，把各自的No runtime invariant:解释替换成了真实检查。这也印证了文档的核心主张：伴生清单是随包演化动态扩展的，中心服务始终不感知具体断言。

仓库门禁与测试体系

verify-package-invariants机械门禁

scripts/verify-package-invariants.ts 是门禁入口，它遍历每个工作区包并强制以下条件：

• 伴生源码存在：每个包都必须有./invariant伴生；
• 精确名称注册：注册名必须是该包的精确 npm 包名；
• named-only Loader 形状：伴生必须以命名导出的形式暴露 Cordis Loader 形状；
• ./invariant导出、发布文件、依赖、TypeScript references、bundle 条目完整接线。

其 AST 规则会拒绝：

• 生成的标记（generated markers）；
• 默认导出；
• 无解释的空 installer。

同时强制正向条件：

• 非空 installer 必须接受并使用fail报告器；
• 注册必须传递那个被检查过的本地install函数。

关键设计是：门禁刻意不从方法名或 helper 调用推断语义质量——它保证“接线正确、断言不敷衍”，但拒绝替包主人判断什么算有意义的关系。

Vitest 拓扑挂载

测试体系分三层：

1. 全量挂载：Vitest 为每个包测试拓扑都挂载InvariantRegistry且{ enabled: true }，并加载属主伴生；
2. 路径映射：invariant 子路径的路径映射解析源码伴生而非过期的构建输出，避免测到旧产物；
3. 聚焦套件：每个可执行伴生都有覆盖有效与无效观测的聚焦测试；穷举拓扑让每个源码伴生经过真实的 Loader 命名空间归一化。

artifact gate（发布前产物门禁）

结构门禁验证完每个发布映射后，还有一个产物门禁：

1. 暂存其 manifest 声明的lib/文件；
2. 在纯 Node 下导入编译后的./invariant自引用；
3. 重复一次 Loader 形状检查。

这样，一个导入未声明运行时 chunk 的伴生在发布前就会失败。此外，测试中凡是合成事件流的，必须产生一个有效的周边生命周期，除非该测试本就故意断言违规。

源码级解读：从空占位到真实检查

中心服务：InvariantRegistry的实现

packages/runtime-diagnostics/invariants/src/index.ts 是服务的完整实现，几个值得注意的点：

配置与校验：Config只有三个字段，compilePatterns会逐条校验过滤规则——空白、带前后空格、重复或非法正则都会在服务启动时抛错而不是跳过（src/index.ts）。

注册即预留：register(packageName, installer)把完整 npm 名加入registrations集合，即使过滤器让 installer 保持不激活，名字也被预留——两个插件永远无法静默声明同一个包名；空白或含空格的名称直接抛错（src/index.ts）。

子 fiber 与原子回滚：被选中的 installer 在专属子 fiber 中运行，installer.inject声明该 fiber 可访问的服务；同步或异步完成都会被 join 后再视为注册成功。installer 失败会释放子 fiber 并原子地释放名字预留（src/index.ts）。返回的 disposer 同时属于伴生 fiber，两侧任一卸载都会移除监听器、追踪状态与预留，因此伴生可以热重载并再次注册同名而不残留状态。

归因失败：fail(message)抛出InvariantError——extends Error、稳定code: 'INVARIANT'、携带属主packageName，消息前缀为invariant violated by "<package>": …。这意味着违规可归因到具体包，而注册表无需导入任何产品代码（src/index.ts）。

空伴生的范本

dsh-invariants自身的伴生就是一个“有理由的空 installer”：注释写明“注册所有权与子生命周期是服务自己的变更边界，从同一注册表观察它只会重复其实现”，install为空函数（packages/runtime-diagnostics/invariants/src/invariant.ts）。

另一个范本是 packages/acp/acp/src/invariant.ts：ACP 传输不拥有持久化的包本地事件流，其映射由协议与生命周期测试覆盖——所以它同样以No runtime invariant:开头，注册一个空 installer。两个文件都遵循相同的伴生结构：name、inject: ['invariants']、install与apply，后者通过ctx.invariants.register(PACKAGE_NAME, install)完成注册。

可执行伴生的范本：dsh-session

packages/core/session/src/invariant.ts 展示了“有意义断言”的形态：它维护每个会话的SessionTrace（lastSeq、openTurn、openStep、nextTurn、nextStep、pendingCalls），逐事件校验而不直接修改已提交的追踪：

• requireOpenStep断言 step 作用域事件命名的是当前打开的 turn/step（src/invariant.ts）；
• validateEvent对每个候选事件先校验再返回一个延迟变更（SessionTraceTransition），先校验seq严格递增，再按turn/start、turn/end、step/start等类型维护打开状态机（src/invariant.ts）。

这正是文档所定义的“关系型”检查：它观测的是事件流随时间推进的嵌套与配对关系，而不是某个方法是否存在。违规消息（如seq must strictly increase: saw X after Y）直接指出不一致的观测，而非复述 API 形状。

备选方案与权衡

该架构记录完整记录了被否决的方案，这些权衡对理解设计边界至关重要：

• 保留生成的空伴生：否决。一个无解释的占位符可能在包获得真实运行时关系后仍然存活。
• 要求每个包都必须有断言：否决。方法存在性、插件形状与固定示例断言只是在重复更强的类型、加载与单元测试契约，却不检查运行时一致性。
• 在服务里保留通用形状辅助函数：否决。会把编译期 API 校验与运行时不变量混为一谈，并鼓励在中心集中定义产品假设。
• 把产品检查搬进服务：否决。产品词汇、依赖、测试与变更所有权应当属于产出数据的那个包。
• 从根入口隐式注册伴生：否决。组合顺序与可选服务存在性会造成隐藏副作用。

影响与后续

该决策的落地效果可以归纳为六点：

1. 每个包都有可见的归属与发布接线，但只有拥有真实运行时关系的包才添加监听器或追踪状态；
2. 空伴生仍是可评审的决策，带有包专属解释；移除解释即触发门禁失败；
3. 类型声明、Cordis 可加载性、插件元数据、服务方法 API 与纯代数继续由各自的编译、加载、单元或集成门禁覆盖；
4. 运行时失败定位到属主 npm 包，指向不一致的观测，而不是复述要求的 API 形状；
5. 原始的选择逻辑、块名单优先级、重复归属、回滚、释放与 HMR 服务契约保持不变。

如何在自己的组合中验证与使用

运行机械门禁

在仓库根目录执行：

pnpm run verify-package-invariants

该命令输出所有违规（格式化为可读列表）并以非零退出码失败；全部合规时打印N hand-owned package companion(s) conform.（scripts/verify-package-invariants.ts）。

挂载注册表与伴生

标准 agent 组合（见 agent-spine-demo）已挂载注册表并带四个核心有状态伴生：dsh-session、dsh-agent、dsh-scope、dsh-agent-loop。自定义组合可仿照包 README 的做法：

import type { Context } from '@deepseek-ai/cordis' import InvariantRegistry from '@deepseek-ai/dsh-invariants' import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant' declare const ctx: Context ctx.plugin(InvariantRegistry, { enabled: true }) ctx.plugin(SessionInvariant)

注意：单独加载注册表不会安装任何检查——它不内置任何产品检查。

配置选择

选择规则：服务启用、白名单为空或至少一个模式匹配完整 npm 名、且无块名单模式匹配时，该包被选中——块名单匹配覆盖白名单匹配。模式用new RegExp(source)编译：默认非锚定，除非源提供^与$；不支持/pattern/flags语法。空白、带空格、重复或非法条目在启动时抛错。三个过滤器在服务生命周期内固定（完整配置目录见 docs/config-catalog.md#deepseek-aidsh-invariants），变更需要 Cordis 插件重载。

- name: '@deepseek-ai/dsh-invariants' config: enabled: true package_allowlist: - '^@deepseek-ai/dsh-'

检查失败时会发生什么

违规从报告它的上下文抛出InvariantError：稳定code: 'INVARIANT'、属主包的完整 npmpackageName、消息前缀invariant violated by "<package>": …。由于失败可归因到具体包且注册表不导入任何产品代码，排查时能直接定位到产出那条数据的包。若 installer 自身失败，其伴生会被释放、注册回滚——坏掉的检查不会留下半截监听器。

延伸阅读

• Runtime invariants 子系统文档：Config、installer、service 与伴生契约的生成式参考；
• dsh-invariants 包 README：设计哲学、完整伴生清单与已知局限；
• package-owned invariant service 架构记录：为什么检查放在属主旁边、注册表拥有选择与生命周期；
• invariant 服务的测试套件：选择、预留与生命周期行为的可执行证明。

【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness