Skip to main content
Glama
README.md
# VibeGuard

<div align="center">

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/Node-%3E%3D20-green)](https://nodejs.org)
[![Status](https://img.shields.io/badge/Status-MVP-orange)](#能力边界)
[![Tools](https://img.shields.io/badge/Tools-clarify%20·%20review%20·%20test%20·%20health-blueviolet)](#功能)

<br>

**在 AI 说「改完了」之后,给你一份能检查、能追溯的判定书。**

<sub>本地运行的 MCP Server。不改代码、不驱动浏览器,只产出并传递判定基准与影响面,让宿主 AI 每一步都有可读、可检查的状态文件。</sub>

<br>

[效果示例](#效果示例) · [功能](#功能) · [安装](#安装) · [使用](#使用) · [工作原理](#工作原理) · [仓库结构](#仓库结构) · [能力边界](#能力边界)

</div>

---

## 效果示例

```
用户      ❯ 给课程列表加关键词搜索

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 表示「没跑」,不是「通过」。
```

---

## 功能

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

| 工具 | 触发方式 | 功能 |
|------|---------|------|
| 🧭 **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(推荐)

```bash
cd <你的项目根>
claude mcp add vibeguard -- node "<vibeguard 路径>/dist/index.js"
```

Claude Code 会继承当前工作目录,`.vibeguard/` 落在目标项目根。

### 方式二:Claude Desktop / Cursor

在客户端配置文件中加入:

```json
{
  "mcpServers": {
    "vibeguard": {
      "command": "node",
      "args": ["<vibeguard 路径>/dist/index.js"]
    }
  }
}
```

<details>
<summary>客户端不固定 cwd?用启动脚本</summary>

Windows(`vibeguard.bat`):

```bat
@echo off
cd /d D:\path\to\your-project
node D:\path\to\vibeguard\dist\index.js
```

macOS / Linux(`vibeguard.sh`):

```sh
#!/bin/sh
cd /path/to/your-project
exec node /path/to/vibeguard/dist/index.js
```

</details>

### 方式三:从源码构建

```bash
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`](docs/issues/README.md)。

### 先声明页面入口(可选,强烈建议)

在项目根创建 `.vibeguard/pages.json`:

```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`](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
```

<details>
<summary>展开查看模块职责与关键设计决策</summary>

| 模块 | 职责 | 关键文件 |
|---|---|---|
| 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` |

</details>

---

## 能力边界

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

| 边界 | 说明 |
|---|---|
| **静态分析是正则启发式** | 动态 `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/usage.md) 与 [`docs/adr/`](docs/adr/README.md)。

---

## 开发

| 命令 | 作用 |
|---|---|
| `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`](LICENSE)。

<div align="center">

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

MIT License

</div>

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.