Skip to content

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

docs(build): repair contributor guidance and maintenance tooling (#3551)

Hao Zhef0445e0cce5b
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ead0761e6..b08c71ada 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ Thank you for your interest in OpenViking! We welcome contributions of all kinds
- **Go**: 1.22+ (Required only for Go SDK development under `sdk/go`)
- **Rust**: 1.91.1+ (Required for source builds because the bundled `ov` CLI is built during packaging)
- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions, must support C++17)
-- **CMake**: 3.12+
+- **CMake**: 3.15+
#### Platform-Specific Native Build Tools
@@ -68,34 +68,19 @@ This command ensures that `setup.py` is re-executed, triggering rebuilds for AGF
### 3. Configure Environment
-Create a configuration file `~/.openviking/ov.conf`:
-
-```json
-{
- "embedding": {
- "dense": {
- "provider": "volcengine",
- "api_key": "your-api-key",
- "model": "doubao-embedding-vision-251215",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3",
- "dimension": 1024,
- "input": "multimodal"
- }
- },
- "vlm": {
- "api_key": "your-api-key",
- "model": "doubao-seed-2-0-lite-260428",
- "api_base": "https://ark.cn-beijing.volces.com/api/v3"
- }
-}
-```
-
-Set the environment variable:
+Run the interactive wizard to pick providers and write `~/.openviking/ov.conf`, then
+validate the result:
-```bash
-export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
+```console
+openviking-server init
+openviking-server doctor
```
+Manual `ov.conf` templates, per-provider examples, and environment variables are in the
+[Configuration guide](https://docs.openviking.ai/en/guides/01-configuration). The default
+config file is loaded automatically; set `OPENVIKING_CONFIG_FILE` only when using a
+non-default path.
+
### 4. Verify Installation
```python
@@ -133,60 +118,44 @@ After installation, run `ov --help` to see all available commands. CLI connectio
```
openviking/
-├── pyproject.toml # Project configuration
+├── pyproject.toml # Python project and tooling configuration
├── Cargo.toml # Rust workspace configuration
-├── third_party/ # Third-party dependencies
-│ ├── krl/ # Native retrieval dependency
-│ ├── leveldb-1.23/ # Embedded key-value storage dependency
-│ └── spdlog-1.14.1/ # Native logging dependency
-│
-├── openviking/ # Python SDK
-│ ├── async_client.py # AsyncOpenViking client
-│ ├── sync_client.py # SyncOpenViking client
+├── openviking/ # Python SDK and server implementation
│ ├── client/ # Local and HTTP client implementations
-│ ├── console/ # Standalone console UI and proxy service
+│ ├── connector/ # Data connectors
│ ├── core/ # Core data models and directory abstractions
-│ ├── message/ # Session message and part models
+│ ├── ingest/ # Ingestion pipeline
+│ ├── integrations/ # Agent integrations
│ ├── models/ # Embedding and VLM backends
│ ├── parse/ # Resource parsers and detectors
│ ├── resource/ # Resource processing and watch management
│ ├── retrieve/ # Retrieval system
│ ├── server/ # HTTP server
-│ ├── service/ # Shared service layer
│ ├── session/ # Session management and compression
-│ ├── storage/ # Storage layer
-│ ├── telemetry/ # Operation telemetry
-│ ├── trace/ # Trace and runtime tracing helpers
-│ ├── utils/ # Utilities and configuration helpers
-│ └── prompts/ # Prompt templates
-│
+│ └── storage/ # Storage layer
+├── openviking_cli/ # Server bootstrap and Python CLI support
+├── bot/ # VikingBot agent framework
+├── sdk/ # Go, Python, and TypeScript client SDKs
+├── web-studio/ # Studio web frontend
├── crates/ # Rust components
+│ ├── ov_cli/ # Rust CLI client
│ ├── ragfs/ # Rust implementation of AGFS
│ ├── ragfs-python/ # Python binding for RAGFS
-│ └── ov_cli/ # Rust CLI client
-│ ├── src/ # CLI source code
-│ └── install.sh # Deprecated stub (use npm package; see Install)
-│
+│ ├── ragfs-python-native/ # Native Python binding package
+│ ├── ragfs-cache-redis/ # Redis cache backend
+│ ├── ragfs-cache-mooncake/ # Mooncake cache backend
+│ ├── ragfs-cache-yuanrong/ # YuanRong cache backend
+│ └── ragfs-cache-yuanrong-sys/ # YuanRong FFI bindings
├── src/ # C++ extension sources (Python abi3)
-│
-├── tests/ # Test suite
-│ ├── client/ # Client tests
-│ ├── console/ # Console tests
-│ ├── core/ # Core logic tests
-│ ├── parse/ # Parser tests
-│ ├── resource/ # Resource processing tests
-│ ├── retrieve/ # Retrieval tests
-│ ├── server/ # Server tests
-│ ├── service/ # Service layer tests
-│ ├── session/ # Session tests
-│ ├── storage/ # Storage tests
-│ ├── telemetry/ # Telemetry tests
-│ ├── vectordb/ # Vector database tests
-│ └── integration/ # End-to-end tests
-│
-└── docs/ # Documentation
- ├── en/ # English docs
- └── zh/ # Chinese docs
+├── third_party/ # Native third-party dependencies
+├── examples/ # Usage and integration examples
+├── benchmark/ # Benchmark suites
+├── tests/ # Python and integration test suites
+├── deploy/ # Deployment assets
+├── docker/ # Docker build files
+├── npm/ # npm CLI package
+├── scripts/ # Development and maintenance scripts
+└── docs/ # English, Chinese, and Japanese documentation
```
---
@@ -493,27 +462,24 @@ Other repository workflows also exist for PR review automation, Docker image bui
Maintainers can manually trigger the following workflows from the "Actions" tab to perform specific tasks or debug issues.
-#### A. Lint Checks (`11. _Lint Checks`)
-Runs code style checks (Ruff) and type checks (Mypy). No arguments required.
-
-#### B. Test Suite (Lite) (`12. _Test Suite (Lite)`)
+#### A. Test Suite (Lite) (`12. _Test Suite (Lite)`)
Runs fast integration tests, supports custom matrix configuration.
* **Inputs**:
* `os_json`: JSON string array of OS to run on (e.g., `["ubuntu-24.04"]`).
* `python_json`: JSON string array of Python versions (e.g., `["3.10"]`).
-#### C. Test Suite (Full) (`13. _Test Suite (Full)`)
+#### B. Test Suite (Full) (`13. _Test Suite (Full)`)
Runs the full test suite on all supported platforms (Linux/Mac/Win) and Python versions (3.10-3.14). Supports custom matrix configuration when triggered manually.
* **Inputs**:
* `os_json`: List of OS to run on (Default: `["ubuntu-24.04", "macos-14", "windows-latest"]`).
* `python_json`: List of Python versions (Default: `["3.10", "3.11", "3.12", "3.13", "3.14"]`).
-#### D. Security Scan (`14. _CodeQL Scan`)
+#### C. Security Scan (`14. _CodeQL Scan`)
Runs CodeQL security analysis. No arguments required.
-#### E. Build Distribution (`15. _Build Distribution`)
+#### D. Build Distribution (`15. _Build Distribution`)
Builds Python wheel packages only, does not publish.
* **Inputs**:
@@ -522,14 +488,14 @@ Builds Python wheel packages only, does not publish.
* `build_sdist`: Whether to build source distribution (Default: `true`).
* `build_wheels`: Whether to build wheel distribution (Default: `true`).
-#### F. Publish Distribution (`16. _Publish Distribution`)
+#### E. Publish Distribution (`16. _Publish Distribution`)
Publishes built packages (requires build Run ID) to PyPI.
* **Inputs**:
* `target`: Select publish target (`testpypi`, `pypi`, `both`).
* `build_run_id`: Build Workflow Run ID (Required, get it from the Build run URL).
-#### G. Manual Release (`03. Release`)
+#### F. Manual Release (`03. Release`)
One-stop build and publish (includes build and publish steps).
> **Version Numbering & Tag Convention**:
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index 2245aeb50..35251fbda 100644
--- a/CONTRIBUTING_CN.md
+++ b/CONTRIBUTING_CN.md
@@ -17,7 +17,7 @@
- **Go**: 1.22+ (从源码构建 AGFS 组件需要)
- **Rust**: 1.91.1+(从源码构建需要;打包流程会同时构建内置 `ov` CLI)
- **C++ 编译器**: GCC 9+ 或 Clang 11+ (构建核心扩展需要,必须支持 C++17)
-- **CMake**: 3.12+
+- **CMake**: 3.15+
#### 平台相关的本地构建工具
diff --git a/CONTRIBUTING_JA.md b/CONTRIBUTING_JA.md
index d059655ed..dcd526074 100644
--- a/CONTRIBUTING_JA.md
+++ b/CONTRIBUTING_JA.md
@@ -17,7 +17,7 @@ OpenVikingに興味をお持ちいただきありがとうございます!あ
- **Go**: 1.22以上(AGFSコンポーネントのソースビルドに必要)
- **Rust**: 1.91.1以上(ソースビルド時に同梱の `ov` CLI もビルドされるため必須)
- **C++コンパイラ**: GCC 9以上 または Clang 11以上(コア拡張のビルドに必要、C++17サポートが必須)
-- **CMake**: 3.12以上
+- **CMake**: 3.15以上
#### プラットフォーム別のネイティブビルドツール
diff --git a/Makefile b/Makefile
index 02c50a988..81f71ad84 100644
--- a/Makefile
+++ b/Makefile
@@ -7,7 +7,7 @@ OV_CLI_DIR := crates/ov_cli
# Dependency Versions
MIN_PYTHON_VERSION := 3.10
-MIN_CMAKE_VERSION := 3.12
+MIN_CMAKE_VERSION := 3.15
MIN_RUST_VERSION := 1.91.1
MIN_GCC_VERSION := 9
MIN_CLANG_VERSION := 11
@@ -63,7 +63,9 @@ check-deps:
@# CMake check
@command -v cmake > /dev/null 2>&1 || (echo "Error: CMake is not installed."; exit 1)
@CMAKE_VER=$$(cmake --version | head -n1 | awk '{print $$3}'); \
- $(PYTHON) -c "v='$$CMAKE_VER'.split('.'); exit(0 if int(v[0]) > 3 or (int(v[0]) == 3 and int(v[1]) >= 12) else 1)" || (echo "Error: CMake >= $(MIN_CMAKE_VERSION) is required. Found $$CMAKE_VER"; exit 1); \
+ if ! $(PYTHON) -c "import re, sys; parse=lambda v: tuple(int(x) for x in re.match(r'^[0-9]+(?:\.[0-9]+)*', v).group().split('.')); raise SystemExit(0 if parse(sys.argv[1]) >= parse(sys.argv[2]) else 1)" "$$CMAKE_VER" "$(MIN_CMAKE_VERSION)"; then \
+ echo "Error: CMake >= $(MIN_CMAKE_VERSION) is required. Found $$CMAKE_VER"; exit 1; \
+ fi; \
echo " [OK] CMake $$CMAKE_VER"
@# Rust check
@command -v rustc > /dev/null 2>&1 || (echo "Error: Rust is not installed."; exit 1)
@@ -102,35 +104,39 @@ build: check-deps check-pip build-studio
$(PYTHON) -m pip install -e .; \
fi
@echo "Building ragfs-python (Rust RAGFS binding) into openviking/lib/..."
- @MATURIN_CMD=""; \
+ @set -e; \
+ MATURIN_CMD=""; \
if command -v maturin > /dev/null 2>&1; then \
MATURIN_CMD=maturin; \
elif command -v uv > /dev/null 2>&1 && uv pip --help > /dev/null 2>&1; then \
- uv pip install maturin && MATURIN_CMD=maturin; \
+ uv pip install maturin; \
+ MATURIN_CMD=maturin; \
fi; \
if [ -n "$$MATURIN_CMD" ]; then \
- TMPDIR=$$(mktemp -d); \
- cd crates/ragfs-python && $$MATURIN_CMD build --release --out "$$TMPDIR" 2>&1; \
- cd ../..; \
+ RAGFS_TMPDIR=$$(mktemp -d); \
+ EXTRACT_SCRIPT=$$(mktemp); \
+ trap 'rm -f "$$EXTRACT_SCRIPT"; rm -rf "$$RAGFS_TMPDIR"' 0; \
+ (cd crates/ragfs-python && $$MATURIN_CMD build --release --out "$$RAGFS_TMPDIR" 2>&1); \
mkdir -p openviking/lib; \
rm -f openviking/lib/ragfs_python*.so openviking/lib/ragfs_python*.pyd openviking/lib/ragfs_python*.dylib; \
- echo "import zipfile, glob, shutil, os, sys" > /tmp/extract_ragfs.py; \
- echo "whls = glob.glob(os.path.join('$$TMPDIR', 'ragfs_python-*.whl'))" >> /tmp/extract_ragfs.py; \
- echo "assert whls, 'maturin produced no wheel'" >> /tmp/extract_ragfs.py; \
- echo "with zipfile.ZipFile(whls[0]) as zf:" >> /tmp/extract_ragfs.py; \
- echo " for name in zf.namelist():" >> /tmp/extract_ragfs.py; \
- echo " bn = os.path.basename(name)" >> /tmp/extract_ragfs.py; \
- echo " if bn.startswith('ragfs_python.abi3.') and (bn.endswith('.so') or bn.endswith('.pyd')):" >> /tmp/extract_ragfs.py; \
- echo " dst = os.path.join('openviking', 'lib', bn)" >> /tmp/extract_ragfs.py; \
- echo " with zf.open(name) as src, open(dst, 'wb') as f: f.write(src.read())" >> /tmp/extract_ragfs.py; \
- echo " os.chmod(dst, 0o755)" >> /tmp/extract_ragfs.py; \
- echo " print(f' [OK] ragfs-python: extracted {bn} -> {dst}')" >> /tmp/extract_ragfs.py; \
- echo " sys.exit(0)" >> /tmp/extract_ragfs.py; \
- echo "print('[Warning] No ragfs_python abi3 .so/.pyd found in wheel')" >> /tmp/extract_ragfs.py; \
- echo "sys.exit(1)" >> /tmp/extract_ragfs.py; \
- $(PYTHON) /tmp/extract_ragfs.py; \
- rm -f /tmp/extract_ragfs.py; \
- rm -rf "$$TMPDIR"; \
+ echo "import zipfile, glob, shutil, os, sys" > "$$EXTRACT_SCRIPT"; \
+ echo "whls = glob.glob(os.path.join('$$RAGFS_TMPDIR', 'ragfs_python-*.whl'))" >> "$$EXTRACT_SCRIPT"; \
+ echo "assert whls, 'maturin produced no wheel'" >> "$$EXTRACT_SCRIPT"; \
+ echo "with zipfile.ZipFile(whls[0]) as zf:" >> "$$EXTRACT_SCRIPT"; \
+ echo " for name in zf.namelist():" >> "$$EXTRACT_SCRIPT"; \
+ echo " bn = os.path.basename(name)" >> "$$EXTRACT_SCRIPT"; \
+ echo " if bn.startswith('ragfs_python.abi3.') and (bn.endswith('.so') or bn.endswith('.pyd')):" >> "$$EXTRACT_SCRIPT"; \
+ echo " dst = os.path.join('openviking', 'lib', bn)" >> "$$EXTRACT_SCRIPT"; \
+ echo " with zf.open(name) as src, open(dst, 'wb') as f: f.write(src.read())" >> "$$EXTRACT_SCRIPT"; \
+ echo " os.chmod(dst, 0o755)" >> "$$EXTRACT_SCRIPT"; \
+ echo " print(f' [OK] ragfs-python: extracted {bn} -> {dst}')" >> "$$EXTRACT_SCRIPT"; \
+ echo " sys.exit(0)" >> "$$EXTRACT_SCRIPT"; \
+ echo "print('[Warning] No ragfs_python abi3 .so/.pyd found in wheel')" >> "$$EXTRACT_SCRIPT"; \
+ echo "sys.exit(1)" >> "$$EXTRACT_SCRIPT"; \
+ $(PYTHON) "$$EXTRACT_SCRIPT"; \
+ rm -f "$$EXTRACT_SCRIPT"; \
+ rm -rf "$$RAGFS_TMPDIR"; \
+ trap - 0; \
else \
echo " [SKIP] maturin not found, ragfs-python (Rust binding) will not be built."; \
echo " Install maturin to enable: uv pip install maturin"; \
@@ -151,7 +157,8 @@ clean:
# Web Studio target
build-studio:
- @if [ "$$OV_SKIP_STUDIO_BUILD" = "1" ]; then \
+ @set -e; \
+ if [ "$$OV_SKIP_STUDIO_BUILD" = "1" ]; then \
echo " [SKIP] web-studio build disabled by OV_SKIP_STUDIO_BUILD=1"; \
elif [ -f openviking/web_studio/dist/index.html ]; then \
echo " [OK] web-studio bundle already present"; \
@@ -161,7 +168,7 @@ build-studio:
echo " [SKIP] web-studio source not found"; \
else \
echo "Building web-studio (Vite SPA)..."; \
- cd web-studio && npm ci && npm run build -- --base="/studio/" && cd ..; \
+ (cd web-studio && npm ci && npm run build -- --base="/studio/"); \
mkdir -p openviking/web_studio; \
rm -rf openviking/web_studio/dist; \
cp -r web-studio/dist openviking/web_studio/dist; \
diff --git a/RELEASE.md b/RELEASE.md
index 677b7846f..2e10630c3 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -12,6 +12,9 @@ OpenViking does not release a single artifact. A release publishes a set of rela
- TOS release assets: for source archives, installation scripts, and stable download paths.
- Rust CLI / npm packages: for users who install the `ov` CLI through npm.
- OpenClaw / ClawHub plugin: for OpenClaw plugin distribution.
+- TypeScript SDK `@openviking/sdk`: for TypeScript and JavaScript HTTP clients.
+- OpenCode plugin `@openviking/opencode-plugin`: for OpenCode integration distribution.
+- Controlplane MCP `mcp-server-openviking-controlplane`: MCP server and `ov-cp` CLI for the control plane.
- VikingBot: currently distributed through `openviking[bot]` and the official Docker image; historical standalone release entries are documented separately to avoid misuse.
A formal main-package release should keep the Python package, Docker images, and TOS assets on the same main release tag. SDK, CLI, and ClawHub plugin releases use their own tag or version namespaces.
@@ -24,6 +27,7 @@ Use the following tag conventions:
| --- | --- | --- |
| `openviking` main package | `vX.Y.Z` | Main release tag, for example `v0.3.26`. |
| `openviking-sdk` | `[email protected]` | SDK-only tag, for example `[email protected]`. |
+| `@openviking/sdk` (TypeScript) | `[email protected]` | TypeScript SDK tag. |
| Rust CLI / npm CLI | `[email protected]` | CLI-only tag, for example `[email protected]`. |
| ClawHub plugin latest | `YYYY.M.D` or `YYYY.M.D-N` | Generated by the workflow or specified manually. |
| ClawHub plugin dev | `YYYY.M.D-dev.N` | Used for the dev channel. |
@@ -41,7 +45,7 @@ Formal main package releases go through GitHub Releases in the root repository:
5. The workflow reuses `_Build Distribution` to build the sdist and multi-platform wheels.
6. The workflow publishes the distributions to PyPI.
7. The workflow builds and pushes multi-architecture Docker images.
-8. The `Release TOS Upload` workflow uploads the source archive and installation scripts to TOS.
+8. The `20. Release TOS Upload` workflow uploads the source archive and installation scripts to TOS.
A formal main release publishes to:
@@ -124,7 +128,7 @@ The workflow injects the version from the tag into the platform packages and wra
## OpenClaw / ClawHub Plugin Release
-The OpenClaw plugin is published manually through the `ClawHub release (OpenViking plugin)` workflow. Inputs include:
+The OpenClaw plugin is published manually through the `OpenViking OpenClaw plugin release` workflow. Inputs include:
- `version`: optional; when empty, the workflow generates a date-based version.
- `channel`: `auto`, `dev`, or `latest`.
@@ -138,6 +142,16 @@ Recommended usage:
- Use `dev` for development validation.
- When specifying `version` manually, ensure it matches the required format for the selected channel.
+## Other Release Flows
+
+- **TypeScript SDK Release** (`typescript-sdk-release.yml`): triggered by pushing a
+ `[email protected]` tag, or manually. Publishes `@openviking/sdk` to npm.
+- **OpenCode Plugin Release** (`opencode-plugin-release.yml`): runs automatically on
+ pushes to `main` that touch `examples/opencode-plugin/**`, or manually. Publishes
+ `@openviking/opencode-plugin` to npm and skips versions that already exist.
+- **Controlplane MCP Release** (`controlplane-mcp-release.yml`): manual only. Publishes
+ `mcp-server-openviking-controlplane`, including the `ov-cp` CLI.
+
## VikingBot Release Notes
VikingBot is no longer maintained as a recommended standalone PyPI release path. The current distribution model is through the main package:
diff --git a/SECURITY.md b/SECURITY.md
index d2124614e..75301e769 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -8,4 +8,4 @@ To protect the security of our customers, ByteDance requests that you do not pub
Individuals, companies, and security teams may wish to publish security advisories on their own websites or other forums. Please contact us via the email or website mentioned above prior to publication to discuss the information that can be disclosed and to coordinate the disclosure timeline.
## Bug Bounty Reward
-[For the policy of bug bounty reward](🚀ByteDance Security Response Center Security Report Handling Rules V6.0), if you have any questions about the rules, please contact https://src.bytedance.com/home for consultation.
+The bug bounty reward policy ("ByteDance Security Response Center Security Report Handling Rules") is published on the [security center](https://security.bytedance.com/src). If you have any questions about the rules, please contact us there or via [[email protected]](mailto:[email protected]).
diff --git a/docs/en/concepts/11-multi-tenant.md b/docs/en/concepts/11-multi-tenant.md
index 3082d6247..cc9f598f5 100644
--- a/docs/en/concepts/11-multi-tenant.md
+++ b/docs/en/concepts/11-multi-tenant.md
@@ -115,6 +115,8 @@ Filesystem operations and semantic retrieval are tenant-aware:
This keeps "what you can search" aligned with "what you can read."
+<a id="peer-restricted-view"></a>
+
### Peer Collection Filter
`peer_id` is a content scope inside the current user boundary. It never changes the
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index e338108a6..5b2154c68 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1584,6 +1584,8 @@ Task record files are stored under the owning account's system directory:
/local/{account_id}/_system/tasks/{user_id}/{task_id}.json
```
+<a id="encryption"></a>
+
## encryption Section
Enable at-rest data encryption to ensure data security and isolation in multi-tenant environments. Encryption is completely transparent to users with no API changes.
diff --git a/docs/en/guides/12-public-access.md b/docs/en/guides/12-public-access.md
index 21ee2953e..1bdd98289 100644
--- a/docs/en/guides/12-public-access.md
+++ b/docs/en/guides/12-public-access.md
@@ -14,6 +14,8 @@ public HTTPS domain.
Prerequisites: a public domain, ports 80 + 443 reachable, DNS pointing at
your host.
+<a id="adding-https-for-public-access"></a>
+
## Option A: bundled Caddy with auto Let's Encrypt (recommended)
`docker compose up` already brings up a Caddy reverse-proxy container. Add a
diff --git a/docs/zh/agent-integrations/06-mcp-clients.md b/docs/zh/agent-integrations/06-mcp-clients.md
index c5a41b528..f7a700f57 100644
--- a/docs/zh/agent-integrations/06-mcp-clients.md
+++ b/docs/zh/agent-integrations/06-mcp-clients.md
@@ -75,7 +75,7 @@ HTTPS 配置、部署模板和完整授权流程详见 [OAuth 2.1 指南](../gui
## 可用工具
-连接后,OpenViking 会提供检索、记忆、资源、watch、文件系统和代码导航工具。完整工具清单、参数、渐进式文件上传和高级配置见 [MCP 集成指南](../guides/06-mcp-integration.md#可用-mcp-工具)。
+连接后,OpenViking 会提供检索、记忆、资源、watch、文件系统和代码导航工具。完整工具清单、参数、渐进式文件上传和高级配置见 [MCP 集成指南](../guides/06-mcp-integration.md#可用的-mcp-工具)。
## 故障排查
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 1f8303de3..e99e19bae 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1516,6 +1516,8 @@ HTTP Sink 使用本地持久化队列重试,同一事件可能被重复发送
启动方式和部署详情见 [服务部署](./03-deployment.md),认证详情见 [认证](./04-authentication.md)。
+<a id="encryption"></a>
+
## encryption 段
启用静态数据加密,确保多租户环境下的数据安全与隔离。加密功能对用户完全透明,API 无变化。
diff --git a/docs/zh/guides/12-public-access.md b/docs/zh/guides/12-public-access.md
index e43712efb..d5e86a60b 100644
--- a/docs/zh/guides/12-public-access.md
+++ b/docs/zh/guides/12-public-access.md
@@ -11,6 +11,8 @@ OpenViking 默认在 1933 端口对外提供 REST API、MCP、OAuth、`.well-kno
前提:有公网域名、80 + 443 端口可达、DNS 已指向。
+<a id="添加-https公网访问"></a>
+
## 方式 A:用自带 Caddy 自动签发 Let's Encrypt 证书(推荐)
`docker compose up` 默认带一个 Caddy 反代容器。给它追加一个域名块即可让
diff --git a/scripts/maintenance/vikingdb_content_backfill/README.md b/scripts/maintenance/vikingdb_content_backfill/README.md
index 43344e039..6150122a4 100644
--- a/scripts/maintenance/vikingdb_content_backfill/README.md
+++ b/scripts/maintenance/vikingdb_content_backfill/README.md
@@ -96,14 +96,16 @@ Then execute the update:
--execute
```
-Optional throttling:
+The following legacy options were accepted by earlier versions but never affected
+execution:
-```bash
-./venv/bin/python scripts/maintenance/vikingdb_content_backfill/backfill_vikingdb_content.py \
- --execute \
- --batch-size 100 \
- --limit 10000
-```
+- `--batch-size`
+- `--page-size`
+- `--read-concurrency`
+- `--update-sleep-ms`
+
+They remain accepted for compatibility with existing operational scripts, but
+print a deprecation warning and should be removed.
## Output Files
diff --git a/scripts/maintenance/vikingdb_content_backfill/backfill_vikingdb_content.py b/scripts/maintenance/vikingdb_content_backfill/backfill_vikingdb_content.py
index 12ed76e8f..a561badc3 100644
--- a/scripts/maintenance/vikingdb_content_backfill/backfill_vikingdb_content.py
+++ b/scripts/maintenance/vikingdb_content_backfill/backfill_vikingdb_content.py
@@ -7,6 +7,7 @@ import argparse
import asyncio
import hashlib
import json
+import sys
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
@@ -212,8 +213,8 @@ class ContentBackfillEnumerator:
def _list_dir_names(self, path: str) -> list[str]:
try:
entries = self._raw_agfs.ls(path)
- except Exception:
- return []
+ except Exception as exc:
+ raise RuntimeError(f"failed to list AGFS directory {path}") from exc
names: list[str] = []
for entry in entries or []:
if entry.get("isDir", entry.get("is_dir", False)) and entry.get("name"):
@@ -236,8 +237,10 @@ class ContentBackfillEnumerator:
node_limit=node_limit,
level_limit=None,
)
- except Exception:
- return
+ except Exception as exc:
+ raise RuntimeError(
+ f"failed to enumerate account {account_id} tree at {root_uri}"
+ ) from exc
for entry in entries:
uri = entry.get("uri")
@@ -330,7 +333,6 @@ class BackfillOptions:
run_dir: Path
execute: bool = False
rewrite_non_empty: bool = False
- batch_size: int = 100
limit: int | None = None
cutoff: datetime | None = None
fail_fast: bool = False
@@ -534,6 +536,12 @@ class ContentBackfillRunner:
SCRIPT_DIR = Path("scripts/maintenance/vikingdb_content_backfill")
RUNS_DIR = SCRIPT_DIR / "result"
ALLOWED_BACKENDS = {"volcengine", "vikingdb"}
+_DEPRECATED_NOOP_OPTIONS = {
+ "batch_size": "--batch-size",
+ "page_size": "--page-size",
+ "read_concurrency": "--read-concurrency",
+ "update_sleep_ms": "--update-sleep-ms",
+}
def default_run_dir() -> Path:
@@ -547,11 +555,16 @@ def validate_backend(backend: str) -> None:
def build_options(args: argparse.Namespace) -> BackfillOptions:
+ for attribute, flag in _DEPRECATED_NOOP_OPTIONS.items():
+ if getattr(args, attribute, None) is not None:
+ print(
+ f"warning: {flag} is deprecated and has no effect; remove it from scripts",
+ file=sys.stderr,
+ )
return BackfillOptions(
run_dir=Path(args.run_dir),
execute=bool(args.execute),
rewrite_non_empty=bool(getattr(args, "rewrite_non_empty", False)),
- batch_size=int(args.batch_size),
limit=getattr(args, "limit", None),
cutoff=datetime.now(),
fail_fast=bool(getattr(args, "fail_fast", False)),
@@ -563,10 +576,11 @@ def build_options(args: argparse.Namespace) -> BackfillOptions:
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--run-dir", type=Path, default=default_run_dir())
- parser.add_argument("--batch-size", type=int, default=100)
- parser.add_argument("--page-size", type=int, default=500)
- parser.add_argument("--read-concurrency", type=int, default=8)
- parser.add_argument("--update-sleep-ms", type=int, default=0)
+ deprecated_help = "deprecated no-op; accepted for compatibility"
+ parser.add_argument("--batch-size", type=int, default=None, help=deprecated_help)
+ parser.add_argument("--page-size", type=int, default=None, help=deprecated_help)
+ parser.add_argument("--read-concurrency", type=int, default=None, help=deprecated_help)
+ parser.add_argument("--update-sleep-ms", type=int, default=None, help=deprecated_help)
parser.add_argument("--limit", type=int, default=None)
parser.add_argument("--execute", action="store_true")
parser.add_argument("--rewrite-non-empty", action="store_true")
diff --git a/tests/misc/test_vikingdb_content_backfill.py b/tests/misc/test_vikingdb_content_backfill.py
new file mode 100644
index 000000000..2381f2fae
--- /dev/null
+++ b/tests/misc/test_vikingdb_content_backfill.py
@@ -0,0 +1,68 @@
+import asyncio
+
+import pytest
+
+from scripts.maintenance.vikingdb_content_backfill import (
+ backfill_vikingdb_content as backfill,
+)
+
+
+class FailingAgfs:
+ def ls(self, _path):
+ raise OSError("storage unavailable")
+
+
+class FailingSource:
+ async def tree(self, *_args, **_kwargs):
+ raise OSError("tree unavailable")
+
+
+def test_account_enumeration_surfaces_agfs_listing_failure():
+ enumerator = backfill.ContentBackfillEnumerator(FailingAgfs(), object())
+
+ with pytest.raises(RuntimeError, match="failed to list AGFS directory /local") as exc:
+ enumerator._list_dir_names("/local")
+
+ assert isinstance(exc.value.__cause__, OSError)
+
+
+def test_tree_enumeration_surfaces_source_failure():
+ enumerator = backfill.ContentBackfillEnumerator(object(), FailingSource())
+
+ async def collect():
+ return [
+ candidate
+ async for candidate in enumerator._iter_tree_candidates(
+ account_id="account-1",
+ root_uri="viking://",
+ ctx=object(),
+ node_limit=None,
+ )
+ ]
+
+ with pytest.raises(
+ RuntimeError,
+ match="failed to enumerate account account-1 tree at viking://",
+ ) as exc:
+ asyncio.run(collect())
+
+ assert isinstance(exc.value.__cause__, OSError)
+
+
+ ("flag", "attribute"),
+ [
+ ("--batch-size", "batch_size"),
+ ("--page-size", "page_size"),
+ ("--read-concurrency", "read_concurrency"),
+ ("--update-sleep-ms", "update_sleep_ms"),
+ ],
+)
+def test_legacy_noop_option_remains_accepted_with_warning(flag, attribute, capsys):
+ args = backfill.build_parser().parse_args([flag, "7"])
+
+ options = backfill.build_options(args)
+
+ assert getattr(args, attribute) == 7
+ assert not hasattr(options, attribute)
+ assert f"warning: {flag} is deprecated and has no effect" in capsys.readouterr().err