brevi

Brevi

AI 编写 Python 的快速、安全目标。 Brevi 是专为 AI 编码 Agent 打造的编译器。Agent 使用自己最擅长的普通 Python 编写代码；Brevi 通过 Rust 将其编译为原生二进制文件。在我们的 12 项计算基准测试中，使用默认构建方式，其运行速度比 CPython 快 1.6 倍至 37.9 倍（中位数为 9.3 倍），并力求输出与 CPython 完全一致（目前，与 CPython 3.13 自带测试套件中 80% 的计分测试结果一致，另有 3% 的测试仍能成功构建但结果不同；针对使用最广泛的标准库模块，其测试中有 45% 的结果一致）。对于无法构建的内容，它会用一行简短的 JSON 响应，供 Agent 采取相应操作。模型无需编写生命周期、借用或分号，也不需要学习指南即可上手。

文档：brevi-lang.org/docs · 版本发布：GitHub · 更新内容：CHANGELOG.md

公开预览版。 Brevi 目前已可使用，并且每次变更都会针对 CPython 进行测试，但它还很新：请预期会遇到一些问题，CLI 和 Brevi 自身的语法也可能随版本发布而变更。它目前还不能直接替代 python3：在 CPython 自身的测试中，一些已构建的程序仍会产生不同结果（参见状态）；对于无法构建的文件，brevi run 会悄悄回退到 python3（--native 可关闭此行为）；沙箱是策略层，而非隔离边界。非常欢迎提交错误报告（CONTRIBUTING.md）。

安装

Linux 和 macOS：

curl -fsSL https://raw.githubusercontent.com/ets-public/brevi/main/install.sh | sh

如果缺少 Rust 工具链，脚本会先安装它（Brevi 通过 rustc 进行编译），然后从最新版本下载适用于你计算机的预编译 brevi，将其安装到 ~/.cargo/bin，并根据该版本的 SHA256SUMS 进行验证；如果没有适用的预编译版本，则使用 cargo install 构建。

Windows：使用 rustup 安装 Rust，然后从最新版本下载并解压 brevi-x86_64-pc-windows-msvc.zip，再将 brevi.exe 添加到 PATH。从 v0.27.0 起，导入库的 Python 文件也可以构建：库调用会通过桥接在 CPython 中运行（PATH 中的 python 需要其 DLL）。

使用包管理器安装（仍需从 rustup 安装 Rust）：

pip install brevi          # or: uvx brevi mcp
npm install -g brevi       # or: npx brevi mcp

从 v0.26.0 起，cargo install brevi 即可使用。Docker、从源代码构建以及版本发布压缩包详见：安装。

快速入门

$ printf 'print(sum(i * i for i in range(10)))\n' > main.py
$ brevi run main.py                     # build natively (cached), then run
285
$ brevi check main.py                   # build without running: errors only
$ brevi build main.py -o app --release  # an optimised binary to keep or ship
$ brevi verify main.py --input tests/   # run it and python3 on each input: a certificate if they agree

对于确定无疑的错误，程序运行前会先报告，并用一行给出修复方法：

$ brevi check broken.py
{"line":8,"msg":"name 'totl' is not defined","fix":"did you mean total?"}

Python 本身只有在某行代码运行时才会发现的错误，也会像在 CPython 中一样在该处引发。Brevi 暂时无法原生构建某个文件，或文件中存在确定无疑的错误时，brevi run 会使用 python3 运行该文件，并打印一行 JSON，指出导致程序停止的行和函数；brevi build、brevi check 和 brevi run --native 绝不会回退，而 --strict（将在下一版本推出）也会拒绝动态回退，适用于要求使用类型化快速路径的 CI 和生产任务。文件可以导入同级模块和标准库，Brevi 会自行原生构建这些内容（可原生运行的内容）；也可以导入已安装的包：numpy、requests、httpx、pydantic、anthropic 和 openai SDK、mcp、jinja2、polars、sqlite3、duckdb、tiktoken 等，会使用 Brevi 自带的原生实现构建（从 v0.26.0 起）；其余包（pandas、yaml 等）则会在原生程序内通过 CPython 运行；brevi build x.py --standalone 会将 CPython 和这些包打包进二进制文件（Linux）。更多信息请参阅使用 Brevi。

面向 Agent

• MCP 服务： brevi mcp 通过标准输入输出提供 check、run、test、verify、patch、edit、show 和 guide，也可通过 Streamable HTTP 提供服务，使用 brevi mcp --http [HOST:]PORT（当地址不是 127.0.0.1 时需要 bearer token）。将其添加为命令 brevi，并将 mcp 作为参数（Claude Code：claude mcp add brevi -- brevi mcp）。Agent 只需将纯 Python 代码作为 code 发送一次；服务会保留代码，之后 patch（按名称替换完整的 def 和类）或 edit（编辑指定行范围）只会更改发送的部分，并再次检查，因此重试只需发送改动的行。run 搭配 cases 会构建一次，并为每个用例打印 ok 或第一个不一致的行；verify 会对相同输入运行原生构建和 CPython，并在两者结果一致时返回证书。工具默认在沙箱中运行；从 v0.27.0 开始，直接运行 brevi mcp 时，若调用试图关闭沙箱或授予任何权限，服务会拒绝执行（--allow、--allow-net 和其他授权标志用于设置调用可以请求的权限；--trust-calls 可恢复旧行为）；verify 会运行 CPython，因此需要 sandbox: false 和 --trust-calls。Claude Desktop 配置（需要 brevi 的完整路径）、时间和内存限制以及故障排查：面向 AI Agent。
• Python SDK（从 v0.27.0 开始）：pip install brevi 也会提供 import brevi。brevi.run(code, stdin=..., limits=..., allow_read=[...]) 会在沙箱中构建并运行程序，仅授予代码请求的权限，并返回其 stdout、stderr、exit_code 和 path；brevi.verify(code, inputs=[...]) 会返回证书；brevi.TOOL 和 brevi.handle(tool_input) 分别是供模型使用的 run_python 工具及其回复。它会与一个 brevi mcp 进程通信，因此构建缓存可以保持预热状态。npm 包为 Node 提供相同的调用方式（import { run } from "brevi"）。brevi-python 是 python3 的直接替代品：Brevi 能构建程序时使用原生执行，否则使用 CPython，并输出 CPython 的结果。packaging/pypi/README.md
• 沙箱镜像（从 v0.27.0 开始）：ghcr.io/ets-public/brevi-sandbox:latest 包含 Brevi、Rust 工具链、python3、SDK 和预热的构建缓存；:python3 则将 brevi-python 作为 python3 提供。templates/README.md
• GitHub Action（从 v0.27.0 开始）：uses: ets-public/brevi/[email protected] 会在 runner 上安装 Brevi 及其工具链，并在多次运行间保留构建缓存。setup/README.md
• Dev container 功能（从 v0.27.0 开始）：在 devcontainer.json 中添加 "features": {"ghcr.io/ets-public/features/brevi:1": {}}。devcontainer/README.md
• Skill 和插件： skills/brevi/SKILL.md 是一个 Agent Skills 包（完成设置后，编写纯 Python 代码，并仅修复错误指出的行）。在 Claude Code 中，运行 /plugin marketplace add ets-public/brevi 和 /plugin install brevi@brevi，即可同时添加 skill 和 MCP 服务。
• llms.txt： brevi-lang.org/llms.txt、llms-full.txt，以及所有以 Markdown 格式提供的文档页面（在地址末尾添加 .md）。
• 编辑器规则适用于 Cursor、Copilot、Windsurf 和 Cline，见 skills/rules/；LangChain、OpenAI Agents SDK、CrewAI 和 Vercel AI SDK 的测试示例见 integrations/。
• Agent 平台模板见 templates/：使用 E2B、Daytona、Modal 或 Cloudflare Sandbox（或 Docker）运行 Agent 编写的 Python 代码；所有能力和限制仅由代码授予，通过一个镜像和一个 run_python 工具即可使用。
• 提示词： 要求模型提供简洁直接的解决方案，并说明代码将被编译。预期使用 CPython 的模型会进行手工优化，这会消耗 token，而且在 Brevi 下通常更慢。详情见面向 AI Agent。

工作原理

Brevi 会优先尝试最快的路径。类型化构建会为每个值推导出固定类型，并生成纯 Rust；大多数已保存的 Agent 程序都通过这种方式构建（813 个中有 567 个），速度数据也来自这条路径。如果程序中的值会改变类型，或者类型化构建无法精确匹配，则会使用动态构建：仍然是原生 Rust，但处理的值表现得像 CPython 的对象。大多数 numpy 代码都由 Brevi 自带的 numpy 构建；在搭载 AVX2 和 AVX-512 的 CPU 上，使用单线程时，其输出与 numpy 逐字节一致（其他环境下，少数函数的最后一位可能不同）。Agent 最常用的库也同样如此（requests、httpx、pydantic、各类 LLM SDK、mcp、jinja2、polars、sqlite3、duckdb、tokenizers、safetensors、onnxruntime；自 v0.26.0 起）。其他库调用（pandas、yaml 等）则会在加载到原生程序中的 CPython 里运行。只有这些方式都无法构建文件时，brevi run 才会回退到 python3。任何不走类型化路径的构建都会用一行 JSON 说明所用路径及原因（{"path":"dynamic","line":3,"fn":"show","why":...}），让 Agent 知道该重写哪个函数。整数会像 Python 中一样增长到超过 64 位，不会悄悄溢出。在 --sandbox 模式下，以及默认启用沙箱的 MCP 工具中，程序默认无法访问文件、网络、原生代码或库，除非调用方授予权限（--allow read,write、--allow-read data、--allow-write out、--allow-net api.example.com、--allow-py yaml）；代码无法自行授予权限，拒绝访问即为最终结果，而且沙箱中的程序绝不会回退到 python3。在 Linux 上，沙箱中加载的 CPython 也会通过 Landlock 受到相同的文件权限限制。沙箱由 Brevi 自行生成的代码强制执行：它不使用 seccomp 过滤器、命名空间或虚拟机；--allow-py 和 --allow native 代表完全信任；Landlock 仅适用于 Linux；目前尚未经过外部安全审查。请将其视为适用于你大体信任的 Agent 代码的轻量限制层；运行不可信代码时，也应使用容器或虚拟机。--limit cpu=2,mem=512,time=10,output=64（MCP limits）会在程序首次达到 CPU、内存、墙钟时间、输出或文件大小限制时停止程序；written、net、threads、fds 和 files 限制自 v0.26.0 起新增（威胁模型）。架构图和详细信息见：docs/ARCHITECTURE.md。

Brevi 还有一种专用于 .bv 文件的、更精简的类 Python 语言，会在运行前完成全面检查：BREVI.md（3,508 个 token，可通过 brevi guide 获取）、REFERENCE.md 和 LIBRARIES.md（Brevi 支持的 Rust crate 和 Python 库）。用纯 Python 完成任务对 Agent 来说成本更低，因此 Agent 工具要求使用 Python。

状态：v0.27.1

v0.27.1 是 v0.27.0 的修复版本：brevi-python 现已可在 macOS 上运行，发布流程也会测试实际发布的归档文件。下方的数据是在 v0.27.0 上测得的；其他内容均未变化。

• 以 CPython 自身的测试衡量。 tools/conformance.py 通过 Brevi 运行 CPython 3.13 的 test_grammar、test_scope、test_int、test_list 和 test_dict 测试：在 v0.27.0 中，311 个计分测试里有 250 个（80.4%）打印的内容与 CPython 完全一致，38 个在构建时被拒绝，8 个虽构建成功但答案不同（差异全部体现在退出状态），没有测试发生崩溃（报告）；在 v0.26.0 中，匹配的有 181 个、被拒绝的有 66 个、答案不同的有 44 个、发生崩溃的有 5 个。在 250 个匹配项中，有 46 个不打印任何内容，因此它们只能说明程序成功构建并正常退出。另一个单独的数字涵盖 Agent 最常用的标准库模块（itertools、collections、re、textwrap、functools、string）：554 个测试中有 250 个（45.1%）匹配，22 个答案不同（报告）。在 main 分支上（11 月 12 日；从下一个版本开始），评分器会运行两个测试分片中的每一项测试（没有测试再被归为无法提取）：core 增加了 test_contains、test_binop、test_richcmp 和 test_set，stdlib 增加了 test_graphlib、test_colorsys 和 test_deque；core 的匹配率为 96.5%（683 个计分测试中有 659 个匹配，以下按设计拒绝的测试不计入；其余 24 个目前无法拆分为独立脚本，其中 22 个使用了 unittest 的 enterContext），stdlib 的匹配率为 99.7%（726 个测试中有 724 个匹配；最后 2 个仅通过 CPython 桥接匹配）；根据 main 分支在最近一次合并后的测量结果，两者都没有任何错误答案。这里涵盖的是评分的 18 个文件，并非 CPython 的全部测试：还会测量更多测试文件以供规划（tools/conformance.py --candidates），但暂未计分。Brevi 的目标是让构建要么与 CPython 匹配，要么被拒绝；每个答案不同的情况都违背这一目标，后续版本会优先修复这些问题。对于你自己的程序，brevi verify x.py --input tests/ 会使用相同的输入运行原生构建和 CPython；如果标准输出、退出代码和标准错误一致，就会打印证书（文件和输入的哈希、路径、加速比），否则会打印首个差异行（从 v0.26.0 开始）。从下一个版本开始，将运行字符串代码的测试（compile、exec、eval）计为按设计拒绝：沙盒化的原生二进制会有意拒绝运行字符串中的新代码。这些测试列在 compat/conformance_by_design.txt 中（core 有 39 个，stdlib 有 5 个），不计入分母，其数量会显示在每项分数旁边。需要包含孤立代理项的字符串（#450）或调用 CPython 私有辅助函数（#481）的测试，会列在 compat/conformance_needs_string_model.txt 和 compat/conformance_cpython_private.txt 中，并作为不匹配项保留在分母内；现在 main 分支上的这两个列表都是空的，因为这些测试已经匹配。测试 CPython 自身机制的项目（子进程中的崩溃检查、multiprocessing、_testinternalcapi），以及 CPython 在参考构建中自身跳过的测试，都会连同原因一起排除，与 cpython_only 测试相同。完全不在目标范围内的情况：标准错误中的文本，以及 CPython 每次运行都会改变的输出（字符串集合的顺序、__del__ 的执行时机）。
• 回归集：已保存的 Agent 程序。 对于未修改的 Python 文件，Brevi 能构建全部 591 个已保存的 Agent 程序和全部 18 个大型程序（国际象棋、文字冒险、解释器），并且每个程序的输出和退出状态都与 CPython 匹配。这些是我们自己的基准任务的解答，通过测试后便会保留，因此这项检查用于确保没有回归，而不是衡量 Python 的支持程度。Codon 能构建 591 个程序中的 206 个，其中 36 个结果不正确（Codon 会有意改变部分 Python 行为，例如 64 位整数）；Nuitka 则与它们全部匹配（bench/compare）。
• 类型化路径更快。 在 12 个计算密集型程序上（n-body、spectral norm、fannkuch、binary trees 等），默认构建的运行速度比 CPython 快 1.6 至 37.9 倍，中位数为 9.3 倍；--release 的速度快 2.1 至 38.8 倍，中位数为 9.8 倍（测量时间为 2026 年 11 月 12 日，使用 Ryzen 9 5950X，在 WSL2 下运行；11 月 3 日在 4 核容器中测量时，只要 Codon 能构建，--release 的速度便大致与 Codon 持平）。这些数据来自类型化构建。值的类型会发生变化的程序会使用动态构建，其运行速度大致与 CPython 相当或略慢：在同样的 12 个程序上，速度为 CPython 的 0.5 至 1.4 倍，中位数为 0.85 倍；813 个已保存的 Agent 程序中有 567 个使用类型化构建，而 CPython 测试的 230 个原生构建中仅有 25 个使用类型化构建。brevi check 的响应时间远低于 1 秒（新文件的中位数为 144 毫秒），未修改的程序则从缓存重新检查，耗时约 10 毫秒。
• 对 Agent 来说，成本大致相同。 在发布测试中，Claude Sonnet 和 Haiku 用纯 Python 解答 24 项任务，分别由 CPython 和 Brevi 检查，并对比 API 总费用。标准是：每项任务都通过、Brevi 的费用不超过 CPython 的 10%，且至少 90% 的最终程序能原生构建。v0.27.0 在两轮测试中达到标准：Sonnet 的费用比为 1.08 倍（按任务计算的 95% 区间为 1.04 至 1.13 倍），Haiku 为 0.97 倍；两边的每项任务都通过，96 个最终程序中有 92 个成功原生构建（其余 4 个仅因另一个任务当时正在使用同一台机器而构建失败，重新构建时均能成功原生构建）；早期版本中，Sonnet 的费用比为 1.03 至 1.09 倍。因此，Brevi 并不会降低普通任务的模型费用；费用大致相同，或高出几个百分点。在这些测试中，如果 Brevi 无法构建某个文件，就会改用 CPython 运行，模型不会看到 Brevi 的构建错误，与 brevi run 的行为相同。在四项高负载任务中，仅告知 Brevi 这一侧其代码会被编译，应以简洁的方式编写，费用比为 0.58 倍（Sonnet）和 0.53 倍（Haiku）；CPython 尚未使用相同的提示语运行，因此这些数字目前还不能说明 Brevi 本身能节省多少费用。
• 已知差距： match 语句和仅在运行时才知道内容的文本的 eval 尚无法原生构建（字面文本的 eval 从 v0.27.0 起支持）；async / await 从 v0.26.0 起支持；基于库中类构建的类会整体在 CPython 中运行；--standalone 仅支持 Linux；在 Windows 上，--limit cpu、file 和 fds 会被拒绝（mem 由 Job Object 管理）（从 v0.27.0 起，库调用、生成器、async 以及 Brevi 自带的 sqlite3、requests/httpx、duckdb、onnxruntime 和 MCP 均可在 Windows 上运行）。请参阅支持情况与限制和路线图。 每周一在发布测试通过后发布一个版本（重要修复可能会提前发布）；在此之前，变更会汇总在 CHANGELOG.md 的“Unreleased”下。

方法和日志：bench/README.md 和 基准测试。v0.8 到 v0.23 的结果（此期间 Brevi 自身语言是主要测试目标）见 bench/HISTORY.md。

从源代码构建

git clone https://github.com/ets-public/brevi
cd brevi
cargo build --release
./target/release/brevi run examples/top.py < examples/input.txt
sh tools/ci_local.sh      # the checks a pull request runs

需要 Rust stable 和 python3。如果要开发编译器本身，请参阅：AGENTS.md。

项目结构

路径	内容
docs/ARCHITECTURE.md	源文件如何变为原生程序，附有示意图
src/lexer.rs、src/parser.rs、src/ast.rs	从源代码到语法树
src/emit.rs	检查和 Rust 代码生成
src/prelude.rs	注入每个生成程序的运行时
src/main.rs	CLI、rustc 调用和错误映射
src/caps.rs	allow 行和 --sandbox 检查
examples/	示例程序
tests/	程序和错误案例的预期输出
tools/parity_probe.py、tools/parity/	使用 CPython 和 Brevi 运行的简短纯 Python 探测脚本；列出无提示差异和不支持的情况
tools/conformance.py	CPython 自带测试套件，拆分为独立脚本并使用 Brevi 构建；最新结果
tools/compat.py、compat/baseline.txt	所有曾经通过的基准测试解法；必须确保它们在新的工具链上仍能通过
integrations/	通过 brevi mcp 使用 LangChain、OpenAI Agents SDK、CrewAI 和 Vercel AI SDK 的示例
templates/	在 E2B、Daytona、Modal、Cloudflare 和 Docker 上运行的 Agent 沙箱，使用 Brevi 沙箱和限制执行代码
grammar/、tools/grammar_check.py、tools/lark_to_gbnf.py	用于受限解码的语法及其检查
tools/upstream_watch.py	为 Rust、Python 和 crate 的新版本创建审查议题
.github/	每日工具链矩阵、上游监控、Dependabot（见“保持更新”）

保持更新

Brevi 绝不能落后于 Rust 或 Python，曾经通过的代码也绝不能在没有提示的情况下失效。

• 工具链（.github/workflows/toolchains.yml）：构建 Brevi，并重新运行 tests/check.sh 和 tools/compat.py check （所有 1,900 多个曾经通过的 Brevi、Python 和 Rust 解法）。每天使用 Rust stable 和最新的 Python 预发布版本及下一个预发布版本运行；每周一还会使用 Rust beta 和 nightly 运行，此时 nightly 会报告生成的 Rust 代码中的弃用警告和未来不兼容警告，以及最新版本的 edition 相关警告，这些问题会在约 6 至 12 周后进入 stable。PR 仅使用 .github/rust-version 中固定的 Rust 版本进行测试（发布和其他工作流也一样；每日运行会测试最新的 stable 版本），跳过草稿和仅修改文档的变更，并且仅在编译器或基线发生变化时重新运行旧解法。 同一提交已测试过的工具链会跳过。失败时会创建一个 toolchain 议题。为节省 Actions 分钟数，请在合并前运行 sh tools/ci_local.sh（执行相同检查）。
• 上游版本（upstream.yml，每周两次）：每当有新的 Rust stable、Python 版本或测试／示例中固定使用的更新版 crate 时，就创建一个 upstream 议题，其中列出新增语言特性和稳定化的 API，并附带审查清单。
• Dependabot：每周更新 Cargo 依赖项和 GitHub Actions 版本。

在某项变更使更多解法通过后，运行 python3 tools/compat.py baseline，将它们纳入基线。 绝不要为了通过检查而从 compat/baseline.txt 中删除某一行。

贡献与安全

错误报告和拉取请求请参阅 CONTRIBUTING.md；私下报告漏洞请参阅 SECURITY.md。其他事宜请发送邮件至 [email protected]。

许可证

Apache License 2.0。详见 LICENSE。