Brain0-ai/brain0

现在的编码 agent 编写了大部分 diff：持续不断地、并行地、不透明地进行。 brain0 **被动地**为你的代码库构建决策图：每一个 **commit** 都与其背后的 **agent 意图**相关联， 精确到单个**函数**，并包含带有日期的历史记录、漂移检测、针对 agent *读取*内容的 DLP 审计， 以及呈现从绿色到红色的二维**风险评分**。没有 hooks，不需要 agent 配合，无需修改代码：它只读取 git 以及你的 agent 已经写入磁盘的记录。 ## 快速开始 ``` npx brain0 up ``` 就是这样。在任何代码库中，`up` 会从你的 git remote 推断出 repo id，索引 git 历史（即**事实**）， 被动地接收你的编码 agent 会话（即**意图**，支持自动发现 Codex 和 Claude Code）， 并在 `http://localhost:8787` 打开 GUI： 这是一个可探索的代码库图谱，从 repo 到模块、文件和符号，点击 commit 即可揭示其背后的 prompt、文件级 diff 以及一目了然的风险。 然后养成习惯： ``` brain0 today # morning triage: what agents did, riskiest first brain0 report # the accountability report (add --md to share it) brain0 query "why did the parser break" # root-cause debug over the graph ``` ## 需要准备什么 唯一硬性要求是 **Node.js ≥ 20**。brain0 是离线优先的：在没有安装其他任何东西的情况下，它依然能实现端到端的运行：确定性摘要、本地 feature-hash embeddings、零出口流量。本地模型会让它变得*更好*，但绝不是*必须*的。 | 组件 | 用途 | 缺失时 | |---|---|---| | **Node.js ≥ 20** | 所有功能 (`npx brain0 up`) | (必需) | | **git** | commit 历史（事实部分） | 文件系统检查点模式 (`brain0 watch`) | | **一个编码 agent**：Codex (`~/.codex`) 或 Claude Code (`~/.claude/projects`)，自动发现 | *为什么*层：prompt、漂移、读取/DLP | 仅包含 commit 和代码的图谱 | | **[Ollama](https://ollama.com)** + 模型（见下文） | 模型编写的摘要 · 语义搜索 · GUI 智能聊天 | 确定性摘要 · feature-hash embeddings · 仅检索式回答 | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` (可选加入) | 用于 GUI 智能聊天的托管 LLM | 本地 Ollama（默认） | ### 推荐的本地模型 ``` ollama pull qwen3:4b # summarizer (default) ollama pull qwen3-embedding:0.6b # embeddings (default; nomic-embed-text is the auto-fallback) ``` 两者都可以在普通硬件上运行。在小型 GPU（约 4 GB VRAM）上，请在首次运行（用于填充缓存）时使用更轻量的摘要模型。摘要在 `~/.cache/brain0/` 中进行内容缓存，因此后续的每次重构都不需要任何模型调用代价（即使是中断的运行也会保留其进度）： ``` BRAIN0_SUMMARIZER_MODEL=qwen3:1.7b npx brain0 up ``` 如果缺少已配置的模型，brain0 会准确告诉你需要拉取什么，并会优雅地降级（embedder 会回退到 `nomic-embed-text`，然后是本地模型）。每一个选择都是可覆盖的：`BRAIN0_SUMMARIZER_{PROVIDER,MODEL,ENDPOINT}`, `BRAIN0_EMBED_{PROVIDER,MODEL,ENDPOINT,DIM}`，`BRAIN0_LLM_PROVIDER`。详情见 [`docs/models.md`](./docs/models.md)。 ## 你的代码库目前无法回答的问题 - *是哪个 prompt 引入了这个 bug？* - *谁（agent 还是人类）修改了这个函数，什么时候改的，以及**为什么**改？* - *agent 声称它“改动很小”。**真的是这样吗？*** - *在推送代码之前，是否有会话读取了 `.env` 或私钥？* - *这项更改看起来无害。它后来被证明危险吗？* brain0 从构建机制上解答了这五个问题。其中有三个答案是你在别处找不到的： ### ① 漂移：声明与实际操作 Agent 会叙述它们更改了什么；git 记录了实际更改了什么。brain0 会协调两者并对差异进行评分。以下摘自 brain0 自身的报告： ``` drift — declared vs done (41) · [1.00] claude-code — changed but not declared: crates/brain0-cli/src/main.rs, packages/gui/src/main.ts … +12 more ``` ### ② 敏感读取：针对 agent 上下文的 DLP brain0 会记录每个会话**读取**了哪些文件（仅记录路径和 secret *种类*，绝不记录具体值），因此你能清楚知道哪些信息传达到了可能为远程的模型： ``` sensitive reads — DLP (7) · claude-code read crates/brain0-agentsrc/src/driver.rs [env_secret] · 8 read(s) outside the repo reached the model's context ``` ### ③ 具备学习能力风险：绿色 → 红色 每一个工件（artifact）都带有一个**先验**评分（影响范围、变动、漂移、diff 大小），并与一个由证据（回退、即时修复）提供的**后验**评分相融合。那些*看起来安全但后来被证明危险*的更改会被标记为**黄金信号**：即值得研究的模式。 ## 赋予你的 agent “为什么层”（MCP） 这同一张图谱也是一个查询通道，你的编码 agent 可以在**触碰代码之前**调用它：通过引用获取溯源感知的上下文，无需通过 MCP 推送任何繁重的负载。 ``` claude mcp add brain0 -- brain0 mcp ``` | 工具 | agent 获取的信息 | |---|---| | `brain0_context` | 文件/符号的风险、近期历史以及背后的意图（agent · 模型 · 漂移） | | `brain0_blame` | *是哪个意图编写了这一行*：通过实时解析，将 `file:line` 解析为其对应的符号 | | `brain0_debug` | 针对某个问题的根因排查候选项，具备近期感知和风险感知能力 | | `brain0_audit` | repo 风险分布、黄金信号、风险最高的节点 | 你的 agent 将不再重复破坏它无法记住的内容。卸载 brain0 会使其再次遗忘。 ## 工作原理 brain0 是一个**纯粹的观察者**：它从不向你的代码库写入内容。 ``` ┌───────────────────────── GUI (PixiJS / TS) ─────────────────────────┐ │ bipartite graph · LOD lens · risk color · timeline · search bar │ └───────────────▲─────────────────────────────────────▲───────────────┘ │ references / highlights │ on-demand ┌───────────────┴────────────┐ │ hydration │ Internal agent (TS) │ │ │ RAG-on-graph · your LLM │ │ └───────────────▲────────────┘ │ │ index queries │ ┌────────────────────────┴─────────────────────────────────────┴──────────────┐ │ Abstract storage (one `Storage` trait, pluggable backends) │ │ light index + embeddings | heavy payload (dedicated store) │ │ SQLite + sqlite-vec (local, open core) | Postgres + pgvector (enterprise) │ └────────────────────────▲──────────────────────────────────────────────────────┘ │ append-only (client-server) ┌────────────────────────┴─────────────────────────────────────────────────────┐ │ Core observer (Rust) │ │ git reader + fs-watcher / checkpoint engine (no-git fallback) [FACT] │ │ passive transcript + memory ingest (Codex, Claude Code, …) [DECLARED] │ │ Tree-sitter (symbol extraction + AST-fingerprint identity) │ │ declared↔done reconciliation (gap-filling + drift) │ │ a-priori risk · a-posteriori risk hooks (event-driven) │ └────────────────────────▲─────────────────────────────────────────────────────┘ │ passive read-only (no agent cooperation) ┌──────────┴───────────┐ │ Coding agents │ write transcripts + memory to disk; │ (e.g. Codex, Claude)│ brain0 reads them, like it reads git └──────────────────────┘ ``` 不可违背的原则： 1. **被动观察**：从不修改你的代码库，从不 commit/checkout，从不干扰 git。 2. **放大镜**：缩放操作会深入到*同一个*对象中（repo → 模块 → 文件 → 符号），绝不会加载不同的节点。 3. **没有无端产生的新节点**：一个演进的实体始终保持为同一个节点（通过重命名/移动追踪实现确定的、跨机器的符号身份），并具有带日期的版本链。 4. **轻量索引，懒加载重型 payload**：可导航的图谱很小，可保存数年；diff、消息和摘要按需实时加载。 5. **开源且可组合**：自带数据库和你的 LLM key，或者完全离线运行。 ## 对比 | | `git blame` | 供应商仪表盘¹ | Git AI | **brain0** | |---|:---:|:---:|:---:|:---:| | 谁提交了某行代码 | ✅ | ✗ | ✅ | ✅ | | 哪个 **prompt/意图**产生了更改 | ✗ | ✗ | ✅ | ✅ | | 跨 agent、供应商中立 | ✅ | ✗ | ✗ | ✅ | | **漂移**：声明与实际操作对比 | ✗ | ✗ | ✗ | ✅ | | agent **读取**了什么（包括 secret、DLP） | ✗ | ✗ | ✗ | ✅ | | 每个文件/符号的**风险评分**，由证据驱动 | ✗ | ✗ | ✗ | ✅ | | 可探索的**图谱 GUI**，支持时间穿梭 | ✗ | ✗ | ✗ | ✅ | | 零集成（你的 agent 中不需要 hooks） | ✗ | ✗ | ✗ | ✅ | | 本地优先，默认离线 | ✗ | ✗ | ✗ | ✅ | ¹ Copilot Metrics API、Cursor 团队分析、Claude Code 分析：针对特定供应商的聚合数据（会话、接受的 LoC），没有行/符号级别的溯源，也没有因果关系。 ## 命令 | 命令 | 功能 | |---|---| | `brain0 up` | 索引 + 观察 + 提供 GUI 服务，一次性执行 | | `brain0 today` | 过去 24 小时分诊，优先关注 (`--since 7d`) | | `brain0 report` | 漂移 · 敏感读取 · 最高风险 · agent 足迹 (`--md`) | | `brain0 query "<问题>"` | 通过引用在图谱上进行根因排查与调试 | | `brain0 mcp` | 通过 stdio 提供查询通道服务（上下文/blame/调试/审计） | | `brain0 ingest` / `observe` / `watch` | 底层的事实/意图观察器 | | `brain0 rewind` | 从记录的检查点恢复工作区（`watch` 的安全网） | | `brain0 guard` / `preflight` | DLP：标记已传达到远程模型的 secret 读取 · 在 commit/运行前将其拦截 | | `brain0 provenance` / `attribution` / `attest` / `compliance` | 每次 commit 的 AI 溯源 · 每个 hunk 的归因 · 签名（Ed25519，in-toto）证明 · 审计员包 | | `brain0 verify` / `audit` / `purge` / `reembed` | 完整性、审计日志、加密粉碎、重新 embedding | ## 从源码构建 前置条件：**Rust**（见 `rust-toolchain.toml`），**Node 20+**，**pnpm**。 ``` cargo build && cargo test # Rust core (14 crates) pnpm install && pnpm -r build && pnpm -r test # TS workspace (shared · agent · gui · server) ./scripts/e2e.sh # cross-language end-to-end check # 一体化开发循环 (build → ingest → observe → server :8787 → GUI :5173) pnpm dev --repo myorg/myrepo ``` GUI 的**刷新**按钮会重新运行同一个被动观察器并实时重新进行 embedding；它仅在 `127.0.0.1` 上提供同源服务。 ``` crates/ Rust core (model, parser, identity, storage, observer, reconcile, risk, agentsrc, crypto, models, policy, attest, mcp, cli) packages/ TypeScript (shared, agent, gui, server, cli) schema/ SQL DDL for the local SQLite backend docs/ Documentation (agent-artifact schemas, security, models, open-core, governance) ``` ## 默认隐私与安全 - **默认离线**：无 key ⇒ 本地 embeddings + 本地模型（Ollama 可选）；任何数据都不会离开本机。远程 LLM/embeddings 需要明确选择加入，并且上下文在出口前会被脱敏处理。 - **摄取时进行 secret 扫描**：记录在被存储、摘要化或 embedding *之前*，会被扫描并脱敏（使用类型占位符，绝不保留原值）；`BRAIN0_EXCLUDE` / `BRAIN0_REDACT` 可添加自定义规则。原始 prompt 文本**不会被持久化**；仅保留模型生成的摘要。 - **静态加密**：采用信封加密的 payload 存储（ChaCha20-Poly1305，KEK 轮换，加密粉碎清除），并具有严格的文件权限。 - **仅追加，内容寻址**：图谱具备防篡改特性（`brain0 verify`），并带有仅追加的安全审计日志。 威胁模型和诚实的局限性说明：[`docs/security.md`](./docs/security.md)。 ## 开放核心 本代码库中的所有内容均是免费且开源的，遵循 [Apache-2.0](./LICENSE) 协议，并且自身功能完备，**没有许可证检查、功能开关或残缺的代码路径**。 团队/托管功能（实现相同公共 `brain0_storage::Storage` trait 的 PostgreSQL + pgvector 后端、签名授权、多租户服务器）位于一个单独的 **brain0-enterprise** 代码库中（AGPLv3 + 商业授权）。brain0 从不依赖于 brain0-enterprise。完整的边界和理由说明：[`docs/open-core.md`](./docs/open-core.md)。 ## 贡献 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。参与即表示你同意遵守[行为准则](./CODE_OF_CONDUCT.md)。我们根据 CLA 接受贡献（见 [`cla/`](./cla/)），这使得开放核心的双重许可能够持续发展。 ## 许可证 [Apache-2.0](./LICENSE) © The brain0 Authors.

标签：AI代码审计, AI风险缓解, DLP, LLM Agent, MITM代理, Rust, 代码溯源, 可视化界面, 开发安全, 网络流量审计, 软件供应链安全, 远程方法调用, 通知系统