Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
OpenViking 发版说明
本文说明 OpenViking 仓库的发版目标、版本与 tag 约定、主要发版流程,以及补发和验证方式。内容以仓库中已追踪的 GitHub Actions、构建配置和包配置为准。
发版目标
OpenViking 的发版目标不是单一产物,而是围绕不同使用入口发布一组相互关联的资产:
openvikingPython 主包:面向本地运行时、服务端、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 安装
ovCLI 的用户。 - 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:
- 确认待发布改动已合入目标分支,且 PR / main 分支检查通过。
- 创建主包 tag,例如
v0.3.26。 - 在 GitHub 上基于该 tag 发布 Release。
03. Releaseworkflow 会在 Release published 时触发。- workflow 复用
_Build Distribution构建 sdist 和多平台 wheel。 - workflow 将构建产物发布到 PyPI。
- workflow 构建并推送多架构 Docker 镜像。
Release TOS Uploadworkflow 会上传源码 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 构建这全部内容。
在那里不发产品版本、单独发布插件热修复:
- 合入修复,并按
.github/scripts/check-plugin-version-bumps.sh的要求升级插件版本。Claude Code 只在版本号变化时更新已安装的插件。 - 在“上一个正式版本 + 修复”的 commit 上打 tag,例如从上一个
vX.Y.Ztag 拉分支并 cherry-pick 修复。tag 不要以v开头,例如memory-plugins-YYYY.M.D,也不要为它发布 GitHub Release:推送v*.*.*tag 会触发 Docker workflow,发布 Release 会触发主包发版 workflow,主包版本号也从v*tag 解析。 - 推送 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]
典型流程:
- 合入 SDK 相关改动。
- 创建并推送 tag,例如
[email protected]。 Python SDK Releaseworkflow 被 tag 触发。- workflow 使用
setuptools_scm解析 SDK 版本。 - workflow 校验当前 tag 是否等于
python-sdk@<resolved-version>。 - workflow 构建
sdk/python并发布到 PyPI。
SDK workflow 也支持手动触发,并可选择 testpypi、pypi 或 both。手动触发适合验证和补发;正式 SDK 发版建议使用 [email protected] tag。
Microsoft Agent Framework 发版流程
适配包位于 integrations/frameworks/microsoft-agent-framework,版本在该目录的 pyproject.toml 中独立维护。
- 合入适配包改动,并确认集成检查通过。
- 手动运行
Microsoft Agent Framework Integration Release,选择testpypi,验证发布的 wheel 可以安装和导入。 - 在已测试的提交上创建
[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/maintag。 - 多架构 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 尚未触发不可逆发布。