Raven-1/docs-site/docs/commands.md
江国庆/Forrest 6b938a4267
feat(*): export conversations and report problems from the web page (#948)
## Summary

The web page gains two things a conversation could only get from the
terminal before: exporting the selected turns as a download, and
reporting a problem through the bug report pipeline. The trajectory view
is now on for everyone.

- **Trajectory view without `--dev` (R0).** `raven`, `raven web`, `raven
serve` and `raven gateway` no longer take `--dev`; the trajectory policy
starts enabled. `raven tui --dev` (running the TUI from source) is
unchanged.
- **Turn selection.** From this version each turn's opening user message
records its trace id (the Turn Trace Mark, never sent to the model).
`raven/trajectory/selection.py` lists a session's main-line turns,
closes a selection over the sub-agent and delegated traces it
dispatched, collects their spans, and cuts the session record down to
the selected turns; older records are matched conservatively and an
unmatched turn stays in the trajectory only.
- **Export.** The Trajectory Export package v1 (`schema:
raven_trajectory_export`, `format_version: 1`) is the input contract of
the coming `web-traj-import`; it is defined in `CONTEXT.md` and pinned
by tests. It holds the raw spans, artifacts and v2 message blobs of the
selected traces plus the cut session record, unredacted. Exports run as
background jobs (at most two) and the browser downloads them from the
same-origin `/trajectory/export/download` route with a one-time token.
New RPCs: `trajectory.turns`, `trajectory.export`,
`trajectory.export_status`, `trajectory.export_cancel`.
- **Bug reports.** `freeze_export` is split into staging and finishing
so a report can be prepared from selected turns; the CLI's behaviour is
unchanged. A Report Session holds a web report in the gateway between
page requests: at most two at once, all blocking I/O on worker threads,
a cancel checked after every step (a report cancelled while packaging is
never sent), a failed or uploaded report releases its slot and keeps its
last status for ten minutes, and an idle one is cancelled after thirty
minutes. Seven `bugreport.*` RPCs, the `bugreport-v1` capability
(announced only while the receiver URL is valid), and error codes -32026
/ -32027 / -32028. Every decision made on the web page, defaults and
bulk buttons included, is remembered in the redaction history with `web`
as its source, unlike the CLI's bulk flags.
- **Web page.** A three-dot conversation menu in the header's corner
(the desk launcher moves one slot in) opens the new `export` wizard.
Export: pick turns, name the file under an "unredacted" warning, follow
the job, download once automatically with a link to download again.
Report a problem: pick turns, describe the problem, decide the uncertain
values in two columns (hits highlighted at code points), upload, and get
a receipt. Closing before the upload starts discards the report being
prepared; once the upload starts the report is saved on the machine, a
failure marked retryable offers a retry, and the saved report can be
sent later from the command line by its id. Every answer is checked
against the wizard's epoch and the job or report it was asked about, and
a write step whose answer is lost is settled from the report's status
instead of being sent again. Layouts were measured at 360 and 390 px in
English and Chinese.
- **Docs and tests.** The webui and trajectory-debugging pages (English
and Chinese) describe both flows. Two integration tests drive them end
to end: the export through the real download route, and the bug report
against a real receiver process, including a stopped receiver, a retry,
the redaction history's replay and a cancel at each step.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- The branch merges the current `main` (one merge commit, no conflicts);
everything below ran on the merged tree.
- `uv run pytest tests/ -q` (full suite): 57 failed / 31491 passed / 177
skipped. Every one of the 57 also fails on the current `main` on this
machine (environment-specific, pre-existing); none is introduced by this
branch.
- `uv run pytest -m integration
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_web_bugreport_e2e.py
tests/integration/test_bug_report_upload_e2e.py -q`: 10 passed (three
consecutive runs of the two new files).
- `uv run ruff check`, `uv run ruff format --check`, `uv run ty check`
on the changed Python: pass.
- ui-web: `npm run gen:check` (239 methods), `npm run lint`, `npm run
type-check`, `npx vitest run` (246 files / 3868 passed), `npm run build`
and `python3 ui-web/build.py` (both boot snapshots match),
`check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint:rpc`, `npm run lint:i18n`: pass.
- `uv run --group docs mkdocs build -f docs-site/mkdocs.yml --strict`:
pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium on the built page (offline fixtures): both flows
walked to the download and to the receipt; the header corner measured in
five layouts (desk panel open and closed, workspace panel open, shell
mode, narrow split) and the wizard at 360 and 390 px in both languages.

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

## Risk

- A process started with the old `--dev` flag that runs `system.upgrade`
relaunches itself with `--dev`, which the new version refuses; the user
runs `raven web` once by hand. This was accepted as the cost of dropping
the flag.
- The trajectory view is on by default: each open page calls the light,
in-memory `trajectory.state` every five seconds, and the index is built
only when the view is opened. No switch to turn it off is added here;
the policy keeps a replaceable source for a settings entry later.
- The export is the raw trajectory and may contain secrets. The page
says so in a warning; the download is served only on the same origin,
behind the session guard, by an unguessable one-time token, and no path
ever reaches the page.
- Rollback: revert the squash commit. Nothing is migrated; the
`trace_id` field already written into session records is ignored by
older versions.

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

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-14 21:34:46 +08:00

5.0 KiB

Command Reference

Use this reference to find the command for a task. Each command's help output lists its subcommands and options.

Command Purpose
raven or raven tui Launch the terminal UI
raven web Open the WebUI and keep Raven running in the background
raven web --stop Stop the background WebUI service
raven agent -m "..." Run a single task from the command line
raven onboard Set up model providers, sandboxing, messaging channels, memory, web tool credentials, subagents, and data import
raven status Show configuration and runtime status
raven doctor Diagnose provider and environment problems
raven --version Show the installed Raven version
raven upgrade --check / raven upgrade Check for updates or upgrade a managed installation
raven agents new <name> Create a specialized agent from Raven's modular templates
raven acp Serve Raven as an ACP agent over stdio
raven a2a enable / raven a2a disable Enable or disable the gateway-mounted A2A face; restart the host afterward
raven a2a serve Start a standalone A2A HTTP listener (loopback port 8710 by default)
raven sessions Create, list, fork, export, or delete sessions; resolve session keys with resume
raven playbook Create, validate, manage, and run reusable agent workflows
raven provider Configure providers and endpoints, authenticate, test connectivity, and select the active model
raven channels List, configure, authenticate, enable, or disable messaging channels
raven gateway Start the gateway and its configured services
raven gateway status / raven gateway reload / raven gateway stop Inspect, reload configuration, or gracefully stop a running gateway
raven serve Start the WebSocket RPC service and serve the WebUI when its build is available
raven skill Browse SkillForge skills, inspect their contents, block or unblock skills, and remove installed bundles
raven plugins List installed plugins and the active memory backend
raven plugin auth <server> Authenticate or refresh OAuth access for an MCP server
raven mcp bridge <socket-path> Bridge a subagent's MCP connection over stdio to a host-managed server
raven import Preview and import data from other AI tools, inspect progress, or stop an import
raven cron Create, inspect, run, enable, disable, or delete scheduled jobs
raven sentinel Configure proactivity and inspect attention, routines, decisions, and nudges
raven ops connection Register and list machines; add probes by default, while doctor validates registry entries
raven sandbox List sandbox VMs, run commands, or open a shell; requires tools.sandbox.debug.enabled=true
raven tracing Open the local trace dashboard
raven tracing compact Consolidate duplicate trace artifacts to free disk space
raven trajectory Save, replay, redact, label, and preserve execution trajectories for debugging, and run the bug report receiver

Run raven --help for the command list, or raven <command> --help for details on a specific command. From a source checkout, prefix commands with uv run.

Find documentation by task

Task Read
Choose a conversation or one-shot workflow Using Raven
Configure shipped or external agents Agent Integrations
Continue or steer a specialist task Working with sub-agents
Share browser work with the agent Browser collaboration
Store and search documents Knowledge bases
Run and watch long tasks Long-running work (Oncall)
Configure a messaging bot Channels and Messaging
Integrate an editor or remote agent Agent protocols
Run parallel tasks or inspect graph history DAG orchestration
Save and run a reusable workflow Playbooks
Evaluate harness changes against a benchmark Evolver: usage and experiments
Configure approvals and unattended access Permissions and security
Add knowledge, tools, or an agent Skills and extensions
Deploy the resident host Self-Hosting
Create an agent or plugin Building an Agent, Building a Plugin
Capture, redact, and replay a failure Trajectory debugging and replay

Use site search to find a topic and --help to check command syntax. For optional protocol features, consult the capabilities reported during the handshake.

From the repository root, search the documentation and implementation together:

rg -n 'ACP|A2A|run_subagent_dag' docs-site/docs raven tests

run_subagent_dag, dag_status, cancel_dag, and a2a_send are model tools, not shell subcommands. Use their guides for arguments and behaviour.