Skip to content

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

feat(openclaw): add TOS release installer flow (#2653)

Mingjian Queccf00aa8a4f1
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md
index 7486f7aa2..066e9bd41 100644
--- a/examples/openclaw-plugin/INSTALL-ZH.md
+++ b/examples/openclaw-plugin/INSTALL-ZH.md
@@ -51,18 +51,15 @@ openclaw --version
如果你使用的是火山控制台创建的 OpenViking Service 库,不需要启动本地 `openviking-server`。从控制台复制 OpenViking Service 的 server url、API Key,并按需配置 peer 标识:
```bash
-openclaw plugins install clawhub:@openviking/openclaw-plugin
-openclaw openviking setup \
- --base-url "https://api.vikingdb.cn-beijing.volces.com/openviking" \
- --api-key "<your-openviking-service-api-key>" \
- --json
-openclaw gateway restart
-openclaw openviking status --json
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<your-openviking-service-api-key>" \
+bash scripts/install.sh --json
```
这条命令会完成:
-- 通过 ClawHub 安装 OpenViking 插件。
+- 默认从 TOS `latest` 安装 OpenViking 插件。
+- 写入 `$OPENCLAW_STATE_DIR/openviking.env`,默认是 `~/.openclaw/openviking.env`,权限为 `0600`。
- 调用 `openclaw openviking setup --base-url ... --api-key ...` 写入插件配置。
- 重启 `openclaw gateway`。
- 执行 `openclaw openviking status --json` 和 `openclaw config get plugins.slots.contextEngine` 验证。
@@ -70,32 +67,32 @@ openclaw openviking status --json
如果需要把 OpenClaw assistant 说话人写成独立 `peer_id`,并让数据面 recall/search 使用对应 actor peer 视图,可以额外传:
```bash
-openclaw openviking setup \
- --base-url "https://api.vikingdb.cn-beijing.volces.com/openviking" \
- --api-key "<your-openviking-service-api-key>" \
- --peer-role assistant \
- --peer-prefix "openclaw-prod" \
- --json
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<your-openviking-service-api-key>" \
+OPENVIKING_PEER_ROLE="assistant" \
+OPENVIKING_PEER_PREFIX="openclaw-prod" \
+bash scripts/install.sh --json
```
如果使用 root key 或可信服务身份,补充租户信息:
```bash
-openclaw openviking setup \
- --base-url "https://api.vikingdb.cn-beijing.volces.com/openviking" \
- --api-key "<root-key>" \
- --account-id "<account-id>" \
- --user-id "<user-id>" \
- --json
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<root-key>" \
+OPENVIKING_ACCOUNT_ID="<account-id>" \
+OPENVIKING_USER_ID="<user-id>" \
+bash scripts/install.sh --json
```
-本地源码验证:
+离线下载包安装:
```bash
-npm install
-npm run typecheck
-npm test
-npm run build
+sh build.sh
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<your-openviking-service-api-key>" \
+OPENVIKING_PEER_ROLE="assistant" \
+OPENVIKING_PEER_PREFIX="openclaw-prod" \
+bash output/install.sh --source tarball --tarball output/openviking.tgz --json
```
接入后,在火山 OpenViking Service 控制台检查:
@@ -405,4 +402,4 @@ openclaw openviking status --json
bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
```
-另见:[INSTALL.md](./INSTALL.md) 和 [INSTALL-AGENT.md](./INSTALL-AGENT.md)。
+另见:[INSTALL.md](./INSTALL.md)、[INSTALL-AGENT.md](./INSTALL-AGENT.md) 和 [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md)。
diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.md
index 19ce58889..b99f0cf4b 100644
--- a/examples/openclaw-plugin/INSTALL.md
+++ b/examples/openclaw-plugin/INSTALL.md
@@ -363,4 +363,4 @@ Or use the cleanup script:
bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
```
-See also: [INSTALL-ZH.md](./INSTALL-ZH.md) and [INSTALL-AGENT.md](./INSTALL-AGENT.md).
+See also: [INSTALL-ZH.md](./INSTALL-ZH.md), [INSTALL-AGENT.md](./INSTALL-AGENT.md), and [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md).
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index dd1f7399f..d2ad2c584 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/README.md
@@ -74,6 +74,7 @@ openclaw config get plugins.slots.contextEngine # should output: openviking
| [INSTALL.md](./INSTALL.md) | Full install, upgrade, and uninstall guide |
| [INSTALL-ZH.md](./INSTALL-ZH.md) | Chinese install guide |
| [INSTALL-AGENT.md](./INSTALL-AGENT.md) | Agent-oriented operator guide |
+| [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md) | TOS release bundle publishing and installer guide |
| [docs/openviking-openclaw-plugin-guide.md](./docs/openviking-openclaw-plugin-guide.md) | Comprehensive Chinese guide for usage, configuration, debugging, testing, build, release, deployment, and rollback |
| [docs/openviking-websocket-rpc-api.md](./docs/openviking-websocket-rpc-api.md) | Gateway WebSocket RPC usage for OpenViking tools |
| [docs/openviking-runtime-query-config.md](./docs/openviking-runtime-query-config.md) | Runtime query config scopes, fields, and commands |
diff --git a/examples/openclaw-plugin/build.sh b/examples/openclaw-plugin/build.sh
new file mode 100755
index 000000000..75e090ad1
--- /dev/null
+++ b/examples/openclaw-plugin/build.sh
@@ -0,0 +1,137 @@
+#!/bin/bash
+
+set -euo pipefail
+
+trap 'echo "Build failed." >&2' ERR
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT_DIR"
+
+PACKAGE_VERSION=$(npm pkg get version | tr -d '"')
+VERSION="${BUILD_VERSION:-$PACKAGE_VERSION}"
+RELEASE_PATH="${BUILD_RELEASE_PATH:-latest}"
+PACKAGE_NAME="openviking"
+OUTPUT_DIR="$ROOT_DIR/output"
+TGZ_RELATIVE_PATH="output/openviking.tgz"
+INSTALL_RELATIVE_PATH="output/install.sh"
+VOLCENGINE_INSTALL_RELATIVE_PATH="output/volcengine-install.sh"
+TGZ_PATH="$ROOT_DIR/$TGZ_RELATIVE_PATH"
+INSTALL_OUTPUT="$ROOT_DIR/$INSTALL_RELATIVE_PATH"
+VOLCENGINE_INSTALL_OUTPUT="$ROOT_DIR/$VOLCENGINE_INSTALL_RELATIVE_PATH"
+STAGING_DIR=""
+TAR_CREATE_FLAGS=(--exclude='._*' --exclude='.DS_Store' -zcf)
+
+supports_tar_flag() {
+ local flag="$1"
+ tar "$flag" -cf /dev/null --files-from /dev/null >/dev/null 2>&1
+}
+
+if supports_tar_flag "--no-xattrs"; then
+ TAR_CREATE_FLAGS=(--no-xattrs "${TAR_CREATE_FLAGS[@]}")
+fi
+if supports_tar_flag "--disable-copyfile"; then
+ TAR_CREATE_FLAGS=(--disable-copyfile "${TAR_CREATE_FLAGS[@]}")
+fi
+
+cleanup() {
+ case "${STAGING_DIR:-}" in
+ "$OUTPUT_DIR"/.package.*)
+ if [ -d "$STAGING_DIR" ]; then
+ rm -rf "$STAGING_DIR"
+ fi
+ ;;
+ esac
+}
+trap cleanup EXIT
+
+info() {
+ echo "[openviking] $*"
+}
+
+require_file() {
+ local path="$1"
+ if [ ! -f "$path" ]; then
+ echo "Required file is missing: $path" >&2
+ exit 1
+ fi
+}
+
+require_dir() {
+ local path="$1"
+ if [ ! -d "$path" ]; then
+ echo "Required directory is missing: $path" >&2
+ exit 1
+ fi
+}
+
+copy_optional_file() {
+ local path="$1"
+ local target_dir="$2"
+ if [ -f "$path" ]; then
+ cp "$path" "$target_dir/"
+ else
+ echo "Optional file is missing, skipped: $path" >&2
+ fi
+}
+
+info "Building OpenViking plugin package $VERSION"
+rm -rf dist "$OUTPUT_DIR"
+
+info "Installing dependencies"
+npm install
+
+info "Running checks"
+npm run typecheck
+npm test
+npm run build
+
+require_file "dist/index.js"
+require_file "dist/commands/setup.js"
+require_file "package.json"
+require_file "openclaw.plugin.json"
+require_file "install-manifest.json"
+require_file "config/feature-gates.json"
+require_dir "skills"
+require_file "scripts/install.sh"
+require_file "scripts/volcengine-openviking-install.sh"
+
+mkdir -p "$OUTPUT_DIR"
+STAGING_DIR=$(mktemp -d "$OUTPUT_DIR/.package.XXXXXX")
+require_dir "$STAGING_DIR"
+PACKAGE_DIR="$STAGING_DIR/$PACKAGE_NAME"
+mkdir -p "$PACKAGE_DIR"
+
+info "Staging package files"
+cp package.json "$PACKAGE_DIR/"
+BUILD_VERSION="$VERSION" node -e 'const fs=require("fs"); const path=process.argv[1]; const pkg=JSON.parse(fs.readFileSync(path,"utf8")); pkg.version = process.env.BUILD_VERSION; fs.writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`);' "$PACKAGE_DIR/package.json"
+cp openclaw.plugin.json "$PACKAGE_DIR/"
+cp install-manifest.json "$PACKAGE_DIR/"
+cp -R config "$PACKAGE_DIR/"
+cp -R dist "$PACKAGE_DIR/"
+cp -R skills "$PACKAGE_DIR/"
+copy_optional_file "README.md" "$PACKAGE_DIR"
+copy_optional_file "INSTALL.md" "$PACKAGE_DIR"
+copy_optional_file "INSTALL-ZH.md" "$PACKAGE_DIR"
+copy_optional_file "INSTALL-AGENT.md" "$PACKAGE_DIR"
+
+info "Installing production dependencies into package"
+npm install --omit=dev --ignore-scripts --no-audit --no-fund --package-lock=false --prefix "$PACKAGE_DIR" # npm install --omit=dev
+require_dir "$PACKAGE_DIR/node_modules/@sinclair/typebox"
+
+sed \
+ -e "s/^VERSION=\".*\"/VERSION=\"$VERSION\"/" \
+ -e "s#^RELEASE_PATH=\"\${INSTALL_RELEASE_PATH:-.*}\"#RELEASE_PATH=\"\${INSTALL_RELEASE_PATH:-$RELEASE_PATH}\"#" \
+ scripts/install.sh > "$INSTALL_OUTPUT"
+chmod +x "$INSTALL_OUTPUT"
+cp scripts/volcengine-openviking-install.sh "$VOLCENGINE_INSTALL_OUTPUT"
+chmod +x "$VOLCENGINE_INSTALL_OUTPUT"
+
+info "Creating $TGZ_PATH"
+COPYFILE_DISABLE=1 tar "${TAR_CREATE_FLAGS[@]}" "$TGZ_PATH" -C "$STAGING_DIR" "$PACKAGE_NAME"
+
+echo
+info "Build complete"
+echo "Package: $TGZ_RELATIVE_PATH"
+echo "Installer: $INSTALL_RELATIVE_PATH"
+echo "Volcengine installer: $VOLCENGINE_INSTALL_RELATIVE_PATH"
+echo "Version: $VERSION"
diff --git a/examples/openclaw-plugin/docs/openviking-install-real-scenario-verification-report.md b/examples/openclaw-plugin/docs/openviking-install-real-scenario-verification-report.md
new file mode 100644
index 000000000..7a95b6662
--- /dev/null
+++ b/examples/openclaw-plugin/docs/openviking-install-real-scenario-verification-report.md
@@ -0,0 +1,427 @@
+# OpenViking 本机安装真实场景验证报告
+
+> 日期:2026-06-05
+> 分支:`feat/sharClawWithOpenViKing`
+> 仓库:`iaasng/arkclaw-openviking-plugin`
+> 本机 OpenClaw:`OpenClaw 2026.5.28 (e932160)`
+> 安装插件版本:`2026.6.2`
+> OpenViking 服务:`https://api.vikingdb.cn-beijing.volces.com/openviking`,健康检查版本 `v0.3.21`
+> 结论:安装、配置、真实 agent 调用、HTTP 接口、WebSocket RPC、JSONL 召回轨迹、边界用例均已完成验证;发现并修复了 HTTP route 注册兼容问题与 Gateway 查询参数大小写/别名问题。
+
+## 1. 验证目标
+
+本次验证基于本机已安装的 `openclaw` 和本仓库构建出的 OpenViking 插件包,覆盖以下目标:
+
+1. 安装包能真实安装到 `~/.openclaw/extensions/openviking`,并被 OpenClaw Gateway 加载。
+2. 插件配置符合预期:remote 模式、API key 可用、`traceRecall` 和 `traceRecallPersist` 开启、资源召回范围配置正确。
+3. OpenClaw agent 真实场景可调用 `ov_search`,返回 OpenViking `viking://` URI。
+4. Recall Trace HTTP API 注册并可访问,成功响应和边界错误响应符合预期。
+5. OpenClaw Gateway WebSocket RPC 能发现 OpenViking 工具,并可通过 `tools.invoke` 调用 `ov_search`、`ov_read`、`memory_recall` 等插件工具。
+6. Recall trace JSONL 能写入本地磁盘,结构符合 `RecallTraceEntry` schema,条数符合配置上限。
+7. 单测、类型检查、构建流程通过,避免回归。
+
+## 2. 关键实现与修复位置
+
+| 项目 | 说明 | 代码位置 |
+|---|---|---|
+| 兼容 OpenClaw 新 HTTP route API | 同时支持 legacy `registerRoute` 与现代 `registerHttpRoute` | `index.ts:885`、`index.ts:887`、`index.ts:888` |
+| HTTP route 注册 | 注册 `/api/openviking/recall-traces`、`:traceId`、`uri-detail`、`latest-ov-search-list` | `index.ts:1144`、`index.ts:1187`、`index.ts:1198` |
+| HTTP 响应包装 | 统一 `Content-Type: application/json`,非 GET 返回 405 | `index.ts:1164`、`index.ts:1173` |
+| Gateway session key 参数别名 | 兼容 `sessionkey`、`session_key`、`session-key`,避免 HTTP 层对 camelCase/保留字段处理导致查不到 trace | `index.ts:917`、`index.ts:1049`、`index.ts:1135` |
+| Gateway RPC trace 默认身份 | `ov_recall_trace` 默认使用外层 `params.sessionKey` 查询当前 session trace;仅显式传 `args.sessionKey/sessionId/ovSessionId/traceId` 时按显式过滤条件查询 | `index.ts:829`、`index.ts:855`、`index.ts:893` |
+| 历史 JSONL 身份兼容 | 默认 `sessionKey` 查询未命中时,fallback 到当前 session 的 `sessionId/ovSessionId`,兼容旧版本或 web session 只按 UUID 落盘的 trace | `index.ts:901`、`index.ts:908`、`index.ts:911` |
+| JSONL 持久化 | 每天一个 JSONL 文件,按 schema 写入并支持查询回退 | `recall-trace.ts:256`、`recall-trace.ts:284`、`recall-trace.ts:431` |
+| 配置归一化 | `traceRecall`、`traceRecallPersist`、`traceRecallDir`、`traceRecallMaxEntries` 等配置归一化 | `config.ts:525`、`config.ts:526`、`config.ts:527`、`config.ts:543` |
+| 回归测试 | HTTP route 注册、session key alias 查询新增测试覆盖 | `tests/ut/tools.test.ts:1317`、`tests/ut/tools.test.ts:1446` |
+
+## 3. 安装与配置验证
+
+### 3.1 构建与安装
+
+执行:
+
+```bash
+./build.sh
+./output/install.sh --source local --tarball ./output/openviking.tgz --openclaw-state-dir "$HOME/.openclaw"
+```
+
+结果:
+
+- `./build.sh` 成功生成:
+ - `output/openviking.tgz`
+ - `output/install.sh`
+ - `output/volcengine-install.sh`
+- 安装脚本成功部署到:`/Users/bytedance/.openclaw/extensions/openviking`
+- `openclaw openviking status --json` 返回健康:
+ - `health.ok=true`
+ - `health.version=v0.3.21`
+ - `health.pluginVersion=2026.6.2`
+ - `slotActive=true`
+
+### 3.2 插件运行时注册
+
+执行:
+
+```bash
+openclaw plugins inspect openviking --runtime --json
+```
+
+结果:
+
+- `status=loaded`
+- `contextEngineIds=["openviking"]`
+- `services=["openviking"]`
+- `commands=["add-resource","add-skill","ov-search","ov-query-config","ov-recall-trace"]`
+- `toolNames` 包含 `ov_search`、`ov_read`、`memory_recall`、`ov_recall_trace`
+- `httpRouteCount=4`,符合预期。
+
+### 3.3 验证配置
+
+执行:
+
+```bash
+openclaw config get plugins.entries.openviking.config --json
+```
+
+关键配置已恢复并验证:
+
+```json
+{
+ "mode": "remote",
+ "traceRecall": true,
+ "traceRecallPersist": true,
+ "traceRecallDir": "/Users/bytedance/.openclaw/openviking/recall-traces",
+ "traceRecallMaxEntries": 200,
+ "traceRecallMaxResultsPerSearch": 20,
+ "recallTargetTypes": ["resource"],
+ "autoRecall": true,
+ "autoCapture": true,
+ "logFindRequests": true,
+ "emitStandardDiagnostics": true,
+ "commitTokenThreshold": 1
+}
+```
+
+## 4. 测试用例与结果
+
+| ID | 测试项 | 步骤 | 预期 | 结果 |
+|---|---|---|---|---|
+| TC-01 | 插件包构建 | 执行 `./build.sh` | typecheck、全量单测、build、tgz 生成成功 | 通过:29 个测试文件、564 个测试通过 |
+| TC-02 | 本地安装 | `output/install.sh --source local --tarball ./output/openviking.tgz` | 安装到 `~/.openclaw/extensions/openviking`,Gateway 重启 | 通过 |
+| TC-03 | 健康检查 | 安装脚本内执行 setup/status | OpenViking 服务连接成功 | 通过:`version=v0.3.21` |
+| TC-04 | Runtime 注册 | `openclaw plugins inspect openviking --runtime --json` | tools/services/context engine/routes 均注册 | 通过:`httpRouteCount=4` |
+| TC-05 | 真实 agent 场景 | `openclaw agent --agent main --session-key agent:main:ov-install-verify-jsonl-20260605 --message ... --json` | agent 调用 `ov_search` 并返回 URI | 通过:返回 `viking://resources/openclaw-plugin-config/.abstract.md` |
+| TC-06 | Recall traces 列表 API | `GET /api/openviking/recall-traces?turn=all&limit=10` | 返回 JSON,包含 trace entries | 通过 |
+| TC-07 | traceId 查询 API | `GET /api/openviking/recall-traces/<traceId>?limit=1` | 返回指定 trace | 通过:返回 `ov_search-1780628249097-lpxfpu9b` |
+| TC-08 | latest ov_search 清单 API | `GET /api/openviking/recall-traces/latest-ov-search-list?limit=5` | 返回最近 ov_search 的扁平 item 列表 | 通过:返回 5 个 item |
+| TC-09 | URI detail API | `GET /api/openviking/uri-detail?uri=...&includeContent=true&contentLimit=120` | 返回内容片段和分页元数据 | 通过:`readStatus=ok`、`returnedChars=120` |
+| TC-10 | 无效 URI 边界 | `GET /api/openviking/uri-detail?uri=not-viking` | HTTP 400,`error.code=invalid_uri` | 通过 |
+| TC-11 | 无效 limit 边界 | `GET /latest-ov-search-list?limit=0` | HTTP 400,`error.code=invalid_param` | 通过 |
+| TC-12 | 非 GET 边界 | `POST /api/openviking/recall-traces` | HTTP 405,`error.code=method_not_allowed` | 通过 |
+| TC-13 | JSONL 文件存在 | 检查 `~/.openclaw/openviking/recall-traces/2026-06-05.jsonl` | 文件存在并有新增 trace | 通过:7 行 |
+| TC-14 | JSONL schema | 逐行校验 required fields、source、operationType、stats、selected URI | 0 个 schema 错误 | 通过 |
+| TC-15 | JSONL 配置上限 | line count <= `traceRecallMaxEntries=200` | 不超过上限 | 通过:7 <= 200 |
+| TC-16 | session key HTTP alias | 使用 `sessionkey`/`session_key` 查询 trace | 可从 persistent layer 查到对应 session trace | 通过;并新增单测覆盖 |
+| TC-17 | Gateway RPC health | `openclaw gateway call health --json` | Gateway 返回健康状态 | 通过:`ok=true`、`runtimeVersion=2026.5.28` |
+| TC-18 | Gateway RPC status | `openclaw gateway call status --json` | 返回运行时版本、默认 agent、session 状态 | 通过:`defaultAgentId=main`、`eventLoop.degraded=false` |
+| TC-19 | Gateway RPC system-presence | `openclaw gateway call system-presence --json` | 返回 Gateway/CLI 节点 presence | 通过:返回 macOS gateway 节点与 CLI probe 节点 |
+| TC-20 | Gateway RPC tools.catalog | `openclaw gateway call tools.catalog --params '{"agentId":"main"}' --json` | 工具目录包含 OpenViking 插件工具 | 通过:14 个 group,12 个 OpenViking 工具 |
+| TC-21 | Gateway RPC tools.effective | 使用已存在 sessionKey `agent:main:ov-install-verify-jsonl-20260605` | 当前 session 可用工具包含 OpenViking 工具 | 通过:2 个 group,12 个 OpenViking 工具 |
+| TC-22 | Gateway RPC tools.invoke/ov_search | `tools.invoke` 调用 `ov_search` 搜索 `openclaw plugin config` | 返回 `ok=true` 与 `viking://` URI | 通过:返回 2 条资源,首条为 `viking://resources/openclaw-plugin-config/.abstract.md` |
+| TC-23 | Gateway RPC tools.invoke/ov_read | `tools.invoke` 调用 `ov_read` 读取首条 URI | 返回完整内容文本 | 通过:`ok=true`、返回 335 字符内容 |
+| TC-24 | Gateway RPC tools.invoke/memory_recall | `tools.invoke` 调用 `memory_recall` | 返回召回结果且工具执行成功 | 通过:`ok=true`、`total=19` |
+| TC-25 | Gateway RPC 未知 method 边界 | `openclaw gateway call does.not.exist --params '{}' --json` | Gateway 拒绝未知 RPC 方法 | 通过:`unknown method: does.not.exist` |
+| TC-26 | Gateway RPC 无效 session 边界 | `tools.effective` 传不存在 sessionKey | Gateway 返回 unknown session key | 通过:`unknown session key` |
+| TC-27 | Gateway RPC 未知工具边界 | `tools.invoke` 调用 `not_a_tool` | `payload.ok=false`/`ok=false`,错误码 `not_found` | 通过:`Tool not available: not_a_tool` |
+| TC-28 | Gateway RPC 工具参数边界 | `ov_search` 缺少必填 `query`;`ov_read` 传 `not-viking` | 工具调用失败且不影响 Gateway | 通过:均返回 `ok=false`、`error.code=internal_error` |
+| TC-29 | Gateway RPC trace 最新查询 | `tools.invoke` 调用 `ov_recall_trace`,`args={"turn":"latest","limit":5}` | 返回最近 trace | 通过:`count=1`,返回 `memory_recall-1780635643409-v243scn9` |
+| TC-30 | Gateway RPC trace source 过滤 | `ov_recall_trace`,`turn=all`、`source=ov_search`、`limit=10` | 返回 ov_search trace | 通过:返回 `ov_search-1780635606119-h2fl11l5` |
+| TC-31 | Gateway RPC traceId 精确查询 | `ov_recall_trace`,`traceId=ov_search-1780635606119-h2fl11l5` | 返回指定 trace | 通过:`count=1`、`source=ov_search` |
+| TC-32 | Gateway RPC trace includeContent | `ov_recall_trace`,`traceId=...`、`includeContent=true` | selected 条目带内容预览 | 通过:`selected[0]` 包含 `contentPreview` |
+| TC-33 | Gateway RPC trace sessionKey 过滤 | `ov_recall_trace`,`turn=all`、`sessionKey=agent:main:ov-install-verify-jsonl-20260605` | 返回该 session 的 trace | 通过:`count=1`、`lookupLayer=memory` |
+| TC-34 | Gateway RPC trace 空结果边界 | `ov_recall_trace` 查询不存在 traceId / 不匹配 sessionKey / 不匹配 source | 返回空结果而非错误 | 通过:`ok=true`、`count=0`、`entries=[]` |
+| TC-35 | Gateway RPC trace limit 边界 | `ov_recall_trace`,`turn=all`、`limit=0` | 参数被安全归一化或回退,不影响 Gateway | 通过:返回最近 1 条,`ok=true` |
+
+## 5. 真实场景验证记录
+
+### 5.1 Agent 调用结果
+
+执行:
+
+```bash
+openclaw agent \
+ --agent main \
+ --session-key agent:main:ov-install-verify-jsonl-20260605 \
+ --message "请使用 OpenViking 的 ov_search 搜索 openclaw plugin config 相关资源,并返回最相关的 viking URI;这是安装验收测试。" \
+ --json \
+ --timeout 600
+```
+
+结果摘要:
+
+- `status=ok`
+- `toolSummary.calls=1`
+- `toolSummary.tools=["ov_search"]`
+- `toolSummary.failures=0`
+- agent 返回:`viking://resources/openclaw-plugin-config/.abstract.md`
+
+### 5.2 JSONL 验证结果
+
+目标文件:
+
+```text
+/Users/bytedance/.openclaw/openviking/recall-traces/2026-06-05.jsonl
+```
+
+校验输出摘要:
+
+```text
+line_count 7
+within_max_entries True
+latest_traceId memory_recall-1780635643409-v243scn9
+latest_source memory_recall
+latest_sessionId null
+latest_sessionKey agent:main:ov-install-verify-jsonl-20260605
+latest_searches 1
+latest_selected 2
+source_counts {"auto_recall":3,"ov_search":3,"memory_recall":1}
+errors 0
+```
+
+## 6. 接口边界验证记录
+
+| API | 场景 | 状态码 | 关键字段 | 结论 |
+|---|---|---:|---|---|
+| `/api/openviking/recall-traces/<traceId>` | 指定 traceId | 200 | `ok=true`、`entries.length=1` | 通过 |
+| `/api/openviking/recall-traces/latest-ov-search-list` | 最近 ov_search | 200 | `ok=true`、`items.length=5` | 通过 |
+| `/api/openviking/uri-detail` | 正常 URI + content | 200 | `readStatus=ok`、`uriType=resource` | 通过 |
+| `/api/openviking/uri-detail` | 非 `viking://` URI | 400 | `error.code=invalid_uri` | 通过 |
+| `/api/openviking/recall-traces/latest-ov-search-list` | `limit=0` | 400 | `error.code=invalid_param` | 通过 |
+| `/api/openviking/recall-traces` | POST | 405 | `error.code=method_not_allowed` | 通过 |
+
+备注:HTTP Gateway 对 `sessionKey` 这类 camelCase/query 保留字段的转发存在不稳定表现,真实 HTTP 验证中 `sessionkey` 和 `session_key` 可稳定命中。已在插件中加入 alias 兼容,并新增回归单测。
+
+## 7. WebSocket RPC 协议验证记录
+
+### 7.1 Gateway RPC 基础接口
+
+本轮使用 `openclaw gateway call <method> --params '<json>' --json` 覆盖 OpenClaw Gateway WebSocket RPC。该 CLI 底层连接 Gateway WebSocket,使用与外部客户端一致的 RPC 方法与参数对象。
+
+| 方法 | 参数 | 结果摘要 | 结论 |
+|---|---|---|---|
+| `health` | `{}` | `ok=true`、`runtimeVersion=2026.5.28`、`eventLoop.degraded=false` | 通过 |
+| `status` | `{}` | `runtimeVersion=2026.5.28`、`defaultAgentId=main`、`mainHeartbeatEnabled=true`、`eventLoopDegraded=false` | 通过 |
+| `system-presence` | `{}` | 返回 `SuperOpsByteDance.local` gateway 节点与 `cli` probe 节点 | 通过 |
+| `tools.catalog` | `{"agentId":"main"}` | `group_count=14`,OpenViking 工具 12 个 | 通过 |
+| `tools.effective` | `{"sessionKey":"agent:main:ov-install-verify-jsonl-20260605"}` | `agentId=main`、`profile=full`、`group_count=2`,OpenViking 工具 12 个 | 通过 |
+
+`tools.catalog` 与 `tools.effective` 均确认 OpenViking 插件工具已经进入 Gateway 工具系统,工具清单包括:
+
+```text
+add_skill, memory_forget, memory_recall, memory_store,
+openviking_tool_result_list, openviking_tool_result_read, openviking_tool_result_search,
+ov_archive_expand, ov_archive_search, ov_read, ov_recall_trace, ov_search
+```
+
+### 7.2 OpenViking 工具 RPC 调用
+
+| 方法 | 工具 | 参数摘要 | 结果摘要 | 结论 |
+|---|---|---|---|---|
+| `tools.invoke` | `ov_search` | `query="openclaw plugin config"`、`limit=2`、`sessionKey=agent:main:ov-install-verify-jsonl-20260605` | `ok=true`,返回 2 条 resource,首条 URI 为 `viking://resources/openclaw-plugin-config/.abstract.md` | 通过 |
+| `tools.invoke` | `ov_read` | 读取 `viking://resources/openclaw-plugin-config/.abstract.md` | `ok=true`,返回 OpenViking content,文本长度 335 | 通过 |
+| `tools.invoke` | `memory_recall` | `query="openclaw plugin config"`、`limit=2`、`resourceTypes=["resource"]` | `ok=true`,`toolName=memory_recall`,`total=19` | 通过 |
+| `tools.invoke` | `ov_recall_trace` | `turn="latest"`、`limit=5` | `ok=true`,返回最近 1 条 trace:`memory_recall-1780635643409-v243scn9` | 通过 |
+
+`ov_search` 返回内容示例:
+
+```text
+Found 2 OpenViking results for "openclaw plugin config"
+1 resource viking://resources/openclaw-plugin-config/.abstract.md score=0.61
+2 resource viking://resources/大模型研究/Agent调研/01_OpenClaw生态与最佳实践/openclaw_codex_report/.abstract.md score=0.57
+```
+
+### 7.3 RPC 边界用例
+
+| 场景 | 命令/参数 | 实际结果 | 结论 |
+|---|---|---|---|
+| 未知 RPC method | `openclaw gateway call does.not.exist --params '{}' --json` | `GatewayClientRequestError: unknown method: does.not.exist` | 通过:Gateway 层拒绝未知方法 |
+| `tools.effective` 使用不存在 sessionKey | `sessionKey=agent:main:not-exists-openviking-rpc-20260605` | `GatewayClientRequestError: unknown session key ...` | 通过:sessionKey 必须存在 |
+| `tools.invoke` 调用不存在工具 | `name=not_a_tool` | `ok=false`、`error.code=not_found`、`Tool not available: not_a_tool` | 通过:工具层返回结构化错误 |
+| `ov_search` 缺少必填 query | `args={"limit":2}` | `ok=false`、`toolName=ov_search`、`error.code=internal_error` | 通过:工具失败被包装为失败响应,Gateway 未崩溃 |
+| `ov_read` 传非 `viking://` URI | `args={"uri":"not-viking"}` | `ok=false`、`toolName=ov_read`、`error.code=internal_error` | 通过:工具失败被包装为失败响应,Gateway 未崩溃 |
+
+### 7.4 Trace RPC 接口专项验证
+
+通过 WebSocket RPC 调用 trace 相关能力时,统一入口是 `tools.invoke` + `name="ov_recall_trace"`,与 HTTP route 的 `/api/openviking/recall-traces` 系列接口覆盖同一批 trace 数据。专项验证使用 session key:`agent:main:ov-install-verify-jsonl-20260605`。
+
+本机可直接粘贴执行的 OpenClaw 命令如下:
+
+```bash
+# 1. 查询最新 trace
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"turn":"latest","limit":5}}' \
+ --json
+
+# 2. 按 source 查询 ov_search trace
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"turn":"all","source":"ov_search","limit":10}}' \
+ --json
+
+# 3. 按 traceId 精确查询
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"traceId":"ov_search-1780635606119-h2fl11l5","limit":1}}' \
+ --json
+
+# 4. 按 traceId 查询并展开 selected 内容预览
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"traceId":"ov_search-1780635606119-h2fl11l5","includeContent":true,"limit":1}}' \
+ --json
+
+# 5. 按 sessionKey 过滤 trace
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"turn":"all","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","limit":20}}' \
+ --json
+
+# 6. 查询不存在的 traceId,验证空结果边界
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"traceId":"not-exist-trace-20260605","limit":1}}' \
+ --json
+
+# 7. 查询不匹配的 sessionKey,验证空结果边界
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"turn":"all","sessionKey":"agent:main:no-trace-session-20260605","limit":5}}' \
+ --json
+
+# 8. 查询不匹配的 source,验证空结果边界
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"turn":"all","source":"not_a_source","limit":5}}' \
+ --json
+
+# 9. limit=0 边界验证
+openclaw gateway call tools.invoke \
+ --params '{"name":"ov_recall_trace","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","args":{"turn":"all","limit":0}}' \
+ --json
+```
+
+| 场景 | 参数摘要 | 实际结果 | 结论 |
+|---|---|---|---|
+| 查询最新 trace | `args={"turn":"latest","limit":5}` | `ok=true`、`count=1`、`lookupLayer=memory`,返回 `memory_recall-1780635643409-v243scn9` | 通过 |
+| 按 source 查询 `ov_search` | `args={"turn":"all","source":"ov_search","limit":10}` | `ok=true`、`count=1`、返回 `ov_search-1780635606119-h2fl11l5` | 通过 |
+| 按 traceId 精确查询 | `args={"traceId":"ov_search-1780635606119-h2fl11l5","limit":1}` | `ok=true`、`count=1`、`source=ov_search`、`stats.selectedCount=2` | 通过 |
+| 查询并展开内容预览 | `args={"traceId":"ov_search-1780635606119-h2fl11l5","includeContent":true,"limit":1}` | `ok=true`、`lookupLayer=persistent`,`selected[0]` 包含 `contentPreview` 字段 | 通过 |
+| 按 sessionKey 查询 | `args={"turn":"all","sessionKey":"agent:main:ov-install-verify-jsonl-20260605","limit":20}` | `ok=true`、`count=1`,返回当前 session 最近 trace | 通过 |
+| 不存在 traceId | `args={"traceId":"not-exist-trace-20260605","limit":1}` | `ok=true`、`count=0`、`entries=[]`,文本提示 `No OpenViking recall traces found` | 通过 |
+| 不匹配 sessionKey | `args={"turn":"all","sessionKey":"agent:main:no-trace-session-20260605","limit":5}` | `ok=true`、`count=0`、`entries=[]` | 通过 |
+| 不匹配 source | `args={"turn":"all","source":"not_a_source","limit":5}` | `ok=true`、`count=0`、`entries=[]` | 通过 |
+| `limit=0` 边界 | `args={"turn":"all","limit":0}` | `ok=true`,返回最近 1 条 trace;Gateway 与插件均未异常 | 通过 |
+
+Trace RPC 返回结构关键字段:
+
+```json
+{
+ "ok": true,
+ "toolName": "ov_recall_trace",
+ "output": {
+ "details": {
+ "action": "queried",
+ "count": 1,
+ "lookupLayer": "memory|persistent",
+ "warnings": [],
+ "entries": ["RecallTraceEntry"]
+ }
+ },
+ "source": "plugin"
+}
+```
+
+结论:trace 相关能力通过 WebSocket RPC 路径验证通过。`ov_recall_trace` 支持 latest/all、source、traceId、sessionKey、includeContent 等查询场景;无匹配数据时返回 `ok=true` + 空 `entries`,工具参数边界不会导致 Gateway 异常。
+
+结论:OpenClaw Gateway WebSocket RPC 可用于自动化发现和调用 OpenViking 插件工具;`tools.effective` 需要传入已存在的 session key,`tools.catalog` 可用于按 agent 查看完整工具目录,OpenViking 工具调用成功与失败均能通过 RPC 返回可识别结果。
+
+## 8. 自动化回归验证
+
+### 8.1 针对性测试
+
+```bash
+npm run typecheck
+npm test -- --run tests/ut/recall-trace.test.ts tests/ut/tools.test.ts tests/ut/config.test.ts tests/ut/manifest-contracts.test.ts
+npm run build
+```
+
+结果:
+
+- TypeScript typecheck:通过
+- targeted tests:4 个测试文件、143 个测试通过
+- build:通过
+
+### 8.2 全量构建验证
+
+`./build.sh` 已执行完整流程:
+
+- `npm install`:通过
+- `npm run typecheck`:通过
+- `npm test`:通过,29 个测试文件、564 个测试全部通过
+- `npm run build`:通过
+- package staging + production dependencies:通过
+- `output/openviking.tgz` 生成:通过
+
+### 8.3 2026-06-08 追加验证:真实 sessionKey trace 查询修复
+
+背景:线上下载的 JSONL trace 文件 `/Users/bytedance/Downloads/2026-06-08.jsonl` 中,每条记录都包含真实 `sessionKey`,同时 `sessionId/ovSessionId` 为同一个 web session UUID。旧版查询逻辑在 `tools.invoke` 只传外层 `params.sessionKey` 时,可能退化为使用由 `sessionKey` 派生出的 `sha256` 作为 `ovSessionId` 查询;该派生值与线上 JSONL 中保存的 UUID 不一致,导致返回空。
+
+本次修复后验证:
+
+```bash
+npm run lint --if-present
+npm run typecheck
+npm test
+npm run build
+```
+
+结果:
+
+- lint:项目未配置 lint script,`npm run lint --if-present` 正常退出。
+- TypeScript typecheck:通过。
+- 全量测试:29 个测试文件、567 个测试全部通过。
+- build:通过。
+
+新增/覆盖场景:
+
+| 场景 | 期望 | 结果 |
+|---|---|---|
+| `ov_recall_trace` 默认查询当前 session | 外层 `params.sessionKey` 作为默认 trace 身份过滤条件 | 通过 |
+| 显式 `args.sessionKey` 查询历史 session | 只按显式 `entry.sessionKey` 过滤,不叠加派生 `ovSessionId` | 通过 |
+| 历史 JSONL 只有 `ovSessionId`、缺少 `sessionKey` | 默认查询未命中时 fallback 到当前 session 的 `sessionId/ovSessionId` | 通过 |
+| 线上 JSONL 回放 | 用真实 `sessionKey=agent:main:web-c6592a8e-5448-4622-9e7f-31a07447eee7` 可查询到 10 条 | 通过 |
+
+发布验证:
+
+- 版本:`2026.6.5`
+- 日期路径:`2026.6.8/`
+- TOS 对象:`install.sh`、`openviking.tgz`、`manifest.json` 已上传并 head 校验通过。
+- `latest/`:未更新。
+
+## 9. 发现的问题与处理
+
+| 问题 | 影响 | 处理 | 状态 |
+|---|---|---|---|
+| 初始 runtime inspect 不带 `--runtime` 时 `httpRouteCount=0` | 容易误判未注册 | 使用 `--runtime` 加载插件后验证;真实 runtime 为 4 | 已澄清 |
+| OpenClaw v2026.5.28 使用 `registerHttpRoute`,旧插件只注册 legacy route 时 HTTP API 不可见 | Recall Trace HTTP API 无法访问 | 插件兼容 `registerHttpRoute`,并保留 legacy `registerRoute` | 已修复 |
+| 安装脚本执行 setup 后会重置部分高级配置 | `traceRecall`/JSONL 验证配置被清空 | 安装后重新写入验证配置并重启 Gateway | 已处理 |
+| HTTP Gateway camelCase `sessionKey` 查询不稳定 | 按 session key 查询 trace 可能返回 0 | 增加 `sessionkey`、`session_key`、`session-key` alias;真实验证使用 alias | 已修复并测试 |
+| `tools.effective` 传不存在的 session key | Gateway 返回 `unknown session key`,无法列出有效工具 | 使用真实已存在 session key `agent:main:ov-install-verify-jsonl-20260605`;文档中补充前置条件 | 已澄清 |
+| Gateway RPC 只传外层 `params.sessionKey` 时 trace 查询为空 | 旧版查询没有默认使用外层 `sessionKey`,而是可能按派生 `ovSessionId` 查询;派生值与线上 UUID 不一致 | 默认按外层 `params.sessionKey` 查询;未命中时兼容 fallback 到当前 session 的 `sessionId/ovSessionId` | 已修复并测试 |
+
+## 10. 最终结论
+
+本机安装测试验证通过:
+
+- 插件包可构建、可本地安装、可被 OpenClaw Gateway 加载。
+- OpenViking remote 配置、健康检查、slot active 均符合预期。
+- 真实 agent 场景中 `ov_search` 能正常调用并返回资源 URI。
+- OpenClaw Gateway WebSocket RPC 能发现并调用 OpenViking 插件工具,`tools.catalog`、`tools.effective`、`tools.invoke`、`ov_recall_trace` 正向与边界用例均符合预期。
+- Recall Trace HTTP APIs 可访问,成功和错误边界响应符合预期。
+- JSONL trace 文件已落盘,schema 校验 0 错误,配置上限符合预期。
+- 新增/相关回归测试均通过,全量构建测试通过。
+
+建议后续发布前将 `output/openviking.tgz` 与 `output/install.sh` 作为当前验收产物重新上传到目标 TOS release path,避免线上安装包仍停留在旧版本或旧配置行为。
diff --git a/examples/openclaw-plugin/docs/openviking-tos-install-guide.md b/examples/openclaw-plugin/docs/openviking-tos-install-guide.md
new file mode 100644
index 000000000..263fe7a31
--- /dev/null
+++ b/examples/openclaw-plugin/docs/openviking-tos-install-guide.md
@@ -0,0 +1,311 @@
+# OpenViking TOS 安装包发布与安装说明
+
+> 更新时间:2026-06-03
+> 发布目录:`latest`(默认)与可指定日期目录(示例:`2026.6.3`)
+> 发布内容:`install.sh`、`openviking.tgz`、`manifest.json`
+
+## 1. 本次发布结论
+
+当前发布协议只发布三个文件:一个兼容多区域的 `install.sh`,一个插件压缩包 `openviking.tgz`,一个描述文件 `manifest.json`。三个文件会覆盖上传到 4 个 TOS bucket,并设置对象 ACL 为公开读(public-read)。每个 bucket 都先上传日期目录;日期目录可用 `--release-dir <yyyy.m.d>` 指定,未指定时按运行当天动态生成,不能固定死某个日期。`latest` 目录只有在组件稳定后显式指定 `--publish-latest` 才上传:
+
+- `latest/install.sh`
+- `latest/openviking.tgz`
+- `latest/manifest.json`
+- `2026.6.3/install.sh`
+- `2026.6.3/openviking.tgz`
+- `2026.6.3/manifest.json`
+
+安装脚本默认安装 `latest/openviking.tgz`;如需安装固定日期版本,可添加 `--date 2026.6.3`。
+
+如果目标 bucket 不存在,上传脚本会先自动创建 bucket,再上传对象。本文中的验证命令均使用 dry-run 或本地语法/单测校验,不执行真实 TOS 上传。
+
+## 2. 域名规则
+
+`install.sh` 默认使用内部域名,适用于内部网络环境:
+
+```text
+ivolces.com
+```
+
+公网测试或公网安装时,需要显式添加:
+
+```bash
+--external
+```
+
+此时脚本会使用公网域名:
+
+```text
+volces.com
+```
+
+## 3. 已发布的公网下载地址
+
+### 3.1 arkclaw-ov-cn-beijing
+
+```text
+https://arkclaw-ov-cn-beijing.tos-cn-beijing.volces.com/latest/install.sh
+https://arkclaw-ov-cn-beijing.tos-cn-beijing.volces.com/latest/openviking.tgz
+https://arkclaw-ov-cn-beijing.tos-cn-beijing.volces.com/latest/manifest.json
+https://arkclaw-ov-cn-beijing.tos-cn-beijing.volces.com/2026.6.3/install.sh
+https://arkclaw-ov-cn-beijing.tos-cn-beijing.volces.com/2026.6.3/openviking.tgz
+https://arkclaw-ov-cn-beijing.tos-cn-beijing.volces.com/2026.6.3/manifest.json
+```
+
+### 3.2 arkclaw-ov-cn-guangzhou
+
+```text
+https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/latest/install.sh
+https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/latest/openviking.tgz
+https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/latest/manifest.json
+https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/2026.6.3/install.sh
+https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/2026.6.3/openviking.tgz
+https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/2026.6.3/manifest.json
+```
+
+### 3.3 arkclaw-ov-cn-shanghai
+
+```text
+https://arkclaw-ov-cn-shanghai.tos-cn-shanghai.volces.com/latest/install.sh
+https://arkclaw-ov-cn-shanghai.tos-cn-shanghai.volces.com/latest/openviking.tgz
+https://arkclaw-ov-cn-shanghai.tos-cn-shanghai.volces.com/latest/manifest.json
+https://arkclaw-ov-cn-shanghai.tos-cn-shanghai.volces.com/2026.6.3/install.sh
+https://arkclaw-ov-cn-shanghai.tos-cn-shanghai.volces.com/2026.6.3/openviking.tgz
+https://arkclaw-ov-cn-shanghai.tos-cn-shanghai.volces.com/2026.6.3/manifest.json
+```
+
+### 3.4 arkclaw-ov
+
+```text
+https://arkclaw-ov.tos-cn-beijing.volces.com/latest/install.sh
+https://arkclaw-ov.tos-cn-beijing.volces.com/latest/openviking.tgz
+https://arkclaw-ov.tos-cn-beijing.volces.com/latest/manifest.json
+https://arkclaw-ov.tos-cn-beijing.volces.com/2026.6.3/install.sh
+https://arkclaw-ov.tos-cn-beijing.volces.com/2026.6.3/openviking.tgz
+https://arkclaw-ov.tos-cn-beijing.volces.com/2026.6.3/manifest.json
+```
+
+## 4. 推荐安装方式
+
+### 4.1 内部网络安装 latest(默认)
+
+在内部网络环境中,直接下载对应区域的 `install.sh` 并执行即可。脚本默认使用内部域名并安装 `latest/openviking.tgz`。
+
+以广州区域为例:
+
+```bash
+wget https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.ivolces.com/latest/install.sh -O install.sh
+bash install.sh --region cn-guangzhou
+```
+
+### 4.2 公网安装 latest
+
+公网环境需要使用公网下载地址,并在执行脚本时加 `--external`。
+
+以广州区域为例:
+
+```bash
+wget https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/latest/install.sh -O install.sh
+bash install.sh --external --region cn-guangzhou
+```
+
+### 4.3 安装固定日期版本
+
+如需安装 `2026.6.3` 固定版本:
+
+```bash
+wget https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/2026.6.3/install.sh -O install.sh
+bash install.sh --external --region cn-guangzhou --date 2026.6.3
+```
+
+### 4.4 指定 bucket 安装
+
+如果使用默认 bucket `arkclaw-ov`,可指定 bucket:
+
+```bash
+wget https://arkclaw-ov.tos-cn-beijing.volces.com/latest/install.sh -O install.sh
+bash install.sh --external --region cn-beijing --bucket arkclaw-ov
+```
+
+### 4.5 自定义 TOS Base URL
+
+如果希望完全指定下载根路径,可使用 `--tos-base-url`:
+
+```bash
+bash install.sh --tos-base-url https://arkclaw-ov.tos-cn-beijing.volces.com
+```
+
+默认下载:
+
+```text
+https://arkclaw-ov.tos-cn-beijing.volces.com/latest/openviking.tgz
+```
+
+如果需要日期目录:
+
+```bash
+bash install.sh --tos-base-url https://arkclaw-ov.tos-cn-beijing.volces.com --date 2026.6.3
+```
+
+对应下载:
+
+```text
+https://arkclaw-ov.tos-cn-beijing.volces.com/2026.6.3/openviking.tgz
+```
+
+## 5. install.sh 参数速查
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `--internal` | 使用内部域名 `ivolces.com` | 默认开启 |
+| `--external` | 使用公网域名 `volces.com` | 关闭 |
+| `--latest` | 安装 `latest/openviking.tgz` | 默认开启 |
+| `--date <date>` | 安装日期目录版本,如 `2026.6.3/openviking.tgz` | 无 |
+| `--release-path <path>` | 安装自定义目录下的 `openviking.tgz` | `latest` |
+| `--region <region>` | 指定区域,如 `cn-beijing` / `cn-guangzhou` / `cn-shanghai` | 自动识别,失败时为 `cn-beijing` |
+| `--bucket <bucket>` | 指定 bucket 名称 | `arkclaw-ov` |
+| `--tos-base-url <url>` | 完整指定 TOS 根 URL | 自动按 bucket/region/domain 生成 |
+| `--manifest-url <url>` | 完整指定 manifest URL | 自动按 bucket/region/domain/release-path 生成 |
+| `--source local` | 从 `install.sh` 同目录安装本地 `openviking.tgz` | 远端下载 |
+| `--tarball <path>` | 从指定本地 tgz 安装 | 无 |
+| `--verify-only` | 仅下载/校验,不安装 | 关闭 |
+| `--dry-run` | 打印动作,不执行下载/安装 | 关闭 |
+| `--no-restart` | 安装后不重启 OpenClaw gateway | 默认会重启 |
+
+## 6. 上传脚本说明
+
+上传脚本路径:
+
+```text
+scripts/upload_tos.py
+```
+
+执行上传(真实上传,需要 `TEAM_TEST_AK` / `TEAM_TEST_SK`):
+
+```bash
+python3 scripts/upload_tos.py --release-dir 2026.6.3
+```
+
+只验证脚本路径、对象 key、bucket 与 latest 策略,不真实上传 TOS:
+
+```bash
+python3 scripts/upload_tos.py --release-dir 2026.6.3 --dry-run
+```
+
+不指定 `--release-dir` 时,脚本默认使用运行当天的 `yyyy.m.d` 作为日期目录。
+
+组件稳定后再发布 latest:
+
+```bash
+python3 scripts/upload_tos.py --release-dir 2026.6.3 --publish-latest
+```
+
+完整发布入口会先构建三文件产物,再调用上传脚本:
+
+```bash
+TEAM_TEST_AK=... TEAM_TEST_SK=... scripts/release-to-tos.sh --release-dir 2026.6.3
+TEAM_TEST_AK=... TEAM_TEST_SK=... scripts/release-to-tos.sh --release-dir 2026.6.3 --publish-latest
+```
+
+仅做发布脚本正确性验证、不上传 TOS:
+
+```bash
+scripts/release-to-tos.sh --release-dir 2026.6.3 --dry-run
+```
+
+上传脚本会读取环境变量:
+
+```text
+TEAM_TEST_AK
+TEAM_TEST_SK
+```
+
+上传对象:
+
+```text
+install.sh
+openviking.tgz
+manifest.json
+```
+
+上传路径:
+
+```text
+2026.6.3/install.sh
+2026.6.3/openviking.tgz
+2026.6.3/manifest.json
+latest/install.sh # 仅 --publish-latest 时上传
+latest/openviking.tgz # 仅 --publish-latest 时上传
+latest/manifest.json # 仅 --publish-latest 时上传
+```
+
+上传目标 bucket:
+
+```text
+arkclaw-ov-cn-beijing
+arkclaw-ov-cn-guangzhou
+arkclaw-ov-cn-shanghai
+arkclaw-ov
+```
+
+如果 bucket 不存在,上传脚本会自动创建对应 bucket。
+
+上传时已设置对象 ACL:
+
+```text
+public-read
+```
+
+## 7. 本次验证结果
+
+### 7.1 本地脚本测试
+
+本地只验证脚本正确性,不做真实 TOS 上传。已通过以下测试:
+
+```bash
+npx vitest run tests/ut/tos-release-contract.test.ts
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/test_upload_tos.py
+bash -n scripts/install.sh
+bash -n scripts/release-to-tos.sh
+node --check scripts/generate-release-manifest.mjs
+node --check scripts/tos-release-client.mjs
+```
+
+测试覆盖:
+
+- 默认使用 `latest/openviking.tgz`
+- `--date 2026.6.3` 使用日期目录
+- 默认内部域名为 `ivolces.com`
+- `--external` 使用公网域名 `volces.com`
+- 上传脚本默认只上传指定日期目录,`--publish-latest` 时才上传 `latest`
+- 不指定 `--release-dir` 时动态使用当天日期目录
+- bucket 不存在时自动创建 bucket
+- 上传对象使用 `public-read` ACL
+
+## 8. 常见问题
+
+### 8.1 为什么公网测试必须加 --external?
+
+因为 `ivolces.com` 是内部域名,在当前公网测试环境无法连通。加 `--external` 后,脚本会改用 `volces.com` 公网域名。
+
+### 8.2 默认不指定日期时安装哪个版本?
+
+默认安装 `latest/openviking.tgz`。
+
+### 8.3 如何回滚到固定日期目录?
+
+使用 `--date`:
+
+```bash
+bash install.sh --date 2026.6.3
+```
+
+公网环境:
+
+```bash
+bash install.sh --external --date 2026.6.3
+```
+
+### 8.4 覆盖上传是否安全?
+
+本次需求明确要求同路径已有文件直接覆盖。上传脚本未开启禁止覆盖,并在每次上传时设置 public-read ACL。
diff --git a/examples/openclaw-plugin/package-lock.json b/examples/openclaw-plugin/package-lock.json
index 81059c687..5eb899d2f 100644
--- a/examples/openclaw-plugin/package-lock.json
+++ b/examples/openclaw-plugin/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@openviking/openclaw-plugin",
- "version": "2026.6.2",
+ "version": "2026.6.11",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@openviking/openclaw-plugin",
- "version": "2026.6.2",
+ "version": "2026.6.11",
"license": "MIT",
"dependencies": {
"@sinclair/typebox": "0.34.48",
@@ -14,6 +14,7 @@
},
"devDependencies": {
"@types/node": "^25.3.5",
+ "@volcengine/tos-sdk": "^2.9.1",
"typescript": "^5.8.0",
"vitest": "^4.1.0"
},
@@ -429,6 +430,16 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/@types/http-proxy": {
+ "version": "1.17.17",
+ "resolved": "https://registry.npmjs.org/@types/http-proxy/-/http-proxy-1.17.17.tgz",
+ "integrity": "sha512-ED6LB+Z1AVylNTu7hdzuBqOgMnvG/ld6wGCG8wFnAzKX5uyW2K3WD52v0gnLCTK/VLpXtKckgWuyScYK6cSPaw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/node": "*"
+ }
+ },
"node_modules/@types/node": {
"version": "25.3.5",
"resolved": "https://registry.npmmirror.com/@types/node/-/node-25.3.5.tgz",
@@ -552,6 +563,40 @@
"url": "https://opencollective.com/vitest"
}
},
+ "node_modules/@volcengine/tos-sdk": {
+ "version": "2.9.1",
+ "resolved": "https://registry.npmjs.org/@volcengine/tos-sdk/-/tos-sdk-2.9.1.tgz",
+ "integrity": "sha512-hmrBzl7/LpJYezGWytPg6CZk5lvFgmDKUVZJLM3vwZgp3UKSZwgxFA7V0QmLnerPDRpLPAqh0bP8qUBSVHfmhA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "axios": "^0.21.1",
+ "axios-adapter-uniapp": "^0.1.4",
+ "crypto-js": "^4.2.0",
+ "debug": "^4.3.4",
+ "http-proxy-middleware": "^2.0.1",
+ "lodash": "^4.17.21",
+ "qs": "^6.11.2",
+ "tos-crc64-js": "0.0.1",
+ "type-fest": "^1.4.0"
+ },
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/agent-base": {
+ "version": "6.0.2",
+ "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
+ "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "debug": "4"
+ },
+ "engines": {
+ "node": ">= 6.0.0"
+ }
+ },
"node_modules/assertion-error": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
@@ -562,6 +607,80 @@
"node": ">=12"
}
},
+ "node_modules/asynckit": {
+ "version": "0.4.0",
+ "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
+ "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/axios": {
+ "version": "1.16.1",
+ "resolved": "https://registry.npmjs.org/axios/-/axios-1.16.1.tgz",
+ "integrity": "sha512-caYkukvroVPO8KrzuJEb50Hm07KwfBZPEC3VeFHTsqWHvKTsy54hjJz9BS/cdaypROE2rH6xvm9mHX4fgWkr3A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "follow-redirects": "^1.16.0",
+ "form-data": "^4.0.5",
+ "https-proxy-agent": "^5.0.1",
+ "proxy-from-env": "^2.1.0"
+ }
+ },
+ "node_modules/axios-adapter-uniapp": {
+ "version": "0.1.4",
+ "resolved": "https://registry.npmjs.org/axios-adapter-uniapp/-/axios-adapter-uniapp-0.1.4.tgz",
+ "integrity": "sha512-4je5JcWGrrTjPEJXVXJZnOkv+BsnYn/fKbQmjxzdCGFyoQw1gq3tfQ4/WhLzy+Gi9cQJl3K8EH26G7U0BK3wcw==",
+ "dev": true,
+ "license": "ISC",
+ "dependencies": {
+ "axios": "^0.27.2"
+ }
+ },
+ "node_modules/braces": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
+ "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "fill-range": "^7.1.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/call-bind-apply-helpers": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
+ "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0",
+ "function-bind": "^1.1.2"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/call-bound": {
+ "version": "1.0.4",
+ "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
+ "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "call-bind-apply-helpers": "^1.0.2",
+ "get-intrinsic": "^1.3.0"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
"node_modules/chai": {
"version": "6.2.2",
"resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
@@ -572,6 +691,19 @@
"node": ">=18"
}
},
+ "node_modules/combined-stream": {
+ "version": "1.0.8",
+ "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
+ "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "delayed-stream": "~1.0.0"
+ },
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/convert-source-map": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -579,6 +711,41 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/crypto-js": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz",
+ "integrity": "sha512-KALDyEYgpY+Rlob/iriUtjV6d5Eq+Y191A5g4UqLAi8CyGP9N1+FdVbkc1SxKc2r4YAYqG8JzO2KGL+AizD70Q==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/debug": {
+ "version": "4.4.3",
+ "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+ "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ms": "^2.1.3"
+ },
+ "engines": {
+ "node": ">=6.0"
+ },
+ "peerDependenciesMeta": {
+ "supports-color": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/delayed-stream": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
+ "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.4.0"
+ }
+ },
"node_modules/detect-libc": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -589,6 +756,41 @@
"node": ">=8"
}
},
+ "node_modules/dunder-proto": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
+ "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "call-bind-apply-helpers": "^1.0.1",
+ "es-errors": "^1.3.0",
+ "gopd": "^1.2.0"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/es-define-property": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+ "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/es-errors": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+ "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
"node_modules/es-module-lexer": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.0.0.tgz",
@@ -596,6 +798,35 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/es-object-atoms": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz",
+ "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/es-set-tostringtag": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
+ "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0",
+ "get-intrinsic": "^1.2.6",
+ "has-tostringtag": "^1.0.2",
+ "hasown": "^2.0.2"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
"node_modules/estree-walker": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
@@ -606,6 +837,13 @@
"@types/estree": "^1.0.0"
}
},
+ "node_modules/eventemitter3": {
+ "version": "4.0.7",
+ "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
+ "integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/expect-type": {
"version": "1.3.0",
"resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
@@ -640,6 +878,57 @@
"integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==",
"license": "MIT"
},
+ "node_modules/fill-range": {
+ "version": "7.1.1",
+ "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
+ "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "to-regex-range": "^5.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/follow-redirects": {
+ "version": "1.16.0",
+ "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
+ "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "individual",
+ "url": "https://github.com/sponsors/RubenVerborgh"
+ }
+ ],
+ "license": "MIT",
+ "engines": {
+ "node": ">=4.0"
+ },
+ "peerDependenciesMeta": {
+ "debug": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/form-data": {
+ "version": "4.0.5",
+ "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
+ "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "asynckit": "^0.4.0",
+ "combined-stream": "^1.0.8",
+ "es-set-tostringtag": "^2.1.0",
+ "hasown": "^2.0.2",
+ "mime-types": "^2.1.12"
+ },
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/fsevents": {
"version": "2.3.3",
"resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -655,6 +944,210 @@
"node": "^8.16.0 || ^10.6.0 || >=11.0.0"
}
},
+ "node_modules/function-bind": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+ "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+ "dev": true,
+ "license": "MIT",
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/get-intrinsic": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
+ "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "call-bind-apply-helpers": "^1.0.2",
+ "es-define-property": "^1.0.1",
+ "es-errors": "^1.3.0",
+ "es-object-atoms": "^1.1.1",
+ "function-bind": "^1.1.2",
+ "get-proto": "^1.0.1",
+ "gopd": "^1.2.0",
+ "has-symbols": "^1.1.0",
+ "hasown": "^2.0.2",
+ "math-intrinsics": "^1.1.0"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/get-proto": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
+ "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "dunder-proto": "^1.0.1",
+ "es-object-atoms": "^1.0.0"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/gopd": {
+ "version": "1.2.0",
+ "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
+ "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/has-symbols": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
+ "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/has-tostringtag": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
+ "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "has-symbols": "^1.0.3"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/hasown": {
+ "version": "2.0.4",
+ "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
+ "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "function-bind": "^1.1.2"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/http-proxy": {
+ "version": "1.18.1",
+ "resolved": "https://registry.npmjs.org/http-proxy/-/http-proxy-1.18.1.tgz",
+ "integrity": "sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "eventemitter3": "^4.0.0",
+ "follow-redirects": "^1.0.0",
+ "requires-port": "^1.0.0"
+ },
+ "engines": {
+ "node": ">=8.0.0"
+ }
+ },
+ "node_modules/http-proxy-middleware": {
+ "version": "2.0.9",
+ "resolved": "https://registry.npmjs.org/http-proxy-middleware/-/http-proxy-middleware-2.0.9.tgz",
+ "integrity": "sha512-c1IyJYLYppU574+YI7R4QyX2ystMtVXZwIdzazUIPIJsHuWNd+mho2j+bKoHftndicGj9yh+xjd+l0yj7VeT1Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/http-proxy": "^1.17.8",
+ "http-proxy": "^1.18.1",
+ "is-glob": "^4.0.1",
+ "is-plain-obj": "^3.0.0",
+ "micromatch": "^4.0.2"
+ },
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "peerDependencies": {
+ "@types/express": "^4.17.13"
+ },
+ "peerDependenciesMeta": {
+ "@types/express": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/https-proxy-agent": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
+ "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "agent-base": "6",
+ "debug": "4"
+ },
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/is-extglob": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
+ "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/is-glob": {
+ "version": "4.0.3",
+ "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
+ "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "is-extglob": "^2.1.1"
+ },
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/is-number": {
+ "version": "7.0.0",
+ "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
+ "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.12.0"
+ }
+ },
+ "node_modules/is-plain-obj": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-3.0.0.tgz",
+ "integrity": "sha512-gwsOE28k+23GP1B6vFl1oVh/WOzmawBrKwo5Ev6wMKzPkaXaCDIQKzLnvsA42DRlbVTWorkgTKIviAKCWkfUwA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=10"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
"node_modules/lightningcss": {
"version": "1.32.0",
"resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
@@ -916,6 +1409,13 @@
"url": "https://opencollective.com/parcel"
}
},
+ "node_modules/lodash": {
+ "version": "4.18.1",
+ "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+ "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/magic-string": {
"version": "0.30.21",
"resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -926,10 +1426,77 @@
"@jridgewell/sourcemap-codec": "^1.5.5"
}
},
+ "node_modules/math-intrinsics": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
+ "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ }
+ },
+ "node_modules/micromatch": {
+ "version": "4.0.8",
+ "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
+ "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "braces": "^3.0.3",
+ "picomatch": "^2.3.1"
+ },
+ "engines": {
+ "node": ">=8.6"
+ }
+ },
+ "node_modules/micromatch/node_modules/picomatch": {
+ "version": "2.3.2",
+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+ "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/jonschlinkert"
+ }
+ },
+ "node_modules/mime-db": {
+ "version": "1.52.0",
+ "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
+ "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
+ "node_modules/mime-types": {
+ "version": "2.1.35",
+ "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
+ "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "mime-db": "1.52.0"
+ },
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
+ "node_modules/ms": {
+ "version": "2.1.3",
+ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+ "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/nanoid": {
- "version": "3.3.11",
- "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
- "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+ "version": "3.3.12",
+ "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+ "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
"dev": true,
"funding": [
{
@@ -945,6 +1512,19 @@
"node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
}
},
+ "node_modules/object-inspect": {
+ "version": "1.13.4",
+ "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
+ "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
"node_modules/obug": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
@@ -984,9 +1564,9 @@
}
},
"node_modules/postcss": {
- "version": "8.5.8",
- "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
- "integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==",
+ "version": "8.5.15",
+ "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+ "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
"dev": true,
"funding": [
{
@@ -1004,7 +1584,7 @@
],
"license": "MIT",
"dependencies": {
- "nanoid": "^3.3.11",
+ "nanoid": "^3.3.12",
"picocolors": "^1.1.1",
"source-map-js": "^1.2.1"
},
@@ -1012,6 +1592,39 @@
"node": "^10 || ^12 || >=14"
}
},
+ "node_modules/proxy-from-env": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz",
+ "integrity": "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/qs": {
+ "version": "6.15.2",
+ "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
+ "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "side-channel": "^1.1.0"
+ },
+ "engines": {
+ "node": ">=0.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/requires-port": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
+ "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/rolldown": {
"version": "1.0.0-rc.15",
"resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.15.tgz",
@@ -1046,6 +1659,82 @@
"@rolldown/binding-win32-x64-msvc": "1.0.0-rc.15"
}
},
+ "node_modules/side-channel": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
+ "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0",
+ "object-inspect": "^1.13.3",
+ "side-channel-list": "^1.0.0",
+ "side-channel-map": "^1.0.1",
+ "side-channel-weakmap": "^1.0.2"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/side-channel-list": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
+ "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0",
+ "object-inspect": "^1.13.4"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/side-channel-map": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
+ "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "call-bound": "^1.0.2",
+ "es-errors": "^1.3.0",
+ "get-intrinsic": "^1.2.5",
+ "object-inspect": "^1.13.3"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/side-channel-weakmap": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
+ "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "call-bound": "^1.0.2",
+ "es-errors": "^1.3.0",
+ "get-intrinsic": "^1.2.5",
+ "object-inspect": "^1.13.3",
+ "side-channel-map": "^1.0.1"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
"node_modules/siginfo": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
@@ -1121,6 +1810,27 @@
"node": ">=14.0.0"
}
},
+ "node_modules/to-regex-range": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
+ "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "is-number": "^7.0.0"
+ },
+ "engines": {
+ "node": ">=8.0"
+ }
+ },
+ "node_modules/tos-crc64-js": {
+ "version": "0.0.1",
+ "resolved": "https://registry.npmjs.org/tos-crc64-js/-/tos-crc64-js-0.0.1.tgz",
+ "integrity": "sha512-l2Ndi9BaDH3gmAJ5VIS/1WeqFcucK41WCbw5dije24k2XtUCclYfvhntWIVHe+0S85QcED4vjqm3AO1izlQ30g==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT"
+ },
"node_modules/tslib": {
"version": "2.8.1",
"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
@@ -1129,6 +1839,19 @@
"license": "0BSD",
"optional": true
},
+ "node_modules/type-fest": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-1.4.0.tgz",
+ "integrity": "sha512-yGSza74xk0UG8k+pLh5oeoYirvIiWo5t0/o3zHHAO2tRDiZcxWP7fywNlXhqb6/r6sWvwi+RsyQMWhVLe4BVuA==",
+ "dev": true,
+ "license": "(MIT OR CC0-1.0)",
+ "engines": {
+ "node": ">=10"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
"node_modules/typescript": {
"version": "5.9.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
diff --git a/examples/openclaw-plugin/package.json b/examples/openclaw-plugin/package.json
index ece7927c1..d9b68ad75 100644
--- a/examples/openclaw-plugin/package.json
+++ b/examples/openclaw-plugin/package.json
@@ -76,6 +76,7 @@
},
"devDependencies": {
"@types/node": "^25.3.5",
+ "@volcengine/tos-sdk": "^2.9.1",
"typescript": "^5.8.0",
"vitest": "^4.1.0"
}
diff --git a/examples/openclaw-plugin/scripts/generate-release-manifest.mjs b/examples/openclaw-plugin/scripts/generate-release-manifest.mjs
new file mode 100755
index 000000000..4a802712a
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/generate-release-manifest.mjs
@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+
+const args = process.argv.slice(2);
+
+function die(message) {
+ console.error(`[generate-release-manifest] ERROR: ${message}`);
+ process.exit(1);
+}
+
+function readOption(name, fallback = "") {
+ const index = args.indexOf(name);
+ if (index === -1) {
+ return fallback;
+ }
+ const value = args[index + 1];
+ if (!value || value.startsWith("--")) {
+ die(`Missing value for ${name}`);
+ }
+ return value;
+}
+
+function readRepeated(name) {
+ const values = [];
+ for (let index = 0; index < args.length; index += 1) {
+ if (args[index] === name) {
+ const value = args[index + 1];
+ if (!value || value.startsWith("--")) {
+ die(`Missing value for ${name}`);
+ }
+ values.push(value);
+ index += 1;
+ }
+ }
+ return values;
+}
+
+function sha256(path) {
+ return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+const environment = readOption("--env");
+const version = readOption("--version");
+const tag = readOption("--tag");
+const gitHash = readOption("--git-hash");
+const notesPath = readOption("--notes", "");
+const outPath = readOption("--out", "output/manifest.json");
+const checksumsOut = readOption("--checksums-out", "");
+const bucket = readOption("--bucket", "arkclaw-openviking");
+const region = readOption("--region", "cn-beijing");
+const endpoint = readOption("--endpoint", "tos-cn-beijing.volces.com");
+const releaseDir = readOption("--release-dir", "");
+const artifacts = readRepeated("--artifact");
+
+if (!["stg", "ppe", "prod"].includes(environment)) {
+ die("--env must be one of stg, ppe, or prod");
+}
+if (!version) {
+ die("--version is required");
+}
+if (!tag) {
+ die("--tag is required");
+}
+if (!/^[0-9a-f]{40}$/i.test(gitHash)) {
+ die("--git-hash must be a 40-character git hash");
+}
+if (artifacts.length === 0) {
+ die("At least one --artifact is required");
+}
+
+const releaseNotes = notesPath ? readFileSync(notesPath, "utf8") : "";
+const artifactEntries = artifacts.map((path) => {
+ const name = basename(path);
+ const stats = statSync(path);
+ const entry = {
+ name,
+ type: name === "openviking.tgz" ? "package" : "installer",
+ path: releaseDir ? `${releaseDir}/${name}` : `${environment}/releases/${version}/${name}`,
+ size: stats.size,
+ sha256: sha256(path),
+ };
+ if (name === "install.sh") {
+ entry.entrypoint = true;
+ entry.defaultArgs = {
+ source: "tos",
+ channel: environment,
+ };
+ }
+ return entry;
+});
+
+const manifest = {
+ schemaVersion: "1.0",
+ plugin: {
+ id: "openviking",
+ packageName: "@openviking/openclaw-plugin",
+ version,
+ },
+ environment,
+ channel: environment,
+ release: {
+ version,
+ tag,
+ gitHash,
+ gitShortHash: gitHash.slice(0, 7),
+ createdAt: new Date().toISOString(),
+ createdBy: process.env.USER || process.env.CI || "unknown",
+ buildHost: process.env.HOSTNAME || "local",
+ releaseNotes,
+ },
+ compatibility: {
+ minOpenclawVersion: "2026.4.8",
+ minGatewayVersion: "2026.4.8",
+ minNodeVersion: "22.0.0",
+ },
+ artifacts: artifactEntries,
+ checksums: {
+ algorithm: "sha256",
+ file: releaseDir ? "manifest.json" : `${environment}/releases/${version}/checksums.sha256`,
+ },
+ tos: {
+ bucket,
+ region,
+ endpoint,
+ },
+ update: {
+ defaultInstall: environment === "prod",
+ rollbackAllowed: true,
+ immutable: true,
+ },
+};
+
+const checksumLines = artifactEntries.map((artifact) => `${artifact.sha256} ${artifact.name}`);
+mkdirSync(dirname(outPath), { recursive: true });
+writeFileSync(outPath, `${JSON.stringify(manifest, null, 2)}\n`);
+if (checksumsOut) {
+ mkdirSync(dirname(checksumsOut), { recursive: true });
+ writeFileSync(checksumsOut, `${checksumLines.join("\n")}\n`);
+}
diff --git a/examples/openclaw-plugin/scripts/install.sh b/examples/openclaw-plugin/scripts/install.sh
new file mode 100755
index 000000000..bf914eb78
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/install.sh
@@ -0,0 +1,571 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ -z "${BASH_VERSION:-}" ]; then
+ echo "[openviking] ERROR: install.sh requires bash" >&2
+ exit 1
+fi
+
+VERSION="2026.6.3"
+RELEASE_PATH="${INSTALL_RELEASE_PATH:-latest}"
+PLUGIN_ID="openviking"
+PACKAGE_NAME="openviking"
+DEFAULT_BUCKET="arkclaw-ov"
+DEFAULT_REGION="cn-beijing"
+DEFAULT_TOS_BASE_URL=""
+
+INSTALL_TOS_BASE_URL="${INSTALL_TOS_BASE_URL:-$DEFAULT_TOS_BASE_URL}"
+INSTALL_MANIFEST_URL="${INSTALL_MANIFEST_URL:-}"
+INSTALL_BUCKET="${INSTALL_BUCKET:-$DEFAULT_BUCKET}"
+INSTALL_REGION="${INSTALL_REGION:-}"
+INSTALL_TARBALL="${INSTALL_TARBALL:-}"
+INSTALL_SOURCE="${INSTALL_SOURCE:-tos}"
+OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+SKILLS_DIR="${SKILLS_DIR:-$HOME/.agents/skills}"
+VERIFY_ONLY=0
+DRY_RUN=0
+RESTART_GATEWAY=1
+INTERNAL_DOMAIN=1
+TMP_DIR=""
+
+OPENVIKING_BASE_URL="${OPENVIKING_BASE_URL:-}"
+OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-}"
+OPENVIKING_PEER_ROLE="${OPENVIKING_PEER_ROLE:-}"
+OPENVIKING_PEER_PREFIX="${OPENVIKING_PEER_PREFIX:-}"
+OPENVIKING_ACCOUNT_ID="${OPENVIKING_ACCOUNT_ID:-}"
+OPENVIKING_USER_ID="${OPENVIKING_USER_ID:-}"
+OPENVIKING_RECALL_RESOURCES="${OPENVIKING_RECALL_RESOURCES:-0}"
+OPENVIKING_RECALL_TARGET_TYPES="${OPENVIKING_RECALL_TARGET_TYPES:-}"
+
+OPENCLAW_DIR="$OPENCLAW_STATE_DIR"
+EXTENSION_DIR="$OPENCLAW_DIR/extensions/$PLUGIN_ID"
+if [ "$PLUGIN_ID" = "openviking" ]; then
+ EXTENSION_DIR="$OPENCLAW_DIR/extensions/openviking"
+fi
+CONFIG_FILE="$OPENCLAW_DIR/openclaw.json"
+
+cleanup() {
+ if [ -n "$TMP_DIR" ] && [ -d "$TMP_DIR" ]; then
+ rm -rf "$TMP_DIR"
+ fi
+}
+trap cleanup EXIT
+trap 'echo "[openviking] ERROR: installation failed" >&2' ERR
+
+usage() {
+ cat <<'EOF'
+Usage: bash install.sh [options]
+
+This simplified installer downloads and installs openviking.tgz from a TOS
+directory. By default it downloads:
+ <tos-base-url>/latest/openviking.tgz
+
+Options:
+ --tos-base-url <url> Override TOS base URL.
+ --manifest-url <url> Override manifest URL. The package is still taken
+ from the same release directory unless manifest
+ parsing is added by the caller.
+ --bucket <bucket> Bucket name for generated regional URL.
+ --region <region> Use https://<bucket>.tos-<region>.ivolces.com.
+ --internal Use ivolces.com domain (default).
+ --external Use volces.com public domain.
+ --latest Install from latest/openviking.tgz (default).
+ --date <date> Install from <date>/openviking.tgz, e.g. 2026.6.3.
+ --release-path <path> Install from <path>/openviking.tgz.
+ --tarball <path> Install a local tgz instead of downloading.
+ --source tos|tarball|local|existing
+ Install ./openviking.tgz next to this script, or
+ use existing for parse/verify-only smoke checks.
+ --source existing Reuse the currently installed plugin and only run configuration checks.
+ --verify-only Download/validate only; do not install.
+ --dry-run Print the download/install actions only.
+ --no-restart Do not restart OpenClaw gateway after install.
+ --openclaw-state-dir <dir> Override ~/.openclaw.
+ --openviking-base-url <url>
+ --openviking-api-key <key>
+ --peer-role <role>
+ --peer-prefix <prefix>
+ --account-id <id>
+ --user-id <id>
+ --recall-resources <0|1>
+ --recall-target-types <types>
+ -h, --help
+EOF
+}
+
+info() {
+ echo "[openviking] $*"
+}
+
+die() {
+ echo "[openviking] ERROR: $*" >&2
+ exit 1
+}
+
+require_file() {
+ local path="$1"
+ if [ ! -f "$path" ]; then
+ die "Required file is missing: $path"
+ fi
+}
+
+require_dir() {
+ local path="$1"
+ if [ ! -d "$path" ]; then
+ die "Required directory is missing: $path"
+ fi
+}
+
+script_dir() {
+ cd "$(dirname "${BASH_SOURCE[0]}")" && pwd
+}
+
+normalize_base_url() {
+ printf '%s' "$1" | sed 's#/*$##'
+}
+
+discover_region() {
+ if [ -n "$INSTALL_REGION" ]; then
+ printf '%s' "$INSTALL_REGION"
+ return 0
+ fi
+
+ local region=""
+ if command -v curl >/dev/null 2>&1; then
+ region=$(curl --connect-timeout 2 --max-time 5 -fsS "http://100.96.0.96/latest/region_id" 2>/dev/null || true)
+ fi
+
+ if [ -n "$region" ]; then
+ printf '%s' "$region"
+ fi
+}
+
+resolve_tos_base_url() {
+ if [ -n "$INSTALL_TOS_BASE_URL" ]; then
+ normalize_base_url "$INSTALL_TOS_BASE_URL"
+ return 0
+ fi
+
+ local region
+ region=$(discover_region)
+ if [ -n "$region" ]; then
+ local bucket="$INSTALL_BUCKET"
+ if [ "$bucket" = "$DEFAULT_BUCKET" ]; then
+ bucket="$DEFAULT_BUCKET-$region"
+ fi
+ local domain_suffix="ivolces.com"
+ if [ "$INTERNAL_DOMAIN" -eq 0 ]; then
+ domain_suffix="volces.com"
+ fi
+ printf 'https://%s.tos-%s.%s' "$bucket" "$region" "$domain_suffix"
+ else
+ printf 'https://%s.tos-%s.volces.com' "$INSTALL_BUCKET" "$DEFAULT_REGION"
+ fi
+}
+
+package_url() {
+ local base_url
+ base_url=$(resolve_tos_base_url)
+ printf '%s/%s/openviking.tgz' "$base_url" "$RELEASE_PATH"
+}
+
+manifest_url() {
+ if [ -n "$INSTALL_MANIFEST_URL" ]; then
+ printf '%s' "$INSTALL_MANIFEST_URL"
+ return 0
+ fi
+
+ local base_url
+ base_url=$(resolve_tos_base_url)
+ printf '%s/%s/manifest.json' "$base_url" "$RELEASE_PATH"
+}
+
+download_manifest() {
+ local output="$1"
+ local manifest_url
+ manifest_url=$(manifest_url)
+ info "Downloading OpenViking release manifest: $manifest_url"
+ if ! download_url "$manifest_url" "$output"; then
+ info "Manifest is unavailable; continuing with direct package download"
+ return 1
+ fi
+ return 0
+}
+
+download_url() {
+ local url="$1"
+ local output="$2"
+
+ if [ "$DRY_RUN" -eq 1 ]; then
+ info "DRY RUN: download $url -> $output"
+ return 0
+ fi
+
+ if command -v curl >/dev/null 2>&1; then
+ curl -fL --retry 3 --connect-timeout 10 --max-time 300 "$url" -o "$output"
+ elif command -v wget >/dev/null 2>&1; then
+ wget -O "$output" "$url"
+ else
+ die "curl or wget is required to download $url"
+ fi
+}
+
+mask_secret() {
+ local value="${1:-}"
+ local length=${#value}
+ if [ "$length" -le 8 ]; then
+ echo "***"
+ else
+ printf '%s...%s' "${value:0:4}" "${value: -4}"
+ fi
+}
+
+redact_arg() {
+ local value="${1:-}"
+ if [ -n "$OPENVIKING_API_KEY" ] && [ "$value" = "$OPENVIKING_API_KEY" ]; then
+ mask_secret "$value"
+ else
+ printf '%s' "$value"
+ fi
+}
+
+run_cmd() {
+ if [ "$DRY_RUN" -eq 1 ]; then
+ printf '[openviking] DRY RUN:'
+ for arg in "$@"; do
+ printf ' %s' "$(redact_arg "$arg")"
+ done
+ printf '\n'
+ return 0
+ fi
+ "$@"
+}
+
+write_env_line() {
+ local key="$1"
+ local value="$2"
+ if [ -n "$value" ]; then
+ local escaped
+ escaped=${value//\'/\'\\\'\'}
+ printf "%s='%s'\n" "$key" "$escaped" >> "$ENV_FILE"
+ fi
+}
+
+ensure_config() {
+ mkdir -p "$OPENCLAW_DIR" "$OPENCLAW_DIR/backup"
+
+ if [ -f "$CONFIG_FILE" ]; then
+ local backup_id
+ if command -v md5 >/dev/null 2>&1; then
+ backup_id=$(md5 -q "$CONFIG_FILE")
+ else
+ backup_id=$(md5sum "$CONFIG_FILE" | awk '{print $1}')
+ fi
+ cp "$CONFIG_FILE" "$OPENCLAW_DIR/backup/openclaw.json.bak.$backup_id"
+ return 0
+ fi
+
+ cat > "$CONFIG_FILE" <<'JSON'
+{
+ "plugins": {
+ "allow": [],
+ "entries": {},
+ "slots": {}
+ }
+}
+JSON
+}
+
+update_openclaw_config() {
+ if ! command -v jq >/dev/null 2>&1; then
+ die "jq is required to update $CONFIG_FILE. Please install jq and retry."
+ fi
+
+ local context_engine
+ context_engine=$(jq -r '.plugins.slots.contextEngine // ""' "$CONFIG_FILE")
+
+ local jq_filter
+ jq_filter='.plugins = (.plugins // {})
+| .plugins.allow = (.plugins.allow // [])
+| .plugins.allow |= (if index("openviking") then . else . + ["openviking"] end)
+| .plugins.entries = (.plugins.entries // {})
+| .plugins.entries.openviking = (.plugins.entries.openviking // {})
+| .plugins.entries.openviking.enabled = true
+| .plugins.entries.openviking.config = (.plugins.entries.openviking.config // {})'
+
+ if [ -z "$context_engine" ] || [ "$context_engine" = "null" ]; then
+ jq_filter="$jq_filter | .plugins.slots = (.plugins.slots // {}) | .plugins.slots.contextEngine = \"openviking\""
+ fi
+
+ local tmp_config="${CONFIG_FILE}.tmp"
+ jq "$jq_filter" "$CONFIG_FILE" > "$tmp_config"
+ mv "$tmp_config" "$CONFIG_FILE"
+
+ if [ -n "$context_engine" ] && [ "$context_engine" != "null" ] && [ "$context_engine" != "$PLUGIN_ID" ]; then
+ echo "Existing context engine '$context_engine' was preserved."
+ echo "To switch to OpenViking, run: openclaw config set plugins.slots.contextEngine openviking"
+ fi
+}
+
+install_package_from_tgz() {
+ local tgz_path="$1"
+
+ if [ "$DRY_RUN" -eq 1 ]; then
+ info "DRY RUN: install $tgz_path -> $EXTENSION_DIR"
+ return 0
+ fi
+
+ require_file "$tgz_path"
+
+ if [ "$VERIFY_ONLY" -eq 1 ]; then
+ tar -tzf "$tgz_path" >/dev/null
+ info "Verification complete: $tgz_path"
+ return 0
+ fi
+
+ TMP_DIR=$(mktemp -d)
+ tar -xzf "$tgz_path" -C "$TMP_DIR"
+
+ local PACKAGE_DIR="$TMP_DIR/$PACKAGE_NAME"
+ require_dir "$PACKAGE_DIR"
+ require_file "$PACKAGE_DIR/package.json"
+ require_file "$PACKAGE_DIR/openclaw.plugin.json"
+ require_file "$PACKAGE_DIR/dist/index.js"
+ # Runtime dependency required by dist/index.js when OpenClaw loads this standalone package.
+ local typebox_dir="$PACKAGE_DIR/node_modules/@sinclair/typebox"
+ require_dir "$typebox_dir"
+ require_dir "$PACKAGE_DIR/node_modules/@sinclair/typebox"
+ require_dir "$PACKAGE_DIR/skills"
+
+ ensure_config
+
+ info "Deploying plugin files to $EXTENSION_DIR"
+ rm -rf "$EXTENSION_DIR"
+ mkdir -p "$EXTENSION_DIR"
+ cp -R "$PACKAGE_DIR/." "$EXTENSION_DIR/"
+
+ info "Deploying skills to $SKILLS_DIR"
+ mkdir -p "$SKILLS_DIR"
+ for skill_dir in "$PACKAGE_DIR"/skills/*/; do
+ if [ -d "$skill_dir" ]; then
+ local skill_name
+ skill_name=$(basename "$skill_dir")
+ rm -rf "$SKILLS_DIR/$skill_name"
+ cp -R "$skill_dir" "$SKILLS_DIR/$skill_name"
+ fi
+ done
+
+ update_openclaw_config
+}
+
+download_and_install() {
+ TMP_DIR=$(mktemp -d)
+ local tgz_path="$TMP_DIR/openviking.tgz"
+ local manifest_path="$TMP_DIR/manifest.json"
+ local url
+ url=$(package_url)
+
+ download_manifest "$manifest_path" || true
+ info "Downloading OpenViking package: $url"
+ download_url "$url" "$tgz_path"
+ install_package_from_tgz "$tgz_path"
+}
+
+configure_openviking_service() {
+ if [ -z "$OPENVIKING_BASE_URL" ] && [ -z "$OPENVIKING_API_KEY" ]; then
+ return 0
+ fi
+ [ -n "$OPENVIKING_BASE_URL" ] || die "OPENVIKING_BASE_URL is required when OPENVIKING_API_KEY is set"
+ [ -n "$OPENVIKING_API_KEY" ] || die "OPENVIKING_API_KEY is required when OPENVIKING_BASE_URL is set"
+
+ ENV_FILE="$OPENCLAW_DIR/openviking.env"
+ if [ "$DRY_RUN" -eq 0 ]; then
+ mkdir -p "$OPENCLAW_DIR"
+ : > "$ENV_FILE"
+ write_env_line "OPENVIKING_BASE_URL" "$OPENVIKING_BASE_URL"
+ write_env_line "OPENVIKING_API_KEY" "$OPENVIKING_API_KEY"
+ write_env_line "OPENVIKING_PEER_ROLE" "$OPENVIKING_PEER_ROLE"
+ write_env_line "OPENVIKING_PEER_PREFIX" "$OPENVIKING_PEER_PREFIX"
+ write_env_line "OPENVIKING_ACCOUNT_ID" "$OPENVIKING_ACCOUNT_ID"
+ write_env_line "OPENVIKING_USER_ID" "$OPENVIKING_USER_ID"
+ write_env_line "OPENVIKING_RECALL_RESOURCES" "$OPENVIKING_RECALL_RESOURCES"
+ write_env_line "OPENVIKING_RECALL_TARGET_TYPES" "$OPENVIKING_RECALL_TARGET_TYPES"
+ chmod 600 "$ENV_FILE"
+ else
+ info "DRY RUN: write service env -> $ENV_FILE"
+ fi
+
+ info "OpenViking Service URL: $OPENVIKING_BASE_URL"
+ info "OpenViking API Key: $(mask_secret "$OPENVIKING_API_KEY")"
+
+ set -- openclaw openviking setup --base-url "$OPENVIKING_BASE_URL" --api-key "$OPENVIKING_API_KEY" --force-slot
+ [ -z "$OPENVIKING_PEER_ROLE" ] || set -- "$@" --peer-role "$OPENVIKING_PEER_ROLE"
+ [ -z "$OPENVIKING_PEER_PREFIX" ] || set -- "$@" --peer-prefix "$OPENVIKING_PEER_PREFIX"
+ [ -z "$OPENVIKING_ACCOUNT_ID" ] || set -- "$@" --account-id "$OPENVIKING_ACCOUNT_ID"
+ [ -z "$OPENVIKING_USER_ID" ] || set -- "$@" --user-id "$OPENVIKING_USER_ID"
+ if [ "$OPENVIKING_RECALL_RESOURCES" = "1" ] && [ -z "$OPENVIKING_RECALL_TARGET_TYPES" ]; then
+ set -- "$@" --recall-target-types resource
+ run_cmd openclaw config set plugins.entries.openviking.config.recallTargetTypes '["resource"]'
+ fi
+ [ -z "$OPENVIKING_RECALL_TARGET_TYPES" ] || set -- "$@" --recall-target-types "$OPENVIKING_RECALL_TARGET_TYPES"
+ run_cmd "$@"
+}
+
+restart_gateway() {
+ if [ "$VERIFY_ONLY" -eq 1 ] || [ "$RESTART_GATEWAY" -eq 0 ]; then
+ return 0
+ fi
+
+ if command -v openclaw >/dev/null 2>&1; then
+ info "Restarting OpenClaw gateway"
+ if ! run_cmd openclaw gateway restart; then
+ echo "Gateway restart failed. Please run manually: openclaw gateway restart" >&2
+ fi
+ run_cmd openclaw openviking status --json || true
+ run_cmd openclaw config get plugins.slots.contextEngine || true
+ else
+ echo "openclaw CLI was not found. Please install OpenClaw and run: openclaw gateway restart" >&2
+ fi
+}
+
+install_source="$INSTALL_SOURCE"
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --tos-base-url)
+ INSTALL_TOS_BASE_URL="${2:-}"
+ shift 2
+ ;;
+ --manifest-url)
+ INSTALL_MANIFEST_URL="${2:-}"
+ shift 2
+ ;;
+ --bucket)
+ INSTALL_BUCKET="${2:-}"
+ shift 2
+ ;;
+ --region)
+ INSTALL_REGION="${2:-}"
+ shift 2
+ ;;
+ --internal)
+ INTERNAL_DOMAIN=1
+ shift
+ ;;
+ --external)
+ INTERNAL_DOMAIN=0
+ shift
+ ;;
+ --latest)
+ RELEASE_PATH="latest"
+ shift
+ ;;
+ --date|--version)
+ RELEASE_PATH="${2:-}"
+ shift 2
+ ;;
+ --release-path)
+ RELEASE_PATH="${2:-}"
+ shift 2
+ ;;
+ --tarball)
+ INSTALL_TARBALL="${2:-}"
+ install_source="local"
+ shift 2
+ ;;
+ --source)
+ case "${2:-}" in
+ local|tarball) install_source="local" ;;
+ existing) install_source="existing" ;;
+ tos|remote) install_source="remote" ;;
+ *) die "Invalid --source: ${2:-}. Expected tos, remote, local, tarball, or existing." ;;
+ esac
+ shift 2
+ ;;
+ --verify-only)
+ VERIFY_ONLY=1
+ shift
+ ;;
+ --dry-run)
+ DRY_RUN=1
+ shift
+ ;;
+ --no-restart)
+ RESTART_GATEWAY=0
+ shift
+ ;;
+ --openclaw-state-dir)
+ OPENCLAW_STATE_DIR="${2:-}"
+ OPENCLAW_DIR="$OPENCLAW_STATE_DIR"
+ EXTENSION_DIR="$OPENCLAW_DIR/extensions/$PLUGIN_ID"
+ CONFIG_FILE="$OPENCLAW_DIR/openclaw.json"
+ shift 2
+ ;;
+ --base-url|--openviking-base-url)
+ OPENVIKING_BASE_URL="${2:-}"
+ shift 2
+ ;;
+ --api-key|--openviking-api-key)
+ OPENVIKING_API_KEY="${2:-}"
+ shift 2
+ ;;
+ --peer-role)
+ OPENVIKING_PEER_ROLE="${2:-}"
+ shift 2
+ ;;
+ --peer-prefix)
+ OPENVIKING_PEER_PREFIX="${2:-}"
+ shift 2
+ ;;
+ --account-id)
+ OPENVIKING_ACCOUNT_ID="${2:-}"
+ shift 2
+ ;;
+ --user-id)
+ OPENVIKING_USER_ID="${2:-}"
+ shift 2
+ ;;
+ --recall-resources)
+ OPENVIKING_RECALL_RESOURCES="${2:-}"
+ shift 2
+ ;;
+ --recall-target-types)
+ OPENVIKING_RECALL_TARGET_TYPES="${2:-}"
+ shift 2
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ --*)
+ die "Unknown option: $1"
+ ;;
+ *)
+ INSTALL_TARBALL="$1"
+ install_source="local"
+ shift
+ ;;
+ esac
+done
+
+echo
+info "Installing OpenViking plugin release $VERSION from $RELEASE_PATH"
+
+if [ "$install_source" = "existing" ]; then
+ info "Using existing OpenViking installation; no package download or file changes will be performed"
+elif [ "$install_source" = "local" ]; then
+ if [ -z "$INSTALL_TARBALL" ]; then
+ INSTALL_TARBALL="$(script_dir)/openviking.tgz"
+ fi
+ install_package_from_tgz "$INSTALL_TARBALL"
+else
+ download_and_install
+fi
+
+if [ "$VERIFY_ONLY" -eq 0 ]; then
+ configure_openviking_service
+ restart_gateway
+fi
+
+echo
+info "OpenViking plugin install complete"
diff --git a/examples/openclaw-plugin/scripts/release-to-tos.sh b/examples/openclaw-plugin/scripts/release-to-tos.sh
new file mode 100644
index 000000000..481bef68d
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/release-to-tos.sh
@@ -0,0 +1,136 @@
+#!/bin/bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+VERSION=""
+TAG=""
+RELEASE_DIR=""
+DRY_RUN=0
+PUBLISH_LATEST=0
+
+usage() {
+ cat <<'EOF'
+Usage: scripts/release-to-tos.sh [options]
+
+Build and publish the simplified OpenViking TOS release bundle:
+ install.sh, openviking.tgz, manifest.json
+
+Options:
+ --release-dir <date> Date directory to upload, e.g. 2026.6.3.
+ Defaults to today's yyyy.m.d.
+ --version <version> Release version metadata. Defaults to package.json version.
+ --tag <tag> Git tag metadata. Defaults to v<version>.
+ --publish-latest Also upload the three files to latest/.
+ Use only after the dated release is validated stable.
+ --dry-run Build/generate metadata and print uploads without writing TOS.
+ -h, --help Show this help.
+
+Required for non-dry-run uploads:
+ TEAM_TEST_AK
+ TEAM_TEST_SK
+EOF
+}
+
+die() {
+ echo "[release-to-tos] ERROR: $*" >&2
+ exit 1
+}
+
+info() {
+ echo "[release-to-tos] $*"
+}
+
+today_release_dir() {
+ node -e 'const d = new Date(); process.stdout.write(`${d.getFullYear()}.${d.getMonth() + 1}.${d.getDate()}`);'
+}
+
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --release-dir|--date)
+ RELEASE_DIR="${2:-}"
+ shift 2
+ ;;
+ --version)
+ VERSION="${2:-}"
+ shift 2
+ ;;
+ --tag)
+ TAG="${2:-}"
+ shift 2
+ ;;
+ --publish-latest)
+ PUBLISH_LATEST=1
+ shift
+ ;;
+ --dry-run)
+ DRY_RUN=1
+ shift
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ die "Unknown option: $1"
+ ;;
+ esac
+done
+
+cd "$ROOT_DIR"
+
+if [ "$DRY_RUN" -ne 1 ]; then
+ [ -n "${TEAM_TEST_AK:-}" ] || die "TEAM_TEST_AK is required for non-dry-run release"
+ [ -n "${TEAM_TEST_SK:-}" ] || die "TEAM_TEST_SK is required for non-dry-run release"
+fi
+
+if [ -z "$RELEASE_DIR" ]; then
+ RELEASE_DIR=$(today_release_dir)
+fi
+if [ -z "$VERSION" ]; then
+ VERSION=$(node -e 'const fs = require("fs"); process.stdout.write(JSON.parse(fs.readFileSync("package.json", "utf8")).version);')
+fi
+if [ -z "$TAG" ]; then
+ TAG="v$VERSION"
+fi
+
+GIT_HASH=$(git rev-parse HEAD)
+
+info "Building simplified TOS package version=$VERSION release_dir=$RELEASE_DIR tag=$TAG"
+BUILD_RELEASE_PATH="$RELEASE_DIR" BUILD_VERSION="$VERSION" bash "$ROOT_DIR/build.sh"
+
+node "$ROOT_DIR/scripts/generate-release-manifest.mjs" \
+ --env "prod" \
+ --version "$VERSION" \
+ --tag "$TAG" \
+ --git-hash "$GIT_HASH" \
+ --artifact "$ROOT_DIR/output/openviking.tgz" \
+ --artifact "$ROOT_DIR/output/install.sh" \
+ --bucket "arkclaw-ov" \
+ --region "cn-beijing" \
+ --endpoint "tos-cn-beijing.volces.com" \
+ --release-dir "$RELEASE_DIR" \
+ --out "$ROOT_DIR/output/manifest.json"
+
+info "Generated output/manifest.json"
+
+upload_args=(
+ "$ROOT_DIR/scripts/upload_tos.py"
+ --release-dir "$RELEASE_DIR"
+ --install-sh "$ROOT_DIR/output/install.sh"
+ --tgz "$ROOT_DIR/output/openviking.tgz"
+ --manifest "$ROOT_DIR/output/manifest.json"
+)
+if [ "$PUBLISH_LATEST" -eq 1 ]; then
+ upload_args+=(--publish-latest)
+fi
+if [ "$DRY_RUN" -eq 1 ]; then
+ upload_args+=(--dry-run)
+fi
+
+python3 "${upload_args[@]}"
+
+info "TOS release complete"
+info "Date path: $RELEASE_DIR/"
+info "Latest updated: $PUBLISH_LATEST"
diff --git a/examples/openclaw-plugin/scripts/resolve-release-version.mjs b/examples/openclaw-plugin/scripts/resolve-release-version.mjs
new file mode 100644
index 000000000..3d4f89f9a
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/resolve-release-version.mjs
@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+
+const args = process.argv.slice(2);
+
+function die(message) {
+ console.error(`[resolve-release-version] ERROR: ${message}`);
+ process.exit(1);
+}
+
+function readOption(name, fallback = "") {
+ const index = args.indexOf(name);
+ if (index === -1) return fallback;
+ const value = args[index + 1];
+ if (!value || value.startsWith("--")) die(`Missing value for ${name}`);
+ return value;
+}
+
+function hasFlag(name) {
+ return args.includes(name);
+}
+
+function readPackageVersion(packagePath) {
+ return JSON.parse(readFileSync(packagePath, "utf8")).version;
+}
+
+function stableBase(version) {
+ const match = String(version).match(/^(\d{4}\.\d{1,2}\.\d{1,2})(?:-beta\.\d+)?$/);
+ if (!match) die(`Invalid release version: ${version}`);
+ return match[1];
+}
+
+function channelOf(version) {
+ return /-beta\.\d+$/.test(version) ? "beta" : "stable";
+}
+
+function nextBetaVersion(baseVersion, existingVersions) {
+ const prefix = `${baseVersion}-beta.`;
+ const maxBeta = existingVersions.reduce((max, version) => {
+ if (!version.startsWith(prefix)) return max;
+ const number = Number(version.slice(prefix.length));
+ return Number.isInteger(number) && number > max ? number : max;
+ }, 0);
+ return `${prefix}${maxBeta + 1}`;
+}
+
+const packagePath = readOption("--package", "package.json");
+const explicitVersion = readOption("--version", "");
+const existingVersions = readOption("--existing-versions", "")
+ .split(/[,\n]/)
+ .map((version) => version.trim())
+ .filter(Boolean);
+const stable = hasFlag("--stable");
+
+let version;
+if (explicitVersion) {
+ version = explicitVersion;
+} else {
+ const base = stableBase(readPackageVersion(packagePath));
+ version = stable ? base : nextBetaVersion(base, existingVersions);
+}
+
+console.log(JSON.stringify({
+ version,
+ tag: `v${version}`,
+ channel: stable ? "stable" : channelOf(version),
+}));
diff --git a/examples/openclaw-plugin/scripts/test_upload_tos.py b/examples/openclaw-plugin/scripts/test_upload_tos.py
new file mode 100755
index 000000000..8c568ff43
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/test_upload_tos.py
@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+
+import importlib.util
+import pathlib
+import re
+
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+MODULE_PATH = SCRIPT_DIR / "upload_tos.py"
+
+
+def load_module():
+ spec = importlib.util.spec_from_file_location("upload_tos", MODULE_PATH)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_bucket_specs_cover_all_regions():
+ module = load_module()
+ assert re.match(r"^\d{4}\.\d{1,2}\.\d{1,2}$", module.default_release_dir())
+ assert [spec.bucket for spec in module.BUCKET_SPECS] == [
+ "arkclaw-ov-cn-beijing",
+ "arkclaw-ov-cn-guangzhou",
+ "arkclaw-ov-cn-shanghai",
+ "arkclaw-ov",
+ ]
+ assert [spec.region for spec in module.BUCKET_SPECS] == [
+ "cn-beijing",
+ "cn-guangzhou",
+ "cn-shanghai",
+ "cn-beijing",
+ ]
+
+
+def test_object_keys_and_public_urls():
+ module = load_module()
+ spec = module.BucketSpec("arkclaw-ov-cn-guangzhou", "cn-guangzhou")
+ assert module.release_paths("2026.6.3", publish_latest=False) == ["2026.6.3"]
+ assert module.release_paths("2026.6.3", publish_latest=True) == ["2026.6.3", "latest"]
+ assert module.object_key("2026.6.3", "install.sh") == "2026.6.3/install.sh"
+ assert module.object_key("latest", "openviking.tgz") == "latest/openviking.tgz"
+ assert module.object_key("latest", "manifest.json") == "latest/manifest.json"
+ assert re.match(
+ r"^https://arkclaw-ov-cn-guangzhou\.tos-cn-guangzhou\.ivolces\.com/\d{4}\.\d{1,2}\.\d{1,2}/install\.sh$",
+ module.public_url(spec, "install.sh"),
+ )
+ assert module.public_url(spec, "install.sh", release_path="2026.6.3") == (
+ "https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.ivolces.com/2026.6.3/install.sh"
+ )
+ assert module.public_url(spec, "install.sh", release_path="latest", internal=False) == (
+ "https://arkclaw-ov-cn-guangzhou.tos-cn-guangzhou.volces.com/latest/install.sh"
+ )
+
+
+def test_release_dir_can_be_specified_and_is_not_hardcoded():
+ module = load_module()
+ custom_release_dir = "2026.7.15"
+
+ assert module.release_paths(custom_release_dir, publish_latest=False) == [custom_release_dir]
+ assert module.release_paths(custom_release_dir, publish_latest=True) == [
+ custom_release_dir,
+ "latest",
+ ]
+ assert module.object_key(custom_release_dir, "manifest.json") == "2026.7.15/manifest.json"
+
+
+def test_upload_sets_public_read_acl_and_content_types(tmp_path):
+ module = load_module()
+ install = tmp_path / "install.sh"
+ tgz = tmp_path / "openviking.tgz"
+ manifest = tmp_path / "manifest.json"
+ install.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+ tgz.write_bytes(b"tgz")
+ manifest.write_text('{"schemaVersion":"1.0"}\n', encoding="utf-8")
+
+ calls = []
+
+ class FakeClient:
+ def put_object_from_file(self, **kwargs):
+ calls.append(kwargs)
+
+ def put_object_acl(self, **kwargs):
+ calls.append(
+ {"acl_bucket": kwargs["bucket"], "acl_key": kwargs["key"], "acl": kwargs["acl"]}
+ )
+
+ def head_object(self, bucket, key):
+ calls.append({"head_bucket": bucket, "head_key": key})
+
+ module.upload_files(
+ FakeClient(),
+ module.BucketSpec("arkclaw-ov-cn-beijing", "cn-beijing"),
+ [install, tgz, manifest],
+ ["2026.6.3"],
+ dry_run=False,
+ )
+
+ uploads = [call for call in calls if "file_path" in call]
+ assert uploads[0]["bucket"] == "arkclaw-ov-cn-beijing"
+ assert uploads[0]["key"] == "2026.6.3/install.sh"
+ assert uploads[0]["acl"] == module.tos.ACLType.ACL_Public_Read
+ assert uploads[0]["content_type"] == "text/x-shellscript; charset=utf-8"
+ assert uploads[1]["key"] == "2026.6.3/openviking.tgz"
+ assert uploads[1]["acl"] == module.tos.ACLType.ACL_Public_Read
+ assert uploads[1]["content_type"] == "application/gzip"
+ assert uploads[2]["key"] == "2026.6.3/manifest.json"
+ assert uploads[2]["acl"] == module.tos.ACLType.ACL_Public_Read
+ assert uploads[2]["content_type"] == "application/json; charset=utf-8"
+ acl_calls = [call for call in calls if "acl_key" in call]
+ assert [call["acl_key"] for call in acl_calls] == [
+ "2026.6.3/install.sh",
+ "2026.6.3/openviking.tgz",
+ "2026.6.3/manifest.json",
+ ]
+
+
+def test_ensure_bucket_creates_missing_bucket():
+ module = load_module()
+ calls = []
+
+ class MissingBucketError(Exception):
+ status_code = 404
+
+ class FakeClient:
+ def head_bucket(self, bucket):
+ calls.append(("head_bucket", bucket))
+ raise MissingBucketError("missing bucket")
+
+ def create_bucket(self, **kwargs):
+ calls.append(("create_bucket", kwargs))
+
+ spec = module.BucketSpec("arkclaw-ov-cn-guangzhou", "cn-guangzhou")
+ module.ensure_bucket(FakeClient(), spec, dry_run=False)
+
+ assert calls == [
+ ("head_bucket", "arkclaw-ov-cn-guangzhou"),
+ ("create_bucket", {"bucket": "arkclaw-ov-cn-guangzhou"}),
+ ]
+
+
+def test_ensure_bucket_dry_run_does_not_create_bucket():
+ module = load_module()
+
+ class FakeClient:
+ def head_bucket(self, bucket):
+ raise AssertionError("dry-run must not call TOS")
+
+ def create_bucket(self, **kwargs):
+ raise AssertionError("dry-run must not call TOS")
+
+ module.ensure_bucket(FakeClient(), module.BucketSpec("arkclaw-ov", "cn-beijing"), dry_run=True)
+
+
+def test_publish_latest_requires_explicit_flag(tmp_path):
+ module = load_module()
+ install = tmp_path / "install.sh"
+ tgz = tmp_path / "openviking.tgz"
+ manifest = tmp_path / "manifest.json"
+ install.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+ tgz.write_bytes(b"tgz")
+ manifest.write_text('{"schemaVersion":"1.0"}\n', encoding="utf-8")
+
+ calls = []
+
+ class FakeClient:
+ def put_object_from_file(self, **kwargs):
+ calls.append(kwargs)
+
+ def put_object_acl(self, **kwargs):
+ calls.append({"acl_key": kwargs["key"]})
+
+ def head_object(self, bucket, key):
+ calls.append({"head_key": key})
+
+ module.upload_files(
+ FakeClient(),
+ module.BucketSpec("arkclaw-ov-cn-beijing", "cn-beijing"),
+ [install, tgz, manifest],
+ module.release_paths("2026.6.3", publish_latest=True),
+ dry_run=False,
+ )
+
+ uploads = [call for call in calls if "file_path" in call]
+ assert [upload["key"] for upload in uploads] == [
+ "2026.6.3/install.sh",
+ "2026.6.3/openviking.tgz",
+ "2026.6.3/manifest.json",
+ "latest/install.sh",
+ "latest/openviking.tgz",
+ "latest/manifest.json",
+ ]
+
+
+def test_install_script_supports_manifest_url_and_regional_manifest_download():
+ install_script = (SCRIPT_DIR / "install.sh").read_text(encoding="utf-8")
+
+ assert "--manifest-url <url>" in install_script
+ assert "manifest_url()" in install_script
+ assert "download_manifest" in install_script
+ assert "manifest_url=$(manifest_url)" in install_script
+ assert "printf '%s/%s/manifest.json'" in install_script
+
+
+if __name__ == "__main__":
+ test_bucket_specs_cover_all_regions()
+ test_object_keys_and_public_urls()
+ test_release_dir_can_be_specified_and_is_not_hardcoded()
+ test_ensure_bucket_creates_missing_bucket()
+ test_ensure_bucket_dry_run_does_not_create_bucket()
+ import tempfile
+
+ class TmpPath:
+ def __enter__(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ return pathlib.Path(self._tmp.name)
+
+ def __exit__(self, exc_type, exc, tb):
+ self._tmp.cleanup()
+
+ with TmpPath() as tmp_path:
+ test_upload_sets_public_read_acl_and_content_types(tmp_path)
+ with TmpPath() as tmp_path:
+ test_publish_latest_requires_explicit_flag(tmp_path)
+ test_install_script_supports_manifest_url_and_regional_manifest_download()
+ print("upload_tos.py tests passed")
diff --git a/examples/openclaw-plugin/scripts/tos-release-client.mjs b/examples/openclaw-plugin/scripts/tos-release-client.mjs
new file mode 100644
index 000000000..0afad078e
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/tos-release-client.mjs
@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+console.error(
+ "[tos-release-client] Simplified TOS protocol is now handled by scripts/release-to-tos.sh " +
+ "and scripts/upload_tos.py. The previous multi-version Node.js release client is deprecated.",
+);
+process.exit(1);
diff --git a/examples/openclaw-plugin/scripts/upload_tos.py b/examples/openclaw-plugin/scripts/upload_tos.py
new file mode 100755
index 000000000..56e328fc3
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/upload_tos.py
@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import pathlib
+import re
+import tempfile
+from typing import NamedTuple
+
+import tos
+
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+DEFAULT_INSTALL_SH = SCRIPT_DIR / "install.sh"
+DEFAULT_TGZ = SCRIPT_DIR / "openviking.tgz"
+DEFAULT_MANIFEST = SCRIPT_DIR / "manifest.json"
+
+
+class BucketSpec(NamedTuple):
+ bucket: str
+ region: str
+
+
+BUCKET_SPECS = [
+ BucketSpec("arkclaw-ov-cn-beijing", "cn-beijing"),
+ BucketSpec("arkclaw-ov-cn-guangzhou", "cn-guangzhou"),
+ BucketSpec("arkclaw-ov-cn-shanghai", "cn-shanghai"),
+ BucketSpec("arkclaw-ov", "cn-beijing"),
+]
+
+
+def default_release_dir(today: datetime.date | None = None) -> str:
+ today = today or datetime.date.today()
+ return f"{today.year}.{today.month}.{today.day}"
+
+
+def object_key(release_path: str, file_name: str) -> str:
+ return f"{release_path}/{file_name}"
+
+
+def release_paths(release_dir: str, publish_latest: bool = False) -> list[str]:
+ paths = [release_dir]
+ if publish_latest:
+ paths.append("latest")
+ return paths
+
+
+def endpoint(region: str) -> str:
+ return f"https://tos-{region}.volces.com"
+
+
+def public_url(
+ spec: BucketSpec, file_name: str, release_path: str | None = None, internal: bool = True
+) -> str:
+ suffix = "ivolces.com" if internal else "volces.com"
+ release_path = release_path or default_release_dir()
+ return f"https://{spec.bucket}.tos-{spec.region}.{suffix}/{object_key(release_path, file_name)}"
+
+
+def bucket_base_url(spec: BucketSpec, internal: bool = True) -> str:
+ suffix = "ivolces.com" if internal else "volces.com"
+ return f"https://{spec.bucket}.tos-{spec.region}.{suffix}"
+
+
+def content_type(path: pathlib.Path) -> str:
+ if path.name == "install.sh":
+ return "text/x-shellscript; charset=utf-8"
+ if path.name.endswith(".tgz"):
+ return "application/gzip"
+ if path.name == "manifest.json" or path.suffix == ".json":
+ return "application/json; charset=utf-8"
+ return "application/octet-stream"
+
+
+def require_file(path: pathlib.Path) -> None:
+ if not path.is_file():
+ raise FileNotFoundError(f"required file is missing: {path}")
+
+
+def file_sha256(path: pathlib.Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as file:
+ for chunk in iter(lambda: file.read(1024 * 1024), b""):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def make_client(spec: BucketSpec):
+ ak = os.environ.get("TEAM_TEST_AK")
+ sk = os.environ.get("TEAM_TEST_SK")
+ if not ak or not sk:
+ raise RuntimeError("TEAM_TEST_AK and TEAM_TEST_SK must be configured in the environment")
+ return tos.TosClientV2(ak=ak, sk=sk, endpoint=endpoint(spec.region), region=spec.region)
+
+
+def is_not_found_error(err: Exception) -> bool:
+ status = (
+ getattr(err, "status_code", None)
+ or getattr(err, "status", None)
+ or getattr(err, "code", None)
+ )
+ message = str(getattr(err, "message", "") or err).lower()
+ code = str(getattr(err, "code", "")).lower()
+ return status == 404 or "notfound" in code or "not found" in message or "nosuchbucket" in code
+
+
+def ensure_bucket(client, spec: BucketSpec, dry_run: bool = False) -> None:
+ if dry_run:
+ print(f"DRY RUN ensure bucket tos://{spec.bucket} region={spec.region}")
+ return
+
+ try:
+ client.head_bucket(spec.bucket)
+ return
+ except Exception as err:
+ if not is_not_found_error(err):
+ raise
+
+ client.create_bucket(bucket=spec.bucket)
+
+
+def upload_one(
+ client, spec: BucketSpec, release_path: str, path: pathlib.Path, dry_run: bool = False
+) -> None:
+ key = object_key(release_path, path.name)
+ if dry_run:
+ print(f"DRY RUN upload {path} -> tos://{spec.bucket}/{key} overwrite=true acl=public-read")
+ return
+
+ client.put_object_from_file(
+ bucket=spec.bucket,
+ key=key,
+ file_path=str(path),
+ acl=tos.ACLType.ACL_Public_Read,
+ content_type=content_type(path),
+ forbid_overwrite=False,
+ )
+ client.put_object_acl(bucket=spec.bucket, key=key, acl=tos.ACLType.ACL_Public_Read)
+ client.head_object(bucket=spec.bucket, key=key)
+
+
+def stamp_bucket_installer(
+ install_sh: pathlib.Path, spec: BucketSpec, release_path: str, output_dir: pathlib.Path
+) -> pathlib.Path:
+ text = install_sh.read_text(encoding="utf-8")
+ text = re.sub(
+ r'^DEFAULT_TOS_BASE_URL=".*"$',
+ f'DEFAULT_TOS_BASE_URL="{bucket_base_url(spec)}"',
+ text,
+ flags=re.MULTILINE,
+ )
+ text = re.sub(
+ r'^RELEASE_PATH="\$\{INSTALL_RELEASE_PATH:-.*\}"$',
+ f'RELEASE_PATH="${{INSTALL_RELEASE_PATH:-{release_path}}}"',
+ text,
+ flags=re.MULTILINE,
+ )
+ stamped = output_dir / "install.sh"
+ stamped.write_text(text, encoding="utf-8")
+ stamped.chmod(0o755)
+ return stamped
+
+
+def stamp_bucket_manifest(
+ manifest: pathlib.Path,
+ spec: BucketSpec,
+ release_path: str,
+ stamped_install: pathlib.Path,
+ output_dir: pathlib.Path,
+) -> pathlib.Path:
+ data = json.loads(manifest.read_text(encoding="utf-8"))
+ data["tos"] = {
+ "bucket": spec.bucket,
+ "region": spec.region,
+ "endpoint": f"tos-{spec.region}.volces.com",
+ }
+ for artifact in data.get("artifacts", []):
+ if artifact.get("name") == "install.sh":
+ artifact["path"] = object_key(release_path, "install.sh")
+ artifact["size"] = stamped_install.stat().st_size
+ artifact["sha256"] = file_sha256(stamped_install)
+ elif artifact.get("path"):
+ artifact["path"] = object_key(
+ release_path, pathlib.PurePosixPath(artifact["path"]).name
+ )
+ stamped = output_dir / "manifest.json"
+ stamped.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ return stamped
+
+
+def upload_bucket_installer(
+ client,
+ spec: BucketSpec,
+ release_path: str,
+ install_sh: pathlib.Path,
+ output_dir: pathlib.Path,
+ dry_run: bool = False,
+) -> pathlib.Path:
+ stamped = stamp_bucket_installer(install_sh, spec, release_path, output_dir)
+ upload_one(client, spec, release_path, stamped, dry_run=dry_run)
+ return stamped
+
+
+def upload_files(
+ client, spec: BucketSpec, artifacts: list[pathlib.Path], paths: list[str], dry_run: bool = False
+) -> None:
+ install_sh = next((artifact for artifact in artifacts if artifact.name == "install.sh"), None)
+ manifest = next((artifact for artifact in artifacts if artifact.name == "manifest.json"), None)
+ for release_path in paths:
+ with tempfile.TemporaryDirectory(prefix="openviking-installer-") as tmp:
+ tmp_dir = pathlib.Path(tmp)
+ stamped_install = (
+ upload_bucket_installer(
+ client, spec, release_path, install_sh, tmp_dir, dry_run=dry_run
+ )
+ if install_sh
+ else None
+ )
+ stamped_manifest = (
+ stamp_bucket_manifest(manifest, spec, release_path, stamped_install, tmp_dir)
+ if manifest and stamped_install
+ else None
+ )
+ for artifact in artifacts:
+ if artifact.name == "install.sh":
+ continue
+ if artifact.name == "manifest.json" and stamped_manifest:
+ upload_one(client, spec, release_path, stamped_manifest, dry_run=dry_run)
+ else:
+ upload_one(client, spec, release_path, artifact, dry_run=dry_run)
+
+
+def parse_args():
+ parser = argparse.ArgumentParser(
+ description="Upload OpenViking install.sh, openviking.tgz, and manifest.json to all TOS buckets."
+ )
+ parser.add_argument("--install-sh", type=pathlib.Path, default=DEFAULT_INSTALL_SH)
+ parser.add_argument("--tgz", type=pathlib.Path, default=DEFAULT_TGZ)
+ parser.add_argument("--manifest", type=pathlib.Path, default=DEFAULT_MANIFEST)
+ parser.add_argument(
+ "--release-dir",
+ default="",
+ help="Date release directory, for example 2026.6.3. Defaults to today's yyyy.m.d.",
+ )
+ parser.add_argument(
+ "--publish-latest",
+ action="store_true",
+ help="Also upload the same files to latest/. Use only after the dated release has been validated as stable.",
+ )
+ parser.add_argument("--dry-run", action="store_true")
+ return parser.parse_args()
+
+
+def main() -> int:
+ args = parse_args()
+ install_sh = args.install_sh.resolve()
+ tgz = args.tgz.resolve()
+ manifest = args.manifest.resolve()
+ require_file(install_sh)
+ require_file(tgz)
+ require_file(manifest)
+
+ artifacts = [install_sh, tgz, manifest]
+ release_dir = args.release_dir or default_release_dir()
+ paths = release_paths(release_dir, publish_latest=args.publish_latest)
+
+ for spec in BUCKET_SPECS:
+ print(f"Uploading to bucket={spec.bucket} region={spec.region}")
+ client = None if args.dry_run else make_client(spec)
+ ensure_bucket(client, spec, dry_run=args.dry_run)
+ upload_files(client, spec, artifacts, paths, dry_run=args.dry_run)
+ for release_path in paths:
+ print(
+ f" {release_path}/install.sh: {public_url(spec, 'install.sh', release_path=release_path)}"
+ )
+ print(
+ f" {release_path}/openviking.tgz: {public_url(spec, 'openviking.tgz', release_path=release_path)}"
+ )
+ print(
+ f" {release_path}/manifest.json: {public_url(spec, 'manifest.json', release_path=release_path)}"
+ )
+
+ if not args.publish_latest:
+ print(
+ "latest/ was not updated. Re-run with --publish-latest only after the dated release is stable."
+ )
+
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/examples/openclaw-plugin/scripts/volcengine-openviking-install.sh b/examples/openclaw-plugin/scripts/volcengine-openviking-install.sh
new file mode 100755
index 000000000..3d3d8ca0d
--- /dev/null
+++ b/examples/openclaw-plugin/scripts/volcengine-openviking-install.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# Compatibility wrapper: Volcengine-specific installation is now handled by the
+# single global install.sh entrypoint.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+exec "$SCRIPT_DIR/install.sh" "$@"
diff --git a/examples/openclaw-plugin/tests/ut/recall-trace.test.ts b/examples/openclaw-plugin/tests/ut/recall-trace.test.ts
index 8ce34bf1e..13456b8c1 100644
--- a/examples/openclaw-plugin/tests/ut/recall-trace.test.ts
+++ b/examples/openclaw-plugin/tests/ut/recall-trace.test.ts
@@ -157,7 +157,7 @@ describe("RecallTraceJsonlStore", () => {
it("persists traces by day and lets a new store query them after flush", async () => {
const dir = makeTempDir();
const store = new RecallTraceJsonlStore({ dir });
- await store.append(makeTrace({ traceId: "persisted", ts: Date.UTC(2026, 5, 1), sessionId: "session-jsonl" }));
+ await store.append(makeTrace({ traceId: "persisted", ts: Date.now(), sessionId: "session-jsonl" }));
await store.flush();
const reloaded = new RecallTraceJsonlStore({ dir });
@@ -173,7 +173,7 @@ describe("RecallTraceJsonlStore", () => {
const store = new RecallTraceJsonlStore({ dir });
await store.append(makeTrace({
traceId: "redacted-preview",
- ts: Date.UTC(2026, 5, 1),
+ ts: Date.now(),
trigger: {
query: "safe query",
rawUserTextPreview: "private user wording",
@@ -276,7 +276,7 @@ describe("RecallTraceRecorder", () => {
await recorder.recordAndFlush(makeTrace({
traceId: "durable-before-return",
sessionId: "durable-session",
- ts: Date.UTC(2026, 5, 1),
+ ts: Date.now(),
}));
const freshReader = new RecallTraceRecorder({
diff --git a/examples/openclaw-plugin/tests/ut/tos-release-contract.test.ts b/examples/openclaw-plugin/tests/ut/tos-release-contract.test.ts
new file mode 100644
index 000000000..d2fbaee34
--- /dev/null
+++ b/examples/openclaw-plugin/tests/ut/tos-release-contract.test.ts
@@ -0,0 +1,249 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const rootDir = join(__dirname, "../..");
+
+function readText(path: string): string {
+ return readFileSync(join(rootDir, path), "utf8");
+}
+
+function resolveReleaseVersion(args: string[]): { version: string; tag: string; channel: string } {
+ return JSON.parse(execFileSync("node", [join(rootDir, "scripts/resolve-release-version.mjs"), ...args], {
+ encoding: "utf8",
+ }));
+}
+
+describe("TOS release and single installer contract", () => {
+ it("generates a release manifest and checksums for artifacts", () => {
+ const tempDir = mkdtempSync(join(tmpdir(), "openviking-manifest-"));
+ const packagePath = join(tempDir, "openviking.tgz");
+ const installerPath = join(tempDir, "install.sh");
+ const notesPath = join(tempDir, "release-notes.md");
+ const manifestPath = join(tempDir, "manifest.json");
+ const checksumsPath = join(tempDir, "checksums.sha256");
+
+ writeFileSync(packagePath, "package-content");
+ writeFileSync(installerPath, "#!/bin/sh\n");
+ writeFileSync(notesPath, "Release notes");
+
+ execFileSync("node", [
+ join(rootDir, "scripts/generate-release-manifest.mjs"),
+ "--env",
+ "prod",
+ "--version",
+ "2026.5.8",
+ "--tag",
+ "v2026.5.8",
+ "--git-hash",
+ "0123456789abcdef0123456789abcdef01234567",
+ "--artifact",
+ packagePath,
+ "--artifact",
+ installerPath,
+ "--notes",
+ notesPath,
+ "--out",
+ manifestPath,
+ "--checksums-out",
+ checksumsPath,
+ ]);
+
+ const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+ const checksums = readFileSync(checksumsPath, "utf8");
+
+ expect(manifest.schemaVersion).toBe("1.0");
+ expect(manifest.environment).toBe("prod");
+ expect(manifest.plugin.id).toBe("openviking");
+ expect(manifest.release.version).toBe("2026.5.8");
+ expect(manifest.release.tag).toBe("v2026.5.8");
+ expect(manifest.release.gitShortHash).toBe("0123456");
+ expect(manifest.tos.bucket).toBe("arkclaw-openviking");
+ expect(manifest.artifacts.map((artifact: { name: string }) => artifact.name)).toEqual([
+ "openviking.tgz",
+ "install.sh",
+ ]);
+ expect(manifest.artifacts.every((artifact: { sha256: string; size: number }) => artifact.sha256.length === 64 && artifact.size > 0)).toBe(true);
+ expect(checksums).toContain("openviking.tgz");
+ expect(checksums).toContain("install.sh");
+ });
+
+ it("generates environment-specific manifest metadata for non-prod releases", () => {
+ const tempDir = mkdtempSync(join(tmpdir(), "openviking-manifest-stg-"));
+ const packagePath = join(tempDir, "openviking.tgz");
+ const installerPath = join(tempDir, "install.sh");
+ const manifestPath = join(tempDir, "manifest.json");
+ const checksumsPath = join(tempDir, "checksums.sha256");
+
+ writeFileSync(packagePath, "package-content");
+ writeFileSync(installerPath, "#!/bin/sh\n");
+
+ execFileSync("node", [
+ join(rootDir, "scripts/generate-release-manifest.mjs"),
+ "--env",
+ "stg",
+ "--version",
+ "2026.5.8",
+ "--tag",
+ "v2026.5.8-stg",
+ "--git-hash",
+ "0123456789abcdef0123456789abcdef01234567",
+ "--artifact",
+ packagePath,
+ "--artifact",
+ installerPath,
+ "--bucket",
+ "arkclaw-openviking-stg",
+ "--region",
+ "cn-shanghai",
+ "--endpoint",
+ "tos-cn-shanghai.volces.com",
+ "--out",
+ manifestPath,
+ "--checksums-out",
+ checksumsPath,
+ ]);
+
+ const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+ const installer = manifest.artifacts.find((artifact: { name: string }) => artifact.name === "install.sh");
+
+ expect(manifest.environment).toBe("stg");
+ expect(manifest.tos).toMatchObject({
+ bucket: "arkclaw-openviking-stg",
+ region: "cn-shanghai",
+ endpoint: "tos-cn-shanghai.volces.com",
+ });
+ expect(installer.defaultArgs.channel).toBe("stg");
+ });
+
+ it("defines release-to-tos dry-run and credential rules", () => {
+ const releaseScript = readText("scripts/release-to-tos.sh");
+
+ expect(releaseScript).toContain("set -euo pipefail");
+ expect(releaseScript).toContain("--release-dir <date>");
+ expect(releaseScript).toContain("Defaults to today's yyyy.m.d");
+ expect(releaseScript).toContain("today_release_dir");
+ expect(releaseScript).toContain("--publish-latest");
+ expect(releaseScript).toContain("BUILD_RELEASE_PATH=\"$RELEASE_DIR\" BUILD_VERSION=\"$VERSION\" bash \"$ROOT_DIR/build.sh\"");
+ expect(releaseScript).toContain("TEAM_TEST_AK");
+ expect(releaseScript).toContain("TEAM_TEST_SK");
+ expect(releaseScript).toContain("--dry-run");
+ expect(releaseScript).toContain("scripts/generate-release-manifest.mjs");
+ expect(releaseScript).toContain("bash \"$ROOT_DIR/build.sh\"");
+ expect(releaseScript).toContain("scripts/upload_tos.py");
+ expect(releaseScript).toContain("output/manifest.json");
+ expect(releaseScript).not.toContain("latest.json");
+ });
+
+ it("defaults release version to the next beta for the package base version", () => {
+ const tempDir = mkdtempSync(join(tmpdir(), "openviking-version-beta-"));
+ const packagePath = join(tempDir, "package.json");
+ writeFileSync(packagePath, JSON.stringify({ version: "2026.6.1" }));
+
+ const resolved = resolveReleaseVersion([
+ "--package",
+ packagePath,
+ "--existing-versions",
+ "2026.6.1-beta.1,2026.6.1-beta.2,2026.6.1",
+ ]);
+
+ expect(resolved).toMatchObject({
+ version: "2026.6.1-beta.3",
+ tag: "v2026.6.1-beta.3",
+ channel: "beta",
+ });
+ });
+
+ it("resolves explicit stable releases to date-style versions without beta suffix", () => {
+ const tempDir = mkdtempSync(join(tmpdir(), "openviking-version-stable-"));
+ const packagePath = join(tempDir, "package.json");
+ writeFileSync(packagePath, JSON.stringify({ version: "2026.6.1-beta.7" }));
+
+ const resolved = resolveReleaseVersion(["--package", packagePath, "--stable"]);
+
+ expect(resolved).toMatchObject({
+ version: "2026.6.1",
+ tag: "v2026.6.1",
+ channel: "stable",
+ });
+ });
+
+ it("keeps explicitly requested release versions and derives their tag", () => {
+ const resolved = resolveReleaseVersion(["--version", "2026.6.1-beta.9"]);
+
+ expect(resolved).toMatchObject({
+ version: "2026.6.1-beta.9",
+ tag: "v2026.6.1-beta.9",
+ channel: "beta",
+ });
+ });
+
+ it("defines a TOS SDK release client for upload, verify, and latest update", () => {
+ const packageJson = JSON.parse(readText("package.json"));
+ const clientScript = readText("scripts/tos-release-client.mjs");
+ const uploader = readText("scripts/upload_tos.py");
+
+ expect(packageJson.dependencies["@volcengine/tos-sdk"]).toBeUndefined();
+ expect(packageJson.devDependencies["@volcengine/tos-sdk"]).toBeDefined();
+ expect(packageJson.overrides?.axios).toMatch(/^\^1\./);
+ expect(uploader).toContain("TosClientV2");
+ expect(uploader).toContain("put_object_from_file");
+ expect(uploader).toContain("put_object_acl");
+ expect(uploader).toContain("ensure_bucket");
+ expect(uploader).toContain("create_bucket");
+ expect(uploader).toContain("stamp_bucket_installer");
+ expect(uploader).toContain("stamp_bucket_manifest");
+ expect(uploader).toContain("hashlib.sha256");
+ expect(uploader).toContain("DEFAULT_TOS_BASE_URL=");
+ expect(uploader).toContain("upload_bucket_installer");
+ expect(uploader).toContain("default_release_dir");
+ expect(uploader).not.toContain('DEFAULT_RELEASE_DIR = "2026.6.3"');
+ expect(uploader).toContain("forbid_overwrite=False");
+ expect(uploader).toContain("--publish-latest");
+ expect(uploader).toContain("manifest.json");
+ expect(uploader).toContain("TEAM_TEST_AK");
+ expect(uploader).toContain("TEAM_TEST_SK");
+ expect(clientScript).toContain("Simplified TOS protocol");
+ expect(clientScript).toContain("scripts/release-to-tos.sh");
+ expect(clientScript).not.toContain("TOS_ACCESS_KEY");
+ expect(clientScript).not.toContain("TOS_SECRET_KEY");
+ });
+
+ it("keeps install.sh as the single global installer with default TOS latest", () => {
+ const installScript = readText("scripts/install.sh");
+
+ expect(installScript).toContain("requires bash");
+ expect(installScript).toContain("Usage: bash install.sh [options]");
+ expect(installScript).toContain("<tos-base-url>/latest/openviking.tgz");
+ expect(installScript).toContain("DEFAULT_TOS_BASE_URL=\"\"");
+ expect(installScript).toContain("INSTALL_TOS_BASE_URL=\"${INSTALL_TOS_BASE_URL:-$DEFAULT_TOS_BASE_URL}\"");
+ expect(installScript).toContain("RELEASE_PATH=\"${INSTALL_RELEASE_PATH:-latest}\"");
+ expect(installScript).toContain("--source tos|tarball|local|existing");
+ expect(installScript).toContain("--date <date>");
+ expect(installScript).toContain("--manifest-url <url>");
+ expect(installScript).toContain("--verify-only");
+ expect(installScript).toContain("openviking.env");
+ expect(installScript).toContain("openclaw openviking setup");
+ });
+
+ it("does not run OpenViking setup during verify-only mode", () => {
+ execFileSync("bash", [join(rootDir, "scripts/install.sh"), "--source", "existing", "--verify-only"], {
+ env: {
+ ...process.env,
+ OPENVIKING_API_KEY: "test-secret-key",
+ OPENVIKING_BASE_URL: "",
+ },
+ });
+ });
+
+ it("keeps the Volcengine installer as a thin compatibility wrapper", () => {
+ const wrapper = readText("scripts/volcengine-openviking-install.sh");
+
+ expect(wrapper).toContain("Compatibility wrapper");
+ expect(wrapper).toContain("exec \"$SCRIPT_DIR/install.sh\"");
+ expect(wrapper).not.toContain("openclaw openviking setup");
+ expect(wrapper).not.toContain("openclaw plugins install clawhub:@openviking/openclaw-plugin");
+ });
+});
diff --git a/examples/openclaw-plugin/tests/ut/volcengine-install-contract.test.ts b/examples/openclaw-plugin/tests/ut/volcengine-install-contract.test.ts
new file mode 100644
index 000000000..1ff863623
--- /dev/null
+++ b/examples/openclaw-plugin/tests/ut/volcengine-install-contract.test.ts
@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const rootDir = join(__dirname, "../..");
+
+function readText(path: string): string {
+ return readFileSync(join(rootDir, path), "utf8");
+}
+
+describe("Volcengine OpenViking one-click install contract", () => {
+ it("keeps the Volcengine install script as a compatibility wrapper", () => {
+ const script = readText("scripts/volcengine-openviking-install.sh");
+
+ expect(script).toContain("set -euo pipefail");
+ expect(script).toContain("Compatibility wrapper");
+ expect(script).toContain("exec \"$SCRIPT_DIR/install.sh\"");
+ });
+
+ it("moves Volcengine configuration flags to the global install script", () => {
+ const script = readText("scripts/install.sh");
+
+ expect(script).toContain("OPENVIKING_BASE_URL");
+ expect(script).toContain("OPENVIKING_API_KEY");
+ expect(script).toContain("OPENVIKING_PEER_ROLE");
+ expect(script).toContain("OPENVIKING_PEER_PREFIX");
+ expect(script).toContain("OPENVIKING_ACCOUNT_ID");
+ expect(script).toContain("OPENVIKING_USER_ID");
+ expect(script).toContain("OPENCLAW_STATE_DIR");
+ });
+
+ it("supports tos, tarball, local, and existing plugin install sources", () => {
+ const script = readText("scripts/install.sh");
+
+ expect(script).toContain("--source tos|tarball|local|existing");
+ expect(script).toContain("INSTALL_SOURCE=\"${INSTALL_SOURCE:-tos}\"");
+ expect(script).toContain("--source existing");
+ expect(script).toContain("--tarball");
+ });
+
+ it("writes a protected env file and never prints the raw api key", () => {
+ const script = readText("scripts/install.sh");
+
+ expect(script).toContain("openviking.env");
+ expect(script).toContain("chmod 600 \"$ENV_FILE\"");
+ expect(script).toContain("mask_secret");
+ expect(script).toContain("redact_arg");
+ expect(script).toContain("OPENVIKING_RECALL_RESOURCES");
+ expect(script).not.toContain("echo \"$OPENVIKING_API_KEY\"");
+ });
+
+ it("delegates configuration to openclaw setup and verifies status", () => {
+ const script = readText("scripts/install.sh");
+
+ expect(script).toContain("openclaw openviking setup");
+ expect(script).toContain("--base-url \"$OPENVIKING_BASE_URL\"");
+ expect(script).toContain("--api-key \"$OPENVIKING_API_KEY\"");
+ expect(script).toContain("--peer-role \"$OPENVIKING_PEER_ROLE\"");
+ expect(script).toContain("--peer-prefix \"$OPENVIKING_PEER_PREFIX\"");
+ expect(script).toContain("--force-slot");
+ expect(script).toContain("openclaw gateway restart");
+ expect(script).toContain("openclaw openviking status --json");
+ expect(script).toContain("openclaw config get plugins.slots.contextEngine");
+ });
+
+ it("keeps the Volcengine wrapper in package build outputs for compatibility", () => {
+ const buildScript = readText("build.sh");
+
+ expect(buildScript).toContain("scripts/volcengine-openviking-install.sh");
+ expect(buildScript).toContain("output/volcengine-install.sh");
+ });
+});