# 贡献指南 感谢你对 OpenViking 感兴趣！我们欢迎各种形式的贡献： - 报告 Bug - 提交功能请求 - 改进文档 - 贡献代码 --- ## 开发环境设置 ### 前置要求 - **Python**: 3.10+ - **Go**: 1.22+ (从源码构建 AGFS 组件需要) - **Rust**: 1.91.1+（从源码构建需要；打包流程会同时构建内置 `ov` CLI） - **C++ 编译器**: GCC 9+ 或 Clang 11+ (构建核心扩展需要，必须支持 C++17) - **CMake**: 3.15+ #### 平台相关的本地构建工具 - **Linux**: 建议安装 `build-essential`；某些环境下还可能需要 `pkg-config` - **macOS**: 安装 Xcode Command Line Tools（`xcode-select --install`） - **Windows**: 本地原生构建建议安装 CMake 和 MinGW #### 支持的平台 (预编译 Wheel 包) OpenViking 为以下环境提供预编译的 **Wheel** 包，安装时无需本地编译： - **Windows**: x86_64 - **macOS**: x86_64, arm64 (Apple Silicon) - **Linux**: x86_64, arm64 (manylinux) 对于其他平台（如 FreeBSD 等），安装时 `pip` 将会自动从源码进行编译。请确保已安装上述[前置要求](#前置要求)中的工具。 ### 1. Fork 并克隆 ```bash git clone https://github.com/YOUR_USERNAME/openviking.git cd openviking ``` ### 2. 安装依赖 我们推荐使用 `uv` 进行 Python 环境管理： ```bash # 安装 uv (如果尚未安装) curl -LsSf https://astral.sh/uv/install.sh | sh # 同步依赖并创建虚拟环境 uv sync --all-extras source .venv/bin/activate # Linux/macOS # 或者 .venv\Scripts\activate # Windows ``` #### 本地开发与原生组件重建 OpenViking 默认使用 `binding-client` 模式，这依赖预先构建的原生产物。如果你修改了 **AGFS (Go)** 代码、内置的 **Rust CLI**，或 **C++ 扩展**，或者这些预编译产物未找到，你需要重新编译并安装它们，以使更改在本地环境中生效。在项目根目录下运行以下命令： ```bash uv pip install -e . --force-reinstall ``` 该命令会强制重新执行 `setup.py`，触发 AGFS、内置 `ov` CLI 和 C++ 组件的重新编译与安装。 ### 3. 配置环境 创建配置文件 `~/.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" } } ``` 设置环境变量： ```bash export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf ``` ### 4. 验证安装 ```bash python -c "import openviking; print(openviking.__version__)" ``` ### 5. 构建 Rust CLI（可选） Rust CLI (`ov`) 提供高性能的命令行客户端，用于连接 OpenViking Server 进行操作。 即使你不打算直接使用 `ov`，只要走 OpenViking 的源码构建流程，Rust 工具链仍然是必需的，因为打包过程也会构建内置 CLI 二进制。 ```bash # 从源码编译安装 cargo install --path crates/ov_cli # 或者安装已发布的 npm CLI 包（下载预编译二进制） npm i -g @openviking/cli ``` 安装后通过 `ov --help` 查看所有可用命令。CLI 连接配置见 `~/.openviking/ovcli.conf`。 --- ## 项目结构 ``` openviking/ ├── pyproject.toml # 项目配置 ├── Cargo.toml # Rust workspace 配置 ├── third_party/ # 第三方依赖 │ └── agfs/ # AGFS 文件系统 │ ├── openviking/ # Python 服务端与核心实现 │ ├── client/ # HTTP 客户端兼容导出 │ ├── console/ # 独立 console UI 与代理服务 │ ├── core/ # 核心数据模型与目录抽象 │ ├── message/ # 会话消息与 part 模型 │ ├── models/ # Embedding 与 VLM 后端 │ ├── parse/ # 资源解析器与检测器 │ ├── resource/ # 资源处理与 watch 管理 │ ├── retrieve/ # 检索系统 │ ├── server/ # HTTP 服务端 │ ├── service/ # 共享 service 层 │ ├── session/ # 会话管理与压缩 │ ├── storage/ # 存储层 │ ├── telemetry/ # 操作级 telemetry │ ├── trace/ # trace 与运行时跟踪辅助 │ ├── utils/ # 工具类与配置辅助 │ └── prompts/ # 提示词模板 │ ├── crates/ # Rust 组件 │ └── ov_cli/ # Rust CLI 客户端 │ ├── src/ # CLI 源码 │ └── install.sh # 已废弃 stub (改用 npm 包, 见 Install) │ ├── src/ # C++ 扩展源码（Python abi3） │ ├── tests/ # 测试套件 │ ├── client/ # 客户端测试 │ ├── console/ # Console 测试 │ ├── core/ # 核心逻辑测试 │ ├── parse/ # 解析器测试 │ ├── resource/ # 资源处理测试 │ ├── retrieve/ # 检索测试 │ ├── server/ # 服务端测试 │ ├── service/ # Service 层测试 │ ├── session/ # 会话测试 │ ├── storage/ # 存储测试 │ ├── telemetry/ # Telemetry 测试 │ ├── vectordb/ # 向量数据库测试 │ └── integration/ # 端到端测试 │ └── docs/ # 文档 ├── en/ # 英文文档 └── zh/ # 中文文档 ``` --- ## 代码风格 我们使用以下工具来保持代码一致性： | 工具 | 用途 | 配置 | |------|---------|--------| | **Ruff** | Linting, 格式化, 导入排序 | `pyproject.toml` | | **mypy** | 类型检查 | `pyproject.toml` | ### 运行检查 ```bash # 格式化代码 ruff format openviking/ # Lint 检查 ruff check openviking/ # 类型检查 mypy openviking/ ``` ### 风格指南 1. **行宽**：100 字符 2. **缩进**：4 个空格 3. **字符串**：推荐使用双引号 4. **类型提示**：鼓励但不强制 5. **Docstrings**：公共 API 必须包含（最多 1-2 行） --- ## 测试 ### 运行测试 ```bash # 运行所有测试 pytest # 运行特定测试模块 pytest tests/client/ -v pytest tests/server/ -v pytest tests/parse/ -v # 运行特定测试文件 pytest tests/client/test_http_client_config.py # 运行特定测试 pytest tests/client/test_http_client_config.py # 按关键字运行 pytest -k "search" -v # 运行并生成覆盖率报告 pytest --cov=openviking --cov-report=term-missing ``` ### 编写测试 测试按模块组织在 `tests/` 的子目录中。项目使用 `asyncio_mode = "auto"`，异步测试**不需要** `@pytest.mark.asyncio` 装饰器： ```python # tests/service/test_example.py class TestResourceService: async def test_add_resource(self, service, request_context, sample_markdown_file): result = await service.resources.add_resource( path=str(sample_markdown_file), ctx=request_context, reason="test document", ) assert "root_uri" in result assert result["root_uri"].startswith("viking://") ``` 常用 fixture 定义在 `tests/conftest.py` 中，包括已初始化的 `service`、`request_context`、`temp_dir` 和示例文件等。 --- ## 维护者路由与贡献入口 ### 面向贡献者的模块地图 如果你还不确定问题、issue 或 PR 属于哪个方向，可以先看这张表： | 领域 | 模块 | 主要联系人 | |------|------|------------| | Integration | Bot | `@yeshion23333` | | Integration | OpenClaw Plugin | `@Mijamind719`、`@wlff123` | | Platform | Framework / Multi-tenant / Resources / Session | `@qin-ctx` | | Platform | Incremental / Scheduled Update | `@myysy` | | Knowledge | Memory | `@chenjw` | | Knowledge | Retrieval / Directory Semantics | `@zhoujh01` | | Storage & Security | Virtual FS / File Encryption | `@chuanbao666`、`@baojun-zhang` | 如果还是无法判断归属，可以直接 @ 下方的跨模块维护支持成员。 ### 面向维护者的路由表 当需要把 issue、PR 或设计问题路由到更具体的 owner 时，可以参考下表： | 领域 | 子域 | 代表路径或主题 | 主要联系人 | 备援 / 跨模块支持 | |------|------|----------------|------------|-------------------| | Integration | Bot Runtime | `bot/vikingbot`、`bot/bridge`、部署脚本、bot 文档 | `@yeshion23333` | `@chenjw` | | Integration | OpenClaw Plugin | `examples/openclaw-plugin`、安装、remote mode、兼容性 | `@Mijamind719`、`@wlff123` | `@LinQiang391` | | Platform | Server & Multi-tenant | `openviking/server`、`openviking/service`、auth、identity、admin、租户边界 | `@qin-ctx` | `@MaojiaSheng` | | Platform | Resource & Session Lifecycle | `openviking/resource`、`openviking/session`、资源导入、session 生命周期 | `@qin-ctx` | `@MaojiaSheng` | | Platform | Incremental & Scheduled Update | `openviking/resource/watch_manager.py`、`openviking/resource/watch_scheduler.py` | `@myysy` | `@qin-ctx` | | Knowledge | Memory Engine | `openviking/session/memory`、`memory_extractor.py`、`memory_deduplicator.py` | `@chenjw` | `@qin-ctx` | | Knowledge | Retrieval & Directory Semantics | `openviking/retrieve`、意图分析、分层检索、目录语义 | `@zhoujh01` | `@qin-ctx` | | Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`、`openviking/pyagfs`、文件系统行为、路径语义 | `@chuanbao666`、`@baojun-zhang` | `@zhoujh01` | | Storage & Security | Encryption & Data Safety | `openviking/crypto`、文件加密、存储安全 | `@chuanbao666`、`@baojun-zhang` | `@zhoujh01` | 对于暂时还没有稳定 owner 的方向，先由跨模块维护支持成员协助路由。 ### 跨模块维护支持 - `@MaojiaSheng` - `@qin-ctx` - `@zhoujh01` 跨模块维护支持成员主要负责 issue 路由、跨模块设计问题，以及 owner 繁忙时的补位 review。 ### 如何获得帮助 - 如果你已经知道受影响模块，请在 issue 或 PR 描述中直接写明。 - 如果暂时无法判断模块归属，优先描述使用场景和受影响行为。 - 如果你想认领某个 issue，建议先留言说明，尤其是跨模块改动。 - 如果你的 PR 涉及多个模块，请在描述中标明主要影响域。 ### 贡献入口标签 Issue 模板已经会对 `bug`、`enhancement`、`question` 等问题类型做基础分类。为了让贡献入口更清晰，维护者还可能补充以下标签： | 标签 | 含义 | |------|------| | `good first issue` | 适合新贡献者上手，范围清晰且验收标准明确 | | `help wanted` | 更适合已经熟悉仓库或 review 风格的贡献者参与 | | `needs-design` | 实现前需要维护者先澄清设计边界 | | `needs-review` | 正在等待首轮 review 的 PR | ### 贡献成长路径 我们希望贡献成长路径足够实际，让贡献者能清楚看到下一步可以怎么参与： | 阶段 | 常见信号 | 下一步建议 | |------|----------|------------| | 新贡献者 | 第一次提 issue 或 PR，通常从文档、测试或小范围修复开始 | 从 `good first issue` 入手，熟悉本地开发和提交流程 | | 活跃贡献者 | 已经有一个或多个合入贡献 | 在自己熟悉的模块下开始认领 `help wanted` | | 模块贡献者 | 在同一子域持续贡献 | 开始参与该模块的 issue 分流、问题复现、文档补充或 review 建议 | | 备援 Reviewer 候选 | 在某个子域形成稳定贡献记录 | 协助首轮 review、问题路由和贡献者支持 | ## 贡献流程 ### 1. 创建分支 ```bash git checkout main git pull origin main git checkout -b feature/your-feature-name ``` 分支命名规范： - `feature/xxx` - 新功能 - `fix/xxx` - Bug 修复 - `docs/xxx` - 文档更新 - `refactor/xxx` - 代码重构 ### 2. 修改代码 - 遵循代码风格指南 - 为新功能添加测试 - 根据需要更新文档 ### 3. 提交更改 ```bash git add . git commit -m "feat: add new parser for xlsx files" ``` ### 4. 推送并创建 PR ```bash git push origin feature/your-feature-name ``` 然后在 GitHub 上创建一个 Pull Request。 --- ## 提交规范 我们遵循 [Conventional Commits](https://www.conventionalcommits.org/)： ``` ():