内容
<p align="center">
<img src="https://raw.githubusercontent.com/TsukumoHQ/trovex/main/growth/assets/brand/readme-hero.png" alt="trovex — 为您的编码代理提供一份规范文档，节省约60%的 tokens." width="100%">
</p>
<!-- mcp-name: io.github.TsukumoHQ/trovex -->
# trovex
**trovex — 为您的编码代理提供一份规范文档，节省约60%的 tokens.**
您的编码代理（Claude Code、Cursor、Windsurf、Zed，任何MCP客户端）每次会话都会重新读取仓库，以确定当前的 `.md` 文件，然后根据猜测进行回答。每次会话、每个代理、每个团队成员都需要支付此费用。
trovex索引您的仓库的markdown文件，并暴露一个MCP工具。您的代理提出问题；trovex返回带有新鲜度标记（规范/过时/重复）的单个当前文档的 `path:line` 指针，并仅提供回答问题的部分，而不是整个文件。代理还可以通过一个共享点写入它们所学的内容，以便每个代理和团队成员都可以读取相同的真实来源，而不是重新推导它。
在文档查找方面节省约 **60%的 tokens**，而上下文质量相同。在本地运行：SQLite中的向量，通过ONNX进行嵌入，无需云或API密钥。
## 您正在安装的内容
30秒的信任检查，由于决定发生在README上，而不是目录列表中：
- **第一方，开源。** 由[tsukumo](https://tsukumo.ch)构建和生产运行，团队在其中。 AGPL-3.0-or-later。
- **本地优先，机器上没有任何内容离开。** SQLite中的向量，通过ONNX进行嵌入。无需云，无需API密钥，无需网络调用来回答查询。
- **写入受限，无shell。** 六个MCP工具：三个只读（`trovex`，`trovex_read`，`trovex_search`）和三个仅修改trovex自己的文档存储（`trovex_write`，`trovex_tag`，`trovex_delete`）。无shell执行，无写入到源文件。
- **约60%是可复制的。** 在真实仓库中测量；`trovex search`在您的仓库上打印节省（[基准测试文章](https://tsukumo.ch/blog/the-token-cost-of-agents-rereading-docs)中的方法）。
## 快速开始
trovex处于公开测试阶段，在PyPI上。无需克隆 — `uv tool install`将`trovex`放入您的PATH中：
```bash
uv tool install trovex # 一次性，无需克隆
trovex index /path/to/your/repo # 索引您的markdown（~1分钟）
trovex search "如何回滚部署？" # 提问 — 打印节省的tokens
trovex serve # 连接到您的代理：MCP在/mcp，仪表盘在/savings
```
没有`uv`？这是一个单行安装：`curl -LsSf https://astral.sh/uv/install.sh | sh`
（或`brew install uv`）。
`search`步骤是快速了解重点的方法：它返回规范文档并打印与读取顶部几个候选项相比节省的tokens。一旦trovex通过MCP连接到您的代理，相同的数字会在`http://localhost:8765/savings`的节省仪表盘上累积。
> 如果您暂时不想安装任何内容？`uvx trovex search "..."`在一次性环境中运行单个命令 — 无需安装。
## 将其连接到您的代理
trovex是一个MCP服务器。在`trovex serve`后，将您的客户端指向`http://localhost:8765/mcp`。每个客户端的设置（Claude Code、Cursor、Windsurf、Cline、Zed、Roo）在
[trovex.dev/for](https://trovex.dev/for/)中。对于Claude Code：
```bash
claude mcp add --transport http trovex http://localhost:8765/mcp
```
## MCP工具
- `trovex(q)` — 将问题路由到正确的磁盘上的 `.md` 并返回带有新鲜度标记的 `path:line` 指针，而不是一大堆文件进行排名。
- `trovex_write(content, kind?, doc_id?, tags?)` / `trovex_read(query | doc_id, section?)` —
trovex内部拥有的文档。代理一次存储一个记录（事件，决定，“实际有效的方法”）；其他代理和第二个开发人员通过内容（可选地仅限一个部分）读取它，而不是重新推导。参见[`REFONTE.md`](REFONTE.md)。
- `trovex_search(query, k?, tags?)` — 跨存储库的段落级检索，带有标签过滤器，用于当您想要顶级匹配块而不是一个规范文档时。
- `trovex_tag(...)` / `trovex_delete(...)` — 标记或软删除存储的文档；删除是可恢复的存档，而不是硬删除。两者都只影响trovex存储库，而不影响您的文件。
人类在渲染的阅读器中通过 `/doc/{id}` 读取trovex拥有的文档。要使代理通过 `trovex_write` 而不是磁盘路由 `.md` 写入，请安装PreToolUse钩子
`deploy/hooks/trovex-md-guard.sh` 并在 `.trovexignore` 中划分例外。
## 它是如何比较的
- vs `CLAUDE.md` / `AGENTS.md`：一个静态文件，会过时并且无法将问题路由到正确的文档，而许多文档保持规范并按查询提供。 [更多](https://trovex.dev/vs/claude-md/)。
- vs `repomix` / files-to-prompt：将整个仓库打包到窗口中，而检索答案。 [更多](https://trovex.dev/vs/repomix/)。
- vs 矢量数据库 / 普通RAG：带有无新鲜度信号的排名候选项块 vs 带有显式标记的单个当前文档。 [更多](https://trovex.dev/vs/vector-db-rag/)。
关于 **60%** 数字背后的推理在
[代理重新读取文档的token成本](https://tsukumo.ch/blog/the-token-cost-of-agents-rereading-docs) 中有详细介绍。
## 技术栈
- Python 3.11 + uv
- FastAPI（MCP HTTP + 服务器渲染的HTML UI）
- fastembed（本地嵌入，ONNX背后）
- sqlite-vec（SQLite中的向量搜索）
- Jinja2 + HTMX（UI，无构建步骤）
## 公开测试
trovex处于公开测试阶段。安装它，在您的仓库上运行它，如果它为您节省了tokens，
[GitHub star](https://github.com/TsukumoHQ/trovex) 帮助其他开发人员找到它。问题和
PR欢迎。
问题，或与其他运行代理的人员比较笔记？加入社区Slack：
[tsukumo.ch/slack](https://tsukumo.ch/slack)。
## 许可证
trovex在 **GNU AGPL-3.0-or-later** 下获得许可（参见 [`LICENSE`](LICENSE)）。您可以
自由地自我托管和修改它；如果您作为网络服务运行修改后的版本，AGPL
要求您共享您的更改。
## 与团队合作？
trovex免费供您自己运行。如果您的团队正在大规模部署编码代理，并希望在
做好这件事的同时获得帮助，或者在不使用AGPL的 copyleft义务的情况下嵌入和托管修改后的trovex，
这就是咨询的用途。
[联系](https://tsukumo.ch/consulting/?utm_source=trovex&utm_medium=oss-suite&utm_campaign=consulting&utm_content=readme)：
tsukumo，trovex背后的团队。
MCP 市场