VinvAI

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://images.vinv.ai/vinv-banner-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://images.vinv.ai/vinv-banner-light.svg"> <img src="https://images.vinv.ai/vinv-banner-dark.svg" alt="Vinv — 给编码人员和他们的编码代理以眼睛。你的代理说它完成了。Vinv 说：‘请证明。’" width="720"> </picture> <br><br> **Vinv 记录你的 Python 后端实际运行情况，并检查你的编码代理的“完成”情况——回放启动、实时端口、验收测试，代理从未见过。** [**vinv.ai**](https://vinv.ai) · **免费 & 开源** · Elastic License 2.0 · Python 优先 · TS & Go 接下来 **无需账户。无需 API 密钥。无需遥测。所有操作都在你的机器上运行。** </div> --- 你的代理从未观察过你的代码运行情况——它编辑了错误的处理器，构造了错误的返回值，然后自我评分：“完成——所有测试通过”，而服务器甚至无法启动。 Vinv 记录运行情况，将每个请求与实际处理它的代码行绑定，并将证据交给你的代理——当代理声称修复时，**Vinv 独立检查**：回放启动、实时端口、验收测试，代理从未见过。单击即可恢复该过程影响的所有内容——包括未跟踪的文件。 `// 循环，真实情况——安装、发现、跟踪、破坏、修复、验证——在这个仓库中` <div align="center"> <img src="https://images.vinv.ai/vinv-journey.gif" alt="Vinv 的实际流程，从 vinv 在其自己的仓库中运行中捕获：单命令安装、Auto-Pilot 发现和启动所有服务、4,000 符号的代码图、实时跟踪、捕获的 BrokenPipeError 并自动分派给代理、验证的修复、所有服务正常" width="720"> </div> _{在 <b>其自己的仓库</b> 中捕获的 Vinv 运行的八个真实画面：① <code>./install.sh</code> — 单个命令，所有内容从源代码构建 · ② Auto-Pilot 发现所有 4 个服务（HTTP 边车、开发服务器、两个 stdio MCP 服务器）并独立设置 · ③ 代码图——4,036 个符号，运行时实时叠加 · ④ 具有每个端点健康报告的实时跟踪流量 · ⑤ 通过 MCP 将语义搜索和故障排名的疑似结果提供给你的代理，真实往返 · ⑥ 检测到真正的生产错误（<code>BrokenPipeError</code> 在实时运行中）并自动分派——“修复已发送，代理正在工作” · ⑦ 输入/输出探针根据黄金基线重新验证修复 · ⑧ 所有服务正常，无需点击。运行时跟踪优先支持 Python，因此跟踪/火焰图帧显示 Python 服务；JS 服务获得发现、验证启动和 stdio/端口探针。} ## `// VINV 的功能` - **监控你的代码运行**——零编辑的 Python 跟踪器记录代码调用的实际发生情况：时间、内存、参数、返回值、错误和触发每个调用的请求。 - **映射你的代码库**——持久化语义索引 + 交互式代码图，使用 **本地嵌入模型** 构建（CodeRankEmbed，MIT，1.37 亿参数——下载一次，在你的 GPU/CPU 上运行），并在保存时增量更新。 - **提供证据**——Vinv 引用每个声明背后的精确符号，并标记代码更改时过时的运行时事实。 - **闭环**——将问题交给自己的编码代理；Vinv 组成证据包，分派它，并 **独立验证结果**。 - **与你已有的代理配合使用**——Claude Code、Codex CLI、Cursor（CLI 和聊天）、Gemini CLI、Copilot Chat、Windsurf Cascade——通过 MCP 和无头分派。**你的代理也是 Vinv 的唯一 LLM**：每个分析步骤都通过你已付费的编码代理 CLI 路由。无需提供商密钥，无需模型选择。 ## `// 安装` 所有内容都从这个仓库运行——无需市场，无需下载，无需账户： ```bash git clone https://github.com/VinvAI/VinvAI ~/.vinv/engines cd ~/.vinv/engines && ./install.sh ``` `install.sh` 构建 Python 引擎（[uv](https://docs.astral.sh/uv/)），Rust 索引（[rustup](https://rustup.rs)），打包编辑器扩展（node），并将其安装到找到的每个编辑器 CLI 中（VS Code，Cursor，Windsurf，VSCodium，Trae）。然后 **打开你的仓库**——Auto-Pilot 接管后续工作，无需点击：嵌入模型下载（约 500 MB 一次）并自动调整到你的硬件，索引构建，每个服务被发现，设置，通过你的编码代理启动，在跟踪下验证，并验证服务。运行过程中发现的问题被分派给你的代理并自动重新验证。 > **诚实的范围：** Python 后端优先——其他堆栈获取索引、图和 QnA，但没有运行时证据（TS 和 Go 接下来）· v0.0.x · 与六个代理通过 MCP 和无头分派合作 · Vinv **不** 进行成本计量、生成的代码安全扫描或生产部署。 ## `// 在自身上验证——每次声明都被衡量` Vinv 的发布门槛是 Vinv 自己：上述循环在该仓库上运行，这些数字来自该运行—— - **零点击 Auto-Pilot**——通过你的代理发现 → 设置每个服务 → 在跟踪下启动 → 构建洞察力 → 探针 → 修复 → 重新验证，直到绿色或预算。所有 4 个仓库服务（一个 HTTP 边车，一个开发服务器，两个 stdio MCP 服务器）都在无需干预的情况下启动；识别并跳过运行到完成的 CLI，不会陷入重试循环。 - **衡量，而不是假设**——嵌入器对你的实际硬件进行基准测试一次，并持久化获胜者（`~/.vinv/embedder_tuned.json`）。在 M 系列 Mac 上，判决结果是 CPU 为 15.3 texts/s，而 GPU 为 0.2——70 倍的陷阱，旧的“优先使用 GPU”默认值直接踩入。 - **通过证明实现故障安全**——我们在运行中杀死了索引器（在第 448 行恢复），杀死了构建过程中的嵌入器（索引器继续运行），并使用 SIGKILL 杀死了跟踪的服务（监督程序在 0 秒内退出，跟踪完好）。 - **发现没人提交的问题**——在其自己的跟踪上运行自己的分析师，提出了五个未提交的问题，包括 83% 的重复计算（现在缓存）和一个 80% 噪声 LLM 裁决队列（现在剔除）。 - **优化而不退化**——每个端点都有黄金输入/输出基线；一个“更快”的更改，如果删除了响应字段，则被标记为 **退化**。检索配置更改仅在离策略评估显示真正获胜时进行（双重稳健，引导 CI，5% 金丝雀，自动回滚）。 - **命名行的搜索**——混合本地检索：文件命中@10 0.90，符号 MRR 0.51，81ms 中位数——每个答案都是具有其 `def` 正文和行号的真实符号，与实际运行的代码连接。 ## `// 上下文图` 四个制品，一个连接。Vinv 索引 **代码**（每个符号和调用边），并从你的实际运行中生成—— **跟踪**（每个调用一个跨度），**日志**（来自同一跟踪的带时间戳的调用事件），和 **指标**（每个符号的延迟和内存），然后将所有四个绑定到处理每个请求的 *确切函数*。制品是商品；**连接不是**。一个图，提供给你的代理，而不是四个工具，它必须在之间猜测。 ## `// 工作原理` 1. **跟踪**——在捆绑的跟踪器下运行你的 Python 服务：无需 SDK，无需代码更改，无需仪表板。调用记录真实值（汇总和编辑 - 参见 [数据和隐私](#-数据--隐私)）。 2. **索引**——每个函数和类都嵌入本地并排名到语义索引中，带有调用/继承图；保存时增量更新保持最新。嵌入来自本地边车（`vinv-embedder`），它根据设备自动调整批次大小（CUDA → Apple Silicon → CPU）并在崩溃后干净地恢复。 3. **服务**——两个 MCP 服务器将上下文图提供给你的代理：语义代码搜索、故障定位排名、观察值、调用切片、覆盖率、影响范围。 4. **验证**——在分派修复后，Vinv 重放记录的启动命令，在新的进程中运行，要求端口实际服务，并运行验收测试，这些测试在修复前由代理生成但从未见过。失败反馈到下一个尝试；不确定的证据升级到你的判断卡。 5. **学习**——每个决策和结果都被概率记录；检索和上下文包合成仅在离策略评估显示真正获胜时更新（本地，从未上传）。 ## `// 仓库布局` | 目录 | 内容 | |---|---| | [`extension/`](extension/) | VS Code/Cursor/Windsurf 扩展（TypeScript）——UI，MCP 服务器，循环 | | [`index/`](index/) | Rust 语义代码索引——tree-sitter 解析，本地嵌入，混合 BM25+密集搜索，代码图 | | [`embedder/`](embedder/) | 本地嵌入边车 - CodeRankEmbed 通过 sentence-transformers，设备感知批处理，故障安全 | | [`tracelens/`](tracelens/) | 零编辑 Python 跟踪器 + 离线分析器 | | [`identification/`](identification/) | 确定性连接：入口点，调用树，跟踪↔源叠加 | | [`handbook/`](handbook/) | 仓库发现 - 通过你的工具链编写纯文本手册（`.vinv/vinv.md`） | | [`bringup/`](bringup/) | 服务清单 + 验证的启动命令，在跟踪器下包装 | | [`goal/`](goal/) | 闭环环节的目标创作 | | [`core/`](core/)，[`contracts/`](contracts/) | 共享代理运行时和类型事件合约 | | [`tests/e2e/`](tests/e2e/) | 植入 bug 的黄金 e2e：植入真实 bug，跟踪它，断言证据命名确切行 | Python 引擎是一个单一的 [uv](https://docs.astral.sh/uv/) 工作区 - 在仓库根目录运行 `uv sync` 设置所有内容。 ## `// MCP 工具参考` **`vinv-index`** — 代码库和会话： | 工具 | 返回 | 何时询问 | |---|---|---| | `vinv_query` | 带有路径和决策 ID 的排名符号 | 任何按含义的代码搜索 - 在 grep 之前 | | `vinv_feedback` | 确认 | 在根据结果采取行动后一次（奖励 -1..1）- 训练检索 | | `vinv_session` | `trajectory` · `status` · `issues` · `hotspots` · `memory_trends` · `cache_candidates`; 操作 `fix` · `run_sweep` · `set_goal` · `set_budget` | 读取 Vinv 的实时状态 - 或从聊天中排队修复/扫描 | **`vinv-runtime`** — 捕获的运行（只读，带有出处戳记）： | 工具 | 返回 | 何时询问 | |---|---|---| | `rank_suspects` | 按故障定位分数排名的符号，附带实际错误消息 | **首先**，在任何故障时 - 在阅读源代码之前 | | `values_of` | 观察到的参数/返回值类型、空值率、范围、顶部值 | “这个函数实际上接收到什么？” | | `slice` | 从请求根到符号的观察到的调用者链，每个帧的值 | “这个坏值是如何传入的？” | | `coverage_of` | 运行情况、运行次数、确定性/错误、时间 | “我的更改是否实际执行？” | | `callers_of` / `blast_radius` / `why_did_this_run` | 观察到的调用者 · 传递影响 · 入口点路径 | “谁调用这个 / 什么会破坏它 / 为什么它运行？” | ## `// 数据和隐私` - **所有内容都在你的机器上运行**：每个仓库的状态在 `.vinv/`（自动 gitignore）中，每个机器的状态在 `~/.vinv/` 中。学习账本是本地的，从未上传。 - **无遥测**。扩展程序不会进行任何网络调用；唯一的下载是嵌入模型（Hugging Face，一次）。所有其他内容都从此仓库构建。 - 跟踪器存储 **摘要**，而非原始值：字符串变为长度 + 哈希前缀；具有敏感名称的参数（`password`、`token`、`api_key`、`secret`、`authorization`、`credential`）被标记为已编辑，从不捕获内容；所有内容默认限制为 256 字节。 - 你的代码从未离开你的机器 - Vinv 与的唯一 LLM 是你配置的 **编码代理 CLI**，通过其自己的身份验证。 ## `// 贡献` 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。快速版：Python 引擎的 `uv sync`，`cargo build` 在 `index/`，`npm install && npm run check` 在 `extension/`，并且 `python tests/e2e/planted_bug_golden/run.py` 必须保持绿色。良好的初始问题被标记。 ## `// 许可证` [Elastic License 2.0](LICENSE) © 2026 VinvAI. <div align="center"> _{Python 优先，TS 和 Go 接下来 · <b>你的代理说它完成了。Vinv 说：‘请证明。’</b>} </div>