内容
# 贝克特 — 面向代码库的 AI 上下文与影响引擎
## 概述
贝克特是一个面向开发者的命令行界面（CLI）和 MCP 服务器，它将代码仓库转化为**持久、可查询的知识**，供 AI 编程代理和开发者使用。其目标是为代理提供**正确代码和正确理解**，以完成任务 — 而无需将整个代码仓库加载到上下文窗口中，也无需在每次查询时重新推导所有内容。
**北极星目标：** 一次调用 → 一个上下文包（markdown 格式），包含已验证的代码片段、含义和影响，且在 token 预算内。参见 [ADR-0006](./docs/adr/0006-grounded-knowledge-wiki.md)。
贝克特不像传统的文件集合那样处理代码仓库，而是维护三个协调的层：
1. **确定性核心** — 一个精确的、从代码导出的符号、依赖关系、流程、入口点和变更影响图。这是一种**可靠的事实**：从源代码中测量，而不是猜测。
2. **知识层（代码仓库 Wiki）** — 一个持久的、不断增长的 markdown 页面集合（模块/服务/流程/概念），解释**意图、约定和注意事项**。页面**锚定到真实符号**，并由宿主代理的模型（通过 MCP 采样）懒散地生成 — 绝不从头开始重新导出。
3. **上下文组装** — 在查询时，贝克特返回相关的**Wiki 页面 + 实际代码片段 + 影响集**，打包在 token 预算内。这是“上下文中的代码”层。
确定性核心使 Wiki 值得信赖：贝克特从源代码中导出真正的调用图，**基于符号 ID 确立** Wiki 页面，并**检查**声明与实时图的冲突，以便自动标记过时或错误的关系。
它充当以下组件之间的桥梁：
- 大型代码库
- AI 编程代理（Claude Code、Cursor、Codex 等）
- 导航和重构系统的开发者
**网站：** [becket.dev](https://becket.dev) (Vercel) · **发布：** [GitHub Releases](https://github.com/GabrieleRuggieri/becket/releases)
---
## 今日使用
这些功能**现在**就可以使用。不需要捆绑的 LLM — 可选的文本丰富化使用您的 MCP 主机的模型。
| 命令/工具 | 您得到的结果 |
|---|---|
| `becket build` | 确定性图 + **可靠的 Wiki** → `.becket/*.json` + `.becket/wiki/`（导入感知解析、共变挖掘、真正的增量更新，通过 `raw_refs`） |
| `becket impact <symbol>` | 下游中断的内容（调用图 + 模块） |
| `becket flow <domain>` | 跨服务的端到端执行路径 |
| `becket context <symbol>` | **Markdown 包**：知识页面 + 排名代码片段 + 影响（ `--budget`、 `--auto-budget`、 `--task`） |
| `becket report` | 索引质量指标（`.becket/report/metrics.json`）+ 本地 HTML 仪表盘：token 节省、边缘置信度、Wiki 检查、包完整性 |
| `becket bench --last N` | 可重复的检索基准测试 vs. 最近的 git 历史记录（召回率 + token 成本） |
| `becket wiki sync\|lint\|show` | 重新编译过时页面、CI 检查、查看可靠页面 |
| `becket build --watch` | 增量重建；自动同步过时的 Wiki 结构 |
| `becket workspace build` | 跨代码仓库链接（HTTP/gRPC/队列） |
| MCP `get_context` | 相同的 Markdown 包；`auto_budget: true` 或 `enrich: true` 按需 |
| MCP `get_wiki` | 可靠的 Wiki 页面；`enrich=true` 通过采样填充文本 |
| MCP `get_impact`、`get_flow`、`get_dependencies` | 与 Cursor / Claude Code 相同的查询（`dependencies` 包括上游调用者） |
### 快速入门（3 步）
```bash
# 尝试演示（代码仓库中的迷你商店）
cd demo && npx becket build
# 或索引您自己的项目
cd your-project && npx becket build
# 验证索引质量
becket report
becket bench --last 30
# MCP：npm install -g becket becket-mcp — 参见 website/docs.html#quickstart
```
### Cursor / Claude Code (MCP)
将以下内容添加到您的 MCP 配置（`.cursor/mcp.json` 或 Claude Code 设置）：
```json
{
"mcpServers": {
"becket": {
"command": "becket-mcp",
"env": {
"BECKET_ROOT": "${workspaceFolder}"
}
}
}
}
```
在代码仓库中运行 `becket build` 一次（或在终端中使用 `becket build --watch`）。代理可以在修改代码之前调用 `get_context` / `get_wiki` / `get_impact`。
### Wiki 文本丰富化
- `becket wiki sync` — 从图重新编译**结构**（保留丰富文本）
- MCP `get_wiki` 且 `enrich=true` — 使用主机模型填充意图/注意事项并**持久化**到 `.becket/wiki/`
---
## 旧版 v0.1 接口
影响、流程和 MCP 查询是主要的 v0.1 工作流程。它们仍然完全受支持；v0.2 在顶部添加了 Wiki 层和 Markdown 上下文包。
---
## 贝克特的作用
贝克特是**代码库的本地智能层**。它索引您的代码仓库一次，在 `.becket/` 下保持**持久内存**，并使用已验证的结构、可选的人类可读 Wiki 文本和**实际源代码片段**回答代理准备好的查询 — 打包到您的 token 预算。
### 问题
当 AI 代理（或开发者）处理大型代码仓库时，会出现四个问题：
1. **代码太多** — 您无法将整个树放入上下文窗口。
2. **没有系统视图** — 本地片段不够；调用者、流程和模块很重要。
3. **没有影响感知** — 小更改可能会破坏不确定有人加载的远程代码。
4. **没有持久内存** — 每个会话都会从头开始重新发现相同的架构。
贝克特通过一个本地索引和一个查询接口解决了这四个问题。
### 工作原理
```
您的代码仓库 → becket build → .becket/（图 + Wiki）
↓
becket context | impact | flow | wiki …
↓
代理的 Markdown 包
```
1. **`becket build`** —遍历和解析代码仓库（tree-sitter）。构建符号、导入感知的调用图，置信度分级、流程、入口点、git 历史记录的共变对和可靠的 Wiki 页面。**不需要 LLM**。
2. **持久内存** — JSON 工件 + `.becket/wiki/*.md` 在会话间存活。真正的增量重建（未更改的文件通过缓存的 `raw_refs` 跳过）；事务性写入防止失败的构建损坏索引。
3. **每任务查询** — `context`、`impact`、`flow` 和 MCP 工具返回您现在需要的东西，通过多信号相关性排名 — 而不是整个代码仓库。
### 能力
| 能力 | 您得到的结果 |
|---|---|
| **代码图** | 符号、依赖关系、调用边，置信度分级 (`import_resolved` → `candidate`)，入口点 — 从源代码测量，可重复 |
| **导入感知解析** | 每个语言的导入提取 + 模块路径 → 文件解析（在名称回退之前） |
| **影响分析** | 变更影响的下游调用者和模块（循环安全 BFS） |
| **流程重建** | 跨服务的端到端路径（例如 `payment` → 处理程序 → 客户端 → 队列） |
| **共变挖掘** | 历史上一起更改的文件（来自 `git log`）为上下文排名提供信息 |
| **可靠的 Wiki** | 模块/服务/流程页面锚定到符号 ID；结构来自图 |
| **Wiki 检查** | 过时页面、损坏的声明、孤立链接 — 与实时图的确定性检查；CI 的 `--strict` |
| **上下文组装** | 一个 Markdown 包：Wiki + 多信号排名片段 + 影响，在 `--budget` 和 `--task` 内 |
| **索引质量报告** | `becket report` — token 节省、边缘置信度配置文件、Wiki 健康状况、片段完整性 |
| **检索基准测试** | `becket bench` — 与最近提交的 git 历史记录相比的召回率（co-committed 文件的召回率 + token 成本） |
| **MCP 服务器** | `get_context`、`get_wiki`、`get_impact`、`get_flow`、`get_dependencies` 用于 Cursor / Claude Code |
| **工作区模式** | 跨代码仓库链接（HTTP、gRPC、队列）用于 monorepos 和 polyrepos |
### 典型工作流程
**修复 bug 前** — 代理在失败的符号上调用 `get_context`，并使用 `--task fix`：调用者、相关片段、影响深度 2、Wiki 注意事项。
**重构前** — `becket impact SymbolName`（或 MCP `get_impact`）查看爆炸半径；`wiki lint --strict` 在 CI 中确保文档不会撒谎关于调用关系。
**入职** — `becket flow <domain>` 加上 `context` 且 `--task onboard` 用于流程和概览，且减少片段。
**丰富意图** — MCP `get_wiki` 且 `enrich=true` 使用主机模型填充文本槽（意图和注意事项）；结构保持图编译。
**验证索引** — 在 `becket build` 后，运行 `becket report` 获取本地仪表盘（token 节省、图置信度、Wiki 检查、片段新鲜度）和 `becket bench --last 30` 测量检索召回率对抗自己的 git 历史记录。
### 设计原则
- **本地优先** — 无云，无遥测，无 API 密钥在核心路径中
- **图是可靠的事实** — Wiki 结构和检查声明来自确定性核心
- **代码从不生成** — 片段从磁盘切片；只有可选的 Wiki 文本由模型作者编写
- **代理的一次调用** — 北极星目标：`get_context` → 单个 Markdown 包，而不是手动文件 `@` 混杂
---
## CLI 接口
### 初始化分析
```bash
becket build
```
生成：
```
.becket/
architecture.json
symbols.json
flows.json
dependencies.json # 边包括解析 + 置信度（模式 1.1.0）
entrypoints.json
index.db # SQLite 缓存（raw_refs、co_change、embeddings）
wiki/ # 可靠的知识页面（符号锚定）
index.md
<page>.md
report/ # 在 becket report / bench 之后
metrics.json
bench.json
index.html
```
JSON 工件是**确定性生成**的，无需模型。
---
### 知识 Wiki
```bash
becket wiki sync # 重新编译过时页面（结构；保留丰富文本）
becket wiki lint # 标记过时、矛盾或孤立页面与图
becket wiki show payment
```
`lint` 是区分因素：因为确定性图是可靠的事实，贝克特可以检测到页面声明代码不再具有的关系。使用 `wiki lint --strict` 在 CI 中。
文本丰富化：MCP `get_wiki` 且 `enrich=true`（需要主机模型）。
### 查询变更影响
```bash
becket impact UserService
```
输出：
- 受影响的模块
- 下游依赖
- 相关测试
- 潜在风险区
---
### 了解流程
```bash
becket flow payment
```
输出：
- 端到端执行路径
- 服务交互
- 涉及的外部系统
---
### 生成 AI 就绪上下文
```bash
becket context PaymentService --task fix # 默认预算 6000 用于修复
becket context PaymentService --task refactor # 默认 12000
becket context PaymentService --auto-budget --task fix # 推荐大小
becket context PaymentService --plan --task fix # 仅快速预算估算
becket context PaymentService --json
```
在 token 预算内，一个 Markdown 包（wiki/知识、影响和片段都计入）：
- 相关的**知识页面**（可靠的 Markdown；意图/注意事项，当丰富时）
- **实际代码片段**（调用者/被调用者，从磁盘切片）
- **影响集**和相关测试
如果预算太小，则包中包含带有 `recommended_tokens` 的通知。使用 `--auto-budget` 或提高 `--budget`。
任务模式：`fix`（默认）、`refactor`、`onboard`（添加流程概览，如果可用）。
低置信度的调用图邻居用 `?` 在包中标记。
---
### 验证索引质量
```bash
becket report # metrics.json + HTML 仪表盘
becket report --open # 在浏览器中打开仪表盘
becket bench --last 30 # 召回率 + token 成本 vs. 最近的提交
becket bench --last 30 --json
```
`report` 采样上下文包并比较 token 成本与完整源文件，配置文件置信度层，运行 Wiki 检查，并检查片段是否仍与磁盘匹配。`bench` 使用最近的 git 提交作为可靠事实：对于每个提交，它从受影响的文件中选择一个种子符号，并测量有多少共同提交的文件出现在组装的上下文中。
---
## 与 AI 工具集成
贝克特设计为**代理无关**。
### Claude Code / Claude CLI
代理可以调用：
```bash
becket context <symbol>
becket impact <symbol>
becket flow <domain>
```
在修改代码之前检索精确的上下文。
---
### Cursor IDE
Cursor 可以将贝克特集成作为后台上下文提供者：
- 用架构意识丰富代码建议
- 减少不正确的重构
- 改善多文件编辑
---
### OpenAI Codex / 未来 CLI 代理
任何代理都可以使用贝克特作为工具：
```bash
tools:
- becket.context
- becket.impact
- becket.flow
```
这使得在大型代码库上进行结构化推理成为可能。
### MCP（模型上下文协议）集成
贝克特公开了一个 MCP 服务器：
```
becket-mcp
```
可用工具：
- **get_impact**、**get_flow**、**get_dependencies** — 已发货
- **get_context** — Markdown 包（Wiki + 片段 + 影响）；可选的 MCP 采样丰富化
- **get_wiki** — 可靠的 Wiki 页面；`enrich=true` 用于通过主机模型的文本
这实现了与现代 AI 代理的无缝集成。Wiki 创作/丰富化通过**主机代理的模型通过 MCP 采样**运行 — 贝克特没有捆绑 LLM，也没有持有 API 密钥。
---
## 设计原则
### 1. 确定性优先
核心分析在可能的情况下应该是确定性的。
### 2. AI 增强，非 AI 依赖
AI 增强了解释（Wiki 文本、名称、摘要），但**结构源自代码**，且 Wiki 始终**可验证对抗图**。删除 AI 层，您将失去文本，永远不会失去正确性。
### 3. 本地优先
所有分析都在本地运行，以确保：
- 隐私
- 速度
- 可重复性
### 4. 机器可读输出
所有输出必须是：
- JSON 兼容
- 稳定模式
- 版本控制
---
## 为什么这很重要
软件开发的未来是：
- AI 辅助
- 多代理
- 上下文重
但当前系统缺乏：
- 代码库的持久理解
- 结构化的架构内存
- 可靠的影响推理
贝克特通过成为**代码与智能之间的语义层**来填补这一空白。
---
## 长期愿景
贝克特旨在成为：
> 所有 AI 编程代理的标准上下文层 — 代码库的**已验证、复合内存**。
就像 Git 成为版本控制的标准一样，
贝克特旨在成为：
- 代码理解
- AI 上下文检索（代码 + 知识，而不仅仅是元数据）
- 一个自我验证的知识 Wiki，基于代码
- 架构推理
---
## 成功标准
如果工具成功：
- 开发者每天在提交/PR前使用它
- AI 代理在修改代码前调用它
- 它减少了调试和重构错误
- 它成为标准开发工作流的一部分
---
## 开发
### 要求
- Rust 1.75+ (`rustup`)
### 从源码构建（贡献者）
```bash
git clone https://github.com/GabrieleRuggieri/becket.git
cd becket
cargo build --release
./target/release/becket build
# 或：./scripts/becket-local.sh build
```
### 安装（预编译）
**npm** （从 GitHub Releases 下载原生二进制文件 — macOS、Linux、Windows）：
```bash
npx becket build
# 或：npm install -g becket becket-mcp
```
**GitHub Releases**：从 [Releases](https://github.com/GabrieleRuggieri/becket/releases) 下载您平台的存档，或使用每个版本附带的 shell 安装程序。
参见 [packaging/README.md](./packaging/README.md) 以供维护者剪切新版本。
### MCP 服务器（AI 代理）
```bash
# 从要分析的代码仓库的根目录（在 `becket build` 之后）
export BECKET_ROOT=.
cargo run --bin becket-mcp --release
```
公开工具：`get_context`、`get_impact`、`get_flow`、`get_dependencies`、`get_wiki`.
### 运行测试和 lint
```bash
cargo test --all
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
```
### Git 钩子（rustfmt 预提交）
设置一次（自动格式化提交前）：
```bash
./scripts/setup-git-hooks.sh
```
CI `cargo fmt --check` 作为安全网。
### 文档地图
| 文档 | 目的 |
|---|---|
| [ARCHITECTURE.md](./ARCHITECTURE.md) | 堆栈、数据模型、API 契约（真实来源） |
| [CODEMAP.md](./CODEMAP.md) | 执行流程和箱体图 |
| [PROGRESS.md](./PROGRESS.md) | 开发日志/已完成里程碑 |
| [BACKLOG.md](./BACKLOG.md) | 已开启工作，按优先级 P0-P2 排序 |
| [CONTRIBUTING.md](./CONTRIBUTING.md) | 开发设置、测试和贡献指南 |
| [CHANGELOG.md](./CHANGELOG.md) | 发布历史 |
### 许可
Apache-2.0 — 参见 [LICENSE](./LICENSE).
---
## 结论
贝克特不仅仅是一个开发者工具。
它是**代码库和 AI 推理系统之间的缺失层**。
它将原始代码仓库转化为一个已验证的图，一个基于该图的复合知识 Wiki，以及按需代码包 — 一个人类和 AI 代理都可以一致依赖的查询知识系统，而无需重新阅读整个代码仓库或信任不可验证的 Wiki。
