内容
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/brain0-wordmark-dark.svg">
<img alt="brain0" src="docs/assets/brain0-wordmark-light.svg" width="380">
</picture>
<br/>
**AI 编写代码的黑盒子。**
`git` 告诉你代码**发生了什么变化**，brain0 告诉你**为什么**：是哪条提示词写了它，
代理**读取**了什么来编写它，以及你是否可以信任它。
[](https://github.com/Brain0-ai/brain0/actions/workflows/ci.yml)
[](./LICENSE)
[](https://www.npmjs.com/package/brain0)
[](./crates)
[](./packages)
[](./CONTRIBUTING.md)
[快速开始](#快速开始) · [它能回答的问题](#你的仓库今天无法回答的问题) ·
[给你的代理记忆](#给你的代理“why”层-MCP) · [工作原理](#工作原理) ·
[比较](#比较) · [文档](./docs)
</div>
---
编码代理现在编写大部分的差异：连续的、并行的和不透明的。
brain0 **被动**地构建你的仓库的决策图：每个**提交**都与背后的**代理意图**相关联，
一直到单个**函数**，带有日期历史、漂移检测、代理**读取**的 DLP 审计和一个二维**风险评分**，
从绿色 → 红色渲染。不需要钩子，不需要代理合作，不需要代码更改：它读取 git 和你的代理已经写入磁盘的记录。
> 从第一天开始就经过验证：brain0 的自身开发过程就由 brain0 跟踪。
## 快速开始
```bash
npx brain0 up
```
就这样。从任何仓库中，`up` 推断出你的 git 远程仓库的仓库 ID，索引 git 历史（**事实**），被动地摄取你的编码代理会话（**意图**，
自动发现 Codex 和 Claude Code），并在 `http://localhost:8787` 打开 GUI：
一个可探索的你代码库的图，从仓库到模块、文件和符号，单击提交后显示其背后的提示词、
每个文件的差异和风险一目了然。
然后养成习惯：
```bash
brain0 today # 上午排查：代理做了什么，风险最高优先
brain0 report # 责任报告（添加 --md 以分享）
brain0 query "为什么解析器会损坏" # 图上的根本原因调试
```
## 你需要
唯一硬性要求是 **Node.js ≥ 20**。brain0 是离线优先的：无需其他安装即可正常运行：
确定性摘要、本地特征哈希嵌入、零出口。本地模型使其 **更好**，但**不是必需的**。
| 组件 | 需要 | 没有它 |
|---|---|---|
| **Node.js ≥ 20** | 所有功能（`npx brain0 up`） | （必需） |
| **git** | 提交历史（事实方面） | 文件系统检查点模式（`brain0 watch`） |
| **编码代理**：Codex (`~/.codex`) 或 Claude Code (`~/.claude/projects`)，自动发现 | **原因** 层：提示、漂移、读取/DLP | 仅提交 + 代码图 |
| **[Ollama](https://ollama.com)** + 模型（如下） | 模型编写的摘要 · 语义搜索 · GUI 智能聊天 | 确定性摘要 · 特征哈希嵌入 · 仅检索答案 |
| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`（可选） | GUI 智能聊天的托管 LLM | 本地 Ollama（默认） |
### 推荐的本地模型
```bash
ollama pull qwen3:4b # 摘要器（默认）
ollama pull qwen3-embedding:0.6b # 嵌入（默认；nomic-embed-text 是自动回落）
```
两者都在普通硬件上运行。在小型 GPU（≈4 GB VRAM）上，使用较轻的摘要器进行第一次缓存填充运行。
摘要缓存在 `~/.cache/brain0/` 中，因此每次重建都需要零模型调用（甚至中断的运行也保留其工作）：
```bash
BRAIN0_SUMMARIZER_MODEL=qwen3:1.7b npx brain0 up
```
如果配置的模型丢失，brain0 会告诉你确切要拉取的内容并优雅地降级（嵌入回落到 `nomic-embed-text`，然后是本地）。
每个选择都是可覆盖的：`BRAIN0_SUMMARIZER_{PROVIDER,MODEL,ENDPOINT}`、`BRAIN0_EMBED_{PROVIDER,MODEL,ENDPOINT,DIM}`、`BRAIN0_LLM_PROVIDER`。
详细信息请参见 [`docs/models.md`](./docs/models.md)。
## 你的仓库今天无法回答的问题
- **哪个提示引入了这个错误？**
- **谁（代理或人类）触摸了这个函数，何时以及**为什么**？**
- **代理声称它“几乎没有改变”。**真的吗？**
- **任何会话是否读取了 `.env` 或私有密钥，然后推送代码？**
- **这个更改看起来无害。后来证明它有危险吗？**
brain0 全部回答了这五个问题。脑海中存在三个答案：
### ① 漂移：声明 vs. 实际
代理叙述他们更改的内容；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
```
### ② 敏感读取：DLP 用于代理上下文
brain0 记录每个会话**读取**的文件（路径和机密**类型**，而非值），因此你知道有什么到达了可能远程的模型：
```
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
```
### ③ 风险学习：绿色 → 红色
每个工件都带有**先验**分数（爆炸半径、变化、漂移、差异大小），与**后验**分数（反转、立即修复）相结合。
一个更改**看起来很安全但后来被证明是危险的**被标记为**黄金信号**：值得研究的模式。
## 给你的代理“why”层（MCP）
同一个图是一个查询通道，你的编码代理可以调用 **在触摸代码之前**：
基于来源的上下文，通过引用，不需要通过 MCP 推送大量内容。
```bash
claude mcp add brain0 -- brain0 mcp
```
| 工具 | 代理学习的内容 |
|---|---|
| `brain0_context` | 文件/符号的风险、最近的历史记录和背后的意图（代理 · 模型 · 漂移） |
| `brain0_blame` | **哪个意图编写了这一行**：`file:line` 通过实时解析解析为符号 |
| `brain0_debug` | 问题的根源候选，基于最近性和风险意识 |
| `brain0_audit` | 仓库风险分布、黄金信号、最节点风险 |
你的代理停止重新破坏它无法记住的内容。卸载 brain0 会使其再次遗忘。
## 工作原理
brain0 是一个**纯观察者**：它从不写入你的仓库。
```
┌───────────────────────── GUI (PixiJS / TS) ─────────────────────────┐
│ 二分图 · LOD 镜头 · 风险颜色 · 时间线 · 搜索栏 │
└───────────────▲─────────────────────────────────────▲───────────────┘
│ 引用 / 高亮 │ 按需
┌───────────────┴────────────┐ │ 水合作用
│ 内部代理（TS） │ │
│ 图上的 RAG · 你的 LLM │ │
└───────────────▲────────────┘ │
│ 索引查询 │
┌────────────────────────┴─────────────────────────────────────┴──────────────┐
│ 抽象存储（一个 `Storage` 特质，可插拔后端） │
│ 轻索引 + 嵌入 | 重载有效载荷（专用存储） │
│ SQLite + sqlite-vec（本地，开源） | Postgres + pgvector（企业） │
└────────────────────────▲──────────────────────────────────────────────────────┘
│ 追加（客户端-服务器）
┌────────────────────────┴─────────────────────────────────────────────────────┐
│ 核心观察者（Rust） │
│ git 读取器 + 文件系统观察器 / 检查点引擎（无 git 回落） [事实] │
│ 被动记录 + 内存摄取（Codex、Claude Code、…） [声明] │
│ Tree-sitter（符号提取 + AST 指纹标识） │
│ 声明↔实际协调（差距填充 + 漂移） │
│ 先验风险 · 后验风险钩子（事件驱动） │
└────────────────────────▲─────────────────────────────────────────────────────┘
│ 被动只读（无代理合作）
┌──────────┴───────────┐
│ 编码代理 │ 编写记录 + 内存到磁盘；
│ （例如 Codex、Claude）│ brain0 读取它们，就像读取 git
└──────────────────────┘
```
原则不会弯曲：
1. **被动观察**：从不修改你的仓库，从不提交/检出，从不干扰 git。
2. **放大镜**：缩放下降到同一个对象（仓库 → 模块 → 文件 → 符号），从不加载不同的节点。
3. **无不合理的节点**：一个实体进化时保持相同的节点（确定性、跨机器符号标识，具有重命名/移动跟踪），带有日期链版本。
4. **轻索引，延迟重载有效载荷**：可导航图小且持续数年；差异、消息和摘要按需水合。
5. **开源和可组合**：使用你自己的数据库和 LLM 密钥，或完全离线运行。
## 比较
| | `git blame` | 供应商仪表盘¹ | Git AI | **brain0** |
|---|:---:|:---:|:---:|:---:|
| 谁提交了一行 | ✅ | ✗ | ✅ | ✅ |
| 哪个**提示/意图**产生了更改 | ✗ | ✗ | ✅ | ✅ |
| 跨代理、供应商中立 | ✅ | ✗ | ✅ | ✅ |
| **漂移**：声明 vs. 实际完成 | ✗ | ✗ | ✗ | ✅ |
| 代理**读取**的内容（包括机密、DLP） | ✗ | ✗ | ✗ | ✅ |
| **风险评分**按文件/符号、证据驱动 | ✗ | ✗ | ✗ | ✅ |
| 可探索的**图形 GUI**，具有时间旅行 | ✗ | ✗ | ✗ | ✅ |
| 零集成（代理中没有钩子） | ✅ | ✗ | ✗ | ✅ |
| 本地优先，默认离线 | ✅ | ✗ | ✅ | ✅ |
¹ Copilot Metrics API、Cursor 团队分析、Claude Code 分析：每供应商聚合（会话、接受的 LoC），无行/符号级来源，无因果关系。
## 命令
| 命令 | 它做什么 |
|---|---|
| `brain0 up` | 索引 + 观察 + 提供 GUI，一次性 |
| `brain0 today` | 最近 24 小时分类，优先显示风险高的 |
| `brain0 report` | 漂移 · 敏感读取 · 风险最高 · 代理足迹（ `--md`） |
| `brain0 query "<问题>"` | 图上的根本原因调试，按引用 |
| `brain0 mcp` | 通过 stdio 提供查询通道（上下文/归因/调试/审计） |
| `brain0 ingest` / `observe` / `watch` | 底层事实/意图观察器 |
| `brain0 rewind` | 从记录的检查点恢复工作树（`watch` 安全网） |
| `brain0 guard` / `preflight` | DLP：标记到达远程模型的机密读取并在提交/运行前阻止它们 |
| `brain0 provenance` / `attribution` / `attest` / `compliance` | 每提交 AI 来源 · 每块归因 · 签名（Ed25519，in-toto）声明 · 审计包 |
| `brain0 verify` / `audit` / `purge` / `reembed` | 完整性、审计日志、加密擦除、重新嵌入 |
## 从源代码构建
先决条件：**Rust**（参见 `rust-toolchain.toml`）、**Node 20+**、**pnpm**。
```bash
cargo build && cargo test # Rust 核心（14 个 crate）
pnpm install && pnpm -r build && pnpm -r test # TS 工作区（共享 · 代理 · GUI · 服务器）
./scripts/e2e.sh # 跨语言端到端检查
# 全一键开发循环（构建 → 摄取 → 观察 → 服务器 :8787 → GUI :5173）
pnpm dev --repo myorg/myrepo
```
GUI 的 **刷新** 按钮重新运行相同的被动观察器并实时重新嵌入；它仅在 `127.0.0.1` 上提供同源服务。
```
crates/ Rust 核心（模型、解析器、标识、存储、观察器、协调、风险、
代理src、加密、模型、策略、证明、mcp、cli）
packages/ TypeScript（共享、代理、gui、服务器、cli）
schema/ 本地 SQLite 后端的 SQL DDL
docs/ 文档（代理工件模式、安全、模型、开放核心、治理）
```
## 默认隐私和安全
- **默认离线**：无密钥 ⇒ 本地嵌入 + 本地模型（Ollama 可选）；无内容离开机器。远程 LLM/嵌入是显式选择，上下文在出口前被删除。
- **摄取时机密扫描**：记录被扫描并删除（类型占位符，绝非值）**在**任何内容被存储、总结或嵌入之前；`BRAIN0_EXCLUDE` / `BRAIN0_REDACT` 添加您自己的规则。原始提示文本**不会持久化**；仅模型生成的摘要。
- **静止加密**：信封加密有效载荷存储（ChaCha20-Poly1305，KEK 轮换，加密清除）具有限制性文件权限。
- **追加安全审计日志**：图是防篡改的（`brain0 verify`），具有追加安全审计日志。
威胁模型和诚实的局限性：[`docs/security.md`](./docs/security.md)。
## 开源
此存储库中的所有内容都是免费和开源的，位于 [Apache-2.0](./LICENSE) 下，并且完全功能齐全，无需许可证检查、功能标志或残缺的代码路径。
团队/托管功能（PostgreSQL + pgvector 后端实现相同的公共 `brain0_storage::Storage` 特质，签名许可，多租户服务器）位于单独的 **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。
