Ch19 发布、验证与边界守卫

Alembic 的发布验证不是一个统一的 npm publish 按钮。五个产品仓库有不同发布形态：Core 是 registry package，Agent 是 registry package，主 Alembic 是 CLI/runtime package，Plugin 是 Codex artifact/channel/portable runtime，Dashboard 是前端构建产物并由主 runtime 服务。每个仓库都必须用自己的边界守卫验证。

本章把这些验证路径收束成维护规则。读者不需要记住所有脚本细节，但必须知道每个脚本在保护什么。

本章回答

• 各仓库的发布形态有什么差别。
• Core public API guard、consumer import guard、release package guard 分别保护什么。
• Plugin 为什么 root registry publish disabled。
• 什么时候需要验证 runtime artifact、plugin cache、Dashboard build。

Core 先稳住 public API

AlembicCore 的 release guard 包括：

npm run check
npm run build
npm run smoke:public-api
npm run release:check

这些命令保护的是 @alembic/core 的包入口、类型输出、测试、lint、public API boundary 和 release readiness。Core 是其他仓库的底座，发布前必须确认 dist exports、package contents、source commit evidence 和 sibling-free dependency。

Core 的失败通常不是“某个 UI 坏了”，而是共享 contract 不稳定。外层仓库一旦依赖了未公开的 deep import，就可能在 Core 发布时断裂。

主 Alembic 验证 resident runtime

主 Alembic 的 scripts 包含 build、build:core、build:dashboard、check、lint:agent-extraction-boundary、lint:core-import-boundary、lint:repo-boundary、smoke:multi-project-control、release:package-guard、release:check 等。

这些验证覆盖：

• TypeScript 构建和 Core source build。
• CLI/runtime package 边界。
• Dashboard 构建接入。
• Core import 边界。
• Agent extraction 边界。
• 多项目 runtime control smoke。
• release staging 和 package guard。

如果改了 CLI、daemon、HTTP route、ProjectRuntimeControl、JobStore 或 Dashboard server，不能只跑书稿构建或前端构建。应该至少跑主仓库相关 typecheck/lint/test/smoke。

Agent 验证执行 runtime

AlembicAgent 的 scripts 包含 build:check、lint、lint:agent-import-boundary、lint:public-api-boundary、lint:core-import-boundary、test、smoke:public-imports、release:stage、release:package-guard。

Agent 的发布预览会把 @alembic/core: file:../AlembicCore 转成 Core registry version，并记录 Core source commit。如果 Core working tree dirty，staging 会拒绝，因为无法精确记录来源。

Agent 验证重点是：

• runtime/type exports 是否稳定。
• tool registry 和 provider 边界是否可构建。
• Core import 是否通过 public entrypoint。
• release package 是否不含本地 workspace dependency。

Plugin 验证 Codex artifact

AlembicPlugin 是 private root package。verify-release-package-boundary.mjs 明确要求 root package private，root registry publish disabled，release workflow 不调用 root npm publish，Codex plugin 通过 artifact/channel 路径发布，runtime.tgz 作为 portable runtime artifact。

Plugin 的关键验证包括：

• npm run build。
• npm run check。
• verify:release-package-boundary。
• verify:codex-channel。
• verify:codex-plugin。
• verify:codex-session。
• MCP clean output probes。
• dev:codex-plugin:reload 后 probe installed cache。

如果改了 Codex tool schema、tool visibility、clean output、Project Skill delivery、runtime artifact 或 cache refresh，必须验证 installed plugin surface，而不只是源码 typecheck。

Dashboard 验证前端 contract

AlembicDashboard 的 npm run check 包含 lint、dashboard contract test、typecheck 和 build。它保护前端与 /api/v1 contract、TypeScript 类型、组件引用和 Vite 构建。

Dashboard 的验证边界是前端体验。若后端 API shape 改了，除了 Dashboard check，还要跑主 Alembic 后端相关 tests/routes 验证；若只是页面文案/布局，Dashboard check 可能足够。

本书自己的验证

AlembicBook 是文档产品。它的最低验证应包括：

npm run build
git diff --check

此外，本书当前规则还要求：

• 不引用旧插图；正文图片应来自当前 prompt-managed 新图。
• 不临时生成新插图。
• 需要插图的位置使用 docs/public/images/ 下的当前生成图，并能被 npm run illustrations -- --list 管理。
• Markdown 内链不能断。
• 章节内容要能追溯到真实仓库实现，而不是旧书叙事。

如果书稿引用某个工具、命令、路径或发布规则，最好能在源码或 package scripts 中找到对应证据。

选择验证命令的原则

验证不是越多越好，而是覆盖改动边界。

改 Core contract，跑 Core check/build/smoke/public API 和至少一个消费者 import check。

改主 runtime，跑主 Alembic check 或目标 test，并视情况跑 daemon/dashboard smoke。

改 Agent runtime，跑 Agent check/test/public imports。

改 Plugin tool surface，跑 Plugin check、clean output probes、installed cache reload/probe。

改 Dashboard，跑 Dashboard check/build。

改 Book，跑 VitePress build、link/image/diff checks。

本章小结

Alembic 的发布验证是多仓库矩阵。每个仓库都有自己的事实源、发布物和 guard。正确验证不是“跑一个最熟悉的命令”，而是让命令覆盖真实改动边界。

下一章会讲测试和证据解释：验证输出应该怎样被阅读，哪些证据能支持验收，哪些只是中间信号。