openvisio-oss

# OpenVisio — 降低 AI 编程代理的 Token 使用量，借助代码图谱 [](LICENSE) [](https://www.npmjs.com/package/openvisio) [](https://www.npmjs.com/package/openvisio) [](https://github.com/syntaxpriest/openvisio-oss) [](https://github.com/syntaxpriest/openvisio-oss/actions/workflows/ci.yml) []() [](https://openvisio.io) **官网： [openvisio.io](https://openvisio.io)** · [npm](https://www.npmjs.com/package/openvisio) · [文档](https://openvisio.io) > **停止为代理读取文件而浪费的 Token 付费。** OpenVisio 是一个 [MCP 服务器](https://modelcontextprotocol.io)，它将任何代码仓库转换为确定的**代码图谱**，并为 **Claude Code、Cursor、Codex、Windsurf、Cline 和 VS Code** 提供排名、Token 预算视图 — 因此代理查询*结构*（符号、导入、调用边、`path:line` 锚点）而不是爬取和重新读取整个文件。相同的答案，只需一小部分上下文。**本地优先，只读，引擎中没有 LLM — 您的代码永远不会离开您的机器。** <p align="center"> <img src="docs/images/viewer.png" alt="OpenVisio 代码图谱查看器 — 大型代码库的 Atlas 视图，文件和符号作为由琥珀色导入和调用边链接的星座" width="100%"> <br> <em>查看器的<strong>Atlas</strong>视图 — 每个文件和符号作为由导入、定义和调用链接的星座（此处：一个 93K 文件仓库）。</em> </p> --- ## 为什么选择 OpenVisio？Token 节省，有测量 AI 编程代理通过缓慢、昂贵的方式探索代码库：grep、打开文件、整个文件读取、跟随导入、在错过时重新读取 — 并在**每次代理循环**时重新处理所有内容。在一个真实的代码仓库中，这意味着在代理编写任何代码之前，数万个 Token 被烧毁，您为每次请求支付这些 Token。OpenVisio 用**一次排名的、`path:line` 锚定图查询**取代爬取，因此代理只读取它实际需要的几行。 | 为此… | 没有图谱的代理 | 使用 OpenVisio | 精简 | |---|---|---|---| | 构建整个代码库的心理模型 | 92.1K Token | 1.5K Token | **~62×** | | 探索足够的内容以开始任务 | ~78K Token / 任务 | ~2.4K Token / 任务 | **~30×** | > **保守预测**在一个包含 65 个文件的示例仓库上（[`bench/REPORT.frontend.md`](bench/REPORT.frontend.md））。它*低估*了真正的胜利：它忽略了重新读取、每次循环的工具定义税和 Codex 的 ~3-5× 代理循环重新处理。Token 节省集中在大型、结构化的代码仓库中。**在您的代码仓库上测量它：** `npm run bench`。 更少的 Token 意味着**更低的 API 账单、更长的有效上下文窗口、更少的“上下文已满”压缩和更快的响应** — 而不牺牲正确性，因为每个图结果都带有 `path:line` 锚点，代理可以回退到进行实际读取。 --- ## 它是什么 一个确定的代码图谱，两个界面： - **对于您的代理** — 一个 [MCP](https://modelcontextprotocol.io) 服务器（npm 上的 `openvisio`），为 Claude Code / Cursor / Codex / Windsurf 提供排名、精简、Token 预算视图的代码仓库，因此它们查询*结构*而不是爬取文件。 - **对于您** — 一个本地查看器，绘制相同的图谱作为 **Atlas** （一个可导航的结构地图）和 **City** （一个 3D 树形图，大小和权重编码复杂性），因此您可以一目了然地看到不熟悉的代码仓库的形状。 OpenVisio 使用 **tree-sitter** 将任何代码仓库解析为符号 + 导入图谱，并使用 **PageRank** 对其进行排名。该图谱是**确定的、无 LLM 的**：相同的代码仓库字节 → 相同的图谱，相同的 ID，每次运行。无需网络，无需嵌入，无需向量数据库。 --- ## 快速开始（60 秒） ```bash npm install -g openvisio cd your-project openvisio ``` `openvisio` 编写项目范围的 MCP 配置（用于 Claude Code 的 `.mcp.json`，以及存在时 `.cursor/mcp.json` / `.vscode/mcp.json`）并运行第一个索引。在文件夹中打开您的代理，批准 `openvisio` 服务器，它会查询代码图谱而不是盲目读取文件。 完整的 CLI + 工具参考：[`mcp/README.md`](mcp/README.md)。 ### 与您的代理配合使用 OpenVisio 使用 **模型上下文协议** （**Anthropic** 的开放标准），因此它可以与任何支持 MCP 的编码代理一起使用： | 代理 / 编辑器 | 制造商 | |---|---| | **Claude Code** | Anthropic | | **Cursor** | Anysphere | | **Codex** | OpenAI | | **Windsurf** | Codeium | | **GitHub Copilot** （代理模式 / VS Code MCP）| GitHub / Microsoft | | **Cline** | 开源 | | **Continue** | Continue.dev | | **Zed** | Zed Industries | | **JetBrains** IDE（通过 MCP）| JetBrains | | 任何其他 MCP 客户端 | — | > 商标归其各自所有者所有。OpenVisio 是一个独立的、MIT 许可的工具，与这些公司无关，也未得到它们的认可 — 它只是实现了它们支持的开放模型上下文协议。 ### 为什么 Token 成本很重要，无论您运行什么模型 无论您的代理调用 **Anthropic Claude** （Opus、Sonnet、Haiku）、**OpenAI** （GPT、Codex）、**Google Gemini** 、**Meta Llama** 、**Mistral** 、**DeepSeek** 还是本地模型，您都为上下文的每个输入 Token 付费（以美元或延迟计算）。OpenVisio 减少了最大的、最浪费的账单部分：代理为了找到相关代码而进行的重复文件爬取。 ### 代理获得的内容 | 工具 | 它做什么 | |------|--------------| | `resolve_context` | 任务排名的骨架 + 最相关的文件的邻域（首先调用）| | `get_repo_skeleton` | 整个排名的代码库地图 | | `find_symbol` | 定位函数/类/类型 → 签名 + `path:line` | | `get_neighborhood` | 文件/符号周围的本地导入子图 | | `get_dependents` | 谁导入这个（影响分析）| | `get_hotspots` | 变更 × 中心性 重构/风险候选人 | 每行都带有 `path:line` 锚点，因此代理只读取它需要的部分。有关 Token 节省方法和 A/B 协议的详细信息，请参见 [`bench/`](bench/)。 --- ## 运行查看器 — 可视化任何代码库 一旦 `openvisio` 安装完成，`view` 索引代码库并在浏览器中打开捆绑的 **Atlas** 和 **City** 视图 — 零安装，从 `127.0.0.1` 提供服务： ```bash openvisio view # 索引当前代码库并打开查看器 openvisio view ../other # … 或任何其他本地代码库 ``` 查看器包含在 `openvisio-viewer` 包中：相同的 React/Three.js **Atlas** + **City** **代码库可视化**，作为一个自包含的静态包。它默认打开 **Atlas**；在右上角使用视图切换到 3D **City**。点击 **Index** 以指向任何本地代码库 — 在内置的文件系统选择器中浏览（标记 git 代码库）或输入路径 — 以及分阶段的进度加载器在确定性引擎索引时运行。点击任何节点以聚焦它。没有任何内容离开您的机器。 **观察您的代理思考。** `view` 默认使用聚光灯端口（7077），因此它兼作实时高亮中心：保持它运行，将您的代理指向代码库，运行 `openvisio mcp . --spotlight`，以及每个工具调用聚焦它正在查看的文件 — 实时。 从克隆中，首先构建工作区（`npm run build` 构建引擎、查看器和 CLI），然后 `node mcp/dist/cli.js view .`。 --- ## 共享图谱（传输） `view` 将所有内容保留在 `127.0.0.1` 上。当您想要一个**可共享的链接** — 相同的 Atlas/City 地图加上 AI **叙述者** — 而无需上传您的源代码时，`transport` 会进行分割：它在**本地**索引代码库（繁重的 tree-sitter 扫描保留在您的机器上，私有且快速），并将**仅计算的图谱 JSON** 发送到渲染它的 Web 服务器。 ```bash openvisio transport # 索引当前代码库，上传图谱，打开链接 openvisio transport ../other # … 或任何其他本地代码库 openvisio transport --no-open # 仅打印 URL，不打开浏览器 openvisio transport --server=https://your-host # 发送到您自己的部署 ``` 发生了什么： 1. 本地索引 → 构建确定的图谱。 2. 将缓存副本写入 `<repo>/.openvisio/graph.json` （自动添加到 `.gitignore`）。 3. `POST` 仅该图谱 JSON 到 `<server>/api/import`。 4. 在 `<server>/?g=<id>` 上打开渲染的图谱 + 叙述者。 您的源代码永远不会离开您的机器 — 只有符号/导入图谱被发送。目标默认为 `https://openvisio.io`；使用 `--server` 或全局使用 `OPENVISIO_SERVER` 环境变量覆盖它。 --- ## 常见问题 **OpenVisio 如何减少 Claude Code / Cursor / Codex 中的 Token 使用量？** OpenVisio 不让代理 grep 和读取整个文件（并在每次循环中重新读取它们），而是从预先计算的代码图谱中回答探索查询：排名骨架、相关邻域和 `path:line` 锚点。代理拉取几百个 Token 的结构，而不是数万个原始源代码 — 通常 **~30× 更少的探索 Token**，以及 **~62×** 来初始化整个代码库模型（预测；参见 [bench](bench/)）。 **我的代码会被上传到任何地方吗？** 不。该引擎是**本地优先且只读**的 — 索引和解析发生在您的机器上，MCP 服务器从不进行网络调用。可选的 `transport` 命令仅发送*计算的图谱 JSON*（符号 + 边，没有源代码）到您选择的查看器，甚至默认情况下关闭正常使用。 **这与嵌入 / RAG / 向量搜索我的代码有什么不同？** 没有嵌入，没有向量数据库，索引器中没有 LLM。OpenVisio 是一个**确定的静态分析**图谱（tree-sitter 解析 + 导入解析 + PageRank）：相同的字节 → 相同的图谱，每次运行。它返回确切的 `path:line` 锚点，而不是模糊的最近邻块 — 因此没有任何内容需要幻觉，也无需在代码更改时重新嵌入。 **支持哪些语言？** 通过 tree-sitter 支持 40+ 种语言 — TypeScript、JavaScript、Python、Go、Rust、Java、C/C++、C#、Kotlin、Ruby、PHP、Swift 等（完整表格如下）。其他每个文件仍作为图节点，因此代码库中没有任何内容不可见。 **它适用于大型 monorepos 吗？** 是的 — 那里最能体现其价值。Token 节省随着代码库大小而增长，查看器已渲染 90K+ 文件图谱。小型/绿地代码库的收益较小（已探索集已经是整个代码库）。 **它是免费和开源的吗？** 是的 — **MIT 许可**。`openvisio` 和 `openvisio-viewer` 在 npm 上。 --- ## 语言 OpenVisio 将这些解析为符号和导入/调用边（tree-sitter 语法）。任何其他文本文件仍被扫描为图节点 — 模板（Twig、Blade）、Markdown 和 EDA/硬件文件（KiCad、Gerber）获取语言标签，没有解析的符号，因此代码库中没有任何内容不可见。 | 语言 | 扩展 | | ------------------ | ----------------------------------- | | TypeScript | `.ts`, `.mts`, `.cts` | | TSX | `.tsx` | | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | | Python | `.py`, `.pyi` | | Go | `.go` | | Rust | `.rs` | | Java | `.java` | | C | `.c`, `.h` | | C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh`| | C# | `.cs` | | Kotlin | `.kt`, `.kts` | | Ruby | `.rb` | | PHP | `.php` | | Swift | `.swift` （默认禁用） | | Scala | `.scala` | | Dart | `.dart` | | Zig | `.zig` | | Lua | `.lua` | | R | `.r`, `.R` | | Elixir | `.ex`, `.exs` | | Elm | `.elm` | | OCaml | `.ml`, `.mli` | | ReScript | `.res` | | Solidity | `.sol` | | TLA+ | `.tla` | | Objective-C | `.m`, `.mm` | | Bash | `.sh`, `.bash` | | Vue | `.vue` | | HTML | `.html`, `.htm` | | CSS | `.css` | | JSON | `.json` | | YAML | `.yaml`, `.yml` | | TOML | `.toml` | | 嵌入式模板 | `.erb`, `.ejs` | | SystemRDL | `.rdl` | | QL | `.ql` | | Emacs Lisp | `.el` | > Swift 的语法足够庞大，可能会在某些机器上使 V8 的 WASM 编译器崩溃，因此默认情况下它是关闭的 — 使用 `OPENVISIO_ENABLE_GRAMMARS=swift` 启用它。 --- ## 代码库布局 | 路径 | 它是什么 | |------|------------| | [`core/`](core/) | `@openvisio/core` — 确定的代码图引擎（tree-sitter 解析，导入解析，PageRank，Token 预算骨架）。 | | [`mcp/`](mcp/) | `openvisio` — 已发布的 MCP 服务器 + CLI。捆绑 `core` 到单个自包含二进制文件。 | | [`viewer/`](viewer/) | `openvisio-viewer` — 捆绑的 Atlas + City 应用程序，由 `openvisio view` 提供服务（React + Three.js，构建到静态包）。 | | [`ui/`](ui/) | 完整的 Next.js Web 应用程序（Atlas + City + AI 叙述者）。 | | [`bench/`](bench/) | Token 节省估计器 + A/B 测量协议。 | | [`docs/`](docs/) | 引擎、图谱和 MCP 集成说明。 | --- ## 开发 需要 **Node 20+**。 ```bash npm install # 安装核心 + mcp 工作区 npm run build # 构建 @openvisio/core，然后捆绑 openvisio CLI npm run typecheck npm run smoke # 端到端 CLI 烟雾测试 ``` 查看器（`ui/`）独立安装 — 请参见 [运行查看器](#运行查看器--可视化任何代码库)。 欢迎贡献 — 请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 --- ## 关键词 MCP 服务器 · 模型上下文协议 · Anthropic Claude · Claude Code · Cursor （Anysphere）· OpenAI Codex · GPT · Google Gemini · GitHub Copilot · Microsoft VS Code · Windsurf · Codeium · Cline · Continue · Zed · JetBrains · Meta Llama · Mistral · DeepSeek · 减少 Token 使用量 · 节省 LLM Token · 降低 API 成本 · Token 高效上下文 · 上下文工程 · 代码图 · 代码知识图 · 代码库可视化 · 3D 代码地图 · 依赖图 · 调用图 · 导入图 · tree-sitter · 静态分析 · AI 编程代理 · AI 配对程序员 · 本地优先 · 只读 · 隐私优先的代码工具。 --- ## 许可证 [MIT](LICENSE) © OpenVisio 贡献者