Skip to main content
Glama

VibeGuard

「宁可少报,也不把『不知道』说成『没问题』」

License: MIT MCP Node Status Tools

在 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.vue
VibeGuard ❯ 定向回归完成 · 范围 1 个页面 / 3 条验收标准 · 用例 3 个:3 通过 / 0 失败 / 0 错误

(没有注入下游适配器时:)
VibeGuard ❯ 定向回归未执行:未配置测试执行器或无可用范围
            unavailable 表示「没跑」,不是「通过」。

Related MCP server: Change Trace MCP

功能

四个工具,覆盖从需求到回归的完整链路:

工具

触发方式

功能

🧭 clarify

{ requirement }

6 问状态机 + 质量门禁,把模糊需求收窄成结构化 spec.json

🔍 review

{} / { base, staged, scope }

读 git diff,按符号三分类,输出越界告警与受影响页面,写入 changes.json

🎯 test

{}

验收标准 ∪ 受影响页面 → 定向回归范围,关联失败与越界变更,写入 test-results.json

🩺 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.js

macOS / 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.json

clarify

进行中的澄清会话(问题快照、回答、进度)

spec.json

clarify

判定基准:描述、验收标准、影响域

changes.json

review

全量判定、告警、页面影响面(schema v2)

test-results.json

test

测试范围、用例结果、失败关联

pages.json

人工维护

页面入口声明,随 git 提交

状态文件按流水线顺序交接,可进 git、团队共享;并发是 last-write-wins。写入采用原子写(临时文件 + rename),损坏时从 .bak 恢复。

降级链

层

触发

结果

L1

主工具失败或被熔断,切备选

换了工具,结果仍可信

L3

适配成功但契约校验不通过

拿到了结果,但标记低置信

L2

所有候选都失败

没拿到;optional 退回本地能力,required 返回 unavailable

  • 阶段策略: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 序列化

src/index.ts、src/server.ts

clarify

6 问状态机、质量门禁,产出 clarify.json / spec.json

src/clarify/

spec

纯函数 analyze(diff, spec, context?),三分类与双信号

src/spec/

git + scanner

采集 diff;正则扫描 import 并解析别名

src/git/、src/scanner/

review

读 spec / diff / 扫描 / pages,判定并写 changes.json

src/review/

pages

加载 pages.json,文件级反向依赖图 BFS

src/pages/

test

派生范围、调用编排器、归一化、关联失败、写 test-results.json

src/test/

orchestrator

健康观测、路由、三级降级

src/orchestrator/

state

.vibeguard/ 四个状态文件,原子写与 .bak 恢复

src/state/

config

用户级配置与凭据代持

src/config/

决策

结论

理由

状态传递

项目文件而非进程会话

MCP 没有会话概念;文件可持久、可进 git、可团队共享

流水线控制

宿主驱动,VibeGuard 只编排阶段内部

避免隐藏顺序与不可见副作用

判定引擎

纯函数,影响集由调用方注入

不做 I/O,可脱离 git 与文件系统测试

精度取舍

宁可漏报,不可误报

只有双信号同时为真才告警

页面入口

pages.json 配置驱动

项目语义无法可靠推断;文件级 BFS 可解释、可测试

测试执行

DownstreamTool 接缝

不重写测试框架;无适配器时诚实 unavailable


能力边界

以下是设计取舍,不是待办清单:

边界

说明

静态分析是正则启发式

动态 import()、provide/inject、事件总线、自动注册组件、namespace 成员级引用均不可见;方向是宁漏勿误,没告警 ≠ 没问题

test 默认 unavailable

不内置浏览器 / API 执行器;没注入 DownstreamTool 适配器就诚实说没跑

页面入口必须人工声明

不猜目录约定、不解析 Vue Router;配置漂移通过 unresolvedConfigPaths 暴露

affected: [] 有前提

只有 pages.status === "ok" 时才表示没有页面受影响;其余状态是「不知道」

不校验新鲜度

review 之后代码再变,需要重新 review

并发 last-write-wins

按序调用即可

配置是明文 JSON

~/.vibeguard/config.json;PRD 宣称的 AES-256 未实现

没有独立 UI

结果由 MCP Host 渲染;test 的真实执行依赖外部适配器

更多边界与验证现状见 docs/usage.md 与 docs/adr/。


开发

命令

作用

npm run build

tsc → dist/

npm start

node dist/index.js

npm run typecheck

tsc --noEmit

npm test

vitest run

npm run test:watch

vitest

最近一次全量回归:26 个测试文件 / 480 个用例通过(2026-11-15)。这些用例覆盖本地逻辑与桩,不代表真实下游工具集成。


许可证

MIT。详见 LICENSE。

VibeGuard 不替你写代码。它替你看清 AI 改了什么、该测什么、哪里越界。

MIT License

Available Tools

4 tools
clarify需求澄清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

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Local MCP server providing project cognition capabilities for AI coding agents, including context packs, impact analysis, and git diff review through stdio communication.
      10
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      7
      4 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      This 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 npm
      MIT