Raven-1/docs/dev.md
0xKT a27559e331 fix(*): the final audit closes consent, tty truth, and the cache lies
An adversarial last pass over the whole branch found what the review
rounds had not. Consent first: the sh decline arm matched only bare n/N,
so a typed "no" installed LibreOffice through sudo; the arm now takes
the word too, and a tripwire pins the default-yes prompt in both
installers so the review-round decision cannot silently flip back. The
tty gate probed existence where openability is the truth -- the node
exists in CI, cron and docker -t without -i -- so the gate now opens it,
and a consoleless run skips instead of defaulting yes or hanging.
install.ps1 finally carries the everos memory wheel through both of its
paths with sh's own rung discipline, so the Windows summary's memory row
can be green at all. The two cache resolvers follow playwright's real
lookups (XDG_CACHE_HOME, LOCALAPPDATA, chrome-win64 layouts), a
non-object registry degrades instead of raising, and the four mouths
that name a fix now say the same runnable thing on every platform.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-12 00:50:35 +08:00

93 lines
2.7 KiB
Markdown

# Raven Developer Guide
## Build & Run from Source
The project uses **Python + `uv`** with `hatchling` as the build backend.
### 0. System prerequisites
`uv` installs everything raven imports. One program it cannot: **LibreOffice**,
which converts a deck (or any Office source document) to PDF. The deck engine
renders, measures and previews through that conversion, and the gateway's PDF
viewer serves it, so without LibreOffice a deck still builds but nothing that
reads the rendered page runs, and several integration tests skip.
```bash
apt install libreoffice # Debian / Ubuntu
brew install --cask libreoffice # macOS
winget install TheDocumentFoundation.LibreOffice # Windows
```
The browser tool's chromium binary is also not a Python package: a source
checkout downloads it with
`uv sync --all-extras && uv run playwright install chromium`
(install.sh does this for tool installs).
`raven doctor` reports it under **External tools**.
### 1. Install dependencies
```bash
cd /path/to/raven
uv sync
```
This creates/updates `.venv` with all core dependencies from `uv.lock`.
For optional extras:
```bash
uv sync --extra channels # messaging integrations (Telegram, Slack, etc.)
uv sync --extra sandbox # boxlite sandbox execution
uv sync --extra tools # web/readability tools
# or all at once:
uv sync --all-extras
```
### 2. Install the package in editable mode
```bash
uv pip install -e .
```
This wires up the `raven` CLI script to your source code so changes take effect immediately.
### 3. Run the CLI
```bash
# via uv run (uses .venv automatically, no activation needed):
uv run raven --help
# or activate the venv first:
source .venv/bin/activate
raven --help
```
### 4. First-time setup
```bash
uv run raven onboard
```
Creates `~/.raven/config.json` and the workspace directory. Edit the config to add your API key (default provider: OpenRouter — get a key at https://openrouter.ai/keys).
### 5. Common commands
| Command | Description |
|---|---|
| `raven tui` | Start the interactive chat TUI |
| `raven agent -m "Hello"` | Send a single message and exit |
| `raven gateway` | Start full server (all channels + heartbeat + cron) |
| `raven status` | Show 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`) |
### 6. Run tests
```bash
uv run pytest tests/
```
Requires Python >= 3.12, and LibreOffice for the tests that render a deck (they skip without it).
Test configuration is in `pyproject.toml` (`asyncio_mode = "auto"`).