zengxzh/buer

# BUER (不二) *一个意图，无分。BUER.* [](LICENSE) [](https://modelcontextprotocol.io) BUER 是 AI 编码代理的 **本地可靠性双向护栏层**。 与传统 LLM 可观测性工具不同，这些工具监控代理 *说了什么*（跟踪、令牌、提示），BUER 冷静地监控代理 **实际上对你的代码做了什么**（AST 修改、依赖图、git 状态和测试结果）。 BUER 作为本地结构监控器，通过双向循环工作： * **警报（反应式）：** 当代理循环、越界或作弊（例如，篡改测试以隐藏损坏的代码）时，停止代理。 * **协助（主动性）：** 在编辑发生之前，直接将结构事实（爆炸半径、依赖简报、安全网警告）注入代理的上下文中。 **一切都是 100% 自动推导的。** BUER 从代理已经产生的客观代码事实中读取（文件修改、git 状态、测试输出）。从不要求代理声明其意图或合作。即使与混乱的代理和 vibe 编码者一起工作，它也能完美运行。 BUER 的测试-定义关联从启发式名称匹配（始终可用，无需设置）开始，并在使用 `--cov-context=test` 运行 pytest 时升级到 **精确层** — 有关详细信息，请参阅 [docs/SETUP.md](docs/SETUP.md#precise-testdefine-association-opt-in)。 ## ⚡ 为什么选择 BUER？（代理可观测性差距） 当 AI 代理卡住或开始破坏事物时，传统的 MLOps 工具（Langfuse、Braintrust、Phoenix）只能看到一系列“成功的 200ms LLM API 响应”。他们对代码层视而不见。 BUER 通过直接在通过 `tree-sitter` 维护的本地有向无环图 ($\mathcal{G}_D$) 上操作来弥合这一差距。 | AI 代理盲点 | BUER 如何解决它（100% 自动推导） | | :--- | :--- | | **P1：无限循环和 churn** | `stuck_region` / `define_loop` / `token_waste` — 检测代码状态无法结构性地收敛 | | **P2：“修复一个，破坏十个”** | `regression` — 通过调用图将测试失败链接回结构编辑；当 pytest `--cov-context=test` 存在时，升级到精确的测试↔定义映射 | | **P3：作弊 / 伪造成功** | `test_tampering` — 如果代理突变测试断言以绕过失败，则立即升级到人类 | | **P4：范围漂移 / 胡乱运行** | `boundary_breach` + `task_scope_breach` — 严格的本地护栏 | | **P5：在恢复时丢失上下文** | `BUER Recap` — 上一次会话的更改和未解决问题的简单语言摘要 | | **P6：对附带损害视而不见** | `influence cone` — 将预编辑爆炸半径预览注入代理的上下文中 | | **P7：未受保护的代码库** | `safety-net warning` / `add-tests assist` / `commit assist` — 标记风险并提供具体的下一步行动 | 以上每个信号都建立在 **客观代码事实锚点**（版本链、测试结果、文件路径、调用图）之上。BUER 不推断意图，也不对代理的输出进行评分 — 它报告代码中可观察到的真实情况。 ## ☸️ 来源：非二法门 BUER 的名字来自 **不二法门** (*bù èr fǎ mén*)，这是 *维摩诘经* 的核心教义。**不二** ("not-two") 代表非二性 — 超越现实的对立矛盾（损坏/工作，这个/那个）。当菩萨试图用语言来定义这个非二法门时，维摩诘以绝对的沉默回答。最真实的法门是那个不再分割的法门。 BUER 将这种哲学带入 AI 软件工程。它基于 **结构决定理论 (SDT)**。BUER 维护的依赖图 — $\mathcal{G}_D$ — 是一个有向无环图，其节点是 *决定*（每个定义的当前结构状态）和其边将生产者映射到消费者。 通过分析这个客观图及其历史，BUER 使代理锚定于一个单一、连贯、无分割的意图，而不是陷入自我矛盾。 参考：Zeng, Xiaozhou (2026). *结构决定理论：现实、时间、不可逆性和空间的单一公理框架.* PhilArchive. ## 🛠️ 如何工作：双向循环 BUER 作为与 Claude Code 等执行环境并行的本地后台服务器运行。它通过在相关代理操作后触发的轻量级 `POST` 端点挂钩到工作流程： ``` ┌──────────────────────────────┐ │ AI Agent (Claude Code) │ └──────────────┬───────────────┘ │ 1. Hooks (post-edit, etc.) │ 2. Proactive Context Triggered Automatically │ (Blast Radius, Briefings) ▼ ┌──────────────────────────────┐ │ BUER Server │ │ (AST / Git / Test Monitor) │ └──────────────────────────────┘ ``` ### 端点 * `/buer/session-start` — 在会话初始化或恢复时触发 * `/buer/post-edit` — 在编辑、写入或多编辑后拦截文件差异 * `/buer/post-read` — 捕获读取活动以跟踪上下文使用 * `/buer/post-bash` — 捕获终端执行，解析测试输出和堆栈跟踪 * `/buer/stop` — 当代理完成其回合时触发 * `/v1/metrics` — 通过 `/v1/metrics` 桥接 OpenTelemetry 成本/令牌指标（可选） ### 1. 警报（防御） 当信号触发时，BUER 采用 **两步升级**：它首先通过注入上下文静默地推动代理自我纠正。如果问题持续存在，则升级到您那里。**完整性违规（如 `test_tampering` 或边界越界）绕过推动并立即升级到您那里。** * `stuck_region` — 代理不断敲打相同的代码块，无法收敛 * `define_loop` — 代理将定义回结构上等效的早期状态 * `test_tampering` — 代理更改断言以通过测试，而不是修复功能代码 ### 2. 协助（进攻） BUER 故意构建了三个不同的通道（*警报、健康提示、内联协助*），在错误发生之前帮助塑造代理的工作： * `structural_briefing` — 预编辑上下文：谁依赖于这段代码，它依赖于什么？ * `debug_range` — 将调试缩小到与崩溃堆栈相交的最近更改 * `safety-net` — 如果代理修改具有巨大爆炸半径的定义，则警告代理 ## 💰 成本与节省跟踪（可选） BUER 具有诚实的、基于遥测的财务编译器。通过在 `/v1/metrics` 处桥接 Claude Code 的 OpenTelemetry 指标（这些指标传输原始令牌计数，但 *排除* 会话内容或代码有效负载），BUER 计算您的实际支出与估计的干预节省之间的差异，分为三个透明的层级： * **层 1（遥测支持）：** 实际测量的 API 成本与计算出的干预节省相匹配 * **层 2（模型估计）：** 从本地编辑轮次估算，乘以 LLM 列价 * **层 3（代理指标）：** 严格的工程指标（churn 计数器、迭代循环）没有财务数字 ## ⚙️ 安装与设置 BUER 需要 **Python ≥ 3.10**。它通过嵌入的 `tree-sitter` 语法本地解析 Python、JavaScript 和 TypeScript — 不需要重型外部编译器工具链即可实现其核心功能。 ``` git clone https://github.com/zengxzh/buer.git cd buer pip install -e . ``` ### 运行服务器 在本地启动监控器： ``` buer-server --host 127.0.0.1 --port 7777 --db .buer/store.sqlite ``` 要配置您的代理环境以将挂钩发送到 BUER，或连接到 systemd 服务持久运行时，请参阅 [docs/SETUP.md](docs/SETUP.md). ### 必需：`.buer/` 数据保护 BUER 将其所有状态存储在项目根目录的本地 `.buer/` 目录中（WAL 模式下的 SQLite 数据库）。为了保护这些数据，**BUER 在第一次在 git 仓库中运行时自动将 `.buer/` 添加到您的项目 `.gitignore` 中** — 如果不存在，则创建 `.gitignore`，否则将其附加到其中（您的现有条目永远不会被修改）。 BUER 还 **监控 `.gitignore`**：如果条目被删除或文件被删除，BUER 在下一次编辑或会话中重新添加 `.buer/`。这是故意的并且 **必需的** — 没有它，常规的 git 操作会破坏 BUER 的数据： - `git clean -fd` 会完全删除 `.buer/` 目录。 - `git checkout` / `git reset --hard` 会回滚数据库（或者，如果 WAL 文件部分回滚，会损坏它）— 丢失所有累积的结构历史。 如果您故意想跟踪 `.buer/` 在 git 中，请将显式的 `!.buer/` 行添加到您的 `.gitignore` 中；BUER 尊重它，不会覆盖它。 ## 🔒 安全性与隐私 BUER 为本地优先、尊重隐私的开发而构建。**BUER 100% 在您的本地机器上运行。** 它永远不会上传您的源代码、文件结构、提示或凭据到任何第三方云服务器。 ## 状态 Alpha — 核心实现完成（图、信号、协调、协助、摘要）；正在进行积极开发和内部测试。 ## 📄 许可证 本项目根据 **商业源代码许可证 1.1 (BSL-1.1)** 许可。 * **权限：** 评估、开发、个人或内部商业使用免费 — 包括监控您或您组织的 AI 编码代理。 * **限制：** 不能作为商业托管或管理服务部署给第三方，也不能作为主要价值来自 BUER 的商业产品，除非获得单独的商业许可证。 * 在 **2030-06-02**（变更日期），许可证转换为 **Apache 许可证，版本 2.0**。 有关完整条款，请参阅 [LICENSE](LICENSE)。 ## 作者 Xiaozhou Zeng

标签：AI 可观测性, AI 编码代理, AST 分析, Git 状态, MLOps, Vibe 编码, 主动性辅助, 代码事实, 代码可靠性, 代码安全, 代码审查, 代码监控, 依赖图, 双向防护, 反应式警报, 启发式名称匹配, 本地守护, 模型上下文协议, 测试定义关联, 测试结果, 混沌代理, 漏洞枚举, 精确层级, 结构监控, 自动推导, 逆向工具