VibeGuard
# VibeGuard
<div align="center">
> **「宁可少报,也不把『不知道』说成『没问题』」**
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://nodejs.org)
[](#能力边界)
[](#功能)
<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
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.