# コントリビューションガイド OpenVikingに興味をお持ちいただきありがとうございます！あらゆる種類のコントリビューションを歓迎します： - バグレポート - 機能リクエスト - ドキュメントの改善 - コードのコントリビューション --- ## 開発環境のセットアップ ### 前提条件 - **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. フォークとクローン ```bash git clone https://github.com/YOUR_USERNAME/openviking.git cd openviking ``` ### 2. 依存関係のインストール Python環境管理には`uv`の使用を推奨します： ```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はAGFSに対してデフォルトで`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 バイナリも一緒にビルドされるためです。 **前提条件**: Rust >= 1.91.1 ```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ワークスペース設定 ├── 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 # 非推奨スタブ（npm パッケージを使用、Install を参照） │ ├── src/ # C++拡張ソース（Python abi3） │ ├── tests/ # テストスイート │ ├── client/ # クライアントテスト │ ├── console/ # Console テスト │ ├── core/ # コアロジックテスト │ ├── parse/ # パーサーテスト │ ├── resource/ # リソース処理テスト │ ├── retrieve/ # 検索テスト │ ├── server/ # サーバーテスト │ ├── service/ # Service レイヤーテスト │ ├── session/ # セッションテスト │ ├── storage/ # ストレージテスト │ ├── telemetry/ # Telemetry テスト │ ├── vectordb/ # ベクトルデータベーステスト │ └── integration/ # E2E テスト │ └── docs/ # ドキュメント ├── en/ # 英語ドキュメント └── zh/ # 中国語ドキュメント ``` --- ## コードスタイル コードの一貫性を維持するために以下のツールを使用しています： | ツール | 目的 | 設定 | |------|---------|--------| | **Ruff** | リンティング、フォーマット、インポートソート | `pyproject.toml` | | **mypy** | 型チェック | `pyproject.toml` | ### チェックの実行 ```bash # コードのフォーマット ruff format openviking/ # リント ruff check openviking/ # 型チェック mypy openviking/ ``` ### スタイルガイドライン 1. **行幅**: 100文字 2. **インデント**: スペース4つ 3. **文字列**: ダブルクォートを推奨 4. **型ヒント**: 推奨（必須ではない） 5. **Docstring**: パブリック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://") ``` 共通フィクスチャは`tests/conftest.py`に定義されており、初期化済みの`service`、`request_context`、`temp_dir`、サンプルファイルなどが含まれます。 --- ## コントリビューションワークフロー ### 1. ブランチの作成 ```bash git checkout main git pull origin main git checkout -b feature/your-feature-name ``` ブランチ命名規則： - `feature/xxx` - 新機能 - `fix/xxx` - バグ修正 - `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でプルリクエストを作成します。 --- ## コミット規約 [Conventional Commits](https://www.conventionalcommits.org/)に従います： ``` ():