Vinv

VinvAI

帮助 AI Agent 测试、修复和优化代码库的工具。

Vinv 将运行时跟踪与生成它们的确切源码关联起来，把这些证据交给你已经在使用的编码 Agent，然后重新运行代码，验证修复确实有效。它不是另一个编码 Agent，而是你现有 Agent 背后的证据层：你的 Agent 提出方案，Vinv 负责验证。

编辑器扩展 一键安装到

MCP 服务 16 个工具 — 添加到

查看实际效果 · 功能介绍 · 深入了解其原理 · 2 分钟演示

_{只构建一次工作区上下文——每个 Agent 都读取同一个 .vinv/ 存储。}

为什么选择 Vinv

如今，84% 的开发者已经在使用或计划使用 AI 编码工具，但不信任其输出的人（46%）多于信任的人（33%），而且不信任的人数在一年内几乎翻了一倍（Stack Overflow 2025，49k 名开发者）。

原因并不陌生：Agent 修改了错误的处理程序，臆造返回结构，然后自己批改自己的作业，而服务甚至无法启动。或者它陷入循环——测试失败，Agent 修改同一个函数，测试再次失败——把上下文窗口浪费在“让我验证一下”上。

这两种失败有着共同的根源：Agent 从未观察过你的代码运行。 它只根据静态文本进行判断。

这个行业自动化了代码的编写，却把代码的验证完全留给了人工。Vinv 自动化验证，然后才进行查找和修复。

安装

Vinv 有三种使用方式：编辑器扩展、CLI，或供任何 Agent 使用的 MCP 服务。三者共用相同的本地引擎。

编辑器扩展

只需单击一次——从 vinv.ai 安装，即可在编辑器中直接打开扩展（VS Code、Cursor、Windsurf、VSCodium、Trae 和 Insiders）。扩展发布在 Open VSX 和 VS Code Marketplace。

也可以使用编辑器的 CLI 安装：

_{首次运行时会构建引擎——大约需要 3 分钟，主要用于编译 Rust 索引；此外还会一次性下载约 100 MB 的本地嵌入模型（需要安装 uv 和 Rust）。大约一分钟后即可获得第一条跟踪记录；之后的操作只需几秒。}

CLI（Python 引擎）

pip install vinv          # every engine as a console script
# or run one with zero install:
uvx --from vinv exerciser campaign <repo> --budget 20

MCP 服务（适用于任何 Agent）

为 Claude Code、Cursor 或任何 MCP 客户端提供 Vinv 工具——只需配置一个全局配置，即可通过 MCP 根自动找到已打开的工作区。

Claude Code、Codex、Gemini CLI——只需安装一次，即可用于你打开的每个文件夹，而不只是当前文件夹：

claude mcp add --scope user vinv -- npx -y vinv-mcp

codex mcp add vinv -- npx -y vinv-mcp

gemini mcp add --scope user vinv npx -- -y vinv-mcp

_{Claude Code 默认使用当前目录，Gemini CLI 默认使用当前项目，因此二者都需要设置 --scope user；Codex 始终写入 ~/.codex/config.toml，没有 scope 标志。}

_{其他客户端：在 mcpServers.vinv 下添加 { "command": "npx", "args": ["-y", "vinv-mcp"] }。参见 vinv-mcp——共 16 个工具：语义搜索、死代码检测、故障定位、运行时值/切片/覆盖率，以及验证/优化循环。}

git clone https://github.com/VinvAI/VinvAI ~/.vinv/engines && cd ~/.vinv/engines && ./install.sh

git clone https://github.com/VinvAI/VinvAI $HOME\.vinv\engines; cd $HOME\.vinv\engines; .\install.ps1

运行 → 测试 → 发现 → 证明。 将 Vinv 指向一个 Python 仓库；其余工作交给它——无需修改代码，也无需 API 密钥。

flowchart LR
  T[Trace] --> I[Index] --> S[Serve MCP] --> V[Verify] --> L[Learn] --> T

• 运行 — 无需任何修改，即可在追踪环境下启动所有服务，从实际运行中捕获耗时、参数、返回值和调用树。
• 测试 — 向每个端点发送真实请求（有效、边界、负面、经过身份验证），并将每个响应存为回归用例。
• 发现 — 找出实际出现的问题或性能变慢之处——服务器错误、崩溃、延迟热点、死代码——并将每项问题关联到确切的源代码行。
• 证明 — 将证据交给你已经在用的 Agent，然后根据修复前编写、且 Agent 从未见过的验收测试验证修复。任何改变输出的“加速”改动都会自动回滚。

_{你的 Agent 是唯一的大模型——不增加费用、不用挑选模型，也无需提供商密钥。查看 vinv.ai/#under-the-hood 上的完整演示。}

查看实际效果

这不是实验室基准测试，而是在真实项目（scikit-learn、watermarks-remover、semantica、FastAPI、Typer、smolagents）中发现并提交的真实问题，每项都有可打开的上游讨论串。所有工作均由安装了 Vinv、运行 Composer 2.5 的 Cursor驱动——并非前沿模型。发挥作用的是证据，而不是模型。 查看包含截图的完整列表：vinv.ai/#catches。

死代码——以从未运行过来证明

静态工具只能证明*“没有任何内容引用它。”* Vinv 则能证明*“没有任何一次捕获执行过它，”*将每个未追踪的代码孤岛及仍指向它的活动调用方一并呈现，并让你的 Agent 给出结论——集成、删除或保留。

_{semantica#1176 在一个讨论串中展现了严谨做法：维护者指出有两个符号可供下游导入，Vinv 为其添加弃用警告并予以恢复，同一位维护者随后合并了更改。}

优化——必须证明有效的加速

每次调用都会计时，并将耗时归属到实际消耗它的符号。只有当配对自助法 95% 置信区间高于零，且行为测试套件重放结果逐字节完全一致时，候选修复才会发布——更快但结果不同的改动会自动回滚。

错误报告 — 只在运行时才会出现的错误

扫描器读取源代码并猜测。Vinv 驱动服务并监视返回结果：

• 驱动 — 对每个发现的端点进行测试，使用无人编写过的输入。
• 判定 — 500 状态码本身不算发现；判定器会指出本应返回的状态码。
• 移交 — 以证据包的形式交付：复现命令、调用链、实际参数值。

在 fastapi/full-stack-fastapi-template（约 44k★）上，经过身份验证的扫描提交了讨论 #2454——4 个端点对本应返回 4xx 的输入返回了 500，每个端点都有一个复现用例——随后另一位贡献者在 master 上逐一复现了这 4 个问题，并指出文件和行号：“已在 master 上验证——全都是真实问题。”

Vinv 能为你的 Agent 做什么

一个循环，按你要解决的问题分类。每项能力都链接到网站上的实时演示。

理解代码库 → vinv.ai/#what-it-does

• 语义代码搜索 — 按含义提问，获取带排名的符号及其 def 函数体和行号，由本地模型生成嵌入。
• 代码图谱 — 持久化记录每个符号和调用边的映射，保存时增量更新，并附带实时运行时叠加信息。
• 运行时追踪 — 无需修改代码即可追踪：每次调用的耗时、内存、参数、返回值和错误，并关联到源代码。
• 询问 Vinv — 用通俗英语提问有关运行中系统的问题，每个回答都引用确切的追踪片段和源代码行，并由确定性审查器拦截证据无法支撑的任何说法。

找出实际出错之处 → vinv.ai/#catches

• 故障嫌疑项排名 — 对任何故障，依据真实成功/失败请求的故障定位得分为符号排序，并附上实际错误消息。
• 行为测试器 — Vinv 不会等待流量：它会自行驱动每个发现的端点，使用 Thompson 抽样多臂老虎机选择策略，并将每个响应保存为永久回归用例。

清理死代码 → vinv.ai/#what-it-does

• 死代码区段 — 将未追踪的孤岛划分为“没有引用”和“由活动代码触达但从未执行”两类，每个区段都附有仍指向它的活动调用方，以及附带理由的保留或删除结论。

找回延迟损耗 → vinv.ai/#what-it-does

• 可找回耗时 — 按实际可节省的毫秒数为延迟热点排序，并将每项作为先预测、后验证的优化任务分派，而不是凭猜测行事。

信任修复结果 → vinv.ai/#under-the-hood

• 已验证的修复 — 重放启动流程、使用实时端口、运行 Agent 看不到的验收测试。点击一次即可还原某个任务执行过程中的所有更改。
• 旅程 — 一次演示所有已验证内容：每个服务，以及每个端点的调用树、延迟火焰图和精确输入 → 输出；还可添加自己的测试输入，由引擎永久重放。
• 自动驾驶 — 点击一次即可依次执行发现 → 设置 → 追踪 → 测试 → 修复 → 验证，直到全部通过或预算耗尽；出现新的追踪错误时，等你在图谱中看到红色圆环，修复任务已经分派完毕。
• 发现项 — 问题聚类、带配对自助法置信区间的优化任务、按类型区分的回归差异，以及可供 Agent 直接使用的机器可读 findings.json。

诚实说明范围： 目前优先支持 Python——服务和 API。其他语言可使用索引、图谱和基于证据的问答，但目前尚无运行时证据。接下来将支持 TypeScript 和 Go。

仅使用 Agent 与使用 Agent + Vinv

为什么 Agent 在 Vinv 下无法通过奖励入侵取巧

Vinv 将每条运行时轨迹都与生成它的确切代码关联起来，并基于这种关联为你的 Agent 构建上下文图，因此 Agent 依据证据推理，而非凭感觉判断。而当它宣称成功时，Vinv 不会只听它的一面之词：

• 验收测试会在修复前编写，存储在工作区之外，并使用不透明令牌；这些测试必须在有缺陷的代码上确定性地失败两次——修复前就能通过的测试会被丢弃。
• 任何会改变可观察输出的“更快”修复都会自动回滚——行为测试套件必须重放出逐字节一致的结果，而且加速效果的配对自助法 95% 置信区间必须不包含零。
• 有意返回的 4xx 拒绝并非需要修复的“错误”——缺陷分类器能区分服务正确地说“不”和服务发生故障，因此 Agent 不会收到只能靠取巧达成的虚假目标。
• 当两次尝试都不再取得进展时，纳什议价僵局裁判只有在探索者立场和审计者立场都严格认为继续尝试优于询问你时，才会继续。

Vinv 的发布门禁就是 Vinv——以下数据来自在本仓库上运行该循环：

_{完整的学习过程——奖励、倾向评分、门控计算，以及每项主张对应的 file:line——见 docs/learning.md。测试分类体系见 docs/testing-ontology.md。}

适配你的 Agent

运行一条命令（在 Agent Tools 中注册 Vinv MCP），即可将服务写入检测到的每个 Agent：

pip install vinv 会将所有引擎作为控制台脚本一并安装，也可以单独使用其中任意一个：

隐私

• 所有内容都在你的机器上——每个仓库的状态存储在 .vinv/ 中（自动加入 Git 忽略），每台机器的状态存储在 ~/.vinv/ 中。无需账户、无需 API 密钥，没有遥测——完全没有。
• 仅有一次出站请求，你可以查看其内容：激活时获取 notices.vinv.ai 上的一个静态 JSON 文件，仅用于发布版本问题和安全通知。没有查询字符串、没有标识符，也不会上传任何内容；最多每 12 小时一次；使用 vinv.notices.enabled 可将其关闭。
• 唯一的下载内容是嵌入模型（来自 Hugging Face，仅下载一次，约 100 MB）；其他所有内容都从此仓库构建。
• 跟踪记录存储的是有限长度的摘要，而非原始值；敏感参数名称（password、token、api_key、……）会经过脱敏，绝不会被捕获。
• Vinv 唯一会与之通信的大模型，是你配置的编码 Agent CLI，通过该 CLI 自身的身份验证进行通信。

贡献与许可

请参阅 CONTRIBUTING.md — 运行 uv sync，在 index/ 中运行 cargo build，在 extension/ 中运行 npm install && npm run check，并确保 tests/e2e/planted_bug_golden/run.py 通过。适合新手的问题都有标签。参与即表示你同意我们的行为准则；如需报告漏洞，请参阅 SECURITY.md。Apache License 2.0 © 2026 VinvAI。