Raven-1/docs-site/docs/development.zh.md
userName20260323 8a1ebdc577
docs: organize bilingual documentation navigation (#635)
## 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>
2026-09-22 16:14:44 +08:00

3.6 KiB
Raw Permalink Blame History

开发

本文介绍如何从本地源码构建、运行和测试 Raven。项目使用 Python 与 uv 管理依赖, 使用 hatchling 打包。

产品扩展请选择构建 Agent、构建插件或 协议与后端集成。这些指南介绍扩展契约,本页介绍共享仓库工作流。

基准驱动的 harness 实验请先读Evolver:使用与实验,包括维护状态 和安全边界。当前 harness 故障的诊断见轨迹调试与回放。

系统依赖

uv 负责安装 Raven 的 Python 依赖。LibreOffice 需要单独安装,用于将幻灯片和其他 受支持的办公文档转换为 PDF。幻灯片引擎依赖这一转换进行渲染、版面测量和预览,网关则展示 生成的 PDF。缺少 LibreOffice 时仍可生成幻灯片文件,但依赖渲染结果的功能不可用,相关集成 测试也会跳过。

apt install libreoffice                          # Debian / Ubuntu
brew install --cask libreoffice                  # macOS
winget install TheDocumentFoundation.LibreOffice # Windows

浏览器工具还需要单独安装 Chromium。请在源码仓库中运行:

uv sync --all-extras && uv run playwright install chromium

使用托管安装时,install.sh 会完成浏览器下载。运行 raven doctor,可在 External tools 一节中查看这两项依赖的状态。

安装依赖

cd /path/to/raven
uv sync

该命令会根据 uv.lock 创建或更新 .venv,安装全部核心依赖。

可选依赖:

uv sync --extra channels   # 消息渠道集成(Telegram、Slack 等)
uv sync --extra sandbox    # boxlite 沙箱执行
uv sync --extra tools      # 网页与正文提取工具
uv sync --all-extras       # 安装全部可选依赖

以可编辑模式安装

uv pip install -e .

uv sync 默认以可编辑模式安装项目。上面的命令可显式重新安装,让 raven 命令继续使用 源码工作树中的代码。

运行 CLI

使用 uv run 可直接在项目环境中运行命令。下方激活环境的示例适用于 POSIX Shell; Windows 用户可以使用 uv run 方式。

# 通过 uv run,自动使用 .venv,无需激活:
uv run raven --help

# 或先激活环境:
source .venv/bin/activate
raven --help

首次配置

uv run raven onboard

按照向导提示选择模型服务商、配置凭据并选择模型。默认情况下,Raven 将配置保存在 ~/.raven/config.json,并在配置过程中创建工作区目录。

常用命令

命令 说明
raven tui 启动交互式聊天 TUI
raven agent -m "Hello" 发送单条消息后退出
raven gateway 启动网关,以及已启用的消息渠道、心跳和定时任务
raven status 查看配置路径、工作区与 API 密钥状态
raven channels status 显示哪些消息渠道已启用
raven provider login <name> 通过 OAuth 登录模型服务商,例如 openai-codex、minimax-global 或 minimax-cn

Raven 的命令概览请参阅命令参考。

运行测试

uv run pytest tests/

测试需要 Python 3.12 或更高版本。渲染幻灯片的测试还需要 LibreOffice,缺少时会跳过。 Pytest 配置位于 pyproject.toml,其中异步测试使用 asyncio_mode = "auto"。