内容
<div align="center">
# reflens
**为您的 AI 编程代理提供任何引用仓库的完整、无损上下文 — 并让它能够推理一个远大于其上下文窗口的代码库。**
指向一个本地文件夹、GitHub URL 或 [Repomix](https://github.com/yamadashy/repomix) 转储。reflens 会对其进行索引，并为 OpenCode / Claude Code（或任何 MCP 主机）提供工具，由代理自行调用。
[](LICENSE)
[](pyproject.toml)
[](tests/)
[](https://modelcontextprotocol.io)
[](pyproject.toml)
</div>
---
## 问题
您希望您的编程代理 **从一个旗舰仓库中学习，并将其模式应用于您的项目**。但是该仓库有 100k–1M+ 个标记 — 它无法适应上下文窗口。今天，您要么：
- 粘贴片段并希望它们是正确的，
- 将其克隆到您的工作空间中，并让代理在每次会话中盲目地 `grep` 它（慢、耗费标记、没有方向），
- 使用 Repomix 转储并观察它溢出窗口。
所有这些都会静默地丢失上下文。**静默截断是一个错误** — 代理自信地推理它从未实际看到的代码。
## 方法：两个层级（诚实的部分）
您 **无法将 25M 标记的仓库无损地拟合到 200K 窗口中** — 这是物理学，而不是工程。任何声称可以做到这一点的工具都在背后截断。reflens 拒绝这样做，并为您提供两个层级和一种方法来 *证明* 没有任何内容丢失：
| 层级 | 它是什么 | 损失 |
|---|---|---|
| **1 — 智能摘要** | 有预算的上下文概述：架构（模块 + 最依赖的文件）、入口点、挖掘的约定和决策，以及 **完整的公共符号表面**（每个签名 + 文档字符串 + 行锚点） | 在 *正文* 上有损失，**在结构和含义上是完整的** |
| **2 — 无损存储** | 每个文件的每个字节，内容寻址（gzip + SHA-256） | **零** — `reflens verify` 重建每个文件并检查 SHA-256 |
代理 **从层级 1 推理**，并在需要详细细节时 **扩展到层级 2**（确切的源代码）。检索是安全网，而不是主要机制。当摘要达到预算时，它会打印确切的工具调用以访问其余部分 — 因此没有任何内容变得无法访问。
→ 完整的设计在 [ARCHITECTURE.md](ARCHITECTURE.md) 中。
## 快速入门（60 秒）
```bash
# 1. 安装（隔离；推荐 pipx）
pipx install "git+https://github.com/cybertronayush/reflens"
# 2. 将其连接到您的代理（编辑 OpenCode + Claude Code 配置，添加使用指南）
reflens install both
# 3. 填充库 — 任意本地目录、GitHub URL 或 repomix .md
reflens add https://github.com/tiangolo/fastapi --name fastapi
reflens add /path/to/your/reference-repo --name myref
reflens add ./repomix-output.md --name dump
# 4. 证明没有丢失任何内容（目录摄取是字节精确的）
reflens verify myref
# 5. 重启 OpenCode / Claude Code，然后直接询问：
# "使用 reflens 学习 fastapi 的依赖注入模式并将其应用于我的应用程序。"
```
就是这样。代理自动调用工具 — 无需斜杠命令，无需每个仓库设置。
## 代理如何使用它
安装后，**每个项目中的每个模型** 都可以获得 `reflens_*` 工具（全局 MCP 服务器）以及全局 `AGENTS.md` / `CLAUDE.md` 中的使用说明。典型的代理流程：
```
reflens_modules(repo) → 模块映射（目录）
→ reflens_map(repo) → 架构简介（中心、约定、决策）
→ reflens_map(repo, path_glob) → 缩放到模块的签名细节
→ reflens_search(repo, query) → 查找相关代码（混合词法 + 语义）
→ reflens_read(repo, target) → 文件或符号的字节精确源
→ reflens_neighbors / _history → 依赖关系 / git 历史
```
您无需为代理编写命令。对于给定任务的 100% 可靠性，只需指定仓库（*“从 `fastapi` 仓库中学习...”*）。
## MCP 工具
| 工具 | 目的 |
|---|---|
| `reflens_list` | 已索引的引用仓库有哪些 |
| `reflens_modules(repo)` | 紧凑的目录（模块 + 内部依赖权重） |
| `reflens_map(repo, level?, path_glob?, budget_tokens?)` | 层级 1 摘要：架构简介（默认，~4K 标记）→ 按模块大纲（`path_glob` + `level=2`） |
| `reflens_search(repo, query, k?, mode?)` | 混合词法（FTS5）+ 语义搜索 → 排名 `file:line` 命中 |
| `reflens_read(repo, target, start?, end?)` | **字节精确** 源文件路径或符号名称 |
| `reflens_neighbors(repo, target, limit?)` | 依赖关系扩展（导入 / 被导入 / 定义） |
| `reflens_history(repo, target?, limit?)` | git 历史（整个仓库或每个文件） |
| `reflens_verify(repo)` | 证明无损 + 完整性 + 提取覆盖率 |
## CLI 参考
```bash
reflens add <source> --name <n> [--semantic] [--max-file-bytes N] [--include-binary]
reflens list
reflens modules <name> # 目录
reflens map <name> [--level 0|1|2] [--glob 'src/**'] [--budget N]
reflens search <name> "<query>" [-k N] [--mode auto|lexical|semantic|hybrid]
reflens read <name> <path|symbol> [--start N --end N]
reflens neighbors <name> <path|symbol>
reflens history <name> [path]
reflens verify <name> # SHA-256 往返 + 完整性 + 覆盖率
reflens enrich <name> [--model ...] # 可选的 LLM 每个模块摘要
reflens remove <name> -y
reflens install [opencode|claude|both] # 连接 MCP 服务器 + 代理指南
reflens serve # MCP stdio 服务器（主机启动此服务）
```
## 提取的内容
- **Python** → 精确，通过标准库 `ast`（类、方法、函数、常量、模块文档字符串、导入）。
- **TypeScript / JavaScript / Go / Rust / Java / Kotlin / C / C++ / C# / Ruby / PHP / Swift / Scala / Shell** → 签名大纲，通过调优的正则表达式提取器（可选 `tree-sitter`，使用 `pip install 'reflens[code]'`）。
- **Markdown** → 标题大纲（文档/规格/ADR 变得可导航）。
- **其他所有内容** → 无损存储 + 全文可搜索。
## 无损性 — 和证明
```bash
$ reflens verify myref
{ "ok": true,
"files": 1750, "verified": 1750, "failed": [],
"completeness": { "declared_files": 1750, "indexed_files": 1750, "drift_detected": false },
"extraction": { "code_files": 1287, "with_symbols": 1235, "coverage_pct": 96.0 } }
```
每个存储的文件都是内容寻址的，并在读取时重新哈希；`verify` 重建所有文件并比较 SHA-256。**目录/git 摄取与源字节相同。** Repomix `--compress` 转储在*相对于转储*时是无损的（它们的正文已经被剥离）— reflens 检测并警告这一点；为真正的源保真度摄取目录。
## 语义搜索（可选）
词法 FTS5 是即时默认的，适用于代码（符号名称、错误字符串）。对于概念查询（“他们如何处理重试？”），构建嵌入：
```bash
pipx install "reflens[semantic] @ git+https://github.com/cybertronayush/reflens"
reflens add /path/to/repo --name myref --semantic
```
嵌入使用 `fastembed`（ONNX，无 torch）并索引 **符号表面**（签名 + 文档字符串），而不是原始代码正文 — 因此像“检测内容类型并选择压缩器”这样的概念查询会返回实际的函数，而不是文档页面。它是可选的（一个大型仓库的一次性 ~4 分钟构建）；向量矩阵在进程中缓存，因此重复查询为 ~3 毫秒。词法 FTS 仍然涵盖完整的文件内容，无损检索不变。
## 比较
| | reflens | 克隆 + 代理 `grep` | Repomix / gitingest | 编辑器代码库索引 |
|---|---|---|---|---|
| 外部引用仓库作为持久库 | ✅ | ✗ （在您的树中） | ✗ （一个文件） | ✗ （您的仓库） |
| 架构优先导向 | ✅ | ✗ | ✗ | 部分 |
| 大于窗口的处理 | ✅ 可导航 | ✗ 溢出 / 重新探索 | ✗ 溢出 | ✅ |
| 无损 + 可证明 | ✅ `verify` | n/a | 部分 | n/a |
| 跨主机安装（MCP） | ✅ | n/a | n/a | 每个编辑器 |
reflens 适用于 **“我希望我的代理从我不想在工作空间中杂乱的 N 个旗舰仓库中学习。”** 对于您正在积极编辑的单个仓库，编辑器的内置工具就足够了。
## 诚实的限制
- **它是可导航的，而不是全知的。** 代理必须提出好的查询；架构优先设计 + AGENTS.md 指南引导它，但懒惰的代理仍然会获得浅层上下文。为可靠性命名仓库。
- **语义摄取很慢** （CPU 嵌入）。仅词法是即时的，默认情况下也是如此。
- **`reflens_history` 需要一个活动的 git 源目录** — 对于 URL 克隆或 repomix 仓库不可用（摘要仍然显示最近的提交主题）。
- **尚未针对“直接克隆”基准进行基准测试。** 设计是合理的；衡量任务成功率的差异是未来的工作。
## 安装和设置
reflens 具有 **零运行时依赖** — 它仅在标准库上运行（`sqlite3` 带有 FTS5、`ast` 和一个手工制作的 MCP stdio 服务器）。**核心** 在 **Python 3.10+** 上运行。可选的额外功能（`semantic`、`code`）会拉取 `fastembed`/`tree-sitter`，它们的轮子可能落后于最新的 Python，因此对于这些使用 **Python 3.12** （推荐）。
选择一个安装路径，然后执行相同的三个安装后步骤。
### 路径 A — pipx（隔离，最简单）
```bash
pipx install "reflens[semantic] @ git+https://github.com/cybertronayush/reflens"
# 核心：pipx install "git+https://github.com/cybertronayush/reflens"
```
### 路径 B — 从源代码（这就是参考设置运行的方式）
```bash
git clone https://github.com/cybertronayush/reflens && cd reflens
python3.12 -m venv .venv
.venv/bin/pip install -e ".[semantic,code,tokens]"
# 使 `reflens` 命令在全局范围内可用（PATH 必须包含 ~/.local/bin）
mkdir -p ~/.local/bin
ln -sf "$PWD/.venv/bin/reflens" ~/.local/bin/reflens
```
### 然后（任意路径）— 连接，重启，填充库
```bash
reflens install both # 在 OpenCode + Claude Code 中注册 MCP 服务器
# 并在全局 AGENTS.md / CLAUDE.md 中写入使用块
# → 重启 OpenCode / Claude Code 以启动服务器
reflens add <dir|git-url|repomix.md> --name myref # 填充库（每个仓库重复）
reflens list # 确认
```
`reflens install` 将每个主机连接到通过安装了 reflens 的解释器启动服务器，例如：
```json
// ~/.config/opencode/opencode.json → mcp.reflens
{ "type": "local",
"command": ["/abs/path/.venv/bin/python", "-m", "reflens", "serve"],
"enabled": true }
// ~/.claude.json → mcpServers.reflens （命令/参数形式，相同的解释器）
```
本地状态存储在 `~/.reflens` 中（可以覆盖为 `REFLENS_HOME`）。没有任何内容离开您的机器。要更新 reflens 本身，请执行 `git pull`（源代码）或重新运行 pipx 安装，然后重启您的代理。
## 贡献
```bash
git clone https://github.com/cybertronayush/reflens && cd reflens
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q
```
参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [ARCHITECTURE.md](ARCHITECTURE.md)。
## 许可证
[Apache-2.0](LICENSE)。
