Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: 修复 openviking serve 命令引用并更新贡献文档 (#357)
Qin Haojiea2d35cd26449
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1d5a363ef..4a948e55e 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -85,6 +85,22 @@ async def main():asyncio.run(main())```+### 5. Build Rust CLI (Optional)++The Rust CLI (`ov`) provides a high-performance command-line client for interacting with OpenViking Server.++**Prerequisites**: Rust >= 1.88++```bash+# Build and install from source+cargo install --path crates/ov_cli++# Or use the quick install script (downloads pre-built binary)+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash+```++After installation, run `ov --help` to see all available commands. CLI connection config goes in `~/.openviking/ovcli.conf`.+---## Project Structure@@ -92,6 +108,7 @@ asyncio.run(main())```openviking/├── pyproject.toml # Project configuration+├── Cargo.toml # Rust workspace configuration├── third_party/ # Third-party dependencies│ └── agfs/ # AGFS filesystem│@@ -117,6 +134,11 @@ openviking/│ │ ├── session.py # Session core│ │ └── compressor.py # Compression│ │+│ ├── server/ # HTTP server+│ │ ├── app.py # FastAPI app factory+│ │ ├── bootstrap.py # Entry point (openviking-server)+│ │ └── routers/ # API routers+│ ││ ├── storage/ # Storage layer│ │ ├── viking_fs.py # VikingFS│ │ └── vectordb/ # Vector database@@ -126,7 +148,21 @@ openviking/│ ││ └── prompts/ # Prompt templates│+├── crates/ # Rust components+│ └── ov_cli/ # Rust CLI client+│ ├── src/ # CLI source code+│ └── install.sh # Quick install script+│+├── src/ # C++ extensions (pybind11)+│├── tests/ # Test suite+│ ├── client/ # Client tests+│ ├── server/ # Server tests+│ ├── session/ # Session tests+│ ├── parse/ # Parser tests+│ ├── vectordb/ # Vector database tests+│ └── integration/ # Integration tests+│└── docs/ # Documentation├── en/ # English docs└── zh/ # Chinese docs@@ -190,48 +226,50 @@ mypy openviking/# Run all testspytest+# Run specific test module+pytest tests/client/ -v+pytest tests/server/ -v+pytest tests/parse/ -v+# Run specific test file-pytest tests/test_parser.py+pytest tests/client/test_lifecycle.py++# Run specific test+pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success++# Run by keyword+pytest -k "search" -v# Run with coveragepytest --cov=openviking --cov-report=term-missing--# Run with verbose output-pytest -v```### Writing Tests-Place test files in `tests/` directory with `test_*.py` naming:+Tests are organized in subdirectories under `tests/`. The project uses `asyncio_mode = "auto"`, so async tests do **not** need the `@pytest.mark.asyncio` decorator:```python-# tests/test_client.py-import pytest+# tests/client/test_example.pyfrom openviking import AsyncOpenViking+class TestAsyncOpenViking:- @pytest.mark.asyncio- async def test_initialize(self, tmp_path):- client = AsyncOpenViking(path=str(tmp_path / "data"))- await client.initialize()- assert client._viking_fs is not None- await client.close()-- @pytest.mark.asyncio- async def test_add_resource(self, tmp_path):- client = AsyncOpenViking(path=str(tmp_path / "data"))- await client.initialize()+ async def test_initialize(self, uninitialized_client: AsyncOpenViking):+ await uninitialized_client.initialize()+ assert uninitialized_client._service is not None+ await uninitialized_client.close()+ async def test_add_resource(self, client: AsyncOpenViking):result = await client.add_resource("./test.md",reason="test document")assert result["status"] == "success"assert "root_uri" in result-- await client.close()```+Common fixtures are defined in `tests/conftest.py`, including `client` (initialized `AsyncOpenViking`), `uninitialized_client`, `temp_dir`, etc.+---## Contribution Workflowdiff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.mdindex 9875050b0..6cd074529 100644--- a/CONTRIBUTING_CN.md+++ b/CONTRIBUTING_CN.md@@ -84,6 +84,22 @@ async def main():asyncio.run(main())```+### 5. 构建 Rust CLI(可选)++Rust CLI (`ov`) 提供高性能的命令行客户端,用于连接 OpenViking Server 进行操作。++**前置要求**:Rust >= 1.88++```bash+# 从源码编译安装+cargo install --path crates/ov_cli++# 或者使用一键安装脚本(下载预编译二进制)+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash+```++安装后通过 `ov --help` 查看所有可用命令。CLI 连接配置见 `~/.openviking/ovcli.conf`。+---## 项目结构@@ -91,6 +107,7 @@ asyncio.run(main())```openviking/├── pyproject.toml # 项目配置+├── Cargo.toml # Rust workspace 配置├── third_party/ # 第三方依赖│ └── agfs/ # AGFS 文件系统│@@ -116,6 +133,11 @@ openviking/│ │ ├── session.py # 会话核心│ │ └── compressor.py # 压缩│ │+│ ├── server/ # HTTP 服务端+│ │ ├── app.py # FastAPI 应用工厂+│ │ ├── bootstrap.py # 启动入口 (openviking-server)+│ │ └── routers/ # API 路由+│ ││ ├── storage/ # 存储层│ │ ├── viking_fs.py # VikingFS│ │ └── vectordb/ # 向量数据库@@ -125,7 +147,21 @@ openviking/│ ││ └── prompts/ # 提示词模板│+├── crates/ # Rust 组件+│ └── ov_cli/ # Rust CLI 客户端+│ ├── src/ # CLI 源码+│ └── install.sh # 一键安装脚本+│+├── src/ # C++ 扩展 (pybind11)+│├── tests/ # 测试套件+│ ├── client/ # 客户端测试+│ ├── server/ # 服务端测试+│ ├── session/ # 会话测试+│ ├── parse/ # 解析器测试+│ ├── vectordb/ # 向量数据库测试+│ └── integration/ # 集成测试+│└── docs/ # 文档├── en/ # 英文文档└── zh/ # 中文文档@@ -189,48 +225,50 @@ mypy openviking/# 运行所有测试pytest+# 运行特定测试模块+pytest tests/client/ -v+pytest tests/server/ -v+pytest tests/parse/ -v+# 运行特定测试文件-pytest tests/test_parser.py+pytest tests/client/test_lifecycle.py++# 运行特定测试+pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success++# 按关键字运行+pytest -k "search" -v# 运行并生成覆盖率报告pytest --cov=openviking --cov-report=term-missing--# 详细输出模式运行-pytest -v```### 编写测试-将测试文件放在 `tests/` 目录下,命名为 `test_*.py`:+测试按模块组织在 `tests/` 的子目录中。项目使用 `asyncio_mode = "auto"`,异步测试**不需要** `@pytest.mark.asyncio` 装饰器:```python-# tests/test_client.py-import pytest+# tests/client/test_example.pyfrom openviking import AsyncOpenViking+class TestAsyncOpenViking:- @pytest.mark.asyncio- async def test_initialize(self, tmp_path):- client = AsyncOpenViking(path=str(tmp_path / "data"))- await client.initialize()- assert client._viking_fs is not None- await client.close()-- @pytest.mark.asyncio- async def test_add_resource(self, tmp_path):- client = AsyncOpenViking(path=str(tmp_path / "data"))- await client.initialize()+ async def test_initialize(self, uninitialized_client: AsyncOpenViking):+ await uninitialized_client.initialize()+ assert uninitialized_client._service is not None+ await uninitialized_client.close()+ async def test_add_resource(self, client: AsyncOpenViking):result = await client.add_resource("./test.md",reason="test document")assert result["status"] == "success"assert "root_uri" in result-- await client.close()```+常用 fixture 定义在 `tests/conftest.py` 中,包括 `client`(已初始化的 `AsyncOpenViking`)、`uninitialized_client`、`temp_dir` 等。+---## 贡献流程diff --git a/examples/k8s-helm/templates/deployment.yaml b/examples/k8s-helm/templates/deployment.yamlindex 6adedee05..95427b7ce 100644--- a/examples/k8s-helm/templates/deployment.yaml+++ b/examples/k8s-helm/templates/deployment.yaml@@ -24,7 +24,7 @@ spec:- /bin/sh- -c- |- exec uv run --with openviking openviking serve \+ exec uv run --with openviking openviking-server \--host {{ .Values.server.host }} \--port {{ .Values.server.port }} \--config /etc/openviking/ov.confdiff --git a/examples/multi_tenant/admin_workflow.sh b/examples/multi_tenant/admin_workflow.shindex 8d13628c9..71f36bc9e 100755--- a/examples/multi_tenant/admin_workflow.sh+++ b/examples/multi_tenant/admin_workflow.sh@@ -10,7 +10,7 @@# 1. Configure & start the server with root_api_key:# Copy ov.conf.example to ov.conf, fill in your model API keys, then:#-# openviking serve --config ./ov.conf+# openviking-server --config ./ov.conf## The key config for multi-tenant auth:# {diff --git a/examples/server_client/README.md b/examples/server_client/README.mdindex fd9e47d60..e7da8876c 100644--- a/examples/server_client/README.md+++ b/examples/server_client/README.md@@ -23,9 +23,9 @@ uv sync# 参见 ov.conf.example 了解完整配置项# 2. 启动 Server(另开终端)-openviking serve # 从默认路径读取 ov.conf-openviking serve --config ./ov.conf # 指定配置文件-openviking serve --host 0.0.0.0 --port 1933 # 覆盖 host/port+openviking-server # 从默认路径读取 ov.conf+openviking-server --config ./ov.conf # 指定配置文件+openviking-server --host 0.0.0.0 --port 1933 # 覆盖 host/port# 3. 配置 CLI 连接(ovcli.conf)# CLI 读取配置的优先级:@@ -89,16 +89,16 @@ pyproject.toml # 项目依赖```bash# 基本启动(从 ~/.openviking/ov.conf 或 $OPENVIKING_CONFIG_FILE 读取配置)-openviking serve+openviking-server# 指定配置文件-openviking serve --config ./ov.conf+openviking-server --config ./ov.conf# 覆盖 host/port-openviking serve --host 0.0.0.0 --port 1933+openviking-server --host 0.0.0.0 --port 1933```-`serve` 命令支持 `--config`、`--host`、`--port` 三个选项。认证密钥等其他配置通过 ov.conf 的 `server` 段设置。+`openviking-server` 命令支持 `--config`、`--host`、`--port` 三个选项。认证密钥等其他配置通过 ov.conf 的 `server` 段设置。### Python 脚本diff --git a/examples/server_client/client_async.py b/examples/server_client/client_async.pyindex ea96854db..28715a584 100644--- a/examples/server_client/client_async.py+++ b/examples/server_client/client_async.py@@ -5,7 +5,7 @@ OpenViking 异步客户端示例 (HTTP mode)使用 AsyncHTTPClient 通过 HTTP 连接远程 Server,演示完整 API。前置条件:- 先启动 Server: openviking serve+ 先启动 Server: openviking-server运行:uv run client_async.pydiff --git a/examples/server_client/client_cli.sh b/examples/server_client/client_cli.shindex 691eed72f..5ec71946d 100755--- a/examples/server_client/client_cli.sh+++ b/examples/server_client/client_cli.sh@@ -13,9 +13,9 @@# b) ~/.openviking/ov.conf # default path# See ov.conf.example for template.#-# openviking serve # default: localhost:1933-# openviking serve --port 8080 # custom port-# openviking serve --config /path/to/ov.conf # explicit config path+# openviking-server # default: localhost:1933+# openviking-server --port 8080 # custom port+# openviking-server --config /path/to/ov.conf # explicit config path## 2. Configure CLI connection (ovcli.conf):# CLI reads ovcli.conf from (priority high → low):diff --git a/examples/server_client/client_sync.py b/examples/server_client/client_sync.pyindex 797433e09..6a1d47c9d 100644--- a/examples/server_client/client_sync.py+++ b/examples/server_client/client_sync.py@@ -5,7 +5,7 @@ OpenViking 同步客户端示例 (HTTP mode)使用 SyncHTTPClient 通过 HTTP 连接远程 Server,演示完整 API。前置条件:- 先启动 Server: openviking serve+ 先启动 Server: openviking-server运行:uv run client_sync.py