raxol

Raxol

递归地，axol。永远 FOSS。

编写一个应用。将它渲染到终端、浏览器、SSH 会话或 Agent 中。

你的应用是一个单独的 TEA 模块（init、update、view），作为 OTP GenServer 运行。Raxol 通过同一套代码将该模块渲染到四种界面：

                          +---> Terminal (termbox2 NIF)
                          |
  TEA module (GenServer) -+---> Browser (Phoenix LiveView)
                          |
                          +---> SSH (Erlang :ssh)
                          |
                          +---> Agent (MCP tools)

有趣之处在于运行时。你的应用可以获得按 Component 隔离的崩溃处理、无需重启的热代码重载、基于 CRDT 的分布式集群，以及一个 Agent 界面，让大模型与结构化 Component 树交互，而不是抓取像素。这些都是 BEAM 的特性；它的虚拟机专为不能宕机、不能丢失状态，并且能在运行时热替换代码的系统而构建。

Bubble Tea、Ratatui 和 Textual 都是出色的渲染器。A2UI 和 AG-UI 定义了 Agent-UI 的线级格式。Raxol 则是运行时，可通过一个源模块渲染所有四种界面。关于框架比较，请参阅 Why OTP；关于运行时与 Hermes、Omnigent 等 Python Agent 技术栈的比较，请参阅 Why Raxol。

Agents

Raxol 既是面向 Agent 的运行时，也是面向人类的运行时。每个交互式 Component 都会自动公开 MCP 工具（Button 提供 click，TextInput 提供 type_into/clear/get_value），焦点镜头会将每次交互可用的工具筛选到约 15 个。A2UI 和 AG-UI 定义了 Agent 在线级上如何与 UI 通信，而 raxol 则从同一棵 Component 树生成 UI 和 Agent 界面：同一份源代码，两种投影。

import Raxol.MCP.Test
import Raxol.MCP.Test.Assertions

session = start_session(MyApp)

session
|> type_into("search", "elixir")
|> click("submit")
|> assert_component("results", fn c -> c[:content] != nil end)
|> stop_session()

mix mcp.server 会通过 stdio 启动 MCP 服务，以集成 Claude Code；mix raxol.code 则是一个交互式终端编码 Agent（axol 界面），所有会产生变更的工具调用都由 ALLOW/ASK/DENY 授权引擎把关。请参阅 Coding Agent。

Code 是编码 Agent 产品，提供两种可上手使用的界面：mix raxol.code 是交互式终端 TUI（axol 界面 ≡··≡），mix raxol.p 是它的无头版本（通过 argv 输入提示词，将回答输出到 stdout，将契约事件输出到 stderr），适用于管道和 CI。所有会产生变更的工具调用都由 ALLOW/ASK/DENY 授权引擎把关。从克隆开始，只需一条设置命令和一条启动命令：

(cd packages/raxol_agent && mix deps.get)   # once
bin/raxol-code                              # the TUI, your cwd as the workspace

尚未配置 API 密钥？TUI 会打开一个提供方向导，而不会直接报错。/inspect（或在 packages/raxol_agent 中运行 mix raxol.inspect）会显示 Agent 在当前目录中将使用的所有配置来源。

会话具有持久性。每个会话都会将事件记录到磁盘，因此 --continue 和 --resume <id> 会同时恢复模型上下文和滚动历史；--replay <id> 会直接从日志打印对话记录（--to-offset N 会在指定偏移处停止）；/rewind 会回退到较早的一轮；/share 会生成一个有效期为 24 小时的签名链接，指向只读对话记录，并实时跟随会话更新（需要 RAXOL_SHARE_SECRET，且宿主需挂载 Raxol.Agent.Code.ShareLive）。 同一个 TUI 也可通过 SSH 使用：mix raxol.code --ssh --ssh-tenants /srv/tenants 可让多个用户共用一个守护进程，每个用户都通过自己的公钥连接，并拥有独立的 cwd 隔离区、会话存储和消费身份（ssh <you>@your-host -p 2222 就是完整的客户端）。单租户（--authorized-keys）和托管部署（RAXOL_SSH_CODE=true）请参阅 编码 Agent。

同一个 Agent 提供两种无人值守接口。bin/raxol-acp（或 mix raxol.acp）通过标准输入输出上的 Agent Client Protocol 提供服务，供自行启动 Agent 的编辑器使用；Raxol.Agent.Harness.McpTools 会将 harness_start_session、harness_send_prompt、harness_read_transcript 和 harness_list_sessions 注册到 MCP 注册表，因此由 MCP 客户端启动的会话之后可在 TUI 中继续。ACP 接口运行完整工具集，每次敏感调用都必须经过 session/request_permission 往返授权，并在判定失败时默认拒绝：如果客户端拒绝、超时或未实现权限功能，就会拒绝写入并继续读取。MCP 接口保持只读：没有人可以响应授权提示时，write_file、edit_file 和 bash 不会提供。

所有这些接口都基于 Harness，即 Agent 会话引擎：持久化事件日志（Raxol.Agent.Journal）、类型化事件／命令契约（Raxol.Agent.Contract），以及通过事件流纯折叠生成的接口状态（Raxol.Harness.Projection），底层还有分阶段的中断、引导和支出／影响范围关卡。同一引擎既能监管 Raxol 自有循环，也能监管外部 Agent CLI（claude、cursor）。请参阅 Harness 架构。

Agent 子系统以独立软件包形式发布：

• Pay（raxol_payments）：钱包、由账本强制执行的支出限额，以及 Agent 遇到 HTTP 402 时透明触发的自动支付，支持五种协议（x402、MPP、Xochi cross-chain、Permit2、Riddler）。
• Earn（raxol_earn）：销售端。声明一项服务并实现两个回调，买方 Agent 即可发现该服务、托管资金，并通过 Virtuals ACP 作业生命周期（请求、协商、交易、评估、完成）在链上结算；每项作业由一个独立监管进程处理。预 Alpha 阶段。
• Improve（raxol_agent）：已解决的任务会成为可重复使用的 SKILL.md。每轮对话结束后，后台审核器会使用低成本模型生成持久化记忆和新技能，不占用当前轮次的延迟或上下文。
• Reach（raxol_gateway）：通过统一适配器契约接入多个聊天平台，按聊天启动独立会话进程，通过私信配对进行授权，并使用 /handoff 在平台间迁移对话，同时保留完整历史记录。
• Bridge（raxol_agent_client_protocol）：Agent Client Protocol 的 Elixir/OTP 实现：用于代码编辑器与 AI 编码 Agent 之间通信的 JSON-RPC 2.0 线协议（Zed 和不断扩大的生态系统都使用此协议）。支持 Agent／客户端双向角色、可插拔传输方式（标准输入输出、进程内），以及可持久化、可恢复的会话（基于偏移量的重新连接／回放），作为供应商扩展提供。零 raxol 内部依赖。预 Alpha 阶段。

安装

# mix.exs
def deps do
  [{:raxol, "~> 2.7"}]
end

或生成一个新项目：

mix raxol.new my_app

使用 Nix 时，运行 nix develop 即可进入包含完整 BEAM 和 NIF 工具链的 Shell（无需本地安装 Elixir）：

nix develop github:DROOdotFOO/raxol   # dev shell with elixir, erlang, NIF + speech deps

试用

无需安装：raxol.io 在浏览器中运行同一目录，每个演示对应一个 LiveView。该界面就是此仓库的 web/ 应用；参见 web/README.md 了解如何自行运行。在终端中：

git clone https://github.com/DROOdotFOO/raxol.git
cd raxol && mix deps.get
mix raxol.playground          # 42 live demos, browse/search/filter

旗舰演示是一个实时 BEAM 仪表盘，包含调度器利用率、内存迷你图和进程表：

mix run examples/demo.exs

参见 examples/README.md，了解完整的学习路径，其中包括 Agent 示例、集群演示和 REPL。

无头环境（CI、容器、Agent）？整个构建和测试流程都无需 tty：

mix local.hex --force        # fresh machines and CI: install Hex without a prompt
mix deps.get
mix compile                  # termbox2 NIF needs make + a C compiler
SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker
MIX_ENV=test mix raxol.rate  # RATE: render-determinism golden suite

前置条件、质量门禁和受限沙盒说明见开发。

性能

在 Apple M1 上（Elixir 1.20 / OTP 29）完整帧耗时 5.0ms，占 60fps 预算的 31%。

项目	耗时
完整帧（创建 + 填充 + 差异比较）	5.0 ms
树差异比较（100 个节点，1 个已更改）	32 us
单元格写入（单次）	1.4 us
缓冲区创建（80x24）	0.32 us
仿真器导入（解析 + 应用，纯文本）	1.7 ms
每个 80x24 缓冲区的内存占用	2 KB

测量时间为 2026-08-07，版本为 fce2465bb，使用 mix run bench/suites/comparison/framework_comparison.exs（完整模式）。导入一行测量的是整个仿真器流程（解析加状态应用），而不是独立的 ANSI 词法分析器；后者处理纯文本耗时不到一微秒（mix raxol.bench parser）。

Unix/macOS 后端使用 termbox2 NIF；Windows 使用纯 Elixir 驱动程序（可用，但尚未调优）。参见基准测试套件。

文档

请从文档索引开始，或直接查看：

• 快速入门
• 组件
• 界面
• 编码 Agent
• 支付
• $RAXOL 代币信息
• API 文档

开发

从源代码开始工作需要 Elixir/OTP（版本见 mise.toml）和 C 工具链：termbox2 NIF 使用 make 和 cc 编译（在 Debian/Ubuntu 上， 运行 apt-get install build-essential）。nix develop 可在一个 shell 中提供所有依赖。以下所有命令都以无头模式运行：构建、 测试套件和黄金测试均不需要终端。

git clone https://github.com/DROOdotFOO/raxol.git
cd raxol
mix local.hex --force        # fresh machines and CI: install Hex without a prompt
mix deps.get
mix compile                  # builds the termbox2 NIF
SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker
MIX_ENV=test mix raxol.rate  # RATE: render-determinism golden suite
mix raxol.check              # full gate: format, compile, credo, dialyzer, security, docs, rate, test
mix raxol.check --quick      # skip dialyzer
mix raxol.demo               # built-in demos (needs a terminal)

SKIP_TERMBOX2_TESTS=true 会排除需要真实本地终端的测试 （pty 生命周期、对时序敏感的测试套件）；CI 设置了相同的变量。不带排除标记的 纯 mix test 也会运行需要外部服务的集成测试（工作流检查点测试需要通过 RAXOL_WORKFLOW_PG_URL 配置 PostgreSQL），因此除非你有这些服务，否则请使用 上面的命令。在 HOME 为只读的沙盒中，请在运行 mix 之前将 MIX_HOME 和 HEX_HOME 指向可写目录。

起源

Raxol 源于两个逐渐汇聚的想法：为 AGI 打造的终端，让 AI Agent 能像人类一样与真正的终端仿真器交互；以及用于高达 Wing 战衣驾驶舱的界面，在那里，故障隔离、实时响应和传感器融合关乎生存。高达的说法听起来像个玩笑。但仔细看看这些约束，就会发现这正是 OTP 的设计目标：系统不能宕机、不能丢失状态，还必须能在运行时热插拔组件。

更长远的愿景见 Raxol：我的高达终端。

使用 Raxol 构建

Xochi 是一个私有跨链 DEX（支持跨 6 条链的意图式兑换、不到 3 秒即可结算、默认使用隐身地址，并提供 ZKSAR 合规性证明），其整个交易界面均由 raxol 构建。一个 Component 树可投射为四种界面：SSH 交易终端、LiveView 网页 UI、用于 Riddler 的亚 2 毫秒求解器的 solver-agent 界面，以及运行求解器健康状况传感器融合的运维驾驶舱。求解器在专用的故障关闭堆栈后执行（买方预签名意图、由账本强制执行的支出门控、拒绝在未配置时运行的部署防护），并刻意不接入 MCP 界面，因此无法通过通用工具调用触发任何资金转移操作。

由 Brendan Turner 开发的 foglet-bbs 是一个仅支持 SSH 的复古公告板（bbs.foglet.io，ssh bbs.foglet.io），它通过压力测试打磨了 raxol 的 SSH 路径。

许可证

MIT。请参阅 LICENSE.md。