OpenViking 发版工程实践：多产物 tag 约定、GitHub Actions 发布流水线与补发策略

OpenViking 发版工程实践多产物 tag 约定、GitHub Actions 发布流水线与补发策略【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文围绕 OpenViking 仓库的发版说明文档系统拆解其“一次发版、多产物联动”的发布体系主包、Python SDK、Docker 镜像、Rust CLI/npm 包、TOS 下载资产与 ClawHub 插件各自的 tag 命名空间与触发链路并逐条对照仓库中的 GitHub Actions workflow 与包配置说明构建、发布、验证与补发的完整操作路径帮助维护者按规范完成一次正式发版并正确处理发布失败场景。发版目标一组相互关联的资产而非单一产物OpenViking 一次正式发版需要同时覆盖多个分发渠道各产物面向不同使用入口openvikingPython 主包面向本地运行时、服务端、CLI 及完整功能用户Python SDKopenviking-sdk面向只通过 HTTP 调用已有 OpenViking 服务的轻量客户端用户Docker 镜像面向容器化部署同时发布到 GHCR 和 Docker HubTOS 发布资产面向源码包、安装脚本和稳定下载路径Rust CLI / npm 包面向通过 npm 安装ovCLI 的用户OpenClaw / ClawHub 插件面向 OpenClaw 插件分发渠道VikingBot当前随openviking[bot]extra 和官方 Docker 镜像分发不再作为独立 PyPI 包维护。从根目录 pyproject.toml 可以确认这一结构包名为openviking、版本为dynamic由setuptools_scm解析[tool.setuptools.packages.find]的查找范围是[., bot]、包含openviking*和vikingbot*包——即 VikingBot 的源码确实被打进主包一起发布。发版的核心纪律是正式主版本发版时Python 主包、Docker 镜像和 TOS 资产必须使用同一个主版本 tagSDK、CLI、ClawHub 插件则使用各自独立的 tag 或 version 命名空间。这一约定在仓库的多个 workflow 里通过 tag 前缀过滤得到强制落地后文逐一展开。版本与 tag 约定产物推荐 tag / version说明openviking主包vX.Y.Z主 release tag例如v0.3.26openviking-sdkpython-sdkX.Y.ZSDK 专用 tag例如python-sdk0.1.3Rust CLI / npm CLIcliX.Y.ZCLI 专用 tag例如cli0.2.0ClawHub 插件 latestYYYY.M.D或YYYY.M.D-N由 workflow 自动生成或手动指定ClawHub 插件 devYYYY.M.D-dev.Ndev channel 使用tag 约定不只是文档规范而是被setuptools_scm配置直接执行的主包pyproject.toml 中[tool.setuptools_scm]设置tag_regex ^v(?Pversion[0-9](?:\\.[0-9])*)$write_to openviking/_version.pygit_describe_command使用--match v[0-9]*。即主包版本只从v前缀 tag 解析。SDKsdk/python/pyproject.toml 的[tool.setuptools_scm]设置root ../..以根仓库为版本源、tag_regex ^python-sdk(?Pversion...)$git_describe_command匹配python-sdk*。由于setuptools_scm的 tag 匹配互斥主包 tagv0.3.26不会干扰 SDK 版本解析反之亦然。这种“同一仓库、多 tag 命名空间、正则隔离”的设计是理解后续所有 workflow 触发条件的关键。正式主包发版流程主包正式发版走根目录 GitHub Release由 release.ymlworkflow 名03. Release驱动。完整流程确认待发布改动已合入目标分支且 PR / main 分支检查通过创建主包 tag例如v0.3.26在 GitHub 上基于该 tag 发布 Release03. Releaseworkflow 在 Release published 事件时触发——注意其buildjob 带有条件github.event_name workflow_dispatch || startsWith(github.event.release.tag_name, v)只有v前缀的主包 tag 才会走这条流水线python-sdk*、cli*等组件 tag 会被直接跳过build job 通过uses: ./.github/workflows/_build.yml复用15. _Build Distribution构建 sdist 和多平台 wheelpublish-pypijob 将构建产物发布到 PyPIDocker 镜像由独立的 tag 推送构建见下文release workflow 中的verify-dockerjob 负责轮询等待并校验镜像确实落库release-tos.yml20. Release TOS Upload在同一 Release published 事件下上传源码 zip 和安装脚本到 TOS。正式主发版的发布目标汇总渠道目标PyPIopenvikingGHCRghcr.io/owner/repoDocker Hubdockerhub-user/openvikingTOS版本化 release 路径和可选latest稳定路径几个从 workflow 源码中可以确认的实现细节发布采用 Trusted Publishingpublish-pypijob 只申请id-token: write权限使用pypa/gh-action-pypi-publishrelease/v1并设置skip-existing: true——同版本重复触发不会报错而是幂等跳过。手动 dispatch 有权限门禁permission-checkjob 通过getCollaboratorPermissionLevel校验触发者至少具有admin/maintain/write权限防止无权限者触发发布。构建矩阵可配默认os_json为[ubuntu-24.04, ubuntu-24.04-arm, macos-14, macos-15-intel, windows-latest]对应 Linux x86_64/aarch64、macOS arm64/x86_64、Windows x86_64默认python_json为[3.10]。Linux wheel 在 glibc 2.31 环境中构建_build.yml 的build-linuxjob 运行在ubuntu:20.04容器内从源码编译指定 CPython再用auditwheel repair修复二进制依赖保证 wheel 在较老 glibc 环境可安装。构建前还会把 Rust CLIov二进制打进openviking/bin/即 pip 装主包同时获得ov命令。内置冒烟测试构建完成后 workflow 会实际pip install该 wheel校验 RAGFS 绑定客户端、向量引擎过滤 ABI 符号以及 Web Studio 静态资源是否随包安装任何一项缺失即构建失败。verify-dockerjob 还揭示了一个值得注意的时序问题tag push 与 Release published 几乎同时发生release workflow 启动时镜像可能尚未构建完成因此该 job 会每 30 秒轮询一次build-docker-image.yml在该 tag 上的运行记录最多 60 次并进一步用docker buildx imagetools inspect断言 GHCR 与 Docker Hub 上版本 tag 与latesttag 的 digest 一致不一致则整个 release 判定失败。主包手动构建、测试发布与补发release.yml 同样支持workflow_dispatch手动触发输入参数target可选none只构建不发布testpypi发布到 TestPyPIpypi发布到 PyPIboth同时发布 TestPyPI 和 PyPI。此外还有build_sdist、build_wheels、os_json、python_json四个参数可用于只构建部分平台的 wheel 或缩减构建范围适合发版前验证。如果需要基于已有构建产物补发Python 包例如构建成功但发布步骤失败应使用 _publish.yml16. _Publish Distribution手动 dispatch 时必填build_run_id从对应 Build 运行 URL 中获取和目标渠道workflow 通过actions/download-artifact的跨 run 能力run-idGITHUB_TOKEN拉取原构建产物的python-package-distributions-*工件再走相同的pypa/gh-action-pypi-publish流程。该流程适合发布失败后的补发不建议作为正常主发版入口——正常发版一律走03. Release以保证 PyPI、Docker、TOS 三者的口径一致。Docker 镜像发布与补发Docker 镜像由 build-docker-image.ymlBuild and Push Docker Image构建触发条件有三类main分支 push产出maintag 镜像v*.*.*tag push产出版本 tag 镜像并同时打上latesttagtyperaw,valuelatest,enable${{ github.ref_type tag }}workflow_dispatch手动触发version输入框必填重建指定版本镜像。从 workflow 源码看其执行结构是按矩阵在ubuntu-24.04amd64与ubuntu-24.04-armarm64上分别 buildx 构建并推送同时推 GHCRghcr.io/owner/repo镜像名统一小写化和 Docker Hubdocker.io/DOCKERHUB_USERNAME/openviking各自输出push-by-digestdigestcreate-manifestjob 汇总两个架构的 digest artifact用docker buildx imagetools create为每个 tag 创建多架构 manifest版本解析分三种来源手动触发用输入值tag 触发用 tag 名main 分支则调用 build_support/versioning.py 的resolve_openviking_version()动态解析解析结果为空或0.0.0时直接以退出码 2 失败避免打出无版本镜像。需要特别理解的口径问题正式主发版时Docker 镜像实际就是由这条独立 workflow 在 tag push 时构建的而03. Releaseworkflow 只做等待与校验verify-docker-image轮询的正是build-docker-image.yml的运行记录。文档中“正式主发版时 Docker 镜像由主 release workflow 自动构建并发布”的表述从源码结构看更准确的描述是release 流水线与镜像构建流水线由同一 tag 事件并行触发、release 流水线负责验证镜像发布结果。使用建议与文档一致正式版本优先走主 release 流程tag Release只有镜像补发例如某个 tag 的 manifest 损坏或特殊验证时才单独使用workflow_dispatch指定版本重建且应保留已发布版本 tag 的可追溯性避免与正式 release 产物口径混淆。TOS 发布资产release-tos.yml 由 Release published 事件仅v前缀 tag或手动 dispatch 触发手动补发时必填tag如v0.3.24update_latest默认为 true。workflow 会 checkout 到对应 tag生成并上传以下资产到 TOS通过 AWS CLI 以 S3 协议访问 TOS endpointreleases/tag/openviking-tag-source.zip由git archive生成的源码包带immutable缓存头视为不可变资产releases/tag/memory-plugin-marketplace.zip与memory-plugins.gitmemory 插件的瘦身市场包与 dumb HTTP git 仓库供 Claude Code / Codex 等客户端离线安装Claude Code memory plugin、Codex memory plugin 及 shared 安装脚本各含install.sh与tos-install.sh的对应 TOS 版本副本当update_latesttrue时上述内容还会服务端拷贝/同步到releases/latest/与根路径稳定位置带no-store缓存头。两个重要的容错设计TOS secrets 未配置时不失败workflow 先检查TOS_ACCESS_KEY、TOS_SECRET_KEY、TOS_REGION、TOS_RELEASE_BUCKET、TOS_ENDPOINT五项 secrets任一缺失则跳过上传并在 step summary 中写明跳过原因——这保证 TOS 渠道的故障不会阻塞 PyPI/Docker 主发布。上传清单可审计所有成功上传的 key 会写入$GITHUB_STEP_SUMMARYrun 页面可直接看到本次发版落库了哪些资产、稳定安装脚本是否被更新。Python SDK 发版流程Python SDK 位于 sdk/pythonPyPI 包名为openviking-sdk使用独立 tag 命名空间python-sdkX.Y.Z。对应 python-sdk-release.ymlPython SDK Release合入 SDK 相关改动创建并推送 tag例如python-sdk0.1.3workflow 的build-sdkjob 由startsWith(github.event.release.tag_name, python-sdk)条件门控——主包v*tag 触发的 Release 不会误发 SDKjob 在sdk/python目录内运行python -m setuptools_scm解析版本其 tag 正则只匹配python-sdk*强校验 tag 与解析版本一致EXPECTED_TAGpython-sdk${SDK_VERSION}不相等直接exit 1。这一步确保“tag 写的是 0.1.3、但 git describe 解析出别的版本”这类错误在发布前被拦截python -m build构建后按事件类型决定目标Release 触发固定发 PyPI手动 dispatch 可选testpypi/pypi/both最终同样用pypa/gh-action-pypi-publishskip-existing幂等发布。Rust CLI / npm 发版流程Rust CLI 对应 rust-cli.ymlRust CLI Build由cli*tag push 触发另监听main与feat/rust-cli分支的 crates 路径变更做 CI 构建但不发布。构建矩阵覆盖 5 个平台并各自打包成一个 npm 平台包构建目标平台包x86_64-unknown-linux-muslopenviking/cli-linux-x64aarch64-unknown-linux-muslopenviking/cli-linux-arm64x86_64-apple-darwinopenviking/cli-darwin-x64aarch64-apple-darwinopenviking/cli-darwin-arm64x86_64-pc-windows-msvcopenviking/cli-win32-x64源码中可以看到几个关键工程决策Linux 产物采用 musl 静态构建workflow 安装 Zig cargo-zigbuild完成 musl 交叉编译使二进制不依赖运行环境的 glibc 版本注释明确说明这是为了兼容 CentOS 7 / RHEL 8 等旧 glibc 发行版版本注入tag 中的版本号通过sed注入 crates/ov_cli/Cargo.toml源文件中版本占位为0.0.0非 tag 构建则使用0.0.0-dev平台包按需生成每个平台的package.json由 workflow 现场生成写入os/cpu约束和bin文件npm 用户只需安装 wrapper 包 npm/cli幂等发布npm-publishjob 在 tag 事件下先npm view pkgversion检查已存在的版本直接跳过随后把 wrapper 包openviking/cli的version与全部optionalDependencies对齐到该版本再发布。OpenClaw / ClawHub 插件发布OpenClaw 插件通过 clawhub-dev-release.ymlOpenViking OpenClaw plugin release发布打包对象为 examples/openclaw-plugin。触发方式main分支上examples/openclaw-plugin/**路径变更自动触发或手动 dispatch。手动触发的输入参数version可选留空时由 workflow 按日期自动生成YYYY.M.D/YYYY.M.D-N/YYYY.M.D-dev.Nchannelauto、dev或latestpackage_ref指定打包的 git ref默认mainchangelog本次插件发布说明publish_clawhub/publish_npm分别控制是否发布到 ClawHub 和 npmopenviking/openclaw-plugin。从 workflow 结构看其guardjob 负责解析 channel 与 version结合CLAWHUB_UPSTREAM_REPOSITORY、CLAWHUB_LATEST_REPOSITORIES、CLAWHUB_DEV_REPOSITORIES、CLAWHUB_RELEASE_TIMEZONE等仓库变量决定 latest 与 dev 的发布来源并通过concurrency: openclaw-plugin-release不取消进行中的运行串行化发版避免连续合并时日期版本号解析互相竞争。发布形态上workflow 同时保留向 ClawHub 发布 legacy zip 工件兼容旧版 OpenClaw 的/download哈希机制和向 npm 发布打包 tarball 两条路径。推荐做法正式渠道使用latest或auto开发验证使用dev手动指定 version 时确保符合对应 channel 的格式要求YYYY.M.D系列。VikingBot 发布说明VikingBot 当前不再作为推荐的独立 PyPI 包发版路径维护现行分发方式是随主包发布Python 安装入口pip install openviking[bot]源码开发入口uv pip install -e .[bot]官方 Docker 镜像默认已包含 VikingBot可通过--without-bot或OPENVIKING_WITH_BOT0关闭。仓库状态与这一结论互相印证bot/目录下没有pyproject.toml、setup.py或setup.cfg已核实不存在因此无法从本仓库将其作为独立 Python 包发布。同时bot/.github/workflows/release.yml 位于bot子目录内应视为历史 bot 子项目或拆分仓库的发布参考不是根仓库当前可直接触发的 GitHub Actions workflow。如需恢复独立vikingbot包需要先在bot/下补齐独立的 Python 包配置、版本策略和发布凭证策略。发版前检查清单发版前建议逐项确认待发布改动已合入目标分支CI / PR 检查已通过版本号未在 PyPI、npm 或 Docker registry 中发布过tag 命名符合对应产物约定v*/python-sdk*/cli*/YYYY.M.D*Python 包依赖、构建配置和 README 已同步更新Docker Hub、PyPI/TestPyPI、TOS、npm、ClawHub 等发布所需 secrets 或 trusted publishing 配置可用Release notes 已准备好且说明破坏性变更、迁移步骤和重要修复。发版后验证清单发版后建议验证PyPI / TestPyPI 上的包版本与 tag 一致pip install openvikingversion或pip install openviking-sdkversion可成功安装Docker registry 中存在版本 tag 和预期的latest/maintag多架构 Docker manifest 可正常拉取03. Release的verify-dockerjob 会自动做 digest 级校验TOS 版本化路径和稳定路径可访问npm 上存在对应 CLI 平台包5 个和 wrapper 包openviking/cliClawHub 插件 channel 和 version 符合预期。故障处理与补发原则PyPI 和 npm 已发布版本通常不可覆盖如包内容有误应发布新版本两条流水线的skip-existing/npm view检查正是为此设计的幂等防线。Docker 的latest、main和手动指定 tag可通过独立 Docker workflow 重建但应保留已发布版本 tag 的可追溯性。TOS 的版本化路径应视为不可变资产上传时显式写入immutable缓存头稳定路径可通过手动 workflow 的update_latest覆盖。构建成功但发布失败时优先使用补发 workflow16. _Publish Distribution传入build_run_id或手动 dispatch避免重新创建不同内容的同名 tag。tag 命名错误时优先删除错误 tag 并重新创建正确 tag前提是该 tag 尚未触发不可逆发布PyPI 上传属于不可逆操作。综上OpenViking 的发布体系核心是“tag 命名空间隔离 workflow 前缀门控 幂等发布 独立的构建/发布分层”主包、SDK、CLI 各自用正则有界的 tag 解析版本发布动作全部走skip-existing幂等通道构建15. _Build Distribution与发布16. _Publish Distribution解耦使任何一次发布失败都能在不重建产物的前提下安全补发。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考