From 54dfcae2f17878f1bc7119c7fe21746d209eeb41 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Fri, 7 Aug 2026 17:15:04 +0800 Subject: [PATCH 01/13] docs: update README banner --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de9dde6..790e165 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-![Raven banner](https://github.com/user-attachments/assets/5a99d736-49ee-49c9-8b51-890f14078e78) +![Raven banner](https://github.com/user-attachments/assets/f2882578-ff8e-4817-a5d2-6ada414acf1a)

X From f16a83a93bfb71e57e352967658e1319f1646bf6 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 15:57:21 +0800 Subject: [PATCH 02/13] docs: redesign README around benchmark proof --- README.md | 575 +++++------------- .../2026-08-11-readme-benchmark-redesign.md | 213 +++++++ .../2026-08-11-readme-benchmark-redesign.md | 83 +++ 3 files changed, 438 insertions(+), 433 deletions(-) create mode 100644 docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md create mode 100644 docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md diff --git a/README.md b/README.md index 790e165..74e389e 100644 --- a/README.md +++ b/README.md @@ -4,519 +4,228 @@

X - HuggingFace + Hugging Face Discord - WeChat + WeCom

[Website](https://raven.evermind.ai) · [中文](README.zh-CN.md)
-
- # Raven -Raven is **The Self-Improving Agent Harness**, built on [EverOS](https://github.com/EverMind-AI/EverOS), with opt-in Deep Research for multi-source investigation. - -Raven helps agents improve across runs by continuously refining the systems around them: tools, skills, memory, code execution, policies, and working environment. EverOS provides durable user memory, agent memory, and world knowledge across sessions, so successful workflows can evolve into reusable Agent Templates and digital workers. +Raven is a memory-first, self-improving agent harness built on [EverOS](https://github.com/EverMind-AI/EverOS). It brings durable memory, controlled context, proactive execution, reusable skills, deep multi-source research, and local observability into one terminal-native runtime. -**Update:** Raven added Deep Research. Enable it with `raven deep-research enable` -to give the agent access to MiroThinker-backed, multi-source research when a -task needs deeper investigation. +> Raven is pre-alpha. Interfaces and configuration may change quickly. -

- Starting Raven from the command line -

+## Benchmarks -
- Table of Contents +![Raven benchmark results across efficiency, self-evolution, and proactivity](https://github.com/user-attachments/assets/86a64ee7-3a0a-4aa0-969e-374646f604f2) -
+Raven's published benchmark runs show three complementary advantages: -- [Quick Install](#quick-install) -- [What You Can Do in 2 Minutes](#what-you-can-do-in-2-minutes) -- [Messaging Gateways](#messaging-gateways) -- [Why Raven](#why-raven) -- [What Raven Is Built For](#what-raven-is-built-for) -- [Agent Templates](#agent-templates) -- [Useful Commands](#useful-commands) -- [Docs by Goal](#docs-by-goal) -- [Architecture](#architecture) -- [Developer Workflow](#developer-workflow) -- [Status](#status) -- [EverMind Ecosystem](#evermind-ecosystem) -- [Contributing](#contributing) +- **More efficient:** higher scores at both tested compute budgets, including `56.7%` vs `46.8%` at 27B tokens. +- **Self-evolving:** first among the tested self-evolution methods on EvoAgentBench, with a `+6.2pp` lead over the next result. +- **More proactive:** `0.60` F1 on ProAgentBench, `2.4x` the `0.253` comparison result. -
+Sources: [Raven benchmark overview](https://raven.evermind.ai/), [EvoAgentBench methodology](https://evermind-ai.github.io/EvoAgentBench/), and [EverMind benchmark updates](https://x.com/evermind). Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. -
+## Quick Start -## Quick Install +### Install -### Linux, macOS, WSL2 +Linux, macOS, or WSL2: ```bash curl -fsSL https://raven.evermind.ai/install.sh | bash ``` -### Windows (native, PowerShell) - -> **Heads up:** Native Windows runs Raven without WSL. CLI, TUI, gateway, and -> tools install natively. If you would rather use WSL2, the Linux/macOS -> one-liner above works there too. - -Run this in PowerShell: +Native Windows PowerShell: ```powershell irm https://raven.evermind.ai/install.ps1 | iex ``` -On **Windows PowerShell 5.1** (the version built into Windows) that command -fails with `Permanent Redirect`. Use the direct URL instead: +Windows PowerShell 5.1 may reject the redirect. Use the direct installer URL instead: ```powershell irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex ``` -### After installation - -The installer handles everything: uv, Python 3.12, Node.js 22, and Raven. - -Open a new terminal. On Linux, macOS, or WSL2, you can also reload your current -shell: - -```bash -source ~/.bashrc # or: source ~/.zshrc -``` - -Then run: +### Onboard and run ```bash raven onboard raven ``` -Raven supports OpenRouter, OpenAI, Anthropic, Gemini, DeepSeek, GitHub Copilot, -OpenAI Codex OAuth, MiniMax Global/CN OAuth, and custom OpenAI-compatible endpoints. +The bilingual onboarding wizard configures six areas without requiring manual edits to `~/.raven/config.json`: -If setup fails or a provider is not ready, run: +1. LLM provider and model +2. Sandbox or execution location +3. Chat channels +4. EverOS long-term memory +5. Deep Research +6. Cold-start import from other AI tools + +Provider setup includes an in-step connectivity check. Optional steps can be skipped and configured later. If setup is incomplete, run: ```bash raven doctor ``` -### Upgrade an existing installation - -Check for the latest published stable release: - - raven upgrade --check - -Upgrade Raven without resetting configuration, sessions, or memory: - - raven upgrade - -Raven upgrades are user-triggered, not automatic. Editable source installs are -not overwritten; update the checkout and rerun its development setup instead. -On POSIX systems, the command stays synchronous until the helper reports its -final result. On native Windows, it schedules an external helper so the running -executable can exit; wait for the helper's completion message before running -Raven again. - -## What You Can Do in 2 Minutes - -- Start the Raven harness in a terminal-native TUI with `raven` or `raven tui`. -- Run a one-shot shell task with `raven agent -m "..."`. -- Configure providers, sandboxing, channels, and memory with `raven onboard`. -- Enable the MiroThinker deep_research tool with `raven deep-research enable`. -- Open captured LLM/tool/memory spans with `raven tracing`. -- Browse built-in and local SkillForge skills with `raven skill list`. -- Resume, fork, export, or delete previous work with `raven sessions list`. -- Check proactive memory and scheduled nudges with `raven sentinel status`. - -## Messaging Gateways - -Raven currently ships 12 gateway adapters. Use `raven channels list` to see the -adapters available in your local install and `raven gateway` to run the gateway -daemon. - -| Gateway | Adapter id | Notes | -| --- | --- | --- | -| Telegram | `telegram` | Bot-based messaging | -| Slack | `slack` | Workspace messaging | -| Discord | `discord` | Server and bot messaging | -| WhatsApp | `whatsapp` | Uses the bundled TypeScript bridge | -| Matrix | `matrix` | Matrix rooms and direct messages | -| Feishu | `feishu` | Lark/Feishu app integration | -| WeCom | `wecom` | WeCom group and app messaging | -| Mochat | `mochat` | API/socket-based messaging | -| QQ | `qq` | QQ bot integration | -| DingTalk | `dingtalk` | DingTalk stream integration | -| Email | `email` | IMAP/SMTP mailbox integration | -| WeChat | `weixin` | Personal WeChat adapter; `weixin` is the current CLI id | - -## Why Raven - -Most agent tools stop at "LLM + tools + loop." That works for demos, but it -breaks down when the agent becomes part of your daily environment: - -- Long sessions overflow context and lose important details. -- Every turn re-sends the same system prompt, skills, and tool definitions. -- The agent waits passively even when it can see something that needs action. -- Useful workflows stay trapped in chat history instead of becoming reusable - skills. - -Raven treats the harness around the agent as the product, not a thin wrapper or -an edge case. - -Raven's self-improving harness is built around four product bets: - -- **Memory-first harness:** user memory, agent memory, and world knowledge stay - separate, durable, and reusable across sessions. -- **Deep Research as a tool:** long-form, multi-source research can be enabled - with `raven deep-research enable` and then used by the agent when the task - calls for deeper investigation. -- **Self-improving skills:** repeated workflows can become skills, collect - feedback, and evolve instead of staying buried in chat history. -- **Agent Templates:** builders can start from Raven, define an agent for a - scenario, and share it without rebuilding the harness layer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CapabilityRavenTypical tool-based agent
Native terminal productInteractive TUI, CLI, gateway mode, and typed RPC between Python and React/InkUsually a thin command wrapper around a chat loop
Long memoryEverOS-backed memory, local skills, session history, and workspace templatesUsually transient context or provider-side chat history
Context controlCurator and legacy context engines with explicit token budgets and fail-safesUsually truncation, summarization, or hidden prompt heuristics
ProactivitySentinel, scheduler, nudge policy, and deferred decision flowUsually waits until the user types again
Deep ResearchOpt-in MiroThinker-backed deep_research tool enabled with raven deep-research enableUsually external search tabs, ad hoc browser prompts, or one-off research scripts
Skill evolutionDetects reusable procedures, materializes skills, tracks feedback, and evolves themUsually static markdown prompts or manually installed plugins
- -
- -## What Raven Is Built For - -Raven is designed for the workflows where ordinary chat agents and static tool -loops feel too small. - -### 1. Terminal-Native Daily Work - -Raven can run the harness as a native TUI, a direct CLI entry point, or a -gateway-backed runtime. The TUI is not a web shell: it is a React/Ink -application talking to Raven's Python runtime through a typed RPC protocol. - -### 2. Memory That Becomes Useful - -Raven connects the harness to EverOS for long-term user and agent memory. -Sessions, procedures, and reusable patterns can be turned into local skill -material instead of disappearing into old transcripts. - -### 3. Context That Does Not Collapse Under Pressure - -The context stack has a legacy path and a Curator path. Under pressure, the -harness can archive, retrieve, and assemble context with explicit budgets -instead of blindly clipping the oldest messages. - -### 4. Agents That Can Reach Out First - -Sentinel watches events, schedules checks, evaluates whether a nudge is useful, -and routes proactive actions through guardrails. The point is not noisy -notifications; the point is an agent harness that can notice. - -### 5. Skills That Improve - -SkillForge treats skills as procedural memory. It can detect reusable workflows, -write skill files, track execution feedback, and evolve instructions when they -stop working. - -### 6. A Harness That Evolves Itself - -`raven.evolver` runs measured self-evolution against a benchmark: it diagnoses -failing trajectories, designs candidate harness patches as real git commits, -and promotes only what passes statistical gates — with a sealed test set for -an honest generalisation number. One command -(`python -m raven.evolver run --config `), fully resumable. Start at -[raven/evolver/README.md](raven/evolver/README.md). - -### 7. Research and Observability in the Harness - -Raven now includes two opt-in surfaces for deeper work. `raven deep-research` -configures the MiroThinker-backed `deep_research` tool so an agent can run a -multi-source research pass when the task calls for it. `raven tracing` opens a -local dashboard for captured LLM, tool, and memory spans, making it easier to -inspect what happened inside a run without changing the agent workflow. - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
+### Upgrade -## Agent Templates +```bash +raven upgrade --check +raven upgrade +``` -Raven is an Apache-2.0 licensed, self-improving agent harness built by EverMind. -It provides the runtime, memory layer, tools, and Agent Templates for building -custom agents and digital workers. +Upgrades preserve configuration, sessions, and memory. Raven does not update automatically. -Use an Agent Template when you want Raven's harness layer but your own -scenario, personality, workflow policy, skills, integrations, or distribution -model. A template can start as one person's agent and later become a repeatable -digital worker for a team or community. +## Deep Research -Agents, templates, skills, workflows, and modules created with Raven belong to -their creators. Builders may use, modify, commercialize, and share agents built -with Raven or based on Raven Agent Templates under the Apache-2.0 license. +Deep Research gives Raven a dedicated path for open-ended questions that require broad web search, source reading, analysis, and multi-source cross-checking. It uses [MiroThinker](https://miromind.ai/) and returns a self-contained answer with inline citations and references. -We encourage builders to say "Built with Raven" and link back to this -repository. The Raven and EverMind names and logos may not be used to imply -official endorsement unless explicitly approved by EverMind. +Configure it during onboarding or later: -## Useful Commands +```bash +raven deep-research enable +raven deep-research get +``` -| Goal | Command | -| --- | --- | -| Start the native TUI | `raven` or `raven tui` | -| Check the TUI runtime | `raven tui --check` | -| Configure Raven | `raven onboard` | -| Run a one-shot shell task | `raven agent -m "..."` | -| Review providers | `raven provider list` | -| Configure Deep Research | `raven deep-research enable` | -| Inspect Deep Research config | `raven deep-research get` | -| Open tracing dashboard | `raven tracing` | -| List messaging channels | `raven channels list` | -| Start the messaging gateway | `raven gateway` | -| Manage sessions | `raven sessions list` | -| Inspect scheduled jobs | `raven cron list` | -| Browse skills | `raven skill list` | -| Inspect proactive state | `raven sentinel status` | -| Show plugins and memory backend | `raven plugins` | -| Debug sandbox VMs | `raven sandbox list` | -| Show local status | `raven status` | -| Check for Raven updates | `raven upgrade --check` | -| Upgrade Raven | `raven upgrade` | -| Diagnose setup | `raven doctor` | - -## Docs by Goal - -| Goal | Start here | -| --- | --- | -| First-time install and setup | [Quick Install](#quick-install) | -| Source-based development | [Developer Workflow](#developer-workflow) and [docs/dev.md](docs/dev.md) | -| Memory and plugin architecture | [docs/memory-plugin-architecture.md](docs/memory-plugin-architecture.md) | -| Configure Deep Research | `raven deep-research --help` | -| Inspect tracing and observability | `raven tracing` and [docs/TRACING_STANDARD_API.md](docs/TRACING_STANDARD_API.md) | -| Sandbox usage and debugging | [docs/sandbox/usage.md](docs/sandbox/usage.md) | -| Proactivity design | [docs/Proactivity-Plan.md](docs/Proactivity-Plan.md) | -| Benchmark self-evolution | [raven/evolver/README.md](raven/evolver/README.md) | -| Detailed design notes | [docs/README.md](docs/README.md) | +Once configured, Raven can invoke `deep_research` when a task needs more than a quick lookup. Before a paid, minute-scale run, interactive surfaces ask whether to use Deep Research or regular search for that query. -
-
+Delivery adapts to where Raven is running: -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +- **CLI and TUI:** progress streams inline while Raven searches, reads pages, and runs analysis. The completed report is shown directly without being rewritten by the main model. +- **Gateway channels:** the run continues in the background and the completed report is delivered back to the originating conversation. +- **Local archive:** every completed result is saved under `/deep_research/` for later use. -
+Use regular search for a single fact or URL. Use Deep Research for comparisons, landscape reviews, technical investigations, and questions where source agreement matters. -## Architecture +## Tracing -Every turn flows through the Spine: one entry (`submit`), one exit (`emit`), -and per-conversation lanes for ordering and cancellation. Feature engines plug -into the agent loop through explicit handoffs instead of importing each other. +Tracing makes Raven's reasoning path inspectable without sending trace data to a hosted service. Open the local dashboard with: -```text -Channels / TUI / Gateway - | - v - Raven Spine - submit -> lanes -> emit - | - v - Agent Loop - tools · skills · providers - | - +--> Context Engine legacy / curator - +--> Memory Engine EverOS / local skills / SkillForge - +--> Proactive Engine Sentinel / scheduler / nudge policy - +--> TokenWise usage tracking / cache placement / routing - +--> Tracing captured LLM / tool / memory spans - +--> Eval Engine task judgement and coordination - +--> Evolver benchmark-driven harness self-evolution +```bash +raven tracing ``` -### Repo Layout - -```text -raven/ -├── spine/ # Per-turn backbone: submit -> lanes -> emit -├── agent/ # Agent loop, tools, hooks, subagents, context builder -├── channels/ # Telegram, Discord, Slack, Matrix, WhatsApp, WeCom, ... -├── tui_rpc/ # Python side of the native TUI protocol -├── providers/ # LLM provider adapters -├── context_engine/ # Context assembly and Curator path -├── proactive_engine/ # Sentinel, scheduler, nudges, feedback -├── memory_engine/ # EverOS memory, local skills, SkillForge -├── token_wise/ # Usage tracking, cache placement, routing -├── tracing/ # Span capture and local tracing dashboard -├── evolver/ # Benchmark-driven harness self-evolution -├── sandbox/ # Isolated command execution -├── security/ # Trust boundaries and network checks -├── cli/ # `raven` command line entry point -└── config/ # Config schema and update helpers - -ui-tui/ # React/Ink native terminal UI -bridge/ # WhatsApp TypeScript bridge -benchmarks/ # Benchmark adapters, including AppWorld evolver wiring -``` +Each `session.turn` becomes a trace tree containing the work that happened beneath it: -
-
+- LLM calls, models, token usage, cost, latency, and errors +- Tool inputs and outputs +- Subagent runs and parent-child relationships +- Skill reads and injections +- Memory recall, storage, extraction, and consolidation +- Large prompts and results stored as out-of-line artifacts -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +Tracing is enabled by default and is designed to never interrupt Raven's control flow. Spans are stored locally at `~/.raven/traces/logs/audit-spans.log`; set `RAVEN_TRACING_DIR` to move the state directory or `RAVEN_TRACING=0` to disable recording. -
+The schema follows a small, versioned semantic contract. See the [Tracing Standard API](docs/TRACING_STANDARD_API.md) for span names, attributes, artifact behavior, and extension rules. -## Developer Workflow +## Core Systems -Source setup, focused checks, and PR rules live in -[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/dev.md](docs/dev.md). -AI-collaboration rules live in [AGENTS.md](AGENTS.md); `CLAUDE.md` is kept as a -compatibility entry point. +| System | What it adds | +| --- | --- | +| **EverOS memory** | Durable user memory, agent memory, and world knowledge across sessions | +| **Context Engine** | Explicit token budgets and a unified assembly pipeline that preserves the most useful context | +| **Proactivity** | Sentinel observations, scheduled work, nudge policy, and deferred decisions | +| **SkillForge** | Built-in, workspace, EverOS, and mirrored skills with retrieval, feedback, and evolution | +| **Evolver** | Reproducible evaluation loops for improving agents and reusable procedures | +| **Agent Templates** | Shareable starting points for specialized digital workers built on the same harness | -
-
+## Providers and Gateways -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +Raven supports API-key, OAuth, local, and OpenAI-compatible providers. The onboarding catalog includes OpenRouter, OpenAI, Anthropic, Gemini, MiniMax, DeepSeek, Z.ai, DashScope, Moonshot, VolcEngine, SiliconFlow, Groq, AiHubMix, Azure OpenAI, GitHub Copilot OAuth, OpenAI Codex OAuth, Ollama, and hosted vLLM. -
+Twelve gateway adapters connect Raven to Telegram, Slack, Discord, WhatsApp, Matrix, Feishu, WeCom, Mochat, QQ, DingTalk, Email, and WeChat. -## Status +```bash +raven channels list +raven channels enable +raven gateway +``` -Raven is pre-alpha and moving quickly. APIs can change without notice, but the -core product surfaces are already in the repository. +## Command Reference -| Layer | Status | +| Command | Purpose | | --- | --- | -| Native TUI + CLI | Functional | -| Spine runtime | Functional | -| Base agent loop, tools, providers | Functional | -| Context engine | Implemented, still evolving | -| Sentinel proactivity | Implemented, still evolving | -| TokenWise strategies | Implemented | -| SkillForge | Implemented | -| Deep Research tool | Implemented, opt-in configuration | -| Tracing dashboard | Implemented | -| Evolver pipeline | Implemented, benchmark adapters still evolving | -| Eval engine | Partial | - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +| `raven` or `raven tui` | Launch the terminal UI | +| `raven agent -m "..."` | Run a one-shot task | +| `raven onboard` | Configure providers, sandboxing, channels, memory, research, and import | +| `raven status` | Show configuration and runtime status | +| `raven doctor` | Diagnose provider and environment problems | +| `raven tracing` | Open the local trace dashboard | +| `raven sessions list` | Browse, resume, fork, export, or delete sessions | +| `raven skill list` | Inspect the local SkillForge catalog | +| `raven sentinel status` | Inspect proactive memory and scheduled nudges | +| `raven cron list` | Inspect scheduled jobs | +| `raven gateway` | Run messaging gateways | +| `raven upgrade` | Upgrade a managed installation | + +Run `raven --help` or `raven --help` for the complete CLI surface. -
+## Architecture -## EverMind Ecosystem +```text +CLI / TUI / Messaging Gateways + | + v + TUI-RPC / Spine + | + v + Agent Loop + +-------+-------+ + | | | + Providers Tools Subagents + | | | + +--- Context Engine ---+ + | + +-------+--------+ + | | + EverOS Memory SkillForge + | | + +--- Proactivity + Evolver +``` -EverMind is an open-source ecosystem for long-term memory, self-evolving -agents, AI-native interfaces, and memory evaluation. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
EverMind Open-Source Ecosystem
Self-Improving Agent HarnessRaven - the terminal-native agent harness for tools, skills, memory, proactivity, context control, and reusable Agent Templates.
Memory RuntimeEverOS - the memory substrate Raven uses for durable user memory, agent memory, case extraction, skill extraction, and multimodal parsing.
Algorithm EngineEverAlgo - stateless extraction, ranking, parsing, and memory operators that power EverOS.
Hypergraph MemoryHyperMem - hypergraph memory for long-term conversations, with benchmark-backed topic -> episode -> fact retrieval.
BenchmarksEverMemBench · EvoAgentBench - evaluation suites for conversational memory and agent self-evolution.
Long-Context ResearchMSA - Memory Sparse Attention for scalable latent memory and 100M-token contexts.
Personal Memory LayerEverMe - CLI and agent plugin suite for cross-device, cross-agent personal memory.
Developer Integrationsevermem-claude-code · everos-plugins - plugins, skills, and migration tooling for AI coding agents.
- -Together, these repositories form EverMind's research-to-runtime stack: memory -methods, reusable algorithms, benchmark evidence, native agent products, and -practical developer integrations. - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +The Python runtime and React/Ink TUI communicate only through typed TUI-RPC. The Spine carries runtime events, while the Agent Loop coordinates providers, tools, context, memory, skills, subagents, and proactive work. -
+Key directories: -## Contributing +```text +raven/agent/ agent loop, tools, and subagents +raven/channels/ messaging adapters +raven/context_engine/ context assembly and token budgeting +raven/memory_engine/ EverOS integration and local skill memory +raven/proactive_engine/ sentinel, scheduling, and nudges +raven/providers/ model providers and routing +raven/skill_hub/ external skill retrieval +raven/tracing/ instrumentation, storage, and viewer +raven/tui_rpc/ typed runtime-to-TUI boundary +ui-tui/ React/Ink terminal interface +``` + +## Documentation -Raven is early, and useful contributions are welcome across runtime -architecture, TUI polish, provider support, memory workflows, proactivity, -benchmarks, documentation, and issue reports. +- [Documentation index](docs/README.md) +- [Developer workflow](docs/dev.md) +- [Tracing Standard API](docs/TRACING_STANDARD_API.md) +- [Sandbox usage](docs/sandbox/usage.md) +- [Memory plugin architecture](docs/memory-plugin-architecture.md) +- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md) +- [Proactivity implementation](docs/Proactivity-Implementation.md) -Model vendors interested in a first-party integration or an open-source -partnership (as MiniMax already has) are welcome to open an issue and say so. +## EverMind Ecosystem -Before opening a PR: +Raven is part of the [EverMind](https://evermind.ai/) open-source ecosystem. Explore [EverOS](https://github.com/EverMind-AI/EverOS), [EverAlgo](https://github.com/EverMind-AI/EverAlgo), [HyperMem](https://github.com/EverMind-AI/HyperMem), [EvoAgentBench](https://github.com/EverMind-AI/EvoAgentBench), [EverMemBench](https://github.com/EverMind-AI/EverMemBench), and [EverMe](https://github.com/EverMind-AI/EverMe). + +## Contributing -1. Read [AGENTS.md](AGENTS.md). -2. Keep the change scoped. -3. Add or update tests for behavior changes. -4. Run the relevant `make` targets. -5. Use a Conventional Commit title. +Issues and pull requests are welcome. Start with the [developer workflow](docs/dev.md), follow [AGENTS.md](AGENTS.md) for repository rules, and use [GitHub Discussions](https://github.com/EverMind-AI/Raven/discussions) for design conversations. -### License +## License -Raven is licensed under the Apache License 2.0. Portions of the runtime and -TUI layer originated from MIT-licensed upstream projects; their copyright -notices and license texts are retained in [NOTICES.md](NOTICES.md) and -[LICENSES](LICENSES/). +[Apache License 2.0](LICENSE) diff --git a/docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md b/docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md new file mode 100644 index 0000000..02babb4 --- /dev/null +++ b/docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md @@ -0,0 +1,213 @@ +# README Benchmark Redesign Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace Raven's repetitive README narrative with a concise benchmark-led story and detailed, evidence-backed Deep Research and Tracing sections. + +**Architecture:** Build one deterministic benchmark proof board outside the repository, upload it through GitHub User Content, and reference it from a rewritten `README.md`. Keep implementation and generated assets out of git; only Markdown source and planning documents enter the pull request. + +**Tech Stack:** Markdown, HTML/CSS/SVG rendered through local Chrome, WebP or PNG, GitHub User Content, git, gh CLI + +## Global Constraints + +- Do not commit images, SVGs, HTML, manifests, or other generated assets. +- Keep the benchmark image below 500 KB while preserving crisp chart text. +- Use only claims supported by Raven code, an official benchmark, or approved EverMind copy. +- Keep repository prose and commit metadata in English. +- Run `make check-large-files` because README and generated-output references change. +- Update the existing draft pull request instead of creating a second pull request. + +--- + +### Task 1: Build the benchmark proof board + +**Files:** +- Create outside git: `/private/tmp/raven-benchmark-board.html` +- Create outside git: `/private/tmp/raven-benchmark-board.png` +- Create outside git: `/private/tmp/raven-benchmark-board.webp` + +**Interfaces:** +- Consumes: the three user-supplied JPEG drafts and the current Raven banner palette +- Produces: one 1920 x 960 benchmark board suitable for a full-width GitHub README image + +- [ ] **Step 1: Lock the visual system** + +Use this palette and type hierarchy in the temporary HTML: + +```text +canvas: #160f08 +panel: #24170c +panel-soft: #2e1d0f +gold: #f2b51d +gold-muted: #a97d17 +text: #f7f0df +text-muted: #b8aa92 +grid: #4b3825 +headline: ui-monospace, SFMono-Regular, Menlo, monospace +body: Inter, ui-sans-serif, system-ui, sans-serif +``` + +- [ ] **Step 2: Build one three-card board** + +Use the following exact card copy and approved figures: + +```text +01 EFFICIENCY +Better Results, Fewer Tokens +56.7% vs 46.8% at 27B +58.1% vs 47.9% at 397B + +02 SELF-EVOLUTION +Learns Best Among Peers +#1 across four methods ++6.2pp lift on EvoAgentBench + +03 PROACTIVITY +Acts Earlier, Scores Higher +0.60 F1 vs 0.253 +2.4x on ProAgentBench +``` + +Each card contains a compact chart, a large result, a short benchmark label, and no paragraph longer than two lines. Use `OpenClaw` consistently and include `Hermes` only where the supplied comparison names it. + +- [ ] **Step 3: Render and compress** + +Render at 1920 x 960, then compare lossless WebP and optimized PNG. Select the smallest version whose labels remain crisp at a 920px GitHub display width. + +Run: + +```bash +file /private/tmp/raven-benchmark-board.webp +stat -f "%z bytes" /private/tmp/raven-benchmark-board.webp +shasum -a 256 /private/tmp/raven-benchmark-board.webp +``` + +Expected: 1920 x 960 image, fewer than 500000 bytes, and a recorded SHA-256 digest. + +### Task 2: Rewrite the README narrative + +**Files:** +- Modify: `README.md` + +**Interfaces:** +- Consumes: the information architecture in `docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md` +- Produces: a concise README ready to receive the generated GitHub User Content URL + +- [ ] **Step 1: Replace the opening narrative** + +Keep the existing Raven banner and community links. Follow them with one positioning paragraph and a `## Benchmarks` section before installation. The section must include the proof-board image, a one-sentence interpretation, and direct links to the Raven benchmark page and EvoAgentBench methodology. + +- [ ] **Step 2: Collapse onboarding into Quick Start** + +Keep the POSIX and native Windows install commands, then show this exact first-run sequence: + +```bash +raven onboard +raven +raven doctor +``` + +Move upgrade details to one short paragraph and two commands. + +- [ ] **Step 3: Write the Deep Research section** + +Explain opt-in setup, per-query deep-versus-regular choice, MiroThinker execution, report persistence, background delivery, quota awareness, and these commands: + +```bash +raven deep-research enable +raven deep-research get +``` + +- [ ] **Step 4: Write the Tracing section** + +Explain local span capture, the turn-to-memory hierarchy, usage/cost/latency/error inspection, artifact panels, no-throw behavior, local storage, and this command: + +```bash +raven tracing +``` + +- [ ] **Step 5: Consolidate the remaining sections** + +Retain one compact section for core systems, one support line for providers and gateways, the architecture diagram, a compact command table, and links for docs, ecosystem, contributing, status, and license. Remove duplicate feature narratives, full gateway/status/ecosystem tables, repeated back-to-top badges, and the long Agent Templates policy copy. + +### Task 3: Publish the image without adding it to git + +**Files:** +- Modify: `README.md` +- Upload outside git: `/private/tmp/raven-benchmark-board.webp` + +**Interfaces:** +- Consumes: the compressed proof board from Task 1 +- Produces: a public `https://github.com/user-attachments/assets/...` URL referenced by `README.md` + +- [ ] **Step 1: Upload through pull request 280** + +Upload the WebP in the GitHub pull request composer, copy the generated GitHub User Content URL, and ensure the pull request references the attachment so GitHub publishes it. + +- [ ] **Step 2: Replace the temporary README URL** + +Set the alt text to `Raven benchmark results across efficiency, self-evolution, and proactivity` and use the exact asset URL returned by the GitHub composer. + +- [ ] **Step 3: Verify the public attachment** + +Download it without browser authentication and compare the uploaded bytes: + +Download the exact generated asset URL to `/private/tmp/raven-benchmark-board-public.webp`, then run: + +```bash +stat -f "%z bytes" /private/tmp/raven-benchmark-board-public.webp +shasum -a 256 /private/tmp/raven-benchmark-board.webp /private/tmp/raven-benchmark-board-public.webp +``` + +Expected: the download succeeds, remains below 500000 bytes, and both SHA-256 digests match. + +### Task 4: Verify, commit, and update the draft pull request + +**Files:** +- Modify: `README.md` +- Create: `docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md` +- Create: `docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md` + +**Interfaces:** +- Consumes: the finished README and public benchmark asset URL +- Produces: an updated, reviewable draft pull request 280 + +- [ ] **Step 1: Run documentation checks** + +```bash +git diff --check +make check-large-files +``` + +Expected: both commands exit 0. + +- [ ] **Step 2: Review the exact diff** + +```bash +git status --short +git diff -- README.md docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md +``` + +Expected: no generated image or web artifact appears in git status. + +- [ ] **Step 3: Commit the approved scope** + +```bash +git add README.md docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md +git commit -m "docs: redesign README around benchmark proof" +``` + +- [ ] **Step 4: Synchronize and push** + +```bash +git fetch origin main +git merge-tree --write-tree HEAD origin/main +make check-large-files +git push --force-with-lease origin docs/readme_github_banner +``` + +Expected: the branch is based on the latest `origin/main`, checks pass after synchronization, and draft pull request 280 updates. + +- [ ] **Step 5: Update and verify the pull request** + +Update the PR title to `docs: redesign README around benchmark proof`, rewrite the description using `.github/pull_request_template.md`, verify the entire description is ASCII, and preview the rendered README on GitHub. Keep the PR in draft state for maintainer review. diff --git a/docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md b/docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md new file mode 100644 index 0000000..5906692 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md @@ -0,0 +1,83 @@ +# README Benchmark Redesign + +## Goal + +Turn the README from a broad capability catalog into a concise product narrative that proves Raven's value early, then helps a new user install and understand the two newest flagship features: Deep Research and Tracing. + +## Audience + +- Developers evaluating agent harnesses +- Builders deciding whether Raven is credible enough to try +- Contributors looking for architecture and development links + +## Information Architecture + +1. Raven banner, positioning, and community links +2. Benchmark proof board +3. Three-command quick start +4. Deep Research +5. Tracing +6. Core systems: memory, context, proactivity, and skills/evolution +7. Supported providers and messaging gateways +8. Architecture, documentation, ecosystem, and contributing links + +## Benchmark Proof Board + +Create one wide image that consolidates the three supplied benchmark concepts: + +- Better Results, Fewer Tokens +- Learns Best Among Peers +- Acts Earlier, Scores Higher + +The board uses Raven's warm cream, dark brown, and gold palette, with high-contrast typography and explicit legends. It fixes spacing, capitalization, ambiguous zero glyphs, and chart labeling in the supplied drafts. + +Every public claim must be traceable to an official benchmark, Raven property, or approved EverMind statement. The README text below the image links to the relevant methodology or leaderboard. + +The final image is uploaded through GitHub User Content. No image, SVG, HTML, or generated asset is committed to the repository. Target download size is below 500 KB. + +## Deep Research + +Explain the user journey rather than only the integration: + +- Enable with `raven deep-research enable` +- Choose deep or regular search per research-shaped query +- Run broad multi-source research through MiroThinker +- Receive the finished result directly, including citations +- Save a Markdown report in the workspace +- Support background completion and delivery when the gateway is available +- Make time and quota use explicit before the paid engine runs + +## Tracing + +Position Tracing as the way to inspect why Raven acted: + +- Open the local dashboard with `raven tracing` +- Follow turn, model, tool, subagent, skill, context, and memory spans +- Inspect usage, cost, latency, errors, tool input, tool output, and artifacts +- Keep trace data local under the Raven state directory +- Allow tracing to be disabled without affecting the host workflow +- Guarantee that tracing failures do not break the agent loop + +## Content Reduction + +- Merge `What You Can Do in 2 Minutes` into Quick Start +- Merge `Why Raven` and `What Raven Is Built For` +- Remove the duplicate Deep Research update block +- Replace the full gateway table with a compact support line +- Merge `Useful Commands` and `Docs by Goal` +- Reduce Agent Templates to one paragraph +- Reduce status, developer workflow, and ecosystem tables to concise links +- Remove repeated back-to-top badges + +## Verification + +- Review every README claim against code, tests, or an official benchmark source +- Confirm image URL works without authentication +- Confirm downloaded image is below 500 KB and matches the uploaded source hash +- Run `git diff --check` +- Run `make check-large-files` +- Preview the rendered README on GitHub through the draft pull request + +## Rollback + +Revert the README-only commits. The externally hosted image can remain unreferenced without changing repository size. From c57d41c0e9fe23df627853727db454ae8c29ee86 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 16:52:27 +0800 Subject: [PATCH 03/13] docs: optimize README image delivery --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 74e389e..d171a85 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-![Raven banner](https://github.com/user-attachments/assets/f2882578-ff8e-4817-a5d2-6ada414acf1a) +![Raven banner](https://github.com/user-attachments/assets/6c6f585a-21b6-4e7b-9187-acffe59d0c10)

X @@ -21,7 +21,7 @@ Raven is a memory-first, self-improving agent harness built on [EverOS](https:// ## Benchmarks -![Raven benchmark results across efficiency, self-evolution, and proactivity](https://github.com/user-attachments/assets/86a64ee7-3a0a-4aa0-969e-374646f604f2) +![Raven benchmark results across efficiency, self-evolution, and proactivity](https://github.com/user-attachments/assets/97092494-6975-4bde-92ca-32db7bd73f62) Raven's published benchmark runs show three complementary advantages: From d5233b826d3e33284ea4b97f5f9a955e515e0622 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 18:54:21 +0800 Subject: [PATCH 04/13] docs: specify README benchmark table --- ...026-08-11-readme-benchmark-table-design.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md diff --git a/docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md b/docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md new file mode 100644 index 0000000..2da1829 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md @@ -0,0 +1,36 @@ +# README Benchmark Table Design + +## Goal + +Replace the benchmark image with native Markdown so the evidence loads immediately, remains searchable and accessible, and does not depend on a second GitHub User Content image. + +## Scope + +- Keep the Raven hero banner unchanged. +- Remove the benchmark image from `README.md`. +- Replace the benchmark image and the three repetitive summary bullets with one Markdown table. +- Keep the evaluation caveat below the table. +- Keep official source links attached to the benchmark names. + +## Table + +Use three columns so the table remains readable on narrow GitHub layouts: + +| Benchmark | Raven Result | Comparison | +| --- | --- | --- | +| Efficiency | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | +| Self-evolution | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | +| Proactivity | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | + +The final README links `Efficiency` to the Raven benchmark overview, `Self-evolution` to the EvoAgentBench methodology, and `Proactivity` to EverMind benchmark updates. + +## Verification + +- Confirm the README contains only the hero banner image. +- Confirm each benchmark source link is present in the table. +- Run `git diff --check` and `make check-large-files`. +- Preview the rendered table on the pull request branch. + +## Rollback + +Revert the table commit to restore the benchmark image reference. From 1b9543e2ff20038227894d0d1df86e9fefe4aa8d Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 18:59:37 +0800 Subject: [PATCH 05/13] docs: replace benchmark image with table --- README.md | 14 ++-- .../2026-08-11-readme-benchmark-table.md | 81 +++++++++++++++++++ 2 files changed, 87 insertions(+), 8 deletions(-) create mode 100644 docs/superpowers/plans/2026-08-11-readme-benchmark-table.md diff --git a/README.md b/README.md index d171a85..78db31d 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,13 @@ Raven is a memory-first, self-improving agent harness built on [EverOS](https:// ## Benchmarks -![Raven benchmark results across efficiency, self-evolution, and proactivity](https://github.com/user-attachments/assets/97092494-6975-4bde-92ca-32db7bd73f62) +| Benchmark | Raven Result | Comparison | +| --- | --- | --- | +| [Efficiency](https://raven.evermind.ai/) | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | +| [Self-evolution](https://evermind-ai.github.io/EvoAgentBench/) | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | +| [Proactivity](https://x.com/evermind) | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | -Raven's published benchmark runs show three complementary advantages: - -- **More efficient:** higher scores at both tested compute budgets, including `56.7%` vs `46.8%` at 27B tokens. -- **Self-evolving:** first among the tested self-evolution methods on EvoAgentBench, with a `+6.2pp` lead over the next result. -- **More proactive:** `0.60` F1 on ProAgentBench, `2.4x` the `0.253` comparison result. - -Sources: [Raven benchmark overview](https://raven.evermind.ai/), [EvoAgentBench methodology](https://evermind-ai.github.io/EvoAgentBench/), and [EverMind benchmark updates](https://x.com/evermind). Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. +Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. ## Quick Start diff --git a/docs/superpowers/plans/2026-08-11-readme-benchmark-table.md b/docs/superpowers/plans/2026-08-11-readme-benchmark-table.md new file mode 100644 index 0000000..c2ec586 --- /dev/null +++ b/docs/superpowers/plans/2026-08-11-readme-benchmark-table.md @@ -0,0 +1,81 @@ +# README Benchmark Table Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the README benchmark image with a source-linked Markdown table in the same location. + +**Architecture:** Keep the existing `## Benchmarks` section and hero banner. Replace only the benchmark image, summary bullets, and separate source list with one native Markdown table plus the existing evaluation caveat. + +**Tech Stack:** GitHub-flavored Markdown, git, GitHub pull request 280 + +## Global Constraints + +- Keep the Raven hero banner unchanged. +- Do not add an image or generated asset to git. +- Preserve every published benchmark value. +- Link each benchmark name to its official source. +- Update the existing draft pull request 280. + +--- + +### Task 1: Replace the benchmark image with a table + +**Files:** +- Modify: `README.md:21-34` +- Create: `docs/superpowers/plans/2026-08-11-readme-benchmark-table.md` + +**Interfaces:** +- Consumes: the existing benchmark values and source URLs in `README.md` +- Produces: a native Markdown table rendered by GitHub without a benchmark image request + +- [ ] **Step 1: Replace the image and bullets** + +Use this exact table under `## Benchmarks`: + +```markdown +| Benchmark | Raven Result | Comparison | +| --- | --- | --- | +| [Efficiency](https://raven.evermind.ai/) | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | +| [Self-evolution](https://evermind-ai.github.io/EvoAgentBench/) | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | +| [Proactivity](https://x.com/evermind) | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | +``` + +Keep this sentence immediately below the table: + +```markdown +Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. +``` + +- [ ] **Step 2: Verify the Markdown diff** + +Run: + +```bash +git diff --check +rg -n 'user-attachments/assets|^\\| \\[.*\\]\\(https://' README.md +make check-large-files +``` + +Expected: the only `user-attachments` URL left in `README.md` is the Raven hero banner, all three benchmark rows contain source links, and both repository checks exit 0. + +- [ ] **Step 3: Commit the README and plan** + +```bash +git add README.md docs/superpowers/plans/2026-08-11-readme-benchmark-table.md +git commit -m "docs: replace benchmark image with table" +``` + +- [ ] **Step 4: Synchronize and push** + +```bash +git fetch origin main +git merge-tree --write-tree HEAD origin/main +make check-large-files +git push origin docs/readme_github_banner +``` + +Expected: the branch is based on the latest `origin/main`, the checks pass, and pull request 280 contains the table commit. + +- [ ] **Step 5: Preview pull request 280** + +Open the branch README on GitHub, confirm the table occupies the former benchmark image position, and confirm all pull request checks pass. From d85e1bb508647c3f8cd84d30a8d8bed47a527f77 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 19:13:33 +0800 Subject: [PATCH 06/13] docs: synchronize Chinese README redesign --- README.zh-CN.md | 550 ++++++++++++------------------------------------ 1 file changed, 139 insertions(+), 411 deletions(-) diff --git a/README.zh-CN.md b/README.zh-CN.md index 03f8b36..1c21c90 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,501 +1,229 @@

-Raven banner +![Raven banner](https://github.com/user-attachments/assets/6c6f585a-21b6-4e7b-9187-acffe59d0c10)

X - HuggingFace + Hugging Face Discord - WeChat + WeCom

[官网](https://raven.evermind.ai) · [English](README.md)
-
- # Raven -Raven 是构建在 [EverOS](https://github.com/EverMind-AI/EverOS) 之上的 -**The Self-Improving Agent Harness**，并内置可选 Deep Research，用于多来源深度研究。 - -Raven 会持续迭代支撑 Agent 的 harness：tools、skills、memory、code execution -runtime、policies 和工作环境。EverOS 为这个 harness 提供跨会话持久存在的用户 -记忆、Agent 记忆和世界知识，让每一次运行都能改进 Agent 的行动方式、知识状态， -并把可重复工作流沉淀成可复用 Agent Templates 和 digital workers。 +Raven 是一个构建在 [EverOS](https://github.com/EverMind-AI/EverOS) 之上的、记忆优先且能自我改进的 Agent Harness。它把持久记忆、可控上下文、主动执行、可复用技能、多来源深度研究和本地可观测性整合进一个终端原生运行时。 -**Update：** Raven 新增 Deep Research。运行 `raven deep-research enable` 后， -Agent 可以在需要深度调查的任务中使用 MiroThinker-backed、多来源 research tool。 +> Raven 目前处于 pre-alpha 阶段，接口和配置可能快速变化。 -

- 从命令行启动 Raven -

+## 基准测试 -
- 目录 - -
- -- [快速安装](#快速安装) -- [2 分钟能做什么](#2-分钟能做什么) -- [消息网关](#消息网关) -- [为什么是 Raven](#为什么是-raven) -- [Raven 适合什么](#raven-适合什么) -- [Agent Templates](#agent-templates) -- [常用命令](#常用命令) -- [按目标阅读文档](#按目标阅读文档) -- [架构](#架构) -- [开发工作流](#开发工作流) -- [当前状态](#当前状态) -- [EverMind 生态](#evermind-生态) -- [参与贡献](#参与贡献) +| 基准测试 | Raven 结果 | 对比 | +| --- | --- | --- | +| [效率](https://raven.evermind.ai/) | 27B 下为 `56.7%`；397B 下为 `58.1%` | Hermes 为 `46.8%` / `47.9%`；27B 下领先 `+9.9pp` | +| [自我进化](https://evermind-ai.github.io/EvoAgentBench/) | EvoAgentBench 排名 `#1` | 在四种方法中领先下一名 `+6.2pp` | +| [主动性](https://x.com/evermind) | ProAgentBench F1 为 `0.60` | 是 Hermes/OpenClaw `0.253` 的 `2.4x` | -
+以上结果对应已发布的测试配置；模型、任务集和评测协议都会影响最终结果。 -
+## 快速开始 -## 快速安装 +### 安装 -### Linux、macOS、WSL2 +Linux、macOS 或 WSL2： ```bash curl -fsSL https://raven.evermind.ai/install.sh | bash ``` -### Windows（原生 PowerShell） - -> **提示：** 原生 Windows 可以不经过 WSL 运行 Raven。CLI、TUI、gateway 和 -> tools 都会在 Windows 下原生安装。如果你更想用 WSL2，也可以直接使用上面的 -> Linux/macOS 一键安装命令。 - -在 PowerShell 里运行： +原生 Windows PowerShell： ```powershell irm https://raven.evermind.ai/install.ps1 | iex ``` -在 **Windows PowerShell 5.1**（Windows 自带的默认版本）下，上面的命令会报 -`Permanent Redirect`，请改用直连地址： +Windows PowerShell 5.1 可能拒绝重定向，请改用直连安装地址： ```powershell irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex ``` -### 安装完成后 - -安装器会处理全部依赖：uv、Python 3.12、Node.js 22 和 Raven。 - -打开一个新终端。Linux、macOS 或 WSL2 也可以刷新当前 shell： - -```bash -source ~/.bashrc # 或：source ~/.zshrc -``` - -然后运行： +### 完成引导并运行 ```bash raven onboard raven ``` -Raven 支持 OpenRouter、OpenAI、Anthropic、Gemini、DeepSeek、GitHub Copilot、 -OpenAI Codex OAuth、MiniMax Global/CN OAuth，以及自定义 OpenAI-compatible endpoints。 +双语 onboarding 向导会配置六个方面，无需手动编辑 `~/.raven/config.json`： + +1. LLM provider 和模型 +2. Sandbox 或执行位置 +3. 聊天渠道 +4. EverOS 长期记忆 +5. Deep Research +6. 从其他 AI 工具进行冷启动导入 -如果配置失败，或者 provider 还没有准备好，运行： +Provider 配置包含向导内连通性检查。可选步骤可以跳过，之后再配置。如果设置尚未完成，请运行： ```bash raven doctor ``` -### 升级现有安装 +### 升级 -检查最新发布的稳定版本： +```bash +raven upgrade --check +raven upgrade +``` - raven upgrade --check +升级会保留配置、sessions 和 memory。Raven 不会自动更新。 -升级 Raven，同时保留现有配置、sessions 和 memory： +## Deep Research - raven upgrade +Deep Research 为需要广泛网页搜索、来源阅读、分析和多来源交叉验证的开放式问题提供专用路径。它使用 [MiroThinker](https://miromind.ai/)，返回带有行内引用和参考来源的完整答案。 -Raven 升级需要由用户主动触发，不会自动进行。Raven 会拒绝覆盖 editable source -installs；请更新源码 checkout，并重新运行对应的开发环境配置。 -在 POSIX 系统上，命令会同步等待 helper 输出最终结果。原生 Windows 会先调度外部 -helper，让当前运行的可执行文件退出；请等 helper 输出完成消息后再运行 Raven。 +可以在 onboarding 时配置，也可以稍后启用： -## 2 分钟能做什么 +```bash +raven deep-research enable +raven deep-research get +``` -- 用 `raven` 或 `raven tui` 启动 Raven 的终端原生 harness。 -- 用 `raven agent -m "..."` 执行一次性 shell 任务。 -- 用 `raven onboard` 配置 providers、sandbox、channels 和 memory。 -- 用 `raven deep-research enable` 启用 MiroThinker-backed deep_research tool。 -- 用 `raven tracing` 打开 LLM/tool/memory spans 的本地 tracing dashboard。 -- 用 `raven skill list` 浏览内置和本地 SkillForge skills。 -- 用 `raven sessions list` 恢复、fork、导出或删除之前的工作。 -- 用 `raven sentinel status` 查看主动记忆和 scheduled nudges 状态。 +配置完成后，当任务需要的不只是快速查询时，Raven 可以调用 `deep_research`。在开始一次付费、分钟级的研究任务前，交互式界面会询问本次查询使用 Deep Research 还是常规搜索。 -## 消息网关 +结果会根据 Raven 的运行位置选择不同交付方式： -Raven 目前内置 12 个 gateway adapters。用 `raven channels list` 查看本地安装中 -可用的 adapters，用 `raven gateway` 启动 gateway daemon。 +- **CLI 和 TUI：** Raven 会在搜索、阅读页面和分析时持续显示进度；完成后的报告会直接展示，不再由主模型改写。 +- **Gateway 渠道：** 任务在后台继续运行，完成后的报告会发送回原始会话。 +- **本地归档：** 每次完成的结果都会保存在 `/deep_research/`，便于之后使用。 -| Gateway | Adapter id | 说明 | -| --- | --- | --- | -| Telegram | `telegram` | Bot-based messaging | -| Slack | `slack` | Workspace messaging | -| Discord | `discord` | Server 和 bot messaging | -| WhatsApp | `whatsapp` | 使用内置 TypeScript bridge | -| Matrix | `matrix` | Matrix rooms 和 direct messages | -| Feishu | `feishu` | Lark/Feishu app integration | -| WeCom | `wecom` | 企业微信群和 app messaging | -| Mochat | `mochat` | API/socket-based messaging | -| QQ | `qq` | QQ bot integration | -| DingTalk | `dingtalk` | DingTalk stream integration | -| Email | `email` | IMAP/SMTP mailbox integration | -| WeChat | `weixin` | 个人微信 adapter；`weixin` 是当前 CLI id | - -## 为什么是 Raven - -大多数 Agent 工具只做到 "LLM + tools + loop"。Demo 阶段够用，但一旦进入 -真实日常工作就会遇到这些问题： - -- 长会话撑爆上下文，重要信息开始丢失。 -- 每轮都重复发送 system prompt、skills 和工具定义，Token 成本失控。 -- Agent 永远被动等待输入，即使它已经看到有事需要处理。 -- 有用的工作流留在聊天记录里，没有变成可复用技能。 - -Raven 把 Agent 周围的 harness 当成产品本身，而不是一层薄包装或边缘 case。 - -Raven 的 self-improving harness 围绕四个产品判断构建： - -- **Memory-first harness：** 用户记忆、Agent 记忆和世界知识彼此独立、持久存在，并且 - 可以跨会话复用。 -- **Deep Research as a tool：** 长篇、多来源研究可以通过 `raven deep-research enable` - 启用，并在任务需要更深调查时交给 Agent 使用。 -- **Self-improving skills：** 重复工作流可以沉淀成 skills，记录反馈，并在失效时 - 继续进化，而不是埋在聊天记录里。 -- **Agent Templates：** 构建者可以从 Raven 出发，为具体场景定义一个 Agent，并在 - 不重做底层 harness layer 的情况下分享出去。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
能力Raven常见工具型 Agent
原生终端产品交互式 TUI、CLI、Gateway 模式，以及 Python 与 React/Ink 之间的 typed RPC通常只是聊天循环外面的一层命令包装
长期记忆EverOS-backed memory、本地 skills、session history 和 workspace templates通常是临时上下文或 provider 侧聊天历史
上下文控制Curator 与 legacy context engines，显式 token budgets 和 fail-safes通常是截断、摘要或隐藏 prompt heuristic
主动性Sentinel、scheduler、nudge policy 和 deferred decision flow通常等用户再次输入
Deep Research可选的 MiroThinker-backed deep_research tool，通过 raven deep-research enable 启用通常依赖外部搜索标签页、临时 browser prompt 或一次性 research scripts
Skill 进化识别可复用流程，生成 skill，追踪反馈，并在失效时进化通常是静态 markdown prompt 或手动安装插件
- -
- -## Raven 适合什么 - -Raven 面向那些普通聊天 Agent 和静态工具循环显得太轻、太浅、太短的工作流。 - -### 1. 终端原生日常工作 - -Raven 可以把 harness 作为 native TUI、直接 CLI 入口或 gateway-backed runtime -运行。TUI 不是网页 shell，而是一个 React/Ink 应用，通过 typed RPC 与 Python -runtime 通信。 - -### 2. 会变得有用的记忆 - -Raven 将 harness 连接到 EverOS，作为长期用户记忆与 Agent 记忆层。Sessions、 -procedures 和可复用模式可以转成本地 skill 材料，而不是消失在旧 transcript 里。 - -### 3. 不会在压力下崩掉的上下文 - -Context stack 有 legacy path 和 Curator path。在 token 压力下，这个 harness -可以归档、检索并组装上下文，而不是盲目裁掉最旧消息。 - -### 4. 会主动开口的 Agent - -Sentinel 监听事件、调度检查、判断 nudge 是否有用，并通过 guardrails 路由 -主动动作。目标不是制造通知噪音，而是让这个 Agent Harness 真的能主动发现需要处理的事。 - -### 5. 会进化的 Skills - -SkillForge 把 skills 当成 procedural memory。它可以识别可复用工作流、写入 -skill 文件、追踪执行反馈，并在 instruction 失效时进化它。 - -### 6. 会自我进化的 Harness - -`raven.evolver` 可以基于 benchmark 做可度量的 harness self-evolution：诊断失败 -trajectories，把候选 harness patch 设计成真实 git commits，并且只提升通过统计 -gate 的改动。它带有 sealed test set，用来保留诚实的泛化结果。一个命令 -（`python -m raven.evolver run --config `）即可运行，并支持完整 resume。 -从 [raven/evolver/README.md](raven/evolver/README.md) 开始。 - -### 7. Harness 内的研究与可观测性 - -Raven 现在提供两个可选入口来支持更深的工作：`raven deep-research` 用于配置 -MiroThinker-backed `deep_research` tool，让 Agent 在任务需要时执行多来源 research； -`raven tracing` 会打开本地 dashboard，查看已捕获的 LLM、tool 和 memory spans， -方便在不改变 agent workflow 的情况下复盘一次运行内部发生了什么。 - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +查询单个事实或 URL 时使用常规搜索；做方案对比、行业综述、技术调研，以及需要核对多个来源一致性的问题时使用 Deep Research。 -
+## Tracing + +Tracing 让 Raven 的推理路径可以被检查，同时不会把 trace 数据发送到托管服务。运行以下命令打开本地 dashboard： -## Agent Templates +```bash +raven tracing +``` -Raven 是 EverMind 构建的 Apache-2.0 licensed、self-improving agent harness。 -它提供 runtime、memory layer、tools 和 Agent Templates，用来构建定制 Agent -和 digital workers。 +每个 `session.turn` 都会成为一棵 trace tree，展示该轮之下发生的工作： -当你想复用 Raven 的 harness layer，但又需要自己的场景、人格、workflow -policy、skills、integrations 或分发方式时，就可以从 Agent Template 开始。 -一个 template 可以先是某个人的个人 Agent，之后再变成团队或社区可复用的 -digital worker。 +- LLM 调用、模型、token 使用量、成本、延迟和错误 +- Tool 输入和输出 +- Subagent 运行及其父子关系 +- Skill 读取和注入 +- Memory recall、存储、提取和 consolidation +- 以独立 artifact 保存的大型 prompts 和结果 -用 Raven 创建的 agents、templates、skills、workflows 和 modules 属于它们的 -创建者。构建者可以在 Apache-2.0 license 下使用、修改、商业化和分享基于 Raven -或 Raven Agent Templates 创建的 Agent。 +Tracing 默认启用，并且不会中断 Raven 的控制流。Spans 保存在本地 `~/.raven/traces/logs/audit-spans.log`；可以通过 `RAVEN_TRACING_DIR` 移动状态目录，或设置 `RAVEN_TRACING=0` 关闭记录。 -我们鼓励构建者标注 "Built with Raven" 并链接回这个仓库。未经 EverMind 明确 -授权，不得使用 Raven 或 EverMind 的名称和 logo 暗示官方背书。 +Schema 遵循一个精简、带版本的语义契约。Span 名称、属性、artifact 行为和扩展规则请参阅 [Tracing Standard API](docs/TRACING_STANDARD_API.md)。 -## 常用命令 +## 核心系统 -| 目标 | 命令 | -| --- | --- | -| 启动原生 TUI | `raven` 或 `raven tui` | -| 检查 TUI runtime | `raven tui --check` | -| 配置 Raven | `raven onboard` | -| 执行一次性 shell 任务 | `raven agent -m "..."` | -| 查看 providers | `raven provider list` | -| 配置 Deep Research | `raven deep-research enable` | -| 查看 Deep Research 配置 | `raven deep-research get` | -| 打开 tracing dashboard | `raven tracing` | -| 列出消息渠道 | `raven channels list` | -| 启动 messaging gateway | `raven gateway` | -| 管理 sessions | `raven sessions list` | -| 查看 scheduled jobs | `raven cron list` | -| 浏览 skills | `raven skill list` | -| 查看 proactive state | `raven sentinel status` | -| 查看 plugins 和 memory backend | `raven plugins` | -| 调试 sandbox VMs | `raven sandbox list` | -| 查看本地状态 | `raven status` | -| 检查 Raven 更新 | `raven upgrade --check` | -| 升级 Raven | `raven upgrade` | -| 诊断配置 | `raven doctor` | - -## 按目标阅读文档 - -| 目标 | 从这里开始 | +| 系统 | 能力 | | --- | --- | -| 第一次安装和配置 | [快速安装](#快速安装) | -| 源码开发 | [开发工作流](#开发工作流) 和 [docs/dev.md](docs/dev.md) | -| Memory 和 plugin 架构 | [docs/memory-plugin-architecture.md](docs/memory-plugin-architecture.md) | -| 配置 Deep Research | `raven deep-research --help` | -| 查看 tracing 和 observability | `raven tracing` 和 [docs/TRACING_STANDARD_API.md](docs/TRACING_STANDARD_API.md) | -| Sandbox 使用和调试 | [docs/sandbox/usage.md](docs/sandbox/usage.md) | -| Proactivity 设计 | [docs/Proactivity-Plan.md](docs/Proactivity-Plan.md) | -| Benchmark self-evolution | [raven/evolver/README.md](raven/evolver/README.md) | -| 详细设计文档 | [docs/README.md](docs/README.md) | +| **EverOS 记忆** | 跨 sessions 持久保存用户记忆、Agent 记忆和世界知识 | +| **Context Engine** | 通过明确的 token 预算和统一组装流程保留最有价值的上下文 | +| **Proactivity** | Sentinel observations、计划任务、nudge policy 和延迟决策 | +| **SkillForge** | 内置、workspace、EverOS 和镜像 skills，支持检索、反馈和进化 | +| **Evolver** | 用于改进 Agent 和可复用流程的可复现评测循环 | +| **Agent Templates** | 基于同一套 harness 构建专用 digital workers 的可分享起点 | -
-
+## Providers 和 Gateways -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +Raven 支持 API key、OAuth、本地和 OpenAI-compatible providers。Onboarding catalog 包括 OpenRouter、OpenAI、Anthropic、Gemini、MiniMax、DeepSeek、Z.ai、DashScope、Moonshot、VolcEngine、SiliconFlow、Groq、AiHubMix、Azure OpenAI、GitHub Copilot OAuth、OpenAI Codex OAuth、Ollama 和托管 vLLM。 -
+十二个 gateway adapters 可以把 Raven 接入 Telegram、Slack、Discord、WhatsApp、Matrix、Feishu、WeCom、Mochat、QQ、DingTalk、Email 和 WeChat。 -## 架构 +```bash +raven channels list +raven channels enable +raven gateway +``` -每个 turn 都流经 Spine：一个入口 `submit`，一个出口 `emit`，并用 -per-conversation lanes 处理顺序与取消。各个 feature engine 通过显式 handoff -接入 Agent loop，而不是互相 import。 +## 常用命令 -```text -Channels / TUI / Gateway - | - v - Raven Spine - submit -> lanes -> emit - | - v - Agent Loop - tools · skills · providers - | - +--> Context Engine legacy / curator - +--> Memory Engine EverOS / local skills / SkillForge - +--> Proactive Engine Sentinel / scheduler / nudge policy - +--> TokenWise usage tracking / cache placement / routing - +--> Tracing captured LLM / tool / memory spans - +--> Eval Engine task judgement and coordination - +--> Evolver benchmark-driven harness self-evolution -``` +| 命令 | 用途 | +| --- | --- | +| `raven` 或 `raven tui` | 启动终端 UI | +| `raven agent -m "..."` | 运行一次性任务 | +| `raven onboard` | 配置 providers、sandboxing、channels、memory、research 和 import | +| `raven status` | 查看配置和运行时状态 | +| `raven doctor` | 诊断 provider 和环境问题 | +| `raven tracing` | 打开本地 trace dashboard | +| `raven sessions list` | 浏览、恢复、fork、导出或删除 sessions | +| `raven skill list` | 查看本地 SkillForge catalog | +| `raven sentinel status` | 查看主动记忆和计划 nudges | +| `raven cron list` | 查看计划任务 | +| `raven gateway` | 运行消息 gateways | +| `raven upgrade` | 升级受管理的安装 | + +运行 `raven --help` 或 `raven --help` 查看完整 CLI。 -### 仓库结构 +## 架构 ```text -raven/ -├── spine/ # Per-turn backbone: submit -> lanes -> emit -├── agent/ # Agent loop, tools, hooks, subagents, context builder -├── channels/ # Telegram, Discord, Slack, Matrix, WhatsApp, WeCom, ... -├── tui_rpc/ # Native TUI protocol 的 Python 侧 -├── providers/ # LLM provider adapters -├── context_engine/ # Context assembly 与 Curator path -├── proactive_engine/ # Sentinel, scheduler, nudges, feedback -├── memory_engine/ # EverOS memory, local skills, SkillForge -├── token_wise/ # Usage tracking, cache placement, routing -├── tracing/ # Span capture 和本地 tracing dashboard -├── evolver/ # Benchmark-driven harness self-evolution -├── sandbox/ # Isolated command execution -├── security/ # Trust boundaries and network checks -├── cli/ # `raven` command line entry point -└── config/ # Config schema and update helpers - -ui-tui/ # React/Ink 原生终端 UI -bridge/ # WhatsApp TypeScript bridge -benchmarks/ # Benchmark adapters，包括 AppWorld evolver wiring +CLI / TUI / Messaging Gateways + | + v + TUI-RPC / Spine + | + v + Agent Loop + +-------+-------+ + | | | + Providers Tools Subagents + | | | + +--- Context Engine ---+ + | + +-------+--------+ + | | + EverOS Memory SkillForge + | | + +--- Proactivity + Evolver ``` -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- -## 开发工作流 +Python runtime 和 React/Ink TUI 只通过 typed TUI-RPC 通信。Spine 传递 runtime events，Agent Loop 负责协调 providers、tools、context、memory、skills、subagents 和主动任务。 -源码开发、focused checks 和 PR 规则放在 -[CONTRIBUTING.md](CONTRIBUTING.md) 与 [docs/dev.md](docs/dev.md) 里维护。 -AI 协作规则放在 [AGENTS.md](AGENTS.md)；`CLAUDE.md` 作为兼容入口保留。 +关键目录： -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- -## 当前状态 +```text +raven/agent/ agent loop、tools 和 subagents +raven/channels/ messaging adapters +raven/context_engine/ context assembly 和 token budgeting +raven/memory_engine/ EverOS integration 和 local skill memory +raven/proactive_engine/ sentinel、scheduling 和 nudges +raven/providers/ model providers 和 routing +raven/skill_hub/ external skill retrieval +raven/tracing/ instrumentation、storage 和 viewer +raven/tui_rpc/ typed runtime-to-TUI boundary +ui-tui/ React/Ink terminal interface +``` -Raven 仍处于 pre-alpha，变化会很快。API 可能调整，但核心产品面已经在仓库里。 +## 文档 -| 层级 | 状态 | -| --- | --- | -| Native TUI + CLI | 可用 | -| Spine runtime | 可用 | -| Base agent loop, tools, providers | 可用 | -| Context engine | 已实现，持续演进 | -| Sentinel proactivity | 已实现，持续演进 | -| TokenWise strategies | 已实现 | -| SkillForge | 已实现 | -| Deep Research tool | 已实现，可选配置 | -| Tracing dashboard | 已实现 | -| Evolver pipeline | 已实现，benchmark adapters 持续演进 | -| Eval engine | 部分完成 | - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
+- [文档索引](docs/README.md) +- [开发工作流](docs/dev.md) +- [Tracing Standard API](docs/TRACING_STANDARD_API.md) +- [Sandbox 使用说明](docs/sandbox/usage.md) +- [Memory plugin 架构](docs/memory-plugin-architecture.md) +- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md) +- [Proactivity 实现](docs/Proactivity-Implementation.md) ## EverMind 生态 -EverMind 是一个面向长期记忆、自进化 Agent、AI-native interfaces 和记忆评测的开源生态。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
EverMind Open-Source Ecosystem
Self-Improving Agent HarnessRaven - 终端原生 Agent Harness，负责 tools、skills、memory、proactivity、context control 和可复用 Agent Templates。
Memory RuntimeEverOS - Raven 默认接入的 memory substrate，提供长期用户记忆、Agent 记忆、case/skill 提取和 multimodal parsing。
Algorithm EngineEverAlgo - stateless extraction、ranking、parsing 和 memory operators，为 EverOS 提供算法能力。
Hypergraph MemoryHyperMem - 面向长期对话的 hypergraph memory，拥有 benchmark-backed topic -> episode -> fact retrieval。
BenchmarksEverMemBench · EvoAgentBench - conversational memory 和 Agent self-evolution 的评测套件。
Long-Context ResearchMSA - Memory Sparse Attention，用于可扩展 latent memory 和 100M-token contexts。
Personal Memory LayerEverMe - CLI 和 Agent plugin suite，用于跨设备、跨 Agent 的个人记忆。
Developer Integrationsevermem-claude-code · everos-plugins - AI coding agents 的 plugins、skills 和 migration tooling。
- -这些仓库共同构成 EverMind 的 research-to-runtime stack：记忆方法、可复用算法、 -benchmark evidence、native agent products 和开发者集成。 - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
+Raven 是 [EverMind](https://evermind.ai/) 开源生态的一部分。你可以继续了解 [EverOS](https://github.com/EverMind-AI/EverOS)、[EverAlgo](https://github.com/EverMind-AI/EverAlgo)、[HyperMem](https://github.com/EverMind-AI/HyperMem)、[EvoAgentBench](https://github.com/EverMind-AI/EvoAgentBench)、[EverMemBench](https://github.com/EverMind-AI/EverMemBench) 和 [EverMe](https://github.com/EverMind-AI/EverMe)。 ## 参与贡献 -Raven 还很早。欢迎在 runtime architecture、TUI polish、provider support、 -memory workflows、proactivity、benchmarks、documentation 和 issue reports 上贡献。 - -提交 PR 前： - -1. 阅读 [AGENTS.md](AGENTS.md)。 -2. 保持改动范围清晰。 -3. 行为变化需要添加或更新测试。 -4. 运行相关 `make` targets。 -5. 使用 Conventional Commit 标题。 +欢迎提交 issues 和 pull requests。请先阅读[开发工作流](docs/dev.md)，按照 [AGENTS.md](AGENTS.md) 中的仓库规则进行协作，并在 [GitHub Discussions](https://github.com/EverMind-AI/Raven/discussions) 讨论设计方案。 -### 许可证 +## 许可证 -Raven 使用 Apache License 2.0。部分 runtime 和 TUI layer 来自 MIT 协议的 -上游项目；相关 copyright notices 与 license texts 保留在 -[NOTICES.md](NOTICES.md) 和 [LICENSES](LICENSES/) 中。 +[Apache License 2.0](LICENSE) From 8543bcdb69bbb9755d5dc7420e769d41c9034c2c Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 20:14:46 +0800 Subject: [PATCH 07/13] docs: specify README welcome screen showcase --- ...026-08-11-readme-welcome-screens-design.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md diff --git a/docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md b/docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md new file mode 100644 index 0000000..9b2bdef --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md @@ -0,0 +1,39 @@ +# README Welcome Screens Design + +## Goal + +Show the first Raven terminal screen directly below the benchmark table so readers can see the installed product before starting the setup instructions. + +## Layout + +Add a short introductory sentence followed by a two-column GitHub-flavored Markdown table: + +| Light theme | Dark theme | +| --- | --- | +| Light welcome screen | Dark welcome screen | + +Use equivalent translated copy in `README.zh-CN.md`. Keep the section between the benchmark caveat and Quick Start in both files. + +## Image Delivery + +- Resize each source screenshot to 1600 pixels wide while preserving aspect ratio. +- Re-encode as JPEG at quality 82 and keep each file below 500 KB. +- Upload both files through GitHub User Content. +- Reference only the public attachment URLs from the READMEs. +- Do not add image files to git. + +## Accessibility + +Use descriptive alt text that identifies Raven's terminal welcome screen and the displayed theme. Keep visible column labels so the comparison remains understandable if images load slowly. + +## Verification + +- Confirm both public attachment URLs load successfully. +- Confirm both files are below 500 KB. +- Confirm the English and Chinese READMEs use the same two URLs and matching placement. +- Preview the rendered table on GitHub. +- Run `git diff --check` and `make check-large-files`. + +## Rollback + +Remove the introductory sentence and image table from both READMEs. The unreferenced GitHub User Content attachments do not affect repository size. From fbf244744eb41bdd1e9f820be13678b50df4d889 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 11 Aug 2026 20:21:00 +0800 Subject: [PATCH 08/13] docs: add terminal welcome screen showcase --- README.md | 6 ++ README.zh-CN.md | 6 ++ .../2026-08-11-readme-welcome-screens.md | 80 +++++++++++++++++++ 3 files changed, 92 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-11-readme-welcome-screens.md diff --git a/README.md b/README.md index 78db31d..2e5c072 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,12 @@ Raven is a memory-first, self-improving agent harness built on [EverOS](https:// Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. +Install Raven, run `raven` in your terminal, and this is the welcome screen you will see: + +| Light theme | Dark theme | +| --- | --- | +| ![Raven terminal welcome screen in light theme](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven terminal welcome screen in dark theme](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | + ## Quick Start ### Install diff --git a/README.zh-CN.md b/README.zh-CN.md index 1c21c90..6383d02 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -29,6 +29,12 @@ Raven 是一个构建在 [EverOS](https://github.com/EverMind-AI/EverOS) 之上 以上结果对应已发布的测试配置；模型、任务集和评测协议都会影响最终结果。 +安装 Raven 后，在终端运行 `raven`，你会看到下面的欢迎界面： + +| 浅色主题 | 深色主题 | +| --- | --- | +| ![Raven 终端浅色主题欢迎界面](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven 终端深色主题欢迎界面](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | + ## 快速开始 ### 安装 diff --git a/docs/superpowers/plans/2026-08-11-readme-welcome-screens.md b/docs/superpowers/plans/2026-08-11-readme-welcome-screens.md new file mode 100644 index 0000000..64e88ad --- /dev/null +++ b/docs/superpowers/plans/2026-08-11-readme-welcome-screens.md @@ -0,0 +1,80 @@ +# README Welcome Screens Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add optimized light and dark Raven terminal welcome screens below the benchmark table in both READMEs. + +**Architecture:** Produce two 1600-pixel-wide JPEG derivatives outside the repository, upload them through GitHub User Content, and reference the resulting public URLs from a two-column Markdown table. Keep the English and Chinese documents structurally aligned and leave git free of image binaries. + +**Tech Stack:** macOS `sips`, GitHub User Content, GitHub-flavored Markdown, git, GitHub pull request 280 + +## Global Constraints + +- Resize each source screenshot to 1600 pixels wide while preserving aspect ratio. +- Re-encode each screenshot as JPEG at quality 82. +- Keep each delivered image below 500 KB. +- Do not add image binaries to git. +- Use the same two public GitHub User Content URLs in both READMEs. +- Place the showcase after the benchmark caveat and before Quick Start. + +--- + +### Task 1: Publish and embed the terminal welcome screens + +**Files:** +- Modify: `README.md:30-32` +- Modify: `README.zh-CN.md:30-32` +- Create outside git: `/private/tmp/raven-welcome-light.jpg` +- Create outside git: `/private/tmp/raven-welcome-dark.jpg` + +**Interfaces:** +- Consumes: the two user-provided JPEG screenshots and the existing benchmark sections +- Produces: two public attachment URLs and matching English and Chinese Markdown tables + +- [ ] **Step 1: Create optimized derivatives** + +Use `sips --resampleWidth 1600 --setProperty format jpeg --setProperty formatOptions 82` to create `/private/tmp/raven-welcome-light.jpg` and `/private/tmp/raven-welcome-dark.jpg` without modifying the source files. + +- [ ] **Step 2: Verify visual quality and size** + +Run `file` and `ls -l` on both derivatives. Confirm each is a 1600-pixel-wide JPEG below 512000 bytes, then inspect both images for readable terminal text and intact colors. + +- [ ] **Step 3: Upload through GitHub User Content** + +Attach both derivatives to pull request 280 through GitHub's comment composer. Capture the resulting `https://github.com/user-attachments/assets/...` URLs and confirm each URL downloads to the expected byte size. + +- [ ] **Step 4: Add the English showcase** + +Insert this structure after the benchmark caveat in `README.md`, using the captured URLs: + +```markdown +Install Raven, run `raven` in your terminal, and this is the welcome screen you will see: + +| Light theme | Dark theme | +| --- | --- | +| ![Raven terminal welcome screen in light theme](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven terminal welcome screen in dark theme](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | +``` + +- [ ] **Step 5: Add the Chinese showcase** + +Insert the translated structure at the same location in `README.zh-CN.md`: + +```markdown +安装 Raven 后，在终端运行 `raven`，你会看到下面的欢迎界面： + +| 浅色主题 | 深色主题 | +| --- | --- | +| ![Raven 终端浅色主题欢迎界面](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven 终端深色主题欢迎界面](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | +``` + +- [ ] **Step 6: Verify the repository diff** + +Run `git diff --check`, confirm both READMEs contain the same two attachment URLs, and run `make check-large-files`. Expected: all commands exit 0 and no image binary appears in `git status`. + +- [ ] **Step 7: Commit and synchronize** + +Commit the two README changes and this plan with `docs: add terminal welcome screen showcase`. Fetch `origin/main`, run `git merge-tree --write-tree HEAD origin/main`, rerun the checks, and push `docs/readme_github_banner` to pull request 280. + +- [ ] **Step 8: Preview and verify pull request 280** + +Open the exact remote commit on GitHub, confirm the two-column table renders between Benchmarks and Quick Start in both READMEs, update the pull request description, and wait for all checks to pass. From 81feb498399efab62d5e8c6b146d28dcabea66f3 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Wed, 12 Aug 2026 15:58:29 +0800 Subject: [PATCH 09/13] docs: align README flow with main --- README.md | 60 ++++++++++++++++++++++++++++++++++++---------- README.zh-CN.md | 63 +++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 99 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 2e5c072..aeb3a34 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,17 @@
+
+ # Raven -Raven is a memory-first, self-improving agent harness built on [EverOS](https://github.com/EverMind-AI/EverOS). It brings durable memory, controlled context, proactive execution, reusable skills, deep multi-source research, and local observability into one terminal-native runtime. +Raven is **The Self-Improving Agent Harness**, built on [EverOS](https://github.com/EverMind-AI/EverOS), with opt-in Deep Research for multi-source investigation. + +Raven helps agents improve across runs by continuously refining the systems around them: tools, skills, memory, code execution, policies, and working environment. EverOS provides durable user memory, agent memory, and world knowledge across sessions, so successful workflows can evolve into reusable Agent Templates and digital workers. + +**Update:** Raven added Deep Research. Enable it with `raven deep-research enable` +to give the agent access to MiroThinker-backed, multi-source research when a +task needs deeper investigation. > Raven is pre-alpha. Interfaces and configuration may change quickly. @@ -23,9 +31,9 @@ Raven is a memory-first, self-improving agent harness built on [EverOS](https:// | Benchmark | Raven Result | Comparison | | --- | --- | --- | -| [Efficiency](https://raven.evermind.ai/) | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | -| [Self-evolution](https://evermind-ai.github.io/EvoAgentBench/) | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | -| [Proactivity](https://x.com/evermind) | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | +| Efficiency | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | +| Self-evolution | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | +| Proactivity | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. @@ -141,6 +149,13 @@ The schema follows a small, versioned semantic contract. See the [Tracing Standa | **Evolver** | Reproducible evaluation loops for improving agents and reusable procedures | | **Agent Templates** | Shareable starting points for specialized digital workers built on the same harness | +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ ## Providers and Gateways Raven supports API-key, OAuth, local, and OpenAI-compatible providers. The onboarding catalog includes OpenRouter, OpenAI, Anthropic, Gemini, MiniMax, DeepSeek, Z.ai, DashScope, Moonshot, VolcEngine, SiliconFlow, Groq, AiHubMix, Azure OpenAI, GitHub Copilot OAuth, OpenAI Codex OAuth, Ollama, and hosted vLLM. @@ -172,6 +187,23 @@ raven gateway Run `raven --help` or `raven --help` for the complete CLI surface. +## Documentation + +- [Documentation index](docs/README.md) +- [Developer workflow](docs/dev.md) +- [Tracing Standard API](docs/TRACING_STANDARD_API.md) +- [Sandbox usage](docs/sandbox/usage.md) +- [Memory plugin architecture](docs/memory-plugin-architecture.md) +- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md) +- [Proactivity implementation](docs/Proactivity-Implementation.md) + +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ ## Architecture ```text @@ -212,20 +244,24 @@ raven/tui_rpc/ typed runtime-to-TUI boundary ui-tui/ React/Ink terminal interface ``` -## Documentation +
+
-- [Documentation index](docs/README.md) -- [Developer workflow](docs/dev.md) -- [Tracing Standard API](docs/TRACING_STANDARD_API.md) -- [Sandbox usage](docs/sandbox/usage.md) -- [Memory plugin architecture](docs/memory-plugin-architecture.md) -- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md) -- [Proactivity implementation](docs/Proactivity-Implementation.md) +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
## EverMind Ecosystem Raven is part of the [EverMind](https://evermind.ai/) open-source ecosystem. Explore [EverOS](https://github.com/EverMind-AI/EverOS), [EverAlgo](https://github.com/EverMind-AI/EverAlgo), [HyperMem](https://github.com/EverMind-AI/HyperMem), [EvoAgentBench](https://github.com/EverMind-AI/EvoAgentBench), [EverMemBench](https://github.com/EverMind-AI/EverMemBench), and [EverMe](https://github.com/EverMind-AI/EverMe). +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ ## Contributing Issues and pull requests are welcome. Start with the [developer workflow](docs/dev.md), follow [AGENTS.md](AGENTS.md) for repository rules, and use [GitHub Discussions](https://github.com/EverMind-AI/Raven/discussions) for design conversations. diff --git a/README.zh-CN.md b/README.zh-CN.md index 6383d02..291e4f2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -13,9 +13,20 @@ +
+ # Raven -Raven 是一个构建在 [EverOS](https://github.com/EverMind-AI/EverOS) 之上的、记忆优先且能自我改进的 Agent Harness。它把持久记忆、可控上下文、主动执行、可复用技能、多来源深度研究和本地可观测性整合进一个终端原生运行时。 +Raven 是构建在 [EverOS](https://github.com/EverMind-AI/EverOS) 之上的 +**The Self-Improving Agent Harness**，并内置可选 Deep Research，用于多来源深度研究。 + +Raven 会持续迭代支撑 Agent 的 harness：tools、skills、memory、code execution +runtime、policies 和工作环境。EverOS 为这个 harness 提供跨会话持久存在的用户 +记忆、Agent 记忆和世界知识，让每一次运行都能改进 Agent 的行动方式、知识状态， +并把可重复工作流沉淀成可复用 Agent Templates 和 digital workers。 + +**Update：** Raven 新增 Deep Research。运行 `raven deep-research enable` 后， +Agent 可以在需要深度调查的任务中使用 MiroThinker-backed、多来源 research tool。 > Raven 目前处于 pre-alpha 阶段，接口和配置可能快速变化。 @@ -23,9 +34,9 @@ Raven 是一个构建在 [EverOS](https://github.com/EverMind-AI/EverOS) 之上 | 基准测试 | Raven 结果 | 对比 | | --- | --- | --- | -| [效率](https://raven.evermind.ai/) | 27B 下为 `56.7%`；397B 下为 `58.1%` | Hermes 为 `46.8%` / `47.9%`；27B 下领先 `+9.9pp` | -| [自我进化](https://evermind-ai.github.io/EvoAgentBench/) | EvoAgentBench 排名 `#1` | 在四种方法中领先下一名 `+6.2pp` | -| [主动性](https://x.com/evermind) | ProAgentBench F1 为 `0.60` | 是 Hermes/OpenClaw `0.253` 的 `2.4x` | +| 效率 | 27B 下为 `56.7%`；397B 下为 `58.1%` | Hermes 为 `46.8%` / `47.9%`；27B 下领先 `+9.9pp` | +| 自我进化 | EvoAgentBench 排名 `#1` | 在四种方法中领先下一名 `+6.2pp` | +| 主动性 | ProAgentBench F1 为 `0.60` | 是 Hermes/OpenClaw `0.253` 的 `2.4x` | 以上结果对应已发布的测试配置；模型、任务集和评测协议都会影响最终结果。 @@ -141,6 +152,13 @@ Schema 遵循一个精简、带版本的语义契约。Span 名称、属性、ar | **Evolver** | 用于改进 Agent 和可复用流程的可复现评测循环 | | **Agent Templates** | 基于同一套 harness 构建专用 digital workers 的可分享起点 | +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ ## Providers 和 Gateways Raven 支持 API key、OAuth、本地和 OpenAI-compatible providers。Onboarding catalog 包括 OpenRouter、OpenAI、Anthropic、Gemini、MiniMax、DeepSeek、Z.ai、DashScope、Moonshot、VolcEngine、SiliconFlow、Groq、AiHubMix、Azure OpenAI、GitHub Copilot OAuth、OpenAI Codex OAuth、Ollama 和托管 vLLM。 @@ -172,6 +190,23 @@ raven gateway 运行 `raven --help` 或 `raven --help` 查看完整 CLI。 +## 文档 + +- [文档索引](docs/README.md) +- [开发工作流](docs/dev.md) +- [Tracing Standard API](docs/TRACING_STANDARD_API.md) +- [Sandbox 使用说明](docs/sandbox/usage.md) +- [Memory plugin 架构](docs/memory-plugin-architecture.md) +- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md) +- [Proactivity 实现](docs/Proactivity-Implementation.md) + +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ ## 架构 ```text @@ -212,20 +247,24 @@ raven/tui_rpc/ typed runtime-to-TUI boundary ui-tui/ React/Ink terminal interface ``` -## 文档 +
+
-- [文档索引](docs/README.md) -- [开发工作流](docs/dev.md) -- [Tracing Standard API](docs/TRACING_STANDARD_API.md) -- [Sandbox 使用说明](docs/sandbox/usage.md) -- [Memory plugin 架构](docs/memory-plugin-architecture.md) -- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md) -- [Proactivity 实现](docs/Proactivity-Implementation.md) +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
## EverMind 生态 Raven 是 [EverMind](https://evermind.ai/) 开源生态的一部分。你可以继续了解 [EverOS](https://github.com/EverMind-AI/EverOS)、[EverAlgo](https://github.com/EverMind-AI/EverAlgo)、[HyperMem](https://github.com/EverMind-AI/HyperMem)、[EvoAgentBench](https://github.com/EverMind-AI/EvoAgentBench)、[EverMemBench](https://github.com/EverMind-AI/EverMemBench) 和 [EverMe](https://github.com/EverMind-AI/EverMe)。 +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ ## 参与贡献 欢迎提交 issues 和 pull requests。请先阅读[开发工作流](docs/dev.md)，按照 [AGENTS.md](AGENTS.md) 中的仓库规则进行协作，并在 [GitHub Discussions](https://github.com/EverMind-AI/Raven/discussions) 讨论设计方案。 From d136ae3710547da7e9fe9f420d5b5fdd4033e6c2 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Wed, 12 Aug 2026 17:02:28 +0800 Subject: [PATCH 10/13] docs: add onboarding video below benchmarks --- README.md | 2 ++ README.zh-CN.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index aeb3a34..e517644 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ task needs deeper investigation. Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. +https://github.com/user-attachments/assets/8d152190-2253-489c-9efb-abc0161e6348 + Install Raven, run `raven` in your terminal, and this is the welcome screen you will see: | Light theme | Dark theme | diff --git a/README.zh-CN.md b/README.zh-CN.md index 291e4f2..c4bd449 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -40,6 +40,8 @@ Agent 可以在需要深度调查的任务中使用 MiroThinker-backed、多来 以上结果对应已发布的测试配置；模型、任务集和评测协议都会影响最终结果。 +https://github.com/user-attachments/assets/8d152190-2253-489c-9efb-abc0161e6348 + 安装 Raven 后，在终端运行 `raven`，你会看到下面的欢迎界面： | 浅色主题 | 深色主题 | From 5af67e1a7598ee6a998a0f16309dca3f8d6c6bb4 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Wed, 12 Aug 2026 19:59:41 +0800 Subject: [PATCH 11/13] docs: replace onboarding video --- README.md | 2 +- README.zh-CN.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e517644..10e56de 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ task needs deeper investigation. Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. -https://github.com/user-attachments/assets/8d152190-2253-489c-9efb-abc0161e6348 +https://github.com/user-attachments/assets/3c541dae-5852-447f-8ea6-c9877612ad57 Install Raven, run `raven` in your terminal, and this is the welcome screen you will see: diff --git a/README.zh-CN.md b/README.zh-CN.md index c4bd449..c6f41c7 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -40,7 +40,7 @@ Agent 可以在需要深度调查的任务中使用 MiroThinker-backed、多来 以上结果对应已发布的测试配置；模型、任务集和评测协议都会影响最终结果。 -https://github.com/user-attachments/assets/8d152190-2253-489c-9efb-abc0161e6348 +https://github.com/user-attachments/assets/3c541dae-5852-447f-8ea6-c9877612ad57 安装 Raven 后，在终端运行 `raven`，你会看到下面的欢迎界面： From ce4b06c7b293ddc0ec816d52d1f515a029e00686 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Wed, 12 Aug 2026 20:13:35 +0800 Subject: [PATCH 12/13] docs: remove welcome theme screenshots --- README.md | 6 ------ README.zh-CN.md | 6 ------ 2 files changed, 12 deletions(-) diff --git a/README.md b/README.md index 10e56de..346b4b6 100644 --- a/README.md +++ b/README.md @@ -39,12 +39,6 @@ Results describe the published test configurations; model, task set, and evaluat https://github.com/user-attachments/assets/3c541dae-5852-447f-8ea6-c9877612ad57 -Install Raven, run `raven` in your terminal, and this is the welcome screen you will see: - -| Light theme | Dark theme | -| --- | --- | -| ![Raven terminal welcome screen in light theme](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven terminal welcome screen in dark theme](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | - ## Quick Start ### Install diff --git a/README.zh-CN.md b/README.zh-CN.md index c6f41c7..93cfc72 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -42,12 +42,6 @@ Agent 可以在需要深度调查的任务中使用 MiroThinker-backed、多来 https://github.com/user-attachments/assets/3c541dae-5852-447f-8ea6-c9877612ad57 -安装 Raven 后，在终端运行 `raven`，你会看到下面的欢迎界面： - -| 浅色主题 | 深色主题 | -| --- | --- | -| ![Raven 终端浅色主题欢迎界面](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven 终端深色主题欢迎界面](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | - ## 快速开始 ### 安装 From bf7155ae968b631fb2898e91940ccc9322abb512 Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Wed, 12 Aug 2026 20:30:30 +0800 Subject: [PATCH 13/13] docs: remove README planning files --- .../2026-08-11-readme-benchmark-redesign.md | 213 ------------------ .../2026-08-11-readme-benchmark-table.md | 81 ------- .../2026-08-11-readme-welcome-screens.md | 80 ------- .../2026-08-11-readme-benchmark-redesign.md | 83 ------- ...026-08-11-readme-benchmark-table-design.md | 36 --- ...026-08-11-readme-welcome-screens-design.md | 39 ---- 6 files changed, 532 deletions(-) delete mode 100644 docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md delete mode 100644 docs/superpowers/plans/2026-08-11-readme-benchmark-table.md delete mode 100644 docs/superpowers/plans/2026-08-11-readme-welcome-screens.md delete mode 100644 docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md delete mode 100644 docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md delete mode 100644 docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md diff --git a/docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md b/docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md deleted file mode 100644 index 02babb4..0000000 --- a/docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md +++ /dev/null @@ -1,213 +0,0 @@ -# README Benchmark Redesign Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Replace Raven's repetitive README narrative with a concise benchmark-led story and detailed, evidence-backed Deep Research and Tracing sections. - -**Architecture:** Build one deterministic benchmark proof board outside the repository, upload it through GitHub User Content, and reference it from a rewritten `README.md`. Keep implementation and generated assets out of git; only Markdown source and planning documents enter the pull request. - -**Tech Stack:** Markdown, HTML/CSS/SVG rendered through local Chrome, WebP or PNG, GitHub User Content, git, gh CLI - -## Global Constraints - -- Do not commit images, SVGs, HTML, manifests, or other generated assets. -- Keep the benchmark image below 500 KB while preserving crisp chart text. -- Use only claims supported by Raven code, an official benchmark, or approved EverMind copy. -- Keep repository prose and commit metadata in English. -- Run `make check-large-files` because README and generated-output references change. -- Update the existing draft pull request instead of creating a second pull request. - ---- - -### Task 1: Build the benchmark proof board - -**Files:** -- Create outside git: `/private/tmp/raven-benchmark-board.html` -- Create outside git: `/private/tmp/raven-benchmark-board.png` -- Create outside git: `/private/tmp/raven-benchmark-board.webp` - -**Interfaces:** -- Consumes: the three user-supplied JPEG drafts and the current Raven banner palette -- Produces: one 1920 x 960 benchmark board suitable for a full-width GitHub README image - -- [ ] **Step 1: Lock the visual system** - -Use this palette and type hierarchy in the temporary HTML: - -```text -canvas: #160f08 -panel: #24170c -panel-soft: #2e1d0f -gold: #f2b51d -gold-muted: #a97d17 -text: #f7f0df -text-muted: #b8aa92 -grid: #4b3825 -headline: ui-monospace, SFMono-Regular, Menlo, monospace -body: Inter, ui-sans-serif, system-ui, sans-serif -``` - -- [ ] **Step 2: Build one three-card board** - -Use the following exact card copy and approved figures: - -```text -01 EFFICIENCY -Better Results, Fewer Tokens -56.7% vs 46.8% at 27B -58.1% vs 47.9% at 397B - -02 SELF-EVOLUTION -Learns Best Among Peers -#1 across four methods -+6.2pp lift on EvoAgentBench - -03 PROACTIVITY -Acts Earlier, Scores Higher -0.60 F1 vs 0.253 -2.4x on ProAgentBench -``` - -Each card contains a compact chart, a large result, a short benchmark label, and no paragraph longer than two lines. Use `OpenClaw` consistently and include `Hermes` only where the supplied comparison names it. - -- [ ] **Step 3: Render and compress** - -Render at 1920 x 960, then compare lossless WebP and optimized PNG. Select the smallest version whose labels remain crisp at a 920px GitHub display width. - -Run: - -```bash -file /private/tmp/raven-benchmark-board.webp -stat -f "%z bytes" /private/tmp/raven-benchmark-board.webp -shasum -a 256 /private/tmp/raven-benchmark-board.webp -``` - -Expected: 1920 x 960 image, fewer than 500000 bytes, and a recorded SHA-256 digest. - -### Task 2: Rewrite the README narrative - -**Files:** -- Modify: `README.md` - -**Interfaces:** -- Consumes: the information architecture in `docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md` -- Produces: a concise README ready to receive the generated GitHub User Content URL - -- [ ] **Step 1: Replace the opening narrative** - -Keep the existing Raven banner and community links. Follow them with one positioning paragraph and a `## Benchmarks` section before installation. The section must include the proof-board image, a one-sentence interpretation, and direct links to the Raven benchmark page and EvoAgentBench methodology. - -- [ ] **Step 2: Collapse onboarding into Quick Start** - -Keep the POSIX and native Windows install commands, then show this exact first-run sequence: - -```bash -raven onboard -raven -raven doctor -``` - -Move upgrade details to one short paragraph and two commands. - -- [ ] **Step 3: Write the Deep Research section** - -Explain opt-in setup, per-query deep-versus-regular choice, MiroThinker execution, report persistence, background delivery, quota awareness, and these commands: - -```bash -raven deep-research enable -raven deep-research get -``` - -- [ ] **Step 4: Write the Tracing section** - -Explain local span capture, the turn-to-memory hierarchy, usage/cost/latency/error inspection, artifact panels, no-throw behavior, local storage, and this command: - -```bash -raven tracing -``` - -- [ ] **Step 5: Consolidate the remaining sections** - -Retain one compact section for core systems, one support line for providers and gateways, the architecture diagram, a compact command table, and links for docs, ecosystem, contributing, status, and license. Remove duplicate feature narratives, full gateway/status/ecosystem tables, repeated back-to-top badges, and the long Agent Templates policy copy. - -### Task 3: Publish the image without adding it to git - -**Files:** -- Modify: `README.md` -- Upload outside git: `/private/tmp/raven-benchmark-board.webp` - -**Interfaces:** -- Consumes: the compressed proof board from Task 1 -- Produces: a public `https://github.com/user-attachments/assets/...` URL referenced by `README.md` - -- [ ] **Step 1: Upload through pull request 280** - -Upload the WebP in the GitHub pull request composer, copy the generated GitHub User Content URL, and ensure the pull request references the attachment so GitHub publishes it. - -- [ ] **Step 2: Replace the temporary README URL** - -Set the alt text to `Raven benchmark results across efficiency, self-evolution, and proactivity` and use the exact asset URL returned by the GitHub composer. - -- [ ] **Step 3: Verify the public attachment** - -Download it without browser authentication and compare the uploaded bytes: - -Download the exact generated asset URL to `/private/tmp/raven-benchmark-board-public.webp`, then run: - -```bash -stat -f "%z bytes" /private/tmp/raven-benchmark-board-public.webp -shasum -a 256 /private/tmp/raven-benchmark-board.webp /private/tmp/raven-benchmark-board-public.webp -``` - -Expected: the download succeeds, remains below 500000 bytes, and both SHA-256 digests match. - -### Task 4: Verify, commit, and update the draft pull request - -**Files:** -- Modify: `README.md` -- Create: `docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md` -- Create: `docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md` - -**Interfaces:** -- Consumes: the finished README and public benchmark asset URL -- Produces: an updated, reviewable draft pull request 280 - -- [ ] **Step 1: Run documentation checks** - -```bash -git diff --check -make check-large-files -``` - -Expected: both commands exit 0. - -- [ ] **Step 2: Review the exact diff** - -```bash -git status --short -git diff -- README.md docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md -``` - -Expected: no generated image or web artifact appears in git status. - -- [ ] **Step 3: Commit the approved scope** - -```bash -git add README.md docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md docs/superpowers/plans/2026-08-11-readme-benchmark-redesign.md -git commit -m "docs: redesign README around benchmark proof" -``` - -- [ ] **Step 4: Synchronize and push** - -```bash -git fetch origin main -git merge-tree --write-tree HEAD origin/main -make check-large-files -git push --force-with-lease origin docs/readme_github_banner -``` - -Expected: the branch is based on the latest `origin/main`, checks pass after synchronization, and draft pull request 280 updates. - -- [ ] **Step 5: Update and verify the pull request** - -Update the PR title to `docs: redesign README around benchmark proof`, rewrite the description using `.github/pull_request_template.md`, verify the entire description is ASCII, and preview the rendered README on GitHub. Keep the PR in draft state for maintainer review. diff --git a/docs/superpowers/plans/2026-08-11-readme-benchmark-table.md b/docs/superpowers/plans/2026-08-11-readme-benchmark-table.md deleted file mode 100644 index c2ec586..0000000 --- a/docs/superpowers/plans/2026-08-11-readme-benchmark-table.md +++ /dev/null @@ -1,81 +0,0 @@ -# README Benchmark Table Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Replace the README benchmark image with a source-linked Markdown table in the same location. - -**Architecture:** Keep the existing `## Benchmarks` section and hero banner. Replace only the benchmark image, summary bullets, and separate source list with one native Markdown table plus the existing evaluation caveat. - -**Tech Stack:** GitHub-flavored Markdown, git, GitHub pull request 280 - -## Global Constraints - -- Keep the Raven hero banner unchanged. -- Do not add an image or generated asset to git. -- Preserve every published benchmark value. -- Link each benchmark name to its official source. -- Update the existing draft pull request 280. - ---- - -### Task 1: Replace the benchmark image with a table - -**Files:** -- Modify: `README.md:21-34` -- Create: `docs/superpowers/plans/2026-08-11-readme-benchmark-table.md` - -**Interfaces:** -- Consumes: the existing benchmark values and source URLs in `README.md` -- Produces: a native Markdown table rendered by GitHub without a benchmark image request - -- [ ] **Step 1: Replace the image and bullets** - -Use this exact table under `## Benchmarks`: - -```markdown -| Benchmark | Raven Result | Comparison | -| --- | --- | --- | -| [Efficiency](https://raven.evermind.ai/) | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | -| [Self-evolution](https://evermind-ai.github.io/EvoAgentBench/) | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | -| [Proactivity](https://x.com/evermind) | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | -``` - -Keep this sentence immediately below the table: - -```markdown -Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes. -``` - -- [ ] **Step 2: Verify the Markdown diff** - -Run: - -```bash -git diff --check -rg -n 'user-attachments/assets|^\\| \\[.*\\]\\(https://' README.md -make check-large-files -``` - -Expected: the only `user-attachments` URL left in `README.md` is the Raven hero banner, all three benchmark rows contain source links, and both repository checks exit 0. - -- [ ] **Step 3: Commit the README and plan** - -```bash -git add README.md docs/superpowers/plans/2026-08-11-readme-benchmark-table.md -git commit -m "docs: replace benchmark image with table" -``` - -- [ ] **Step 4: Synchronize and push** - -```bash -git fetch origin main -git merge-tree --write-tree HEAD origin/main -make check-large-files -git push origin docs/readme_github_banner -``` - -Expected: the branch is based on the latest `origin/main`, the checks pass, and pull request 280 contains the table commit. - -- [ ] **Step 5: Preview pull request 280** - -Open the branch README on GitHub, confirm the table occupies the former benchmark image position, and confirm all pull request checks pass. diff --git a/docs/superpowers/plans/2026-08-11-readme-welcome-screens.md b/docs/superpowers/plans/2026-08-11-readme-welcome-screens.md deleted file mode 100644 index 64e88ad..0000000 --- a/docs/superpowers/plans/2026-08-11-readme-welcome-screens.md +++ /dev/null @@ -1,80 +0,0 @@ -# README Welcome Screens Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Add optimized light and dark Raven terminal welcome screens below the benchmark table in both READMEs. - -**Architecture:** Produce two 1600-pixel-wide JPEG derivatives outside the repository, upload them through GitHub User Content, and reference the resulting public URLs from a two-column Markdown table. Keep the English and Chinese documents structurally aligned and leave git free of image binaries. - -**Tech Stack:** macOS `sips`, GitHub User Content, GitHub-flavored Markdown, git, GitHub pull request 280 - -## Global Constraints - -- Resize each source screenshot to 1600 pixels wide while preserving aspect ratio. -- Re-encode each screenshot as JPEG at quality 82. -- Keep each delivered image below 500 KB. -- Do not add image binaries to git. -- Use the same two public GitHub User Content URLs in both READMEs. -- Place the showcase after the benchmark caveat and before Quick Start. - ---- - -### Task 1: Publish and embed the terminal welcome screens - -**Files:** -- Modify: `README.md:30-32` -- Modify: `README.zh-CN.md:30-32` -- Create outside git: `/private/tmp/raven-welcome-light.jpg` -- Create outside git: `/private/tmp/raven-welcome-dark.jpg` - -**Interfaces:** -- Consumes: the two user-provided JPEG screenshots and the existing benchmark sections -- Produces: two public attachment URLs and matching English and Chinese Markdown tables - -- [ ] **Step 1: Create optimized derivatives** - -Use `sips --resampleWidth 1600 --setProperty format jpeg --setProperty formatOptions 82` to create `/private/tmp/raven-welcome-light.jpg` and `/private/tmp/raven-welcome-dark.jpg` without modifying the source files. - -- [ ] **Step 2: Verify visual quality and size** - -Run `file` and `ls -l` on both derivatives. Confirm each is a 1600-pixel-wide JPEG below 512000 bytes, then inspect both images for readable terminal text and intact colors. - -- [ ] **Step 3: Upload through GitHub User Content** - -Attach both derivatives to pull request 280 through GitHub's comment composer. Capture the resulting `https://github.com/user-attachments/assets/...` URLs and confirm each URL downloads to the expected byte size. - -- [ ] **Step 4: Add the English showcase** - -Insert this structure after the benchmark caveat in `README.md`, using the captured URLs: - -```markdown -Install Raven, run `raven` in your terminal, and this is the welcome screen you will see: - -| Light theme | Dark theme | -| --- | --- | -| ![Raven terminal welcome screen in light theme](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven terminal welcome screen in dark theme](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | -``` - -- [ ] **Step 5: Add the Chinese showcase** - -Insert the translated structure at the same location in `README.zh-CN.md`: - -```markdown -安装 Raven 后，在终端运行 `raven`，你会看到下面的欢迎界面： - -| 浅色主题 | 深色主题 | -| --- | --- | -| ![Raven 终端浅色主题欢迎界面](https://github.com/user-attachments/assets/d415573d-98ab-4265-872b-67c33b42dcee) | ![Raven 终端深色主题欢迎界面](https://github.com/user-attachments/assets/0ffa1ba4-c03f-4d3f-bfff-d9eda87122dd) | -``` - -- [ ] **Step 6: Verify the repository diff** - -Run `git diff --check`, confirm both READMEs contain the same two attachment URLs, and run `make check-large-files`. Expected: all commands exit 0 and no image binary appears in `git status`. - -- [ ] **Step 7: Commit and synchronize** - -Commit the two README changes and this plan with `docs: add terminal welcome screen showcase`. Fetch `origin/main`, run `git merge-tree --write-tree HEAD origin/main`, rerun the checks, and push `docs/readme_github_banner` to pull request 280. - -- [ ] **Step 8: Preview and verify pull request 280** - -Open the exact remote commit on GitHub, confirm the two-column table renders between Benchmarks and Quick Start in both READMEs, update the pull request description, and wait for all checks to pass. diff --git a/docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md b/docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md deleted file mode 100644 index 5906692..0000000 --- a/docs/superpowers/specs/2026-08-11-readme-benchmark-redesign.md +++ /dev/null @@ -1,83 +0,0 @@ -# README Benchmark Redesign - -## Goal - -Turn the README from a broad capability catalog into a concise product narrative that proves Raven's value early, then helps a new user install and understand the two newest flagship features: Deep Research and Tracing. - -## Audience - -- Developers evaluating agent harnesses -- Builders deciding whether Raven is credible enough to try -- Contributors looking for architecture and development links - -## Information Architecture - -1. Raven banner, positioning, and community links -2. Benchmark proof board -3. Three-command quick start -4. Deep Research -5. Tracing -6. Core systems: memory, context, proactivity, and skills/evolution -7. Supported providers and messaging gateways -8. Architecture, documentation, ecosystem, and contributing links - -## Benchmark Proof Board - -Create one wide image that consolidates the three supplied benchmark concepts: - -- Better Results, Fewer Tokens -- Learns Best Among Peers -- Acts Earlier, Scores Higher - -The board uses Raven's warm cream, dark brown, and gold palette, with high-contrast typography and explicit legends. It fixes spacing, capitalization, ambiguous zero glyphs, and chart labeling in the supplied drafts. - -Every public claim must be traceable to an official benchmark, Raven property, or approved EverMind statement. The README text below the image links to the relevant methodology or leaderboard. - -The final image is uploaded through GitHub User Content. No image, SVG, HTML, or generated asset is committed to the repository. Target download size is below 500 KB. - -## Deep Research - -Explain the user journey rather than only the integration: - -- Enable with `raven deep-research enable` -- Choose deep or regular search per research-shaped query -- Run broad multi-source research through MiroThinker -- Receive the finished result directly, including citations -- Save a Markdown report in the workspace -- Support background completion and delivery when the gateway is available -- Make time and quota use explicit before the paid engine runs - -## Tracing - -Position Tracing as the way to inspect why Raven acted: - -- Open the local dashboard with `raven tracing` -- Follow turn, model, tool, subagent, skill, context, and memory spans -- Inspect usage, cost, latency, errors, tool input, tool output, and artifacts -- Keep trace data local under the Raven state directory -- Allow tracing to be disabled without affecting the host workflow -- Guarantee that tracing failures do not break the agent loop - -## Content Reduction - -- Merge `What You Can Do in 2 Minutes` into Quick Start -- Merge `Why Raven` and `What Raven Is Built For` -- Remove the duplicate Deep Research update block -- Replace the full gateway table with a compact support line -- Merge `Useful Commands` and `Docs by Goal` -- Reduce Agent Templates to one paragraph -- Reduce status, developer workflow, and ecosystem tables to concise links -- Remove repeated back-to-top badges - -## Verification - -- Review every README claim against code, tests, or an official benchmark source -- Confirm image URL works without authentication -- Confirm downloaded image is below 500 KB and matches the uploaded source hash -- Run `git diff --check` -- Run `make check-large-files` -- Preview the rendered README on GitHub through the draft pull request - -## Rollback - -Revert the README-only commits. The externally hosted image can remain unreferenced without changing repository size. diff --git a/docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md b/docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md deleted file mode 100644 index 2da1829..0000000 --- a/docs/superpowers/specs/2026-08-11-readme-benchmark-table-design.md +++ /dev/null @@ -1,36 +0,0 @@ -# README Benchmark Table Design - -## Goal - -Replace the benchmark image with native Markdown so the evidence loads immediately, remains searchable and accessible, and does not depend on a second GitHub User Content image. - -## Scope - -- Keep the Raven hero banner unchanged. -- Remove the benchmark image from `README.md`. -- Replace the benchmark image and the three repetitive summary bullets with one Markdown table. -- Keep the evaluation caveat below the table. -- Keep official source links attached to the benchmark names. - -## Table - -Use three columns so the table remains readable on narrow GitHub layouts: - -| Benchmark | Raven Result | Comparison | -| --- | --- | --- | -| Efficiency | `56.7%` at 27B; `58.1%` at 397B | Hermes `46.8%` / `47.9%`; `+9.9pp` at 27B | -| Self-evolution | Ranked `#1` on EvoAgentBench | `+6.2pp` over the next result across four methods | -| Proactivity | `0.60` F1 on ProAgentBench | `2.4x` Hermes/OpenClaw at `0.253` | - -The final README links `Efficiency` to the Raven benchmark overview, `Self-evolution` to the EvoAgentBench methodology, and `Proactivity` to EverMind benchmark updates. - -## Verification - -- Confirm the README contains only the hero banner image. -- Confirm each benchmark source link is present in the table. -- Run `git diff --check` and `make check-large-files`. -- Preview the rendered table on the pull request branch. - -## Rollback - -Revert the table commit to restore the benchmark image reference. diff --git a/docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md b/docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md deleted file mode 100644 index 9b2bdef..0000000 --- a/docs/superpowers/specs/2026-08-11-readme-welcome-screens-design.md +++ /dev/null @@ -1,39 +0,0 @@ -# README Welcome Screens Design - -## Goal - -Show the first Raven terminal screen directly below the benchmark table so readers can see the installed product before starting the setup instructions. - -## Layout - -Add a short introductory sentence followed by a two-column GitHub-flavored Markdown table: - -| Light theme | Dark theme | -| --- | --- | -| Light welcome screen | Dark welcome screen | - -Use equivalent translated copy in `README.zh-CN.md`. Keep the section between the benchmark caveat and Quick Start in both files. - -## Image Delivery - -- Resize each source screenshot to 1600 pixels wide while preserving aspect ratio. -- Re-encode as JPEG at quality 82 and keep each file below 500 KB. -- Upload both files through GitHub User Content. -- Reference only the public attachment URLs from the READMEs. -- Do not add image files to git. - -## Accessibility - -Use descriptive alt text that identifies Raven's terminal welcome screen and the displayed theme. Keep visible column labels so the comparison remains understandable if images load slowly. - -## Verification - -- Confirm both public attachment URLs load successfully. -- Confirm both files are below 500 KB. -- Confirm the English and Chinese READMEs use the same two URLs and matching placement. -- Preview the rendered table on GitHub. -- Run `git diff --check` and `make check-large-files`. - -## Rollback - -Remove the introductory sentence and image table from both READMEs. The unreferenced GitHub User Content attachments do not affect repository size.