Vibgrate MCP

@vibgrate/cli
面向 AI 编码 Agent 的本地代码库智能分析——在你的机器上构建图谱、检测漂移，并提供版本准确的文档

想要参与贡献？请参阅 CONTRIBUTING.md 和 适合新手的议题。

npx @vibgrate/cli scan          # drift score + upgrade priorities
npm install -D @vibgrate/cli   # install for repeat runs

vg 可以回答任何代码库的三个问题：

1. 这是一个什么样的代码库？ — 确定性的代码图谱：调用树、导入路径、影响范围和依赖事实。
2. 它落后了多少？ — 分级的 DriftScore（0–100），涵盖运行时／框架滞后、依赖项年限和临近 EOL 的情况，并提供按优先级排序的修复清单。暴露程度会单独计为 RiskScore；两项合并即为 DriftRisk Index。完整的方法论——公式、来源和局限性——以 白皮书形式发布，采用 CC BY 4.0 许可（DOI 10.5281/zenodo.21336304）。
3. 可以在这里修复吗？ — VG Code，一个以代码图谱而非 grep 作为搜索工具的编码 Agent；可在终端中通过 vg code 使用，也可通过 Vibgrate for VS Code 中的 VG Code 面板使用——此外还有 vg fix，可生成按优先级排序且能够应用的升级计划。

所有操作都在你的机器上运行。无需 API 密钥，不会发起网络请求，也不会有数据离开你的代码库，除非你明确推送。vibgrate 命令是 vg 的别名——两者可以互换使用。

---

查看运行效果

_{真实的 vg scan 回放——一条命令即可查看漂移分数、明细和按优先级排序的建议。动画可直接在 GitHub 上播放；不会在浏览器中运行任何内容。}

▶ 试用在线互动式 CLI 模拟器 →
_{使用真实示例代码库逐步体验每条命令（scan、build、ask、why，……）。}

---

10 秒上手

无需安装或注册：

npx @vibgrate/cli scan          # drift score + upgrade priorities
npx @vibgrate/cli build         # build the code graph
npx @vibgrate/cli ask "what does AuthService do?"
npx @vibgrate/cli code          # a coding agent — it asks before every edit

安装以便重复运行：

npm install -D @vibgrate/cli
npx vg scan                     # vg is the primary command; vibgrate is an alias

本地二进制文件位于 node_modules/.bin 中——除非进行全局安装，否则请使用 npx vg（或 npm 脚本）。

---

Windows 安装

支持使用 Node.js 22 或更高版本的 Windows。Windows 安装程序优先使用 PowerShell：

irm https://vibgrate.com/install.ps1 | iex

如果你更喜欢使用 npm，可全局安装 CLI：

npm install -g @vibgrate/cli

如果只运行一次且不想更改 PATH，请使用：

npx @vibgrate/cli scan

全局 npm 安装会将 vg.cmd 和 vibgrate.cmd 命令垫片放在 npm 的全局前缀目录中。使用 npm config get prefix 查看确切位置；如果找不到 vg，请将该目录添加到用户的 PATH，然后打开新的 PowerShell 窗口。使用以下命令验证安装：

vg --help
vg doctor

vg doctor 是只读诊断命令。如果 vg 与系统上的其他命令冲突，请改用完全相同的 vibgrate 命令。本 README 其他位置的命令示例使用 POSIX 路径语法；在 Windows 上请将路径调整为 PowerShell 语法。

---

与 AI 助手搭配使用

vg serve 会启动 Vibgrate AI Context ——一个本地优先的 MCP 服务，可向任何兼容 MCP 的助手（Claude、Cursor、Windsurf、Copilot、Gemini CLI 等）提供代码地图、离线漂移分析、本地模型和版本匹配的 库文档，所有内容均来自你的设备（无需账号，也不会上传任何内容；本地文档不完整时，会回退到托管目录，除非你传入 --local）。无需塞满上下文窗口，也不会幻觉 API。代码地图会自动保持最新： 文件发生变化时（包括助手刚刚所做的编辑），下一次工具调用会在作答前增量重建代码地图，无需监视器或守护进程。

_{node-turborepo/serve — vg serve --http 会启动 Vibgrate AI Context。在线模拟器。}

只需一条命令即可完成配置：

vg install                      # interactive: pick your assistant(s) and done
vg install --all                # install for every detected assistant at once

此操作会为你选择的工具写入 MCP 配置，并安装一个用于教助手查询图谱的技能。重新加载助手后，你就能获得具备图谱上下文的回答：调用树、影响分析、漂移发现结果、版本匹配的库文档——全部来自本地数据。经测量的 Token 节省数据及其方法说明已发布于 vibgrate.com/cli/benchmarks/token-savings。

在 vibgrate.com/skills 浏览全部 21+ 个受支持的助手及其技能说明。

减少助手重复读取的内容：上下文压缩

每轮对话中，你的 AI 助手都会重新发送整个对话——包括 20,000 行的测试日志、400 行的 JSON 负载，以及它已经处理过的 grep 输出。每一步你都要为这些上下文再次付费。Vibgrate CLI 会在内容到达模型之前压缩工具输出和较早的对话轮次，在你的设备上保留可供检索的原始内容，并报告节省了多少。

vg install claude --compress    # point Claude Code at the listener and start it (undo with `vg uninstall claude`)
vg savings                      # tokens and estimated dollars saved, today / 7 days / 30 days

无需学习单独的命令：压缩是你已经在运行的服务的一种模式，也是你已经在使用的安装器的一个标志。vg install <agent> --compress 会写入 Agent 自己的基础 URL 配置，在后台启动监听器（或复用已在运行的监听器），并且对于 Claude Code，还会添加一个 SessionStart 钩子，让它在重启后恢复运行。vg serve --compress 会在一个前台进程中提供代码映射并执行压缩；vg serve --compress --background 则只启动监听器并返回。若要在不写入任何配置的情况下运行单个会话，vg serve --compress claude 会通过它运行一个 Agent，并在退出时恢复你的环境。在 vg code 中，压缩已默认开启——大型工具结果在重新进入循环前会先经过压缩，模型可以通过 vg_retrieve 取回任何原始内容。

运行时会依次执行以下操作：

• 根据内容类型路由每个区块——JSON 数组、日志和构建输出、grep 结果、差异、HTML、表格、配置文件、源代码、散文——并应用针对相应格式构建的压缩器。错误、ID、堆栈跟踪以及与你请求匹配的行始终会保留。
• **优先无损压缩。**重复行、grep 标题和差异索引行会折叠为可按字节还原的标记。只有在能明显节省更多内容时才会执行有损压缩，而且绝不会用于文件读取或编辑，因此先读后改仍能保持精确。
• **不会丢失任何内容。**压缩后的区块会带有标记；模型（或你通过 vg serve retrieve <hash>）可以取回原始内容，或只取回所需的片段。原始内容存储在短期本地存储中——不会上传任何内容。
• **兼顾前缀缓存。**默认的 cache 模式只压缩最新一轮，让你的服务提供商的提示词缓存持续命中；token 模式则压缩所有符合条件的内容，以实现最大节省。
• 适用于任何 Agent。vg install <agent> --compress 支持 Claude Code、Codex、Cursor、Aider、Copilot、OpenCode、Cline、Continue、Goose、OpenHands、Gemini CLI、Kimi、Grok 等；vg uninstall <agent> 会逐字节还原它们的配置。也可以使用适配 Anthropic、OpenAI 和 Vercel AI SDK 格式的 SDK 封装器。

所有操作都在本地离线运行。监听器绑定到回环地址，原样转发你的服务提供商凭据，在任何内容写入磁盘前先对机密格式进行脱敏，并且绝不会主动连接外部服务器。vg serve config 会列出所有可调参数，vg serve config set KEY VALUE 则可以修改其中一项。

工具

vg serve 会公开 24 个 MCP 工具（加上使用 --memory 时的两个记忆工具）：

• orient — 从这里开始：项目概览、入口点、优先查看的位置。
• search_symbols — 按名称或字面字符串查找符号。
• query_graph — 按含义查找代码：症状、关系、变更会造成什么影响。
• get_node — 检查单个符号：签名、调用方、被调用方、所属区域。
• find_path — 查找两个符号之间的最短连接，并注明每一跳的边类型；calls_only 仅沿调用关系查找，并提供每个调用点的行号。
• impact_of — 变更的影响范围：依赖项、文件、覆盖该变更的测试、风险。
• tests_for — 查看覆盖某个符号的测试。
• get_graph_summary — 代码地图概览：数量、语言、主要区域和枢纽。
• list_areas — 按规模列出代码区域（社区）。
• list_hubs — 列出依赖最多的符号。
• get_facts — 获取节点的确定性事实（契约 / 不变量 / 特征描述）。
• guide_node — 获取节点相关的标准和实践引用（OWASP/CWE）。
• check_drift — 离线依赖清单，可选附带由谁添加的 git 归因信息。
• vuln_attribution — 各项未修复漏洞的引入者、暴露时间窗口和 CRA 修复指标。
• list_vulnerabilities — 来自最近一次 vg scan --vulns 的已知漏洞：CVE、严重程度、CVSS、修复版本，以及该次扫描记录的 EPSS 或已知在野利用字段。
• upgrade_impact — 升级软件包会造成什么影响：主版本差距、导入影响范围、修复的漏洞。
• list_models — 磁盘上的本地模型（Ollama / LM Studio / gguf）。
• resolve_library — 将库解析为其规范 ID 和项目使用的版本。
• library_docs — 符合版本的库用法文档，并按令牌预算切分。
• compress_content / retrieve_original / compression_stats（使用 --compress）— 在工具输出进入上下文前缩减内容，将标记还原为原文或所需片段，并报告压缩节省的内容。
• memory_search / memory_save（使用 --memory）— 在 AI Agent 之间共享的项目专属记忆。
• review_doc（使用 --review）— 为变更编写评审文档：打开文档、按 ID 修改区块、检查每个 pin、查看历史记录、恢复版本，以及阅读并回复他人在 Vibgrate Cloud 中推送的文档上留下的评论。文档保存在 .vibgrate/review-docs/ 下，不会放在代码库中。

只有在你提出请求时才会列出最后三组工具。每个 Agent 步骤都会重新发送所有已公布工具的 schema，因此未启用的功能也会持续产生成本。

更倾向使用托管服务，而非团队的扫描数据？Vibgrate Cloud MCP 可将你的助手连接到 Vibgrate Cloud（OAuth 2.1，14 个只读工具）。

---

理解任意代码库

构建一次图谱，持续查询。以下是在示例代码库上录制的真实 CLI 回放 — 在线运行。

_{node-turborepo/build — vg build 为 pnpm monorepo 建立映射。}

vg build                        # index the repo (incremental; re-run after changes)
vg show src/auth/service.ts     # what this file does, calls, and is called by
vg ask "where is rate limiting enforced?"
vg impact src/db/connection.ts  # what breaks if this changes + tests to run
vg path src/api/handler.ts src/db/query.ts   # shortest call path between two files
vg tree src/server.ts           # call tree rooted at a node
vg insights                     # overview: hubs, hotspots, untested paths

_{node-turborepo/ask — vg ask 返回带引用的节点，而不是一篇聊天长文。}

_{node-turborepo/impact — 编辑前查看变更枢纽的影响范围。}

图谱具有字节级确定性且可复现 — 同一代码库在每台机器上始终生成相同的图谱。

vg share                        # make the graph committable + auto-updating for the team
vg serve                        # start Vibgrate AI Context (local-first MCP: code map + drift + version-correct docs)

---

VG Code — 编写变更，而不只是生成报告

VG Code 是 Vibgrate CLI 内的编码 Agent。它的搜索工具是确定性代码图谱 — 不是 grep，也不是基于分块的嵌入 — 可按你的选择运行本地模型或托管模型。

vg code                                            # guided: pick a model, then describe tasks
vg code "add a --timeout flag to the scan command"

它会写入你的磁盘吗？ 会 — 但只会执行你批准的步骤。只读步骤（搜索、读取、列出、影响分析）无需提示；每次编辑和每条命令都会先征求许可。--auto 会在 CI 中运行相同的循环，但不显示提示。没有终端且未使用 --auto 时，vg code 会拒绝启动，而不会在无人看管时写入内容。

两个入口，一个 Agent。 vg code 是终端入口。Vibgrate for VS Code 中的 VG Code 面板是图形界面入口；对大多数人来说，它会是日常使用的入口：任务间保留会话、聊天历史记录、带差异对比的行内批准 / 拒绝卡片、检查点和 @ 提及。扩展不会重新实现 Agent — 它通过 --stream-json 运行随此 CLI 一同发布的 Agent，并将你的决定转发给它，因此终端、编辑器和 CI 的行为始终一致。

为什么要在这里使用 Agent，而不是再开一个聊天窗口？

• 搜索就是图谱。 search_code 会根据 vg build 生成的映射解析符号、调用方和被调用方——因此模型会获得三个关键函数，而不是 40 个提到该词的文件。
• 编辑前先评估影响范围。 graph_impact 会在模型修改符号之前告知它哪些内容依赖该符号，而 vg tests 会确定之后要运行哪些测试。
• 文档与库版本相匹配。 library_docs 会固定到锁文件中的版本，因此模型会基于你实际使用的 API 编写代码。
• 阻止虚构标识符，而非仅仅标记。 写入编辑内容前，系统会根据图谱的标识符字典树扫描替换内容。图谱不认识、且目标文件中也尚不存在的符号会导致写入被阻止。
• 本地模型是核心功能，托管模型只需一个开关即可启用。 使用已拉取的模型时，无需账户和密钥，Code Modes 会根据机器配置适配模型。任务有更高需求时，Vibgrate Relay 可通过你的 Vibgrate 账户提供托管模型——无需各个提供商的 API 密钥；如果无法连接，则回退到本地模型。
• 可接入你已有的 MCP 服务。 系统会读取 .mcp.json（Claude Code）、.cursor/mcp.json 和 .vscode/mcp.json，并与 .vibgrate/code.json 合并；名称冲突时以后者为准。
• 费用清晰可见。 每项任务完成后以及在 /cost 中都会显示 Token/$ 计量器；vg savings 会按模型报告由图谱支持的调用次数。

取舍： CLI 不附带模型，VG Code 的效果取决于你为它指定的模型。7B 本地模型并非前沿模型——它带来隐私保护、离线推理和零 Token 费用。Relay 则以按 Token 计费的方式提供更强的能力。选择适合任务的档位即可；无论选择哪种，图谱提供的依据都相同。

完整会话流程

  VG Code  · graph-grounded coding · v2026.x

  ✔ Code map built
  ✔ Model catalog loaded
  ◆ Ready — ollama/qwen2.5-coder:7b · graph 48213. Describe a task, or /help.

  code › add a --timeout flag to the scan command and use it

    → search_code(query: --timeout flag scan command)
      scanCommand (function) src/commands/scan.ts:12
    → graph_impact(symbol: runScan)
      3 symbol(s) depend on runScan: …
    → edit_file(path: src/commands/scan.ts, …)
  ? Apply edit to src/commands/scan.ts? [Y/n] y
      ✔ edited src/commands/scan.ts
    → run_command(command: npm test -- scan)
  ? Run `npm test -- scan`? [y/N] y
      ✔ exit 0  … 12 passing

  ✔ added a --timeout flag to scan and covered it with tests
    +6 -1 across 1 file(s) · via ollama/qwen2.5-coder:7b

具体流程如下：

1. 构建代码映射，或以增量方式刷新——只有变更过的文件会重新解析。
2. 加载模型目录，然后选择本地模型或托管提供商。拉取本地模型前，系统会进行内存预检，将模型的估算占用量与可用 RAM/VRAM 比较，并拒绝运行这台机器无法承载的模型。
3. Vibgrate Graph（vg serve）会作为子进程在整个会话期间运行，并在你退出时停止。每次图谱调用都会归属到 VG Code 和当前使用的模型。
4. Agent 按以下循环工作：搜索 → 读取 → 评估影响 → 编辑 → 运行。
5. 每个会修改内容的步骤都需要你批准；使用 --auto 时则会无人值守运行。
6. 编辑会通过确定性合并应用，因此变更会准确落到预期位置。

批准模式

模式	行为
交互式（默认）	只读步骤可自由运行。每次编辑和每条命令都需要先询问。
--auto	不提示。拒绝列表会拦截灾难性命令——清空文件系统、curl … | sh、强制推送、sudo。适用于 CI 和脚本化运行。
--single	单次执行：提出差异后停止。不运行工具循环，也不执行命令。除非传入 --apply --yes，否则为试运行。

--max-steps <n> 会限制循环次数（默认 24）。--worktree 会在隔离的 git worktree 中运行整个会话，因此在应用变更前不会触及主工作树。

选择哪种模型——本地模型，还是通过 Relay 托管的模型

Code Modes 会根据这台机器的实际内存、显存和磁盘空间，选择真正适用的本地模型，并在下载任何内容前进行检查：

模式	用途
Spark	快速、占用空间小——适合快速编辑和内存有限的情况
Flow	均衡的默认选项，适合日常编码
Forge	更高配置的选项，适合资源充足且需要更大容量的情况

vg models                       # what's set, and what fits this machine
vg models install flow          # install the pack (--dry-run to preview)
vg models pull qwen2.5-coder:7b

Vibgrate Relay 是托管服务层，可在任务所需容量超出机器能力时补充本地模型。一个 Vibgrate 账户和端点、精选的托管模型目录、按 Token 计量并从预付余额中扣费——无需管理各个提供商的 API 密钥：

export VIBGRATE_RELAY_TOKEN=…   # Relay is then preferred, with local fallback
vg code --provider vibgrate-relay --model <slug>

你不必只用它。--provider 也可以指定 ollama、lmstudio、foundry-local、llama-cpp、openrouter、litellm、openai 和 together；这些 API 密钥只会从环境变量中读取（如 OPENROUTER_API_KEY），绝不会作为标志传入。如果未指定 --provider，vg code 会使用你已配置的选项——优先使用已设置令牌的 Relay，其次是其他托管服务密钥，最后是本地模型；绝不会连接到你未配置的端点。--local 会让它只在本机运行。

Agent 可用的工具

工具	功能	审批
search_code	搜索代码图谱——符号和关系，并对精确短语进行字面搜索	无需审批
read_file / list_files	读取文件或行范围；列出图谱中的文件	无需审批
graph_impact	查看更改某个符号的影响范围	无需审批
library_docs	获取你实际安装的依赖项对应版本的文档	无需审批
edit_file / create_file / delete_file / apply_patch	更改工作树	需审批
run_command	运行测试、构建及其他命令	需审批
web_fetch / web_search	获取或搜索公开网络内容——不可信、会隐藏机密，并限制内容大小	需审批
browser_* / read_notebook / spawn_subagent	操作浏览器、使用 Jupyter 笔记本、委派子任务	需审批
mcp__<server>__<tool>	来自你配置的 MCP 服务的工具	只读时无需审批，否则需审批

会话内命令

命令	功能
/undo	还原上一个任务更改的文件
/diff	显示上一次更改
/model	无需离开会话即可切换模型
/cost	查看当前 Token 和美元费用（本地模型免费）
/compact	将当前会话内容压缩为一个检查点摘要
/help / /exit	列出命令 / 退出

状态存储位置

磁盘上	会话中
代码图谱（.vibgrate/），由 git 忽略	对话和步骤历史
你的配置（.vibgrate/code.json）	/undo 堆栈
修改内容本身——本地保存，可通过 git 还原	Token/美元计量器
会话存储，因此 --continue 可以恢复	vg serve 子进程

--continue 会恢复你最近的会话：向模型概述已完成的内容，并恢复 /undo。

配置一次即可

.vibgrate/code.json——标志仍可覆盖配置：

{
  "provider": "ollama",
  "model": "qwen2.5-coder:7b",
  "testCommand": "npm test",
  "auto": false,
  "denyCommands": ["deploy", "kubectl\\s+delete"],
  "maxSteps": 24,
  "mcpServers": {
    "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] }
  }
}

完整的键参考（包括 securityTier、capsule 和 modelProfile）见 DOCS.md。

安全

• 永远不会将机密文件（.env、.npmrc、.netrc、密钥材料）读入提示词；Agent 读取的任何文件中，凭据格式都会被隐藏。
• 在 --auto 模式下，拒绝列表会拦截可能造成灾难性后果的命令。交互模式下，每条命令都会显示出来，供你审批。
• 所有更改均保存在本地，并可通过 git 还原。/undo 会还原上一个任务；--worktree 会让整个会话在主工作树之外运行。
• 网络和浏览器结果均视为不可信内容，绝不会作为指令执行。

---

衡量和管理升级漂移

_{calcom/scan — 使用示例 Cal.com 数据执行纯粹的 vg 漂移扫描。在线模拟器。}

vg scan                         # drift score + risk level + ranked priorities
vg scan --push                  # same, and upload to Vibgrate Cloud for trend tracking
vg baseline                     # snapshot current drift for regression gating
vg report                       # generate a report from a saved scan artifact

一次扫描即可获得：

• 总体评分（0–100）和风险级别（低 / 中 / 高）
• 评分明细 — 运行时、框架、依赖项、生命周期结束（EOL）
• 各项目详情，涵盖 Node.js/TypeScript、.NET、Python 和 Java
• 按可能影响程度排序的可执行发现
• SBOM 导出（CycloneDX / SPDX）
• 已知漏洞（使用 --vulns 启用）— 严重程度、CVSS、修复版本、咨询数据中已有的 EPSS；如果位于 git 仓库中，还会显示引入漏洞的人

---

查找已知漏洞及引入者

vg scan --vulns 会根据公开的 OSV 数据库检查已安装的依赖，并以文本、JSON 或 SARIF 格式报告每个已知漏洞及其严重程度、CVSS 评分和修复该漏洞的版本。若公告数据中已有 epss、epssPercentile 和 kev，JSON 也会包含这些字段；缺失的评分会被省略，绝不会写成 0。添加 --package-manifest，即可从本地公告包完全离线运行。离线扫描和清单扫描不会联系 EPSS 服务。在 npm、pnpm 和 yarn 项目中，它还会检查依赖拉取的包，这些包从锁文件中读取，并会列出每个包的路径。清单缺失或无效时，程序会以状态码 1 退出，且不会执行扫描。清单格式和错误文本见 DOCS.md。

SARIF 会为每个包和公告写入一条结果（vg scan --vulns --format sarif）。每条结果都包含 partialFingerprints["vg/finding-id/v1"]，因此未发生变化的发现会保留相同的代码扫描提醒。公告自身的 ID 是主 ID。CVE 和其他别名会保留在该结果中。如果扫描保留了两个公告 ID，则预计会出现第二条代码扫描提醒，包括这两个 ID 互相列为别名的情况。字段布局、结果顺序以及指纹的组成方式，见 DOCS.md 和 DOCS.md。

JSON（vg scan --vulns --format json 和 .vibgrate/scan_result.json）会在多个 ID 互为别名时，为每个包和版本写入一条发现，包括通过第三个 ID 关联的情况。如果关联的 ID 中包含 CVE，发现 ID 就是其中最小的 CVE；如果没有，则使用最小的公告 ID。只有一个公告时，会保留其自身 ID。aliases 会按顺序列出其他 ID。--offline --package-manifest 采用相同的分组方式。ID 规则见 DOCS.md。

vg scan --vulns                 # drift score + known vulnerabilities
vg scan --full                  # drift + vulnerabilities + a banned-dependency report

在 Git 仓库中，每条发现都会根据历史记录追溯归因：是谁、在哪个提交中引入了易受攻击的版本，以及你已暴露多长时间。这些暴露时长会汇总为各严重程度的暴露时间和 SLA 违约指标，并以 欧盟《网络韧性法案》（CRA） 为参照——“我们修复得够快吗？”现在有了量化结果。

这回答的是关于当前检出代码的问题。要回答监管机构关心的问题——哪些已交付产品包含该漏洞——请参阅下文的 Vibgrate Evidence——回答哪些已交付产品包含该漏洞。

vg why lodash                   # who added a dependency, every version since, and any open vulnerabilities
vg bisect lodash 4.17.21        # the commit where lodash crossed a version line (e.g. reached the fix)

检测和归因覆盖整个 npm 生态系统（npm、pnpm、yarn），以及 pip/poetry、cargo、composer、bundler、pub、hex、NuGet 和 Maven/Gradle——数据从各项目的锁文件中读取，因此无论你构建什么，都能正常工作。Go 则根据 go.mod 中直接的 require 行匹配。伪版本和 +incompatible 标签的比较方式见 DOCS.md。

你的 AI 助手也能获取这些信息：vg serve 提供 list_vulnerabilities、vuln_attribution 和 upgrade_impact 工具，告知 Agent 升级的代价——版本差距、有多少文件导入了该包、升级能修复哪些漏洞，以及（在线且选择启用时）当前版本与最新版本之间的破坏性变更说明。

---

Vibgrate Evidence — 回答“哪些已发布产品包含此内容？”

扫描器会告诉你眼前代码的情况。监管机构问的是你已发布的代码——十八个月前以 3.2.1 版本发布到德国和法国、目前仍在支持期内的代码。Vibgrate Evidence 会将答案作为签名制品提供，第三方无需账户和网络连接即可离线验证。

它提供的是证据，而非结论。它不会告诉你是否合规，也不构成法律建议。它会给出站得住脚、可复现的答案及其背后的审计跟踪记录；如何判定和提交由你负责。

vg evidence init --regime cra                       # who files, and to which coordinator
vg evidence product add "Acme Gateway" --markets DE,FR --in-scope
vg evidence release acme-gateway 3.2.1 --from sbom.cdx.json --ship-date 2025-02-14
vg evidence exposure CVE-2025-12345 --bundle ./ev   # signed answer, exit code for CI

为什么要冻结清单，而不是重新扫描？

• 已发布的版本不可变，你的代码树却不是。 exposure 会根据发布时冻结的清单进行匹配，而不是 HEAD。今天重新扫描只能告诉你现在会发布什么，这不是问题所问的内容。
• 它不会妄加推断。 如果产品关联的发布版本没有冻结清单，结果会是 undetermined，并附上原因，绝不会给出看似确定的 not affected。这一区别正是该制品的全部价值所在。
• 设计上不绑定司法管辖区。 报告义务以制度建模：欧盟 CRA（--regime cra，自 2026 年 9 月 11 日起适用）和 DORA 事件报告（--regime dora-incident）现已提供。新增司法管辖区只需添加制度配置档案，不需要新命令或新工具。
• 没有模型会参与生成任何数据。 证据流程中的内容都不是由语言模型生成的。每个数字都根据冻结的清单和公告数据计算得出。
• 全程离线。 使用 --offline 和本地公告文件无需联网；vg evidence verify 也能在从未听说过 Vibgrate 的机器上运行。

**取舍：**答案的质量取决于你冻结的清单。证据无法还原你开始记录之前发布的内容——从未冻结清单的发布版本将永久保持 undetermined。从开始记录的那一天起，价值便会逐渐累积，这就是现在开始，而不是等到九月的理由。

生命周期

步骤	命令	功能
1. 设置	vg evidence init	组织、协调 CSIRT，以及拥有提交权限的人员
2. 注册	vg evidence product add	注册一个包含数字元素的产品——市场、分类和范围理由
3. 冻结	vg evidence release	将已发布版本固定到不可变的组件清单，可来源于 SBOM、扫描结果或 BuildKit 的构建结果
4. 查询	vg evidence exposure <vuln>	查询哪些已发布产品包含该漏洞、对应的版本、所涉市场，以及是否仍在支持期内
5. 验证	vg evidence verify <bundle>	在任意机器上离线重新验证签名答案

此外，vg evidence readiness 会根据制度义务生成确定性的差距报告，vg evidence regimes 会列出各项制度及其时限，vg evidence drill 会针对模拟公告进行限时演练，vg evidence watch 会将 CISA KEV 目录与冻结清单关联，vg evidence pack 会生成由人工粘贴到报告平台的提交包，而 vg evidence export 会导出包含所有内容的隔离网络环境数据包。DOCS.md 介绍了 regimes、readiness 和 drill 会读取哪些内容，以及如何在上传前完成本地试运行。

从构建生成的内容冻结容器发布版本

如果交付产物是容器镜像，构建过程已经生成了清单所需的信息。vg evidence release 可以直接读取这些信息，无需手动输入：

docker buildx build --push --provenance=true --sbom=true --metadata-file build.json -t ghcr.io/acme/gateway:3.2.1 .
vg evidence release acme-gateway 3.2.1 --image ghcr.io/acme/gateway:3.2.1 --ship-date 2025-02-14

通过 --from 传入或附加到镜像的 SBOM 必须是有效的 CycloneDX 或 SPDX JSON。文件遭到截断、不是 JSON，或缺少必需字段时，命令会以状态码 1 退出。错误消息会指出文件名和预期格式，并提示重新生成 SBOM，但不会包含文档内容。组件或软件包缺少 name 时，命令会报错，而不是将其丢弃。

--image <ref> 会从 Docker 获取镜像摘要、org.opencontainers.image.* 标签，以及附加到镜像的来源证明和 SBOM 证明；附加的 SBOM 将成为清单。它会运行 docker image inspect 和 docker buildx imagetools inspect；如果引用的镜像不在本地，第二个命令会联系镜像仓库。没有守护进程时，可通过文件传入相同的信息：用 --buildkit-metadata build.json 提供摘要和构建引用，用 --provenance <file> 提供 SLSA 证明（源代码仓库、提交、基础镜像），再用 --from <file> 提供 CycloneDX 或 SPDX SBOM（可以是原始 SBOM，也可以是证明）。结果会记录在冻结清单的 build 下。若 --digest 与构建信息相矛盾，命令会报错；证明签名会记录为未验证——vg 没有镜像仓库信任根，因此请使用 cosign 验证。

包中包含什么，以及“已验证”的含义

--bundle <dir> 会写入 result.json、一份针对它的 DSSE/Ed25519 in-toto 证明（evidence.intoto.jsonl）、第三方可照着操作的 VERIFY.md，以及在指定 --tsa <url> 时生成的 RFC 3161 可信时间戳令牌（timestamp.tsr）。

vg evidence verify 会如实报告以下三种状态之一，其中中间状态尤其重要：

状态	含义
verified	签名检查通过，签名者已固定到你通过 --pub 提供的信任根，并且结果摘要仍然匹配
unverified	在加密验证上完整且未被篡改，但签名者尚未固定——它确实存在，只是你还未信任它
failed	签名无效，或 result.json 已与签名内容不匹配

遭到截断、无效或无法读取的包不属于上述任何一种状态。vg evidence verify 会以状态码 1 退出，并提示你恢复该包，或使用 vg evidence exposure --bundle 重新创建。错误消息不会包含文件内容。

退出代码可用作 CI 门禁：0 未发现暴露 · 2 发现暴露 · 3 无法判定，需要人工审核 · 1 操作错误。

证据状态存储在 .vibgrate/evidence/ 中。首次使用时会在 .vibgrate/attest-key.pem 生成 Ed25519 签名密钥（权限模式为 0600，旁边还会生成 .pub 文件），除非你通过 VG_ATTEST_KEY 指定自己的密钥——请备份它，切勿提交。

---

跟踪长期变化 → 创建免费工作区

CLI 完全支持离线使用。如果你想要跨运行和仓库查看趋势，让变化成为可管理的指标，而不是意外发现的问题，可以将扫描结果推送到 Vibgrate Cloud 工作区：

1. 在 dash.vibgrate.com 创建工作区，并复制你的 DSN。
2. 连接并推送：

VIBGRATE_DSN="vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>" \
  vg scan --push

上传是可选的——只有运行 --push 时，数据才会离开你的计算机。请将 DSN 存储为 CI 机密，切勿提交。

→ 创建工作区

---

CI 集成

_{java-spring/budget — 将 vg scan --drift-budget 60 用作 CI 门禁（此录制的运行结果为 0）。在线模拟器。}

在 GitHub 上最快的启动方式只需一条命令。它会写入 .github/workflows/vibgrate.yml，使用 vibgrate/cli Action 扫描每个拉取请求，并将 SARIF 上传到 GitHub Security。无需 Vibgrate 帐户：

vg init --ci github

想自己编写？相同的工作流只需一个 vibgrate/cli Action 步骤：

- uses: actions/checkout@v4
- uses: vibgrate/cli@v1
  with:
    upload-sarif: true
    max-score: 40 # optional: fail the job when DriftScore is above 40

将 vg 加入任意流水线，即可把漂移评分变成质量门禁：

# GitHub Actions — drift gate + SARIF upload
- name: Vibgrate scan
  env:
    VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
  run: npx @vibgrate/cli scan --push --format sarif --out vibgrate.sarif --fail-on error

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: vibgrate.sarif

根据漂移预算和相对于基线的回归设置门禁：

vg baseline
vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5
vg scan --vulns --fail-on-epss 0.1

• --drift-budget <score>：如果漂移超过预算，则构建失败。
• --drift-worsening <percent>：如果相较基线，漂移恶化超过 X%，则构建失败。
• --fail-on-epss <threshold>：如果任何公告的 EPSS 分数达到或超过阈值，则构建失败。该分数是 0 到 1 之间的概率。分数等于阈值时也会失败。缺失的分数不会进行比较，也不会视为 0。此标志会替代 .vibgrate/config.yml 或 vibgrate.config.json 中的 failOnEpss。它会读取 vg scan --vulns 或 vg scan --full 中的公告。参见 DOCS.md。
• --summary-out <file>：写入一份简短的 JSON 摘要（包含 driftScore、riskLevel、相较 --baseline 的变化，以及 driftBudget 判定），供 CI 步骤读取，即使门禁导致运行失败也不例外。未设置预算时，driftBudget 为 null。--drift-budget 和 --drift-worsening 会以 flags 作为 source 记录。未测量的分数为 null，绝不会是 0。完整产物包含相同的 drift.* 字段以及各组件的分数：参见 DOCS.md。
• --junit <file>：在 --format（JSON 或 SARIF）之外，写入一份确定性的 JUnit XML 摘要，包含发现项和这些门禁。退出代码保持不变；参见 DOCS.md。

vg scan --format sarif --out vibgrate.sarif --junit vibgrate.junit.xml --fail-on error --drift-budget 40

• 使用 --baseline 执行扫描时，还会记录快照中已存在的发现项（规则、位置和 ID）。文本报告会显示数量，SARIF 会将相同的 ID 列为抑制项，这些发现项仍会保留在报告中。

可直接复制粘贴的 CI 模板位于 examples/github-actions/。作业何时失败、警告模式如何保持绿色、应固定哪些版本，以及如何填充 DriftScore 徽章：参见 examples/github-actions/README.md。Azure DevOps 和 GitLab CI 代码片段见 DOCS.md。

---

与版本对应的库文档

vg lib <pkg> 会打印某个库的用法文档。如果项目根目录中的锁定文件列出了该软件包，版本标签就会显示锁定的版本。会读取哪些文件，以及缺少锁定版本、安装版本不符或目录获取失败时会发生什么：参见 DOCS.md。

vg lib react

通过 MCP 连接的 AI 助手在回答有关项目中库 API 的问题时，会自动使用 vg lib。

---

SBOM 和 OpenVEX

_{strapi/sbom — vg sbom export --format cyclonedx --out sbom.cdx.json。这是一份清单，不是合规性判定。在线模拟器。}

vg sbom export --format cyclonedx --out sbom.cdx.json
vg sbom export --format spdx     --out sbom.spdx.json
vg sbom delta  --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out delta.txt
vg vex                          # generate an OpenVEX document for attestation

vg sbom export 会生成一份清单，而非合规性判定。CycloneDX 中，元数据组件的 type 为 application，每个依赖项（包括容器镜像）的 type 均为 library。SPDX 不包含 primaryPackagePurpose。映射关系、缺失项（OS 软件包、镜像内容、Terraform 资源）和简短的样例示例见 DOCS.md。

每个组件上的 vibgrate:scope 为 direct 或 transitive。开发依赖会将 CycloneDX 组件的 scope 设为 excluded，并生成 SPDX DEV_DEPENDENCY_OF 关系。可选依赖会将 scope 设为 optional，并生成 OPTIONAL_DEPENDENCY_OF。映射关系（包括导出时省略的字段）见依赖范围。

请通过软件包 URL 匹配组件（CycloneDX 中为 purl，SPDX 中为 purl 外部引用 purl）。扫描 JSON 使用相同的坐标（projects[].type、dependencies[].package、resolvedVersion 和 extended.vulnerabilities.packages[]），不会重复包含 purl 字符串。这些文件没有 CPE 字段。CLI 不会凭空生成 CPE，其他目录工具提供的 CPE 也不能替代 purl。字段和本地示例见：DOCS.md。

当锁文件记录了软件包摘要时，CycloneDX hashes 和 SPDX checksums 会先按算法名称、再按摘要值排序列出这些摘要。没有记录摘要的软件包会省略该数组。扫描依赖项没有摘要字段。serialNumber、documentNamespace、projectId 和 solutionId 都是标识符。字段和本地示例见：DOCS.md。

--format 可设为 cyclonedx（默认值）或 spdx。同一扫描在这两种文件中的差异——purl 的位置、依赖关系图、许可证、工具元数据和文档 ID——见选择 CycloneDX 还是 SPDX。

审查变更

Vibgrate Review 会根据声明的架构和安全控制策略审查当前变更。它报告的是变更完整性，而非安全性证明。

_{dotnet-clean-arch/review — 在 Clean Architecture 样例上运行 vg review。在线模拟器。}

vg review
vg review findings-from-diff --base origin/main --format json
vg review propose blast:<node_id> --model forge --json
vg review propose arch:<rule>:<path> --model forge --json --findings findings.json

vg review findings-from-diff 会输出确定性的 vg.review.findings.v1 文档（爆炸半径和架构策略 correctness 条目，以及安全扫描器结果），并写入 .vibgrate/review-propose-handoff.json。 JSON 字段列表、每个 kind、排序规则、捕获的示例和失败时的退出状态见 DOCS.md。 vg review propose <id> 会附加 PatchIR 空运行——--model 可设为 relay:<slug>（托管 Review）或 spark | flow | forge（本地 Code Mode）。 查找顺序为当前变更集、--findings JSON，然后是上次运行的 交接文件；如果要明确指定该变更集，请将与 findings-from-diff 相同的 --base / --in-place / --diff 传入。除非在主题分支上同时传入 --apply --yes，否则不会写入任何内容。

---

隐私与离线优先

• 除非你运行 --push / vg push / vg share，否则不会有数据离开你的设备。
• 漂移评分只读取清单和配置。代码图（vg build/vg map）以及少数扩展扫描器（代码质量、数据库架构、UI 文本）会在本地读取源代码，以计算结构事实和指标——绝不会读取原始代码行，也绝不会原样上传；各扫描器具体读取的内容请参阅 DOCS.md。
• 无需登录，也不依赖任何 SaaS。
• --offline 不会联系软件包注册表，也不会上传结果。--package-manifest <file> 会从本地 JSON 或 ZIP 清单为漂移评分提供数据，并在使用 --vulns 时提供已知漏洞数据。清单缺失或无效时会以 1 退出。同一棵目录树和同一份清单会保持发现结果顺序和公告 ID 不变。请参阅 DOCS.md。
• --max-privacy 会抑制本地制品写入和高上下文扫描器；--no-local-artifacts 会跳过将 .vibgrate/*.json 写入磁盘。
• vg code --local 会将模型推理保留在设备上：使用本地模型和本地图，不进行托管调用，也不获取模型目录。Agent 自带的 Web 工具仍可用，并且与所有网络步骤一样，运行前都需获得你的批准。
• vg code 绝不会将机密文件读入提示词，并会对读取文件中的凭据格式进行脱敏。
• vg evidence 在本地运行：使用本地公告文件时，--offline 无需联网；vg evidence verify 可在没有账户且没有网络连接的机器上验证捆绑包。只有运行 vg evidence push 后，内容才会发送至 Vibgrate Cloud。vg evidence regimes、vg evidence readiness 和 vg evidence drill 也都在本地执行——配置文件随 CLI 一同提供，差距报告和演练内容则保存在 .vibgrate/evidence/ 中。试运行流程见 DOCS.md。

vg scan --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json

将 .vibgrate/ 添加到 .gitignore 中——这些是重新生成的本地输出。

了解 Vibgrate 如何处理代码和数据：vibgrate.com/security，以及子处理方登记表。

---

使用 AI 助手快速开始

将以下内容粘贴到你的 AI 编码工具中（Claude、Cursor、Copilot、Gemini CLI，等等）：

Set up Vibgrate for local codebase intelligence:
1. Install: npm install -g @vibgrate/cli@latest
2. Build the graph: vg build
3. Wire your assistant: vg install
4. Ask: vg ask "what are the main entry points?"
Then explain the architecture and my top 3 upgrade priorities.

完整提示词请参阅 docs/QUICKSTART-PROMPT.md。

---

命令参考

每组命令均按 A–Z 顺序列出。在适用时，会标出简短的典型流程（常用顺序）。

代码图

典型流程： vg build → vg status → vg ask → vg impact → vg share

vg ask 根据本地图回答问题。问题和代码都会留在这台机器上。--offline 会跳过可选的模块获取以及此进程对嵌入模型的下载。请参阅哪些内容保留在本地／何时使用网络。

命令	说明
vg ask "<question>"	使用自然语言查询地图
vg build [path]	构建／更新代码地图（增量、确定性）。--attest 为该地图签名；--verify 根据磁盘上的地图检查签名。标志、密钥和失败文本见 DOCS.md。--policy hexagonal-v1|layered-v1|vertical-v1 选择架构模块评估的边界规则（默认值来自 .vibgrate/architecture.toml，该文件也可以包含你自己的 [[overlay]] 规则）；--init-policy 根据构建时的分类结果写入该文件的初稿（策略包和叠加规则详见 docs/architecture-policies.md）
vg bundle	构建可在隔离环境中使用的捆绑包（语法库 + 图 + 库目录）
vg code ["<instruction>"]	以图为依据的编码 Agent——使用本地或托管模型，每项编辑和命令都需批准（CI 使用 --auto，一次性差异使用 --single）
vg embed	预计算语义索引，以便即时运行 vg ask
vg export	导出地图（json / ndjson / graphml / dot / cypher / md / html / SBOM）
vg facts <file>	获取节点的确定性事实（契约、不变量）
vg guide <file>	获取节点相关的标准／实践（免费策略包）
vg impact <file>	更改后会导致哪些内容出问题，以及要运行哪些测试
vg install / vg uninstall	在你的 AI 助手中接入（或移除）Vibgrate AI Context + 技能（--detect、--all、--list）
vg lib <package>	获取版本准确、标注偏差的库文档
vg locale	管理应用的翻译——在 Vibgrate Cloud 中管理区域设置项目、键和翻译（push / pull / status；vg localize 是别名）
vg map / vg hubs / vg areas / vg oddities	地图洞察：概览、依赖最多的代码、自然分组、跨区域异味
vg models	代码模式（Spark / Flow / Forge）+ 本地模型集群（Ollama / LM Studio / gguf）；默认执行 install / pull（使用 --dry-run 预览）
vg module	管理可选的本地模块（relevance、hcs）：status、install、remove
vg path <from> <to>	查看 A 如何连接到 B（最短路径）；--diagram 将其绘制为固定的调用路径
vg show flow <entry>	以固定流程图逐步展示函数的作用
vg show scratchpad	解释暂存区：通过 --keep 或由 Agent 留存的解释，最新内容显示在顶部
vg savings	本地报告节省的令牌数／费用——针对地图查询的 grep 基准，以及按窗口、模型和客户端统计的上下文压缩量（估算值）
vg watch	文件更改时重新构建地图
vg serve	启动 Vibgrate AI Context（本地优先的 MCP：代码地图 + 偏差 + 版本准确的文档）
vg share	使图可提交并为团队自动更新
vg show <file>	解释一个节点：它是什么、它调用什么、什么会调用它
vg show arch	打开本地架构地图：先显示工作区包，再显示列切片（UI → 服务 → 存储）。回环；--focus <symbol>、--no-open
vg status	缓存／新鲜度、计数、过时情况
vg tests <file>	查看覆盖某个节点的测试
vg tree <file>	以某个节点为根的调用树
vg unknowns	查看图无法解析的内容，并按影响范围排序

没有 vg attest-actions 命令。vg attest 和 vg verify 是已弃用的名称，分别对应 vg build --attest 和 vg build --verify。

vg build --attest 会将 DSSE in-toto 语句写入 .vibgrate/attestation.intoto.jsonl（使用 --attestation <file> 覆盖）。密钥由 --attest-key <path> 指定，否则使用 VG_ATTEST_KEY，再否则使用 .vibgrate/attest-key.pem。首次运行且默认路径下没有密钥时，会生成一个 Ed25519 密钥（模式为 0600，并在旁边生成 .pub 文件），并提示你妥善保管该密钥并将其加入 gitignore。你指定的路径若不存在，会导致用法错误。非 Ed25519 密钥会被拒绝。请提交证明文件，不要提交私钥。 vg build --verify 会根据磁盘上已有的映射检查该文件。它不会为了检查签名而重新构建，也不会替换映射。同一命令还会在内存中重建映射，以确认构建具有确定性。--pub <path> 用于指定签名者。若不指定，有效签名只能证明文件未被篡改，不能证明你信任签名者。默认路径下缺失的文件会报告为不存在。若指定的证明文件不存在，命令会失败并提示使用 vg build --attest。

签名和检查使用本地加密技术，不会上传任何内容。签名时只会在可用的情况下使用 git 来记录提交。vg build --attest 仍然会执行构建：如果构建不得下载 Architecture 模块或嵌入模型，请传入 --offline 或 --local。完整的输入、输出和每条失败信息：DOCS.md。

vg build --attest
vg build --verify --pub .vibgrate/attest-key.pem.pub

在证明文件生成前，按路径请求该文件会失败。进程会以 3 退出并打印：

error: no attestation at .vibgrate/attestation.intoto.jsonl — sign one with `vg build --attest`

确认路径指向你需要的文件，然后运行 vg build --attest 进行签名。

上下文压缩

压缩不会添加新命令。它是 vg serve 的一种模式、vg install 的一个标志，也是 vg savings 的一个部分。

典型流程： vg install claude --compress → 照常使用 Claude Code → vg savings

命令	说明
vg serve --compress	提供代码映射服务，并压缩上下文：在回环地址上启动兼容 Anthropic 和 OpenAI 的侦听器，供任意 Agent 使用
vg serve --compress --background	将侦听器作为后台进程启动（或复用正在运行的进程）后返回；运行 vg serve stop 可结束它
vg serve --compress <agent>	通过它运行单个 Agent 会话，仅设置环境变量——不会写入任何内容，也不会留下任何痕迹
vg install <agent> --compress	通过写入该 Agent 自身的基础 URL 配置，持久地将其指向此服务（由标记跟踪，可还原），并启动侦听器
vg uninstall <agent>	将该配置逐字节还原，并还原 vg install 写入的所有其他内容
vg install <agent> --learn	将你过去的 Agent 会话转化为其指令文件中的防护规则：重复失败、循环、缺少上下文（使用 --apply 写入）
vg savings	按模型、客户端和项目查看节省的 Token 数和金额：今天 / 7 天 / 30 天
vg savings --benchmark	在内置测试样例上进行离线压缩基准测试：查看每种内容类型的延迟和压缩率
vg show savings	在本地页面中实时查看相同数据，页面位于 vg show arch 旁
vg serve status / vg serve stop	查看正在侦听的服务及其路由到的 Agent；停止后台侦听器
vg serve config	查看每个 VG_* 设置及其值的来源；使用 set / unset 写入 settings.json
vg serve memory	管理跨 Agent 项目记忆：list、search、add、delete、stats、export、import
vg serve compress [file]	手动对文件运行处理管道——这是调试路径，不属于常规用法
vg serve retrieve <hash>	将压缩标记展开为原始内容或其部分片段（--grep、--lines、--head、--tail、--json-path）

整体代码规范（vg hcs）

为 Rust、Ruby、PHP、Dart、Swift、Scala、C++、COBOL 和 VB6 提供确定性的代码事实——每条事实占一行 NDJSON，在任何机器上都可复现，因此事实流可以提交、比较差异并作为 CI 门禁。默认采用增量提取：对已有事实流重新运行时，只需处理增量部分。

所有 HCS 计算都在可选且单独授权的引擎模块中运行，该模块在本地 WASM 沙箱中执行——不会发起网络调用，也不会启动进程。首次使用时会获取该模块，也可提前运行 vg module install hcs 安装。模块不可用时，每条 vg hcs 命令都会以 6 退出——绝不会以 2 退出，因此 CI 门禁不会把“引擎缺失”误认为判定结果。

典型流程： vg hcs extract → vg hcs digest / vg hcs map / vg hcs gate

命令	描述
vg hcs extract [dir]	将事实提取到 NDJSON 流中（默认增量提取；使用 --full 重新提取）
vg hcs digest	将事实流渲染为易读的规范（md / json / html）
vg hcs gate	治理门禁：比较两个事实流，出现重大结构性退化时失败（退出码为 2）
vg hcs map	根据事实流构建系统地图（json / md / mermaid）
vg hcs validate <file>	根据 HCS 规范验证事实流（附录 I 一致性代码）

诊断、IDE 与运行时

典型流程： vg doctor → vg lsp → vg daemon

命令	描述
vg daemon	用于多根图会话的本地工作区守护进程（IDE / Agent）：status、ensure、publish、query、impact、…
vg doctor	只读诊断：配置、凭据（已编辑敏感信息）、地图新鲜度、托管服务可达性、MCP 启动、压缩代理和存储
vg llm-host	隔离的本地推理主机进程（serve、status），用于企业级进程隔离
vg lsp	语言服务（stdio）——为 VS Code 和其他轻量 IDE 客户端提供 Vibgrate 的引擎
vg policy	显示生产环境上下文策略固定项；使用 vg policy verify <file> 验证已签名的学习补丁

漂移评分与供应链

典型流程： vg init → vg scan → vg baseline → vg report → vg fix

命令	描述
vg baseline [path]	创建漂移基线
vg bisect <package> <constraint>	查找依赖跨越版本界限的提交（使用 --assert 为 CI 设置门禁）
vg drift	查看依赖中有哪些过时项（离线运行；使用 --online 获取最新信息）
vg evidence	生成已签名、可复现的法规证据——适用于不限定司法管辖区的监管制度（首先支持 EU CRA，也支持 DORA 事件报告）：init、product、release、exposure、readiness、drill、watch、pack、verify、push、export
vg fix	从托管规划器获取按优先级和风险等级排序的升级计划，然后应用你选择的计划
vg init [path]	初始化配置和 .vibgrate/
vg report	根据扫描产物生成报告
vg review	Vibgrate Review — 在本地审查当前更改的架构和安全控制（--in-place、--local、--loop）。通过 vg review findings-from-diff，从代码图中确定性地找出影响范围；vg review propose <id> 会附加 PatchIR 试运行结果（使用相同的 --base / --in-place / --diff、--findings 或 .vibgrate/review-propose-handoff.json）。在已签名的收据中给出一个决策（pass / needs_review / fail / undetermined）（对收据摘要使用 Ed25519 签名；vg review verify <receipt.json> 可离线验证）；受保护的发现不能被认可为通过。报告更改完整性，但不构成安全性证明。如果代码映射缺失或已过时，则会自行构建或刷新（使用 --no-auto-build 可选择不自动执行）
vg sbom export / delta / vex	导出 CycloneDX/SPDX SBOM、对比两个产物，或生成 OpenVEX 文档
vg scan [path]	扫描升级漂移
vg scan --full	全面扫描：漂移、漏洞和禁用依赖报告
vg scan --push	扫描并将结果推送到 Vibgrate Cloud
vg scan --vulns	同时检测已知漏洞（OSV；通过 --package-manifest 离线运行）
vg update	检查并安装更新
vg why <package>	查看是谁引入了某个依赖、其版本历史以及所有未解决漏洞
vg why <file:line>	查看最后修改某行的提交，以及编写该行的 VG Code 会话（使用 vg review trailer on 选择启用）
vg review trailer push	将提交背后的 VG Code 会话分享至 Vibgrate Cloud，让团队成员可以使用 vg why <file:line> --cloud

工作区身份验证与云端上传

本地评分无需进行身份验证——推送前，任何内容都不会离开你的计算机。

典型流程： vg login → vg dsn create → vg push → vg logout

命令	描述
vg dsn create	生成 DSN 令牌
vg login / vg logout	使用 Vibgrate 工作区对 CLI 进行身份验证（或清除已存储的凭据）
vg push	将扫描结果上传至 Vibgrate Cloud

vg scan [path] [--vulns] [--full] [--format text|json|sarif|md] [--out <file>] [--fail-on warn|error|architecture-finding|architecture-warning] [--fail-on-epss <threshold>] \
  [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy] \
  [--drift-budget <score>] [--drift-worsening <percent>] [--baseline <file>] [--summary-out <file>]

完整的标志和配置参考：DOCS.md · vibgrate.com/cli · 帮助中心 · 术语表。

---

团队为何采用 Vibgrate

大多数系统不会一蹴而就地失效——它们会不断积累升级债务和架构漂移，却未被察觉，直到迁移成本变得高昂。vg 让这类债务变得可衡量、可重复——我们称之为代码漂移智能的实践——并为 AI 助手提供发挥作用所需的本地上下文。了解它如何应用于团队和企业，或将它与您已有的工具进行比较：对比 Renovate · 对比 Dependabot · 对比 Snyk。

模式	可获得的内容	最适合
一次性扫描	快速查看漂移评分、滞后情况和发现项	审计、尽职调查、迁移规划
集成 CI 的扫描	持续漂移信号、SARIF 注释、回归防护	长期控制升级债务
MCP + 图谱	拥有实时、离线代码库上下文的 AI 助手	日常开发、代码审查、重构
VG Code	基于图谱的编码 Agent——可在终端或 VS Code 面板中使用本地模型或 Relay，逐项编辑并受治理	实际修改，而不只是制定计划

建议的推广步骤：立即运行 vg build + vg install，本周将 vg scan 加入 CI，并尝试用 vg code 完成一项小任务。

---

已知限制

• 漂移和风险评分是估算值，根据清单文件、锁文件和公开公告数据计算。它们是优先级信号，而非合规判定或认证。
• VG Code 的质量取决于您选择的模型。 CLI 不附带任何模型。小型本地模型能够很好地处理机械式编辑，但难以应对影响多个部分的设计变更；vg models 会告诉您哪些模型适合这台机器，而不是哪个模型能完成这项工作。任务超出机器能力时，请使用 Relay 或其他托管模型。
• 引导式 vg code 需要终端。 在 CI 中，传入指令并加上 --auto（或 --mock）——不会出现交互式选择器，而且没有该参数时，Agent 会拒绝在无人值守的情况下运行。
• 图谱决定了上限。 解析器无法关联到定义的内容，对 search_code 和 graph_impact 来说都是不可见的。运行 vg unknowns，即可按影响范围查看图谱缺少的内容。
• --auto 是拒绝名单，不是沙箱。 它会阻止已知的灾难性命令，但不会限制 Agent 的活动范围。请在容器中运行不可信指令，或使用 --worktree 和 --security-tier L1。
• --verify 会重新运行您的测试，但不能证明正确性。 测试失败时，会将结果反馈给 Agent 以尝试修复。测试通过，就意味着测试通过。
• 漏洞数据的时效性取决于其来源。 --vulns 会报告扫描时 OSV 已知的信息；离线运行则会报告您提供的软件包中包含的信息。
• Vibgrate Evidence 会生成证据，而非合规判定。 它能帮助您履行某项制度下的义务；但不会判定您是否达标，不会颁发任何认证，也不构成法律意见。申报由您负责。
• Evidence 无法追溯过往情况。 暴露情况依据发布时冻结的清单文件确定。未曾冻结的版本将始终为 undetermined——事后无法重建。
• vg evidence watch 会显示 KEV 列表，而非作出判定。 就申报而言，漏洞是否属于“正在遭受主动利用”，由您判断，而非由工具判断。
• vg evidence verify 不会重新验证 TSA 证书链。 它会确认 RFC 3161 令牌的印记与 result.json 绑定，并显示可信时间。若要验证完整证书链，请使用 openssl ts -verify -in timestamp.tsr -data result.json -CAfile <tsa-ca.pem>。

---

要求

• Node.js 22+
• macOS、Linux、Windows
• VG Code 还需要一个模型：本地运行时（Code Mode 包、Ollama、LM Studio，或磁盘上的 GGUF）、Vibgrate Relay 令牌，或其他托管服务提供商的 API 密钥。运行 vg models 查看哪些选项适用于这台机器。

命令名称冲突

vg 很短，偶尔会与其他工具冲突（virtualgo、vugu、oh-my-zsh 的 git verify-commit 别名、自定义 shell 别名等）。

vibgrate 是完全相同的别名——使用相同的二进制文件、标志和行为。如果你的系统上 vg 已被占用，请在所有地方改用 vibgrate：

vibgrate scan          # same as: vg scan
vibgrate build         # same as: vg build
vibgrate serve         # same as: vg serve

安装 @vibgrate/cli 时，它会无条件注册两个可执行文件入口。如果安装时检测到 vg 已被其他工具占用，它会打印一行提示，建议你使用 vibgrate。

---

Vibgrate 的其他产品

Vibgrate CLI	本软件包 — 扫描、评分并绘制任意代码仓库的映射。在线演示 · 基准测试 · Token 节省量
Vibgrate for VS Code	在编辑器中查看相同的评分，另有 VG Code 面板 — vg code 的图形界面，运行的正是这个 Agent。Marketplace · Open VSX
Vibgrate Relay	通过一个 Vibgrate 账号为 VG Code 提供托管模型 — 无需各提供商的 API 密钥，按 Token 预付额度，本地模型仍可用于离线场景
Vibgrate Graph	vg map、vg impact 和 vg show 背后的确定性本地代码映射
Vibgrate AI Context	vg serve — 提供版本准确的库文档、代码映射和离线漂移信息，供任何助手使用。支持的助手 · 在 mcp.so 上查看
Vibgrate Cloud MCP	基于工作区数据的托管 MCP 服务（OAuth 2.1）
Vibgrate Cloud	历史记录、趋势和团队汇总。创建工作区 · 定价
Vibgrate Review	vg review — 此次更改是否让系统更贴近其声明的架构，还是削弱了安全控制？基于代码映射在本地运行；推送的是审查凭证，而非代码仓库
Vibgrate Evidence	vg evidence — 冻结已发布的版本，然后以可离线验证的签名证据回答“哪些已发布产品包含此漏洞？”。适用于不依赖司法管辖区的监管制度，首先支持 EU CRA

评分机制：DriftScore · RiskScore · DriftRisk Index · 已发布的方法论 · 真实扫描的公开索引 · README 徽章

参考：软件包注册表 · 集成市场 · 术语表 · 帮助中心 · 安全 · 使命

免费创建工作区 →  ·  体验在线演示  ·  VG Code  ·  Evidence  ·  完整文档

_{采用 Apache-2.0 许可 · 版权所有 © 2026 Vibgrate}