veris

Veris

veris — 拉丁语，意为“真实的”

你的 Agent 刚刚修改了 40 个文件。
究竟哪里出了问题？其中有内容经过检查吗？

---

我们让 Veris 分析 Veris——它找到了 55 个缺陷

每个缺陷都已公布——出了什么问题、为什么重要、如何修复，以及证明修复有效的测试：docs/internal/BUG_TRACKER.md

以下是我们工具中最严重的三个缺陷：

它捏造了基线。 无法使用 git 时，Veris 会用当前图谱的前 70% 构建一个“修改前”状态，并将对比结果报告为真实的行为差异。没有标记，也没有警告。一个验证工具竟然捏造了验证依据。

它 91% 的调用边都是猜出来的。 它会将调用的末尾名称与所有同名声明进行匹配。console.log() 因此被连到项目自己的 Logger.log。在一个真实依赖项上测得：3,077 条边中有 2,804 条指向含糊不清的名称。

被评分的 Agent 可以抹去自己的失败记录。 执行结果使用 INSERT OR REPLACE 存储。先提交 fail，再提交 pass，失败记录就消失了。

我们本可以悄悄修复这些问题。公开它们才是重点：一个会告诉你哪些内容未经验证的工具，没有资格隐瞒自己未经验证的声明。

**这也是演示。**这就是 Veris 对自身进行分析的结果。

---

Veris 是什么

一个面向 AI 编写代码的行为差异分析工具，通过 Model Context Protocol 提供服务，让你的 Agent 可以在仍在工作时发起询问，而不是等到你在审查中发现问题后才问。

它回答两个逐行差异无法回答的问题：

1. **哪些行为发生了变化？**不是哪些行，而是哪些行为，以及哪些内容会触达这些行为。
2. **其中有内容经过实际检查吗？**已公开的研究表明，大约 65% 的 Agent 编写的 PR，其自身修改行的覆盖率为零。

**Veris 从不执行任何内容。**不运行测试、不使用沙箱、不涉及运行时。它会读取代码、建立模型，并告诉你的 Agent 哪些内容存在风险、有哪些证据。执行工作仍交给擅长执行的工具。

Veris 并非	原因
测试运行器	它不执行任何内容，而是告诉你的测试运行器哪些内容值得运行。
代码检查器或 SAST 工具	它不检查代码风格或已知的不良模式，而是对行为变化建模。
“AI 护栏”	这个说法指过滤模型输出，而 Veris 关注的是模型编写的代码。
覆盖率工具	覆盖率说明哪些行运行过；Veris 则说明哪些行为发生了变化，以及有哪些依据支持这些判断。

---

30 秒速览

$ npx veris-core . --base-ref=origin/main

-> Baseline: origin/main @ 1bebd2ce2e08 -> head 3ed9031421-dirty
   Working tree has 4 uncommitted changes; this run is not reproducible from commits alone.
-> Graph: 326 nodes, 602 edges (head), 131 tracked files
-> Call resolution: 403 resolved (97.1%), 6 single-candidate, 6 ambiguous (no edge emitted)
-> Workflows: 15 detected, 3 affected in diff
-> Adversarial probes generated: 4

再读一遍第 2 行和第 4 行——这就是全部理念。

有 6 次调用存在歧义，无法消除，因此 Veris 没有猜测，而是不绘制边。头部标记为 -dirty，因为其中包含未提交的更改，所以无法仅凭提交重现结果。

大多数工具只报告发现了什么。Veris 还会报告它无法确定什么，因为坦承存在缺口，也好过自信地给出错误答案。

---

安装

作为 MCP 服务——添加一个配置块，然后重启客户端：

{
  "mcpServers": {
    "veris": {
      "command": "npx",
      "args": ["-y", "veris-core", "mcp"]
    }
  }
}

在 Claude Code、Cursor 或任何兼容 MCP 的 Agent 中启用 17 个工具。

作为 CLI：

npx veris-core .                            # analyze against origin/main
npx veris-core . --base-ref=HEAD~1          # explicit baseline
npx veris-core . --budget=10 --onboarding   # 10-min plan + onboarding map
npx veris-core doctor                       # check git, base ref, deps

需要具有真实历史记录的 git 仓库。 Veris 会与基础 ref 的合并基点进行比较。如果无法确定合并基点，它会失败并说明原因，而不是编造基准。在 CI 中：fetch-depth: 0。

在 npm 12 上，运行历史记录需要额外添加一行。 npm 12 默认不再运行依赖安装脚本，因此 better-sqlite3 不会获取预构建绑定。Veris 仍会分析、进行差异比较、评估风险并规划验证——只有运行历史记录和跨运行漂移检测需要它。允许列表按项目设置，不会从依赖项继承，因此必须放在你的 package.json 中：

{ "allowScripts": { "better-sqlite3": true } }

然后运行 npm rebuild better-sqlite3。veris-core doctor 会报告你所处的模式；如果持久化不可用，它绝不会声称持久化正常工作。

---

它如何思考

flowchart TD
    A[git-tracked source] -->|ts-morph + TypeScript checker| B[Behavioral graph]
    B -->|worktree at merge-base| C{Baseline exists?}
    C -->|no| X[Fail loudly<br/>never fabricate]
    C -->|yes| D[Diff: added / removed<br/>rewritten-body / edges]
    D --> E[Risk · Workflows · Fingerprints · Drift]
    E --> F[Probes · Tiered plan · Budget]
    F --> G[Coverage from<br/>trust-weighted evidence]
    G --> H[17 MCP tools · Dashboard · Reports]
    H -->|agent or CI executes| I[report_execution]
    I -->|append-only, hash-chained| G

    style X fill:#ff5d6c,stroke:#c1121f,color:#fff
    style G fill:#8b5cf6,stroke:#6d28d9,color:#fff
    style B fill:#0ea5e9,stroke:#0369a1,color:#fff

红框是一个特性。回到覆盖率的循环也是。

---

三个让它与众不同的理念

1. 每条边都会声明自己的确定性

大多数图工具只会给出一条边。Veris 会告诉你它为何相信这条边：

resolution	含义
resolved	TypeScript 检查器识别出了声明。可信。
heuristic	检查器无法识别，但只有一个同名声明。
structural	包含关系或导入关系。
(无边)	有多个候选项，且没有任何依据可以区分。保持沉默，不作猜测。

任何不能依赖猜测进行推理的机制——例如门禁、策略规则——都会筛选 resolved。缺失的边会低估耦合，但绝不会凭空捏造耦合。

2. 证据只追加，并记录是谁提供的

发布结果的 Agent 往往正是接受评判的 Agent。因此：

{ "nodeId": "src/pay.ts::charge",
  "result": "pass",
  "trustClass": "harness-observed",   // ← default is "agent-asserted"
  "producer": "github-actions:e2e" }

信任类别	来源	权重
veris-derived	Veris 计算得出	完整
harness-observed	外部运行器观察到	完整
agent-asserted	Agent 声称如此——默认类别	一半

记录采用哈希链串联。后续运行永远不会覆盖之前的失败；直接编辑数据库会破坏哈希链，verifyEvidenceChain() 会准确报告损坏位置。Agent 无法靠更用力地声明来提高自身的可信度。

3. 它能捕捉名称未变的重写

- function chargeCard(amount) { return gateway.charge(amount); }
+ function chargeCard(amount) { return gateway.charge(amount * 100); }

名称相同。被调用项相同。图结构相同。所有基于名称和拓扑的比较都看不出任何变化。Veris 会对规范化后的函数体进行哈希，因此这种变化会显示为 modifiedNode——而重命名目录过去会被误判为 100% 漂移，现在则会被正确识别为没有漂移。

---

Agent 会询问什么

veris: analyze_pr_behavior with baseRef=origin/main
veris: list_workflows, then analyze_workflow for the highest-risk one
veris: generate_adversarial_probes, then allocate_budget minutes=15
veris: detect_drift
veris: what_if_revert nodeIds=[...]

探测项具体明确，而非泛泛提醒：

支付 / 幂等性——在 500 ms 的时间窗口内，使用相同的幂等键提交两次扣款。 **不变量：**账本中恰好有一条记录；第二次调用返回第一次调用的结果。

---

Webhook / 重放——使用原始签名，重放一条 24 小时前签署的负载。 **不变量：**即使签名有效，也会因超出时间戳窗口而被拒绝。

它还有哪些功能

语义工作流	25 个领域——身份验证、支付、结账、Webhook、队列、缓存……因此，分析单元是“结账可靠性”，而不是 GraphModels.ts。
风险模型	耦合程度、入站耦合主导性、运行时关键性——三个衡量不同因素的输入。所有权重都在 data/risk-config.json 中，并附有通俗易懂的说明。
漂移检测	跨运行记录指纹。可检测静默重写、表面变化、反复振荡的重构和删除。
预算分配	给定 N 分钟，选出实际运行时杠杆效应最高的子集。
反事实分析	what_if_revert——移除它后，哪些方面会恢复？
入门导出	为新工程师或新 Agent 提供面向工作流的 Markdown，帮助其了解陌生代码库。
仪表板	独立 HTML。点击某个工作流，所有内容都会随之筛选。点击即可复制指令。

---

坦诚说明局限

直接说明，避免大家日后才发现这些问题。

• 工作流是标签，不是路径。 分类依据目录名、导入项和符号名进行加权关键词投票，不会遍历调用图。导入 Redis 的限流代码会归入缓存。让工作流成为真实路径是路线图上的首要事项。
• 覆盖率不等于保证。 它衡量已有证据支持的计划验证占比，未根据真实事故进行校准，也不会估算代码正确的概率。
• 风险是启发式指标。 适合用于确定优先查看的内容，不是缺陷预测器，也没有真实情况作为依据。
• 探针是经过筛选的库——由人工编写、针对真实故障模式，并按领域选择。它们并非根据你的代码生成。
• 仅支持 TypeScript 和 JavaScript。 Python 和 Go 已列入路线图。
• 有些调用无法解析。 动态分派和无类型 JS 会让检查器无法处理这些调用，因此不会生成对应边，输出中会列出数量。

从 2.x 升级？ 3.0 存在实际的不兼容变更——请参阅 UPGRADING.md。

---

隐私与安全

• 本地优先。 所有分析都在你的计算机上运行。绝不收集遥测数据。 你的代码不会离开计算机。
• 零保留模式——VERIS_STATE_DISABLED=1。
• 分析器不使用网络套接字。 仅使用 stdio 和文件系统。

Veris 通常用于分析你并未编写的代码库，因此代码库内容属于不可信输入。插件会执行被分析代码库中的代码，因此默认禁用——使用 --allow-plugins 选择启用，并且运行前会打印每个插件的路径和 SHA-256。这里没有沙箱，SECURITY.md 会明确说明这一点，而不会暗示另有保护措施。

---

文档

MCP 工具	全部 17 个工具及推荐流程
架构	设计不变量及其所取代的缺陷
审计跟踪	全部 55 项发现及其证据
升级	2.x → 3.0
安全	威胁模型与报告方式
路线图	下一步计划，以及永远不会实现的内容
插件	扩展分类和风险评估

---

贡献

最能推动项目进展的五件事：

1. 入口点检测，针对你熟悉的框架——路由、处理器、队列消费者。这能让工作流从一个标签变成一条路径。
2. 带标签的代码仓库，用于分类基准测试。准确率声明需要真实依据，而不是更多规则。
3. 探测依据。 已提供的探测效果不错，但没有引用来源；有公开事后分析支持的探测，胜过十个没有来源的探测。
4. 语言适配器——Python、Go。
5. 校准数据——Veris 标记了哪些问题，后来证明有误；又漏掉了哪些问题。后者更有价值。

请参阅 CONTRIBUTING.md。开源，由赞助支持。没有付费层级、功能限制，也没有以开放核心为诱饵的套路。

_{MIT 许可 — 请参阅 LICENSE}