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

CONTRIBUTING.md

@@ -85,13 +85,30 @@ 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
 
 ```
 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

CONTRIBUTING_CN.md

@@ -84,13 +84,30 @@ 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`。
+
 ---
 
 ## 项目结构
 
 ```
 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` 等。
+
 ---
 
 ## 贡献流程

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

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:
 #        {

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 脚本
 

examples/server_client/client_async.py

@@ -5,7 +5,7 @@
 使用 AsyncHTTPClient 通过 HTTP 连接远程 Server，演示完整 API。
 
 前置条件:
-    先启动 Server: openviking serve
+    先启动 Server: openviking-server
 
 运行:
     uv run client_async.py

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):

examples/server_client/client_sync.py

@@ -5,7 +5,7 @@
 使用 SyncHTTPClient 通过 HTTP 连接远程 Server，演示完整 API。
 
 前置条件:
-    先启动 Server: openviking serve
+    先启动 Server: openviking-server
 
 运行:
     uv run client_sync.py