Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

15.5 KB
Raw Blame

OpenViking 发版说明

本文说明 OpenViking 仓库的发版目标、版本与 tag 约定、主要发版流程,以及补发和验证方式。内容以仓库中已追踪的 GitHub Actions、构建配置和包配置为准。

发版目标

OpenViking 的发版目标不是单一产物,而是围绕不同使用入口发布一组相互关联的资产:

  • openviking Python 主包:面向本地运行时、服务端、CLI 及完整功能用户。
  • Python SDK openviking-sdk:面向只通过 HTTP 调用已有 OpenViking 服务的轻量客户端用户。
  • Microsoft Agent Framework 适配包 openviking-ms-agent-framework:面向连接已有 OpenViking 服务的 MAF 应用。
  • Docker 镜像:面向容器化部署,发布到 GHCR 和 Docker Hub。
  • TOS 发布资产:面向源码包、安装脚本和稳定下载路径。
  • Rust CLI / npm 包:面向通过 npm 安装 ov CLI 的用户。
  • OpenClaw / ClawHub 插件:面向 OpenClaw 插件分发渠道。
  • VikingBot:当前随 openviking[bot] 和官方 Docker 镜像分发;历史独立发版入口单独说明,避免误用。

一次正式主版本发版应确保 Python 包、Docker 镜像和 TOS 资产使用同一个主版本 tag;SDK、CLI、ClawHub 插件则使用各自独立的 tag 或 version 命名空间。

版本与 tag 约定

推荐使用以下 tag 约定:

产物 推荐 tag / version 说明
openviking 主包 vX.Y.Z 主 release tag,例如 v0.3.26。
openviking-sdk [email protected] SDK 专用 tag,例如 [email protected]。
openviking-ms-agent-framework [email protected] 必须与 integrations/frameworks/microsoft-agent-framework/pyproject.toml 中的版本一致。
Rust CLI / npm CLI [email protected] CLI 专用 tag,例如 [email protected]。
Vika(vika/) [email protected] 必须与 vika/package.json 中的版本一致,见 Vika 发版流程。
ClawHub 插件 latest YYYY.M.D 或 YYYY.M.D-N 由 workflow 自动生成或手动指定。
ClawHub 插件 dev YYYY.M.D-dev.N dev channel 使用。

主包版本通过 setuptools_scm 从 Git tag 解析;正式主发版建议统一使用 vX.Y.Z。SDK 版本同样通过 setuptools_scm 解析,但只匹配 python-sdk@* tag,以避免和主包 tag 混淆。

正式主包发版流程

主包正式发版走根目录 GitHub Release:

  1. 确认待发布改动已合入目标分支,且 PR / main 分支检查通过。
  2. 创建主包 tag,例如 v0.3.26。
  3. 在 GitHub 上基于该 tag 发布 Release。
  4. 03. Release workflow 会在 Release published 时触发。
  5. workflow 复用 _Build Distribution 构建 sdist 和多平台 wheel。
  6. workflow 将构建产物发布到 PyPI。
  7. workflow 构建并推送多架构 Docker 镜像。
  8. Release TOS Upload workflow 会上传源码 zip 和安装脚本到 TOS。

正式主发版的发布目标包括:

  • PyPI:openviking
  • GHCR:ghcr.io/<owner>/<repo>
  • Docker Hub:<dockerhub-user>/openviking
  • TOS:版本化 release 路径和可选 latest 稳定路径

主包手动构建、测试发布与补发

根目录 release workflow 也支持手动触发,可选择发布目标:

  • none:只构建,不发布。
  • testpypi:发布到 TestPyPI。
  • pypi:发布到 PyPI。
  • both:同时发布 TestPyPI 和 PyPI。

如需基于已有构建产物补发 Python 包,可使用 _Publish Distribution workflow,并传入对应的 build run id。该流程适合发布失败后的补发,不建议作为正常主发版入口。

Docker 镜像发布与补发

正式主发版时,Docker 镜像由主 release workflow 自动构建并发布。镜像会推送到 GHCR 和 Docker Hub,并在正式 release 下写入版本 tag 与 latest tag。

仓库还提供独立的 Build and Push Docker Image workflow,适用于:

  • 手动指定版本重建镜像。
  • main 分支镜像构建。
  • tag 触发后的镜像补发。

注意:独立 Docker workflow 当前也会在 v*.*.* tag push 时自动触发。正式 GitHub Release 的发布口径仍以 03. Release workflow 为准;独立 Docker workflow 应视为镜像专用构建或补发路径,避免与正式 release 产物口径混淆。

为避免重复发布,正式版本优先使用主 release workflow;只有镜像补发或特殊验证时才使用独立 Docker workflow。

TOS 发布资产

TOS 发布流程会生成源码 zip,并上传以下类型资产:

  • releases/<tag>/openviking-<tag>-source.zip
  • Claude Code memory plugin 安装脚本
  • Codex memory plugin 安装脚本
  • 对应 TOS install 脚本

正式 GitHub Release 会自动触发 TOS 上传,并覆盖稳定路径。手动触发时指定 tag,workflow 上传该 tag 的版本化路径;只有设置 update_latest=true(默认 false)才会覆盖稳定路径,因此补传旧版本的资产不会把用户退回到旧版本。

如果 TOS 相关 secrets 未配置完整,workflow 会跳过上传并在 step summary 中说明,不会使整个流程失败。

文档站上的 Memory 插件下载

安装器和 Memory 插件从文档站下载,不再从 TOS 发布桶下载。两条文档部署流水线(17. Docs 部署到 GitHub Pages 的 docs.openviking.ai,19. Docs TOS Deploy 部署到 docs.openviking.net)都会运行 .github/scripts/build-plugin-downloads.sh,把产物发布到 /dl 下,目录结构与发布桶一致:memory-plugin-shared/install.sh 和 bootstrap.sh、releases/latest/memory-plugin-marketplace.zip、plugins/claude/marketplace.json 和 plugins/claude/openviking-memory-<插件版本>.zip、plugins/memory-plugins.git,以及安装站点的版本检查读取的 releases/latest/channels.json。

只要推送到 main 的提交改动了文档、插件、安装器或 .github/scripts,两条流水线就会部署,所以插件改动合入即发布,不需要打 tag,也不需要发 GitHub Release。发布出去的安装器以 <日期>-<commit> 作为版本号。发布插件修复时,合入修复并按 .github/scripts/check-plugin-version-bumps.sh 的要求升级插件版本;回滚时在 main 上 revert 该改动并再次升级版本号。两条流水线也可以在 main 上手动触发。

TOS 发布桶仍会随每次发版收到同样的文件,供仍指向它的安装使用,见下文。

TOS 上的 Memory 插件热修复与回滚

指向 TOS 发布桶的安装读它的稳定路径:plugins/claude/marketplace.json(Claude Code)、plugins/memory-plugins.git(Codex 和 TraeCode CLI)、releases/latest/memory-plugin-marketplace.zip(其他所有宿主)、releases/latest/channels.json(安装时的版本解析),以及 memory-plugin-shared/install.sh 和 bootstrap.sh。workflow 每次运行都从所给 tag 对应的 commit 构建这全部内容。

在那里不发产品版本、单独发布插件热修复:

  1. 合入修复,并按 .github/scripts/check-plugin-version-bumps.sh 的要求升级插件版本。Claude Code 只在版本号变化时更新已安装的插件。
  2. 在“上一个正式版本 + 修复”的 commit 上打 tag,例如从上一个 vX.Y.Z tag 拉分支并 cherry-pick 修复。tag 不要以 v 开头,例如 memory-plugins-YYYY.M.D,也不要为它发布 GitHub Release:推送 v*.*.* tag 会触发 Docker workflow,发布 Release 会触发主包发版 workflow,主包版本号也从 v* tag 解析。
  3. 推送 tag,然后运行 gh workflow run release-tos.yml -f tag=<tag> -f update_latest=true。

回滚时运行 gh workflow run release-tos.yml -f tag=<上一个正常的 tag> -f update_latest=true。workflow 定义取自默认分支,但它调用的脚本来自 tag 的 checkout,所以只能重新发布已经包含当前发布脚本的 tag;要退回更早的插件代码,按热修复流程发布。

两种操作完成后,Claude Code(URL marketplace)在下次检查更新时生效,版本号变低也算更新。Codex 在下次启动时生效,TraeCode CLI 在执行 trae-cli plugin marketplace upgrade 时生效。Cursor、TRAE、TRAE CN、ZCode、Kimi Code、OpenCode、pi,以及使用本地目录 marketplace 的 Claude Code,需要重新运行安装器才会变化。dsh 从 npm 安装,不受影响。

Python SDK 发版流程

Python SDK 位于 sdk/python,PyPI 包名为 openviking-sdk。SDK 使用独立 tag 命名空间:

[email protected]

典型流程:

  1. 合入 SDK 相关改动。
  2. 创建并推送 tag,例如 [email protected]。
  3. Python SDK Release workflow 被 tag 触发。
  4. workflow 使用 setuptools_scm 解析 SDK 版本。
  5. workflow 校验当前 tag 是否等于 python-sdk@<resolved-version>。
  6. workflow 构建 sdk/python 并发布到 PyPI。

SDK workflow 也支持手动触发,并可选择 testpypi、pypi 或 both。手动触发适合验证和补发;正式 SDK 发版建议使用 [email protected] tag。

Microsoft Agent Framework 发版流程

适配包位于 integrations/frameworks/microsoft-agent-framework,版本在该目录的 pyproject.toml 中独立维护。

  1. 合入适配包改动,并确认集成检查通过。
  2. 手动运行 Microsoft Agent Framework Integration Release,选择 testpypi,验证发布的 wheel 可以安装和导入。
  3. 在已测试的提交上创建 [email protected] tag,并基于它发布 GitHub Release,使用 gh release create <tag> --latest=false 避免替换主包的 latest Release。workflow 会校验 tag 与包版本一致,运行离线契约测试、构建产物并发布到 PyPI。

手动触发还支持 pypi 和 both,用于发布和补发。仅推送 tag 不会触发此 workflow。

分别在 PyPI 和 TestPyPI 配置 GitHub Trusted Publisher:仓库为 volcengine/OpenViking,workflow 文件名为 python-agent-framework-release.yml,environment 分别为 pypi 和 testpypi。首次发版时,以包名 openviking-ms-agent-framework 注册 pending publisher。发布通过 OIDC 完成认证。

Rust CLI / npm 发版流程

Rust CLI 的 tag 格式为:

[email protected]

推送 cli@* tag 后,Rust CLI Build workflow 会为多个平台构建 ov 二进制,并发布 npm 包:

  • 平台包:@openviking/cli-linux-x64、@openviking/cli-linux-arm64、@openviking/cli-darwin-x64、@openviking/cli-darwin-arm64、@openviking/cli-win32-x64
  • wrapper 包:@openviking/cli

workflow 会把 tag 中的版本写入平台包和 wrapper 包。如果 npm 上已存在同版本包,workflow 会跳过已发布版本。

Vika 发版流程

Vika(vika/)按平台发布自包含的安装包:linux-x64、linux-arm64、darwin-x64、darwin-arm64,每个都自带 Node 和依赖。Vika Release workflow(vika-release.yml)负责测试、构建并上传到 TOS 发布桶的 vika/ 下:

  • vika/releases/<版本>/:安装包及其 .sha256、install.sh,以及最后上传的 release.json。每个版本只发布一次:同一版本的另一份构建已经上传时,workflow 直接停止;重跑失败的发布 job 会把同一份构建发布完。发布 job 依次执行,不会并行。
  • vika/install.sh 和 vika/latest:最后写入,只有比当前 vika/latest 更新的正式版才会更新。用户用 curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/vika/install.sh | sh 安装,vika upgrade 按 vika/latest 升级。版本更旧的 tag(例如旧版本线上的热修复)或带 - 的 tag(例如 [email protected])只发布自己的版本目录;带 - 的版本在 GitHub 上标记为预发布。

正式发版:在 vika/package.json 中设定版本并合入,然后推送与之一致的 [email protected] tag。tag 不能以 v 开头:推送 v*.*.* tag、为 v* tag 发布 Release 都会触发主包的 workflow。workflow 同时为该 tag 创建 GitHub Release,不会将其标记为仓库的最新 Release。

分支预览:在该分支上运行 workflow,可以在 Actions 页面操作,也可以执行 gh workflow run vika-release.yml --ref <分支>。它发布 <package 版本>-<commit>,不改动 vika/latest,运行摘要里给出安装命令。发布需要 TOS secrets,所以只能预览本仓库内的分支。

改动 vika/ 的 PR 会跑测试,并构建、检查 linux-x64 安装包,但不发布。

workflow 使用与 release-tos.yml 相同的 TOS secrets。仓库变量 VIKA_DOWNLOAD_BASE 和 VIKA_TOS_PREFIX 可以覆盖公开地址和 key 前缀,例如在 fork 中对着测试桶演练。

OpenClaw / ClawHub 插件发布

OpenClaw 插件通过 ClawHub release (OpenViking plugin) workflow 手动发布。输入参数包括:

  • version:可选;为空时由 workflow 按日期自动生成。
  • channel:auto、dev 或 latest。
  • changelog:本次插件发布说明。

workflow 会先解析 channel 和 version,再打包 examples/openclaw-plugin,推送生成的 package branch,最后调用 ClawHub 官方 trusted publishing workflow 发布。

推荐做法:

  • 正式渠道使用 latest 或 auto。
  • 开发验证使用 dev。
  • 手动指定 version 时,确保符合对应 channel 的格式要求。

VikingBot 发布说明

VikingBot 当前不再作为推荐的独立 PyPI 包发版路径维护。现行分发方式是随主包发布:

  • Python 安装入口:pip install "openviking[bot]"。
  • 源码开发入口:uv pip install -e ".[bot]"。
  • 官方 Docker 镜像默认已包含 VikingBot,可通过 --without-bot 或 OPENVIKING_WITH_BOT=0 关闭。

根仓库原有的 First Release to PyPI workflow 已删除。当前 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 命名符合对应产物约定。
  • Python 包依赖、构建配置和 README 已同步更新。
  • Docker Hub、PyPI/TestPyPI、TOS、npm、ClawHub 等发布所需 secrets 或 trusted publishing 配置可用。
  • Release notes 已准备好,且说明破坏性变更、迁移步骤和重要修复。

发版后验证清单

发版后建议验证:

  • PyPI / TestPyPI 上的包版本与 tag 一致。
  • pip install openviking==<version> 或 pip install openviking-sdk==<version> 可成功安装。
  • Docker registry 中存在版本 tag 和预期的 latest / main tag。
  • 多架构 Docker manifest 可正常拉取。
  • TOS 版本化路径和稳定路径可访问。
  • npm 上存在对应 CLI 平台包和 wrapper 包。
  • ClawHub 插件 channel 和 version 符合预期。

故障处理与补发原则

  • PyPI 和 npm 已发布版本通常不可覆盖;如包内容有误,应发布新版本。
  • Docker 的 latest、main 和手动指定 tag 可通过镜像补发 workflow 重建,但应保留已发布版本 tag 的可追溯性。
  • TOS 的版本化路径应视为不可变资产;稳定路径可通过手动 workflow 覆盖。
  • 如果构建成功但发布失败,优先使用补发 workflow 或手动 dispatch,避免重新创建不同内容的同名 tag。
  • 如 tag 命名错误,优先删除错误 tag 并重新创建正确 tag,前提是该 tag 尚未触发不可逆发布。