Skip to content

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

docs: streamline contribution guidelines (#4278)

Qin Haojie1c62be57b01f
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 63b2c62fe..37a7c5040 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,573 +1,268 @@
-# Contributing Guide
+# Contributing to OpenViking
-Thank you for your interest in OpenViking! We welcome contributions of all kinds:
+English / [中文](CONTRIBUTING_CN.md) / [日本語](CONTRIBUTING_JA.md)
-- Bug reports
-- Feature requests
-- Documentation improvements
-- Code contributions
+Thank you for contributing to OpenViking. This guide exists to help contributors
+submit changes that are clear, focused, and practical to review.
----
+We welcome bug reports, feature requests, documentation improvements, and code
+contributions.
-## Development Setup
+## What We Value
-### Prerequisites
+OpenViking values focused, well-understood changes. Contributors are responsible
+for understanding, explaining, and validating their changes, whether or not AI
+tools were used.
-- **Python**: 3.10+
-- **Go**: 1.22+ (Required only for Go SDK development under `sdk/go`)
-- **Rust**: 1.91.1+ (Required for source builds because the bundled `ov` CLI is built during packaging)
-- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions, must support C++17)
-- **CMake**: 3.15+
+Prefer the smallest complete change. Concise code means fewer concepts, branches,
+duplicated rules, and speculative abstractions—not fewer necessary lines. A good
+change is direct, readable, and easy to explain from its entrypoint to its
+observable behavior.
-#### Platform-Specific Native Build Tools
+In practice:
-- **Linux**: Install `build-essential`; some environments may also require `pkg-config`
-- **macOS**: Install Xcode Command Line Tools (`xcode-select --install`)
-- **Windows**: Install CMake and MinGW for local native builds
+- Solve one coherent problem per PR. Do not mix unrelated cleanup or refactoring.
+- Reuse the existing owner of a rule instead of introducing a parallel mechanism.
+- Avoid speculative fallbacks, flags, state fields, and abstractions.
+- Remove code, tests, and compatibility paths that the new implementation replaces.
+- Keep necessary structure when it makes ownership, lifecycle, or failure handling
+ clearer.
-#### Supported Platforms (Pre-compiled Wheels)
+### Review Priority
-OpenViking provides pre-compiled **Wheel** packages for the following environments:
+Maintainer time is limited, so focused PRs are reviewed first:
-- **Windows**: x86_64
-- **macOS**: x86_64, arm64 (Apple Silicon)
-- **Linux**: x86_64, arm64 (manylinux)
+- PRs with **100 or fewer changed lines** are usually reviewed more promptly.
+- PRs with **200 or fewer changed lines** are prioritized over larger PRs.
-For other platforms (e.g., FreeBSD), the package will be automatically compiled from source during installation via `pip`. Ensure you have the [Prerequisites](#prerequisites) installed.
+These are review priorities, not hard limits or response-time guarantees. Changed
+lines mean additions plus deletions in hand-written source, tests, and documentation;
+generated files, vendored code, and lockfiles are excluded when assessing size.
-### 1. Fork and Clone
+Do not omit necessary tests or documentation to stay below a threshold. Split a
+large change only where each PR remains independently understandable and correct.
+Small size does not override correctness, design quality, or compatibility.
-```bash
-git clone https://github.com/YOUR_USERNAME/openviking.git
-cd openviking
-```
+## Before You Start
-### 2. Install Dependencies
+1. Search existing issues, PRs, and code for the same behavior or domain rule.
+2. For a bug, reproduce it through the real production entrypoint when possible.
+3. Identify the owning module and trace where the value or state is created,
+ normalized, stored, and consumed.
+4. For a feature, describe the problem and expected behavior before designing the
+ implementation.
-We recommend using `uv` for Python environment management:
+Open an issue or start a discussion before implementing a change that affects:
-```bash
-# Install uv (if not installed)
-curl -LsSf https://astral.sh/uv/install.sh | sh
+- public REST, SDK, CLI, MCP, or configuration semantics;
+- persisted data, storage schemas, VFS/AGFS paths, or encrypted file behavior;
+- asynchronous task ownership, queues, cancellation, cleanup, or result state;
+- resource import/watch behavior, session lifecycle, or memory extraction;
+- retrieval levels, directory scope, or ranking semantics;
+- tenant, account, user, or peer identity boundaries;
+- multiple owner modules or a large architectural refactor.
-# Sync dependencies and create virtual environment
-uv sync --all-extras
-source .venv/bin/activate # Linux/macOS
-# or .venv\Scripts\activate # Windows
-```
+Include the current behavior, proposed behavior, a concrete request or configuration
+example, and any compatibility impact. This lets maintainers confirm the design
+boundary before implementation work begins.
-#### Local Development & Native Rebuilds
+Use the repository's GitHub templates for [bug reports](https://github.com/volcengine/OpenViking/issues/new?template=bug_report.yml),
+[feature requests](https://github.com/volcengine/OpenViking/issues/new?template=feature_request.yml),
+and [questions](https://github.com/volcengine/OpenViking/issues/new?template=question.yml).
-OpenViking defaults to `binding-client` mode for AGFS/RAGFS, which requires pre-built native artifacts. If you modify the **RAGFS Rust binding**, the bundled **Rust CLI**, or the **C++ extensions**, or if the pre-built artifacts are not found, you need to re-compile and re-install them. Run the following command in the project root:
+## Find the Right Area
-```bash
-uv pip install -e . --force-reinstall
-```
+If you know the affected area, mention it in the issue or PR. If you are unsure,
+describe the observable behavior and use case first; a maintainer will help route it.
-This command ensures that `setup.py` is re-executed, triggering rebuilds for AGFS/RAGFS, the bundled `ov` CLI, and the C++ components.
+This map reflects sustained authorship and review activity in PRs merged from June 24
+through August 24, 2026. It is routing guidance, not exclusive code ownership; mention
+only the contacts relevant to the change.
-### 3. Configure Environment
+| Domain | Area | Representative paths or topics | Active maintainers / reviewers |
+|---|---|---|---|
+| Platform | Server, API, auth, identity, admin, tasks | `openviking/server`, `openviking/service` | `@qin-ctx` |
+| Resource | Ingestion, watch, and task pipeline | `openviking/resource` | `@qin-ctx`, `@KCHENPENGFEI` |
+| Resource | Resource parsing | `openviking/parse` | `@zihengli-bytedance`, `@KCHENPENGFEI` |
+| Memory | Session, memory extraction, and compilation | `openviking/session`, memory extraction, `ov compile` | `@chenjw`, `@heaoxiang-ai`, `@fujiajie666` |
+| Retrieval | Search and vector databases | `openviking/retrieve`, `openviking/storage/vectordb` | `@zhoujh01`, `@t0saki` |
+| Storage | RAGFS, PathLock, QueueFS, and encryption | `openviking/storage`, `openviking/pyagfs`, `openviking/crypto`, `crates/ragfs*` | `@baojun-zhang` |
+| Integration | Agent plugins and MCP | `agent-plugins`, memory plugin examples, server MCP | `@t0saki`, `@ZaynJarvis` |
+| Integration | VikingBot and agent compilation | `bot`, `ov compile` | `@yeshion23333`, `@fujiajie666` |
+| Client | SDKs, CLI, and LangChain | `sdk`, `crates/ov_cli`, `integrations/langchain` | `@zhoujh01`, `@t0saki`, `@ehz0ah` |
+| Product | Web Studio | `web-studio` | `@yufeng201`, `@ZaynJarvis` |
+| Project | Documentation, CI, and plugin releases | `docs`, `.github/workflows` | `@yufeng201`, `@ZaynJarvis` |
-Run the interactive wizard to pick providers and write `~/.openviking/ov.conf`, then
-validate the result:
+For cross-module changes or areas without a clear owner, identify the primary affected
+area first, then mention `@qin-ctx`, `@ZaynJarvis`, or `@zhoujh01`.
-```console
-openviking-server init
-openviking-server doctor
-```
+## Development Setup
-Manual `ov.conf` templates, per-provider examples, and environment variables are in the
-[Configuration guide](https://docs.openviking.ai/en/guides/01-configuration). The default
-config file is loaded automatically; set `OPENVIKING_CONFIG_FILE` only when using a
-non-default path.
+### Prerequisites
-### 4. Verify Installation
+- Python 3.10+
+- Rust 1.91.1+ for source builds, Rust bindings, and the bundled `ov` CLI
+- Go 1.22+ only for development under `sdk/go`
+- A C++17 compiler: GCC 9+ or Clang 11+
+- CMake 3.15+
-```bash
-python -c "import openviking; print(openviking.__version__)"
-```
+On Linux, install `build-essential` and, where needed, `pkg-config`. On macOS,
+install Xcode Command Line Tools. On Windows, install CMake and MinGW for local
+native builds.
-### 5. Build Rust CLI (Optional)
+### Install
-The Rust CLI (`ov`) provides a high-performance command-line client for interacting with OpenViking Server.
-
-Even if you do not plan to use `ov` directly, the Rust toolchain is still required when building OpenViking from source because packaging also builds the bundled CLI binary.
+Fork the repository, then clone your fork:
```bash
-# Build and install from source
-cargo install --path crates/ov_cli
-
-# Or install the published npm CLI package (downloads pre-built binary)
-npm i -g @openviking/cli
+git clone https://github.com/YOUR_USERNAME/OpenViking.git
+cd OpenViking
```
-After installation, run `ov --help` to see all available commands. CLI connection config goes in `~/.openviking/ovcli.conf`.
-
----
-
-## Project Structure
+We recommend using `uv`:
-```
-openviking/
-├── pyproject.toml # Python project and tooling configuration
-├── Cargo.toml # Rust workspace configuration
-├── openviking/ # Python SDK and server implementation
-│ ├── client/ # HTTP client compatibility exports
-│ ├── connector/ # Data connectors
-│ ├── core/ # Core data models and directory abstractions
-│ ├── ingest/ # Ingestion pipeline
-│ ├── integrations/ # Agent integrations
-│ ├── models/ # Embedding and VLM backends
-│ ├── parse/ # Resource parsers and detectors
-│ ├── resource/ # Resource processing and watch management
-│ ├── retrieve/ # Retrieval system
-│ ├── server/ # HTTP server
-│ ├── session/ # Session management and compression
-│ └── storage/ # Storage layer
-├── openviking_cli/ # Server bootstrap and Python CLI support
-├── bot/ # VikingBot agent framework
-├── sdk/ # Go, Python, and TypeScript client SDKs
-├── web-studio/ # Studio web frontend
-├── crates/ # Rust components
-│ ├── ov_cli/ # Rust CLI client
-│ ├── ragfs/ # Rust implementation of AGFS
-│ ├── ragfs-python/ # Python binding for RAGFS
-│ ├── ragfs-python-native/ # Native Python binding package
-│ ├── ragfs-cache-redis/ # Redis cache backend
-│ ├── ragfs-cache-mooncake/ # Mooncake cache backend
-│ ├── ragfs-cache-yuanrong/ # YuanRong cache backend
-│ └── ragfs-cache-yuanrong-sys/ # YuanRong FFI bindings
-├── src/ # C++ extension sources (Python abi3)
-├── third_party/ # Native third-party dependencies
-├── examples/ # Usage and integration examples
-├── benchmark/ # Benchmark suites
-├── tests/ # Python and integration test suites
-├── deploy/ # Deployment assets
-├── docker/ # Docker build files
-├── npm/ # npm CLI package
-├── scripts/ # Development and maintenance scripts
-└── docs/ # English, Chinese, and Japanese documentation
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync --all-extras
```
----
-
-## Code Style
-
-We use the following tools to maintain code consistency:
-
-| Tool | Purpose | Config |
-|------|---------|--------|
-| **Ruff** | Linting, Formatting, Import sorting | `pyproject.toml` |
-| **mypy** | Type checking | `pyproject.toml` |
-
-### Running Checks
+Verify the environment:
```bash
-# Format code
-ruff format openviking/
-
-# Lint
-ruff check openviking/
-
-# Type check
-mypy openviking/
+uv run python -c "import openviking; print(openviking.__version__)"
```
-### Style Guidelines
-
-1. **Line width**: 100 characters
-2. **Indentation**: 4 spaces
-3. **Strings**: Prefer double quotes
-4. **Type hints**: Encouraged but not required
-5. **Docstrings**: Required for public APIs (1-2 lines max)
-
----
-
-## Testing
-
-### Running Tests
+To configure a local server, run:
```bash
-# 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/client/test_http_client_config.py
-
-# Run specific test
-pytest tests/client/test_http_client_config.py
-
-# Run by keyword
-pytest -k "search" -v
-
-# Run with coverage
-pytest --cov=openviking --cov-report=term-missing
+uv run openviking-server init
+uv run openviking-server doctor
```
-### Writing Tests
-
-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/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://")
-```
-
-Common fixtures are defined in `tests/conftest.py`, including the initialized `service`, `request_context`, `temp_dir`, and sample files.
-
----
-
-## Maintainer Routing and Contribution Entry
-
-### Contributor-Facing Module Map
-
-If you are not sure where your question, issue, or PR belongs, start with this table:
-
-| Domain | Area | Primary Contact |
-|--------|------|-----------------|
-| 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` |
+Configuration details and provider examples are in the
+[configuration guide](https://docs.openviking.ai/en/guides/01-configuration).
-If the area is still unclear, mention one of the cross-module maintainers listed below.
+If you modify the RAGFS Rust binding, bundled Rust CLI, or C++ extensions, rebuild
+the native components:
-### Maintainer Routing Map
-
-Use this table when routing issues, PRs, or design questions to a more specific owner:
-
-| Domain | Subarea | Representative Paths or Topics | Primary Contact | Backup / Cross-Module |
-|--------|---------|--------------------------------|-----------------|-----------------------|
-| Integration | Bot Runtime | `bot/vikingbot`, `bot/bridge`, deployment scripts, bot docs | `@yeshion23333` | `@chenjw` |
-| Integration | OpenClaw Plugin | `examples/openclaw-plugin`, installation, remote mode, compatibility | `@Mijamind719`, `@wlff123` | `@LinQiang391` |
-| Platform | Server & Multi-tenant | `openviking/server`, `openviking/service`, auth, identity, admin, tenant boundary | `@qin-ctx` | `@MaojiaSheng` |
-| Platform | Resource & Session Lifecycle | `openviking/resource`, `openviking/session`, resource ingestion, session lifecycle | `@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`, intent analysis, hierarchical retrieval, directory semantics | `@zhoujh01` | `@qin-ctx` |
-| Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`, `openviking/pyagfs`, filesystem behavior, path semantics | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` |
-| Storage & Security | Encryption & Data Safety | `openviking/crypto`, file encryption, storage safety | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` |
-
-For areas without a stable owner yet, cross-module maintainers will help route the request first.
-
-### Cross-Module Maintainers
-
-- `@MaojiaSheng`
-- `@qin-ctx`
-- `@zhoujh01`
-
-Cross-module maintainers help with issue routing, cross-cutting design questions, and fallback review support.
-
-### How to Ask for Help
-
-- If you already know the affected module, mention it in the issue or PR description.
-- If you are unsure about the module, describe the use case and affected behavior first.
-- If you want to work on an issue, leave a comment before starting, especially for cross-module changes.
-- If your PR spans multiple areas, call out the primary affected domain in the description.
+```bash
+uv pip install -e . --force-reinstall
+```
-### Contribution Entry Labels
+Component-specific SDKs, integrations, plugins, and benchmarks may have additional
+setup instructions in their local README or package manifest.
-Issue templates already classify reports such as `bug`, `enhancement`, and `question`. Maintainers may also use the following labels to make contribution entry clearer:
+## Making a Change
-| Label | Meaning |
-|-------|---------|
-| `good first issue` | Newcomer-friendly work with clear scope and acceptance criteria |
-| `help wanted` | Tasks that benefit from contributors who already know the codebase or review style |
-| `needs-design` | Work that needs maintainer clarification before implementation |
-| `needs-review` | Pull requests waiting for the first review round |
+### Ownership and Design
-### Contributor Growth Path
+- Put behavior in its owning module. Higher layers should transport or consume the
+ result, not reimplement the same rule.
+- Convert external compatibility shapes into one canonical domain model at the
+ boundary. Keep inner business logic free of input-shape guessing.
+- Preserve meaningful server, network, timeout, authentication, and conflict errors
+ at client-facing boundaries.
+- Keep task state causally tied to the task that produced it. Do not infer completion
+ from global queue state or an unrelated callback.
+- Prefer one authoritative source for every value and rule.
-The project uses a practical contribution path so contributors can see what “next step” looks like:
+If a local edge case starts changing task boundaries, public semantics, or the
+overall architecture, stop and return to the design discussion instead of adding
+special branches throughout the main path.
-| Stage | Typical Signals | Common Next Step |
-|-------|------------------|------------------|
-| New Contributor | First issue or first PR, often docs, tests, or scoped fixes | Start with `good first issue` items and get familiar with local workflow |
-| Active Contributor | One or more merged contributions | Pick up `help wanted` work in an area you already touched |
-| Module Contributor | Repeated contributions in the same subarea | Help with triage, reproduction, docs, or review comments in that area |
-| Backup Reviewer Candidate | Stable contribution record in one subarea | Help with first-pass review, routing, and contributor support |
+### Code Style
-## Contribution Workflow
+Python uses Ruff for formatting and linting, and mypy for type checking. The
+configured line width is 100 characters.
-### 1. Create a Branch
+Run checks on the paths you changed:
```bash
-git checkout main
-git pull origin main
-git checkout -b feature/your-feature-name
+uv run ruff format <changed-paths>
+uv run ruff check <changed-paths>
+uv run mypy <changed-paths>
```
-Branch naming conventions:
-- `feature/xxx` - New features
-- `fix/xxx` - Bug fixes
-- `docs/xxx` - Documentation updates
-- `refactor/xxx` - Code refactoring
+Public APIs should have short, useful docstrings. Prefer clear names and direct
+control flow over comments that restate the code.
-### 2. Make Changes
+For Rust, Go, TypeScript, documentation, and plugin changes, use the formatter,
+lint, type-check, and test commands defined by that component.
-- Follow code style guidelines
-- Add tests for new functionality
-- Update documentation as needed
+### Tests
-### 3. Commit Changes
+Validate the smallest meaningful public contract and major failure boundary affected
+by the change.
-```bash
-git add .
-git commit -m "feat: add new parser for xlsx files"
-```
+- Prefer updating an existing high-value contract test.
+- Do not add a new unit test or test file by default.
+- Do not test private helper existence, mock call order, simple field forwarding, or
+ framework behavior unless it protects a lasting public contract.
+- A small, clear fix does not automatically require a new test, but its validation
+ must be explained.
+- Put temporary reproduction, diagnostic, stress, and validation scripts in
+ `test_scripts/`, not in source, benchmark, or maintenance script directories.
-### 4. Push and Create PR
+Run the relevant focused tests, for example:
```bash
-git push origin feature/your-feature-name
-```
-
-Then create a Pull Request on GitHub.
-
----
-
-## Commit Convention
-
-We follow [Conventional Commits](https://www.conventionalcommits.org/):
-
+uv run pytest tests/client/test_http_client_config.py
+uv run pytest tests/server/ -k "search"
```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-### Types
-| Type | Description |
-|------|-------------|
-| `feat` | New feature |
-| `fix` | Bug fix |
-| `docs` | Documentation |
-| `style` | Code style (no logic change) |
-| `refactor` | Code refactoring |
-| `perf` | Performance improvement |
-| `test` | Tests |
-| `chore` | Build/tooling |
-
-### Examples
+Run the full Python suite only when the scope and risk justify it:
```bash
-# New feature
-git commit -m "feat(parser): add support for xlsx files"
-
-# Bug fix
-git commit -m "fix(retrieval): fix score calculation in rerank"
-
-# Documentation
-git commit -m "docs: update quick start guide"
-
-# Refactoring
-git commit -m "refactor(storage): simplify interface methods"
+uv run pytest
```
----
-
-## Pull Request Guidelines
-
-### PR Title
-
-Use the same format as commit messages.
-
-### PR Description Template
+## Submitting a Pull Request
-```markdown
-## Summary
+Create a branch from the latest `main`, make the focused change, and open a PR
+against the appropriate repository branch.
-Brief description of the changes and their purpose.
+Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
+and PR titles:
-## Type of Change
-
-- [ ] New feature (feat)
-- [ ] Bug fix (fix)
-- [ ] Documentation (docs)
-- [ ] Refactoring (refactor)
-- [ ] Other
-
-## Testing
-
-Describe how to test these changes:
-- [ ] Unit tests pass
-- [ ] Manual testing completed
-
-## Related Issues
-
-- Fixes #123
-- Related to #456
-
-## Checklist
-
-- [ ] Code follows project style guidelines
-- [ ] Tests added for new functionality
-- [ ] Documentation updated (if needed)
-- [ ] All tests pass
+```text
+feat(parser): support xlsx resources
+fix(retrieval): preserve rerank score order
+docs: clarify server configuration
+refactor(storage): remove duplicate path normalization
```
----
-
-## CI/CD Workflows
-
-We use **GitHub Actions** for Continuous Integration and Continuous Deployment. Our workflows are designed to be modular and tiered.
-
-### 1. Automatic Workflows
-
-| Event | Workflow | Description |
-|-------|----------|-------------|
-| **Pull Request** | `pr.yml` | Runs **Lint** (Ruff, Mypy) and **Test Lite** (Integration tests on Linux + Python 3.10). Provides fast feedback for contributors. (Displayed as **01. Pull Request Checks**) |
-| **Push to Main** | `ci.yml` | Runs **Test Full** (All OS: Linux/Win/Mac, All Py versions: 3.10-3.14) and **CodeQL** (Security scan). Ensures main branch stability. (Displayed as **02. Main Branch Checks**) |
-| **Release Published** | `release.yml` | Triggered when you create a Release on GitHub. Automatically builds source distribution and wheels, determines version from Git Tag, and publishes to **PyPI**. (Displayed as **03. Release**) |
-| **Weekly Cron** | `schedule.yml` | Runs **CodeQL** security scan every Sunday. (Displayed as **04. Weekly Security Scan**) |
-
-Other repository workflows also exist for PR review automation, Docker image builds, and Rust CLI packaging.
-
-### 2. Manual Trigger Workflows
-
-Maintainers can manually trigger the following workflows from the "Actions" tab to perform specific tasks or debug issues.
-
-#### A. Test Suite (Lite) (`12. _Test Suite (Lite)`)
-Runs fast integration tests, supports custom matrix configuration.
+Complete the repository's PR template. A useful description states:
-* **Inputs**:
- * `os_json`: JSON string array of OS to run on (e.g., `["ubuntu-24.04"]`).
- * `python_json`: JSON string array of Python versions (e.g., `["3.10"]`).
+- the observable behavior before and after the change;
+- the root cause and real execution path for a bug fix;
+- the affected entrypoint and owner module;
+- compatibility or migration impact, if any;
+- the exact validation commands that were run;
+- whether the issue was reproduced or only inferred from the code.
-#### B. Test Suite (Full) (`13. _Test Suite (Full)`)
-Runs the full test suite on all supported platforms (Linux/Mac/Win) and Python versions (3.10-3.14). Supports custom matrix configuration when triggered manually.
+Mark the **Human Involvement** field accurately. AI-assisted contributions are welcome,
+but the author remains responsible for the change and must be able to explain how it
+interacts with the rest of the system.
-* **Inputs**:
- * `os_json`: List of OS to run on (Default: `["ubuntu-24.04", "macos-14", "windows-latest"]`).
- * `python_json`: List of Python versions (Default: `["3.10", "3.11", "3.12", "3.13", "3.14"]`).
+Before submitting:
-#### C. Security Scan (`14. _CodeQL Scan`)
-Runs CodeQL security analysis. No arguments required.
+- Review the complete diff and remove unrelated or generated changes.
+- Confirm that replaced helpers, branches, mocks, and comments are gone.
+- Update relevant documentation when public behavior changes.
+- Report skipped checks and the concrete reason; do not claim tests that were not run.
-#### D. Build Distribution (`15. _Build Distribution`)
-Builds Python wheel packages only, does not publish.
-
-* **Inputs**:
- * `os_json`: List of OS to build on (Default: `["ubuntu-24.04", "ubuntu-24.04-arm", "macos-14", "macos-15-intel", "windows-latest"]`).
- * `python_json`: List of Python versions (Default: `["3.10", "3.11", "3.12", "3.13", "3.14"]`).
- * `build_sdist`: Whether to build source distribution (Default: `true`).
- * `build_wheels`: Whether to build wheel distribution (Default: `true`).
-
-#### E. Publish Distribution (`16. _Publish Distribution`)
-Publishes built packages (requires build Run ID) to PyPI.
-
-* **Inputs**:
- * `target`: Select publish target (`testpypi`, `pypi`, `both`).
- * `build_run_id`: Build Workflow Run ID (Required, get it from the Build run URL).
-
-#### F. Manual Release (`03. Release`)
-One-stop build and publish (includes build and publish steps).
-
-> **Version Numbering & Tag Convention**:
-> This project uses `setuptools_scm` to automatically extract version numbers from Git Tags.
-> * **Tag Naming Convention**: Must follow the `vX.Y.Z` format (e.g., `v0.1.0`, `v1.2.3`). Tags must be compliant with Semantic Versioning.
-> * **Release Build**: When a Release event is triggered, the version number directly corresponds to the Git Tag (e.g., `v0.1.0` -> `0.1.0`).
-> * **Manual/Non-Tag Build**: The version number will include the commit count since the last Tag (e.g., `0.1.1.dev3`).
-> * **Confirm Version**: After the publish job completes, you can see the published version directly in the **Notifications** area at the top of the Workflow **Summary** page (e.g., `Successfully published to PyPI with version: 0.1.8`). You can also verify it in the logs or the **Artifacts** filenames.
-
-* **Inputs**:
- * `target`: Select publish target.
- * `none`: Build artifacts only (no publish). Used for verifying build capability.
- * `testpypi`: Publish to TestPyPI. Used for Beta testing.
- * `pypi`: Publish to official PyPI.
- * `both`: Publish to both.
- * `os_json`: Build platforms (Default includes all).
- * `python_json`: Python versions (Default includes all).
- * `build_sdist`: Whether to build source distribution (Default: `true`).
- * `build_wheels`: Whether to build wheel distribution (Default: `true`).
-
-> **Publishing Notes**:
-> * **Test First**: It is strongly recommended to publish to **TestPyPI** for verification before publishing to official PyPI. Note that PyPI and TestPyPI are completely independent environments, and accounts and package data are not shared.
-> * **No Overwrites**: Neither PyPI nor TestPyPI allow overwriting existing packages with the same name and version. If you need to republish, you must upgrade the version number (e.g., tag a new version or generate a new dev version). If you try to publish an existing version, the workflow will fail.
-
----
-
-## Issue Guidelines
-
-### Bug Reports
-
-Please provide:
-
-1. **Environment**
- - Python version
- - OpenViking version
- - Operating system
-
-2. **Steps to Reproduce**
- - Detailed steps
- - Code snippets
-
-3. **Expected vs Actual Behavior**
-
-4. **Error Logs** (if any)
-
-### Feature Requests
-
-Please describe:
-
-1. **Problem**: What problem are you trying to solve?
-2. **Solution**: What solution do you propose?
-3. **Alternatives**: Have you considered other approaches?
-
----
+CI runs checks based on the affected paths. A green CI result is required, but it
+does not replace author validation or maintainer review.
## Documentation
-Documentation is in Markdown format under `docs/`:
-
-- `docs/en/` - English documentation
-- `docs/zh/` - Chinese documentation
-
-### Documentation Guidelines
-
-1. Code examples must be runnable
-2. Keep documentation in sync with code
-3. Use clear, concise language
-
----
-
-## Code of Conduct
-
-By participating in this project, you agree to:
-
-1. **Be respectful**: Maintain a friendly and professional attitude
-2. **Be inclusive**: Welcome contributors from all backgrounds
-3. **Be constructive**: Provide helpful feedback
-4. **Stay focused**: Keep discussions technical
-
----
-
-## Getting Help
-
-If you have questions:
-
-- [GitHub Issues](https://github.com/volcengine/openviking/issues)
-- [Discussions](https://github.com/volcengine/openviking/discussions)
+Project documentation lives under `docs/en/` and `docs/zh/`. Keep examples runnable,
+use concise language, and update both languages when the changed documentation has a
+corresponding translation.
----
+## Community
-Thank you for contributing!
+Be respectful, inclusive, constructive, and focused on the technical discussion.
+Use [GitHub Discussions](https://github.com/volcengine/OpenViking/discussions) for
+open-ended design or usage discussions and [GitHub Issues](https://github.com/volcengine/OpenViking/issues)
+for actionable bugs and feature requests.
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index 528fd30d0..4b964266d 100644
--- a/CONTRIBUTING_CN.md
+++ b/CONTRIBUTING_CN.md
@@ -1,601 +1,238 @@
-# 贡献指南
+# 为 OpenViking 做贡献
-感谢你对 OpenViking 感兴趣!我们欢迎各种形式的贡献:
+[English](CONTRIBUTING.md) / 中文 / [日本語](CONTRIBUTING_JA.md)
-- 报告 Bug
-- 提交功能请求
-- 改进文档
-- 贡献代码
+感谢你参与 OpenViking。本指南旨在帮助贡献者提交清晰、聚焦且便于评审的改动。
----
+我们欢迎 Bug 报告、功能请求、文档改进和代码贡献。
-## 开发环境设置
+## 我们重视什么
-### 前置要求
+OpenViking 重视聚焦且经过充分理解的改动。无论是否使用 AI 工具,贡献者都要对
+理解、解释和验证自己的改动负责。
-- **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
+- 一个 PR 只解决一个内聚的问题,不要混入无关清理或重构。
+- 复用现有规则的 Owner,不要引入平行机制。
+- 避免猜测式 Fallback、Flag、状态字段和抽象。
+- 删除被新实现替代的代码、测试和兼容路径。
+- 当必要结构能让职责、生命周期或失败处理更清楚时,应当保留它。
-#### 支持的平台 (预编译 Wheel 包)
+### 评审优先级
-OpenViking 为以下环境提供预编译的 **Wheel** 包,安装时无需本地编译:
+维护者精力有限,因此会优先查看聚焦的 PR:
-- **Windows**: x86_64
-- **macOS**: x86_64, arm64 (Apple Silicon)
-- **Linux**: x86_64, arm64 (manylinux)
+- **改动不超过 100 行**的 PR,通常能得到更及时的查看。
+- **改动不超过 200 行**的 PR,会比更大的 PR 优先查看。
-对于其他平台(如 FreeBSD 等),安装时 `pip` 将会自动从源码进行编译。请确保已安装上述[前置要求](#前置要求)中的工具。
+这只是评审优先级,不是硬性限制或响应时间承诺。改动行数按手写源码、测试和文档的
+新增行与删除行之和计算;生成文件、第三方代码和锁文件不计入规模判断。
-### 1. Fork 并克隆
+不要为了控制行数省略必要的测试或文档。只有当拆分后的每个 PR 都能独立理解且保持
+正确时,才拆分大改动。PR 小不代表可以降低正确性、设计质量或兼容性要求。
-```bash
-git clone https://github.com/YOUR_USERNAME/openviking.git
-cd openviking
-```
+## 开始之前
-### 2. 安装依赖
+1. 全局搜索已有 Issue、PR 和代码,确认是否已经存在相同的行为或领域规则。
+2. 修复 Bug 时,尽量通过真实生产入口复现问题。
+3. 确认 Owner 模块,并追踪相关值或状态在哪里创建、规范化、存储和消费。
+4. 开发功能时,先说明要解决的问题和预期行为,再设计实现。
-我们推荐使用 `uv` 进行 Python 环境管理:
+以下改动应在实现前先提交 Issue 或发起讨论:
-```bash
-# 安装 uv (如果尚未安装)
-curl -LsSf https://astral.sh/uv/install.sh | sh
+- 公开的 REST、SDK、CLI、MCP 或配置语义;
+- 持久化数据、存储 Schema、VFS/AGFS 路径或加密文件行为;
+- 异步任务归属、队列、取消、清理或结果状态;
+- 资源导入与监听、Session 生命周期或记忆抽取;
+- 检索 Level、目录范围或排序语义;
+- Tenant、Account、User 或 Peer 身份边界;
+- 涉及多个 Owner 模块或大型架构重构。
-# 同步依赖并创建虚拟环境
-uv sync --all-extras
-source .venv/bin/activate # Linux/macOS
-# 或者 .venv\Scripts\activate # Windows
-```
+讨论中请给出当前行为、目标行为、具体请求或配置示例,以及兼容性影响。这样维护者
+可以在开始实现前确认设计边界。
-#### 本地开发与原生组件重建
+请使用仓库提供的 GitHub 模板提交 [Bug 报告](https://github.com/volcengine/OpenViking/issues/new?template=bug_report.yml)、
+[功能请求](https://github.com/volcengine/OpenViking/issues/new?template=feature_request.yml)和
+[使用问题](https://github.com/volcengine/OpenViking/issues/new?template=question.yml)。
-OpenViking 默认使用 `binding-client` 模式,这依赖预先构建的原生产物。如果你修改了 **AGFS (Go)** 代码、内置的 **Rust CLI**,或 **C++ 扩展**,或者这些预编译产物未找到,你需要重新编译并安装它们,以使更改在本地环境中生效。在项目根目录下运行以下命令:
+## 找到正确的模块
-```bash
-uv pip install -e . --force-reinstall
-```
+如果已知受影响模块,请在 Issue 或 PR 中注明。如果不确定,先描述可观察行为和使用场景,
+维护者会协助路由。
-该命令会强制重新执行 `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"
- }
-}
-```
+这张表根据 2026 年 6 月 24 日至 8 月 24 日已合并 PR 中持续的提交和评审活动整理。
+它用于协助路由,不代表排他性的代码所有权;只需 @ 与改动直接相关的联系人。
-设置环境变量:
+| 领域 | 模块 | 代表路径或主题 | 近期活跃维护者 / 评审者 |
+|---|---|---|---|
+| Platform | Server、API、Auth、Identity、Admin、Task | `openviking/server`、`openviking/service` | `@qin-ctx` |
+| Resource | 导入、Watch 与任务流水线 | `openviking/resource` | `@qin-ctx`、`@KCHENPENGFEI` |
+| Resource | 资源解析 | `openviking/parse` | `@zihengli-bytedance`、`@KCHENPENGFEI` |
+| Memory | Session、记忆抽取与编译 | `openviking/session`、记忆抽取、`ov compile` | `@chenjw`、`@heaoxiang-ai`、`@fujiajie666` |
+| Retrieval | Search 与 VectorDB | `openviking/retrieve`、`openviking/storage/vectordb` | `@zhoujh01`、`@t0saki` |
+| Storage | RAGFS、PathLock、QueueFS 与加密 | `openviking/storage`、`openviking/pyagfs`、`openviking/crypto`、`crates/ragfs*` | `@baojun-zhang` |
+| Integration | Agent Plugin 与 MCP | `agent-plugins`、记忆插件示例、Server MCP | `@t0saki`、`@ZaynJarvis` |
+| Integration | VikingBot 与 Agent 编译 | `bot`、`ov compile` | `@yeshion23333`、`@fujiajie666` |
+| Client | SDK、CLI 与 LangChain | `sdk`、`crates/ov_cli`、`integrations/langchain` | `@zhoujh01`、`@t0saki`、`@ehz0ah` |
+| Product | Web Studio | `web-studio` | `@yufeng201`、`@ZaynJarvis` |
+| Project | 文档、CI 与 Plugin 发布 | `docs`、`.github/workflows` | `@yufeng201`、`@ZaynJarvis` |
-```bash
-export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
-```
+跨模块改动或 Owner 不明确时,请先确认主要影响域,再 @ `@qin-ctx`、`@ZaynJarvis` 或 `@zhoujh01`。
-### 4. 验证安装
+## 开发环境
-```bash
-python -c "import openviking; print(openviking.__version__)"
-```
+### 前置要求
-### 5. 构建 Rust CLI(可选)
+- Python 3.10+
+- 从源码构建、开发 Rust Binding 或内置 `ov` CLI 时需要 Rust 1.91.1+
+- 仅开发 `sdk/go` 时需要 Go 1.22+
+- 支持 C++17 的编译器:GCC 9+ 或 Clang 11+
+- CMake 3.15+
-Rust CLI (`ov`) 提供高性能的命令行客户端,用于连接 OpenViking Server 进行操作。
+Linux 请安装 `build-essential`,部分环境还需要 `pkg-config`。macOS 请安装 Xcode
+Command Line Tools。Windows 本地原生构建请安装 CMake 和 MinGW。
-即使你不打算直接使用 `ov`,只要走 OpenViking 的源码构建流程,Rust 工具链仍然是必需的,因为打包过程也会构建内置 CLI 二进制。
+### 安装
-```bash
-# 从源码编译安装
-cargo install --path crates/ov_cli
+Fork 仓库,然后克隆自己的 Fork:
-# 或者安装已发布的 npm CLI 包(下载预编译二进制)
-npm i -g @openviking/cli
+```bash
+git clone https://github.com/YOUR_USERNAME/OpenViking.git
+cd OpenViking
```
-安装后通过 `ov --help` 查看所有可用命令。CLI 连接配置见 `~/.openviking/ovcli.conf`。
-
----
-
-## 项目结构
+推荐使用 `uv`:
-```
-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/ # 中文文档
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync --all-extras
```
----
-
-## 代码风格
-
-我们使用以下工具来保持代码一致性:
-
-| 工具 | 用途 | 配置 |
-|------|---------|--------|
-| **Ruff** | Linting, 格式化, 导入排序 | `pyproject.toml` |
-| **mypy** | 类型检查 | `pyproject.toml` |
-
-### 运行检查
+验证环境:
```bash
-# 格式化代码
-ruff format openviking/
-
-# Lint 检查
-ruff check openviking/
-
-# 类型检查
-mypy openviking/
+uv run python -c "import openviking; print(openviking.__version__)"
```
-### 风格指南
-
-1. **行宽**:100 字符
-2. **缩进**:4 个空格
-3. **字符串**:推荐使用双引号
-4. **类型提示**:鼓励但不强制
-5. **Docstrings**:公共 API 必须包含(最多 1-2 行)
-
----
-
-## 测试
-
-### 运行测试
+配置本地 Server:
```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
+uv run openviking-server init
+uv run openviking-server doctor
```
-### 编写测试
-
-测试按模块组织在 `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` |
-
-如果还是无法判断归属,可以直接 @ 下方的跨模块维护支持成员。
+配置说明和 Provider 示例见[配置指南](https://docs.openviking.ai/zh/guides/01-configuration)。
-### 面向维护者的路由表
+修改 RAGFS Rust Binding、内置 Rust CLI 或 C++ 扩展后,需要重新构建原生组件:
-当需要把 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 涉及多个模块,请在描述中标明主要影响域。
+```bash
+uv pip install -e . --force-reinstall
+```
-### 贡献入口标签
+SDK、Integration、Plugin 和 Benchmark 可能有额外要求,请查看对应目录中的 README 或
+包配置。
-Issue 模板已经会对 `bug`、`enhancement`、`question` 等问题类型做基础分类。为了让贡献入口更清晰,维护者还可能补充以下标签:
+## 修改代码
-| 标签 | 含义 |
-|------|------|
-| `good first issue` | 适合新贡献者上手,范围清晰且验收标准明确 |
-| `help wanted` | 更适合已经熟悉仓库或 review 风格的贡献者参与 |
-| `needs-design` | 实现前需要维护者先澄清设计边界 |
-| `needs-review` | 正在等待首轮 review 的 PR |
+### 职责与设计
-### 贡献成长路径
+- 行为应放在所属模块中。上层只负责传输或消费结果,不要重复实现相同规则。
+- 在边界把外部兼容表达转换为唯一的规范领域模型,内层业务逻辑不应猜测输入形态。
+- 面向客户端的边界应保留有意义的 Server、Network、Timeout、Auth 和 Conflict 错误。
+- 任务状态必须与产生它的任务保持因果关联,不能通过全局队列状态或无关回调推断完成。
+- 每个值和规则只保留一个权威来源。
-我们希望贡献成长路径足够实际,让贡献者能清楚看到下一步可以怎么参与:
+如果局部边缘 Case 开始改变任务边界、公开语义或整体架构,应暂停实现并回到设计讨论,
+不要在主流程中不断增加特殊分支。
-| 阶段 | 常见信号 | 下一步建议 |
-|------|----------|------------|
-| 新贡献者 | 第一次提 issue 或 PR,通常从文档、测试或小范围修复开始 | 从 `good first issue` 入手,熟悉本地开发和提交流程 |
-| 活跃贡献者 | 已经有一个或多个合入贡献 | 在自己熟悉的模块下开始认领 `help wanted` |
-| 模块贡献者 | 在同一子域持续贡献 | 开始参与该模块的 issue 分流、问题复现、文档补充或 review 建议 |
-| 备援 Reviewer 候选 | 在某个子域形成稳定贡献记录 | 协助首轮 review、问题路由和贡献者支持 |
+### 代码风格
-## 贡献流程
+Python 使用 Ruff 进行格式化和 Lint,使用 mypy 进行类型检查,配置行宽为 100 字符。
-### 1. 创建分支
+对改动路径运行检查:
```bash
-git checkout main
-git pull origin main
-git checkout -b feature/your-feature-name
+uv run ruff format <changed-paths>
+uv run ruff check <changed-paths>
+uv run mypy <changed-paths>
```
-分支命名规范:
-- `feature/xxx` - 新功能
-- `fix/xxx` - Bug 修复
-- `docs/xxx` - 文档更新
-- `refactor/xxx` - 代码重构
+公开 API 应包含简短且有用的 Docstring。优先使用清晰命名和直接控制流,不要用注释
+重复解释代码本身。
-### 2. 修改代码
+Rust、Go、TypeScript、文档和 Plugin 改动,请使用对应组件定义的格式化、Lint、类型检查
+和测试命令。
-- 遵循代码风格指南
-- 为新功能添加测试
-- 根据需要更新文档
+### 测试
-### 3. 提交更改
+验证受影响的最小有效公开契约和主要失败边界。
-```bash
-git add .
-git commit -m "feat: add new parser for xlsx files"
-```
+- 优先修改已有的高价值契约测试。
+- 默认不要新增单元测试或测试文件。
+- 不要测试私有 Helper 是否存在、Mock 调用顺序、简单字段透传或框架行为,除非它保护
+ 长期公开契约。
+- 小而明确的修复不必自动新增测试,但必须说明验证方式。
+- 临时复现、诊断、压测和验证脚本统一放在 `test_scripts/`,不要放入源码、Benchmark
+ 或维护脚本目录。
-### 4. 推送并创建 PR
+运行相关的聚焦测试,例如:
```bash
-git push origin feature/your-feature-name
+uv run pytest tests/client/test_http_client_config.py
+uv run pytest tests/server/ -k "search"
```
-然后在 GitHub 上创建一个 Pull Request。
-
----
-
-## 提交规范
-
-我们遵循 [Conventional Commits](https://www.conventionalcommits.org/):
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-### 类型
-
-| 类型 | 描述 |
-|------|-------------|
-| `feat` | 新功能 |
-| `fix` | Bug 修复 |
-| `docs` | 文档 |
-| `style` | 代码风格(不影响逻辑) |
-| `refactor` | 代码重构 |
-| `perf` | 性能优化 |
-| `test` | 测试 |
-| `chore` | 构建/工具 |
-
-### 示例
+只有改动范围和风险需要时才运行完整 Python 测试:
```bash
-# 新功能
-git commit -m "feat(parser): add support for xlsx files"
-
-# Bug 修复
-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"
+uv run pytest
```
----
-
-## Pull Request 指南
-
-### PR 标题
-
-使用与提交消息相同的格式。
-
-### PR 描述模板
-
-```markdown
-## Summary
+## 提交 Pull Request
-简要描述更改及其目的。
+基于最新的 `main` 创建分支,完成聚焦改动后向 `main` 提交 PR。
-## Type of Change
+Commit Message 和 PR 标题使用 [Conventional Commits](https://www.conventionalcommits.org/):
-- [ ] New feature (feat)
-- [ ] Bug fix (fix)
-- [ ] Documentation (docs)
-- [ ] Refactoring (refactor)
-- [ ] Other
-
-## Testing
-
-描述如何测试这些更改:
-- [ ] Unit tests pass
-- [ ] Manual testing completed
-
-## Related Issues
-
-- Fixes #123
-- Related to #456
-
-## Checklist
-
-- [ ] Code follows project style guidelines
-- [ ] Tests added for new functionality
-- [ ] Documentation updated (if needed)
-- [ ] All tests pass
+```text
+feat(parser): support xlsx resources
+fix(retrieval): preserve rerank score order
+docs: clarify server configuration
+refactor(storage): remove duplicate path normalization
```
----
-
-## CI/CD 工作流
-
-我们使用 **GitHub Actions** 进行持续集成和持续部署。我们的工作流设计为模块化和分层的。
-
-### 1. 自动工作流
-
-| 事件 | 工作流 | 描述 |
-|-------|----------|-------------|
-| **Pull Request** | `pr.yml` | 运行 **Lint** (Ruff, Mypy) 和 **Test Lite** (Linux + Python 3.10 上的集成测试)。为贡献者提供快速反馈。(显示为 **01. Pull Request Checks**) |
-| **Push to Main** | `ci.yml` | 运行 **Test Full** (所有操作系统:Linux/Win/Mac,所有 Py版本:3.10-3.14) 和 **CodeQL** (安全扫描)。确保主分支稳定性。(显示为 **02. Main Branch Checks**) |
-| **Release Published** | `release.yml` | 当您在 GitHub 上创建 Release 时触发。自动构建源码包和 wheel 包,基于 Git Tag 确定版本号,并发布到 **PyPI**。(显示为 **03. Release**) |
-| **Weekly Cron** | `schedule.yml` | 每周日运行 **CodeQL** 安全扫描。(显示为 **04. Weekly Security Scan**) |
-
-仓库中另外还有用于 PR review 自动化、Docker 镜像构建和 Rust CLI 打包的工作流。
-
-### 2. 手动触发工作流
-
-维护者可以从 "Actions" 选项卡手动触发以下工作流,以执行特定任务或调试问题。
-
-#### A. 代码检查 (`11. _Lint Checks`)
-运行代码风格检查 (Ruff) 和类型检查 (Mypy) 。无需参数。
-
-#### B. 简易测试 (`12. _Test Suite (Lite)`)
-运行快速集成测试,支持自定义矩阵配置。
+完整填写仓库的 PR 模板。有效的 PR 描述应说明:
-* **Inputs**:
- * `os_json`: 操作系统列表的 JSON 字符串数组 (例如 `["ubuntu-24.04"]`)。
- * `python_json`: Python 版本列表的 JSON 字符串数组 (例如 `["3.10"]`)。
+- 改动前后的可观察行为;
+- Bug 的根因和真实执行路径;
+- 受影响的入口和 Owner 模块;
+- 兼容性或迁移影响;
+- 实际执行的验证命令;
+- 问题已经复现,还是仅根据代码推断。
-#### C. 完整测试 (`13. _Test Suite (Full)`)
-在所有支持的平台 (Linux/Mac/Win) 和 Python 版本 (3.10-3.14) 上运行完整的测试套件。手动触发时支持自定义矩阵配置。
+请准确选择 Human Involvement。项目接受 AI 辅助贡献,但作者仍对改动负责,并且必须
+能解释它与系统其他部分如何交互。
-* **Inputs**:
- * `os_json`: 操作系统列表 (默认: `["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 安全分析。无需参数。
+- 完整检查 Diff,删除无关或意外生成的改动。
+- 确认被替代的 Helper、分支、Mock 和注释已经删除。
+- 公开行为变化时更新相关文档。
+- 如实说明未运行的检查及具体原因,不要声称执行了实际未运行的测试。
-#### E. 构建发行版 (`15. _Build Distribution`)
-仅构建 Python wheel 包,不发布。
-
-* **Inputs**:
- * `os_json`: 操作系统列表 (默认: `["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`)
-将已构建的包(需要提供构建运行 ID)发布到 PyPI。
-
-* **Inputs**:
- * `target`: 选择发布目标 (`testpypi`, `pypi`, `both`)。
- * `build_run_id`: 构建 Workflow 的 Run ID (必需,从构建运行的 URL 中获取)。
-
-#### G. 手动发布 (`03. Release`)
-一站式构建并发布(包含构建和发布步骤)。
-
-> **版本号与 Tag 规范**:
-> 本项目使用 `setuptools_scm` 自动从 Git Tag 提取版本号。
-> * **Tag 命名规范**:必须遵循 `vX.Y.Z` 格式(例如 `v0.1.0`, `v1.2.3`)。Tag 必须是符合语义化版本规范的。
-> * **Release 构建**:当触发 Release 事件时,版本号直接对应 Git Tag(例如 `v0.1.0` -> `0.1.0`)。
-> * **手动构建/非 Tag 构建**:版本号会包含距离上一个 Tag 的提交次数(例如 `0.1.1.dev3`)。
-> * **确认版本号**:发布任务完成后,您可以在 Workflow 运行详情页的 **Summary** 页面顶部(**Notifications** 区域)直接看到发布的版本号(例如 `Successfully published to PyPI with version: 0.1.8`)。您也可以在日志或 **Artifacts** 产物文件名中确认。
-
-* **Inputs**:
- * `target`: 选择发布目标。
- * `none`: 仅构建工件(不发布)。用于验证构建能力。
- * `testpypi`: 发布到 TestPyPI。用于 Beta 测试。
- * `pypi`: 发布到官方 PyPI。
- * `both`: 发布到两者。
- * `os_json`: 构建平台 (默认包含所有)。
- * `python_json`: Python 版本 (默认包含所有)。
- * `build_sdist`: 是否构建源码包 (默认: `true`)。
- * `build_wheels`: 是否构建 Wheel 包 (默认: `true`)。
-
-> **发布注意事项**:
-> * **测试优先**:强烈建议在发布到正式 PyPI 之前,先发布到 **TestPyPI** 进行验证。请注意,PyPI 和 TestPyPI 是两个完全独立的环境,账号和包数据互不相通。
-> * **版本不可覆盖**:PyPI 和 TestPyPI 均**不允许覆盖**已发布的同名同版本包。如果您需要重新发布,必须升级版本号(例如打一个新的 Tag 或产生新的 dev 版本)。如果尝试发布已存在的版本,工作流将会失败。
-
----
-
-## Issue 指南
-
-### Bug 报告
-
-请提供:
-
-1. **环境**
- - Python 版本
- - OpenViking 版本
- - 操作系统
-
-2. **复现步骤**
- - 详细步骤
- - 代码片段
-
-3. **预期与实际行为**
-
-4. **错误日志**(如果有)
-
-### 功能请求
-
-请描述:
-
-1. **问题**:您试图解决什么问题?
-2. **解决方案**:您建议什么解决方案?
-3. **替代方案**:您是否考虑过其他方法?
-
----
+CI 会根据受影响路径运行相应检查。CI 通过是必要条件,但不能替代作者验证和维护者评审。
## 文档
-文档采用 Markdown 格式,位于 `docs/` 目录下:
-
-- `docs/en/` - 英文文档
-- `docs/zh/` - 中文文档
-
-### 文档指南
-
-1. 代码示例必须可运行
-2. 保持文档与代码同步
-3. 使用清晰、简洁的语言
-
----
-
-## 行为准则
-
-参与本项目即表示您同意:
-
-1. **尊重**:保持友好和专业的态度
-2. **包容**:欢迎来自不同背景的贡献者
-3. **建设性**:提供有帮助的反馈
-4. **专注**:保持讨论集中在技术层面
-
----
-
-## 获取帮助
-
-如果您有问题:
-
-- [GitHub Issues](https://github.com/volcengine/openviking/issues)
-- [Discussions](https://github.com/volcengine/openviking/discussions)
+项目文档位于 `docs/en/` 和 `docs/zh/`。代码示例必须可运行,语言应清晰简洁;当对应
+翻译存在时,应同步更新两种语言。
----
+## 社区
-感谢您的贡献!
+请保持尊重、包容、建设性,并聚焦技术讨论。开放式设计或使用讨论请前往
+[GitHub Discussions](https://github.com/volcengine/OpenViking/discussions),可执行的 Bug
+和功能请求请提交到 [GitHub Issues](https://github.com/volcengine/OpenViking/issues)。
diff --git a/CONTRIBUTING_JA.md b/CONTRIBUTING_JA.md
index 062d67d8b..89966ebe5 100644
--- a/CONTRIBUTING_JA.md
+++ b/CONTRIBUTING_JA.md
@@ -1,530 +1,257 @@
-# コントリビューションガイド
+# OpenVikingへのコントリビューション
-OpenVikingに興味をお持ちいただきありがとうございます!あらゆる種類のコントリビューションを歓迎します:
+[English](CONTRIBUTING.md) / [中文](CONTRIBUTING_CN.md) / 日本語
-- バグレポート
-- 機能リクエスト
-- ドキュメントの改善
-- コードのコントリビューション
+OpenVikingへのコントリビューションありがとうございます。このガイドは、明確で
+焦点が絞られ、レビューしやすい変更を提出するためのものです。
----
+バグ報告、機能リクエスト、ドキュメント改善、コードのコントリビューションを歓迎します。
-## 開発環境のセットアップ
+## 重視すること
-### 前提条件
+OpenVikingでは、焦点が絞られ、十分に理解された変更を重視します。AIツールの使用有無に
+かかわらず、コントリビューターは自分の変更を理解し、説明し、検証する責任を負います。
-- **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 を推奨
+- 1つのPRでは、まとまりのある1つの問題だけを解決してください。無関係な整理や
+ リファクタリングを混ぜないでください。
+- ルールを所有する既存のモジュールを再利用し、並行する仕組みを追加しないでください。
+- 推測に基づくフォールバック、フラグ、状態フィールド、抽象化を避けてください。
+- 新しい実装によって置き換えられたコード、テスト、互換パスは削除してください。
+- 所有権、ライフサイクル、失敗処理を明確にするために必要な構造は残してください。
-#### サポートされているプラットフォーム(プリコンパイル済みWheel)
+### レビューの優先度
-OpenVikingは以下の環境向けにプリコンパイル済み**Wheel**パッケージを提供しています:
+メンテナーの時間には限りがあるため、焦点を絞ったPRからレビューします:
-- **Windows**: x86_64
-- **macOS**: x86_64、arm64(Apple Silicon)
-- **Linux**: x86_64、arm64(manylinux)
+- **変更行数が100行以下**のPRは、通常より迅速に確認されます。
+- **変更行数が200行以下**のPRは、それより大きなPRより優先して確認されます。
-その他のプラットフォーム(例:FreeBSD)では、`pip`によるインストール時にソースから自動コンパイルされます。[前提条件](#前提条件)がインストールされていることを確認してください。
+これはレビューの優先度であり、厳格な上限や応答時間の保証ではありません。変更行数は、
+手書きのソース、テスト、ドキュメントにおける追加行と削除行の合計です。生成ファイル、
+ベンダーコード、ロックファイルは規模の判断から除外します。
-### 1. フォークとクローン
+行数を抑えるために必要なテストやドキュメントを省略しないでください。分割後の各PRが
+単独で理解でき、正しさを保てる場合にのみ大きな変更を分割してください。PRが小さくても、
+正確性、設計品質、互換性の要件が下がることはありません。
-```bash
-git clone https://github.com/YOUR_USERNAME/openviking.git
-cd openviking
-```
+## 作業を始める前に
-### 2. 依存関係のインストール
+1. 既存のIssue、PR、コードを検索し、同じ動作やドメインルールがないか確認してください。
+2. バグ修正では、可能な限り実際の本番エントリーポイントから再現してください。
+3. 所有モジュールを特定し、値や状態がどこで生成、正規化、保存、利用されるか追跡してください。
+4. 機能追加では、実装を設計する前に、問題と期待する動作を説明してください。
-Python環境管理には`uv`の使用を推奨します:
+次の変更は、実装前にIssueまたはDiscussionで相談してください:
-```bash
-# uvのインストール(未インストールの場合)
-curl -LsSf https://astral.sh/uv/install.sh | sh
+- 公開REST、SDK、CLI、MCP、設定のセマンティクス
+- 永続データ、ストレージスキーマ、VFS/AGFSパス、暗号化ファイルの動作
+- 非同期タスクの所有権、キュー、キャンセル、クリーンアップ、結果状態
+- リソースのインポート/監視、セッションライフサイクル、メモリ抽出
+- 検索レベル、ディレクトリスコープ、ランキングのセマンティクス
+- テナント、アカウント、ユーザー、ピアの識別境界
+- 複数の所有モジュールにまたがる変更や大規模なアーキテクチャ変更
-# 依存関係の同期と仮想環境の作成
-uv sync --all-extras
-source .venv/bin/activate # Linux/macOS
-# または .venv\Scripts\activate # Windows
-```
+現在の動作、提案する動作、具体的なリクエストまたは設定例、互換性への影響を記載して
+ください。これにより、実装前にメンテナーが設計境界を確認できます。
-#### ローカル開発とネイティブコンポーネントの再ビルド
+リポジトリのGitHubテンプレートを使用して、[バグ報告](https://github.com/volcengine/OpenViking/issues/new?template=bug_report.yml)、
+[機能リクエスト](https://github.com/volcengine/OpenViking/issues/new?template=feature_request.yml)、
+[質問](https://github.com/volcengine/OpenViking/issues/new?template=question.yml)を提出してください。
-OpenVikingはAGFSに対してデフォルトで`binding-client`モードを使用し、事前にビルドされたネイティブ成果物を利用します。**AGFS(Go)**コード、同梱の**Rust CLI**、または**C++拡張**を変更した場合や、プリビルド成果物が見つからない場合は、再コンパイルと再インストールが必要です。プロジェクトルートで以下のコマンドを実行してください:
+## 適切な領域を見つける
-```bash
-uv pip install -e . --force-reinstall
-```
+影響する領域が分かる場合は、IssueまたはPRに記載してください。不明な場合は、まず観測可能な
+動作とユースケースを説明してください。メンテナーが担当領域への振り分けを支援します。
-このコマンドにより`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"
- }
-}
-```
+この表は、2026年6月24日から8月24日までにマージされたPRで継続的に確認できる
+作成・レビュー活動に基づいています。排他的なコード所有権ではなく、振り分けのための
+目安です。変更に直接関係する担当者だけにメンションしてください。
-環境変数を設定します:
+| ドメイン | 領域 | 代表的なパスまたはトピック | 最近活動しているメンテナー/レビュアー |
+|---|---|---|---|
+| Platform | Server、API、Auth、Identity、Admin、Task | `openviking/server`、`openviking/service` | `@qin-ctx` |
+| Resource | 取り込み、Watch、タスクパイプライン | `openviking/resource` | `@qin-ctx`、`@KCHENPENGFEI` |
+| Resource | リソース解析 | `openviking/parse` | `@zihengli-bytedance`、`@KCHENPENGFEI` |
+| Memory | Session、メモリ抽出、コンパイル | `openviking/session`、メモリ抽出、`ov compile` | `@chenjw`、`@heaoxiang-ai`、`@fujiajie666` |
+| Retrieval | SearchとVectorDB | `openviking/retrieve`、`openviking/storage/vectordb` | `@zhoujh01`、`@t0saki` |
+| Storage | RAGFS、PathLock、QueueFS、暗号化 | `openviking/storage`、`openviking/pyagfs`、`openviking/crypto`、`crates/ragfs*` | `@baojun-zhang` |
+| Integration | Agent PluginとMCP | `agent-plugins`、メモリPluginの例、Server MCP | `@t0saki`、`@ZaynJarvis` |
+| Integration | VikingBotとAgentコンパイル | `bot`、`ov compile` | `@yeshion23333`、`@fujiajie666` |
+| Client | SDK、CLI、LangChain | `sdk`、`crates/ov_cli`、`integrations/langchain` | `@zhoujh01`、`@t0saki`、`@ehz0ah` |
+| Product | Web Studio | `web-studio` | `@yufeng201`、`@ZaynJarvis` |
+| Project | ドキュメント、CI、Pluginリリース | `docs`、`.github/workflows` | `@yufeng201`、`@ZaynJarvis` |
-```bash
-export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
-```
+複数領域にまたがる変更や担当が不明な場合は、主な影響領域を特定したうえで、
+`@qin-ctx`、`@ZaynJarvis`、`@zhoujh01`のいずれかにメンションしてください。
-### 4. インストールの確認
+## 開発環境
-```bash
-python -c "import openviking; print(openviking.__version__)"
-```
+### 前提条件
-### 5. Rust CLIのビルド(オプション)
+- Python 3.10以上
+- ソースビルド、Rust Binding、同梱`ov` CLIの開発にはRust 1.91.1以上
+- `sdk/go`の開発時のみGo 1.22以上
+- C++17対応コンパイラ:GCC 9以上またはClang 11以上
+- CMake 3.15以上
-Rust CLI(`ov`)は、OpenViking Serverとやり取りするための高性能コマンドラインクライアントを提供します。
+Linuxでは`build-essential`をインストールし、必要に応じて`pkg-config`も追加してください。
+macOSではXcode Command Line Toolsをインストールしてください。Windowsでのローカル
+ネイティブビルドにはCMakeとMinGWをインストールしてください。
-`ov` を直接使わない場合でも、OpenViking をソースからビルドするなら Rust ツールチェーンは必要です。パッケージング時に同梱 CLI バイナリも一緒にビルドされるためです。
+### インストール
-**前提条件**: Rust >= 1.91.1
+リポジトリをフォークし、自分のフォークをクローンします:
```bash
-# ソースからビルドしてインストール
-cargo install --path crates/ov_cli
-
-# または公開済みの npm CLI パッケージをインストール(プリビルドバイナリをダウンロード)
-npm i -g @openviking/cli
+git clone https://github.com/YOUR_USERNAME/OpenViking.git
+cd OpenViking
```
-インストール後、`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` |
-
-### チェックの実行
+`uv`の使用を推奨します:
```bash
-# コードのフォーマット
-ruff format openviking/
-
-# リント
-ruff check openviking/
-
-# 型チェック
-mypy openviking/
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync --all-extras
```
-### スタイルガイドライン
-
-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://")
+uv run python -c "import openviking; print(openviking.__version__)"
```
-共通フィクスチャは`tests/conftest.py`に定義されており、初期化済みの`service`、`request_context`、`temp_dir`、サンプルファイルなどが含まれます。
-
----
-
-## コントリビューションワークフロー
-
-### 1. ブランチの作成
+ローカルサーバーを設定します:
```bash
-git checkout main
-git pull origin main
-git checkout -b feature/your-feature-name
+uv run openviking-server init
+uv run openviking-server doctor
```
-ブランチ命名規則:
-- `feature/xxx` - 新機能
-- `fix/xxx` - バグ修正
-- `docs/xxx` - ドキュメント更新
-- `refactor/xxx` - コードリファクタリング
-
-### 2. 変更の実施
+設定とProviderの例は[設定ガイド](https://docs.openviking.ai/en/guides/01-configuration)を
+参照してください。
-- コードスタイルガイドラインに従う
-- 新機能にはテストを追加する
-- 必要に応じてドキュメントを更新する
-
-### 3. 変更のコミット
-
-```bash
-git add .
-git commit -m "feat: add new parser for xlsx files"
-```
-
-### 4. プッシュとPRの作成
+RAGFS Rust Binding、同梱Rust CLI、C++拡張を変更した場合は、ネイティブコンポーネントを
+再ビルドしてください:
```bash
-git push origin feature/your-feature-name
+uv pip install -e . --force-reinstall
```
-その後、GitHubでプルリクエストを作成します。
+SDK、Integration、Plugin、Benchmarkには追加のセットアップ手順がある場合があります。
+各ディレクトリのREADMEまたはパッケージマニフェストを確認してください。
----
+## 変更の実装
-## コミット規約
+### 所有権と設計
-[Conventional Commits](https://www.conventionalcommits.org/)に従います:
+- 動作は所有モジュールに実装してください。上位レイヤーは結果を転送または利用し、
+ 同じルールを再実装しないでください。
+- 外部の互換表現は境界で1つの正規ドメインモデルに変換してください。内部ビジネスロジックに
+ 入力形式の推測を持ち込まないでください。
+- クライアント向けの境界では、Server、Network、Timeout、Auth、Conflictの意味ある
+ エラー区分を維持してください。
+- タスク状態は、その状態を生成したタスクとの因果関係を保つ必要があります。グローバルキューの
+ 状態や無関係なコールバックから完了を推測しないでください。
+- 各値とルールには、信頼できる情報源を1つだけ持たせてください。
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
+局所的なエッジケースがタスク境界、公開セマンティクス、全体アーキテクチャを変え始めた場合は、
+メインフローに特殊分岐を追加し続けず、実装を止めて設計議論に戻ってください。
-### タイプ
+### コードスタイル
-| タイプ | 説明 |
-|------|-------------|
-| `feat` | 新機能 |
-| `fix` | バグ修正 |
-| `docs` | ドキュメント |
-| `style` | コードスタイル(ロジック変更なし) |
-| `refactor` | コードリファクタリング |
-| `perf` | パフォーマンス改善 |
-| `test` | テスト |
-| `chore` | ビルド/ツーリング |
+PythonではRuffをフォーマットとLintに、mypyを型チェックに使用します。設定行幅は100文字です。
-### 例
+変更したパスに対してチェックを実行してください:
```bash
-# 新機能
-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"
+uv run ruff format <changed-paths>
+uv run ruff check <changed-paths>
+uv run mypy <changed-paths>
```
----
-
-## プルリクエストガイドライン
-
-### PRタイトル
-
-コミットメッセージと同じフォーマットを使用します。
-
-### PR説明テンプレート
-
-```markdown
-## 概要
-
-変更内容とその目的の簡単な説明。
+公開APIには短く有用なDocstringを付けてください。コードを言い換えるコメントより、明確な名前と
+直接的な制御フローを優先してください。
-## 変更の種類
+Rust、Go、TypeScript、ドキュメント、Pluginの変更では、各コンポーネントで定義された
+フォーマット、Lint、型チェック、テストコマンドを使用してください。
-- [ ] 新機能(feat)
-- [ ] バグ修正(fix)
-- [ ] ドキュメント(docs)
-- [ ] リファクタリング(refactor)
-- [ ] その他
+### テスト
-## テスト
+変更の影響を受ける、意味のある最小の公開契約と主要な失敗境界を検証してください。
-これらの変更のテスト方法を記述してください:
-- [ ] ユニットテストが通過する
-- [ ] 手動テストが完了している
+- 既存の価値の高い契約テストを更新することを優先してください。
+- デフォルトでは、新しいユニットテストやテストファイルを追加しないでください。
+- 長期的な公開契約を保護する場合を除き、プライベートHelperの存在、Mock呼び出し順序、
+ 単純なフィールド転送、フレームワークの動作をテストしないでください。
+- 小さく明確な修正では、自動的に新しいテストを追加する必要はありませんが、検証方法を
+ 説明する必要があります。
+- 一時的な再現、診断、負荷、検証スクリプトは`test_scripts/`に置き、ソース、Benchmark、
+ メンテナンススクリプトのディレクトリには置かないでください。
-## 関連Issue
+関連するテストを絞って実行します。例:
-- Fixes #123
-- Related to #456
-
-## チェックリスト
-
-- [ ] コードがプロジェクトのスタイルガイドラインに従っている
-- [ ] 新機能にテストが追加されている
-- [ ] ドキュメントが更新されている(必要な場合)
-- [ ] すべてのテストが通過する
+```bash
+uv run pytest tests/client/test_http_client_config.py
+uv run pytest tests/server/ -k "search"
```
----
-
-## 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"]`)。
+変更範囲とリスクに応じて必要な場合のみ、Pythonテスト全体を実行してください:
-#### 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ガイドライン
+```bash
+uv run pytest
+```
-### バグレポート
+## Pull Requestの提出
-以下を提供してください:
+最新の`main`からブランチを作成し、焦点を絞った変更を行って`main`向けにPRを提出します。
-1. **環境**
- - Pythonバージョン
- - OpenVikingバージョン
- - オペレーティングシステム
+コミットメッセージとPRタイトルには
+[Conventional Commits](https://www.conventionalcommits.org/)を使用してください:
-2. **再現手順**
- - 詳細な手順
- - コードスニペット
+```text
+feat(parser): support xlsx resources
+fix(retrieval): preserve rerank score order
+docs: clarify server configuration
+refactor(storage): remove duplicate path normalization
+```
-3. **期待される動作と実際の動作**
+リポジトリのPRテンプレートをすべて記入してください。良いPR説明には次を含めます:
-4. **エラーログ**(ある場合)
+- 変更前後の観測可能な動作
+- バグ修正の場合は、根本原因と実際の実行パス
+- 影響するエントリーポイントと所有モジュール
+- 互換性または移行への影響(該当する場合)
+- 実際に実行した検証コマンド
+- 問題を再現したのか、コードから推測しただけなのか
-### 機能リクエスト
+Human Involvementの項目は正確に選択してください。AI支援によるコントリビューションも
+歓迎しますが、作者は変更に責任を持ち、システムの他の部分との相互作用を説明できる必要が
+あります。
-以下を記述してください:
+提出前に:
-1. **問題**: どのような問題を解決しようとしていますか?
-2. **解決策**: どのような解決策を提案しますか?
-3. **代替案**: 他のアプローチを検討しましたか?
+- Diff全体を確認し、無関係な変更や意図せず生成された変更を削除してください。
+- 置き換えられたHelper、分岐、Mock、コメントが削除されていることを確認してください。
+- 公開動作が変わる場合は、関連ドキュメントを更新してください。
+- 実行しなかったチェックと具体的な理由を報告し、未実行のテストを実行済みとしないでください。
----
+CIは影響するパスに応じてチェックを実行します。CIの成功は必要条件ですが、作者による検証や
+メンテナーレビューの代わりにはなりません。
## ドキュメント
-ドキュメントは`docs/`配下にMarkdown形式で管理されています:
-
-- `docs/en/` - 英語ドキュメント
-- `docs/zh/` - 中国語ドキュメント
-
-### ドキュメントガイドライン
-
-1. コード例は実行可能であること
-2. ドキュメントとコードの同期を維持すること
-3. 明確で簡潔な言葉を使用すること
-
----
-
-## 行動規範
-
-このプロジェクトに参加することで、以下に同意するものとします:
-
-1. **敬意を持つ**: 友好的でプロフェッショナルな態度を維持する
-2. **包括的である**: あらゆるバックグラウンドのコントリビューターを歓迎する
-3. **建設的である**: 有益なフィードバックを提供する
-4. **集中する**: 議論を技術的な内容に保つ
-
----
-
-## ヘルプ
-
-質問がある場合:
-
-- [GitHub Issues](https://github.com/volcengine/openviking/issues)
-- [Discussions](https://github.com/volcengine/openviking/discussions)
+プロジェクトドキュメントは`docs/en/`と`docs/zh/`にあります。コード例は実行可能にし、
+明確で簡潔な表現を使用してください。対応する翻訳がある場合は両言語を更新してください。
----
+## コミュニティ
-コントリビューションありがとうございます!
+敬意を持ち、包括的かつ建設的に、技術的な議論へ集中してください。自由形式の設計や使用方法の
+議論には[GitHub Discussions](https://github.com/volcengine/OpenViking/discussions)を、
+対応可能なバグや機能リクエストには
+[GitHub Issues](https://github.com/volcengine/OpenViking/issues)を使用してください。