Raven-1/docs-site/mkdocs.yml
Handsome-wzw 132c89b91b
docs(docs): a guide to working on registered machines, in English and Chinese (#956)
## Summary

The sub-agent page's "Work on a registered machine" section said in six
sentences that the feature exists; a reader who had not seen the code
could not get from there to an agent running on their own GPU box. This
adds `docs-site/docs/machines.md` and `machines.zh.md`, a full
walk-through, and puts the page in the nav under "Working with
Sub-agents" (with its Chinese nav title). The old section is now two
sentences and a link.

What the page covers, in order: what the machine needs; registering it
with `raven ops connection add` (what is recorded and where, the key
path rather than the key, host keys on first connection, the managed ssh
alias); installing the node (what lands where, the space check, the
package index, `--dir`, upgrading and `--prune`, the daemon's lifetime);
naming the machine in an acp, cli or openai entry, and why a builtin one
cannot; adding one from a conversation through `subagents.add`; what a
dispatch does (attachments named by address, MCP not lent, files left on
the machine, the reply's closing line); the scp spelling of a path on a
machine; reading, editing and fetching by address with the permission
rules; disconnects and restarts; a table of limits and defaults; a
troubleshooting table of the sentences the tools say; what never leaves
this computer. MCP lending is written as coming in #947, not as present.

Every number and sentence was read from the code rather than remembered:
`raven/node/protocol.py` and `raven/node/client.py` (agent limit, record
retention, heartbeat, backoff, idle close), `raven/node/install.py`
(what an install needs, puts there and refuses),
`raven/agent/tools/deliver.py` (fetch budget and landing path),
`raven/acp_client/remote.py` and `raven/ops/remote_path.py` (address
forms, failure sentences, reading roots), `raven/config/schema.py` (the
`machine` and `remoteCwd` fields of each kind),
`raven/rpc/methods/subagents.py` (the add's refusals and default name).
The three config examples validate against
`ThirdPartyAcpSubagentConfig`, `ThirdPartyCliSubagentConfig` and
`ThirdPartyOpenAISubagentConfig`. Example addresses use the
documentation-reserved 203.0.113.0/24 range. The review's four findings
were folded back in: the installer needs `uv` (or `curl`/`wget` to fetch
it) whatever Python the machine has; `doctor` exits non-zero only when
no entry is usable; a link idle for 10 minutes is closed at the next use
of another machine, not by a timer; and the pull request is named in
text, since site pages link nowhere external.

## Type

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

## Verification

- `uv run --frozen --group docs mkdocs build -f docs-site/mkdocs.yml
--strict`: builds clean on the committed tree, both languages; the
page's internal anchors and the link into `oncall.md` resolve in the
built HTML.
- Both pages rendered in a browser (full-page screenshots reviewed): nav
entry, right-hand TOC, tables and code blocks in both languages.
- `pytest tests/test_docs_site.py -n 0`: 16 passed (both pages have both
languages, no external links, Chinese headings pin the English anchors).
- `python -m scripts.check_source_language`, `python -m
scripts.check_large_files`, `python -m scripts.check_commit_messages
origin/main..HEAD`: pass.
- The English and Chinese pages have the same sixteen headings; every
Chinese heading carries the English anchor, so a link written against
one language lands on the other.
- The three JSON examples were loaded through the config schema classes.

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

## Risk

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

Documentation only; no code changes. The page describes the security
boundary as the code draws it: the key and the assembled ssh line never
reach a model, the user, address and port do as part of a path on the
machine. Rollback is reverting the commit.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-15 14:35:25 +08:00

153 lines
12 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

site_name: Raven
site_url: https://evermind-ai.github.io/Raven/
repo_url: https://github.com/EverMind-AI/Raven
docs_dir: docs
theme:
name: material
# The icon raven.evermind.ai links as its favicon, byte for byte: the full
# EverMind mark at 192px, which that site uses for its light, dark and
# apple-touch icons alike, so a tab on either site shows the same mark. Its
# CDN re-encodes it as AVIF for any client that accepts one, so fetch it with
# a plain `Accept: */*` to get the original PNG back:
# https://framerusercontent.com/images/Mygj0zy4ZlnkWoo1CVUGFUDFfxY.png
# Section 7 of AGENTS.md keeps icon files out of the repository, so it is
# inlined rather than shipped as a file.
favicon: 'data:image/png;base64,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'
font:
text: Atkinson Hyperlegible Next
features:
- navigation.sections
- navigation.top
- navigation.footer
- content.code.copy
palette:
- scheme: default
primary: custom
accent: custom
extra:
generator: false
extra_css:
- stylesheets/evermind.css
extra_javascript:
- javascripts/toc-progress.js
hooks:
- hooks/search_by_language.py
markdown_extensions:
- admonition
- attr_list
- md_in_html
- tables
- toc:
permalink: true
- pymdownx.superfences
- pymdownx.highlight
plugins:
# Chinese runs no spaces, so jieba segments it at build time and marks
# each boundary with a zero-width space. The separator has to break on
# that mark: JavaScript's \s stops at \u200a and would leave every run
# as a single token.
- search:
separator: '[\s\u200b\-]+'
- i18n:
docs_structure: suffix
fallback_to_default: true
reconfigure_material: true
reconfigure_search: true
languages:
- locale: en
default: true
name: English
build: true
- locale: zh
name: 简体中文
build: true
nav_translations:
Guide: 指南
Overview: 总览
Quick Start: 快速开始
Using Raven: 使用 Raven
Working with Sub-agents: 与子 Agent 协作
Working on Registered Machines: 在登记机器上工作
Browser and Human Collaboration: 浏览器与人工协作
Knowledge Bases: 知识库与文档检索
Long-running Work (Oncall): 长任务托管(Oncall)
Playbooks: Playbooks 使用指南
Channels and Messaging: 渠道与消息
Agent Integrations: Agent 集成
Self-Hosting: 自托管
Docker Deployment: Docker 部署
Launch WebUI: 启动 WebUI
Sandbox: 沙箱
Reference: 参考
Architecture: 架构
Agent Protocols: Agent 协议
DAG Orchestration: DAG 编排
Permissions and Security: 权限与安全
Skills, Memory and Extensions: 技能、记忆与扩展
Command Reference: 命令参考
Repo Layout: 仓库布局
Developers: 开发者
Development: 开发
Building an Agent: 构建 Agent
Building a Plugin: 构建插件
Protocol and Backend Integration: 协议与后端集成
Proactive Reminders and Follow-ups: 主动提醒与跟进
Proactivity Design and Implementation: 主动性设计与实现
Evolver: Evolver
Usage and Experiments: 使用与实验
Design and Implementation: 设计与实现
Trajectory Debugging and Replay: 轨迹调试与回放
Tracing and Instrumentation API: 追踪与埋点 API
- git-revision-date-localized:
type: date
enable_creation_date: false
fallback_to_build_date: false
nav:
- Guide:
- Overview: index.md
- Quick Start: quick-start.md
- Using Raven:
- Overview: using-raven.md
- Launch WebUI: webui.md
- Sandbox: sandbox.md
- Working with Sub-agents: agent-collaboration.md
- Working on Registered Machines: machines.md
- Browser and Human Collaboration: browser-collaboration.md
- Knowledge Bases: knowledge.md
- Playbooks: playbooks.md
- Proactive Reminders and Follow-ups: proactivity.md
- Long-running Work (Oncall): oncall.md
- Channels and Messaging: channels.md
- Agent Integrations: agent-integrations.md
- Skills, Memory and Extensions: skills-and-extensions.md
- Self-Hosting:
- Overview: self-hosting.md
- Docker Deployment: docker.md
- Reference:
- Architecture: architecture.md
- Agent Protocols: agent-protocols.md
- DAG Orchestration: orchestration.md
- Permissions and Security: permissions.md
- Command Reference: commands.md
- Repo Layout: repo-layout.md
- Developers:
- Development: development.md
- Building an Agent: building-agent.md
- Building a Plugin: building-plugin.md
- Protocol and Backend Integration: protocol-backends.md
- Proactivity Design and Implementation: proactivity-design.md
- Trajectory Debugging and Replay: trajectory-debugging.md
- Evolver:
- Usage and Experiments: evolver.md
- Design and Implementation: self-evolution-map.md
- Tracing and Instrumentation API: tracing-api.md