OpenViking/CONTRIBUTING_JA.md

コントリビューションガイド

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. フォークとクローン

git clone https://github.com/YOUR_USERNAME/openviking.git
cd openviking

2. 依存関係のインストール

Python環境管理にはuvの使用を推奨します：

# 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++拡張を変更した場合や、プリビルド成果物が見つからない場合は、再コンパイルと再インストールが必要です。プロジェクトルートで以下のコマンドを実行してください：

uv pip install -e . --force-reinstall

このコマンドによりsetup.pyが再実行され、AGFS、同梱 ov CLI、C++コンポーネントの再ビルドがトリガーされます。

3. 環境設定

設定ファイル ~/.openviking/ov.conf を作成します：

{
  "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"
  }
}

環境変数を設定します：

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

4. インストールの確認

import asyncio
import openviking as ov

async def main():
    client = ov.AsyncOpenViking(path="./test_data")
    await client.initialize()
    print("OpenViking initialized successfully!")
    await client.close()

asyncio.run(main())

5. Rust CLIのビルド（オプション）

Rust CLI（ov）は、OpenViking Serverとやり取りするための高性能コマンドラインクライアントを提供します。

ov を直接使わない場合でも、OpenViking をソースからビルドするなら Rust ツールチェーンは必要です。パッケージング時に同梱 CLI バイナリも一緒にビルドされるためです。

前提条件: Rust >= 1.91.1

# ソースからビルドしてインストール
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 SDK
│   ├── async_client.py   # AsyncOpenVikingクライアント
│   ├── sync_client.py    # SyncOpenVikingクライアント
│   ├── 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

チェックの実行

# コードのフォーマット
ruff format openviking/

# リント
ruff check openviking/

# 型チェック
mypy openviking/

スタイルガイドライン

1. 行幅: 100文字
2. インデント: スペース4つ
3. 文字列: ダブルクォートを推奨
4. 型ヒント: 推奨（必須ではない）
5. Docstring: パブリックAPIには必須（最大1〜2行）

---

テスト

テストの実行

# 全テストの実行
pytest

# 特定のテストモジュールの実行
pytest tests/client/ -v
pytest tests/server/ -v
pytest tests/parse/ -v

# 特定のテストファイルの実行
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

テストの書き方

テストはtests/配下のサブディレクトリに整理されています。プロジェクトはasyncio_mode = "auto"を使用しているため、非同期テストに@pytest.mark.asyncioデコレーターは不要です：

# tests/client/test_example.py
from openviking import AsyncOpenViking


class TestAsyncOpenViking:
    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, sample_markdown_file):
        result = await client.add_resource(
            path=str(sample_markdown_file),
            reason="test document"
        )
        assert "root_uri" in result
        assert result["root_uri"].startswith("viking://")

共通フィクスチャはtests/conftest.pyに定義されており、client（初期化済みAsyncOpenViking）、uninitialized_client、temp_dir、sample_markdown_file などが含まれます。

---

コントリビューションワークフロー

1. ブランチの作成

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

ブランチ命名規則：

• feature/xxx - 新機能
• fix/xxx - バグ修正
• docs/xxx - ドキュメント更新
• refactor/xxx - コードリファクタリング

2. 変更の実施

• コードスタイルガイドラインに従う
• 新機能にはテストを追加する
• 必要に応じてドキュメントを更新する

3. 変更のコミット

git add .
git commit -m "feat: add new parser for xlsx files"

4. プッシュとPRの作成

git push origin feature/your-feature-name

その後、GitHubでプルリクエストを作成します。

---

コミット規約

Conventional Commitsに従います：

<type>(<scope>): <subject>

<body>

<footer>

タイプ

タイプ	説明
feat	新機能
fix	バグ修正
docs	ドキュメント
style	コードスタイル（ロジック変更なし）
refactor	コードリファクタリング
perf	パフォーマンス改善
test	テスト
chore	ビルド/ツーリング

例

# 新機能
git commit -m "feat(parser): add support for xlsx files"

# バグ修正
git commit -m "fix(retrieval): fix score calculation in rerank"

# ドキュメント
git commit -m "docs: update quick start guide"

# リファクタリング
git commit -m "refactor(storage): simplify interface methods"

---

プルリクエストガイドライン

PRタイトル

コミットメッセージと同じフォーマットを使用します。

PR説明テンプレート

## 概要

変更内容とその目的の簡単な説明。

## 変更の種類

- [ ] 新機能（feat）
- [ ] バグ修正（fix）
- [ ] ドキュメント（docs）
- [ ] リファクタリング（refactor）
- [ ] その他

## テスト

これらの変更のテスト方法を記述してください：
- [ ] ユニットテストが通過する
- [ ] 手動テストが完了している

## 関連Issue

- Fixes #123
- Related to #456

## チェックリスト

- [ ] コードがプロジェクトのスタイルガイドラインに従っている
- [ ] 新機能にテストが追加されている
- [ ] ドキュメントが更新されている（必要な場合）
- [ ] すべてのテストが通過する

---

CI/CDワークフロー

継続的インテグレーションとデプロイメントにGitHub Actionsを使用しています。ワークフローはモジュール化され、段階的に設計されています。

1. 自動ワークフロー

イベント	ワークフロー	説明
プルリクエスト	pr.yml	Lint（Ruff、Mypy）とTest Lite（Linux + Python 3.10での統合テスト）を実行。コントリビューターに迅速なフィードバックを提供。（01. Pull Request Checksとして表示）
mainへのプッシュ	ci.yml	Test Full（全OS：Linux/Win/Mac、全Pyバージョン：3.10-3.14）とCodeQL（セキュリティスキャン）を実行。mainブランチの安定性を保証。（02. Main Branch Checksとして表示）
リリース公開	release.yml	GitHubでリリースを作成すると発動。自動的にソースディストリビューションとwheelをビルドし、Gitタグからバージョンを判定してPyPIに公開。（03. Releaseとして表示）
週次Cron	schedule.yml	毎週日曜日にCodeQLセキュリティスキャンを実行。（04. Weekly Security Scanとして表示）

このほか、PR review の自動化、Docker イメージのビルド、Rust CLI のパッケージング用ワークフローも用意されています。

2. 手動トリガーワークフロー

メンテナーは「Actions」タブから以下のワークフローを手動でトリガーして、特定のタスクを実行したり問題をデバッグしたりできます。

A. Lintチェック (11. _Lint Checks)

コードスタイルチェック（Ruff）と型チェック（Mypy）を実行。引数は不要です。

B. テストスイート（Lite）(12. _Test Suite (Lite))

高速統合テストを実行し、カスタムマトリックス設定をサポートします。

• 入力:
  • os_json: 実行するOSのJSON文字列配列（例：["ubuntu-24.04"]）。
  • python_json: Pythonバージョンの JSON文字列配列（例：["3.10"]）。

C. テストスイート（Full）(13. _Test Suite (Full))

サポートされているすべてのプラットフォーム（Linux/Mac/Win）とPythonバージョン（3.10-3.14）で完全なテストスイートを実行。手動トリガー時にカスタムマトリックス設定をサポートします。

• 入力:
  • os_json: 実行するOSのリスト（デフォルト：["ubuntu-24.04", "macos-14", "windows-latest"]）。
  • python_json: Pythonバージョンのリスト（デフォルト：["3.10", "3.11", "3.12", "3.13", "3.14"]）。

D. セキュリティスキャン (14. _CodeQL Scan)

CodeQLセキュリティ分析を実行。引数は不要です。

E. ディストリビューションビルド (15. _Build Distribution)

Pythonのwheelパッケージのみをビルドし、公開はしません。

• 入力:
  • os_json: ビルドするOSのリスト（デフォルト：["ubuntu-24.04", "ubuntu-24.04-arm", "macos-14", "macos-15-intel", "windows-latest"]）。
  • python_json: Pythonバージョンのリスト（デフォルト：["3.10", "3.11", "3.12", "3.13", "3.14"]）。
  • build_sdist: ソースディストリビューションをビルドするか（デフォルト：true）。
  • build_wheels: wheelディストリビューションをビルドするか（デフォルト：true）。

F. ディストリビューション公開 (16. _Publish Distribution)

ビルド済みパッケージをPyPIに公開（ビルドRun IDが必要）。

• 入力:
  • target: 公開先を選択（testpypi、pypi、both）。
  • build_run_id: ビルドワークフローのRun ID（必須、ビルド実行URLから取得）。

G. 手動リリース (03. Release)

ワンストップのビルドと公開（ビルドと公開ステップを含む）。

バージョン番号とタグ規約: このプロジェクトはsetuptools_scmを使用してGitタグからバージョン番号を自動抽出します。

• タグ命名規約: vX.Y.Z形式に従う必要があります（例：v0.1.0、v1.2.3）。タグはセマンティックバージョニングに準拠する必要があります。
• リリースビルド: リリースイベントがトリガーされると、バージョン番号はGitタグに直接対応します（例：v0.1.0 -> 0.1.0）。
• 手動/非タグビルド: バージョン番号には最後のタグからのコミット数が含まれます（例：0.1.1.dev3）。
• バージョン確認: 公開ジョブ完了後、ワークフローSummaryページ上部のNotificationsエリアで公開バージョンを直接確認できます（例：Successfully published to PyPI with version: 0.1.8）。ログまたはArtifactsのファイル名でも確認できます。

• 入力:
  • target: 公開先を選択。
    • none: アーティファクトのビルドのみ（公開なし）。ビルド機能の検証に使用。
    • testpypi: TestPyPIに公開。ベータテストに使用。
    • pypi: 公式PyPIに公開。
    • both: 両方に公開。
  • os_json: ビルドプラットフォーム（デフォルトはすべて含む）。
  • python_json: Pythonバージョン（デフォルトはすべて含む）。
  • build_sdist: ソースディストリビューションをビルドするか（デフォルト：true）。
  • build_wheels: wheelディストリビューションをビルドするか（デフォルト：true）。

公開に関する注意事項:

• 先にテスト: 公式PyPIに公開する前に、TestPyPIで検証することを強く推奨します。PyPIとTestPyPIは完全に独立した環境であり、アカウントやパッケージデータは共有されません。
• 上書き不可: PyPIもTestPyPIも、同じ名前とバージョンの既存パッケージの上書きを許可しません。再公開が必要な場合は、バージョン番号をアップグレードする必要があります（例：新しいバージョンをタグ付けするか、新しいdevバージョンを生成）。既存のバージョンを公開しようとすると、ワークフローが失敗します。

---

Issueガイドライン

バグレポート

以下を提供してください：

1. 環境

   • Pythonバージョン
   • OpenVikingバージョン
   • オペレーティングシステム

2. 再現手順

   • 詳細な手順
   • コードスニペット

3. 期待される動作と実際の動作

4. エラーログ（ある場合）

機能リクエスト

以下を記述してください：

1. 問題: どのような問題を解決しようとしていますか？
2. 解決策: どのような解決策を提案しますか？
3. 代替案: 他のアプローチを検討しましたか？

---

ドキュメント

ドキュメントはdocs/配下にMarkdown形式で管理されています：

• docs/en/ - 英語ドキュメント
• docs/zh/ - 中国語ドキュメント

ドキュメントガイドライン

1. コード例は実行可能であること
2. ドキュメントとコードの同期を維持すること
3. 明確で簡潔な言葉を使用すること

---

行動規範

このプロジェクトに参加することで、以下に同意するものとします：

1. 敬意を持つ: 友好的でプロフェッショナルな態度を維持する
2. 包括的である: あらゆるバックグラウンドのコントリビューターを歓迎する
3. 建設的である: 有益なフィードバックを提供する
4. 集中する: 議論を技術的な内容に保つ

---

ヘルプ

質問がある場合：

• GitHub Issues
• Discussions

---

コントリビューションありがとうございます！