From 6982cf37752c83a910741c7d153daa8fe42aac10 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 21:39:00 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/automation/index.md | 113 ++++---- docs/zh-CN/ci.md | 301 ++++++++++++++-------- docs/zh-CN/cli/commitments.md | 94 +++++++ docs/zh-CN/cli/index.md | 81 +++--- docs/zh-CN/concepts/commitments.md | 147 +++++++++++ docs/zh-CN/concepts/memory.md | 87 ++++--- docs/zh-CN/reference/RELEASING.md | 399 +++++++++++++++++------------ 7 files changed, 823 insertions(+), 399 deletions(-) create mode 100644 docs/zh-CN/cli/commitments.md create mode 100644 docs/zh-CN/concepts/commitments.md diff --git a/docs/zh-CN/automation/index.md b/docs/zh-CN/automation/index.md index 67079e525..ace143b29 100644 --- a/docs/zh-CN/automation/index.md +++ b/docs/zh-CN/automation/index.md @@ -1,20 +1,20 @@ --- read_when: - 决定如何使用 OpenClaw 自动化工作 - - 在心跳、cron、钩子和长期指令之间选择 + - 在 Heartbeat、cron、跟进承诺、钩子和常驻指令之间选择 - 寻找合适的自动化入口点 -summary: 自动化机制概览：任务、定时任务、钩子、常驻指令和任务流 +summary: 自动化机制概览：任务、cron、钩子、常设指令和任务流 title: 自动化与任务 x-i18n: - generated_at: "2026-04-29T09:12:56Z" + generated_at: "2026-04-29T21:36:54Z" model: gpt-5.5 provider: openai - source_hash: da79bdd32a231f90850697b94bf061a778e9d0ad81420119ccd3fa0d3bc16fc1 + source_hash: a2465c39f21db8bcb98f980a2c4b2c03018dddd5f43de59d8bf6ce0d6e97d9ef source_path: automation/index.md workflow: 16 --- -OpenClaw 通过任务、计划作业、事件钩子和常设指令在后台运行工作。本页帮助你选择合适的机制，并了解它们如何配合。 +OpenClaw 通过任务、定时任务、推断式跟进承诺、事件钩子和长期指令在后台运行工作。本页帮助你选择合适的机制，并理解它们如何协同工作。 ## 快速决策指南 @@ -25,6 +25,7 @@ flowchart TD START --> Q3{Orchestrate multi-step flows?} START --> Q4{React to lifecycle events?} START --> Q5{Give the agent persistent instructions?} + START --> Q6{Remember a natural follow-up?} Q1 -->|Yes| Q1a{Exact timing or flexible?} Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"] @@ -34,59 +35,68 @@ flowchart TD Q3 -->|Yes| FLOW[Task Flow] Q4 -->|Yes| HOOKS[Hooks] Q5 -->|Yes| SO[Standing Orders] + Q6 -->|Yes| COMMITMENTS[Inferred Commitments] ``` -| 用例 | 推荐 | 原因 | +| 使用场景 | 推荐方式 | 原因 | | --------------------------------------- | ---------------------- | ------------------------------------------------ | -| 在上午 9 点准时发送每日报告 | 计划任务（Cron） | 精确计时，隔离执行 | -| 20 分钟后提醒我 | 计划任务（Cron） | 使用精确计时的一次性任务（`--at`） | -| 运行每周深度分析 | 计划任务（Cron） | 独立任务，可使用不同模型 | -| 每 30 分钟检查收件箱 | 心跳 | 与其他检查批处理，感知上下文 | -| 监控日历中的即将到来的事件 | 心跳 | 自然适合周期性感知 | -| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务账本会跟踪所有分离的工作 | -| 审计运行了什么以及何时运行 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` | -| 多步骤研究后总结 | 任务流 | 带修订跟踪的持久编排 | -| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件上触发 | -| 每次工具调用时执行代码 | 插件钩子 | 进程内钩子可以拦截工具调用 | -| 回复前始终检查合规性 | 常设指令 | 自动注入到每个会话 | +| 在上午 9 点准时发送日报 | 定时任务（Cron） | 精确时间，隔离执行 | +| 20 分钟后提醒我 | 定时任务（Cron） | 使用精确时间的一次性任务（`--at`） | +| 每周运行深度分析 | 定时任务（Cron） | 独立任务，可使用不同模型 | +| 每 30 分钟检查收件箱 | Heartbeat | 与其他检查批量执行，具备上下文感知 | +| 监控日历中的即将到来的事件 | Heartbeat | 非常适合周期性感知 | +| 在提到的面试后跟进 | 推断式跟进承诺 | 类似记忆的跟进，不是明确的提醒请求 | +| 基于用户上下文进行温和关怀式问候 | 推断式跟进承诺 | 限定在同一智能体和渠道内 | +| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务台账会跟踪所有脱离主流程的工作 | +| 审计运行过的内容和时间 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` | +| 多步研究后再总结 | Task Flow | 带修订跟踪的持久编排 | +| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件触发 | +| 每次工具调用时执行代码 | 插件钩子 | 进程内钩子可以拦截工具调用 | +| 回复前始终检查合规性 | 长期指令 | 自动注入到每个会话中 | -### 计划任务（Cron）与心跳 +### 定时任务（Cron）与 Heartbeat -| 维度 | 计划任务（Cron） | 心跳 | -| --------------- | ----------------------------------- | ------------------------------------- | -| 计时 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟） | -| 会话上下文 | 全新（隔离）或共享 | 完整主会话上下文 | -| 任务记录 | 始终创建 | 从不创建 | -| 交付 | 渠道、webhook 或静默 | 内联在主会话中 | -| 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 | +| 维度 | 定时任务（Cron） | Heartbeat | +| ---------- | ----------------------------------- | ------------------------------------- | +| 时间 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟） | +| 会话上下文 | 全新（隔离）或共享 | 完整主会话上下文 | +| 任务记录 | 始终创建 | 从不创建 | +| 投递 | 渠道、webhook 或静默 | 在主会话中内联 | +| 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 | -当你需要精确计时或隔离执行时，使用计划任务（Cron）。当工作受益于完整会话上下文且近似计时可以接受时，使用心跳。 +当你需要精确时间或隔离执行时，使用定时任务（Cron）。当工作受益于完整会话上下文且近似时间即可时，使用 Heartbeat。 ## 核心概念 -### 计划任务（cron） +### 定时任务（cron） -Cron 是 Gateway 网关内置的精确计时调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出交付到聊天渠道或 webhook 端点。支持一次性提醒、重复表达式和入站 webhook 触发器。 +Cron 是 Gateway 网关内置的精确定时调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出投递到聊天渠道或 webhook 端点。支持一次性提醒、重复表达式和入站 webhook 触发器。 -参见[计划任务](/zh-CN/automation/cron-jobs)。 +参见[定时任务](/zh-CN/automation/cron-jobs)。 ### 任务 -后台任务账本跟踪所有分离的工作：ACP 运行、子智能体生成、隔离 cron 执行和 CLI 操作。任务是记录，不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 检查它们。 +后台任务台账会跟踪所有脱离主流程的工作：ACP 运行、子智能体启动、隔离 cron 执行和 CLI 操作。任务是记录，不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 检查它们。 参见[后台任务](/zh-CN/automation/tasks)。 -### 任务流 +### 推断式跟进承诺 -任务流是后台任务之上的流程编排基底。它通过托管和镜像同步模式、修订跟踪，以及用于检查的 `openclaw tasks flow list|show|cancel`，来管理持久的多步骤流程。 +跟进承诺是可选择启用的短期跟进记忆。OpenClaw 会从普通对话中推断它们，将其限定到同一智能体和渠道，并通过 Heartbeat 投递到期的问候。用户明确请求的精确提醒仍应由 cron 处理。 -参见[任务流](/zh-CN/automation/taskflow)。 +参见[推断式跟进承诺](/zh-CN/concepts/commitments)。 -### 常设指令 +### Task Flow -常设指令授予智能体对已定义程序的永久操作权限。它们位于工作区文件中（通常为 `AGENTS.md`），并会注入到每个会话中。可与 cron 结合，用于基于时间的执行。 +Task Flow 是后台任务之上的流程编排基底。它通过托管和镜像同步模式、修订跟踪，以及用于检查的 `openclaw tasks flow list|show|cancel`，管理持久的多步流程。 -参见[常设指令](/zh-CN/automation/standing-orders)。 +参见 [Task Flow](/zh-CN/automation/taskflow)。 + +### 长期指令 + +长期指令为智能体授予针对已定义程序的永久操作权限。它们存放在工作区文件中（通常是 `AGENTS.md`），并会注入到每个会话中。可与 cron 结合使用，以实现基于时间的强制执行。 + +参见[长期指令](/zh-CN/automation/standing-orders)。 ### 钩子 @@ -94,28 +104,29 @@ Cron 是 Gateway 网关内置的精确计时调度器。它会持久化作业， 参见[钩子](/zh-CN/automation/hooks)。 -### 心跳 +### Heartbeat -心跳是周期性的主会话轮次（默认每 30 分钟一次）。它在一个带完整会话上下文的智能体轮次中批处理多个检查（收件箱、日历、通知）。心跳轮次不会创建任务记录，也不会延长每日/空闲会话重置的新鲜度。使用 `HEARTBEAT.md` 放置一个小型清单；如果你希望在心跳自身内部进行仅到期的周期性检查，也可以使用 `tasks:` 块。空心跳文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。当 cron 工作处于活动或排队状态时，心跳会延后；`heartbeat.skipWhenBusy` 也可以在子智能体或嵌套通道繁忙时延后心跳。 +Heartbeat 是周期性的主会话轮次（默认每 30 分钟）。它会在一次智能体轮次中批量执行多项检查（收件箱、日历、通知），并带有完整会话上下文。Heartbeat 轮次不会创建任务记录，也不会延长每日/空闲会话重置的新鲜度。使用 `HEARTBEAT.md` 编写一个小型检查清单；如果你希望在 Heartbeat 本身内部只运行到期的周期性检查，则使用 `tasks:` 块。空的 Heartbeat 文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。当 cron 工作处于活跃或排队状态时，Heartbeat 会延后；`heartbeat.skipWhenBusy` 还可以在子智能体或嵌套通道繁忙时延后它们。 -参见[心跳](/zh-CN/gateway/heartbeat)。 +参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 -## 它们如何配合 +## 它们如何协同工作 -- **Cron** 处理精确计划（每日报告、每周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。 -- **心跳** 在每 30 分钟一次的批处理轮次中处理例行监控（收件箱、日历、通知）。 -- **钩子** 通过自定义脚本响应特定事件（会话重置、压缩、消息流）。插件钩子覆盖工具调用。 -- **常设指令** 为智能体提供持久上下文和权限边界。 -- **任务流** 在单个任务之上协调多步骤流程。 -- **任务** 自动跟踪所有分离的工作，以便你检查和审计。 +- **Cron** 处理精确日程（日报、周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。 +- **Heartbeat** 每 30 分钟在一个批量轮次中处理常规监控（收件箱、日历、通知）。 +- **钩子** 使用自定义脚本响应特定事件（会话重置、压缩、消息流）。插件钩子覆盖工具调用。 +- **长期指令** 为智能体提供持久上下文和权限边界。 +- **Task Flow** 在单个任务之上协调多步流程。 +- **任务** 自动跟踪所有脱离主流程的工作，便于你检查和审计。 ## 相关内容 -- [计划任务](/zh-CN/automation/cron-jobs) — 精确调度和一次性提醒 -- [后台任务](/zh-CN/automation/tasks) — 所有分离工作的任务账本 -- [任务流](/zh-CN/automation/taskflow) — 持久的多步骤流程编排 +- [定时任务](/zh-CN/automation/cron-jobs) — 精确调度和一次性提醒 +- [推断式跟进承诺](/zh-CN/concepts/commitments) — 类似记忆的跟进问候 +- [后台任务](/zh-CN/automation/tasks) — 所有脱离主流程工作的任务台账 +- [Task Flow](/zh-CN/automation/taskflow) — 持久的多步流程编排 - [钩子](/zh-CN/automation/hooks) — 事件驱动的生命周期脚本 - [插件钩子](/zh-CN/plugins/hooks) — 进程内工具、提示、消息和生命周期钩子 -- [常设指令](/zh-CN/automation/standing-orders) — 持久智能体指令 -- [心跳](/zh-CN/gateway/heartbeat) — 周期性主会话轮次 +- [长期指令](/zh-CN/automation/standing-orders) — 持久的智能体指令 +- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性主会话轮次 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有配置键 diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 2b2955cd9..2a69c993e 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -2,67 +2,67 @@ read_when: - 你需要了解某个 CI 作业为何运行或未运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、范围门禁和本地等效命令 +summary: CI 作业图、作用域门禁和本地命令等价项 title: CI 流水线 x-i18n: - generated_at: "2026-04-29T20:52:52Z" + generated_at: "2026-04-29T21:36:49Z" model: gpt-5.5 provider: openai - source_hash: 2d448fb1d5b30b32bd71b79921c0eb8a36b00932e12a31bb069304cf0d1518a8 + source_hash: 6a1ebc8e9e34c27f4ae176e8183637dfe4e1c84c2510b8ffe5614eb4c21c8963 source_path: ci.md workflow: 16 --- -CI 在每次推送到 `main` 以及每个 pull request 时运行。它使用智能范围界定，在只有无关区域发生变更时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能范围界定，并展开完整的常规 CI 图，用于发布候选版本或广泛验证；对于独立手动运行，Android 通道通过 `include_android` 选择加入。仅发布用的插件预发布通道位于单独的 `Plugin Prerelease` 工作流中，并且只从 `Full Release Validation` 或显式手动分派运行。 +CI 在每次推送到 `main` 和每个拉取请求时运行。它使用智能范围限定，在只有无关区域发生变更时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能范围限定，并为发布候选或广泛验证展开完整的常规 CI 图；对于独立手动运行，Android 通道通过 `include_android` 选择启用。仅发布用的插件预发布通道位于单独的 `Plugin Prerelease` 工作流中，并且只从 `Full Release Validation` 或显式手动分发运行。 -`check-dependencies` 分片运行 `pnpm deadcode:dependencies`，这是一次生产 Knip 仅依赖项检查，固定到该脚本使用的最新 Knip 版本，并且为 `dlx` 安装禁用 pnpm 的最低发布时间限制。它还运行 `pnpm deadcode:unused-files`，将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 进行比较。当 PR 添加新的未审查未使用文件，或清理后留下过期的允许列表条目时，该守卫会失败，同时保留 Knip 无法静态解析的有意动态插件、生成产物、构建、实时测试和包桥接表面。 +`check-dependencies` 分片运行 `pnpm deadcode:dependencies`，这是一个生产 Knip 仅依赖项检查流程，固定到该脚本使用的最新 Knip 版本，并为 `dlx` 安装禁用 pnpm 的最小发布时间限制。它还运行 `pnpm deadcode:unused-files`，将 Knip 的生产未使用文件发现结果与 `scripts/deadcode-unused-files.allowlist.mjs` 对比。该保护会在 PR 添加新的未经审查的未使用文件，或清理后留下过期允许列表条目时失败，同时保留 Knip 无法静态解析的有意动态插件、生成内容、构建、实时测试和包桥接表面。 -`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整 commit SHA，使用该目标分派手动 `CI` 工作流，为仅发布用的插件/包/静态/Docker 证明分派 `Plugin Prerelease`，并为安装 smoke、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道分派 `OpenClaw Release Checks`。当提供已发布包规格时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传入发布检查的实时/提供商覆盖范围：`minimum` 保留最快的 OpenAI/核心发布关键通道，`stable` 添加稳定提供商/后端集合，`full` 运行广泛的 advisory 提供商/媒体矩阵。该总控工作流会记录已分派的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父验证器作业，以刷新总控结果和耗时摘要。 +`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标分发手动 `CI` 工作流，为仅发布的插件/包/静态/Docker 证明分发 `Plugin Prerelease`，并为安装冒烟、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 通道分发 `OpenClaw Release Checks`。当提供已发布包规格时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传递给发布检查的实时/提供商覆盖范围：`minimum` 保留最快的 OpenAI/核心发布关键通道，`stable` 添加稳定的提供商/后端集合，`full` 运行广泛的建议提供商/媒体矩阵。总控会记录已分发的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父级验证作业，以刷新总控结果和耗时摘要。 -对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。发布候选版本使用 `all`，仅常规完整 CI 子项使用 `ci`，每个发布子项使用 `release-checks`，或者在总控中使用更窄的发布组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样可以在针对性修复后，将失败发布 box 的重新运行范围保持有界。 +对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。发布候选使用 `all`，仅常规完整 CI 子项使用 `ci`，所有发布子项使用 `release-checks`，或在总控上使用更窄的发布组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这能在完成针对性修复后，将失败发布盒的重新运行范围限制住。 -发布实时/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 以命名分片运行（`native-live-src-agents`、`native-live-src-gateway-core`、按提供商筛选的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及按提供商筛选的音乐分片），而不是一个串行作业。这样在保持相同文件覆盖的同时，让缓慢实时提供商失败更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍然可用于手动一次性重新运行。 +发布实时/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖范围，但它通过 `scripts/test-live-shard.mjs` 以命名分片运行（`native-live-src-agents`、`native-live-src-gateway-core`、提供商过滤的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及提供商过滤的音乐分片），而不是一个串行作业。这样在保持相同文件覆盖范围的同时，让较慢的实时提供商失败更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍然可用于手动一次性重新运行。 -原生实时媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预安装 `ffmpeg` 和 `ffprobe`；媒体作业只在设置前验证这些二进制文件。将 Docker 支持的实时套件保留在常规 Blacksmith runner 上，因为容器作业不是启动嵌套 Docker 测试的合适位置。 +原生实时媒体分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预装 `ffmpeg` 和 `ffprobe`；媒体作业只在设置前验证这些二进制文件。让 Docker 支持的实时套件继续在常规 Blacksmith 运行器上运行，因为容器作业不适合启动嵌套 Docker 测试。 -Docker 支持的实时模型/后端分片会为所选 commit 使用单独共享的 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流构建并推送该镜像一次，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片会使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重建完整源 Docker 目标，则发布运行配置错误，并会在重复镜像构建上浪费挂钟时间。 +Docker 支持的实时模型/后端分片为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流会构建并推送一次该镜像，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP 绑定和 Codex harness 分片使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重新构建完整源码 Docker 目标，说明发布运行配置有误，并会把墙钟时间浪费在重复镜像构建上。 -`OpenClaw Release Checks` 使用受信任的工作流 ref，将所选 ref 一次性解析为 `release-package-under-test` tarball，然后将该 artifact 传递给实时/E2E 发布路径 Docker 工作流和包验收分片。这样可以让发布 box 之间的包字节保持一致，并避免在多个子作业中重复打包同一个候选版本。 +`OpenClaw Release Checks` 使用可信工作流引用将选定引用解析一次为 `release-package-under-test` tarball，然后将该工件传递给实时/E2E 发布路径 Docker 工作流和包验收分片。这样可以让发布盒之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选版本。 -`Package Acceptance` 是用于验证包 artifact 的旁路运行工作流，不会阻塞发布工作流。它会从已发布 npm 规格、使用所选 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或另一个 GitHub Actions 运行中的 tarball artifact 解析一个候选项，将其上传为 `package-under-test`，然后复用 Docker 发布/E2E 调度器，使用该 tarball 而不是重新打包工作流 checkout。Profile 覆盖 smoke、package、product、full 和自定义 Docker 通道选择。`package` profile 使用离线插件覆盖，因此已发布包验证不会受实时 ClawHub 可用性限制。可选 Telegram 通道会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` artifact，并为独立分派保留已发布 npm 规格路径。 +`Package Acceptance` 是用于验证包工件且不阻塞发布工作流的旁路运行工作流。它从已发布的 npm 规格、使用选定 `workflow_ref` harness 构建的可信 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或来自另一个 GitHub Actions 运行的 tarball 工件中解析一个候选项，将其上传为 `package-under-test`，然后复用 Docker 发布/E2E 调度器，使用该 tarball 而不是重新打包工作流检出内容。配置文件覆盖冒烟、包、产品、完整和自定义 Docker 通道选择。`package` 配置文件使用离线插件覆盖范围，因此已发布包验证不会受实时 ClawHub 可用性限制。可选 Telegram 通道在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 工件，同时保留已发布 npm 规格路径用于独立分发。 ## 包验收 -当问题是“这个可安装的 OpenClaw 包作为产品是否可用？”时，使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证源代码树，而包验收通过用户在安装或更新后使用的同一个 Docker E2E harness 验证单个 tarball。 +当问题是“这个可安装的 OpenClaw 包作为产品是否可用？”时，使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证源码树，而包验收通过用户在安装或更新后执行的同一套 Docker E2E harness 验证单个 tarball。 该工作流有四个作业： -1. `resolve_package` checkout `workflow_ref`，解析一个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将二者作为 `package-under-test` artifact 上传，并在 GitHub step summary 中打印来源、工作流 ref、包 ref、版本、SHA-256 和 profile。 -2. `docker_acceptance` 调用 `openclaw-live-and-e2e-checks-reusable.yml`，并传入 `ref=workflow_ref` 和 `package_artifact_name=package-under-test`。可复用工作流会下载该 artifact，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该包而不是打包工作流 checkout 运行所选 Docker 通道。当某个 profile 选择多个定向 `docker_lanes` 时，可复用工作流会先准备包和共享镜像一次，然后将这些通道展开为并行定向 Docker 作业，并生成唯一 artifact。 -3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行；如果 Package Acceptance 解析了一个包，它会安装同一个 `package-under-test` artifact；独立 Telegram 分派仍可安装已发布 npm 规格。 -4. 如果包解析、Docker 验收或可选 Telegram 通道失败，`summary` 会使工作流失败。 +1. `resolve_package` 检出 `workflow_ref`，解析一个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` 工件上传，并在 GitHub 步骤摘要中打印来源、工作流引用、包引用、版本、SHA-256 和配置文件。 +2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。可复用工作流下载该工件，验证 tarball 清单，在需要时准备包摘要 Docker 镜像，并针对该包而不是打包工作流检出内容运行选定的 Docker 通道。当某个配置文件选择多个目标 `docker_lanes` 时，可复用工作流会准备一次包和共享镜像，然后将这些通道展开为并行的目标 Docker 作业，并使用唯一工件。 +3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行，并在 Package Acceptance 已解析出包时安装相同的 `package-under-test` 工件；独立 Telegram 分发仍可安装已发布的 npm 规格。 +4. `summary` 会在包解析、Docker 验收或可选 Telegram 通道失败时使工作流失败。 候选来源： -- `source=npm`：只接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。将其用于已发布 beta/stable 验收。 -- `source=ref`：打包受信任的 `package_ref` 分支、标签或完整 commit SHA。解析器会获取 OpenClaw 分支/标签，验证所选 commit 可从仓库分支历史或发布标签到达，在 detached worktree 中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 +- `source=npm`：只接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 +- `source=ref`：打包可信的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证选定提交可从仓库分支历史或发布标签到达，在分离的工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 - `source=url`：下载 HTTPS `.tgz`；必须提供 `package_sha256`。 -- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 可选，但应为外部共享 artifact 提供。 +- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 可选，但对于外部共享工件应提供。 -保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是 `source=ref` 时会被打包的源 commit。这让当前测试 harness 可以验证较旧的受信任源 commit，而无需运行旧工作流逻辑。 +保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的可信工作流/harness 代码。`package_ref` 是在 `source=ref` 时被打包的源提交。这样当前测试 harness 就可以验证较旧的可信源提交，而无需运行旧的工作流逻辑。 -Profile 映射到 Docker 覆盖： +配置文件映射到 Docker 覆盖范围： - `smoke`：`npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package`：`npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`bundled-channel-deps-compat`、`plugins-offline`、`plugin-update` - `product`：`package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` -- `full`：带 OpenWebUI 的完整 Docker 发布路径块 +- `full`：带 OpenWebUI 的完整 Docker 发布路径分块 - `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时必需 -发布检查使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。发布路径 Docker 块覆盖重叠的包/更新/插件通道，而 Package Acceptance 保留针对同一个已解析包 tarball 的 artifact-native bundled-channel 兼容性、离线插件和 Telegram 证明。 -跨 OS 发布检查仍覆盖特定 OS 的新手引导、安装器和平台行为；包/更新产品验证应从 Package Acceptance 开始。Windows 打包和安装器全新通道还会验证已安装包可以从原始绝对 Windows 路径导入 browser-control override。OpenAI 跨 OS 智能体 turn smoke 在设置时默认使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因此安装和 Gateway 网关证明保持快速且确定。专用实时提供商/模型通道仍覆盖更广泛的模型路由，包括更慢的 frontier 默认值。 +发布检查使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用包验收。发布路径 Docker 分块覆盖重叠的包/更新/插件通道，而包验收针对同一个已解析包 tarball 保留工件原生的内置渠道兼容、离线插件和 Telegram 证明。 +跨 OS 发布检查仍覆盖特定 OS 的新手引导、安装器和平台行为；包/更新产品验证应从包验收开始。Windows 打包和安装器全新安装通道还会验证已安装包能否从原始绝对 Windows 路径导入 browser-control 覆盖项。OpenAI 跨 OS 智能体回合冒烟默认使用已设置的 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因此安装和 Gateway 网关证明保持快速且确定。专用实时提供商/模型通道仍覆盖更广泛的模型路由，包括较慢的前沿默认项。 -Package Acceptance 对已发布包有有界的旧版兼容窗口。到 `2026.4.25` 为止的包（包括 `2026.4.25-beta.*`）可以对 `dist/postinstall-inventory.json` 中指向 tarball 省略文件的已知私有 QA 条目使用兼容路径；当包未暴露该 flag 时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；`update-channel-switch` 可以从 tarball 派生的伪 git fixture 中修剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；插件 smoke 可以读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；`plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 包也可以针对已发布的本地构建元数据 stamp 文件发出警告。之后的包必须满足现代契约；相同条件将失败，而不是警告或跳过。 +包验收为已经发布的包设置了有界的旧版兼容窗口。到 `2026.4.25` 为止的包，包括 `2026.4.25-beta.*`，可对 `dist/postinstall-inventory.json` 中指向 tarball 省略文件的已知私有 QA 条目使用兼容路径；当包不暴露 `gateway install --wrapper` 标志时，`doctor-switch` 可跳过其持久化子案例；`update-channel-switch` 可从 tarball 派生的伪 git fixture 中修剪缺失的 `pnpm.patchedDependencies`，并可记录缺失的持久化 `update.channel`；插件冒烟可读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；`plugin-update` 可允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 包也可针对已经发布的本地构建元数据标记文件发出警告。之后的包必须满足现代契约；相同条件会失败，而不是警告或跳过。 示例： @@ -105,23 +105,130 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -调试失败的包验收运行时，先查看 `resolve_package` 摘要，确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 构件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志、阶段计时和重新运行命令。优先重新运行失败的包配置文件或确切的 Docker lane，而不是重新运行完整发布验证。 +调试失败的 package acceptance 运行时，先查看 `resolve_package` +摘要，确认 package 来源、版本和 SHA-256。然后检查 +`docker_acceptance` 子运行及其 Docker 工件： +`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 日志、阶段 +耗时和重新运行命令。优先重新运行失败的 package profile 或 +精确的 Docker lane，而不是重新运行完整的发布验证。 -QA Lab 在主智能范围工作流之外有专用 CI lane。`Parity gate` 工作流会在匹配的 PR 变更和手动分发时运行；它会构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 智能体包。`QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也可手动分发；它会将模拟一致性门、实时 Matrix lane、实时 Telegram 和 Discord lane 作为并行作业展开。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。发布检查会使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 和 `mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输 lane，这样渠道契约就能与实时模型延迟和常规提供商插件启动隔离。实时传输 Gateway 网关还会禁用内存搜索，因为 QA 一致性会单独覆盖内存行为；提供商连接性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。Matrix 会对计划任务和发布门使用 `--profile fast`，仅在检出的 CLI 支持时添加 `--fail-fast`。CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 分发始终会将完整 Matrix 覆盖分片为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 还会在发布批准前运行发布关键的 QA Lab lane；它的 QA 一致性门会将候选包和基线包作为并行 lane 作业运行，然后把两个构件下载到一个小型报告作业中，用于最终一致性比较。不要把 PR 合并路径置于 `Parity gate` 之后，除非变更确实触及 QA 运行时、模型包一致性，或一致性工作流拥有的表面。对于常规渠道、配置、文档或单元测试修复，将其视为可选信号，并遵循范围化的 CI/检查证据。 +QA Lab 在主智能范围化 workflow 之外有专用的 CI lane。 +`Parity gate` workflow 会在匹配的 PR 变更和手动调度时运行；它会 +构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 +agentic pack。`QA-Lab - All Lanes` workflow 会在 `main` 上每夜运行，也可 +手动调度；它会将 mock parity gate、live Matrix lane，以及 live +Telegram 和 Discord lane 作为并行 job 扇出。live job 使用 +`qa-live-shared` 环境，Telegram/Discord 使用 Convex lease。发布 +检查会使用确定性 mock provider 和 mock 限定的模型（`mock-openai/gpt-5.5` 和 +`mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram live transport lane，因此 channel contract +会与 live model 延迟和正常 provider-plugin 启动隔离。live transport gateway 也会 +禁用 memory search，因为 QA parity 会单独覆盖 memory 行为； +provider 连通性由独立的 live model、native provider +和 Docker provider suite 覆盖。Matrix 在定时和发布 gate 中使用 `--profile fast`， +只有在检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值 +和手动 workflow 输入仍为 `all`；手动 `matrix_profile=all` +调度总是将完整 Matrix 覆盖分片为 `transport`、`media`、 +`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` job。`OpenClaw Release Checks` 也会 +在发布批准前运行发布关键的 QA Lab lane；它的 QA parity +gate 会将候选 pack 和 baseline pack 作为并行 lane job 运行，然后把 +两个工件下载到一个小型 report job 中，用于最终 parity 比较。 +除非变更实际触及 QA runtime、model-pack parity，或 parity workflow 拥有的 surface， +否则不要把 PR landing path 置于 `Parity gate` 之后。 +对于普通 channel、config、docs 或 unit-test 修复，应将其视为可选 +信号，并遵循范围化的 CI/check 证据。 -`Duplicate PRs After Merge` 工作流是用于合并后重复项清理的手动维护者工作流。它默认是 dry-run，且仅在 `apply=true` 时关闭明确列出的 PR。在变更 GitHub 之前，它会验证已落地的 PR 已合并，并且每个重复 PR 都有共享的引用议题或重叠的变更 hunk。 +`Duplicate PRs After Merge` workflow 是一个供维护者在落地后清理 +重复项的手动 workflow。它默认 dry-run，只有在 `apply=true` 时才会关闭显式 +列出的 PR。在修改 GitHub 之前，它会验证已落地 PR 已合并，并且每个 +重复项都有共享的 referenced issue 或重叠的 changed hunks。 -`CodeQL` 工作流有意作为范围较窄的第一轮安全扫描器，而不是完整仓库扫描。每日和手动运行会使用高精度安全查询扫描 Actions 工作流代码，以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 Gateway 网关表面。channel-runtime-boundary 作业会在 `/codeql-critical-security/channel-runtime-boundary` 类别下单独扫描核心渠道实现契约，以及渠道插件运行时、Gateway 网关、插件 SDK、密钥和审计触点，这样渠道安全信号就能在不扩大基线 JS/TS 类别的情况下扩展。network-ssrf-boundary 作业会在 `/codeql-critical-security/network-ssrf-boundary` 类别下扫描核心 SSRF、IP 解析、网络防护、web-fetch 和插件 SDK SSRF 策略表面，这样网络信任边界信号就能与更广泛的 JS/TS 安全基线保持分离。mcp-process-tool-boundary 作业会在 `/codeql-critical-security/mcp-process-tool-boundary` 类别下扫描 MCP 服务器、进程执行辅助工具、出站投递和智能体工具执行门，这样命令和工具边界信号就能同时与通用 JS/TS 基线及非安全 MCP/进程质量分片保持分离。 +`CodeQL` workflow 有意作为窄范围的第一轮安全扫描器， +不是完整的仓库扫描。每日和手动运行会扫描 Actions workflow code +以及风险最高的 JavaScript/TypeScript auth、secrets、sandbox、cron 和 +gateway surface，并在 +`/codeql-critical-security/core-auth-secrets` category 下使用高精度安全查询。 +channel-runtime-boundary job 会另外扫描核心 channel implementation +contract，以及 channel plugin runtime、gateway、Plugin SDK、secrets 和 +audit touchpoint，归入 `/codeql-critical-security/channel-runtime-boundary` +category，这样 channel security signal 可以扩展，而无需扩大 baseline +auth/secrets category。network-ssrf-boundary job 会扫描核心 SSRF、IP parsing、 +network guard、web-fetch 和 Plugin SDK SSRF policy surface，归入 +`/codeql-critical-security/network-ssrf-boundary` category，这样 network trust +boundary signal 会与 auth/secrets security baseline 分离。 +mcp-process-tool-boundary job 会扫描 MCP server、process execution helper、 +outbound delivery 和 agent tool-execution gate，归入 +`/codeql-critical-security/mcp-process-tool-boundary` category，这样 command 和 +tool boundary signal 会与 auth/secrets baseline 以及 +非安全 MCP/process quality shard 分离。 -`CodeQL Android Critical Security` 工作流是计划运行的 Android 安全分片。它会在工作流完整性检查接受的最小 Blacksmith Linux runner 标签上为 CodeQL 手动构建 Android 应用，并在 `/codeql-critical-security/android` 类别下上传结果。 +`CodeQL Android Critical Security` workflow 是定时 Android +security shard。它会在 workflow sanity 接受的最小 +Blacksmith Linux runner label 上为 CodeQL 手动构建 Android app，并将结果上传到 +`/codeql-critical-security/android` category 下。 -`CodeQL macOS Critical Security` 工作流是每周/手动运行的 macOS 安全分片。它会在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用，从上传的 SARIF 中过滤掉依赖构建结果，并在 `/codeql-critical-security/macos` 类别下上传结果。将它保留在每日默认工作流之外，因为即使干净时，macOS 构建也会主导运行时间。 +`CodeQL macOS Critical Security` workflow 是每周/手动 macOS +security shard。它会在 Blacksmith macOS 上为 CodeQL 手动构建 macOS app， +从上传的 SARIF 中过滤 dependency build result，并将结果上传到 +`/codeql-critical-security/macos` category 下。将它放在每日 +默认 workflow 之外，因为即使在干净状态下，macOS build 也会主导运行时长。 -`CodeQL Critical Quality` 工作流是对应的非安全分片。它只在较小的 Blacksmith Linux runner 上，对范围较窄的高价值表面运行错误严重级别、非安全 JavaScript/TypeScript 质量查询。它的手动分发接受 `profile=all|plugin-sdk-package-contract`；窄配置文件是用于隔离运行一个质量分片的首个教学/迭代钩子，无需分发工作流其余部分。它的 core-auth-secrets 作业会在单独的 `/codeql-critical-quality/core-auth-secrets` 类别下扫描凭证、密钥、沙箱、cron 和 Gateway 网关安全边界代码。config-boundary 作业会在单独的 `/codeql-critical-quality/config-boundary` 类别下扫描配置 schema、迁移、规范化和 IO 契约。gateway-runtime-boundary 作业会在单独的 `/codeql-critical-quality/gateway-runtime-boundary` 类别下扫描 Gateway 网关协议 schema 和服务器方法契约。channel-runtime-boundary 作业会在单独的 `/codeql-critical-quality/channel-runtime-boundary` 类别下扫描核心渠道实现契约。agent-runtime-boundary 作业会在单独的 `/codeql-critical-quality/agent-runtime-boundary` 类别下扫描命令执行、模型/提供商分发、自动回复分发和队列，以及 ACP 控制平面运行时契约。mcp-process-runtime-boundary 作业会在单独的 `/codeql-critical-quality/mcp-process-runtime-boundary` 类别下扫描 MCP 服务器和工具桥、进程监督辅助工具，以及出站投递契约。memory-runtime-boundary 作业会在单独的 `/codeql-critical-quality/memory-runtime-boundary` 类别下扫描内存主机 SDK、内存运行时外观、内存插件 SDK 别名、内存运行时激活胶水代码和内存 Doctor 命令。ui-control-plane 作业会在单独的 `/codeql-critical-quality/ui-control-plane` 类别下扫描 Control UI 启动、本地持久化、Gateway 网关控制流和任务控制平面运行时契约。web-media-runtime-boundary 作业会在单独的 `/codeql-critical-quality/web-media-runtime-boundary` 类别下扫描核心 web 获取/搜索、媒体 IO、媒体理解、图像生成和媒体生成运行时契约。plugin-boundary 作业会在单独的 `/codeql-critical-quality/plugin-boundary` 类别下扫描加载器、注册表、公共表面和插件 SDK 入口点契约。plugin-sdk-package-contract 作业会在单独的 `/codeql-critical-quality/plugin-sdk-package-contract` 类别下扫描已发布包侧的插件 SDK 源码和插件包契约辅助工具。让该工作流与安全分离，这样质量发现就能在不掩盖安全信号的情况下进行计划、度量、禁用或扩展。Swift、Python 和内置插件 CodeQL 扩展应仅在窄配置文件具备稳定运行时和信号后，作为范围化或分片式后续工作加回。 +`CodeQL Critical Quality` workflow 是对应的非安全 shard。它 +只在较小的 Blacksmith Linux runner 上，对窄范围高价值 surface 运行 +error-severity、非安全的 JavaScript/TypeScript quality query。它的 +手动调度接受 `profile=all|plugin-sdk-package-contract`；窄范围 +profile 是第一个教学/迭代钩子，可用于隔离运行一个 quality shard， +而无需调度 workflow 的其余部分。 +它的 +core-auth-secrets job 会扫描 auth、secrets、sandbox、cron 和 gateway security +boundary code，归入单独的 `/codeql-critical-quality/core-auth-secrets` +category。config-boundary +job 会扫描 config schema、migration、normalization 和 IO contract，归入 +单独的 `/codeql-critical-quality/config-boundary` category。gateway-runtime-boundary job 会扫描 gateway protocol schema 和 server method +contract，归入单独的 +`/codeql-critical-quality/gateway-runtime-boundary` category。channel-runtime-boundary job 会扫描核心 channel implementation contract，归入 +单独的 `/codeql-critical-quality/channel-runtime-boundary` category。agent-runtime-boundary job 会扫描 command execution、model/provider dispatch、 +auto-reply dispatch 与 queue，以及 ACP control-plane runtime contract，归入 +单独的 `/codeql-critical-quality/agent-runtime-boundary` category。mcp-process-runtime-boundary job 会扫描 MCP server 和 tool bridge、process +supervision helper，以及 outbound delivery contract，归入单独的 +`/codeql-critical-quality/mcp-process-runtime-boundary` category。memory-runtime-boundary job 会扫描 memory host SDK、memory runtime facade、 +memory Plugin SDK alias、memory runtime activation glue，以及 memory doctor +command，归入单独的 `/codeql-critical-quality/memory-runtime-boundary` +category。 +ui-control-plane job 会扫描 Control UI bootstrap、local persistence、gateway +control flow 和 task control-plane runtime contract，归入单独的 +`/codeql-critical-quality/ui-control-plane` category。web-media-runtime-boundary job 会扫描核心 web fetch/search、media IO、media +understanding、image-generation 和 media-generation runtime contract，归入 +单独的 `/codeql-critical-quality/web-media-runtime-boundary` category。plugin-boundary job 会扫描 loader、registry、public-surface 和 Plugin SDK +entrypoint contract，归入单独的 `/codeql-critical-quality/plugin-boundary` +category。plugin-sdk-package-contract job 会扫描已发布 package 侧的 +Plugin SDK source 和 plugin package contract helper，归入单独的 +`/codeql-critical-quality/plugin-sdk-package-contract` category。保持该 +workflow 与 security 分离，这样 quality finding 就可以被 +调度、衡量、禁用或扩展，而不会遮蔽 security signal。 +Swift、Python 和 bundled-plugin CodeQL 扩展应仅在窄范围 profile 具备稳定 +runtime 和 signal 后，作为范围化或分片的后续工作重新加入。 -`Docs Agent` 工作流是事件驱动的 Codex 维护 lane，用于让现有文档与最近落地的变更保持一致。它没有纯计划任务：`main` 上成功的非机器人 push CI 运行可以触发它，手动分发也可以直接运行它。通过 workflow-run 调用时，如果 `main` 已继续前进，或最近一小时内已创建另一个未跳过的 Docs Agent 运行，则会跳过。运行时，它会审查从上一个未跳过的 Docs Agent 来源 SHA 到当前 `main` 的提交范围，因此一次每小时运行可以覆盖自上次文档处理以来积累的所有 main 变更。 +`Docs Agent` workflow 是事件驱动的 Codex 维护 lane，用于让 +现有 docs 与最近落地的变更保持一致。它没有纯定时计划：`main` 上 +成功的非 bot push CI 运行可以触发它，手动调度也可以 +直接运行它。workflow-run 调用会在 `main` 已经前移，或过去一小时内 +已创建另一个未跳过的 Docs Agent 运行时跳过。运行时，它会 +审查从上一个未跳过的 Docs Agent source SHA 到当前 `main` 的 commit range， +因此一次每小时运行可以覆盖自上次 docs pass 以来积累的所有 main 变更。 -`Test Performance Agent` 工作流是事件驱动的 Codex 维护 lane，用于处理慢测试。它没有纯计划任务：`main` 上成功的非机器人 push CI 运行可以触发它，但如果该 UTC 日已经有另一个 workflow-run 调用运行过或正在运行，它会跳过。手动分发会绕过该每日活动门。该 lane 会构建一个完整套件分组 Vitest 性能报告，让 Codex 只进行保留覆盖率的小型测试性能修复，而不是大范围重构，然后重新运行完整套件报告，并拒绝会降低通过基线测试数量的变更。如果基线存在失败测试，Codex 只能修复明显失败项，且智能体之后的完整套件报告必须通过后才能提交任何内容。当 `main` 在机器人推送落地前前进时，该 lane 会对已验证补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；有冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以保持与文档智能体相同的 drop-sudo 安全姿态。 +`Test Performance Agent` workflow 是事件驱动的 Codex 维护 lane， +用于处理慢测试。它没有纯定时计划：`main` 上成功的非 bot push CI 运行 +可以触发它，但如果另一个 workflow-run 调用在同一个 UTC 日已经 +运行或正在运行，它会跳过。手动调度会绕过该每日活动 +gate。该 lane 会构建完整套件分组 Vitest performance report，让 Codex +只进行小型、保持覆盖率的 test performance 修复，而不是大范围 +重构，然后重新运行完整套件 report，并拒绝会降低 +passing baseline test count 的变更。如果 baseline 存在 failing test，Codex 只能修复 +明显失败，并且 after-agent full-suite report 必须通过后 +才会提交任何内容。当 `main` 在 bot push 落地前前移时，该 lane +会 rebase 已验证的 patch，重新运行 `pnpm check:changed`，并重试 push； +有冲突的 stale patch 会被跳过。它使用 GitHub-hosted Ubuntu，因此 Codex +action 可以保持与 docs agent 相同的 drop-sudo 安全姿态。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -130,46 +237,32 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## 作业概览 +## Job 概览 -| 作业 | 目的 | 运行时机 | +| 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测仅文档变更、变更范围、变更的插件，并构建 CI 清单 | 始终在非草稿推送和 PR 上运行 | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿推送和 PR 上运行 | -| `security-dependency-audit` | 针对 npm 安全公告执行无依赖的生产 lockfile 审计 | 始终在非草稿推送和 PR 上运行 | -| `security-fast` | 快速安全作业的必需聚合检查 | 始终在非草稿推送和 PR 上运行 | -| `build-artifacts` | 构建 `dist/`、控制 UI、构建产物检查，以及可复用的下游产物 | Node 相关变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/插件契约/协议检查 | Node 相关变更 | -| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | Node 相关变更 | -| `checks-node-core-test` | 核心 Node 测试分片，排除渠道、内置、契约和插件通道 | Node 相关变更 | -| `check` | 分片的主要本地门禁等价项：生产类型、lint、守卫、测试类型和严格烟雾测试 | Node 相关变更 | -| `check-additional` | 架构、边界、插件表面守卫、包边界和 gateway-watch 分片 | Node 相关变更 | -| `build-smoke` | 已构建 CLI 的烟雾测试和启动内存烟雾测试 | Node 相关变更 | -| `checks` | 构建产物渠道测试的验证器 | Node 相关变更 | -| `checks-node-compat-node22` | Node 22 兼容性构建和烟雾测试通道 | 发布的手动 CI 调度 | -| `check-docs` | 文档格式、lint 和断链检查 | 文档已变更 | -| `skills-python` | 针对由 Python 支持的 Skills 执行 Ruff + pytest | Python Skills 相关变更 | -| `checks-windows` | Windows 特定的进程/路径测试，以及共享运行时导入说明符回归测试 | Windows 相关变更 | -| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | macOS 相关变更 | -| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 | -| `android` | 两个 flavor 的 Android 单元测试，以及一次 debug APK 构建 | Android 相关变更 | -| `test-performance-agent` | 可信活动后的每日 Codex 慢速测试优化 | 主 CI 成功或手动调度 | +| `preflight` | 检测仅文档变更、已变更范围、已变更插件，并构建 CI 清单 | 始终在非草稿 push 和 PR 上运行 | +| `security-scm-fast` | 私钥检测，以及通过 `zizmor` 进行 workflow 审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-dependency-audit` | 针对 npm 安全公告，对生产锁文件执行无需依赖的审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-fast` | 快速安全作业的必需汇总 | 始终在非草稿 push 和 PR 上运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游产物 | 与 Node 相关的变更 | +| `checks-fast-core` | 快速 Linux 正确性通道，例如内置插件、插件契约和协议检查 | 与 Node 相关的变更 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的汇总检查结果 | 与 Node 相关的变更 | +| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和插件通道 | 与 Node 相关的变更 | +| `check` | 分片的主本地门禁等价项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 | +| `check-additional` | 架构、边界、插件表面守卫、包边界和 gateway-watch 分片 | 与 Node 相关的变更 | +| `build-smoke` | 已构建 CLI smoke 测试和启动内存 smoke | 与 Node 相关的变更 | +| `checks` | 已构建产物渠道测试的验证器 | 与 Node 相关的变更 | +| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 通道 | 发布时手动 CI 调度 | +| `check-docs` | 文档格式、lint 和断链检查 | 文档已变更 | +| `skills-python` | 针对 Python 支持的 Skills 运行 Ruff + pytest | 与 Python Skills 相关的变更 | +| `checks-windows` | Windows 特定进程/路径测试，以及共享运行时 import specifier 回归检查 | 与 Windows 相关的变更 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | +| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | +| `android` | 两种 flavor 的 Android 单元测试，加一次 debug APK 构建 | 与 Android 相关的变更 | +| `test-performance-agent` | 可信活动后的每日 Codex 慢测试优化 | 主 CI 成功或手动调度 | -手动 CI 调度运行与正常 CI 相同的作业图，但会强制启用每个 -非 Android 范围通道：Linux Node 分片、内置插件分片、渠道 -契约、Node 22 兼容性、`check`、`check-additional`、构建烟雾测试、文档 -检查、Python Skills、Windows、macOS 和控制 UI i18n。独立的手动 CI -调度仅在 `include_android=true` 时运行 Android；完整发布 -总控通过传入 `include_android=true` 启用 Android。插件预发布 -静态检查、仅发布的 `agentic-plugins` 分片、完整插件 -批量扫描，以及插件预发布 Docker 通道都排除在 CI 之外。Docker -预发布套件仅在 `Full Release Validation` 调度 -单独的 `Plugin Prerelease` 工作流且启用发布验证门禁时运行。 -手动运行使用 -唯一并发组，因此候选发布完整套件不会被 -同一 ref 上的另一次推送或 PR 运行取消。可选的 `target_ref` 输入允许 -可信调用方在某个分支、标签或完整提交 SHA 上运行该作业图，同时 -使用所选调度 ref 中的工作流文件。 +手动 CI 调度运行与普通 CI 相同的作业图，但强制启用所有非 Android 作用域通道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建 smoke、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立手动 CI 调度仅在 `include_android=true` 时运行 Android；完整发布总入口通过传入 `include_android=true` 启用 Android。插件预发布静态检查、仅发布的 `agentic-plugins` 分片、完整插件批量扫描，以及插件预发布 Docker 通道均排除在 CI 之外。Docker 预发布套件仅在 `Full Release Validation` 调度单独的 `Plugin Prerelease` workflow，并启用发布验证门禁时运行。手动运行使用唯一的并发组，因此发布候选完整套件不会被同一 ref 上的另一次 push 或 PR 运行取消。可选的 `target_ref` 输入允许受信任调用方在使用所选调度 ref 中 workflow 文件的同时，针对分支、标签或完整 commit SHA 运行该图。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -179,55 +272,47 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## 快速失败顺序 -作业按顺序排列，让低成本检查在高成本检查运行前先失败： +作业按顺序排列，让低成本检查先于高成本检查失败： -1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是此作业内部的步骤，而不是独立作业。 +1. `preflight` 决定到底存在哪些通道。`docs-scope` 和 `changed-scope` 逻辑是此作业内的步骤，不是独立作业。 2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而无需等待更重的产物和平台矩阵作业。 -3. `build-artifacts` 与快速 Linux 通道重叠运行，这样下游消费者可在共享构建就绪后立即开始。 -4. 更重的平台和运行时通道随后扇出：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +3. `build-artifacts` 与快速 Linux 通道重叠运行，因此下游消费者可以在共享构建就绪后立即开始。 +4. 更重的平台和运行时通道随后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 -手动触发会跳过变更范围检测，并让预检清单 -表现得像每个受范围限定的区域都发生了变更。 -CI 工作流编辑会验证 Node CI 图和工作流 lint，但它们本身不会强制执行 Windows、Android 或 macOS 原生构建；这些平台通道仍然只针对平台源码变更。 -仅 CI 路由编辑、选定的低成本核心测试夹具编辑，以及窄范围的插件契约辅助/测试路由编辑会使用快速的仅 Node 清单路径：预检、安全检查和一个 `checks-fast-core` 任务。该路径会在变更文件仅限于该快速任务直接覆盖的路由或辅助表面时，避开构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外的防护矩阵。 -Windows Node 检查的范围限定于 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助、包管理器配置，以及执行该通道的 CI 工作流表面；无关源码、插件、安装冒烟和仅测试变更会保留在 Linux Node 通道上，因此它们不会为正常测试分片已经覆盖的内容占用 16-vCPU Windows worker。 -单独的 `install-smoke` 工作流通过自己的 `preflight` job 复用同一个范围脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。拉取请求会针对 Docker/package 表面、内置插件 package/manifest 变更，以及 Docker 冒烟 job 覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete 共享工作区 CLI 冒烟，运行容器 gateway-network e2e，验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker 配置文件，同时单独限制每个场景的 Docker 运行。完整路径会保留 QR package 安装和安装器 Docker/update 覆盖，用于夜间计划运行、手动触发、workflow-call 发布检查，以及真正触及安装器/package/Docker 表面的拉取请求。`main` 推送（包括 merge commit）不会强制运行完整路径；当变更范围逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟，并将完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独控制；它会在夜间计划和发布检查工作流中运行，手动 `install-smoke` 触发可以选择启用它，但拉取请求和 `main` 推送不会运行它。QR 和安装器 Docker 测试会保留它们各自专注安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/update/plugin-dependency 通道的裸 Node/Git runner，以及一个会将同一个 tarball 安装到 `/app`、用于普通功能通道的功能镜像。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，runner 只执行选定的计划。调度器使用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个通道选择镜像，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行通道；用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认 main-pool slot 数 10，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整 provider 敏感的 tail-pool slot 数 10。重型通道上限默认为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，因此 npm install 和多服务通道不会让 Docker 过载，而较轻的通道仍会填满可用 slot。单个比有效上限更重的通道仍可从空池启动，然后单独运行直到释放容量。默认情况下，通道启动会错开 2 秒，以避免本地 Docker daemon create 风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker，移除陈旧的 OpenClaw E2E 容器，输出活动通道 Status，持久化通道耗时以便按最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于调度器检查。默认情况下，它会在第一次失败后停止调度新的池化通道，并且每个通道都有一个 120 分钟回退超时，可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 通道使用更严格的按通道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器通道，包括仅发布通道（如 `install-e2e`）和拆分的内置更新通道（如 `bundled-channel-update-acpx`），同时跳过清理冒烟，以便智能体可以复现某个失败通道。可复用的 live/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些 package、镜像类型、live 镜像、通道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 会把该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，下载当前运行的 package artifact，或从 `package_artifact_run_id` 下载 package artifact；验证 tarball 清单；当计划需要 package-installed 通道时，通过 Blacksmith 的 Docker layer cache 构建并推送按 package 摘要标记的 bare/functional GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有的 package 摘要镜像，而不是重新构建。Docker 镜像拉取会用有界的每次尝试 180 秒超时进行重试，因此卡住的 registry/cache stream 会快速重试，而不是消耗 CI 关键路径的大部分时间。`Package Acceptance` 工作流是高级 package gate：它会从 npm、受信任的 `package_ref`、HTTPS tarball 加 SHA-256，或先前的工作流 artifact 解析候选项，然后将这个单一的 `package-under-test` artifact 传入可复用的 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分开，因此当前验收逻辑可以验证较旧的受信任 commit，而无需检出旧的工作流代码。发布检查会针对目标 ref 运行自定义 Package Acceptance 增量：内置渠道兼容、离线插件夹具，以及针对解析出的 tarball 的 Telegram package QA。发布路径 Docker 套件会运行更小的分块 job，并使用 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取所需的镜像类型，并通过同一个加权调度器执行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|plugins-runtime-install-e|plugins-runtime-install-f|plugins-runtime-install-g|plugins-runtime-install-h|bundled-channels`）。当完整 release-path 覆盖请求 OpenWebUI 时，它会并入 `plugins-runtime-services`，并且只为仅 OpenWebUI 的触发保留独立的 `openwebui` 分块。旧的聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布工作流使用拆分分块，因此安装器 E2E 和内置插件安装/卸载扫测不会主导关键路径。`install-e2e` 通道别名仍然是两个 provider 安装器通道的聚合手动重跑别名。`bundled-channels` 分块会运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 通道，而不是串行的一体化 `bundled-channel-deps` 通道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表，以及每通道重跑命令。工作流 `docker_lanes` 输入会针对准备好的镜像运行选定通道，而不是运行分块 job，这会将失败通道调试限制在一个目标 Docker job 内，并为该次运行准备、下载或复用 package artifact；如果选定通道是 live Docker 通道，目标 job 会为该次重跑在本地构建 live-test 镜像。生成的每通道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败通道可以复用失败运行中的精确 package 和镜像。使用 `pnpm test:docker:rerun ` 从 GitHub 运行下载 Docker artifact，并打印组合/每通道目标重跑命令；使用 `pnpm test:docker:timings ` 查看慢通道和阶段关键路径摘要。计划的 live/E2E 工作流每天运行完整 release-path Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 Doctor repair 过程可以与其他内置检查分片并行。 +作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 +手动派发会跳过变更作用域检测，并让预检清单表现得像每个作用域区域都发生了变更。 +CI 工作流编辑会验证 Node CI 图和工作流 lint，但不会单独强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然只限定在平台源代码变更时运行。 +仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及范围很窄的插件契约辅助程序/测试路由编辑，会使用快速的仅 Node 清单路径：预检、安全检查，以及单个 `checks-fast-core` 任务。该路径会避开构建产物、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片，以及额外的守护矩阵；前提是变更文件仅限于该快速任务会直接执行的路由或辅助程序表面。 +Windows Node 检查限定于 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助程序、包管理器配置，以及执行该通道的 CI 工作流表面；无关的源代码、插件、安装冒烟和仅测试变更会留在 Linux Node 通道上，因此不会为普通测试分片已经覆盖的内容占用一个 16-vCPU Windows worker。 +独立的 `install-smoke` 工作流通过自己的 `preflight` job 复用同一个作用域脚本。它把冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。拉取请求会针对 Docker/包表面、内置插件包/清单变更，以及 Docker 冒烟 job 会执行的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete 共享工作区 CLI 冒烟，运行容器 gateway-network e2e，验证内置扩展构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker profile，同时每个场景的 Docker run 会单独设上限。完整路径会把 QR 包安装和安装器 Docker/update 覆盖保留给夜间定时运行、手动派发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的拉取请求。在完整模式下，install-smoke 会准备或复用一个目标 SHA 的 GHCR 根 Dockerfile 冒烟镜像，然后把 QR 包安装、根 Dockerfile/Gateway 网关冒烟、安装器/update 冒烟，以及快速内置插件 Docker E2E 作为独立 job 运行，这样安装器工作不必等待根镜像冒烟完成。`main` 推送，包括合并提交，不会强制完整路径；当变更作用域逻辑会在推送上请求完整覆盖时，工作流会保留快速 Docker 冒烟，并把完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独控制；它会在夜间计划和发布检查工作流中运行，手动 `install-smoke` 派发也可以选择加入，但拉取请求和 `main` 推送不会运行它。QR 和安装器 Docker 测试保留自己的安装聚焦 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/update/plugin-dependency 通道的裸 Node/Git 运行器，以及一个会把同一个 tarball 安装到 `/app` 的功能镜像，用于普通功能通道。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行选定的计划。调度器会通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个通道选择镜像，然后用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行通道；使用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认 10 个槽位的主池数量，并使用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整默认 10 个槽位的提供商敏感尾池数量。重型通道上限默认是 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，因此 npm install 和多服务通道不会让 Docker 超额提交，而较轻的通道仍会填满可用槽位。单个比有效上限更重的通道仍可从空池启动，然后独占运行，直到释放容量。通道启动默认错开 2 秒，以避免本地 Docker daemon 创建风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker、移除陈旧的 OpenClaw E2E 容器、输出活动通道状态、持久化通道耗时以进行最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 来检查调度器。默认情况下，它会在第一次失败后停止调度新的池化通道，并且每个通道都有一个可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖的 120 分钟后备超时；选定的 live/tail 通道会使用更严格的逐通道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器通道，包括 `install-e2e` 等仅发布通道，以及 `bundled-channel-update-acpx` 等拆分的内置 update 通道，同时跳过清理冒烟，以便智能体复现某个失败通道。可复用的 live/E2E 工作流会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些包、镜像类型、live 镜像、通道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 会把该计划转换成 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，下载当前运行的包产物，或从 `package_artifact_run_id` 下载包产物；验证 tarball 清单；当计划需要已安装包的通道时，通过 Blacksmith 的 Docker 层缓存构建并推送带包摘要标签的裸/功能 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有包摘要镜像，而不是重新构建。Docker 镜像拉取会用有界的每次尝试 180 秒超时进行重试，因此卡住的 registry/cache 流会快速重试，而不是消耗 CI 关键路径的大部分时间。`Package Acceptance` 工作流是高层包门禁：它会从 npm、受信任的 `package_ref`、HTTPS tarball 加 SHA-256，或先前工作流产物中解析候选包，然后把单个 `package-under-test` 产物传入可复用的 Docker E2E 工作流。它把 `workflow_ref` 与 `package_ref` 分开，因此当前验收逻辑可以验证较早的受信任提交，而不必检出旧的工作流代码。发布检查会为目标 ref 运行自定义 Package Acceptance 增量：内置渠道兼容性、离线插件 fixture，以及针对解析出的 tarball 的 Telegram 包 QA。发布路径 Docker 套件会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行更小的分块 job，因此每个分块只拉取自己需要的镜像类型，并通过同一个加权调度器执行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|plugins-runtime-install-e|plugins-runtime-install-f|plugins-runtime-install-g|plugins-runtime-install-h|bundled-channels`）。当完整 release-path 覆盖请求 OpenWebUI 时，OpenWebUI 会并入 `plugins-runtime-services`，并且只为仅 OpenWebUI 的派发保留独立的 `openwebui` 分块。旧的聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布工作流使用拆分分块，这样安装器 E2E 和内置插件安装/卸载扫描不会主导关键路径。`install-e2e` 通道别名仍然是两个提供商安装器通道的聚合手动重跑别名。`bundled-channels` 分块会运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 通道，而不是串行的一体化 `bundled-channel-deps` 通道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表，以及逐通道重跑命令。工作流 `docker_lanes` 输入会针对准备好的镜像运行选定通道，而不是运行分块 job，这会把失败通道调试限定在一个有针对性的 Docker job 内，并为该运行准备、下载或复用包产物；如果选定通道是 live Docker 通道，目标 job 会为该次重跑在本地构建 live-test 镜像。生成的逐通道 GitHub 重跑命令会在存在这些值时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败通道可以复用失败运行中的精确包和镜像。使用 `pnpm test:docker:rerun ` 可从 GitHub 运行下载 Docker 产物，并打印合并/逐通道目标重跑命令；使用 `pnpm test:docker:timings ` 可查看慢通道和阶段关键路径摘要。定时 live/E2E 工作流每天运行完整 release-path Docker 套件。内置 update 矩阵按 update 目标拆分，因此重复 npm update 和 Doctor 修复流程可以与其他内置检查分片并行。 -当前发布 Docker 分块是 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合 `bundled-channels` 分块仍可用于手动一次性重跑，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 也仍作为聚合插件/运行时别名保留，但发布工作流使用拆分分块，因此渠道冒烟、更新目标、插件运行时检查，以及内置插件安装/卸载扫测可以并行运行。目标 `docker_lanes` 触发也会在一个共享 package/镜像准备步骤后，将多个选定通道拆分为并行 job，并且内置渠道更新通道会针对短暂 npm 网络失败重试一次。 +当前发布 Docker 分块为 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合 `bundled-channels` 分块仍可用于手动一次性重跑，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 也仍是聚合插件/运行时别名，但发布工作流使用拆分分块，这样渠道冒烟、update 目标、插件运行时检查，以及内置插件安装/卸载扫描可以并行运行。目标 `docker_lanes` 派发也会在一个共享包/镜像准备步骤之后，把多个选定通道拆分成并行 job，并且内置渠道 update 通道会针对临时 npm 网络失败重试一次。 -本地变更通道逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地检查 gate 在架构边界方面比宽泛的 CI 平台范围更严格：核心生产变更会运行核心生产和核心测试 typecheck，以及核心 lint/guard；仅核心测试变更只运行核心测试 typecheck 加核心 lint；扩展生产变更会运行扩展生产和扩展测试 typecheck，以及扩展 lint；仅扩展测试变更会运行扩展测试 typecheck 加扩展 lint。公共插件 SDK 或插件契约变更会扩展到扩展 typecheck，因为扩展依赖这些核心契约，但 Vitest 扩展扫测是显式测试工作。仅发布元数据版本 bump 会运行目标版本/配置/根依赖检查。未知根/配置变更会安全失败到所有检查通道。 -本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且 -有意比 `check:changed` 更低成本：直接测试编辑会运行自身， -源码编辑优先使用显式映射，然后是同级测试和导入图 -依赖项。共享 group-room delivery 配置是显式映射之一： -对 group visible-reply 配置、源码 reply delivery mode，或 -message-tool 系统提示的变更会路由到核心 reply 测试以及 Discord 和 -Slack delivery 回归，因此共享默认值变更会在第一次 PR -推送前失败。只有当变更足够影响整个 harness，导致低成本映射集不能作为可靠代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 +本地变更通道逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地检查门禁对架构边界的要求比宽泛的 CI 平台范围更严格：核心生产代码变更会运行核心生产代码和核心测试类型检查，以及核心 lint/防护检查；仅核心测试变更只运行核心测试类型检查和核心 lint；插件生产代码变更会运行插件生产代码和插件测试类型检查，以及插件 lint；仅插件测试变更会运行插件测试类型检查和插件 lint。公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约，但 Vitest 插件扫检属于显式测试工作。仅发布元数据的版本号变更会运行定向版本/配置/根依赖检查。未知的根目录/配置变更会故障安全地进入所有检查通道。 +本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且有意比 `check:changed` 更轻量：直接测试编辑会运行它们自身，源码编辑会优先使用显式映射，然后是同级测试和导入图依赖项。共享群组聊天室投递配置是显式映射之一：对群组可见回复配置、来源回复投递模式或消息工具系统提示词的变更，会路由到核心回复测试以及 Discord 和 Slack 投递回归测试，因此共享默认值变更会在第一次 PR 推送前失败。只有当变更范围足够覆盖整个 harness，以至于廉价映射集合不能作为可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 -对于 Testbox 验证，请从仓库根目录运行，并优先为广泛证明使用新预热的 box。在把缓慢 gate 花在一个被复用、已过期或刚报告过异常大同步的 box 上之前，先在该 box 内运行 `pnpm testbox:sanity`。当所需的根文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信副本。请停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意的大规模删除 PR，请为该次完整性检查设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。当本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后输出时，`pnpm testbox:run` 也会终止该调用。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该保护，或为异常大的本地差异使用更大的毫秒值。 +对于 Testbox 验证，请从仓库根目录运行，并优先使用新预热的 box 做宽泛证明。在把一个慢门禁花在复用过、已过期，或刚刚报告了异常大同步的 box 上之前，先在 box 内运行 `pnpm testbox:sanity`。当必需的根目录文件（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个已跟踪删除时，完整性检查会快速失败。这通常表示远程同步状态不是 PR 的可信副本。停止该 box 并预热一个新的，而不是调试产品测试失败。对于有意的大规模删除 PR，请为该次完整性检查设置 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。如果本地 Blacksmith CLI 调用停留在同步阶段超过五分钟且没有同步后输出，`pnpm testbox:run` 也会终止它。设置 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该防护，或者为异常大的本地 diff 使用更大的毫秒值。 -手动 CI 调度会运行 `checks-node-compat-node22` 作为广泛兼容性覆盖。Android 对独立手动 CI 是可选项，通过 `include_android=true` 启用，并且始终为 `Full Release Validation` 启用。`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是由 `Full Release Validation` 或显式操作员调度的独立工作流。普通拉取请求、`main` 推送和独立手动 CI 调度会保持关闭该套件。 +手动 CI 派发会运行 `checks-node-compat-node22` 作为宽泛兼容性覆盖。Android 对独立手动 CI 是可选项，通过 `include_android=true` 启用，并且在 `Full Release Validation` 中始终启用。`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个独立工作流，由 `Full Release Validation` 或显式操作者派发。普通 pull request、`main` 推送和独立手动 CI 派发都会关闭该套件。 -最慢的 Node 测试族已被拆分或均衡，以便每个作业都保持较小规模而不过度预留运行器：渠道契约以三个加权分片运行，小型核心单元 lane 会成对运行，auto-reply 以四个均衡 worker 运行并将 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，agentic Gateway 网关/插件配置会分布到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享插件兜底配置。`Plugin Prerelease` 会在八个 extension worker 之间均衡内置插件测试；这些 extension 分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node 堆，因此导入密集型插件批次不会创建额外的 CI 作业。广泛的 agents lane 使用共享 Vitest 文件并行调度器，因为它主要受导入/调度支配，而不是由单个慢测试文件主导。`runtime-config` 会与 infra core-runtime 分片一起运行，以避免共享运行时分片占据尾部耗时。include-pattern 分片使用 CI 分片名称记录 timing 条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；boundary guard 分片会在一个作业内并发运行其小型独立 guard。Gateway 网关 watch、渠道测试和 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建后，在 `build-artifacts` 内并发运行，保留它们原有的检查名称作为轻量验证作业，同时避免两个额外的 Blacksmith worker 和第二个 artifact-consumer 队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。third-party flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送上执行重复的 debug APK 打包作业。 -当同一 PR 或 `main` ref 上有更新推送落地时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。 -自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸状态无法无限期阻塞较新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 +最慢的 Node 测试族已被拆分或均衡，以便每个作业保持较小规模且不过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元通道成对运行，自动回复作为四个均衡 worker 运行，并将回复子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片；agentic Gateway 网关/插件配置分散到现有仅源码 agentic Node 作业中，而不是等待构建产物。宽泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享插件总括配置。`Plugin Prerelease` 会在八个插件 worker 之间均衡内置插件测试；这些插件分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker 和更大的 Node 堆，因此导入繁重的插件批次不会创建额外 CI 作业。宽泛 agents 通道使用共享 Vitest 文件并行调度器，因为它主要受导入/调度支配，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享 runtime 分片承担尾部耗时。包含模式分片使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将 runtime 拓扑架构与 Gateway 网关 watch 覆盖分开；边界防护分片会在一个作业内并发运行其小型独立防护检查。Gateway 网关 watch、渠道测试和核心支持边界分片在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内并发运行，保留它们原有的检查名称作为轻量验证作业，同时避免两个额外 Blacksmith worker 和第二个产物消费队列。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送上重复执行 debug APK 打包作业。 +当较新的推送落到同一个 PR 或 `main` ref 上时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也在失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被取代后继续排队。 +自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸任务不会无限期阻塞较新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 -## 运行器 +## Runners -| 运行器 | 作业 | +| Runner | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片渠道契约检查、除 lint 以外的 `check` 分片、`check-additional` 分片和聚合、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、较低权重的 extension 分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 带来的成本高于节省；install-smoke Docker 构建，其中 32-vCPU 队列时间带来的成本高于节省 | +| `ubuntu-24.04` | `preflight`，快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`），快速协议/契约/内置检查，分片渠道契约检查，除 lint 外的 `check` 分片，`check-additional` 分片和聚合，Node 测试聚合验证器，文档检查，Python Skills，workflow-sanity，labeler，auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`，较低权重的插件分片，`checks-fast-core`，`checks-node-compat-node22`，`check-prod-types` 和 `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`，build-smoke，Linux Node 测试分片，内置插件测试分片，`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 的成本高于节省；install-smoke Docker 构建，其中 32-vCPU 的排队时间成本高于节省 | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` | +| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 回退到 `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 回退到 `macos-latest` | -## 本地等效命令 +## 本地等价命令 ```bash pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD diff --git a/docs/zh-CN/cli/commitments.md b/docs/zh-CN/cli/commitments.md new file mode 100644 index 000000000..44c5bcd45 --- /dev/null +++ b/docs/zh-CN/cli/commitments.md @@ -0,0 +1,94 @@ +--- +read_when: + - 你想查看推断式跟进承诺 + - 你想要忽略待处理的签到 + - 你正在审计 Heartbeat 可能会传递的内容 +summary: '`openclaw commitments` 的 CLI 参考（查看并忽略推断出的跟进事项）' +title: '`openclaw commitments`' +x-i18n: + generated_at: "2026-04-29T21:37:00Z" + model: gpt-5.5 + provider: openai + source_hash: 37d5e5dca25cf649a5069360aa4e41fcc33d042dea99f643b98c07189c58f21c + source_path: cli/commitments.md + workflow: 16 +--- + +列出并管理推断式跟进承诺。 + +跟进承诺是选择启用的短期跟进记忆，由会话上下文创建。请参阅[推断式跟进承诺](/zh-CN/concepts/commitments)了解概念指南。 + +没有子命令时，`openclaw commitments` 会列出待处理的跟进承诺。 + +## 用法 + +```bash +openclaw commitments [--all] [--agent ] [--status ] [--json] +openclaw commitments list [--all] [--agent ] [--status ] [--json] +openclaw commitments dismiss [--json] +``` + +## 选项 + +- `--all`：显示所有状态，而不是只显示待处理的跟进承诺。 +- `--agent `：筛选到一个智能体 ID。 +- `--status `：按状态筛选。取值：`pending`、`sent`、`dismissed`、`snoozed` 或 `expired`。 +- `--json`：输出机器可读的 JSON。 + +## 示例 + +列出待处理的跟进承诺： + +```bash +openclaw commitments +``` + +列出所有已存储的跟进承诺： + +```bash +openclaw commitments --all +``` + +筛选到一个智能体： + +```bash +openclaw commitments --agent main +``` + +查找已推迟的跟进承诺： + +```bash +openclaw commitments --status snoozed +``` + +解除一个或多个跟进承诺： + +```bash +openclaw commitments dismiss cm_abc123 cm_def456 +``` + +导出为 JSON： + +```bash +openclaw commitments --all --json +``` + +## 输出 + +文本输出包括： + +- 跟进承诺 ID +- 状态 +- 类型 +- 最早到期时间 +- 作用域 +- 建议的跟进消息文本 + +JSON 输出还包括跟进承诺存储路径和完整的已存储记录。 + +## 相关内容 + +- [推断式跟进承诺](/zh-CN/concepts/commitments) +- [记忆概览](/zh-CN/concepts/memory) +- [Heartbeat](/zh-CN/gateway/heartbeat) +- [定时任务](/zh-CN/automation/cron-jobs) diff --git a/docs/zh-CN/cli/index.md b/docs/zh-CN/cli/index.md index 419230311..f58046698 100644 --- a/docs/zh-CN/cli/index.md +++ b/docs/zh-CN/cli/index.md @@ -3,60 +3,60 @@ read_when: - 找到合适的 `openclaw` 子命令 - 查找全局标志或输出样式规则 summary: OpenClaw CLI 索引：命令列表、全局标志，以及指向各命令页面的链接 -title: CLI 参考资料 +title: CLI 参考 x-i18n: - generated_at: "2026-04-25T08:03:59Z" - model: gpt-5.4 + generated_at: "2026-04-29T21:36:46Z" + model: gpt-5.5 provider: openai - source_hash: b8a61396b8ec7f57d15988d40b09f90458745bbb29e90bd387134aa032214853 + source_hash: 522e0f156b919946756de6b933bb0a08374507401bf8639312daf52781927f33 source_path: cli/index.md - workflow: 15 + workflow: 16 --- -`openclaw` 是主要的 CLI 入口点。每个核心命令要么有专门的参考页面，要么与其别名命令一起记录；本索引列出了命令、全局标志，以及适用于整个 CLI 的输出样式规则。 +`openclaw` 是主要的 CLI 入口点。每个核心命令都有专门的参考页面，或与其别名对应的命令一起记录；此索引列出命令、全局标志，以及适用于整个 CLI 的输出样式规则。 ## 命令页面 -| 区域 | 命令 | +| 区域 | 命令 | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 设置和新手引导 | [`crestodian`](/zh-CN/cli/crestodian) · [`setup`](/zh-CN/cli/setup) · [`onboard`](/zh-CN/cli/onboard) · [`configure`](/zh-CN/cli/configure) · [`config`](/zh-CN/cli/config) · [`completion`](/zh-CN/cli/completion) · [`doctor`](/zh-CN/cli/doctor) · [`dashboard`](/zh-CN/cli/dashboard) | -| 重置和卸载 | [`backup`](/zh-CN/cli/backup) · [`reset`](/zh-CN/cli/reset) · [`uninstall`](/zh-CN/cli/uninstall) · [`update`](/zh-CN/cli/update) | -| 消息和智能体 | [`message`](/zh-CN/cli/message) · [`agent`](/zh-CN/cli/agent) · [`agents`](/zh-CN/cli/agents) · [`acp`](/zh-CN/cli/acp) · [`mcp`](/zh-CN/cli/mcp) | -| 健康状态和会话 | [`status`](/zh-CN/cli/status) · [`health`](/zh-CN/cli/health) · [`sessions`](/zh-CN/cli/sessions) | -| Gateway 网关和日志 | [`gateway`](/zh-CN/cli/gateway) · [`logs`](/zh-CN/cli/logs) · [`system`](/zh-CN/cli/system) | -| 模型和推理 | [`models`](/zh-CN/cli/models) · [`infer`](/zh-CN/cli/infer) · `capability`（[`infer`](/zh-CN/cli/infer) 的别名） · [`memory`](/zh-CN/cli/memory) · [`wiki`](/zh-CN/cli/wiki) | -| 网络和节点 | [`directory`](/zh-CN/cli/directory) · [`nodes`](/zh-CN/cli/nodes) · [`devices`](/zh-CN/cli/devices) · [`node`](/zh-CN/cli/node) | -| 运行时和沙箱 | [`approvals`](/zh-CN/cli/approvals) · `exec-policy`（见 [`approvals`](/zh-CN/cli/approvals)） · [`sandbox`](/zh-CN/cli/sandbox) · [`tui`](/zh-CN/cli/tui) · `chat`/`terminal`（[`tui --local`](/zh-CN/cli/tui) 的别名） · [`browser`](/zh-CN/cli/browser) | -| 自动化 | [`cron`](/zh-CN/cli/cron) · [`tasks`](/zh-CN/cli/tasks) · [`hooks`](/zh-CN/cli/hooks) · [`webhooks`](/zh-CN/cli/webhooks) | -| 设备发现和文档 | [`dns`](/zh-CN/cli/dns) · [`docs`](/zh-CN/cli/docs) | -| 配对和渠道 | [`pairing`](/zh-CN/cli/pairing) · [`qr`](/zh-CN/cli/qr) · [`channels`](/zh-CN/cli/channels) | -| 安全和插件 | [`security`](/zh-CN/cli/security) · [`secrets`](/zh-CN/cli/secrets) · [`skills`](/zh-CN/cli/skills) · [`plugins`](/zh-CN/cli/plugins) · [`proxy`](/zh-CN/cli/proxy) | -| 旧版别名 | [`daemon`](/zh-CN/cli/daemon)（Gateway 网关服务） · [`clawbot`](/zh-CN/cli/clawbot)（命名空间） | -| 插件（可选） | [`voicecall`](/zh-CN/cli/voicecall)（如果已安装） | +| 重置和卸载 | [`backup`](/zh-CN/cli/backup) · [`reset`](/zh-CN/cli/reset) · [`uninstall`](/zh-CN/cli/uninstall) · [`update`](/zh-CN/cli/update) | +| 消息和智能体 | [`message`](/zh-CN/cli/message) · [`agent`](/zh-CN/cli/agent) · [`agents`](/zh-CN/cli/agents) · [`acp`](/zh-CN/cli/acp) · [`mcp`](/zh-CN/cli/mcp) | +| 健康状态和会话 | [`status`](/zh-CN/cli/status) · [`health`](/zh-CN/cli/health) · [`sessions`](/zh-CN/cli/sessions) | +| Gateway 网关和日志 | [`gateway`](/zh-CN/cli/gateway) · [`logs`](/zh-CN/cli/logs) · [`system`](/zh-CN/cli/system) | +| 模型和推理 | [`models`](/zh-CN/cli/models) · [`infer`](/zh-CN/cli/infer) · `capability`（[`infer`](/zh-CN/cli/infer) 的别名） · [`memory`](/zh-CN/cli/memory) · [`commitments`](/zh-CN/cli/commitments) · [`wiki`](/zh-CN/cli/wiki) | +| 网络和节点 | [`directory`](/zh-CN/cli/directory) · [`nodes`](/zh-CN/cli/nodes) · [`devices`](/zh-CN/cli/devices) · [`node`](/zh-CN/cli/node) | +| 运行时和沙箱 | [`approvals`](/zh-CN/cli/approvals) · `exec-policy`（见 [`approvals`](/zh-CN/cli/approvals)） · [`sandbox`](/zh-CN/cli/sandbox) · [`tui`](/zh-CN/cli/tui) · `chat`/`terminal`（[`tui --local`](/zh-CN/cli/tui) 的别名） · [`browser`](/zh-CN/cli/browser) | +| 自动化 | [`cron`](/zh-CN/cli/cron) · [`tasks`](/zh-CN/cli/tasks) · [`hooks`](/zh-CN/cli/hooks) · [`webhooks`](/zh-CN/cli/webhooks) | +| 设备发现和文档 | [`dns`](/zh-CN/cli/dns) · [`docs`](/zh-CN/cli/docs) | +| 配对和渠道 | [`pairing`](/zh-CN/cli/pairing) · [`qr`](/zh-CN/cli/qr) · [`channels`](/zh-CN/cli/channels) | +| 安全和插件 | [`security`](/zh-CN/cli/security) · [`secrets`](/zh-CN/cli/secrets) · [`skills`](/zh-CN/cli/skills) · [`plugins`](/zh-CN/cli/plugins) · [`proxy`](/zh-CN/cli/proxy) | +| 旧版别名 | [`daemon`](/zh-CN/cli/daemon)（Gateway 网关服务） · [`clawbot`](/zh-CN/cli/clawbot)（命名空间） | +| 插件（可选） | [`voicecall`](/zh-CN/cli/voicecall)（如果已安装） | ## 全局标志 -| 标志 | 用途 | +| 标志 | 用途 | | ----------------------- | --------------------------------------------------------------------- | -| `--dev` | 将状态隔离在 `~/.openclaw-dev` 下，并切换默认端口 | -| `--profile ` | 将状态隔离在 `~/.openclaw-` 下 | -| `--container ` | 将执行目标指定为某个已命名容器 | -| `--no-color` | 禁用 ANSI 颜色（也支持 `NO_COLOR=1`） | -| `--update` | [`openclaw update`](/zh-CN/cli/update) 的简写形式（仅适用于源码安装） | -| `-V`, `--version`, `-v` | 打印版本并退出 | +| `--dev` | 将状态隔离在 `~/.openclaw-dev` 下并偏移默认端口 | +| `--profile ` | 将状态隔离在 `~/.openclaw-` 下 | +| `--container ` | 指定用于执行的命名容器 | +| `--no-color` | 禁用 ANSI 颜色（也会遵循 `NO_COLOR=1`） | +| `--update` | [`openclaw update`](/zh-CN/cli/update) 的简写（仅适用于源码安装） | +| `-V`, `--version`, `-v` | 打印版本并退出 | ## 输出模式 - ANSI 颜色和进度指示器仅在 TTY 会话中渲染。 -- OSC-8 超链接会在支持时渲染为可点击链接；否则 CLI 会回退为普通 URL。 -- `--json`（以及在支持时的 `--plain`）会禁用样式，以获得干净的输出。 -- 长时间运行的命令会显示进度指示器（在支持时使用 OSC 9;4）。 +- 在受支持的位置，OSC-8 超链接会渲染为可点击链接；否则 CLI 会回退为纯 URL。 +- `--json`（以及受支持位置的 `--plain`）会禁用样式，以便输出干净内容。 +- 长时间运行的命令会显示进度指示器（受支持时使用 OSC 9;4）。 -调色板的唯一可信来源：`src/terminal/palette.ts`。 +调色板事实来源：`src/terminal/palette.ts`。 ## 命令树 - + ``` openclaw [--dev] [--profile ] @@ -124,6 +124,9 @@ openclaw [--dev] [--profile ] status index search + commitments + list + dismiss wiki status doctor @@ -350,26 +353,26 @@ openclaw [--dev] [--profile ] terminal (alias: tui --local) ``` -插件可以添加额外的顶级命令（例如 `openclaw voicecall`）。 +插件可以添加额外的顶层命令（例如 `openclaw voicecall`）。 ## 聊天斜杠命令 -聊天消息支持 `/...` 命令。请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。 +聊天消息支持 `/...` 命令。参见[斜杠命令](/zh-CN/tools/slash-commands)。 -重点包括： +要点： - `/status` — 快速诊断。 -- `/trace` — 会话范围内的插件追踪/调试行。 +- `/trace` — 会话范围的插件跟踪/调试行。 - `/config` — 持久化的配置更改。 -- `/debug` — 仅运行时的配置覆盖（保存在内存中，不写入磁盘；需要 `commands.debug: true`）。 +- `/debug` — 仅运行时的配置覆盖（内存中，不写入磁盘；需要 `commands.debug: true`）。 ## 用量跟踪 -当 OAuth/API 凭证可用时，`openclaw status --usage` 和 Control UI 会显示提供商的用量/配额。数据直接来自提供商的用量端点，并被标准化为 `X% left`。当前支持用量窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi 和 z.ai。 +当 OAuth/API 凭证可用时，`openclaw status --usage` 和 Control UI 会显示提供商用量/配额。数据直接来自提供商用量端点，并归一化为 `X% left`。当前具有用量窗口的提供商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi 和 z.ai。 -详见 [用量跟踪](/zh-CN/concepts/usage-tracking)。 +详情参见[用量跟踪](/zh-CN/concepts/usage-tracking)。 ## 相关内容 diff --git a/docs/zh-CN/concepts/commitments.md b/docs/zh-CN/concepts/commitments.md new file mode 100644 index 000000000..c7093d67d --- /dev/null +++ b/docs/zh-CN/concepts/commitments.md @@ -0,0 +1,147 @@ +--- +read_when: + - 你希望 OpenClaw 记住自然的后续跟进 + - 你想了解推断式跟进与提醒有何不同 + - 你想查看或忽略跟进承诺 +sidebarTitle: Commitments +summary: 用于并非精确提醒的回访的推断式跟进记忆 +title: 推断式跟进承诺 +x-i18n: + generated_at: "2026-04-29T21:36:56Z" + model: gpt-5.5 + provider: openai + source_hash: 3f51af0ac2c9841258fbeeb8f2f98dba6f438b8e0c9433f601a0504d6ef27111 + source_path: concepts/commitments.md + workflow: 16 +--- + +跟进承诺是短期存在的后续跟进记忆。启用后，OpenClaw 可以 +注意到某段对话创造了未来回访的机会，并记住稍后再提起。 + +示例： + +- 你提到明天有面试。OpenClaw 可能会在之后回访。 +- 你说自己很疲惫。OpenClaw 可能会稍后询问你是否睡过了。 +- 智能体说它会在某件事变化后跟进。OpenClaw 可能会跟踪这个 + 未闭合的循环。 + +跟进承诺不是像 `MEMORY.md` 那样的持久事实，也不是精确的 +提醒。它位于记忆和自动化之间：OpenClaw 记住一个绑定到 +对话的义务，然后由 Heartbeat 在到期时投递。 + +## 启用跟进承诺 + +跟进承诺默认关闭。请在配置中启用： + +```bash +openclaw config set commitments.enabled true +openclaw config set commitments.maxPerDay 3 +``` + +等效的 `openclaw.json`： + +```json +{ + "commitments": { + "enabled": true, + "maxPerDay": 3 + } +} +``` + +`commitments.maxPerDay` 限制在一个滚动日内，每个智能体会话可以投递 +多少个推断式后续跟进。默认值为 `3`。 + +## 工作原理 + +智能体回复后，OpenClaw 可能会在单独的上下文中运行一次隐藏的后台 +提取过程。该过程只查找推断式后续跟进承诺。它不会写入可见对话， +也不会要求主智能体对提取进行推理。 + +当它找到高置信度候选项时，OpenClaw 会存储一条跟进承诺，其中包含： + +- 智能体 ID +- 会话键 +- 原始渠道和投递目标 +- 到期时间窗口 +- 简短的建议回访 +- 足够的来源上下文，供 Heartbeat 判断是否发送 + +投递通过 Heartbeat 进行。当跟进承诺到期时，Heartbeat 会把该跟进承诺 +加入同一智能体和渠道范围内的 Heartbeat 回合。模型可以发送一条自然的 +回访，也可以回复 `HEARTBEAT_OK` 将其忽略。 + +OpenClaw 绝不会在写入推断式跟进承诺后立即投递。到期时间会被限制为 +至少晚于创建时间一个 Heartbeat 间隔，因此后续跟进不会在刚被推断出的 +同一刻回显回来。 + +## 范围 + +跟进承诺限定在创建它们时的确切智能体和渠道上下文内。在 Discord 中与 +一个智能体交谈时推断出的后续跟进，不会由另一个智能体、另一个渠道或 +无关会话投递。 + +这种范围限定是该功能的一部分。自然回访应该像是同一段对话的延续， +而不是一个全局提醒系统。 + +## 跟进承诺与提醒 + +| 需求 | 使用 | +| ----------------------------------------------- | ---------------------------------------- | +| “下午 3 点提醒我” | [定时任务](/zh-CN/automation/cron-jobs) | +| “20 分钟后提醒我” | [定时任务](/zh-CN/automation/cron-jobs) | +| “每个工作日运行这份报告” | [定时任务](/zh-CN/automation/cron-jobs) | +| “我明天有面试” | 跟进承诺 | +| “我整晚没睡” | 跟进承诺 | +| “如果我没有回复这个未处理的话题，请跟进” | 跟进承诺 | + +精确的用户请求已经属于调度器路径。跟进承诺只用于推断式后续跟进： +也就是用户没有要求提醒，但对话明确创造了一个有用的未来回访时机。 + +## 管理跟进承诺 + +使用 CLI 检查和清除已存储的跟进承诺： + +```bash +openclaw commitments +openclaw commitments --all +openclaw commitments --agent main +openclaw commitments --status snoozed +openclaw commitments dismiss cm_abc123 +``` + +请参阅 [`openclaw commitments`](/zh-CN/cli/commitments) 获取命令参考。 + +## 隐私和成本 + +跟进承诺提取会使用一次 LLM 过程，因此启用它会在符合条件的回合之后 +增加后台模型用量。该过程对用户可见的对话是隐藏的，但它可以读取最近 +的交流内容，以判断是否存在后续跟进。 + +已存储的跟进承诺是 OpenClaw 本地状态。它们是操作性记忆，而不是长期 +记忆。使用以下命令停用该功能： + +```bash +openclaw config set commitments.enabled false +``` + +## 故障排除 + +如果预期的后续跟进没有出现： + +- 确认 `commitments.enabled` 为 `true`。 +- 检查 `openclaw commitments --all` 中是否有待处理、已忽略、已稍后提醒或已过期的 + 记录。 +- 确保该智能体的 Heartbeat 正在运行。 +- 检查该智能体会话是否已经达到 `commitments.maxPerDay`。 +- 记住，精确提醒会被跟进承诺提取跳过，并且应改为出现在 + [定时任务](/zh-CN/automation/cron-jobs) 下。 + +## 相关内容 + +- [记忆概览](/zh-CN/concepts/memory) +- [主动记忆](/zh-CN/concepts/active-memory) +- [Heartbeat](/zh-CN/gateway/heartbeat) +- [定时任务](/zh-CN/automation/cron-jobs) +- [`openclaw commitments`](/zh-CN/cli/commitments) +- [配置参考](/zh-CN/gateway/configuration-reference#commitments) diff --git a/docs/zh-CN/concepts/memory.md b/docs/zh-CN/concepts/memory.md index 8645ac450..83553cff5 100644 --- a/docs/zh-CN/concepts/memory.md +++ b/docs/zh-CN/concepts/memory.md @@ -1,14 +1,14 @@ --- read_when: - - 你想了解记忆的工作原理 + - 你想了解记忆是如何工作的 - 你想知道要写入哪些记忆文件 -summary: OpenClaw 如何跨会话记住信息 +summary: OpenClaw 如何跨会话记住内容 title: 记忆概览 x-i18n: - generated_at: "2026-04-28T11:49:17Z" + generated_at: "2026-04-29T21:36:43Z" model: gpt-5.5 provider: openai - source_hash: 5495270d96c72de525ff3d285b122eb2b86137c741e3042f067b7adc55eb51f0 + source_hash: ecf6cf2c95ce3ee78d62923e795f16957088f0eb6620ed50647cff05b99bd572 source_path: concepts/memory.md workflow: 16 --- @@ -19,66 +19,72 @@ OpenClaw 通过在你的智能体工作区中写入**纯 Markdown 文件**来记 你的智能体有三个与记忆相关的文件： -- **`MEMORY.md`** — 长期记忆。持久化事实、偏好和决策。会在每个私信会话开始时加载。 +- **`MEMORY.md`** — 长期记忆。持久的事实、偏好和决策。会在每个私信会话开始时加载。 - **`memory/YYYY-MM-DD.md`** — 每日笔记。持续记录的上下文和观察。今天和昨天的笔记会自动加载。 - **`DREAMS.md`**（可选）— Dream Diary 和 Dreaming 扫描摘要，供人工审阅，包括有依据的历史回填条目。 这些文件位于智能体工作区中（默认 `~/.openclaw/workspace`）。 -如果你希望智能体记住某件事，直接告诉它：“记住我偏好 TypeScript。”它会把内容写入合适的文件。 +如果你希望智能体记住某件事，直接告诉它即可：“记住我偏好 TypeScript。” 它会把内容写入适当的文件。 +## 推断式跟进承诺 + +有些未来跟进并不是持久事实。如果你提到明天有一次面试，有用的记忆可能是“面试后跟进”，而不是“永久存入 `MEMORY.md`”。 + +[跟进承诺](/zh-CN/concepts/commitments) 是针对此类场景的可选、短期跟进记忆。OpenClaw 会在隐藏的后台步骤中推断它们，将其限定在同一个智能体和渠道内，并通过 Heartbeat 发送到期的跟进。明确的提醒仍然使用[定时任务](/zh-CN/automation/cron-jobs)。 + ## 记忆工具 智能体有两个用于处理记忆的工具： -- **`memory_search`** — 使用语义搜索查找相关笔记，即使用词与原文不同也可以找到。 -- **`memory_get`** — 读取指定的记忆文件或行范围。 +- **`memory_search`** — 使用语义搜索查找相关笔记，即使措辞与原文不同也可以找到。 +- **`memory_get`** — 读取特定的记忆文件或行范围。 -这两个工具都由当前启用的记忆插件提供（默认：`memory-core`）。 +这两个工具由主动记忆插件提供（默认：`memory-core`）。 ## Memory Wiki 配套插件 -如果你希望持久记忆更像一个维护良好的知识库，而不只是原始笔记，请使用内置的 `memory-wiki` 插件。 +如果你希望持久记忆表现得更像一个维护良好的知识库，而不只是原始笔记，可以使用内置的 `memory-wiki` 插件。 -`memory-wiki` 会把持久知识编译成一个 wiki 知识库，具备： +`memory-wiki` 会将持久知识编译成一个 wiki 库，包含： - 确定性的页面结构 - 结构化声明和证据 -- 矛盾和新鲜度跟踪 -- 生成的仪表板 +- 矛盾与新鲜度跟踪 +- 生成的仪表盘 - 面向智能体/运行时消费者的编译摘要 - wiki 原生工具，例如 `wiki_search`、`wiki_get`、`wiki_apply` 和 `wiki_lint` -它不会替代当前启用的记忆插件。当前启用的记忆插件仍然负责回忆、提升和 Dreaming。`memory-wiki` 会在旁边添加一个富含出处信息的知识层。 +它不会替代主动记忆插件。主动记忆插件仍然负责回忆、提升和 Dreaming。`memory-wiki` 会在旁边添加一个富含来源信息的知识层。 参见 [Memory Wiki](/zh-CN/plugins/memory-wiki)。 ## 记忆搜索 -配置嵌入提供商后，`memory_search` 会使用**混合搜索**：将向量相似度（语义含义）与关键词匹配（ID 和代码符号等精确术语）结合起来。只要你拥有任一受支持提供商的 API 密钥，它就可以开箱即用。 +配置嵌入提供商后，`memory_search` 会使用**混合搜索**，将向量相似度（语义含义）与关键字匹配（ID 和代码符号等精确术语）结合起来。只要你拥有任意受支持提供商的 API key，它就可以开箱即用。 -OpenClaw 会根据可用的 API 密钥自动检测你的嵌入提供商。如果你已经配置 OpenAI、Gemini、Voyage 或 Mistral 密钥，记忆搜索会自动启用。 +OpenClaw 会根据可用的 API key 自动检测你的嵌入提供商。如果你配置了 OpenAI、Gemini、Voyage 或 Mistral key，记忆搜索会自动启用。 -有关搜索的工作方式、调优选项和提供商设置的详细信息，请参见 [Memory Search](/zh-CN/concepts/memory-search)。 +有关搜索工作方式、调优选项和提供商设置的详细信息，请参见[记忆搜索](/zh-CN/concepts/memory-search)。 ## 记忆后端 - -基于 SQLite。支持关键词搜索、向量相似度和混合搜索，开箱即用。无需额外依赖。 + +基于 SQLite。通过关键字搜索、向量相似度和混合搜索开箱即用。无需额外依赖。 -本地优先的 sidecar，支持重排序、查询扩展，以及索引工作区之外的目录。 +本地优先的 sidecar，支持重排序、查询扩展，以及索引工作区之外目录的能力。 -AI 原生的跨会话记忆，具备用户建模、语义搜索和多智能体感知能力。通过插件安装。 +AI 原生的跨会话记忆，支持用户建模、语义搜索和多智能体感知。插件安装。 -内置的 LanceDB 后端记忆，支持 OpenAI 兼容嵌入、自动回忆、自动捕获和本地 Ollama 嵌入。 +内置的 LanceDB 支持记忆，包含 OpenAI 兼容嵌入、自动回忆、自动捕获和本地 Ollama 嵌入支持。 @@ -86,15 +92,15 @@ AI 原生的跨会话记忆，具备用户建模、语义搜索和多智能体 -将持久记忆编译成富含出处信息的 wiki 知识库，包含声明、仪表板、桥接模式，以及对 Obsidian 友好的工作流。 +将持久记忆编译成富含来源信息的 wiki 库，包含声明、仪表盘、桥接模式和适合 Obsidian 的工作流。 ## 自动记忆刷新 -在 [compaction](/zh-CN/concepts/compaction) 汇总你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体把重要上下文保存到记忆文件中。该功能默认开启，你无需配置任何内容。 +在[压缩](/zh-CN/concepts/compaction)总结你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体把重要上下文保存到记忆文件中。此功能默认开启，你无需配置任何内容。 -要让这个维护回合使用本地模型，请设置一个精确的记忆刷新模型覆盖： +若要让这个整理回合使用本地模型，请设置一个精确的记忆刷新模型覆盖： ```json { @@ -110,33 +116,33 @@ AI 原生的跨会话记忆，具备用户建模、语义搜索和多智能体 } ``` -该覆盖仅适用于记忆刷新回合，不会继承当前会话的 fallback 链。 +该覆盖仅应用于记忆刷新回合，并且不会继承当前会话的回退链。 -记忆刷新可防止 compaction 期间上下文丢失。如果你的智能体在对话中有尚未写入文件的重要事实，它们会在生成摘要前自动保存。 +记忆刷新可防止压缩期间的上下文丢失。如果你的智能体在对话中有尚未写入文件的重要事实，它们会在生成摘要之前自动保存。 ## Dreaming -Dreaming 是可选的后台记忆整合过程。它会收集短期信号、为候选项评分，并且只将符合条件的条目提升到长期记忆（`MEMORY.md`）。 +Dreaming 是一个可选的后台记忆整合步骤。它会收集短期信号、为候选项评分，并且只将符合条件的项目提升到长期记忆（`MEMORY.md`）。 -它旨在让长期记忆保持高信号密度： +它的设计目标是让长期记忆保持高信噪比： -- **选择启用**：默认禁用。 -- **定时执行**：启用后，`memory-core` 会自动管理一个周期性 cron 任务，用于完整的 Dreaming 扫描。 -- **阈值控制**：提升必须通过评分、回忆频率和查询多样性门槛。 +- **可选启用**：默认禁用。 +- **定时执行**：启用后，`memory-core` 会自动管理一个用于完整 Dreaming 扫描的周期性 cron job。 +- **设有阈值**：提升必须通过分数、回忆频率和查询多样性门槛。 - **可审阅**：阶段摘要和日记条目会写入 `DREAMS.md`，供人工审阅。 -有关阶段行为、评分信号和 Dream Diary 详细信息，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 +有关阶段行为、评分信号和 Dream Diary 详情，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 ## 有依据的回填和实时提升 Dreaming 系统现在有两个密切相关的审阅通道： -- **实时 Dreaming** 使用 `memory/.dreams/` 下的短期 Dreaming 存储；普通深度阶段在判断哪些内容可以进入 `MEMORY.md` 时使用的就是它。 +- **实时 Dreaming** 使用 `memory/.dreams/` 下的短期 Dreaming 存储，这是普通深度阶段在决定哪些内容可以进入 `MEMORY.md` 时使用的内容。 - **有依据的回填** 将历史 `memory/YYYY-MM-DD.md` 笔记作为独立的每日文件读取，并将结构化审阅输出写入 `DREAMS.md`。 -当你想重放较早的笔记，并检查系统认为哪些内容具有持久价值，而无需手动编辑 `MEMORY.md` 时，有依据的回填很有用。 +当你想重放较旧的笔记，并在不手动编辑 `MEMORY.md` 的情况下检查系统认为哪些内容是持久的，有依据的回填会很有用。 当你使用： @@ -150,7 +156,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - 短期存储仍然是面向机器的排序界面。 - `MEMORY.md` 仍然只由深度提升写入。 -如果你认为这次重放没有用，可以移除暂存的产物，而不影响普通日记条目或正常回忆状态： +如果你认为这次重放没有帮助，可以移除暂存的产物，而不影响普通日记条目或正常回忆状态： ```bash openclaw memory rem-backfill --rollback @@ -165,17 +171,17 @@ openclaw memory search "query" # Search from the command line openclaw memory index --force # Rebuild the index ``` -## 相关阅读 +## 延伸阅读 - [内置记忆引擎](/zh-CN/concepts/memory-builtin)：默认 SQLite 后端。 -- [QMD 记忆引擎](/zh-CN/concepts/memory-qmd)：高级本地优先 sidecar。 -- [Honcho 记忆](/zh-CN/concepts/memory-honcho)：AI 原生跨会话记忆。 +- [QMD 记忆引擎](/zh-CN/concepts/memory-qmd)：高级的本地优先 sidecar。 +- [Honcho 记忆](/zh-CN/concepts/memory-honcho)：AI 原生的跨会话记忆。 - [Memory LanceDB](/zh-CN/plugins/memory-lancedb)：基于 LanceDB 的插件，支持 OpenAI 兼容嵌入。 - [Memory Wiki](/zh-CN/plugins/memory-wiki)：编译后的知识库和 wiki 原生工具。 - [记忆搜索](/zh-CN/concepts/memory-search)：搜索流水线、提供商和调优。 - [Dreaming](/zh-CN/concepts/dreaming)：从短期回忆到长期记忆的后台提升。 - [记忆配置参考](/zh-CN/reference/memory-config)：所有配置开关。 -- [Compaction](/zh-CN/concepts/compaction)：compaction 如何与记忆交互。 +- [压缩](/zh-CN/concepts/compaction)：压缩如何与记忆交互。 ## 相关内容 @@ -184,3 +190,4 @@ openclaw memory index --force # Rebuild the index - [内置记忆引擎](/zh-CN/concepts/memory-builtin) - [Honcho 记忆](/zh-CN/concepts/memory-honcho) - [Memory LanceDB](/zh-CN/plugins/memory-lancedb) +- [跟进承诺](/zh-CN/concepts/commitments) diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index 1f205d1cc..b258cc828 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,146 +1,142 @@ --- read_when: - 正在查找公开发布渠道定义 - - 运行发布验证或包验收 + - 运行发布验证或软件包验收 - 查找版本命名和发布节奏 -summary: 发布通道、操作员检查清单、验证环境、版本命名和节奏 +summary: 发布通道、操作员检查清单、验证环境、版本命名和发布节奏 title: 发布策略 x-i18n: - generated_at: "2026-04-29T11:37:54Z" + generated_at: "2026-04-29T21:36:59Z" model: gpt-5.5 provider: openai - source_hash: bc944cc72f61226363cd6684c1b4830c518874da21bcf8127d365772275f17f7 + source_hash: 54dc9ad7918ac95ec535a0404bbcbc04461a2b977151db0c2039b91e7e69c15c source_path: reference/RELEASING.md workflow: 16 --- OpenClaw 有三个公开发布通道： -- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` +- stable：已打标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest` - beta：发布到 npm `beta` 的预发布标签 - dev：`main` 的移动头部 ## 版本命名 -- 稳定发布版本：`YYYY.M.D` +- stable 发布版本：`YYYY.M.D` - Git 标签：`vYYYY.M.D` -- 稳定修正发布版本：`YYYY.M.D-N` +- stable 修正发布版本：`YYYY.M.D-N` - Git 标签：`vYYYY.M.D-N` -- Beta 预发布版本：`YYYY.M.D-beta.N` +- beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` - 月份或日期不要补零 -- `latest` 表示当前已提升的稳定 npm 发布版本 +- `latest` 表示当前已提升的 stable npm 发布版本 - `beta` 表示当前 beta 安装目标 -- 稳定版和稳定修正发布版本默认发布到 npm `beta`；发布操作者可以明确指定 `latest`，也可以稍后提升经过验证的 beta 构建 -- 每个稳定的 OpenClaw 发布版本都会同时交付 npm 软件包和 macOS 应用； - beta 发布通常会先验证并发布 npm/软件包路径，除非明确请求， - 否则 mac 应用的构建、签名和公证保留给稳定版 +- stable 和 stable 修正发布版本默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，或稍后提升一个已验证的 beta 构建 +- 每个 stable OpenClaw 发布版本都会同时交付 npm 包和 macOS 应用； + beta 发布版本通常先验证并发布 npm/包路径，除非明确请求，否则 + mac 应用构建/签名/公证仅保留给 stable ## 发布节奏 - 发布按 beta 优先推进 -- 只有最新 beta 验证通过后才会发布稳定版 -- 维护者通常会从当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本， +- 只有最新 beta 通过验证后才会发布 stable +- 维护者通常从基于当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本， 这样发布验证和修复不会阻塞 `main` 上的新开发 -- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出下一个 - `-beta.N` 标签，而不是删除或重新创建旧 beta 标签 -- 详细发布流程、审批、凭证和恢复说明仅限维护者 +- 如果 beta 标签已经推送或发布且需要修复，维护者会切出下一个 `-beta.N` 标签， + 而不是删除或重新创建旧的 beta 标签 +- 详细的发布流程、审批、凭证和恢复说明仅限维护者查看 -## 发布操作者清单 +## 发布操作员清单 -此清单是发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚详情保留在仅限维护者的发布运行手册中。 +此清单是发布流程的公开形态。私有凭证、 +签名、公证、dist-tag 恢复和紧急回滚细节保留在 +仅限维护者的发布运行手册中。 1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送， - 并确认当前 `main` 的 CI 足够健康，可以从它创建分支。 + 并确认当前 `main` CI 足够绿，可以从它创建分支。 2. 使用 `/changelog` 根据真实提交历史重写顶部 `CHANGELOG.md` 章节， - 保持条目面向用户，提交它，推送它，并在创建分支前再 rebase/pull 一次。 -3. 审查 + 保持条目面向用户，提交它，推送它，并在创建分支前再次 rebase/pull。 +3. 检查 `src/plugins/compat/registry.ts` 和 - `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。仅当升级路径仍然被覆盖时才移除过期兼容性，或者记录为什么要有意保留它。 + `src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除过期兼容性， + 否则记录为什么有意继续保留。 4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上执行常规发布工作。 -5. 为预期标签提升每个必需位置的版本，然后运行本地确定性预检： +5. 为预期标签更新每个必需的版本位置，然后运行本地确定性预检： `pnpm check:test-types`、`pnpm check:architecture`、 `pnpm build && pnpm ui:build` 和 `pnpm release:check`。 -6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前， - 允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。 +6. 以 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前， + 允许使用完整 40 字符的发布分支 SHA 进行仅验证预检。 保存成功的 `preflight_run_id`。 -7. 对发布分支、标签或完整提交 SHA 使用 `Full Release Validation` 启动所有预发布测试。 - 这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 -8. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、工作流作业、软件包配置、提供商或模型 allowlist。只有当变更表面让之前证据失效时，才重新运行完整的总控流程。 -9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布， - 然后针对已发布的 `openclaw@YYYY.M.D-beta.N` - 或 `openclaw@beta` 软件包运行发布后软件包验收。如果已推送或已发布的 beta 需要修复， +7. 使用 `Full Release Validation` 为发布分支、标签或完整提交 SHA 启动所有预发布测试。 + 这是四个大型发布测试盒的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。 +8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败 + 文件、通道、workflow job、package profile、provider 或 model allowlist。 + 只有当变更范围让先前证据过期时，才重新运行完整 umbrella。 +9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` + 或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复， 切出下一个 `-beta.N`；不要删除或重写旧 beta。 -10. 对于稳定版，只有经过验证的 beta 或候选发布版本具备所需验证证据后才能继续。稳定版 npm 发布会通过 `preflight_run_id` 复用成功的预检工件；稳定版 macOS 发布就绪还要求 `main` 上存在打包好的 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的 +10. 对于 stable，只有在已验证的 beta 或发布候选具备所需验证证据后才继续。 + stable npm 发布会通过 `preflight_run_id` 复用成功的 + 预检工件；stable macOS 发布就绪还要求 `main` 上存在已打包的 `.zip`、`.dmg`、`.dSYM.zip` 和更新后的 `appcast.xml`。 -11. 发布后，运行 npm 发布后验证器，在你需要发布后渠道证明时可选择运行独立的已发布 npm Telegram E2E，按需提升 dist-tag，根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease 说明，并执行发布公告步骤。 +11. 发布后，运行 npm 发布后验证器，需要发布后渠道证明时可选运行独立的 + published-npm Telegram E2E，按需进行 dist-tag 提升，根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease notes， + 并执行发布公告步骤。 ## 发布预检 -- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外仍被覆盖 -- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外保持绿色 -- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在 -- 在发布批准前运行手动 `Full Release Validation` workflow，从一个入口启动所有预发布 test boxes。它接受分支、标签或完整 commit SHA，分发手动 `CI`，并分发 `OpenClaw Release Checks`，用于安装 smoke、package acceptance、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 线。仅在 package 已发布且也应运行发布后 Telegram E2E 时提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配已发布的 npm package、但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。 - 示例： - `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- 当你希望在发布工作继续进行时，为 package 候选项获取旁路证明，请运行手动 `Package Acceptance` workflow。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 以当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对需要 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions run 上传的 tarball 使用 `source=artifact`。该 workflow 会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并且可以用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。 - 示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai` - 常用 profile： - - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载线 - - `package`：不含 OpenWebUI 或 live ClawHub 的 artifact-native package/update/plugin 线 - - `product`：package profile 外加 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI - - `full`：带 OpenWebUI 的 Docker 发布路径分片 +- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外也保持覆盖 +- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外为绿色 +- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，确保预期的 `dist/*` 发布产物和控制 UI 包存在，供打包验证步骤使用 +- 在发布批准前运行手动 `Full Release Validation` 工作流，以便从一个入口点启动所有预发布测试盒。它接受分支、标签或完整提交 SHA，分发手动 `CI`，并分发 `OpenClaw Release Checks`，用于安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 线路。仅在包已发布且发布后的 Telegram E2E 也应运行时，才提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配已发布的 npm 包、但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。示例：`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` +- 当你希望在发布工作继续进行的同时，为包候选项获取侧信道证明时，运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 通过当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对带必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该工作流会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一 tarball 运行 Telegram QA。示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai` + 常用配置： + - `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载线路 + - `package`：不含 OpenWebUI 或 live ClawHub 的产物原生包/更新/插件线路 + - `product`：包配置加 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI + - `full`：带 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 选择 -- 当你只需要发布候选项的完整普通 CI 覆盖时，直接运行手动 `CI` workflow。手动 CI 分发会绕过 changed scoping，并强制运行 Linux Node 分片、内置插件分片、渠道 contract、Node 22 兼容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android 和 Control UI i18n 线。 - 示例：`gh workflow run ci.yml --ref release/YYYY.M.D` -- 验证发布 telemetry 时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP receiver 运行 QA-lab，并验证导出的 trace span 名称、有界 attributes，以及内容/标识符脱敏；不需要 Opik、Langfuse 或其他外部 collector。 -- 每次带标签发布前运行 `pnpm release:check` -- 发布检查现在在单独的手动 workflow 中运行： - `OpenClaw Release Checks` -- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock 一致性门禁，以及快速 live Matrix profile 和 Telegram QA 线。live 线使用 `qa-live-shared` environment；Telegram 还使用 Convex CI credential leases。当你希望并行获取完整 Matrix 传输、媒体和 E2EE inventory 时，运行手动 `QA-Lab - All Lanes` workflow，并设置 `matrix_profile=all` 和 `matrix_shards=true`。 -- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用 reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- 这种拆分是有意的：让真实 npm 发布路径保持简短、确定且专注于 artifact，同时让较慢的 live 检查留在自己的线中，避免它们拖慢或阻塞发布 -- 带 secret 的发布检查应通过 `Full Release Validation` 分发，或从 `main`/release workflow ref 分发，以便 workflow 逻辑和 secrets 保持受控 -- `OpenClaw Release Checks` 接受分支、标签或完整 commit SHA，只要解析出的 commit 可从 OpenClaw 分支或 release tag 到达 -- `OpenClaw NPM Release` validation-only 预检也接受当前完整 40 字符 workflow 分支 commit SHA，无需推送 tag -- 该 SHA 路径仅用于验证，不能升级为真实发布 -- 在 SHA 模式下，workflow 只为 package metadata check 合成 `v`；真实发布仍需要真实 release tag -- 两个 workflow 都将真实 publish 和 promotion 路径保留在 GitHub-hosted runners 上，而非变更性 validation 路径可以使用更大的 Blacksmith Linux runners -- 该 workflow 使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` workflow secrets 运行 - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` -- npm 发布预检不再等待单独的发布检查线 -- 批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （或匹配的 beta/correction tag） -- npm publish 后，运行 - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - （或匹配的 beta/correction version），在全新的临时 prefix 中验证已发布 registry 安装路径 -- beta publish 后，运行 `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 credential pool，针对已发布 npm package 验证 installed-package 新手引导、Telegram 设置和真实 Telegram E2E。本地 maintainer 一次性操作可以省略 Convex vars，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。 -- Maintainers 可以通过手动 `NPM Telegram Beta E2E` workflow 从 GitHub Actions 运行相同的发布后检查。它有意仅允许手动运行，不会在每次 merge 时运行。 -- Maintainer 发布自动化现在使用 preflight-then-promote： - - 真实 npm publish 必须通过成功的 npm `preflight_run_id` - - 真实 npm publish 必须从与成功 preflight run 相同的 `main` 或 `release/YYYY.M.D` 分支分发 - - stable npm releases 默认指向 `beta` - - stable npm publish 可以通过 workflow input 明确指定 `latest` - - 基于 token 的 npm dist-tag 变更现在位于 - `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - 以保障安全，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而 public repo 保持 OIDC-only publish +- 当你只需要发布候选项的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 分发会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和控制 UI i18n 线路。示例：`gh workflow run ci.yml --ref release/YYYY.M.D` +- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP 接收器运行 QA-lab，并验证导出的跟踪 span 名称、有界属性以及内容/标识符脱敏，无需 Opik、Langfuse 或其他外部采集器。 +- 每次打标签发布前运行 `pnpm release:check` +- 发布检查现在在一个单独的手动工作流中运行：`OpenClaw Release Checks` +- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab 模拟一致性门禁、快速 live Matrix 配置和 Telegram QA 线路。live 线路使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你希望并行获取完整 Matrix 传输、媒体和 E2EE 清单时，使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。 +- 跨操作系统安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- 这种拆分是有意的：保持真实 npm 发布路径短、确定且聚焦产物，同时让较慢的 live 检查留在自己的线路中，避免拖慢或阻塞发布 +- 带有密钥的发布检查应通过 `Full Release Validation` 分发，或从 `main`/release 工作流引用分发，以保持工作流逻辑和密钥受控 +- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达 +- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支提交 SHA，无需已推送的标签 +- 该 SHA 路径仅用于验证，不能提升为真实发布 +- 在 SHA 模式下，工作流仅为包元数据检查合成 `v`；真实发布仍需要真实发布标签 +- 两个工作流都将真实发布和提升路径保留在 GitHub 托管 runner 上，而非变更性验证路径可以使用更大的 Blacksmith Linux runner +- 该工作流会使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥运行 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` +- npm 发布预检不再等待单独的发布检查线路 +- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或匹配的 beta/修正版标签） +- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/修正版版本），在全新的临时前缀中验证已发布注册表安装路径 +- 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 设置和真实 Telegram E2E。本地维护者的一次性运行可以省略 Convex 变量，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境凭证。 +- 维护者可以通过手动 `NPM Telegram Beta E2E` 工作流从 GitHub Actions 运行同一个发布后检查。它有意仅支持手动运行，不会在每次合并时运行。 +- 维护者发布自动化现在使用先预检再提升： + - 真实 npm 发布必须通过成功的 npm `preflight_run_id` + - 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支分发 + - 稳定 npm 发布默认使用 `beta` + - 稳定 npm 发布可以通过工作流输入显式目标为 `latest` + - 基于令牌的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，出于安全考虑，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布 - 公开 `macOS Release` 仅用于验证 - - 真实私有 mac publish 必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` - - 真实 publish 路径会提升已准备好的 artifacts，而不是再次 rebuild 它们 -- 对于 `YYYY.M.D-N` 这样的 stable correction releases，发布后 verifier 还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同 temp-prefix 升级路径，确保 release corrections 不会静默地让旧的 global installs 停留在 base stable payload 上 -- npm 发布预检会 fail closed，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` payload，以免我们再次发布空的浏览器 dashboard -- 发布后验证还会检查已发布 registry install 是否在根 `dist/*` 布局下包含非空的内置插件 runtime deps。若某个发布缺失或包含空的内置插件依赖 payload，则 postpublish verifier 会失败，且不能 promoted 到 `latest`。 -- `pnpm test:install:smoke` 还会对候选 update tarball 强制执行 npm pack `unpackedSize` 预算，因此 installer e2e 会在 release publish 路径前捕获意外的 pack bloat -- 如果发布工作触及 CI planning、extension timing manifests 或 extension test matrices，请在批准前重新生成并审查由 planner 拥有的 `plugin-prerelease-extension-shard` matrix outputs，来源为 `.github/workflows/plugin-prerelease.yml`，确保 release notes 不会描述过时的 CI 布局 -- Stable macOS 发布就绪性还包括 updater surfaces： + - 真实私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id` + - 真实发布路径会提升已准备好的产物，而不是再次重建它们 +- 对于类似 `YYYY.M.D-N` 的稳定修正版本，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，确保发布修正不会静默地让较旧的全局安装停留在基础稳定载荷上 +- npm 发布预检会默认失败，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷，避免再次发布空的浏览器仪表板 +- 发布后验证还会检查已发布注册表安装是否在根 `dist/*` 布局下包含非空的内置插件运行时依赖。若发布版本缺少或带有空的内置插件依赖载荷，发布后验证器会失败，且无法提升为 `latest`。 +- `pnpm test:install:smoke` 也会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 会在发布发布路径前捕获意外的打包膨胀 +- 如果发布工作触及 CI 规划、插件计时清单或插件测试矩阵，请在批准前重新生成并审查由规划器拥有的 `plugin-prerelease-extension-shard` 矩阵输出，来源于 `.github/workflows/plugin-prerelease.yml`，确保发布说明不会描述过时的 CI 布局 +- 稳定 macOS 发布就绪还包括更新器表面： - GitHub release 最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip` - - publish 后，`main` 上的 `appcast.xml` 必须指向新的 stable zip - - 打包后的 app 必须保留非 debug bundle id、非空 Sparkle feed URL，以及对该 release version 而言不低于 canonical Sparkle build floor 的 `CFBundleVersion` + - 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定 zip + - 打包后的应用必须保持非调试 bundle id、非空 Sparkle feed URL，以及等于或高于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` -## 发布 test boxes +## 发布测试盒 -`Full Release Validation` 是 operators 从一个入口启动所有预发布测试的方式。请从可信的 `main` workflow ref 运行它，并将 release branch、tag 或完整 commit SHA 作为 `ref` 传入： +`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。从可信的 `main` 工作流引用运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入： ```bash gh workflow run full-release-validation.yml \ @@ -152,19 +148,17 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -该 workflow 会解析目标 ref，使用 `target_ref=` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在设置 `npm_telegram_package_spec` 时可选地分发独立的发布后 Telegram E2E。`OpenClaw Release Checks` 随后会扇出安装 smoke、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram package QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。仅当 `Full Release Validation` summary 显示 `normal_ci` 和 `release_checks` 成功，并且任何可选的 `npm_telegram` child 成功或有意跳过时，完整 run 才可接受。最终 verifier summary 包含每个 child run 的最慢 job 表格，因此 release manager 可以在不下载日志的情况下看到当前关键路径。 -Child workflows 从运行 `Full Release Validation` 的可信 ref 分发，通常为 `--ref main`，即使目标 `ref` 指向较旧的 release branch 或 tag。没有单独的 Full Release Validation workflow-ref input；请通过选择 workflow run ref 来选择可信 harness。 +该工作流会解析目标引用，使用 `target_ref=` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在设置了 `npm_telegram_package_spec` 时可选地分发独立的发布后 Telegram E2E。随后，`OpenClaw Release Checks` 会扇出安装冒烟、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。完整运行只有在 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功，且任何可选的 `npm_telegram` 子项成功或被有意跳过时才可接受。最终验证器摘要会包含每个子运行的最慢作业表，因此发布经理无需下载日志即可看到当前关键路径。子工作流从运行 `Full Release Validation` 的可信引用分发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签。不存在单独的 Full Release Validation 工作流引用输入；通过选择工作流运行引用来选择可信 harness。 -使用 `release_profile` 选择 live/provider 覆盖广度： +使用 `release_profile` 选择 live/提供商覆盖范围： -- `minimum`：最快的 release-critical OpenAI/core live 和 Docker 路径 -- `stable`：minimum 加上用于 release approval 的 stable provider/backend 覆盖 -- `full`：stable 加上广泛的 advisory provider/media 覆盖 +- `minimum`：最快的发布关键 OpenAI/core live 和 Docker 路径 +- `stable`：minimum 加上用于发布批准的稳定提供商/后端覆盖 +- `full`：stable 加上广泛的建议提供商/媒体覆盖 -`OpenClaw Release Checks` 使用可信 workflow ref 将目标 ref 解析一次为 `release-package-under-test`，并在 release-path Docker checks 和 Package Acceptance 中复用该 artifact。这让所有面向 package 的 boxes 使用相同字节，并避免重复 package builds。 -当 repo/org variable 已设置时，跨 OS OpenAI install smoke 使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因为这条线证明的是 package install、新手引导、gateway startup 和一次 live 智能体 turn，而不是对最慢默认模型进行 benchmark。更广泛的 live provider matrix 仍然是进行 model-specific 覆盖的地方。 +`OpenClaw Release Checks` 使用可信工作流引用将目标引用一次性解析为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该产物。这会让所有面向包的测试盒使用相同字节，并避免重复构建包。当设置了仓库/组织变量时，跨操作系统 OpenAI 安装冒烟使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因为此线路证明的是包安装、新手引导、Gateway 网关启动和一次 live 智能体轮次，而不是基准测试最慢的默认模型。更广泛的 live 提供商矩阵仍然是模型特定覆盖的位置。 -请根据 release stage 使用这些 variants： +根据发布阶段使用这些变体： ```bash # Validate an unpublished release candidate branch. @@ -193,22 +187,37 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -不要把完整总控工作流作为聚焦修复后的首次重跑。如果某个检查盒失败，请使用失败的子工作流、作业、Docker 通道、包配置文件、模型提供商或 QA 通道作为下一次验证。只有当修复更改了共享发布编排，或让之前的全检查盒证据变得过期时，才再次运行完整总控工作流。总控工作流的最终验证器会重新检查记录的子工作流运行 ID，因此当某个子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。 +不要把完整总控流程用作聚焦修复后的第一次重跑。如果某个盒子失败， +下一次证明请使用失败的子 workflow、job、Docker 通道、包配置文件、模型 +提供商或 QA 通道。只有当修复更改了共享发布编排，或使此前所有盒子的 +证据过期时，才再次运行完整总控流程。总控流程的最终验证器会重新检查 +已记录的子 workflow 运行 ID，因此在子 workflow 成功重跑后，只需重跑 +失败的父级 `Verify full validation` job。 -对于有边界的恢复，请将 `rerun_group` 传给总控工作流。`all` 是真正的候选发布运行，`ci` 只运行常规 CI 子工作流，`plugin-prerelease` 只运行仅发布用的插件子工作流，`release-checks` 运行所有发布检查盒，而更窄的发布分组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。 +对于有界恢复，请向总控流程传入 `rerun_group`。`all` 是真正的 +候选发布运行，`ci` 只运行普通 CI 子项，`plugin-prerelease` 只运行 +仅发布插件子项，`release-checks` 会运行每个发布盒子，更窄的发布组包括 +`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、 +`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。 ### Vitest -Vitest 检查盒是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限定，并为候选发布强制运行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。 +Vitest 盒子是手动 `CI` 子 workflow。手动 CI 会有意绕过变更范围限定， +并为候选发布强制运行普通测试图：Linux Node 分片、内置插件分片、渠道 +契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、 +Python skills、Windows、macOS、Android，以及 Control UI i18n。 -使用此检查盒回答“源代码树是否通过了完整的常规测试套件？”它不同于发布路径的产品验证。需要保留的证据： +使用这个盒子回答“源代码树是否通过了完整的普通测试套件？”它与发布路径 +产品验证不同。需要保留的证据： - `Full Release Validation` 摘要，显示已调度的 `CI` 运行 URL -- `CI` 在精确目标 SHA 上通过 -- 调查回归时来自 CI 作业的失败或缓慢分片名称 -- 当运行需要性能分析时，保留 Vitest 计时产物，例如 `.artifacts/vitest-shard-timings.json` +- `CI` 在精确目标 SHA 上为绿色 +- 调查回归时来自 CI job 的失败或缓慢分片名称 +- 当一次运行需要性能分析时，保留 `.artifacts/vitest-shard-timings.json` + 等 Vitest 计时产物 -仅当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、实时、跨 OS 或包检查盒时，才直接运行手动 CI： +仅当发布需要确定性的普通 CI，而不需要 Docker、QA Lab、live、cross-OS +或 package 盒子时，才直接运行手动 CI： ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -216,49 +225,95 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker 检查盒位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 运行，并包含发布模式的 `install-smoke` 工作流。它通过打包后的 Docker 环境验证候选发布，而不只是源代码级测试。 +Docker 盒子位于 `OpenClaw Release Checks` 中，通过 +`openclaw-live-and-e2e-checks-reusable.yml` 提供，另有发布模式的 +`install-smoke` workflow。它通过打包后的 Docker 环境验证候选发布，而不 +只是源码级测试。 发布 Docker 覆盖范围包括： -- 启用较慢 Bun 全局安装冒烟的完整安装冒烟 +- 启用慢速 Bun 全局安装冒烟的完整安装冒烟 +- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，QR、root/gateway 和 + installer/Bun 冒烟 job 作为独立的 install-smoke 分片运行 - 仓库 E2E 通道 -- 发布路径 Docker 分块：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts` -- 按需在 `plugins-runtime-services` 分块中覆盖 OpenWebUI -- 将内置渠道依赖通道拆分到 channel-smoke、update-target 和 setup/runtime 契约分块中，而不是放在一个大型内置渠道作业里 -- 拆分内置插件安装/卸载通道 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23` -- 当发布检查包含实时套件时，覆盖 live/E2E 提供商套件和 Docker 实时模型 +- 发布路径 Docker 分块：`core`、`package-update-openai`、 + `package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、 + `plugins-runtime-services`、 + `plugins-runtime-install-a`、`plugins-runtime-install-b`、 + `plugins-runtime-install-c`、`plugins-runtime-install-d`、 + `plugins-runtime-install-e`、`plugins-runtime-install-f`、 + `plugins-runtime-install-g`、`plugins-runtime-install-h`、 + `bundled-channels-core`、`bundled-channels-update-a`、 + `bundled-channels-update-discord`、`bundled-channels-update-b`，以及 + `bundled-channels-contracts` +- 按需在 `plugins-runtime-services` 分块内覆盖 OpenWebUI +- 将内置渠道依赖通道拆分到 channel-smoke、update-target 以及 + setup/runtime 契约分块，而不是一个大型 bundled-channel job +- 拆分内置插件安装/卸载通道，从 `bundled-plugin-install-uninstall-0` + 到 `bundled-plugin-install-uninstall-23` +- 当发布检查包含 live 套件时，覆盖 live/E2E 提供商套件和 Docker live + 模型覆盖 -重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用 live/E2E 工作流上使用 `docker_lanes=`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含之前的 `package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以复用同一个 tarball 和 GHCR 镜像。 +重跑前先使用 Docker 产物。发布路径调度器会上传 +`.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、 +`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复， +请在可复用 live/E2E workflow 上使用 `docker_lanes=`， +而不是重跑所有发布分块。生成的重跑命令会在可用时包含此前的 +`package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以 +复用同一个 tarball 和 GHCR 镜像。 ### QA Lab -QA Lab 检查盒也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 包机制。 +QA Lab 盒子也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和 +渠道级发布门禁，独立于 Vitest 和 Docker 包机制。 发布 QA Lab 覆盖范围包括： -- 使用 agentic parity pack，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的模拟一致性门禁 -- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置文件 -- 使用 Convex CI 凭据租约的实时 Telegram QA 通道 +- mock parity gate，使用 agentic parity pack 将 OpenAI 候选通道与 + Opus 4.6 基线进行比较 +- 使用 `qa-live-shared` 环境的快速 live Matrix QA 配置 +- 使用 Convex CI 凭据租约的 live Telegram QA 通道 - 当发布遥测需要明确的本地证明时运行 `pnpm qa:otel:smoke` -使用此检查盒回答“发布在 QA 场景和实时渠道流程中是否行为正确？”批准发布时保留 parity、Matrix 和 Telegram 通道的产物 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键通道。 +使用这个盒子回答“该发布在 QA 场景和 live 渠道流程中是否行为正确？” +批准发布时保留 parity、Matrix 和 Telegram 通道的产物 URL。完整 Matrix +覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认发布关键通道。 ### Package -Package 检查盒是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选项规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单，记录包版本和 SHA-256，并将工作流 harness ref 与包源 ref 分开。 +Package 盒子是可安装产品门禁。它由 `Package Acceptance` 和解析器 +`scripts/resolve-openclaw-package-candidate.mjs` 支持。该解析器会将候选项 +规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单， +记录包版本和 SHA-256，并让 workflow harness ref 与包源码 ref 保持分离。 支持的候选来源： -- `source=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本 -- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的 `package_ref` 分支、标签或完整提交 SHA +- `source=npm`：`openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw + 发布版本 +- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的 + `package_ref` 分支、标签或完整 commit SHA - `source=url`：下载 HTTPS `.tgz`，并要求提供 `package_sha256` - `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz` -`OpenClaw Release Checks` 使用 `source=ref`、`package_ref=`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 保留面向同一已解析 tarball 的产物原生内置渠道兼容性、离线插件 fixture 和 Telegram 包 QA。它是此前大部分需要 Parallels 的包/更新覆盖的 GitHub 原生替代方案。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但包/更新产品验证应优先使用 Package Acceptance。 +`OpenClaw Release Checks` 会以 `source=ref`、`package_ref=`、 +`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline` +和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker +分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 则针对同一 +已解析 tarball 保留产物原生的内置渠道兼容性、离线插件夹具和 Telegram +包 QA。它是过去大部分需要 Parallels 的包/更新覆盖的 GitHub 原生替代。 +Cross-OS 发布检查对特定 OS 的新手引导、安装器和平台行为仍然重要，但 +包/更新产品验证应优先使用 Package Acceptance。 -旧版 package-acceptance 宽松规则是有意限时的。直到 `2026.4.25` 的包，可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失私有 QA 清单条目、缺失 `gateway install --wrapper`、tarball 派生 git fixture 中缺失补丁文件、缺失持久化的 `update.channel`、旧版插件安装记录位置、缺失 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 包可以对已发布的本地构建元数据戳文件发出警告。之后的包必须满足现代包契约；这些相同缺口会导致发布验证失败。 +旧版 package-acceptance 宽容策略有意设置了时间边界。直到 `2026.4.25` +的包都可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺少 +私有 QA 清单条目、缺少 `gateway install --wrapper`、tarball 派生的 git +夹具中缺少补丁文件、缺少持久化的 `update.channel`、旧版插件安装记录 +位置、缺少 marketplace 安装记录持久化，以及 `plugins update` 期间的 +配置元数据迁移。已发布的 `2026.4.26` 包可以对已经随版本发布的本地构建 +元数据 stamp 文件发出警告。之后的包必须满足现代包契约；这些相同缺口 +会导致发布验证失败。 -当发布问题涉及实际可安装包时，请使用更宽的 Package Acceptance 配置文件： +当发布问题涉及实际可安装包时，请使用更广的 Package Acceptance 配置： ```bash gh workflow run package-acceptance.yml \ @@ -269,58 +324,80 @@ gh workflow run package-acceptance.yml \ -f suite_profile=product ``` -常见包配置文件： +常见包配置： -- `smoke`：快速包安装/渠道/智能体、Gateway 网关网络和配置重载通道 -- `package`：不含实时 ClawHub 的安装/更新/插件包契约；这是 release-check 默认值 -- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI -- `full`：包含 OpenWebUI 的 Docker 发布路径分块 +- `smoke`：快速包安装/渠道/智能体、Gateway 网关网络和配置热重载通道 +- `package`：不含 live ClawHub 的安装/更新/插件包契约；这是 release-check + 默认值 +- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web + search 和 OpenWebUI +- `full`：带 OpenWebUI 的 Docker 发布路径分块 - `custom`：用于聚焦重跑的精确 `docker_lanes` 列表 -对于包候选 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会把已解析的 `package-under-test` tarball 传入 Telegram 通道；独立 Telegram 工作流仍接受已发布的 npm spec，用于发布后检查。 +对于包候选 Telegram 证明，请在 Package Acceptance 上启用 +`telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该 workflow +会把已解析的 `package-under-test` tarball 传入 Telegram 通道；独立 +Telegram workflow 仍接受已发布的 npm spec，用于发布后检查。 -## NPM 工作流输入 +## NPM workflow 输入 -`OpenClaw NPM Release` 接受这些由操作员控制的输入： +`OpenClaw NPM Release` 接受以下由操作员控制的输入： -- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整 40 字符工作流分支提交 SHA，用于仅验证的预检 +- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 + `v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整 + 40 字符 workflow 分支 commit SHA，用于仅验证的预检 - `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径 -- `preflight_run_id`：真实发布路径必需，以便工作流复用成功预检运行准备的 tarball +- `preflight_run_id`：真实发布路径必需，这样 workflow 会复用成功预检运行 + 准备好的 tarball - `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta` -`OpenClaw Release Checks` 接受这些由操作员控制的输入： +`OpenClaw Release Checks` 接受以下由操作员控制的输入： -- `ref`：要验证的分支、标签或完整提交 SHA。带密钥的检查要求已解析提交可从 OpenClaw 分支或发布标签访问。 +- `ref`：要验证的分支、标签或完整 commit SHA。带密钥的检查要求解析后的 + commit 可从 OpenClaw 分支或发布标签访问。 规则： -- 稳定标签和修正标签可以发布到 `beta` 或 `latest` +- 稳定版和修正版标签可以发布到 `beta` 或 `latest` - Beta 预发布标签只能发布到 `beta` -- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入完整提交 SHA -- `OpenClaw Release Checks` 和 `Full Release Validation` 始终只做验证 -- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；工作流会在发布继续前验证该元数据 +- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入 + 完整 commit SHA +- `OpenClaw Release Checks` 和 `Full Release Validation` 始终仅用于验证 +- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；workflow 会 + 在发布继续前验证该元数据 -## 稳定 npm 发布流程 +## 稳定版 npm 发布序列 -切稳定 npm 发布时： +切稳定版 npm 发布时： 1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release` - - 在标签存在之前，你可以使用当前完整工作流分支提交 SHA，对预检工作流进行仅验证的空运行 -2. 对常规 beta 优先流程选择 `npm_dist_tag=beta`，或者仅在你有意直接发布稳定版时选择 `latest` -3. 当你希望从一个手动工作流获得常规 CI 加上实时 prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation` -4. 如果你有意只需要确定性的常规测试图，请改为在发布 ref 上运行手动 `CI` 工作流 + - 在标签存在前，可以使用当前完整 workflow 分支 commit SHA，对预检 + workflow 做一次仅验证的 dry run +2. 普通 beta-first 流程选择 `npm_dist_tag=beta`；只有在有意直接发布稳定版时 + 才选择 `latest` +3. 当你想从一个手动 workflow 获得普通 CI 加 live prompt cache、Docker、 + QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整 commit SHA + 上运行 `Full Release Validation` +4. 如果你有意只需要确定性的普通测试图，则改为在发布 ref 上运行手动 `CI` + workflow 5. 保存成功的 `preflight_run_id` -6. 再次运行 `OpenClaw NPM Release`，并使用 `preflight_only=false`、相同的 `tag`、相同的 `npm_dist_tag` 和已保存的 `preflight_run_id` -7. 如果发布落在 `beta`，使用私有 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 工作流，将该稳定版本从 `beta` 提升到 `latest` -8. 如果发布有意直接发布到 `latest`，且 `beta` 应立即跟随同一个稳定构建，请使用同一个私有工作流将两个 dist-tag 都指向该稳定版本，或者让它的计划自修复同步稍后移动 `beta` +6. 再次运行 `OpenClaw NPM Release`，并使用 `preflight_only=false`、相同的 + `tag`、相同的 `npm_dist_tag`，以及已保存的 `preflight_run_id` +7. 如果发布落在 `beta`，请使用私有 + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + workflow 将该稳定版本从 `beta` 提升到 `latest` +8. 如果发布有意直接发布到 `latest`，并且 `beta` 应立即跟随同一个稳定构建， + 请使用同一个私有 workflow 将两个 dist-tag 指向该稳定版本，或让其计划式 + 自修复同步稍后移动 `beta` -dist-tag 变更位于私有仓库中，是出于安全原因，因为它仍然需要 `NPM_TOKEN`，而公共仓库保持仅 OIDC 发布。 +dist-tag 变更位于私有仓库中是出于安全考虑，因为它仍然需要 `NPM_TOKEN`， +而公共仓库保持仅 OIDC 发布。 -这会让直接发布路径和 beta 优先提升路径都保持已文档化，并对操作员可见。 +这样可以让直接发布路径和 beta-first 提升路径都得到记录，并对操作员可见。 -如果维护者必须回退到本地 npm 认证，请仅在专用 tmux 会话内运行任何 1Password -CLI (`op`) 命令。不要直接从主智能体 shell 调用 `op`；将其保持在 tmux 内可以让提示、 -警报和 OTP 处理过程可观察，并防止重复的主机警报。 +如果维护者必须回退到本地 npm 身份验证，只能在专用的 tmux 会话中运行任何 1Password +CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将它保留在 tmux 内可以让提示、 +警报和 OTP 处理可观察，并防止重复的主机警报。 ## 公共参考资料 @@ -338,6 +415,6 @@ CLI (`op`) 命令。不要直接从主智能体 shell 调用 `op`；将其保持 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) 中的私有发布文档作为实际运行手册。 -## 相关内容 +## 相关 - [发布渠道](/zh-CN/install/development-channels)