VibeGuard
Reads git diffs from the target repository to review changes, classify modified symbols, and compute affected pages against the spec.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VibeGuard 给课程列表加关键词搜索,先帮我澄清需求并生成 spec"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
VibeGuard
「宁可少报,也不把『不知道』说成『没问题』」
在 AI 说「改完了」之后,给你一份能检查、能追溯的判定书。
本地运行的 MCP Server。不改代码、不驱动浏览器,只产出并传递判定基准与影响面,让宿主 AI 每一步都有可读、可检查的状态文件。
效果示例 · 功能 · 安装 · 使用 · 工作原理 · 仓库结构 · 能力边界
效果示例
用户 ❯ 给课程列表加关键词搜索
VibeGuard ❯ 需求澄清进行中 · 已答 1/6 · 下一问 2/6:验收标准
(用反引号点名文件或符号,review 才能把它们判成 in-spec)
用户 ❯ 用户在 `CourseSearch.vue` 输入关键词后列表即时过滤
清空输入框后恢复显示全部课程
无匹配结果时显示空状态提示
VibeGuard ❯ 需求澄清完成 · 已写入 spec.json · 3 条验收标准VibeGuard ❯ 已审查 3 个文件(1 个非代码)· 12 条变更 · 1 条越界告警 · 基准 Spec 可用 · 受影响页面 1 个
⚠ src/stores/courseStore.ts · modify `courses`
消费者 UserList.vue 在 Spec 外
→ src/views/UserList.vueVibeGuard ❯ 定向回归完成 · 范围 1 个页面 / 3 条验收标准 · 用例 3 个:3 通过 / 0 失败 / 0 错误
(没有注入下游适配器时:)
VibeGuard ❯ 定向回归未执行:未配置测试执行器或无可用范围
unavailable 表示「没跑」,不是「通过」。Related MCP server: Change Trace MCP
功能
四个工具,覆盖从需求到回归的完整链路:
工具 | 触发方式 | 功能 |
🧭 clarify |
| 6 问状态机 + 质量门禁,把模糊需求收窄成结构化 |
🔍 review |
| 读 git diff,按符号三分类,输出越界告警与受影响页面,写入 |
🎯 test |
| 验收标准 ∪ 受影响页面 → 定向回归范围,关联失败与越界变更,写入 |
🩺 health |
| 状态目录、四个状态文件、凭据配置、下游工具健康一屏可见 |
核心模型:
三分类:
in-spec(命中锚点)/implicit(无法证明越界,不告警)/out-of-spec(未命中锚点 且 影响集含 Spec 外消费者,告警);双信号:语义未命中 + 静态影响面越界,两个信号同时为真才判越界;
页面影响面:
.vibeguard/pages.json声明入口,沿文件级反向依赖图 BFS,输出带最短路径证据的受影响页面。
安装
前提
Node.js >= 20,已安装 git;
被审查的项目必须是 git 仓库;
MCP 进程的 cwd 必须是目标项目根,否则
.vibeguard/会建错位置。
方式一:Claude Code(推荐)
cd <你的项目根>
claude mcp add vibeguard -- node "<vibeguard 路径>/dist/index.js"Claude Code 会继承当前工作目录,.vibeguard/ 落在目标项目根。
方式二:Claude Desktop / Cursor
在客户端配置文件中加入:
{
"mcpServers": {
"vibeguard": {
"command": "node",
"args": ["<vibeguard 路径>/dist/index.js"]
}
}
}Windows(vibeguard.bat):
@echo off
cd /d D:\path\to\your-project
node D:\path\to\vibeguard\dist\index.jsmacOS / Linux(vibeguard.sh):
#!/bin/sh
cd /path/to/your-project
exec node /path/to/vibeguard/dist/index.js方式三:从源码构建
git clone git@github.com:violetGarend/vibeguard.git
cd vibeguard
npm install
npm run build也可以用 npm pack 生成 vibeguard-0.1.0.tgz 分发,对方 npm install -g ./vibeguard-0.1.0.tgz 后直接用 vibeguard 命令。
安装完调用一次 health,确认 stateDir 指向 <项目根>/.vibeguard。
使用
最小调用序列:
clarify { requirement, skipOptional: true } → 回答验收标准 → spec.json
review {} → changes.json
test {} → test-results.json 或 unavailable
health {} → 环境 / 状态 / 下游健康三点语义:
阶段由宿主 AI 按序调用,VibeGuard 不主动推进流水线;
unavailable表示「没跑」,不是「通过」;test-results.json在unavailable时也会写盘,覆盖上一次的通过结果;changes.json是 schema v2;各切片的验收行为见docs/issues/README.md。
先声明页面入口(可选,强烈建议)
在项目根创建 .vibeguard/pages.json:
{
"version": 1,
"pages": [
{
"id": "course-search",
"route": "/courses/search",
"name": "课程搜索页",
"entry": "src/views/CourseSearch.vue",
"dependencies": ["src/composables/useCourseSearch.ts"],
"smoke": true
}
]
}这份配置随项目提交。入口移动或路由改名后要同步更新,否则 unresolvedConfigPaths 会给出漂移提示。
完整用法与排障见 docs/usage.md。
工作原理
三个工具通过项目根 .vibeguard/ 下的文件交接,而不是进程会话:
需求描述
│
clarify ──→ spec.json ───────────────┐
│ │
git diff ──→ review ──→ changes.json ─┼──→ test ──→ test-results.json
↑ ↑ │ ↑
scanner pages.json ─────────────┘ pages.json
引用扫描 页面入口声明文件 | 写入者 | 内容 |
| clarify | 进行中的澄清会话(问题快照、回答、进度) |
| clarify | 判定基准:描述、验收标准、影响域 |
| review | 全量判定、告警、页面影响面(schema v2) |
| test | 测试范围、用例结果、失败关联 |
| 人工维护 | 页面入口声明,随 git 提交 |
状态文件按流水线顺序交接,可进 git、团队共享;并发是 last-write-wins。写入采用原子写(临时文件 + rename),损坏时从 .bak 恢复。
降级链
层 | 触发 | 结果 |
L1 | 主工具失败或被熔断,切备选 | 换了工具,结果仍可信 |
L3 | 适配成功但契约校验不通过 | 拿到了结果,但标记低置信 |
L2 | 所有候选都失败 | 没拿到; |
阶段策略:
clarify/review为optional(有本地兜底),test为required(无本地兜底);当前只有
test调用编排器;clarify/review走本地能力;编排器不驱动 clarify → review → test 流水线,阶段由宿主 AI 按序调用。
仓库结构
vibeguard/
├── src/
│ ├── server.ts ← 浅 MCP 壳:4 个工具注册与 JSON 序列化
│ ├── index.ts ← stdio 入口 + 启动日志
│ ├── clarify/ ← 6 问状态机、质量门禁 → spec.json
│ ├── spec/ ← 纯函数判定引擎:三分类 + 双信号
│ ├── git/ ← diff 采集(spawn git,不经 shell)
│ ├── scanner/ ← 正则 import 扫描 → ImpactIndex
│ ├── pages/ ← pages.json + 文件级反向 BFS
│ ├── review/ ← 判定 + 页面影响面 → changes.json
│ ├── test/ ← 范围派生 + 结果归一化 → test-results.json
│ ├── orchestrator/ ← 健康、路由、三级降级
│ ├── state/ ← 原子写与 .bak 恢复
│ ├── config/ ← 用户级凭据代持(~/.vibeguard/config.json)
│ └── util/ ← 共享原子写
├── tests/ ← 26 个测试文件 / 480 个用例
├── docs/ ← 使用说明、ADR、实现切片、测试与对齐报告
├── vibeguard-implementation-prd.md
└── vibeguard-prd.html模块 | 职责 | 关键文件 |
MCP Shell | 注册 4 个工具,参数解包与 JSON 序列化 |
|
clarify | 6 问状态机、质量门禁,产出 |
|
spec | 纯函数 |
|
git + scanner | 采集 diff;正则扫描 import 并解析别名 |
|
review | 读 spec / diff / 扫描 / pages,判定并写 |
|
pages | 加载 |
|
test | 派生范围、调用编排器、归一化、关联失败、写 |
|
orchestrator | 健康观测、路由、三级降级 |
|
state |
|
|
config | 用户级配置与凭据代持 |
|
决策 | 结论 | 理由 |
状态传递 | 项目文件而非进程会话 | MCP 没有会话概念;文件可持久、可进 git、可团队共享 |
流水线控制 | 宿主驱动,VibeGuard 只编排阶段内部 | 避免隐藏顺序与不可见副作用 |
判定引擎 | 纯函数,影响集由调用方注入 | 不做 I/O,可脱离 git 与文件系统测试 |
精度取舍 | 宁可漏报,不可误报 | 只有双信号同时为真才告警 |
页面入口 |
| 项目语义无法可靠推断;文件级 BFS 可解释、可测试 |
测试执行 |
| 不重写测试框架;无适配器时诚实 |
能力边界
以下是设计取舍,不是待办清单:
边界 | 说明 |
静态分析是正则启发式 | 动态 |
| 不内置浏览器 / API 执行器;没注入 |
页面入口必须人工声明 | 不猜目录约定、不解析 Vue Router;配置漂移通过 |
| 只有 |
不校验新鲜度 | review 之后代码再变,需要重新 review |
并发 last-write-wins | 按序调用即可 |
配置是明文 JSON |
|
没有独立 UI | 结果由 MCP Host 渲染; |
更多边界与验证现状见 docs/usage.md 与 docs/adr/。
开发
命令 | 作用 |
|
|
|
|
|
|
|
|
|
|
最近一次全量回归:26 个测试文件 / 480 个用例通过(2026-11-15)。这些用例覆盖本地逻辑与桩,不代表真实下游工具集成。
许可证
MIT。详见 LICENSE。
VibeGuard 不替你写代码。它替你看清 AI 改了什么、该测什么、哪里越界。
MIT License
Available Tools
4 toolsclarify需求澄清A
需求澄清:把一句模糊的需求逐步收窄成结构化 Spec,写入 spec.json 供 review 当判定基准。**每次调用都会返回当前该回答的问题(currentQuestion)——丢了上下文就空调用一次,它会告诉你现在该答什么。**典型流程:带 requirement 开始 → 带着 answer 与 questionId 逐问作答 → 全部答完后自动跑质量门禁,通过则产出 spec.json;不通过返回 status:"blocked" 与 nextAction,照着重答即可。想最快拿到 Spec:{requirement, skipOptional:true} 跳过可选项,两次调用即可完成。门禁未通过但确实要产出时用 force——它只放宽「验收标准条数」这类质量规则,不放宽「描述为空 / 一条标准都没有」这类结构规则(那是空基准,比没有基准更糟)。注意:.vibeguard/spec.json 不存在时 review 会降级为「无基准」分析(全部 implicit、不告警)。
Inputs: force, answer, restart, questions, +3 more.
healthVibeGuard 健康检查A
报告 MCP 壳、状态仓库、配置与下游工具的健康状态:工具列表、状态目录、状态文件、凭据配置与过期情况,以及编排器看到的下游工具健康(在线 / 降级 / 离线 / 未使用 + 延迟)。
Inputs: no named parameters.
review变更审查A
读取 git diff、扫描引用图并对照 spec.json 判定,输出按变更单元的三分类标注(in-spec / implicit / out-of-spec)与越界的事前警告,同时原子写入 changes.json 供 test 阶段读取。未找到 spec.json 时降级为「无基准」分析(全部 implicit、不告警),并在 notices 中说明。
Inputs: base, scope, staged.
test回归测试A
派生测试范围并执行定向回归,写入 test-results.json。范围 = spec.json 的验收标准 ∪ changes.json 的页面级影响面(读取 .vibeguard/pages.json 声明页面入口);页面映射不完整时只扩大、不缩小(并入全部冒烟页);没有 Spec 时降级为通用冒烟测试。测试失败会沿页面证据链关联相关的 out-of-spec 变更。未配置下游 test 阶段工具时返回 status:"unavailable"(该阶段没有本地兜底),绝不伪装成通过。
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The four tools map cleanly to distinct stages: health is diagnostic, clarify produces a spec, review evaluates a diff against the spec, and test derives and runs targeted regression. There is no meaningful overlap between their purposes, and the workflow ordering is obvious.
All tool names are concise lowercase single words, which is consistent and readable. The only minor deviation is that health is a noun/state check while clarify, review, and test are action verbs.
Four tools is well-scoped for a spec-driven guard workflow: clarify, review, and test form the core pipeline, and health supports diagnostics. Each tool earns its place without obvious redundancy or missing stages.
The surface covers the full clarify → review → test lifecycle plus health, with sensible degradation behavior when no spec exists. Minor gaps remain around explicitly reading generated artifacts (spec.json, changes.json, test-results.json) or initializing/resetting configuration, though agents can likely work around these via the filesystem.
Related MCP Connectors
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for building and testing AI agents with multi-model experimentation and insights.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceLocal MCP server providing project cognition capabilities for AI coding agents, including context packs, impact analysis, and git diff review through stdio communication.103MIT
- AlicenseAqualityDmaintenanceA local-first, model-neutral MCP server for collecting and normalizing change-scoped release evidence. It provides deterministic Git change summaries, evidence collection, and review bundles for agent review.74 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides a local-first MCP server for AI-native software delivery, enabling structured specifications, human approval gates, controlled repository operations, verification evidence, review, and traceability.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceThis MCP server exposes a local structural code graph and project memory so AI coding agents can retrieve focused code entities, relationships, and prior mistakes before reading full files. It enables bounded context queries, caller/callee and impact analysis, and carryover of recorded session information through a CLI, hooks, and an authenticated local dashboard.24 npmMIT