## Summary Reorganize the Raven documentation landing page and expand the bilingual documentation site. - Add bilingual guidance for agent collaboration, ACP and A2A protocols, DAG orchestration, channels, browser collaboration, knowledge bases, Playbooks, proactive follow-ups, Oncall, permissions, tracing, trajectory replay, and Evolver. - Group daily usage under `Use Raven` and `Using Raven`. - Group `Technical Reference` and `Developer Guide` under `Explore the documentation` while preserving separate cards. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - [x] Relevant tests pass locally - [ ] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed Exact checks: - `uv run --frozen --group docs mkdocs build -f docs-site/mkdocs.yml --strict` - passed. - `uv run --frozen --group docs pytest tests/test_docs_site.py tests/test_living_docs.py tests/integration/test_docs_site_controls_e2e.py -q -o addopts=''` - 77 passed. - `uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD` - passed. - `git diff --check origin/main...HEAD` - passed. - `make check-large-files` - passed. ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes This is a documentation-only change. It does not change runtime behavior, configuration semantics, or public APIs. Reverting the documentation commits restores the previous site content and navigation. ## Related Issues N/A --------- Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com> Co-authored-by: Claude (claude) <noreply@anthropic.com>
3.7 KiB
Development
Build, run, and test Raven from a local source checkout. The project uses
Python with uv for dependency management and hatchling for packaging.
For product extensions, choose Building an Agent, Building a Plugin, or Protocol and Backend Integration. Those guides cover the extension contracts; this page covers the shared checkout workflow.
For benchmark-driven harness experiments, start with Evolver: usage and experiments, including its lifecycle and security limits. For failures in the current harness, use Trajectory debugging and replay.
System prerequisites
uv installs Raven's Python dependencies. Install LibreOffice separately
to convert slide decks and other supported office documents to PDF. The deck
engine uses this conversion for rendering, layout measurements, and previews;
the gateway displays the resulting PDF. Without LibreOffice, decks can still
be generated, but rendering-dependent steps are unavailable and the relevant
integration tests are skipped.
apt install libreoffice # Debian / Ubuntu
brew install --cask libreoffice # macOS
winget install TheDocumentFoundation.LibreOffice # Windows
The browser tool also needs a separate Chromium binary. Install it from your source checkout:
uv sync --all-extras && uv run playwright install chromium
install.sh handles the browser download for managed installations.
raven doctor reports both dependencies under
External tools.
Install dependencies
cd /path/to/raven
uv sync
This creates or updates .venv with every core dependency from uv.lock.
Optional extras:
uv sync --extra channels # messaging integrations (Telegram, Slack, and others)
uv sync --extra sandbox # boxlite sandbox execution
uv sync --extra tools # web and readability tools
uv sync --all-extras # all of them at once
Install the package in editable mode
uv pip install -e .
uv sync installs the project in editable mode by default. The command above
reinstalls it explicitly, keeping the raven command linked to your source tree.
Run the CLI
Use uv run to run commands in the project environment. The activation example
below uses a POSIX shell; on Windows, use the uv run form.
# through uv run, which uses .venv without activating it:
uv run raven --help
# or activate the environment first:
source .venv/bin/activate
raven --help
First-time setup
uv run raven onboard
Follow the setup wizard to choose a model provider, configure credentials, and
select a model. By default, Raven stores its configuration in
~/.raven/config.json and creates a workspace directory during setup.
Common commands
| Command | Description |
|---|---|
raven tui |
Start the interactive chat TUI |
raven agent -m "Hello" |
Send a single message and exit |
raven gateway |
Start the gateway with enabled messaging channels, heartbeat, and scheduled tasks |
raven status |
Show the config path, workspace, and API key status |
raven channels status |
Show which messaging channels are enabled |
raven provider login <name> |
Authenticate with an OAuth provider, for example openai-codex, minimax-global, or minimax-cn |
See Command Reference for an overview of Raven's commands.
Run tests
uv run pytest tests/
Tests require Python 3.12 or newer. Tests that render slide decks also require
LibreOffice and are skipped when it is unavailable. Pytest settings are defined
in pyproject.toml, including asyncio_mode = "auto" for asynchronous tests.