本指南面向负责构建和发布 OpenAgentCore 的维护者。要安装 Core 和 Web,请按 安装 Core 和 Web 操作。安装程序代码遵循的规则见 部署 和 节点安装程序;必需检查见 CONTRIBUTING。
构建分发包
分发包是从同一个提交构建的一组相互匹配的发布资源:作为独立文件的 Runtime 镜像和节点构件,以及原生安装程序。构建还会为每种架构生成一个控制归档(安装程序、oac 命令,以及 Core、Web、ingress 和 PostgreSQL 镜像)。发布器从中读取镜像和原生目录;没有任何安装流程使用它,因此它不是发布资源。
Core、Web 和 ingress 镜像发布为经过校验的 Linux amd64/arm64 多架构索引。arm64 控制归档包含这三个镜像;Node、托管 Runtime 和离线包使用 Linux amd64。发行构建使用 QEMU 执行 ARM 镜像步骤,包括 E2B helper。主机 oac 从同一份实现构建为 Linux amd64/arm64、macOS amd64/arm64 和 Windows amd64 二进制;启动脚本只选择、校验并运行它们。所有版本索引校验通过后才更新浮动标签。
请在 Linux x86_64 上构建,所需环境包括与 Debian 12 兼容的 glibc、Docker、go.mod 中指定的 Go 版本、C 编译器(microsandbox 辅助程序使用 CGO 构建)、Node、pnpm、Python 3.9 或更高版本、curl、tar、pigz 和 sha256sum。源代码必须保持干净并已提交。请先准备固定版本的 Codex 包和 MiniMax Code 配套程序,然后执行构建:
bash scripts/prepare-release-runtimes.sh
inputs="$HOME/.oac/build/release-inputs/inputs.json"
export CODEX_CLI_DIR="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["codex"])' "$inputs")"
export MCODE_HARNESS_BUILD_DIR="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["mcode"])' "$inputs")"
export CORE_DISTRIBUTION_RELEASE_BASE_URL=https://github.com/MiniMax-AI/OpenAgentCore/releases/download/v1.2.3
make build-core-distribution如果 ~/.oac/build/release-inputs 已存在,prepare-release-runtimes.sh 会拒绝执行;请使用全新的构建主机。
| 变量 | 作用 |
|---|---|
CORE_DISTRIBUTION_RELEASE_BASE_URL | 用于提供生成的资源文件名的带版本 HTTPS 目录(绝不能使用 latest)。除非 CORE_DISTRIBUTION_OFFLINE=1,否则为必填项 |
CORE_DISTRIBUTION_OFFLINE | 设为 1 时还会构建离线归档 |
CORE_DISTRIBUTION_PLATFORMS | 默认 linux/amd64,linux/arm64;本地源码安装使用 linux/amd64,无需 QEMU 或 ARM 控制面镜像 |
CODEX_CLI_DIR、MCODE_HARNESS_BUILD_DIR | prepare-release-runtimes.sh 固定的 Runtime 输入 |
CORE_DISTRIBUTION_CODEX_IMAGE、CORE_DISTRIBUTION_CLAUDE_IMAGE、CORE_DISTRIBUTION_MCODE_IMAGE | 使用现有 Harness 镜像,而不是构建这些镜像;值必须是以不可变 sha256: 镜像 ID 表示的现有镜像。三个变量必须全部设置或全部不设置;每个镜像都必须包含由该提交构建的守护进程 |
OAC_NATIVE_INSTALLER_BUILD_DIR | 原生安装程序目录;请参阅原生安装程序 |
CORE_DISTRIBUTION_BUILD_DIR | ~/.oac 下的输出目录。默认值:~/.oac/build/core-distribution |
CORE_DISTRIBUTION_BUILD_NETWORK | Docker 构建网络:default、host 或 none |
CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE | 已缓存的 microsandbox 发布归档。默认值:~/.oac/cache/microsandbox-oac-v0.7.11-2-linux-x86_64.tar.gz,缺失时下载 |
CORE_DISTRIBUTION_DATABASE_IMAGE | PostgreSQL 16 镜像;默认值为 deploy/compose/database-image.txt 中索引的 linux/amd64 清单 |
构建过程会复用 Core、Web、Runtime、SDK 和辅助程序构建器。清单会记录提交及其源代码树、镜像配置及 OCI 清单摘要、Runtime OCI 清单摘要、microsandbox 运行时和固件哈希,以及每个 Runtime 和节点构件的大小与 SHA-256;原生安装程序在目录中仅记录其 SHA-256。输出包括控制归档及其 .sha256、可选的离线归档,以及带版本号的 Runtime、节点和原生安装程序资源。此过程不会发布任何内容。如果目标目录中已包含此提交的分发包,重建会拒绝执行。
ingress 镜像仅包含 oac 和三个节点元数据文件:manifest.json、SHA256SUMS 与 node-install.pyz。构建流程根据与分发包相同的 Runtime 和构件身份生成其清单,再禁用网络验证初始化。节点清单不包含控制平面镜像身份,因此可在 ingress 镜像生成前打包。
控制归档不包含 Runtime 镜像或节点执行构件;离线归档包含这些内容。下载契约说明了节点如何获取这些内容。
分发包会携带 scripts/core-distribution-manifest.py 中 BUNDLED_DOCS 列出的文档。随包文档之间的链接保持相对路径;其他所有相对链接都会重写为该捆绑包对应提交在 GitHub 上的同一文件。链接或锚点无法解析时,构建会失败;make check-docs 会对 example/ 之外每个受 Git 跟踪的 Markdown 文件运行相同检查。添加或移动安装程序或其输出所引用的文档时,请更新该列表。
原生安装程序
自托管机器通过各平台的原生安装程序安装 oac-daemon:Linux amd64、macOS arm64 和 Windows amd64。每个安装程序均由 native-check 工作流在各自的操作系统上构建(scripts/build-native-installer.mjs,其中的 pins 对象包含 Node.js 版本和由各 Harness 声明生成的 Harness 版本),并在每次选中的原生检查中得到验证。手动打包运行和发布检查会将该平台的各个归档上传为 oac-native-installer-<OS>-<ARCH> 并保留七天;普通 PR 和 main 检查即使成功也不会上传软件包。要构建本地分发包,请从该确切提交的一次 native-check 运行中下载这三个构件(可以是手动运行或发布运行;PR 运行构建的是合并提交,因此不匹配),然后使用该检出内容组装目录,输入目录中放入这三个构件的所有归档:
node scripts/build-native-catalog.mjs INPUT_DIR OUTPUT_DIR
export OAC_NATIVE_INSTALLER_BUILD_DIR=OUTPUT_DIR每个平台有一个小型基础归档 <os>-<arch>.tar.gz(oac-daemon 和 bundle.json,后者列出每个组件及其每个文件的 SHA-256),以及每个组件一个归档,即 <os>-<arch>-node 和 <os>-<arch>-<harness>(MiniMax Code 不为 Windows 构建)。build-native-installer.mjs 生成它们,并略去仅用于构建或安装的文件:node 中 CI 运行器全局安装的 pnpm,以及 minimax 中 better-sqlite3 的编译输入。Core 按名称提供这些制品,不了解其内容;oac-daemon install 下载所需的组件。
该目录会记录提交、Runtime 协议版本、每个制品的 SHA-256,并在提供发布基址时记录其带版本号的 URL。控制归档和 Core 镜像仅携带 native-installers/catalog.json;这些归档会成为独立的 oac-native-<commit>-<artifact>.tar.gz 发布资源,离线归档则会在 Core 镜像之外保留所有 Linux amd64 归档的一份副本,由其 install.py 复制到安装目录中供 Core 提供下载。其他平台由 Core 重定向到对应的发布资源;没有发布基址的目录没有这类 URL,因此其离线归档会保留所有归档。如果没有目录,Sessions 会将安装命令报告为不可用,并且发布工作流会拒绝发布。
Runtime 镜像和辅助程序
make build-core-distribution 会构建以下全部内容。也可以单独构建其中一项,以测试某个 Harness 镜像或辅助程序。所有命令都必须从仓库根目录运行;默认输出位于 ${OAC_DEV_HOME:-$HOME/.oac}/build 下。
三个维护的 Runtime 镜像共用固定摘要的基础镜像 node:22.23.1-bookworm-slim(含 ca-certificates、bash、git、python3、python3-pip 和 ripgrep),以及一个构建期调整:固定 Debian 登录 profile 会保留继承且已导出的 PATH,未设置 PATH 时仍使用 Debian 默认值。这样,登录和非登录工具都能使用 Runtime 初始化的包路径与用户路径,无需另一份包路径设置。组合镜像继承同一 profile。上游 profile 结构变化会使构建失败以便审查;自定义 shell 启动文件仍可以显式更改 PATH。
Codex Runtime 镜像。 在 ~/.oac 下解压官方 npm 包 @openai/codex@<version>-linux-x64,版本见 Harness 目录(例如使用 npm pack --ignore-scripts 和 tar -xzf),然后执行:
export CODEX_CLI_DIR=/absolute/path/to/package
make build-codex-runtime
docker build --platform linux/amd64 -t oac-runtime:codex "${OAC_DEV_HOME:-$HOME/.oac}/build/codex-runtime"该脚本会检查软件包版本,为 Linux amd64 构建 oac-daemon,并准备一个仅包含守护进程、未修改的原生可执行文件、相关资源、共用的登录 profile 构建步骤和 services/core/deploy/codex/Dockerfile 的上下文。
Claude Code Runtime 镜像。 必须使用 Node 22.21 或更高版本以及 pnpm。
make build-claude-sdk-runtime
make build-claude-runtime
docker build --platform linux/amd64 -t oac-runtime:claude "${OAC_DEV_HOME:-$HOME/.oac}/build/claude-runtime"第一步会将适配器和固定版本的 Claude Agent SDK(packages/claude-sdk-adapter/package.json)导出为适用于主机平台且带校验和的归档;第二步会验证该归档并添加守护进程。镜像步骤需要 linux-x64-glibc 归档,因此必须在带 glibc 的 Linux x86_64 上构建两者。请保持导出的归档不变。
MiniMax Code Runtime 镜像。 使用 packages/mcode-harness/source.json 中固定修订版本的检出,并使用相同版本的 @minimax-ai/code npm 包提供原生依赖,以构建配套程序。配套程序构建可在 Linux x86_64 或 macOS arm64 上运行,并输出到一个新目录;对于 Linux Runtime 镜像,请在 Linux x86_64 上构建它(macOS arm64 仅用于原生安装程序):
MCODE_NATIVE_SOURCE=/absolute/minimax-code \
MCODE_CLI_DIR=/absolute/node_modules/@minimax-ai/code \
MCODE_HARNESS_BUILD_DIR=/absolute/mcode-harness bash scripts/build-mcode-harness.sh
MCODE_HARNESS_BUILD_DIR=/absolute/mcode-harness bash scripts/build-mcode-runtime.sh
docker build --platform linux/amd64 -t oac-runtime:mcode "${OAC_DEV_HOME:-$HOME/.oac}/build/mcode-runtime"scripts/prepare-release-runtimes.sh 会根据固定版本配置运行配套程序构建。
分发包将三个 Harness 镜像合并到一个 Runtime 镜像(deploy/distribution/Runtime.Dockerfile)中:以携带守护进程的 MiniMax Code 镜像为基础,并复制入 Codex 可执行文件及资源和 Claude Code 包。构建过程会验证每个镜像都携带由同一提交构建的守护进程。
E2B 辅助程序。
make build-e2b-providerDocker 使用固定版本的 CPython 和 Debian 12 镜像按 GOARCH=amd64(默认)或 GOARCH=arm64 构建 Linux 辅助程序。Python 依赖闭包(including PyInstaller)在 services/core/tools/e2b-provider/requirements.lock 中按哈希锁定;不需要 E2B 账户密钥。要使用其他输出目录,请设置 E2B_PROVIDER_BUILD_DIR。构建结果完全由辅助程序源代码、LICENSE 和构建脚本决定,因此会按它们的哈希缓存在 ~/.oac/cache/e2b-provider/ 下,仅在它们变化时重新构建。输出为 oac-e2b-provider-linux-<architecture>.tar.gz 及其 .sha256;解压后会得到 oac-e2b-provider/,其中包含可执行文件、_internal/、licenses/、requirements.lock 和 manifest.json。Core 镜像使用该目录树;主机需要兼容的 glibc 和 CA 证书,而不需要 Python。
microsandbox 辅助程序。 仅支持 Linux amd64,并且需要 C 编译器:
make build-microsandbox-provider
make check-microsandbox-provider该辅助程序会写入 ~/.oac/build/microsandbox-provider/oac-microsandbox-provider。其独立的 Go 模块固定来自下文所述 fork 的 microsandbox SDK。上述两个命令与分发构建均使用 scripts/build-microsandbox-provider.py:它暂存模块依赖,验证 fork 的 FFI 发行文件校验和,填充 SDK 的空发行包,并构建嵌入该 FFI 的程序。仓库不提交 vendored 二进制文件。请使用此入口,而非直接调用 go build;构建生产版本时,绝不能使用该 SDK 的 microsandbox_ffi_path 标签。Core 本身仍采用禁用 CGO 的构建。该辅助程序需要 glibc,并且只能在节点上运行。
microsandbox 运行时。 分发包使用 fork 发布 oac-v0.7.11-2 的归档 microsandbox-linux-x86_64.tar.gz,SHA256 为 9ca514e58d7156954537210d2e673c07b091ed5137775b8952ecfd2e96d85638(即 scripts/core-distribution-manifest.py 中的 RUNTIME_ARCHIVE_SHA256)。构建过程会先验证校验和,再解压 msb 和 libkrunfw.so.5.6.1,并记录这两个文件的哈希。辅助程序会在每次调用时检查这些哈希,并且绝不安装或升级它们。
microsandbox fork。 SDK、其 FFI 和 msb 运行时来自 SaladDay/microsandbox 的 oac 分支:一个上游发布标签加上一小队补丁,补丁列表见 git log v0.7.11..oac。每个补丁同时向上游提交,上游发布包含它之后就从队列中删除。推送 oac-v<upstream version>-<n> 标签会在与上游发布相同的 manylinux 2.28 容器中构建 Linux amd64 FFI 和运行时归档,其中 libkrunfw 使用同一上游版本的官方文件而不构建内核,并把它们连同 SHA256 文件附加到该标签的 release(.github/workflows/oac-release.yml)。要换到新标签,把 services/core/tools/microsandbox-provider/go.mod 中 SDK 的 replace 指向该标签的提交,并更新 scripts/build-microsandbox-provider.py 中的 FORK_TAG 和 FFI_SHA256 以及 RUNTIME_ARCHIVE_SHA256。
独立 Core 构建
make build-core 会将 oac-core、oac-core-device、oac-core-environment-key、oac-node 和 oac 构建到 ${OAC_DEV_HOME:-$HOME/.oac}/build/oac-core(OAC_DEV_CORE_BUILD_DIR 可选择其他绝对目录)。构建过程仅将 scripts/build-core.sh 中列出的源文件集(Core 服务、其契约、所需的共享软件包以及根 Go 模块文件)复制到临时上下文,并使用禁用 CGO、只读模块和裁剪路径的方式构建。它不需要 Node、Docker 或其他应用程序。Core 新增共享依赖时,请将该软件包加入列表;绝不能复制整个仓库来使其完成编译。
make docker-build-core 会根据这五个命令和 E2B 辅助程序构建 oac-core:dev 镜像(OAC_DEV_CORE_IMAGE 可选择其他名称)。基础镜像是通过摘要固定的 debian:bookworm-slim,包含 CA 证书以及辅助程序所需的 glibc 运行时;默认用户的 UID/GID 为 65532,Core 监听 :8091。此本地构建目标生成 Linux amd64 镜像;分发构建生成两种架构的镜像。对镜像或其构建进行更改时,除了相关的源代码检查外,还必须运行 make check-core-container:它会在只读根文件系统上针对该镜像运行官方客户端测试套件,并且需要 Linux Docker、非 root 用户,以及服务检查中的测试数据库和固定版本 SDK(OAC_TEST_DATABASE_URL 指向一个已应用迁移的 oac_*_tests 数据库,并设置 OAC_TEST_OFFICIAL_SDK_PYTHON)。
发布版本
在经过审查的提交上推送版本标签,以运行 core-release 工作流:
git tag -a v1.2.3 FULL_REVIEWED_COMMIT_SHA -m "OpenAgentCore v1.2.3"
git push origin v1.2.3flowchart LR
tag[Push tag] --> checks[Full gate and native packaging] --> build[Build distribution and manifest] --> publish[Push images and publish the Release]
标签使用 vMAJOR.MINOR.PATCH 格式,可选用 -rc.1 等预发布后缀以及 +build.1 等构建元数据。预发布后缀会创建 GitHub 预发布版。推送标签即表示发布决定。自动检查用于确定构建和测试结果,而不是真实模型资格:推送标签前应评估实际执行证据。模型凭据和私有证书颁发机构绝不能进入 CI 或发布输入,包含它们的验收镜像也不例外。
工作流会在带标签的提交上运行 check,包括完整的本地门禁、官方客户端和镜像验收,以及启用打包构件的原生平台矩阵。检查成功后,blacksmith-4vcpu-ubuntu-2204 上的一个 build 作业会准备固定的 Runtime 输入、复用原生安装程序、构建分发包,并直接从本地文件发布。此合并作业具有 contents: write 和 packages: write 权限;检出过程不会保留凭据。只有发布失败或手动构建不发布时,才会把这些文件保留为未压缩的 Actions 构建产物,供恢复使用。
分发归档和 Runtime 归档使用 pigz 级别 6,最多使用四个压缩工作线程,并且 gzip 头部中不包含文件名或时间戳。发布器会验证归档和原生安装程序校验和、解析仓库身份、拒绝使用该标签已有的 Release 或草稿,并创建一个具有固定 ID 的草稿。最多四个资源可并发上传,按从大到小的顺序进行,且不会重试。确认完整的远程资源清单后,发布器会验证所有镜像归档和现有注册表标签,再并发推送最多四个镜像。每个镜像配置和注册表清单都会接受验证;任何错误都会使 Release 保持未发布状态。失败操作返回前,正在进行的传输会完成。发布器会按 ID 发布草稿,并在发布前重新检查版本标签。
容器注册表
版本发布和手动 build-<full SHA> 草稿使用 ghcr.io/minimax-ai/openagentcore/<component>:<version>,其中 <component> 为 core、web、runtime、ingress 或 postgres。Core、Web 和 ingress 索引包含 Linux amd64 和 arm64 镜像,Runtime 包含 Linux amd64。各平台镜像使用 <version>-<architecture> 标签,从控制归档加载。已有版本标签必须与发行镜像及平台集合一致。发布器校验全部版本索引后,才为稳定版更新 latest;预发布版和草稿保持 latest 不变。postgres 是固定在 deploy/compose/database-image.txt 中的官方 PostgreSQL 索引,连同全部平台和原摘要一并复制;注册表中的标签若指向其他摘要,发布器会拒绝。要升级 PostgreSQL,请把该文件改为同一主版本的新摘要,模板、离线包和镜像复制都读取这一处。容器标签中的 SemVer 构建元数据用 _ 替换 +,版本字符串上限为 128 个字符。镜像校验后,发布器上传该版本的 compose.yaml 和校验和清单。Compose 用对应发行版的索引摘要固定 Core、Web、ingress 和 PostgreSQL,初始化时检查其构建版本与 Compose 版本一致。
合并的构建/发布作业使用具有 packages: write 权限的 GITHUB_TOKEN。首次发布时,GitHub 会将每个容器软件包创建为私有:软件包管理员必须先在各自的软件包设置中将全部五个软件包(core、web、runtime、ingress 和 postgres)改为 Public,用户才能匿名拉取。请参阅 GitHub container visibility。更改可见性后,请验证未认证拉取。仅更改仓库可见性并不会使新的容器软件包变为公开。
GHCR 和 GitHub Releases 不共享事务。发布失败后,GHCR 中可能仍会保留一些匹配的版本标签;请保留这些镜像,并使用原始构件按照下文的草稿恢复流程操作。除清单缺失以外,注册表故障都会停止发布。作业摘要会记录按摘要固定的引用。这些镜像和渲染后的 Compose 文件仍需要配置中描述的配置、机密和路由。
安装指南介绍版本选择和各平台的启动命令。
Go 检查和构建作业共享 ~/.oac/cache/ 下的 Go 模块和编译器缓存目录,缓存键由运行器 OS 和架构、全部 Go 模块文件、检查/构建分区以及提交确定。分区键可防止并发作业在同一个键下保存不同的编译器子集。发布构建既可以使用后端检查的缓存,也可以使用更早发布构建的缓存。较旧的缓存只会为下载和编译提供初始内容;每项检查仍会运行。发布作业还会缓存 npm 软件包下载内容和固定版本的 microsandbox 归档,并在每次构建时验证后者的校验和。Actions 缓存可见性遵循 GitHub ref 的作用域;特定标签的缓存不会与其他发布标签共享。只有作业成功后才会保存新键。
绝不移动发布标签或覆盖已发布的资源。发布失败时,请先检查 Release:即使响应丢失,发布也可能已经完成。对于完整的已发布 Release,请保持原样。对于不完整的草稿,仅在检查后将其删除,然后使用 gh run download RUN_ID --name core-release-REVISION --dir ASSET_DIRECTORY 下载原始 core-release-<revision> Actions 构建产物,并使用该确切源代码修订版本的检出运行 python3 scripts/publish-core-release.py --assets ASSET_DIRECTORY。将 GH_REPO、GH_TOKEN、RELEASE_REVISION、RELEASE_TAG 和 RELEASE_MODE 设置为原始发布输入,并将 Docker 登录到 GHCR。该脚本会重新验证资源,并拒绝使用已有 Release。恢复上传失败时,绝不能重新运行合并的构建作业,也绝不能重新创建标签。
构建候选版本但不发布
手动运行需要完整的提交 SHA,会执行相同的检查和构建,默认生成离线归档,并且不会发布 Release:
revision=$(git rev-parse HEAD)
gh workflow run core-release --repo MiniMax-AI/OpenAgentCore --ref main \
-f ref="$revision" -f offline=true -f draft_release=true设置 draft_release=true 时,结果是未发布的 build-<full SHA> 草稿 Release,其镜像会以该标签推送;设置 draft_release=false 时,文件会保留在 Actions 构建产物中。请使用完全匹配的构件集合;绝不能混用构建结果,也绝不能通过 latest 解析组件。
持续集成
每个 PR 都会运行 core-check 并报告必需状态 check。main 使用 GitHub 分支保护,合并前必须通过此检查且分支必须为最新状态,因此合并不会启动另一份测试套件。所有更改都必须通过经过检查的 PR 提交;管理员绕过检查并不代表 CI 成功。推送到 main 时,如果输入发生变化,就会发布网站,并运行 cache-warm:它构建 MiniMax companion、E2B 辅助程序和 pnpm 存储,不运行测试,因为只有 main 上保存的缓存能被每个 PR 和发布标签恢复。版本标签和手动发布构建会在其确切源代码提交上运行完整的发布门禁。scripts/ci_plan.py 管理唯一的输入到检查映射。组件规则要求同时匹配目录或脚本前缀以及文件后缀;确切的依赖项、工作流和共享构建输入都有明确规则。规则会在共享使用方和混合变更之间累加。没有匹配构建/测试规则的路径仅运行 hygiene。引入新组件、语言、构建输入或资源位置时,请添加相应规则。
计划器会将 PR 事件所测试的合并提交与其已验证的第一个父提交进行比较。NUL 分隔的 Git 输出和禁用重命名检测会同时保留旧路径和新路径。计划及原因会显示在运行摘要中。历史记录缺失或不一致、检出不匹配、路径无效、计划器/编排发生变更以及共享构建输入发生变化时,都会选择完整门禁。经过验证的空差异仅选择 hygiene。发布、手动和显式 ref 调用始终选择所有组。
| 组 | 检查和使用方 |
|---|---|
hygiene | 仓库链接、随包文档完整性以及 CI 计划器/门禁测试;每次变更都会运行 |
distribution | Harness 目录和安装程序模式、安装/应用/恢复/清理测试、Compose 解析和初始化固定数据、发布/下载和捆绑包契约、Go 控制台测试与构建;模板解析需要 Docker Compose,不需要 pnpm install 或浏览器 |
compose | 使用从当前检出构建的镜像从空数据卷实际启动、登录和 API 访问、上传文件和下载节点安装程序,然后在保留凭据和数据的同时重新配置 URL 并重新创建容器;需要 Docker、Go 和网络访问,不需要模型凭据 |
backend | 并行部分,每部分都有专用 PostgreSQL 保护检查:runtime(sqlc 新鲜度、Runtime/共享 Go 测试、Linux microsandbox 辅助程序、守护进程构建)、core(独立 Core 构建、Core 服务和客户端测试),以及串行 Core 集成测试包的三个 integration 分片(使用固定版本的官方客户端运行) |
harness | Claude Code adapter 测试和打包、MiniMax 配套脚本 |
example | 可选的应用程序类型检查、测试、构建和隔离的浏览器验收 |
web | TypeScript、Web/客户端测试和 Web 构建 |
website | 针对网站、已发布文档和依赖项变更的网站构建与输出检查 |
web-acceptance | Web 单元测试/构建成功后,以四个隔离分片运行完整 Web 浏览器测试套件;每个分片保留一个工作线程 |
api | 针对独立命令和迁移的可复用官方客户端验收;当镜像/构建/辅助程序输入发生变化时进行镜像验收,并在每次完整门禁中执行 |
native | 可复用的 Linux、macOS 和 Windows 构建、文件系统/进程/Harness 检查和原生安装;三个平台可并发运行 |
lint | 可复用的 actionlint 检查,包括本地复合操作 |
.github/actionlint.yaml 会选择 hygiene 和 lint。已知工作流变更会选择其使用方:CI review 和 actionlint 工作流运行 hygiene 和 lint;原生工作流变更会添加原生检查;API 验收工作流变更会添加启用容器验收的 API 检查;网站工作流变更会添加网站检查。共享 Node 操作会选择使用它的每个作业以及 lint。新工作流或未分类的工作流/操作会选择完整门禁,直至在计划器中声明其使用方。计划器测试和 CI 测量脚本运行 hygiene;更改计划器本身会运行完整门禁。
Compose 模板和 Compose 测试发生变更时,会同时选择 distribution 固定数据和 compose 冒烟作业;Core、Web、共享 Go 软件包和镜像 Dockerfile 的变更也会选择冒烟作业。安装 Docker 后,可在本地运行 python3 scripts/compose-smoke.py 重复该测试。该脚本使用唯一的项目、自动分配的回环端口,并将在 ~/.oac/tests/ 下生成构件;退出时移除其容器和数据卷。CI 还会在冒烟步骤失败或中断后执行清理。诊断信息会显示容器状态,但不会打印 HTTP 响应正文或登录密钥。Core、Web 和 ingress 镜像都从当前检出构建,并带有当前检出提交的节点元数据;Web 提供占位页面而不是控制台构建,初始化容器禁用网络运行。冒烟矩阵使用 Linux amd64 和 arm64 原生 runner;原生矩阵在 Linux、macOS 和 Windows 上构建并测试共享的 Core 安装程序。
| 变更输入 | 所选检查组 |
|---|---|
docs/ 和 contracts/ 下已发布的文档和资源,以及 docs.json | hygiene、website |
| 其他普通 Markdown 文件,包括源代码目录中的文档 | hygiene |
Core .go、.sql、辅助脚本和配置输入 | backend、api |
| Web 源代码、样式和资源 | web、web-acceptance(所有浏览器分片) |
| 安装程序 | distribution |
| 嵌入式原生资源和声明的测试固定数据目录,无论后缀 | 其使用方 |
| 共享契约、SDK、Runtime 输入和依赖项;生成的目录和协议输入 | 其使用方,包括安装程序、客户端和 UI |
| Go 模块和工作区输入 | backend、api(包括容器)、native、distribution |
| 网站依赖项 | website |
| Web 依赖项 | web、web-acceptance |
| 示例依赖项 | example |
| 共享 TypeScript 客户端依赖项 | web、web-acceptance、example |
| Claude 适配器依赖项 | harness、native、distribution |
| 共享包管理器配置 | 所有 Node 使用方 |
| 根 TypeScript 配置 | web、example |
| 适配器 TypeScript 配置 | harness、native |
| Core/DB 变更 | backend、api 中的官方客户端验收 |
不要在可复用工作流中重复路径列表,也不要在必需工作流上添加 paths 过滤器。生成的目录文件和配置参考章节会保留其分发新鲜度检查。
即使计划或依赖项失败,最终 check 仍会运行。它要求计划有效且成功、每个所选作业均成功,并且每个未选择作业均被跳过。失败、取消、作业缺失、意外跳过或意外执行都会导致门禁失败。API/原生可复用工作流是此门禁的直接依赖项。同一 PR 上较新的运行会取消之前的运行。发布检查在请求的不可变 ref 上运行;原生打包在这些检查中执行一次,分发构建会等待其完成。
要手动执行完整检查,请使用 Actions → core-check → Run workflow。遇到暂时性故障时,请使用 GitHub 的 Re-run failed jobs,这样已成功的作业可保持完成状态。原生发布安装程序通过 Actions 构建产物在同一发布工作流的不同作业之间传递。
CI review and Feishu notification 工作流仅在 PR 合并到 main 后运行一次。它检出合并后的提交,读取该 PR 已有的检查和日志,通过 FEISHU_WEBHOOK_URL 发送一张飞书卡片,概述本次改动、是否符合仓库规则以及实际 CI 状态。它不会触发另一轮测试;审查或发送失败不会让作业失败,也不会阻止合并。关闭未合并 PR 不触发审查。该工作流只针对合并事件使用 pull_request_target,绝不在持有通知凭据时检出未合并 PR 的 head。
浏览器作业各自拥有独立的固定数据和服务;对共享可变固定数据增加 worker 数不安全。失败的浏览器作业保留报告与 trace 七天。原生失败阶段摘要保留七天,详细输出留在 Actions 日志中;凭据和临时安装目录不上传。原生归档仅在显式手动打包或发布时构建并上传,不重新压缩已压缩的归档。
本地 Node 复合操作会安装固定版本的 pnpm,并根据锁文件、OS、架构、Node 版本和 pnpm 版本缓存其软件包存储。它缓存下载的软件包,而不是 node_modules;安装仍保持冻结状态。Go 分区会保留发布部分所述的现有模块/编译器缓存。三个原生平台独立运行;并行执行可缩短总耗时,但不会减少机器总时间。
对于本地更改,请检查所选的组,并根据更改检查项选择针对性检查:
python3 scripts/ci_plan.py plan --base origin/main --head HEAD
make check-cimake check 仍是完整的本地入口,使用未分片的 Web 测试套件和未分片的 Core 集成测试包。make check-web-unit 和 make check-web-acceptance OAC_WEB_TEST_SHARD=1/4 用于分别运行 Web 部分;make check-core-packages 和 make check-core-integration OAC_CORE_INTEGRATION_SHARD=1/3 用于分别运行 Core 部分,其中集成测试按名称的稳定哈希分配到分片。选择测试涵盖混合变更、共享使用方、重命名/删除、未知输入、浅合并检出以及失败/取消/缺失结果。对于选择映射的更改,请针对受影响的规则重放具有代表性的差异。对于工作流更改,请运行 actionlint,并验证更改后的调度或分区行为。仅在需要验证受变更影响的行为时,才运行真实组件测试。
使用 python3 scripts/ci_metrics.py RUN_ID ... 衡量已完成的运行。它会报告最近一次尝试的运行器分钟数总和、耗时、从该次尝试开始计算的初始排队延迟、并发作业峰值、平台明细以及作业结果/失败比例。只有在该次尝试中被分配了运行器的作业才计入机器时间和执行并发;排队期间被取消的作业仍保留其结果和实际耗时。更早的尝试不计入其中。失败作业的重新运行可能沿用更早的成功结果:这些结果会单独显示,且其原有执行时间会被排除。如果缺少重新运行的开始时间戳,测量会停止,因为无法可靠区分复用的作业。比较时应保留 run/head/attempt 标识,并分别报告取消和未完成的运行。原始运行器分钟数并非计费分钟数;估算成本前,应使用各平台公布的转换和配额规则。较小的成功样本不能作为长期失败率估计。
CI 运行器和免费配额
Linux 检查作业使用 Blacksmith 的 2-vCPU Ubuntu 22.04 或 24.04 运行器;原生 Windows 使用其 2-vCPU Windows 2025 运行器。Blacksmith 没有 2-vCPU macOS 运行器,因此原生 macOS 使用标准 GitHub macos-15 ARM64 运行器。发布构建和发布始终共用一个 Blacksmith blacksmith-4vcpu-ubuntu-2204 运行器,不受运行器切换设置影响。直接在 runs-on 中使用的自定义运行器标签在 .github/actionlint.yaml 中声明,以便进行工作流验证。
将仓库 Actions 变量 OAC_USE_GITHUB_RUNNERS 设为 true,即可改为在标准 GitHub 托管运行器上运行检查作业。Linux 会保留对应的 Ubuntu 版本,Windows 使用 windows-2025,macOS 继续使用 macos-15。删除该变量或将其设为 false,即可让可切换的检查作业恢复为 Blacksmith 的 2-vCPU 默认值。例如,维护者可以在组织的免费配额用尽时进行切换,并在配额重置后恢复 Blacksmith:
gh variable set OAC_USE_GITHUB_RUNNERS --body true --repo MiniMax-AI/OpenAgentCore这是显式的操作员开关,而不是自动账单余额探测。运行器选择仅适用于新调度的运行。在将 2-vCPU 用量视为免费之前,请先查看当前配额和平台转换率:Blacksmith's runner documentation。Windows 分钟消耗的配额多于 Linux 分钟。标准 GitHub 运行器的用量取决于仓库可见性和 GitHub 套餐。发布构建使用 4-vCPU 运行器;这些工作流不会请求任何付费缓存附加服务。