yudongyouqing 0cf70f5773
fix(sandbox): point boxlite install advice at the running environment (#822)
## Summary

- The missing-boxlite advice told users to run `pip install
'raven[sandbox]'`, which is wrong twice over: the `raven` name on
package indexes resolves to an unrelated project, and a global pip
install bypasses the uv environment raven actually runs in (#640).
- Added `boxlite_install_hint()` to `raven.sandbox`: it resolves the
pinned boxlite requirement from the installed distribution metadata
(falling back to the bare name when metadata is absent) and renders a
copy-pasteable command targeting the running interpreter, e.g. `uv pip
install --python /path/to/venv/bin/python boxlite==0.9.5`.
- The onboarding screen keeps its translatable line in the zh catalog
and prints the command on its own untranslatable line;
`build_executor`'s ImportError message uses the same hint.
- The two init-failure messages that fire after the boxlite import
already succeeded no longer suggest a reinstall; they keep the platform
bullets naming the actual causes.

## Type

- [x] Fix

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Commands run on macOS, Python 3.12, on top of a clean checkout of main:

- `uv run pytest tests/test_sandbox_unit.py
tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py
tests/test_i18n_prompts.py -q` -> 467 passed. The new tests
(TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor
case, one onboard screen case) were each watched failing before the fix.
- `uv run --frozen --python 3.12 --all-extras pytest -q` -> 27002
passed, 109 skipped, 21 failed. The 21 failures reproduce identically on
unmodified main (verified by stashing this change):
`test_agents_research_tools.py` (13),
`test_agents_research_verbatim_sink.py` (5),
`test_simulation_scenario.py` and `test_simulation_suite.py` (2),
`test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1,
LibreOffice not installed locally). None touch the changed modules.
- `uv run ruff check` and `ruff format --check` on the six touched files
-> clean.
- `make lint-imports` -> 10 kept, 0 broken.
- `make check-source-language` -> pass.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

- User-visible change: three messages read differently (the onboarding
hint, the build_executor ImportError, two executor init-failure
messages). No API, config, or behavior change beyond the wording. The
hint assumes uv on PATH, which every documented install path already
requires.
- Rollback is a straight revert of this commit.

## Related Issues

Fixes #640
2026-10-03 22:32:44 +08:00
..

Raven operational scripts

Standalone CLIs and admin utilities. Not part of the Raven wheel — these scripts are invoked directly from a checkout and don't ship to end users.

Layout

scripts/
├── README.md                     This file.
└── boxlite_cli.py                Direct CLI for the boxlite microVM library.

When to use

Script Purpose See
boxlite_cli.py Manage boxlite OCI images + VMs (pull / ls / create / start / stop / rm / shell). Independent of Raven — works even when no agent is running, can inspect VMs owned by another boxlite home. docs/sandbox/boxlite_cli.md

scripts/boxlite_cli.py is complementary to the raven sandbox sub-command group (in raven/cli/sandbox_commands.py):

  • raven sandbox … — agent-runtime debug interface (Unix-socket connection to a SandboxDebugServer inside a running Raven process; only sees VMs owned by that process).
  • scripts/boxlite_cli.py … — direct boxlite library CLI (manages images, creates / cleans up VMs, can target any boxlite home dir).

Use raven sandbox when you want to inspect / shell into the VMs your live agent is currently using. Use scripts/boxlite_cli.py for everything else (image management, post-mortem cleanup, cross-process inspection, Raven-not-running scenarios).

Where fixture generators live

Test / benchmark data generators are NOT in scripts/ — they live alongside the benchmark or test that consumes them. Examples:

  • benchmarks/skill_evals/fixtures/build_mock_library.py — synthetic SQLite mass-library DB for test_skill_forge_e2e.py and skill_evals/run_eval.py.