更新和插件测试

更新与插件验证清单：证明可安装包能够更新真实用户状态，通过 doctor 修复过时的遗留状态，并且仍然可以从所有受支持的来源安装、加载、更新和卸载插件。

有关更广泛的测试运行器地图，请参阅测试。有关实时 provider 密钥和涉及网络的测试套件，请参阅实时测试。

本页内容¶

我们保护的内容 - 这些通道所要守护的保证。
开发期间的本地证明 - 迭代期间要运行的命令。
无头节点自动更新证明 - 已安装节点激活和共享 Gateway 防护。
Docker 通道 - 通道参考：每个通道运行什么以及何时运行。
包验收 - 通道参考：验收矩阵及其门禁。
发布默认 - 发布候选版本必须通过的通道。
遗留兼容性 - 仍覆盖的旧包和插件状态。
添加覆盖 - 新回归应放在哪里。
故障分诊 - 当通道变红时该怎么做。

我们保护的内容¶

包 tarball 完整，具有有效的 dist/postinstall-inventory.json，并且不依赖未解包的仓库文件。
用户可以从旧版已发布包迁移到候选包，而不丢失配置、代理、会话、工作区、插件允许列表或通道配置。
openclaw doctor --fix --non-interactive 负责遗留迁移和修复，包括真正悬空的插件运行时别名。包 postinstall 负责包本地依赖残留；两者都会保留其他安装或配置可能使用的有效共享运行时根目录。启动不应为过时的插件状态增加隐藏的兼容性迁移。
插件安装可以从本地目录、git 仓库、npm 包和 ClawHub 注册表路径正常工作。
插件 npm 依赖安装在每个插件一个受管理的 npm 项目中，在信任前被扫描，并在插件卸载时通过 npm uninstall 移除，因此提升的依赖不会残留。
当没有变化时，插件更新是无操作：安装记录、解析后的来源、已安装的依赖布局和启用状态保持完整。

开发期间的本地证明¶

从窄范围开始：

pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed

对于插件安装、卸载、依赖或包清单更改，也运行覆盖已编辑接缝的聚焦测试：

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

在任何包 Docker 通道使用 tarball 之前，先证明包产物：

pnpm release:check

release:check 会运行生成的配置/文档和插件检查（配置 schema、配置文档基线、插件 SDK 导出和 surface 预算、插件版本/清单），写入包 dist 清单，运行 npm pack --dry-run，拒绝禁止打包的文件，将 tarball 安装到临时 prefix，运行 postinstall，并对捆绑的 channel 入口点进行冒烟测试。

对于 Plugin SDK 更改，请单独比较确切的提交：

base_sha=$(git merge-base origin/main HEAD)
head_sha=$(git rev-parse HEAD)
pnpm plugin-sdk:api:diff -- --base "$base_sha" --head "$head_sha"

发布 npm 预检会针对先前已发布的 dist-tag 使用相同的可读 diff，并在该发布更改 Plugin SDK API 时打印所需的 8 字符确认摘要。

无头节点自动更新证明¶

pnpm test:e2e:node-auto-update <built-openclaw.tgz> [new-artifact-directory] 在 Linux 上运行真实的已安装包场景。请在任务拥有的 Testbox 或 Crabbox 中运行，其中具备 Node、npm 和 registry 访问权限。它不需要 provider 凭据，并且是可选加入的；默认的 pnpm test:e2e 聚合不会运行它。

在测试主机上构建并打包候选版本，然后传入该确切的 tarball：

pnpm build
node scripts/package-openclaw-for-docker.mjs --skip-build \
  --output-dir /tmp/openclaw-node-update-package \
  --output-name openclaw-node-update.tgz
pnpm test:e2e:node-auto-update \
  /tmp/openclaw-node-update-package/openclaw-node-update.tgz \
  /tmp/openclaw-node-update-proof

该证明会启动隔离的 Gateway、paired-node、supervisor 和 fixture-registry 进程。它会验证忙碌工作延迟、空闲激活、保留的配对和启动选项、激活冷却、全部三个公开退出选项，以及当候选版本格式错误时保留可用节点。一个相同状态的 Gateway/node 用例确认，在节点激活其私有运行时期间，Gateway 进程、配置和全局安装保持不变。一个独立测试单元针对候选版本运行已发布的 openclaw@2026.9.4 更新器。

一个 legacy-plugin 用例在其命令返回时子进程仍在运行，随后证明缺失的 idle-work 回调会阻止激活，既在该工作期间，也在子进程结束后。一个 default-plugin 节点，没有插件限制或节点命令允许列表，必须在空闲时激活准备好的更新。

每次运行都使用源检出之外的新 artifact 目录，或省略它以创建新的临时目录。该场景会在那里保留 observations.json 和每个进程的日志，并在完成或失败时停止其子进程。在停止远程租约之前收集证明。该场景证明 Linux 行为；它不会建立 Windows 或 macOS 激活覆盖。有关操作员契约，请参阅 Node 自动更新。

Docker 通道¶

Docker 通道是产品级证明。它们在 Linux 容器中安装或更新真实包，并通过 CLI 命令、Gateway 启动、HTTP 探测、RPC 状态和文件系统状态断言行为。

迭代时使用聚焦通道：

pnpm test:docker:plugins
pnpm test:docker:plugin-lifecycle-matrix
pnpm test:docker:plugin-update
pnpm test:docker:upgrade-survivor
pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-restart-auth
pnpm test:docker:update-migration

重要通道：

test:docker:plugins 覆盖插件安装冒烟测试、本地文件夹安装、本地文件夹更新跳过行为、带预装依赖的本地文件夹、file: 包安装、带 CLI 执行的 git 安装、git 移动引用更新、带提升传递依赖的 npm 注册表安装、 npm 更新无操作、拒绝格式错误的 npm 包元数据、本地 ClawHub 夹具安装和更新无操作、市场更新行为，以及 Claude-bundle 启用/检查。设置 OPENCLAW_PLUGINS_E2E_CLAWHUB=0 以保持 ClawHub 块隔离/离线。
test:docker:plugin-lifecycle-matrix 在裸容器中安装候选包，让一个 npm 插件依次经过安装、检查、禁用、启用、显式升级、显式降级，以及在删除插件代码后卸载。它按阶段记录 RSS 和 CPU 指标。
test:docker:plugin-update 验证未更改的已安装插件在 openclaw plugins update 期间不会重新安装或丢失安装元数据。
test:docker:upgrade-survivor 在脏旧用户夹具上覆盖安装候选 tarball，运行包更新和非交互式 doctor，然后启动回环 Gateway 并检查状态保留。
test:docker:published-upgrade-survivor 首先安装最新稳定版本，通过内置的 openclaw config set 配方进行配置，将其更新到候选 tarball，运行 doctor，检查旧版清理，启动 Gateway，并探测 /healthz、/readyz 和 RPC 状态。基线配方通过环境变量引用的 API 密钥配置 Anthropic、Google Gemini 和 OpenAI，并保持 OpenAI 作为代理的主要模型。
test:docker:update-restart-auth 安装候选包，启动托管 token 认证 Gateway，为 openclaw update --yes --json 取消设置调用方 gateway 认证环境变量，并要求候选更新命令在常规探测前重启 Gateway。
test:docker:update-migration 是清理密集的已发布更新通道。它默认安装最新稳定版本，从已配置的 Discord/Telegram 风格用户状态开始，预置包本地插件依赖残留和共享运行时哨兵，并更新到候选 tarball。包 postinstall 必须移除包本地残留，而 update 和 Doctor 保留共享运行时根目录。

将 OPENCLAW_UPGRADE_SURVIVOR_LIVE_MODELS 设置为以空白分隔的模型引用列表，以便在更新后为每个模型运行一次 openclaw agent --local 标记回合。 Anthropic 使用 ANTHROPIC_API_KEY，Google 使用 GEMINI_API_KEY， OpenAI 使用 OPENAI_API_KEY；缺少所选密钥会使通道失败。Docker 仅转发所选提供商密钥。每个回合都有独立会话和 live-<provider>.json / .err 工件（同一提供商的额外模型使用 -2、-3 等）。summary.json 记录 liveModels.models 条目，包含 model、ok 和 latencyMs。

旧版 OPENCLAW_UPGRADE_SURVIVOR_LIVE_OPENAI=1 形式仍会选择 openai/gpt-5.5，或在提供 OPENCLAW_UPGRADE_SURVIVOR_LIVE_OPENAI_MODEL 时选择它。显式模型列表优先于该标志；摘要记录 liveModels.source 和 overridesLiveOpenai。现有的 OPENCLAW_UPGRADE_SURVIVOR_LIVE_OPENAI_TIMEOUT_SECONDS 预算（默认 180 秒）分别适用于每个回合。实时回合使用配方中配置的 thinking 默认值，以便每个模型应用其支持的推理级别。禁止实时提供商的场景保留该限制。

冻结的 extended-stable 候选目标使用其历史 runner，并在 Docker 启动前拒绝两个实时选择变量，退出码为 2。

# Export the three provider keys before invoking the lane.
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.9.5 \
OPENCLAW_UPGRADE_SURVIVOR_LIVE_MODELS="openai/gpt-5.5 anthropic/claude-opus-5 google/gemini-3.1-pro-preview" \
pnpm test:docker:published-upgrade-survivor

base 和 sqlite-volume 的源固定 tarball 运行会在更新前验证候选提交，并在候选探测前将已安装的应用负载与冻结 tarball 进行比较。这可以区分具有相同版本字符串的不同构建。npm 仍负责依赖物化；未选择源 SHA 的手动 tarball 运行保留其现有契约。

有用的已发布升级存活变体：

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.6.1 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.7.1-2 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=sqlite-volume \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.6.34 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=legacy-operator-state \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS=openclaw@2026.9.4 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=custom-plugin-siblings \
pnpm test:docker:published-upgrade-survivor

可用场景：base、acpx-openclaw-tools-bridge、feishu-channel、 bootstrap-persona、channel-post-core-restore、plugin-deps-cleanup、 configured-plugin-installs、custom-plugin-siblings、stale-source-plugin-shadow、tilde-log-path、 meeting-transcripts-sqlite、versioned-runtime-deps、cron-scheduled-authority、 legacy-operator-state 和 sqlite-volume。在聚合运行中， OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues 会展开 release-soak 夹具，但排除耗时的 sqlite-volume 场景。使用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=far-reaching 以包含它。

custom-plugin-siblings 场景从已发布 2026.9.4 或更高版本开始，其中启用了自定义内存插件，并从其运行时入口和 Doctor 配置修复契约导入 ../shared/value.mjs。它针对所选候选 tarball 运行已发布更新器，并要求该契约和 Gateway 插件注册都以私有 canary 状态中的预期同级值执行。仅就绪是不够的。它还检查更新前后的实际插件加载、保留的启用状态以及未更改的原始源文件。当前源 Full Release Validation 将此场景纳入其常规 Package Acceptance 覆盖和 release soak。这些默认发布运行将此场景固定到已发布 2026.9.4 driver，即使源候选仍报告版本 2026.9.4；其他场景保留其现有基线选择。

可选的 projects-doctor 和 projects-startup-migration 场景要求精确的已发布 openclaw@2026.9.4 基线以及一个冻结的候选 tarball。它们使用隔离状态、手动重启，并且不使用实时 provider 或 registry companion fixtures；它们不会通过 reported-issues 或 far-reaching 运行。它们验证原始已发布 driver 和已安装候选 payload 的字节，包括当它们的版本字符串相等时。使用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIO 选择其中一个，并设置 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.9.4。

projects-doctor 保留一个已注册项目和一个已配置工作区，然后两次运行真实的 doctor --lint --only core/doctor/project-clone-shape --json。它检查存储的行、schema、哨兵值以及只读快照清理。projects-startup-migration 通过已发布 owners 使用本地 Git 准备两个独立的 project/worktree 样本。每个样本都有经过验证的备份，以及通过已发布 Doctor 导入的合成 legacy session JSON/JSONL。更新必须通过候选 Doctor 修复第一个样本的规范工作区。第二个状态保持在该更新的发现范围之外。在启动之前，候选 Doctor schema owner 在其维护锁下运行，以升级该数据库，同时保留 legacy workspace 字段以及精确的 session/transcript 字节。其第一次正常 Gateway 启动必须保留该状态。在干净关闭之后，显式的 doctor --fix --non-interactive 修复其规范工作区；第二次启动必须保持已修复状态不变。这些是受支持的 legacy 格式导入，而不是历史运行时生成的 session。两次 Gateway 运行都必须变为 ready 并在持久化读回之前报告干净关闭。将 OPENCLAW_UPGRADE_SURVIVOR_STARTUP_BINDINGS 设置为一个经过审查的 JSON 文件，其中包含候选 commit、agentSchema，以及 operations.prepare/operations.open 的三元组：编译后的 basename、精确导出符号和 SHA-256。快照 preparer 和 SQLite opener 必须与已安装候选 payload 匹配；该文件以只读方式挂载。此场景不使用远程仓库或模型轮次。

可选的 channel-owner-policy 场景使用相同的固定 openclaw@2026.9.4 已发布 driver 和候选包检查。它在已发布数据库的 machine-state 表中注入一个现有的 operator.channelPolicy JSON 样本，然后运行已安装的 updater。它要求 state schema 19 内容、保留的 role/identity policy 和已配置 owners，以及跨两次候选 Gateway 启动的稳定 configured-owner 引用。该样本是合成的现有状态，而不是声称已发布基线铸造了恢复引用。此测试单元使用隔离状态和手动重启；它不证明 updater 拥有的服务重启或旧 reader 降级行为。

legacy-operator-state 场景使用已发布基线自身的 CLI 创建第二个 agent、allowlist exec approvals，以及两个 command cron jobs：一个没有显式 agent，另一个由 ops 拥有。它保持 systemAgent 未设置，通过本地 registry 安装一个版本匹配的 npm 插件，并保留一个 workspace skill。它还配置 DuckDuckGo 但没有安装记录：bundled 基线使用其自身的 CLI web-search 设置；较新的基线接收一个已经损坏的升级所保留的配置。本地 registry 提供候选的官方外部 DuckDuckGo 包。在独立 Doctor 或 consent repair 之前，断言要求 npm 安装记录、候选包版本和完整性、plugins list 条目，以及干净的 config validate --json。另一个隔离的 missing-plugin 状态在没有更新或 capability acceptance 的情况下执行 doctor --fix --non-interactive。一个 mock OpenAI 服务器在更新前后验证一个真实 agent turn，且不使用 provider credentials。更新后，lane 检查 approvals 和 legacy-file retirement、有效 cron owners、候选插件 artifact、候选 state schema、幂等更新以及 Gateway 健康。断言在独立 Doctor 可能掩盖不完整更新迁移之前运行。

已发布的 companion 包版本在整个 fixture 中保留相同的 archive 字节。如果 source candidate 仍使用已发布 companion 的版本，registry 和安装断言会保留该已发布 archive。新的 companion 版本则使用准备好的候选 artifact。npm integrity guard 在两种情况下都保持启用；fixture 从不替换已发布版本的字节以使更新通过。

无 owner 的 cron job 在添加第二个 agent 之前创建，因为较新的基线会拒绝含糊的新 job。approval 快照在比较之前通过基线 CLI 写回：JSON 时代的读取可以分配 ID 而不持久化它们。最终注入的状态仍然包含两个 agent、两个 job，并且没有显式 systemAgent。

PR/main gate 使用 OPENCLAW_UPGRADE_SURVIVOR_UPDATE_RESTART_MODE=auto-auth。对于此场景，基线 updater 必须替换其正在运行的 managed Gateway；harness 检查进程替换和已配置认证。Cron owners 在该第一次更新后立即查询，在任何 consent repair 可能掩盖不完整迁移之前。默认本地 manual 模式传递 --no-restart 并启动候选以进行 probes，因此它不证明 updater 拥有的重启。两种模式都要求干净的 doctor --lint --json 报告。

Schema 快照在 schema-before.json 和 schema-after.json 中记录已发布的 userVersion 和已应用的 contentVersion。该 lane 将已应用内容与候选包的 schema 常量进行比较。自 #141109 起，shared-state 发布可能因 legacy updater 的五分钟终端宽限期而滞后于已完成的迁移；立即要求已发布编号会拒绝一次健康的升级。Agent schemas 仍使用其已发布版本。observer 以只读方式打开数据库，并且从不触发迁移或发布。参见 Schema 提升与旧 updater。

更新前快照还会记录基线已配置的代理名单和代理范围内的旧版样本，包括会话行、转录与轨迹文件、轨迹指针，以及技能 prompt blob。模型目录和无关的逐代理制品不在该观察器的会话迁移范围内。在候选探针或代理轮次之前，每个拥有现有 SQLite 或旧版会话历史的代理，都必须拥有一个符合候选代理模式的存储。观察器会验证导入的会话身份与转录事件、已完成的归档回执与保留的源字节，以及未变化的 prompt blob。没有旧版历史且未被使用的代理，仍可惰性创建其存储。这些检查遵循 Doctor 会话 SQLite 迁移契约；观察器从不导入文件，也不打开可写数据库。

每个受支持的基线（包括 2026.9.2）都必须完成更新，并将其数据库迁移到候选模式。类型化的 update-schema-bump-unfenced 拒绝、回滚、未迁移的数据库或不可用的 Gateway，都会导致泳道失败。必需的插件能力同意只能在自动迁移断言通过后使用现有的显式恢复步骤；它绝不允许将失败的模式修复视为成功。

其他场景保留其现有的成功断言。它们刻意注入的旧版文件可能会阻止基线在更新前启动；更新器必须在候选探针之前迁移这些夹具。该泳道不会预先修复或跳过那些较旧的迁移样本。

在这些聚合别名之外，也可以显式选择 auth-profile-v2026-7-2-beta-5。它会导入历史 JSON 凭据夹具，在当前共享存储中验证凭据和认证顺序，并检查已归档的源字节。它不测试对在已发布 SQLite 存储中创建的凭据的保留。

sqlite-volume 场景默认将已配置的 Matrix、Discord 和 Telegram 插件/频道状态，与 4,800 个会话、23,890 个转录事件和 2,200 个 cron 爬取任务相结合。对于公开插件状态 SDK 的基线，它会使用该已安装的 SDK 创建已发布的共享数据库，并在两个命名空间中写入 512 条永久记录，然后检查每个存储的值和时间戳是否都得以保留。没有该 API 的较旧基线会明确地将此部分报告为不适用。它还会预置账户范围的配对请求和允许列表，以及工作区身份、指令和记忆文件。更新后，它会在任何独立 Doctor 修复掩盖不完整迁移之前，立即验证精确的 JSONL 到 SQLite 迁移、cron 迁移、旧版归档、数据库完整性、账户隔离和工作区内容。然后，它通过 Gateway RPC 读取抽样对话，运行一次幂等 Doctor 遍，并在 Gateway 重启后重复历史和保留检查。

这是 Docker 内部的包更新测试。它不证明容器镜像替换或后台更新活动；这些独立入口请参阅更新。必需的插件能力同意仍然是一个显式恢复步骤，并会记录在幸存者摘要中。

从 2026.9.2 到 2026.9.3 的幸存者转换会演练已安装的更新器。共享状态迁移内容可以是最新的，而已发布的模式版本仍保持为 15，直到旧更新器完成其发布宽限期。模式证明会记录这两个值，并要求内容为当前内容；它既不等待发布，也不强制发布。参见旧更新器模式处理。

test:docker:release-upgrade-user-journey 单独涵盖了显式的外部包管理器流程和全新的 Doctor 流程，包括由所有者停止的 Gateway、经验证的备份，以及通过 Gateway 历史保留的基线与新会话。其回执记录 selfUpdatePassed: false 和 not-run 的自我更新状态；外部安装并不能证明内部更新器的结果。代理模式和不受支持的共享状态迁移拒绝，仍由 Doctor 所有者测试覆盖。

使用 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_SESSIONS、OPENCLAW_UPGRADE_SURVIVOR_VOLUME_EVENTS_PER_SESSION 和 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_CRON_JOBS 来扩展夹具规模。幂等 Doctor 遍的默认预算为 60 秒；在较慢的主机上，可以使用 OPENCLAW_UPGRADE_SURVIVOR_VOLUME_IDEMPOTENCE_BUDGET_SECONDS 覆盖该预算。

Update Migration 工作流每周运行一次，并支持手动触发。其默认的 supported-lines 基线集合会在运行时解析 npm dist-tags 和已发布版本：latest、上一个稳定版本、extended-stable（当该标签存在时），以及受支持下限 2026.6.34。重复版本只运行一次。它会将每个基线更新到选定的 package_ref 制品（默认为 main），演练插件清理和旧版操作员状态。将 baselines 留空即可使用该默认值。若要从 2026.6.1 以来的每个已发布稳定版本执行显式历史回放，请传入 baselines=all-since-2026.6.1：

gh workflow run update-migration.yml \
  --ref main \
  -f workflow_ref=main \
  -f package_ref=main \
  -f baselines=all-since-2026.6.1 \
  -f scenarios=plugin-deps-cleanup

包验收¶

包验收是 GitHub 原生的包门禁。它先将一个候选包解析为 package-under-test tarball，记录版本和 SHA-256，然后针对该确切的 tarball 运行可复用的 Docker E2E 泳道。工作流测试框架引用与包源引用相互独立，因此当前的测试逻辑可以验证较旧的可信版本。

候选来源：

source=npm：验证 openclaw@extended-stable、openclaw@beta、openclaw@latest 或某个精确的已发布版本。
source=ref：使用选定的当前测试框架打包可信的分支、标签或提交。
source=url：验证带有必需 package_sha256 的公共 HTTPS tarball。此路径会拒绝 URL 凭据、非默认 HTTPS 端口、私有/内部主机名或 DNS/IP 结果、特殊用途 IP 地址段，以及不安全的重定向。
source=trusted-url：对照 .github/package-trusted-sources.json 中维护者拥有的策略，验证带有必需 package_sha256 和 trusted_source_id 的 HTTPS tarball。请将其用于企业/私有镜像，而不要通过输入级 allow-private 开关来削弱 source=url。当策略配置了 Bearer 认证时，会使用固定的 OPENCLAW_TRUSTED_PACKAGE_TOKEN 密钥。
source=artifact：复用另一次 Actions 运行上传的 tarball。

完整发布验证默认使用 source=artifact，基于解析后的发布 SHA 构建。对于发布后验证，请传入 package_acceptance_package_spec=openclaw@YYYY.M.PATCH，使相同的升级矩阵改为针对已发布的 npm 包。

发布检查会调用 Package Acceptance，并传入 package/update/restart/plugin 集合：

doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape

当启用发布浸泡测试时（对 release_profile=stable 和 full 强制启用），它们还会传入：

published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai

这使包迁移、更新通道切换、损坏托管插件容错、过期插件依赖清理、离线插件覆盖、插件更新行为以及 Telegram 包 QA 都运行在同一个已解析工件上，而不会让默认发布包门禁遍历每个已发布版本。

当前源发布检查使用相同的 supported-lines 基线扩展，在 Docker 扇出之前一次性解析为精确包。候选源元数据必须暴露新的测试框架，且其 YYYY.M.PATCH 基础版本必须至少不低于受信任工作流包的基础版本；预发布后缀在此比较中会被忽略。子任务会准备或复用预发布插件注册表。默认场景集包括 base 和 legacy-operator-state；发布浸泡测试运行 reported-issues。

独立的 supported-lines 选择器仅展开 legacy-operator-state。所有现有合成场景仍保留在单独解析的候选相对前驱版本上，包括每周 plugin-deps-cleanup 验证。接受逗号和空白分隔符以及重复选择器。显式版本列表和混合选择器/版本列表会保留完整笛卡尔矩阵，用于手动验证。

旧源目标、extended-stable 资格验证、已发布包以及独立 npm 覆盖仍保留候选相对前驱版本和先前场景集。已发布资格验证不会准备新的 operator-state 场景所需的注册表。历史浸泡测试保留所有现有 reported-issue 夹具；它不会自动启用冻结目标场景省略。参见发布资格验证了解确切边界。候选仍为所选的被测包 tarball。每个 PR 的 docker-seed-e2e 触发器仍仅限于 latest 和 legacy-operator-state，并且也会在每次运行 CI 的规范 main 推送上运行。仅文档推送匹配 **/*.md 和 docs/** 时跳过 CI；混合文档和代码推送仍会运行它。

对于手动历史覆盖，last-stable-4 选择四个最近的稳定 npm 已发布版本。精确版本、all-since-2026.6.1 和 release-history 仍可通过 published_upgrade_survivor_baselines 使用。当前工具执行 2026.6.1 及之后的基线。release-history 选择六个最近受支持的稳定版本，而不添加更早的三月或四月锚点。要重放六月之前的升级，请选择匹配的历史工具；对于旧安装，请先升级到 2026.9.5 再安装最新发行版。在重放有界受支持基线集之外的迁移时，使用这些覆盖项。

当选择多个 published-upgrade survivor 基线时，可复用 Docker 工作流会将每个基线分片为各自的定向 runner 作业。每个基线分片仍会运行所选场景集，但日志和工件保持按基线隔离，且实际耗时受最慢分片限制，而不是一个大型串行作业。

在发布前验证候选时，手动运行包配置：

gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=package \
  -f published_upgrade_survivor_scenarios=reported-issues \
  -f telegram_mode=mock-openai

对于已发布的 extended-stable 金丝雀，设置 package_spec=openclaw@extended-stable。Package Acceptance 会在 Docker 通道运行之前将该选择器解析为精确 tarball。

当发布问题包含 MCP 通道、 cron/subagent 清理、OpenAI 网络搜索或 OpenWebUI 时，使用 suite_profile=product。仅当需要完整 Docker 发布路径覆盖时，才使用 suite_profile=full。

发布默认¶

对于发布候选版本，默认验证栈为：

使用 pnpm check:changed 和 pnpm test:changed 检查源级回归。
使用 pnpm release:check 检查包工件完整性。
使用 Package Acceptance package 配置或 release-check 自定义包通道，验证安装/更新/重启/插件契约。
跨操作系统发布检查，验证操作系统特定的安装程序、入门引导和平台行为。
仅当变更面触及提供商或托管服务行为时，才运行实时套件。

在维护者机器上，除非明确进行本地验证，否则广泛门禁和 Docker/包产品验证应在 Testbox 中运行。

遗留兼容性¶

Package Acceptance 应用当前元数据和持久化契约，不再包含已退役的 2026 年 6 月前警告或跳过路径。要复现这些历史候选版本的验收，需要其历史 workflow_ref 工具。

对于保留的升级契约，请将迁移保留在 Doctor 中，并在更新命令拥有重启时，使用 upgrade-survivor、published-upgrade-survivor 或 update-restart-auth 证明变更。六月前的任务和工作流 sidecar 导入已退役；请使用中间升级流程以保留这些记录。

添加覆盖¶

当更改更新或插件行为时，请在能够因正确原因失败的最底层添加覆盖：

纯路径或元数据逻辑：在源代码旁边添加单元测试。
包清单或打包文件行为：package-dist-inventory 或 tarball 检查器测试。
CLI 安装/更新行为：Docker 通道断言或夹具。
已发布版本迁移行为：published-upgrade-survivor 场景。
更新拥有的重启行为：update-restart-auth。
注册表/包源行为：test:docker:plugins 夹具或 ClawHub 夹具服务器。
依赖布局或清理行为：同时断言运行时执行和文件系统边界。npm 依赖项可能会被提升到插件的受管 npm 项目中，因此测试应证明该项目被扫描/清理，而不是假设只有插件包本地的 node_modules 树。

默认使新的 Docker 测试夹具保持隔离性。除非测试目标是实时注册表行为，否则使用本地夹具注册表和假包。

故障排查¶

从工件身份开始：

Package Acceptance resolve_package 摘要：来源、版本、SHA-256 和工件名称。
Docker 工件：.artifacts/docker-tests/**/summary.json、failures.json、泳道日志和重跑命令。
Upgrade survivor 摘要：.artifacts/upgrade-survivor/summary.json，包括基线版本、候选版本、场景、阶段计时和配置配方覆盖。

legacy-operator-state survivor 通过移动标签（latest、beta 或 alpha）安装匹配的已发布伴随包。如果 npm 确认该精确伴随包版本从未发布，则该行在 baselineCompanion 中将该伴随包记录为不可用，并继续剩余的 operator-state 和 external-plugin 迁移检查。注册表错误仍会导致夹具设置失败。未开始的更新报告 unknown 结果；失败的更新尝试报告 failed，独立于后续场景断言。

故障捕获在私有诊断快照中保留最新的会话 SQLite 迁移清单和 Doctor 问题报告，受大小上限约束。已发布的诊断包含问题直方图和捕获遗漏，而不是原始会话详情。在移除测试主机之前收集私有工件。容器拥有的观察目录在该隔离主机上可能需要 sudo tar；保持其权限完整。通过远程包装器收集时，使用不同的成功/失败下载目标。成功下载不会改变 survivor 退出码或 summary.status。

优先使用相同的包工件重跑失败的精确泳道，而不是重跑整个发布伞。

Tests - 测试参考索引，每个读者任务一页
Testing - 完整测试套件：测试集、实时泳道和 Docker 运行器
Release policy - 此检查单所把关的发布流程

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw