VibeDrift/VibeDrift

VibeDrift 专门检测 AI 生成代码中的偏移（drift）：即新代码偏离代码库其余部分已遵循模式的情况。它在本地运行，根据代码库自身的约定对仓库进行评分，并精准指出存在问题的代码文件。你的代码永远不会离开你的本地计算机。 保持代码一致性的最快方法是在 Agent 编写代码的*同时*检查偏移。[MCP server](#mcp-server) 让 Claude Code 和 Cursor 能够实时、循环地访问你仓库的约定，从而确保新代码在首次编写时就能保持匹配。 ## 快速开始 ``` npx @vibedrift/cli ``` 就这么简单。无需安装，无需注册。它会扫描当前目录并打开一个交互式 HTML 报告。 如果你愿意，也可以全局安装： ``` npm i -g @vibedrift/cli vibedrift # scan ./ vibedrift ./path/to/project # scan a specific path ``` ## 支持的语言 JavaScript, TypeScript, Python, Go, Rust。 ## 检测内容 - 架构不一致（例如：一半的 handler 使用了 repository 模式，而另一半直接执行了原生 SQL） - 隐性重复：两个功能相似但名称不同的函数 - 命名、导入、错误处理、异步风格和日志记录方面的约定偏移 - 安全漏洞：硬编码的密钥、注入风险、未经过滤的输入 - 死代码、复杂度热点，以及未完成或占位的实现 VibeDrift 会学习你代码库的主导模式，并标记出偏离该模式的代码。请参阅[评分指南](https://vibedrift.ai/guide)了解检测结果是如何汇总为分数的。 ## 命令 ``` vibedrift [path] Scan a project (default command) vibedrift watch [path] Re-scan on file changes (requires login) vibedrift mcp Run the MCP server (Claude Code / Cursor) vibedrift login / logout Account auth vibedrift status Account, plan, and token vibedrift hook Install or remove a git pre-push drift gate vibedrift doctor Diagnose install, auth, and API vibedrift update Update to the latest version ``` 常用扫描选项： ``` --format output format (html is the default) --fail-on-score exit 1 if the score is below n (CI gate) --diff [ref] scan only files changed in git (vs HEAD, or vs a ref/branch) --deep AI-powered deep analysis (requires login) --include / --exclude filter the files scanned (repeatable) --write-context write committable .vibedrift/ context files --local-only skip every network call (fully offline) ``` 运行 `vibedrift --help` 获取完整列表。 ## 深度扫描 `vibedrift --deep` 增加了本地静态检查无法实现的云端分析功能：语义重复检测、名称与行为意图校验，以及生成综合性一致性报告。你可以使用 `--diff` 将其范围限定在你的改动集内： ``` vibedrift login vibedrift . --deep # full-repo deep scan vibedrift . --deep --diff # deep-scan only what you changed (fast pre-PR check) vibedrift . --deep --diff main # deep-scan everything that differs from a branch ``` 深度扫描仅发送代码片段（绝不包含完整文件或文件路径），并且在内存中处理且不予存储。它需要一个免费账号。请访问 [vibedrift.ai](https://vibedrift.ai) 了解深度扫描包含的具体内容。 ## MCP server VibeDrift 内置了 MCP server，让 AI 编码 Agent 在编写代码时能够参考你仓库自身的约定，从而将偏移检测转化为偏移预防。它暴露了五个工具： - `get_intent_hints` 读取你的 `CLAUDE.md` / `AGENTS.md` / `.cursorrules` 中声明的约定 - `get_dominant_pattern` 返回仓库在某个维度上的主流模式，并提供可供参考的示例 - `check_file_drift` 检查文件是否符合仓库的模式 - `find_similar_function` 查找现有的近似重复代码，以便 Agent 复用而非重写 - `validate_change` 检查拟定的新函数是否会引入偏移或导致代码重复 这些工具在你的本地计算机上运行，不发送任何代码，也无需登录。它们会在首次使用时自动构建仓库的基准线。 ### 在任何 MCP client 中安装 VibeDrift 是一个标准的 [MCP](https://modelcontextprotocol.io) server，通过 stdio 使用 `npx -y @vibedrift/cli mcp` 启动。 **Claude Code**（会自动为你写入配置）： ``` claude mcp add vibedrift -- npx -y @vibedrift/cli mcp ``` **Cursor, Claude Desktop, Windsurf, Cline, VS Code, Zed 及其他工具** 在其 MCP 配置中使用相同的命令： ``` { "mcpServers": { "vibedrift": { "command": "npx", "args": ["-y", "@vibedrift/cli", "mcp"] } } } ``` 如果工具返回 `no_baseline`，请在该仓库中运行一次 `vibedrift` 以构建基准线。 ### 不使用 MCP 对于不支持 MCP 的 Agent，同样的五个工具也可以作为普通的导入包或基于同一引擎的 Agent Skill 使用： - **导入：** `import { validateChange, findSimilarFunction } from "@vibedrift/cli/tools"`（参见 [docs/tools-api.md](./docs/tools-api.md)） - **Agent Skill：** 位于 [`skills/vibedrift/`](./skills/vibedrift/SKILL.md) 的独立技能包 ## CI 集成 GitHub Action 会在 Pull Request 上运行 VibeDrift，发布分数差异评论，并可以使检查失败： ``` # .github/workflows/vibedrift.yml name: VibeDrift on: [pull_request] permissions: pull-requests: write jobs: drift-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: skhan75/vibedrift-actions@v1 with: fail-on-score: 70 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` 请查看 [Action 仓库](https://github.com/skhan75/vibedrift-actions) 获取所有输入和输出信息。 ## 隐私 - **你的代码永远不会离开你的计算机。** 绝不会发送任何源码、文件内容或文件路径。 - **匿名扫描信标，默认对所有人开启。** 每次扫描后，VibeDrift 会发送一个微小的匿名信标：包括语言、文件数量、代码行数、扫描时间、CLI 版本、检测结果数量以及分数。不包含任何代码、路径或标识符。可以通过 `vibedrift telemetry disable`、`VIBEDRIFT_TELEMETRY_DISABLED=1` 或 `--local-only` 关闭此功能。 - **更新检查。** 每天一次，扫描时会检查 npm registry 是否有更新的版本（已缓存，静默失败，在 `--local-only` 下跳过）。 - **`--local-only`** 会跳过所有的网络请求，即使在已登录的情况下也是如此。 - 认证状态保存在 `~/.vibedrift/config.json`（权限为 0600）；扫描历史记录保存在 `~/.vibedrift/scans/`，绝对不会出现在你的项目目录树中。 ### 环境变量 | 变量 | 用途 | |---|---| | `VIBEDRIFT_TOKEN` | 用于 CI 或非交互环境的 Bearer token | | `VIBEDRIFT_API_URL` | 覆盖默认的 API 基础 URL | | `VIBEDRIFT_TELEMETRY_DISABLED` | 设置为 `1` 可关闭信标和更新检查 | ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。CLI 完全在你的本地机器上运行；与之通信的可选云端深度扫描服务是一个独立的托管产品。 ## 链接 - **文档与评分指南：** [vibedrift.ai/guide](https://vibedrift.ai/guide) - **网站：** [vibedrift.ai](https://vibedrift.ai) - **问题反馈：** [GitHub Issues](https://github.com/VibeDrift/VibeDrift/issues) - **社区：** [Discord](https://discord.gg/YVcQ65Jt3Q)

标签：AI编程助手, MCP, MITM代理, SOC Prime, 代码一致性检测, 可视化界面, 开发工具, 数据可视化, 日志审计, 暗色界面, 自动化攻击, 逆向工具, 错误基检测, 静态代码分析