Skip to content

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

docs: 修复 openviking serve 命令引用并更新贡献文档 (#357)

Qin Haojiea2d35cd26449
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 tests
pytest
+# 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 coverage
pytest --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.py
from 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 Workflow
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index 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.py
from 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.yaml
index 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.conf
diff --git a/examples/multi_tenant/admin_workflow.sh b/examples/multi_tenant/admin_workflow.sh
index 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.md
index 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.py
index 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.py
diff --git a/examples/server_client/client_cli.sh b/examples/server_client/client_cli.sh
index 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.py
index 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