diff --git a/docs/zh-CN/concepts/qa-e2e-automation.md b/docs/zh-CN/concepts/qa-e2e-automation.md index b1ff1a7dc..69c22921a 100644 --- a/docs/zh-CN/concepts/qa-e2e-automation.md +++ b/docs/zh-CN/concepts/qa-e2e-automation.md @@ -3,29 +3,29 @@ read_when: - 扩展 qa-lab 或 qa-channel - 添加由仓库支持的 QA 场景 - 围绕 Gateway 网关仪表板构建更高真实性的 QA 自动化 -summary: 用于 qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态 +summary: qa-lab、qa-channel、种子化场景和协议报告的私有 QA 自动化形态 title: QA 端到端自动化 x-i18n: - generated_at: "2026-04-25T17:30:17Z" + generated_at: "2026-04-26T02:36:39Z" model: gpt-5.4 provider: openai - source_hash: be2cfc97a33519e0c4263dc7da356136b10ddcbeef436ab821e645688b6b2cfc + source_hash: 1a90735fad04376b9ea1b6fc3cbbc276ee4b4ed6d0fdb31cfc93f97e9013288f source_path: concepts/qa-e2e-automation.md workflow: 15 --- -私有 QA 自动化栈的目标是以比单个单元测试更贴近真实、更加符合渠道形态的方式来演练 OpenClaw。 +私有 QA 自动化栈的目标，是以比单个单元测试更贴近真实、符合渠道形态的方式来检验 OpenClaw。 当前组成部分： -- `extensions/qa-channel`：合成消息渠道，支持私信、渠道、线程、反应、编辑和删除等界面。 -- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察转录内容、注入入站消息，以及导出 Markdown 报告。 -- `qa/`：由仓库支持的种子资源，用于启动任务和基线 QA 场景。 +- `extensions/qa-channel`：合成消息渠道，包含私信、渠道、线程、反应、编辑和删除等交互面。 +- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察对话记录、注入入站消息，以及导出 Markdown 报告。 +- `qa/`：由仓库支持的启动任务种子资源和基线 QA 场景。 -当前的 QA 操作流程是一个双窗格 QA 站点： +当前的 QA 操作流程是一个双栏 QA 站点： - 左侧：带有智能体的 Gateway 网关仪表板（Control UI）。 -- 右侧：QA Lab，显示类似 Slack 的转录内容和场景计划。 +- 右侧：QA Lab，显示类 Slack 风格的对话记录和场景计划。 使用以下命令运行： @@ -33,9 +33,9 @@ x-i18n: pnpm qa:lab:up ``` -该命令会构建 QA 站点，启动由 Docker 支持的 gateway 车道，并暴露 QA Lab 页面；在这里，操作员或自动化循环可以为智能体分配 QA 任务，观察真实渠道行为，并记录哪些成功了、哪些失败了，或者哪些仍然受阻。 +该命令会构建 QA 站点，启动由 Docker 支持的 gateway 通道，并暴露 QA Lab 页面，供操作员或自动化循环为智能体分配 QA 任务、观察真实渠道行为，并记录哪些内容有效、失败或仍被阻塞。 -为了在不每次都重建 Docker 镜像的情况下更快地迭代 QA Lab UI，可使用绑定挂载的 QA Lab bundle 启动整套系统： +如果你想更快地迭代 QA Lab UI，而无需每次都重建 Docker 镜像，可以使用绑定挂载的 QA Lab bundle 启动该栈： ```bash pnpm openclaw qa docker-build-image @@ -44,26 +44,34 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` 会让 Docker 服务继续使用预构建镜像，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，当 QA Lab 资源哈希发生变化时，浏览器会自动重新加载。 +`qa:lab:up:fast` 会让 Docker 服务继续使用预构建镜像，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重新构建该 bundle，当 QA Lab 资源哈希变化时，浏览器会自动重新加载。 -如需运行一个使用真实传输层的 Matrix 冒烟车道，请执行： +若要运行本地 OpenTelemetry 跟踪冒烟测试，请执行： + +```bash +pnpm qa:otel:smoke +``` + +该脚本会启动一个本地 OTLP/HTTP 跟踪接收器，启用 `diagnostics-otel` 插件运行 `otel-trace-smoke` QA 场景，然后解码导出的 protobuf span，并断言发布关键形态：必须存在 `openclaw.run`、`openclaw.model.call`、`openclaw.context.assembled` 和 `openclaw.message.delivery`；成功轮次中的模型调用不得导出 `StreamAbandoned`；原始诊断 ID 和 `openclaw.content.*` 属性不得出现在跟踪中。它会将 `otel-smoke-summary.json` 写入 QA 套件工件旁边。 + +若要运行一个基于真实传输的 Matrix 冒烟通道，请执行： ```bash pnpm openclaw qa matrix ``` -该车道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的 driver、SUT 和 observer 用户，创建一个私有房间，然后在 QA gateway 子进程中运行真实的 Matrix 插件。这个实时传输车道会将子进程配置限定在被测传输层上，因此 Matrix 会在子配置中不带 `qa-channel` 运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还想捕获外层 `scripts/run-node.mjs` 的构建/启动器输出，可将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=` 设置为仓库本地日志文件。 -默认会打印 Matrix 进度。`OPENCLAW_QA_MATRIX_TIMEOUT_MS` 用于限制完整运行时长，`OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` 用于限制清理时长，这样在 Docker 拆除卡住时，会报告精确的恢复命令，而不是一直挂起。 +该通道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的 driver、SUT 和 observer 用户，创建一个私有房间，然后在 QA gateway 子进程中运行真实的 Matrix 插件。该实时传输通道会将子配置限定在待测传输范围内，因此 Matrix 会在子配置中不包含 `qa-channel` 的情况下运行。它会将结构化报告工件和合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若你也想捕获外层 `scripts/run-node.mjs` 的构建器/启动器输出，请将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=` 设置为仓库本地日志文件。 +默认会打印 Matrix 进度。`OPENCLAW_QA_MATRIX_TIMEOUT_MS` 用于限制整个运行时长，`OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` 用于限制清理时长，这样当 Docker 拆除卡住时，会报告精确的恢复命令而不是一直挂起。 -如需运行一个使用真实传输层的 Telegram 冒烟车道，请执行： +若要运行一个基于真实传输的 Telegram 冒烟通道，请执行： ```bash pnpm openclaw qa telegram ``` -该车道会以一个真实的私有 Telegram 群组为目标，而不是配置一个一次性服务器。它需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并且要求两个不同的机器人位于同一个私有群组中。SUT 机器人必须具有 Telegram 用户名，并且当两个机器人都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode 时，机器人之间的观测效果最佳。 -只要任一场景失败，该命令就会以非零状态退出。如果你想获取产物但不希望退出码失败，请使用 `--allow-failures`。 -Telegram 报告和摘要包含每条回复的 RTT，时间范围从 driver 消息发送请求开始，到观测到 SUT 回复为止，从 canary 开始统计。 +该通道以一个真实的私有 Telegram 群组为目标，而不是配置一次性服务器。它要求提供 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并要求两个不同的 bot 位于同一个私有群组中。SUT bot 必须具有 Telegram 用户名，而当两个 bot 都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode 时，bot 与 bot 之间的观察效果最佳。 +任一场景失败时，该命令会以非零状态退出。如果你希望保留工件但不因失败退出码而失败，请使用 `--allow-failures`。 +Telegram 报告和摘要中包含每次回复的 RTT，计算范围从 driver 消息发送请求到观察到的 SUT 回复，从 canary 开始。 在使用池化的实时凭证之前，请运行： @@ -71,111 +79,110 @@ Telegram 报告和摘要包含每条回复的 RTT，时间范围从 driver 消 pnpm openclaw qa credentials doctor ``` -Doctor 会检查 Convex broker 环境变量，验证端点设置，并在存在维护者密钥时验证 admin/list 的可达性。对于密钥，它只会报告已设置/缺失状态。 +Doctor 会检查 Convex broker 环境变量，验证端点设置，并在存在维护者密钥时验证 admin/list 可达性。它仅报告密钥是已设置还是缺失。 -如需运行一个使用真实传输层的 Discord 冒烟车道，请执行： +若要运行一个基于真实传输的 Discord 冒烟通道，请执行： ```bash pnpm openclaw qa discord ``` -该车道会以一个真实的私有 Discord guild 渠道为目标，并使用两个机器人：一个由 harness 控制的 driver 机器人，以及一个由子 OpenClaw gateway 通过内置 Discord 插件启动的 SUT 机器人。使用环境变量凭证时，它需要 `OPENCLAW_QA_DISCORD_GUILD_ID`、`OPENCLAW_QA_DISCORD_CHANNEL_ID`、`OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` 和 `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID`。 -该车道会验证渠道提及处理，并检查 SUT 机器人是否已向 Discord 注册原生 `/help` 命令。 -只要任一场景失败，该命令就会以非零状态退出。如果你想获取产物但不希望退出码失败，请使用 `--allow-failures`。 +该通道以一个真实的私有 Discord guild 渠道为目标，并使用两个 bot：一个由 harness 控制的 driver bot，以及一个通过内置 Discord 插件由子 OpenClaw gateway 启动的 SUT bot。使用环境变量凭证时，它要求提供 `OPENCLAW_QA_DISCORD_GUILD_ID`、`OPENCLAW_QA_DISCORD_CHANNEL_ID`、`OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`、`OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` 和 `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID`。 +该通道会验证渠道 mention 处理，并检查 SUT bot 是否已向 Discord 注册原生 `/help` 命令。 +任一场景失败时，该命令会以非零状态退出。如果你希望保留工件但不因失败退出码而失败，请使用 `--allow-failures`。 -实时传输车道现在共享一个更小的统一契约，而不是各自发明自己的场景列表形状： +实时传输通道现在共享一个更小的统一契约，而不是各自发明自己的场景列表结构： -`qa-channel` 仍然是覆盖面广泛的合成产品行为测试套件，不属于实时传输覆盖矩阵的一部分。 +`qa-channel` 仍然是覆盖面广的合成产品行为套件，不属于实时传输覆盖矩阵的一部分。 -| 车道 | Canary | 提及门控 | Allowlist 阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 反应观测 | 帮助命令 | 原生命令注册 | -| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | -------- | -------- | ------------ | +| 通道 | Canary | Mention 门控 | Allowlist 阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | Reaction 观察 | Help 命令 | 原生命令注册 | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | | Matrix | x | x | x | x | x | x | x | x | | | | Telegram | x | x | | | | | | | x | | | Discord | x | x | | | | | | | | x | -这样可以让 `qa-channel` 继续作为覆盖面广泛的产品行为测试套件，而 Matrix、Telegram 以及未来的实时传输层则共享一份明确的传输契约检查清单。 +这样可以让 `qa-channel` 保持为覆盖广泛的产品行为套件，同时让 Matrix、Telegram 以及未来的实时传输共享一份明确的传输契约检查清单。 -如需运行一个一次性的 Linux VM 车道，并且不将 Docker 引入 QA 路径，请执行： +若要运行一个一次性的 Linux VM 通道，而不将 Docker 引入 QA 路径，请执行： ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -这会启动一个全新的 Multipass guest，在 guest 内安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。 +该命令会启动一个全新的 Multipass guest，在 guest 内安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。 它会复用与主机上 `qa suite` 相同的场景选择行为。 -主机和 Multipass 套件运行默认都会并行执行多个已选场景，并为每个场景使用隔离的 gateway worker。`qa-channel` 默认并发数为 4，并受所选场景总数限制。使用 `--concurrency ` 可调整 worker 数量，或使用 `--concurrency 1` 进行串行执行。 -只要任一场景失败，该命令就会以非零状态退出。如果你想获取产物但不希望退出码失败，请使用 `--allow-failures`。 -实时运行会转发对 guest 来说实用且受支持的 QA 身份验证输入：基于环境变量的 provider 密钥、QA 实时 provider 配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 能通过挂载的工作区回写。 +主机和 Multipass 套件运行默认都会并行执行多个已选场景，并使用隔离的 gateway worker。`qa-channel` 默认并发数为 4，并受所选场景数量限制。使用 `--concurrency ` 可调整 worker 数量，或使用 `--concurrency 1` 进行串行执行。 +任一场景失败时，该命令会以非零状态退出。如果你希望保留工件但不因失败退出码而失败，请使用 `--allow-failures`。 +实时运行会转发适合 guest 使用的受支持 QA 身份验证输入：基于环境变量的 provider 密钥、QA 实时 provider 配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 能通过挂载的工作区写回内容。 -## 由仓库支持的种子资源 +## 由仓库支持的种子 种子资源位于 `qa/`： - `qa/scenarios/index.md` - `qa/scenarios//*.md` -这些内容有意存放在 git 中，以便人类和智能体都能看到 QA 计划。 +这些内容有意保存在 git 中，以便 QA 计划对人类和智能体都可见。 -`qa-lab` 应保持为一个通用的 Markdown 运行器。每个场景 Markdown 文件都是单次测试运行的真实来源，应定义： +`qa-lab` 应保持为通用的 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的唯一事实来源，并应定义： - 场景元数据 -- 可选的类别、能力、车道和风险元数据 +- 可选的 category、capability、lane 和 risk 元数据 - 文档和代码引用 - 可选的插件要求 - 可选的 gateway 配置补丁 - 可执行的 `qa-flow` -支撑 `qa-flow` 的可复用运行时界面可以保持通用且跨领域。例如，Markdown 场景可以将传输侧辅助工具与浏览器侧辅助工具结合起来，通过 Gateway 网关的 `browser.request` 接缝驱动嵌入式 Control UI，而无需添加特例运行器。 +支撑 `qa-flow` 的可复用运行时表面可以保持通用和跨领域特性。例如，Markdown 场景可以将传输侧辅助工具与浏览器侧辅助工具结合起来，通过 Gateway 网关 `browser.request` 接口驱动嵌入式 Control UI，而无需添加特殊用途的运行器。 -场景文件应按产品能力而不是源码树文件夹进行分组。即使文件移动，也应保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 来追踪实现。 +场景文件应按产品能力而不是源代码树目录分组。文件移动时应保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 提供实现可追溯性。 -基线列表应保持足够广泛，以覆盖： +基线列表应足够广泛，以覆盖： - 私信和渠道聊天 - 线程行为 - 消息动作生命周期 - cron 回调 -- memory recall +- 记忆召回 - 模型切换 -- subagent 交接 +- 子智能体移交 - 读取仓库和读取文档 - 一个小型构建任务，例如 Lobster Invaders -## 提供商 mock 车道 +## provider 模拟通道 -`qa suite` 有两个本地 provider mock 车道： +`qa suite` 有两个本地 provider 模拟通道： -- `mock-openai` 是场景感知的 OpenClaw mock。它仍然是由仓库支持的 QA 和一致性门控的默认确定性 mock 车道。 -- `aimock` 会启动一个由 AIMock 支持的 provider 服务器，用于实验性的协议、夹具、录制/回放和混沌覆盖。它是增量补充，不替代 `mock-openai` 场景分发器。 +- `mock-openai` 是具备场景感知能力的 OpenClaw 模拟。它仍然是由仓库支持的 QA 和 parity gate 的默认确定性模拟通道。 +- `aimock` 会启动一个由 AIMock 支持的 provider 服务器，用于实验性的协议、夹具、录制/回放和混沌覆盖。它是附加能力，不会替代 `mock-openai` 场景分发器。 -provider 车道的实现位于 `extensions/qa-lab/src/providers/` 下。 -每个 provider 都拥有自己的默认值、本地服务器启动逻辑、gateway 模型配置、auth-profile 暂存需求，以及 live/mock 能力标志。共享的 suite 和 gateway 代码应通过 provider 注册表进行路由，而不是根据 provider 名称分支。 +provider 通道实现位于 `extensions/qa-lab/src/providers/` 下。每个 provider 自行负责其默认值、本地服务器启动、gateway 模型配置、auth-profile 暂存需求，以及实时/模拟能力标记。共享的 suite 和 gateway 代码应通过 provider 注册表进行路由，而不是基于 provider 名称分支。 ## 传输适配器 -`qa-lab` 拥有一条用于 Markdown QA 场景的通用传输接缝。 -`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来的真实或合成渠道应插入同一个 suite 运行器，而不是添加一个传输专用 QA 运行器。 +`qa-lab` 拥有一个用于 Markdown QA 场景的通用传输接口。 +`qa-channel` 是该接口上的第一个适配器，但设计目标更广：未来真实或合成的渠道应接入同一个套件运行器，而不是增加传输专用的 QA 运行器。 在架构层面，拆分如下： -- `qa-lab` 负责通用场景执行、worker 并发、产物写入和报告。 -- 传输适配器负责 gateway 配置、就绪状态、入站和出站观测、传输动作以及标准化后的传输状态。 -- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行这些场景的可复用运行时界面。 +- `qa-lab` 负责通用场景执行、worker 并发、工件写入和报告。 +- 传输适配器负责 gateway 配置、就绪状态、入站和出站观察、传输动作以及标准化的传输状态。 +- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行它们的可复用运行时表面。 面向维护者的新渠道适配器采用指南位于 [测试](/zh-CN/help/testing#adding-a-channel-to-qa)。 ## 报告 -`qa-lab` 会根据观测到的总线时间线导出一份 Markdown 协议报告。 +`qa-lab` 会根据观察到的总线时间线导出 Markdown 协议报告。 该报告应回答： -- 哪些有效 -- 哪些失败 -- 哪些仍然受阻 +- 哪些内容有效 +- 哪些内容失败 +- 哪些内容仍被阻塞 - 值得补充哪些后续场景 -如需进行角色和风格检查，请在多个实时模型引用上运行相同场景，并写出经评审的 Markdown 报告： +若要进行角色与风格检查，请在多个实时模型引用上运行同一场景，并写出一份经评判的 Markdown 报告： ```bash pnpm openclaw qa character-eval \ @@ -194,17 +201,23 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -该命令运行的是本地 QA gateway 子进程，而不是 Docker。character eval 场景应通过 `SOUL.md` 设置 persona，然后运行普通的用户轮次，例如聊天、工作区帮助和小型文件任务。不应告知候选模型它正在被评估。该命令会保留每份完整转录，记录基础运行统计信息，然后在支持的情况下使用开启快速模式且带 `xhigh` 推理的 judge 模型，按自然度、氛围和幽默感对各次运行进行排序。比较不同 provider 时，请使用 `--blind-judge-models`：judge 提示仍会获得每份转录和运行状态，但候选引用会被替换为诸如 `candidate-01` 之类的中性标签；报告会在解析后将排序结果映射回真实引用。 +该命令运行的是本地 QA gateway 子进程，而不是 Docker。Character eval 场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区协助和小型文件任务。不应告知候选模型它正在被评估。该命令会保留每一份完整对话记录，记录基本运行统计信息，然后在支持的情况下，以快速模式和 `xhigh` 推理让 judge 模型按自然度、氛围感和幽默感对这些运行结果进行排序。跨 provider 比较时使用 `--blind-judge-models`：judge 提示词仍会获得每份对话记录和运行状态，但候选引用会被替换为诸如 `candidate-01` 之类的中性标签；报告会在解析后将排序结果映射回真实引用。 -候选运行默认使用 `high` thinking，GPT-5.5 使用 `medium`，而支持的较旧 OpenAI 评估引用则使用 `xhigh`。可使用 `--model provider/model,thinking=` 内联覆盖某个特定候选模型。`--thinking ` 仍可设置全局回退值，较旧的 `--model-thinking ` 形式也会保留以兼容旧用法。 +候选运行默认使用 `high` thinking，GPT-5.5 使用 `medium`，而支持该级别的较旧 OpenAI 评估引用默认使用 `xhigh`。你可以使用 `--model provider/model,thinking=` 为特定候选项进行内联覆盖。`--thinking ` 仍会设置全局回退值，而较旧的 `--model-thinking ` 形式则保留用于兼容性。 -OpenAI 候选引用默认启用快速模式，因此在 provider 支持时会使用优先处理。若某个单独候选或 judge 需要覆盖，可内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有在你想为每个候选模型都强制开启快速模式时，才传递 `--fast`。报告会记录候选和 judge 的耗时，供基准分析使用，但 judge 提示会明确说明不要按速度进行排序。 +OpenAI 候选引用默认启用快速模式，以便在 provider 支持时使用优先处理。若某个候选项或 judge 需要单独覆盖，可内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有当你想为每个候选模型强制开启快速模式时，才使用 `--fast`。报告中会记录候选项和 judge 的持续时间以供基准分析使用，但 judge 提示词会明确说明不要按速度排序。 -候选和 judge 模型运行的默认并发度都是 16。当 provider 限制或本地 gateway 压力导致运行噪声过大时，可调低 `--concurrency` 或 `--judge-concurrency`。 +候选模型运行和 judge 模型运行的默认并发数都是 16。当 provider 限制或本地 gateway 压力使运行噪声过大时，可降低 `--concurrency` 或 `--judge-concurrency`。 -当未传递候选 `--model` 时，character eval 默认使用 `openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5` 和 `google/gemini-3.1-pro-preview`。 +当未传入候选 `--model` 时，character eval 默认使用 +`openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、 +`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、 +`moonshot/kimi-k2.5` 和 +`google/gemini-3.1-pro-preview`。 -当未传递 `--judge-model` 时，judge 默认使用 `openai/gpt-5.5,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。 +当未传入 `--judge-model` 时，judge 默认使用 +`openai/gpt-5.5,thinking=xhigh,fast` 和 +`anthropic/claude-opus-4-6,thinking=high`。 ## 相关文档 diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index 76385d0fc..7f7085601 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,23 +1,23 @@ --- read_when: - - 查找公开发布渠道定义 + - 查找公开发布渠道的定义 - 查找版本命名和发布节奏 summary: 公开发布渠道、版本命名和发布节奏 title: 发布策略 x-i18n: - generated_at: "2026-04-24T18:10:40Z" + generated_at: "2026-04-26T02:36:38Z" model: gpt-5.4 provider: openai - source_hash: bc20f30345cbc6c0897e63c9f6a554f9c25be0b52df3efc7d2bbd8827891984a + source_hash: 48ac0ca7d9c6a6ce011e8adda54e1e49beab30456c0dc2bffaec6acec41094df source_path: reference/RELEASING.md workflow: 15 --- OpenClaw 有三个公开发布通道： -- stable：带标签的发布版本，默认发布到 npm `beta`，或在显式请求时发布到 npm `latest` +- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确要求时发布到 npm `latest` - beta：预发布标签，发布到 npm `beta` -- dev：`main` 的移动最新版本 +- dev：`main` 的持续更新头部版本 ## 版本命名 @@ -28,168 +28,178 @@ OpenClaw 有三个公开发布通道： - Beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` - 月和日不要补零 -- `latest` 表示当前已提升的 stable npm 发布版本 +- `latest` 表示当前已提升为正式版的 stable npm 发布 - `beta` 表示当前 beta 安装目标 -- Stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作员可以显式指定 `latest`，或稍后再提升一个经过验证的 beta 构建 +- Stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作人员可以显式将目标设为 `latest`，或稍后再提升一个经过验证的 beta 构建 - 每个 stable OpenClaw 发布都会同时交付 npm 包和 macOS 应用； - beta 发布通常会先验证并发布 npm/package 路径，而 mac 应用的构建 / 签名 / 公证则保留给 stable，除非另有明确要求 + beta 发布通常会先验证并发布 npm / package 路径，而 mac + 应用的构建 / 签名 / 公证通常保留给 stable，除非另有明确要求 ## 发布节奏 -- 发布先走 beta -- 只有在最新 beta 通过验证后，才会进入 stable +- 发布采用 beta-first 流程 +- 只有在最新 beta 完成验证后，才会跟进 stable - 维护者通常从当前 `main` 创建 `release/YYYY.M.D` 分支来切发布， 这样发布验证和修复就不会阻塞 `main` 上的新开发 -- 如果某个 beta 标签已经推送或发布但需要修复，维护者会切下一个 +- 如果某个 beta 标签已经推送或发布，且需要修复，维护者会切下一个 `-beta.N` 标签，而不是删除或重建旧的 beta 标签 -- 详细的发布流程、审批、凭证和恢复说明仅限维护者查看 +- 详细的发布流程、审批、凭证和恢复说明仅面向维护者 ## 发布前检查 -- 在发布前检查前运行 `pnpm check:test-types`，以便在更快的本地 `pnpm check` 门禁之外，测试 TypeScript 仍然得到覆盖 -- 在发布前检查前运行 `pnpm check:architecture`，以便在更快的本地门禁之外，更广泛的导入环和架构边界检查保持通过 -- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，以便 pack - 验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在 -- 每次带标签发布前都要运行 `pnpm release:check` +- 在发布前检查前运行 `pnpm check:test-types`，这样测试 TypeScript + 仍会在更快的本地 `pnpm check` 门禁之外得到覆盖 +- 在发布前检查前运行 `pnpm check:architecture`，这样更广泛的导入环路 + 和架构边界检查会在更快的本地门禁之外保持通过 +- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，这样 + 期望的 `dist/*` 发布产物和 Control UI bundle 会在 pack + 验证步骤中存在 +- 在验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP / HTTP + 接收器运行 QA-lab，并验证导出的追踪 span 名称、有界属性以及内容 / + 标识符脱敏，而无需 Opik、Langfuse 或其他外部收集器。 +- 在每次带标签发布前运行 `pnpm release:check` - 发布检查现在在单独的手动工作流中运行： `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布审批前运行 QA Lab mock parity 门禁，以及实时 - Matrix 和 Telegram QA 通道。实时通道使用 +- `OpenClaw Release Checks` 还会在发布审批前运行 QA Lab mock parity 门禁， + 以及实时的 Matrix 和 Telegram QA 通道。实时通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。 -- 跨 OS 的安装与升级运行时验证由私有调用方工作流分发： +- 跨 OS 的安装和升级运行时验证由私有调用方工作流分发： `openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`， - 它会调用可复用的公开工作流 + 它会调用可复用的公共工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- 这种拆分是有意为之：让真正的 npm 发布路径保持简短、 - 可预测且聚焦于产物，而把更慢的实时检查放在独立通道中， - 这样它们就不会拖慢或阻塞发布 +- 这种拆分是有意为之：让真实的 npm 发布路径保持简短、 + 可预测，并聚焦产物，同时将较慢的实时检查放在独立通道中， + 以免拖慢或阻塞发布 - 发布检查必须从 `main` 工作流 ref 或 - `release/YYYY.M.D` 工作流 ref 分发，以便工作流逻辑和密钥保持受控 -- 该工作流接受现有发布标签，或当前完整的 - 40 字符工作流分支提交 SHA -- 在提交 SHA 模式下，它只接受当前工作流分支的 HEAD；较早的发布提交请使用发布标签 -- `OpenClaw NPM Release` 的仅验证前检查也接受当前完整的 - 40 字符工作流分支提交 SHA，而不要求已推送的标签 -- 该 SHA 路径仅用于验证，不能提升为真实发布 -- 在 SHA 模式下，工作流仅为包元数据检查合成 + `release/YYYY.M.D` 工作流 ref 分发，这样工作流逻辑和密钥才能保持受控 +- 该工作流接受现有发布标签，或当前完整的 40 字符工作流分支提交 SHA +- 在 commit-SHA 模式下，它只接受当前工作流分支的 HEAD；较早的发布提交请使用 + 发布标签 +- `OpenClaw NPM Release` 的仅验证 preflight 也接受当前完整的 + 40 字符工作流分支提交 SHA，而不要求先推送标签 +- 该 SHA 路径仅用于验证，不能被提升为真实发布 +- 在 SHA 模式下，该工作流只会为包元数据检查合成 `v`；真实发布仍然需要真实的发布标签 -- 两个工作流都将真实发布和提升路径保留在 GitHub 托管 runner 上， - 而非变更性的验证路径则可以使用更大的 - Blacksmith Linux runner +- 这两个工作流都将真实发布和提升路径保留在 GitHub-hosted + runners 上，而非变更型验证路径可以使用更大的 + Blacksmith Linux runners - 该工作流会运行 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` 并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 这两个工作流密钥 -- npm 发布前检查不再等待单独的发布检查通道 +- npm 发布 preflight 不再等待单独的发布检查通道 - 在审批前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （或匹配的 beta / 修正标签） + （或对应的 beta / 修正版标签） - npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - （或匹配的 beta / 修正版版本），以在全新的临时前缀中验证已发布的 registry - 安装路径 + （或对应的 beta / 修正版版本），以在新的临时前缀中验证已发布的 + registry 安装路径 - beta 发布后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` - 以验证已安装包的新手引导、Telegram 设置，以及针对已发布 npm 包的真实 Telegram E2E， - 使用共享租赁的 Telegram 凭证池。维护者的本地一次性运行可省略 Convex 变量， - 并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境凭证。 + 以针对已发布的 npm 包验证已安装包的新手引导、Telegram 设置以及真实 Telegram E2E， + 并使用共享的租赁 Telegram 凭证池。本地维护者的单次运行可以省略 Convex 变量， + 直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。 - 维护者也可以通过 GitHub Actions 中的手动 - `NPM Telegram Beta E2E` 工作流运行相同的发布后检查。它有意设置为仅手动运行， - 不会在每次合并时执行。 -- 维护者发布自动化现在使用“先前检查后提升”： + `NPM Telegram Beta E2E` 工作流运行同样的发布后检查。它刻意只支持手动触发， + 不会在每次合并时运行。 +- 维护者发布自动化现在使用 preflight-then-promote： - 真实 npm 发布必须通过成功的 npm `preflight_run_id` - - 真实 npm 发布必须从与成功前检查运行相同的 `main` 或 + - 真实 npm 发布必须从与成功 preflight 运行相同的 `main` 或 `release/YYYY.M.D` 分支分发 - - stable npm 发布默认使用 `beta` - - stable npm 发布可通过工作流输入显式指定 `latest` - - 基于 token 的 npm dist-tag 变更现在位于 + - stable npm 发布默认指向 `beta` + - stable npm 发布可以通过工作流输入显式指定目标为 `latest` + - 基于 token 的 npm dist-tag 修改现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - 中，以增强安全性，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保留仅 OIDC 的发布 - - 公开的 `macOS Release` 仅用于验证 + 中，以提高安全性，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公共 + 仓库保持仅使用 OIDC 发布 + - 公共的 `macOS Release` 仅用于验证 - 真实的私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` - 真实发布路径会提升已准备好的产物，而不是再次重新构建它们 - 对于像 `YYYY.M.D-N` 这样的 stable 修正版发布，发布后验证器 - 还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径， - 以防发布修正悄悄让旧的全局安装仍停留在基础 stable 负载上 -- npm 发布前检查默认失败关闭，除非 tarball 同时包含 - `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 负载， - 以免我们再次发布一个空的浏览器仪表盘 -- 发布后验证还会检查已发布的 registry 安装是否在根 - `dist/*` 布局下包含非空的内置插件运行时依赖。若某次发布带有缺失或空的内置插件 - 依赖负载，则会导致发布后验证失败，并且不能被提升到 `latest`。 -- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算进行强制检查， - 这样安装器 E2E 就能在发布路径之前发现意外的打包膨胀 -- 如果发布工作触及了 CI 规划、扩展 timing manifests 或 - 扩展测试矩阵，请在审批前重新生成并审查由规划器管理的 - `.github/workflows/ci.yml` 中的 `checks-node-extensions` 工作流矩阵输出， + 还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同临时前缀升级路径， + 这样发布修正就不会悄悄让较旧的全局安装仍停留在基础 stable 载荷上 +- npm 发布 preflight 默认采用失败即关闭策略，除非 tarball 同时包含 + `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷， + 以避免我们再次发布一个空的浏览器仪表板 +- 发布后验证还会检查已发布的 registry 安装在根级 `dist/*` + 布局下包含非空的内置插件运行时依赖。若某个发布携带缺失或空的内置插件 + 依赖载荷，则发布后验证器会判定失败，且不能被提升到 + `latest`。 +- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` + 预算进行强制检查，因此安装器 e2e 能在发布路径之前捕获意外的打包膨胀 +- 如果发布工作触及了 CI 规划、扩展 timing manifests 或扩展测试矩阵， + 请在审批前重新生成并审查位于 `.github/workflows/ci.yml` + 中由 planner 负责的 `checks-node-extensions` 工作流矩阵输出， 以免发布说明描述的是过时的 CI 布局 - Stable macOS 发布就绪性还包括更新器相关表面： - - GitHub 发布最终必须包含打包好的 `.zip`、`.dmg` 和 `.dSYM.zip` + - GitHub release 最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip - - 打包应用必须保持非调试 bundle id、非空的 Sparkle feed - URL，以及不低于该发布版本规范 Sparkle build 下限的 `CFBundleVersion` + - 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed + URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` ## NPM 工作流输入 -`OpenClaw NPM Release` 接受以下由操作员控制的输入： +`OpenClaw NPM Release` 接受以下由操作人员控制的输入： - `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 - `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前 - 完整的 40 字符工作流分支提交 SHA，用于仅验证的前检查 -- `preflight_only`：`true` 表示仅进行验证 / 构建 / 打包，`false` 表示真实发布路径 -- `preflight_run_id`：真实发布路径中必填，以便工作流复用成功前检查运行生成的 tarball + `v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前 + 完整的 40 字符工作流分支提交 SHA，用于仅验证的 preflight +- `preflight_only`：`true` 表示仅验证 / 构建 / 打包，`false` 表示真实发布路径 +- `preflight_run_id`：真实发布路径上必填，这样工作流可以复用成功 + preflight 运行中准备好的 tarball - `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta` -`OpenClaw Release Checks` 接受以下由操作员控制的输入： +`OpenClaw Release Checks` 接受以下由操作人员控制的输入： -- `ref`：现有发布标签，或从 `main` 分发时用于验证的当前完整 - 40 字符 `main` 提交 SHA；若从发布分支分发，则使用现有发布标签或当前完整的 - 40 字符发布分支提交 SHA +- `ref`：现有发布标签，或从 `main` 分发时当前完整的 40 字符 `main` 提交 + SHA；若从发布分支分发，请使用现有发布标签或当前完整的 40 字符发布分支提交 + SHA 规则： - Stable 和修正标签可以发布到 `beta` 或 `latest` - Beta 预发布标签只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，完整提交 SHA 输入仅在 - `preflight_only=true` 时允许 -- `OpenClaw Release Checks` 始终仅用于验证，也接受当前 - 工作流分支提交 SHA -- 发布检查的提交 SHA 模式还要求当前工作流分支 HEAD -- 真实发布路径必须使用前检查期间相同的 `npm_dist_tag`； - 工作流会在发布继续前验证该元数据 +- 对于 `OpenClaw NPM Release`，只有在 + `preflight_only=true` 时才允许输入完整提交 SHA +- `OpenClaw Release Checks` 始终仅用于验证，也接受当前工作流分支提交 SHA +- 发布检查的 commit-SHA 模式还要求该 SHA 必须是当前工作流分支 HEAD +- 真实发布路径必须使用 preflight 期间使用的同一个 `npm_dist_tag`； + 工作流会在继续发布前验证该元数据 ## Stable npm 发布顺序 在切 stable npm 发布时： 1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true` - - 在标签尚不存在之前，你可以使用当前完整工作流分支提交 - SHA 来进行前检查工作流的仅验证 dry run -2. 为正常的 beta-first 流程选择 `npm_dist_tag=beta`，或仅在你明确想直接进行 stable 发布时选择 `latest` -3. 使用相同标签再次单独运行 `OpenClaw Release Checks`，或者在你希望获得实时 prompt cache、 - QA Lab parity、Matrix 和 Telegram 覆盖时，使用当前完整工作流分支提交 SHA - - 之所以故意拆开，是为了在不重新耦合长时间运行或易波动检查到发布工作流的情况下， - 仍能提供实时覆盖 + - 在标签尚不存在时，你可以使用当前完整的工作流分支提交 + SHA 来对 preflight 工作流进行仅验证的 dry run +2. 对于正常的 beta-first 流程，选择 `npm_dist_tag=beta`；只有在你明确 + 想直接发布 stable 时，才选择 `latest` +3. 单独运行 `OpenClaw Release Checks`，并使用相同标签，或者 + 当前完整的工作流分支提交 SHA，以便获得实时 prompt cache、 + QA Lab parity、Matrix 和 Telegram 覆盖 + - 之所以单独拆开，是为了让实时覆盖保持可用，而不把长时间运行或不稳定的检查 + 重新耦合回发布工作流 4. 保存成功的 `preflight_run_id` -5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`、相同的 - `tag`、相同的 `npm_dist_tag`，以及保存的 `preflight_run_id` -6. 如果该发布先落在 `beta`，则使用私有的 +5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`，使用相同的 + `tag`、相同的 `npm_dist_tag` 以及保存的 `preflight_run_id` +6. 如果该发布先落到 `beta`，请使用私有的 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - 工作流，将该 stable 版本从 `beta` 提升到 `latest` -7. 如果该发布有意直接发布到 `latest`，并且 `beta` - 也应立即跟进相同 stable 构建，则使用同一个私有 - 工作流将两个 dist-tag 都指向该 stable 版本，或让其计划中的 - 自愈同步稍后再移动 `beta` + 工作流将该 stable 版本从 `beta` 提升到 `latest` +7. 如果该发布是有意直接发布到 `latest`，且 `beta` + 也应立即跟进同一个 stable 构建，请使用同一个私有工作流让两个 dist-tag + 都指向该 stable 版本，或者让其计划中的自愈同步稍后再移动 `beta` -dist-tag 变更位于私有仓库中，以提高安全性，因为它仍然 -需要 `NPM_TOKEN`，而公开仓库保留仅 OIDC 的发布。 +出于安全原因，dist-tag 修改位于私有仓库中，因为它仍然 +需要 `NPM_TOKEN`，而公共仓库保持仅使用 OIDC 发布。 -这样可以让直接发布路径和 beta-first 提升路径都得到文档化，并且对操作员可见。 +这让直接发布路径和 beta-first 提升路径都保持文档化且对操作人员可见。 -如果维护者必须回退到本地 npm 认证，请仅在专用 tmux 会话内运行任何 1Password -CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将其保持在 tmux 内可以让提示、 -告警和 OTP 处理可观察，并防止重复的主机告警。 +如果维护者必须回退到本地 npm 身份验证，请仅在专用 tmux 会话内运行任何 +1Password CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`； +将其保留在 tmux 内可以让提示、告警和 OTP 处理可观察，并防止重复的主机告警。 -## 公开参考 +## 公开参考资料 - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml) - [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml) @@ -198,10 +208,10 @@ CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将其保 - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -维护者使用位于 +维护者会使用私有发布文档 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -的私有发布文档作为实际操作手册。 +作为实际运行手册。 ## 相关内容 -- [Release channels](/zh-CN/install/development-channels) +- [发布渠道](/zh-CN/install/development-channels)