VibeRaven

快速开始

需要 Node.js 20 或更高版本。在应用的项目根目录中：

npx -y [email protected] check

• 在终端或 CI 中：npx -y [email protected] check
• 用于编码 Agent：npx -y [email protected] --agent-mode
• Windows PowerShell：如果执行策略阻止运行 npx，请使用 npx.cmd。

它会读取 supabase/migrations、客户端和服务端代码、package.json 以及 .env.example。它不会连接你的 Supabase 项目，也不会向你的应用发送请求。发现阻断项时会以状态码 1 退出，因此也可用作 CI 步骤。

检查内容

发现项	缺口 ID	相关的 Supabase Security Advisor lint
在迁移中创建、但从未启用行级安全性的公共表	rls_disabled	rls_disabled_in_public（指南）
使用 using (true)、允许任何人读取或写入所有行的策略	rls_policy_allows_all_write, rls_policy_allows_all_read	无
出现在会发送到浏览器的文件中，或使用 NEXT_PUBLIC_ 名称的 service_role 密钥	service_role_key_in_client_code, service_role_key_in_client_env	无
位于 public 中、没有任何迁移禁止 anon 执行的安全定义函数	security_definer_function_executable	anon_security_definer_function_executable（指南）
无服务器代码使用端口 5432 直接连接 Postgres，而不是使用端口 6543 的事务池化器	pooler_port_mismatch	无
从不检查原始请求体签名的 Stripe webhook 处理程序	unverified_stripe_webhook	无
代码读取但 .env.example 未列出的环境变量、未限制行数的查询、缺少错误监控	env_var_drift, unbounded_query, missing_monitoring	无

同类应用中还经常出现另外两项 Security Advisor lint。VibeRaven 目前还没有对应规则，相关指南说明了修复方法：

• security_definer_view：含义及修复方法
• function_search_path_mutable：含义及修复方法

如需查看针对单个迁移的运行前后对比，请参阅缺少 RLS 的示例。

输出示例

以下结果来自 viberaven check 1.6.12，使用一个每种缺口各有一项的合成 Next.js + Supabase 应用（项目路径已缩短）：

viberaven check · ~/my-app

🔴 No RLS policy proof in migrations  (rls_disabled)
   1 public table without row level security: public.profiles (supabase/migrations/20260301000000_init.sql:1). The Data API does not enforce row restrictions for roles and operations allowed by the table's grants. Verify those grants to determine who can read or change rows.
🔴 A policy lets anyone write every row  (rls_policy_allows_all_write)
   Policy "orders are editable" on public.orders (supabase/migrations/20260301000000_init.sql:13) lets anyone, signed in or not, update every row, to any values: using (true).
🔴 Service role key used in client code  (service_role_key_in_client_code)
   app/admin/page.tsx:4: creates a Supabase client with the service role key. This file ships to the browser, and the service role key skips RLS entirely. Move the call behind a server route or edge function and rotate the key.
🟡 Supabase connection is not using the pooler port  (pooler_port_mismatch)
   Found direct 5432 DATABASE_URL/POSTGRES_URL evidence. Vercel/serverless deployments should prefer Supabase transaction pooler port 6543.
🟡 Security definer function callable by the Data API roles  (security_definer_function_executable)
   public.grant_credits(uuid, integer) at supabase/migrations/20260301000000_init.sql:15 is security definer, so it runs with its owner's rights and RLS does not limit what it touches. No migration revokes EXECUTE from public, anon, authenticated, so anyone holding the anon key can call it at /rest/v1/rpc/grant_credits. If only the server calls it, add: revoke execute on function public.grant_credits(uuid, integer) from public, anon, authenticated; Fix: revoke execute on function public.grant_credits(uuid, integer) from public, anon, authenticated;
🟡 Stripe webhook does not verify the signature  (unverified_stripe_webhook)
   1 Stripe webhook handler without signature verification over the raw body: app/api/stripe/webhook/route.ts (no signature check (constructEvent), no stripe-signature header, no raw body). Anyone who finds the URL can post a fake event, for example a paid checkout.
🟡 Env vars used in code but missing from .env.example  (env_var_drift)
   Code reads 1 environment variable that .env.example does not document (NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY). Fresh clones, CI, and the production deploy can silently run without them.
🟡 Database queries with no row limit  (unbounded_query)
   1 file run Supabase selects or Prisma findMany with no .limit()/.range()/take bound (app\admin\page.tsx). These work with 50 test rows and melt with 50,000 production rows.
⚪ No error monitoring detected  (missing_monitoring)
   No Sentry/PostHog (or similar) instrumentation was found. Production errors will only surface when users complain.

Verdict: ❌ 3 blockers, 5 warnings · score 5
Fix: viberaven fix · Details: ~/my-app\.viberaven\agent-tasklist.md

每项结果也会以 Markdown 和 JSON 格式写入 .viberaven/（agent-tasklist.md、gate-result.json、context-map.json），编码 Agent 和 Git 历史记录都可以读取。

适用场景与不适用场景

适用场景：

• 在发布或移交使用 Lovable、Bolt、Cursor、Claude Code 或 Codex 构建的 Vercel + Supabase 应用之前；
• Supabase 迁移或策略变更之后；
• 生产环境错误指向 RLS、service_role 密钥、环境变量、数据库连接或 Stripe webhook 时；
• 通过下方的 GitHub Action，在每次推送或拉取请求时运行。

以下情况不适用：

• 需要了解数据库中的实时状态。 VibeRaven 检查的是代码仓库，不是实时数据库测试。它会读取迁移，因此无法看到有人在 Supabase 控制面板中添加的策略。要检查实时项目，请使用 Supabase Security Advisor。
• 需要进行完整的安全审计。 它不会向应用发送请求，不会测试 XSS 或 CSRF，也不会查询依赖项的 CVE。检查结果正常并不等于通过了安全审计。
• 需要确认应用能否正常运行。 它不会运行构建，也不会逐页检查。请使用 Playwright 或你自己的测试。
• 应用未使用 Supabase。 大多数检查都没有可读取的内容。

比较

这些工具回答的问题各不相同，大多数项目上线时都需要用到不止一种。

工具	检查内容	运行位置	与 VibeRaven 的配合方式
Supabase Security Advisor	对线上数据库进行静态检查：禁用 RLS、安全定义视图和函数、可变的 search_path 等	Supabase 控制台中，针对已部署的项目	Advisor 会检查线上情况。VibeRaven 会在迁移应用前读取迁移文件，以及数据库无法看到的客户端代码和环境文件。
OWASP ZAP	通过 HTTP 动态扫描运行中的 Web 应用：注入、XSS、标头、Cookie	针对已部署或本地 URL 运行	ZAP 从外部测试应用。VibeRaven 会读取代码仓库，并了解 Supabase 授权、策略和密钥。
Semgrep、Snyk、CodeQL	对多种语言进行通用静态分析和依赖漏洞检查	在 CI 或本地对源代码运行	提供广泛的代码规则和 CVE 检查。VibeRaven 的范围更窄：Supabase RLS 和授权、service_role 泄露、连接池器端口以及 Stripe Webhook。
Playwright	你编写的端到端测试，通过真实浏览器驱动应用	在本地或 CI 中，针对运行中的应用	Playwright 验证你测试的流程。以用户 A 登录并尝试读取用户 B 数据行的测试，就是对 VibeRaven 指出的 RLS 问题进行的实时检查。

数据：512 个公开 Lovable 应用

我们对 512 个公开 Lovable 代码仓库中的 Supabase 迁移文件运行了检查。根据分析文章：

对 GitHub 上 512 个包含 supabase/migrations 文件夹的公开 Lovable 项目进行静态检查（2026 年 10 月）后发现，47.3%（242 个）在 public 架构中至少定义了一个 security definer 函数，未登录的调用方可使用 anon 密钥通过 /rest/v1/rpc 执行该函数。

文章介绍了检查方法、局限性和修复方案。另一篇早期文章介绍了同一批 512 个应用中的 RLS 策略。

修复问题

npx -y [email protected] fix                         # list gaps with safe automatic recipes
npx -y [email protected] fix --gap <id> --dry-run    # preview one recipe
npx -y [email protected] fix --gap <id>              # apply it
npx -y [email protected] audit --vercel-supabase     # RLS in migrations, pooler port, service_role key
npx -y [email protected] --strict                    # the verdict as an exit code for CI (exit 1 on not_clear; warnings exit 0)

rls_disabled 配方会添加一个启用 RLS 但不包含策略的迁移，因此在你添加策略之前，浏览器读取操作不会返回任何数据。应用前请先确认，然后通过你的数据库工作流应用并测试。

在 CI 中使用：GitHub Action

Lovable 和 Bolt 会直接推送到 main，因此只检查拉取请求会漏掉它们的大部分更改。VibeRaven GitHub Action 会在拉取请求和推送时，在你自己的运行器中执行相同的检查：

on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: write
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: ohad6k/viberaven-action@v1

拉取请求会收到一条评论，说明此次更改新增或修复了哪些内容。推送到 main 时，如果发现阻止项，会收到一条提交评论。默认情况下，这只是建议；设置 fail-on-blockers: 'true' 后，发现阻止项时任务会失败，而分支保护规则决定这对合并意味着什么。npx -y [email protected] init --github 会写入此工作流的仅检查拉取请求版本，不使用 Action。

为 AI Agent 安装

在编码 Agent 修改代码仓库前，为它们提供相同的上下文：

npx -y [email protected] init --agents all --dry-run   # preview
npx -y [email protected] init --agents all
npx -y [email protected] doctor --agents

这会将有限范围的规则（...）安装到：

• AGENTS.md、CLAUDE.md、GEMINI.md
• .cursor/rules/viberaven-core.mdc（以及范围限定于 Supabase、部署和支付的规则）
• .github/copilot-instructions.md
• .viberaven/agent-context.md、.viberaven/mission-map.md

这些规则会说明何时适合进行检查（使用 Vercel + Supabase 构建的 AI 应用上线或交接前，或者迁移或策略变更后），并介绍这一流程：运行 check，阅读 .viberaven/，修复一个问题，然后在每批修复完成后再次运行 check。这些只是建议，并非门槛：由用户决定何时发布。

Agent 技能

六个 skills.sh 技能可引导 Agent 处理架构问题、版本证据和上线证明：

技能	用途
viberaven	路由器：本地检查／修复循环、Studio 和 MCP 上下文。
architecture-context	在进行任何编辑前，询问缺失的产品问题。
architecture-plan	根据回答和仓库证据制定工作流计划。
what-broke	在修补前找出导致应用故障的版本。
production-context	在 .viberaven/production-context.md 中保存精简的生产环境记忆。
go-live	从本地应用到 GitHub 再到 Vercel，并提供线上 URL 证明。

npx -y [email protected] add ohad6k/VibeRaven --skill viberaven

完整技能包请参阅 agent-skills/。

此仓库也可作为 Agent 插件使用：plugin.yaml、.claude-plugin/、.codex-plugin/ 和 gemini-extension.json 为 Claude Code、Codex 和 Gemini CLI 提供六个技能，以及 /viberaven-work、/viberaven-help、/viberaven-production-context 和 /viberaven-launch 命令。

如需更精简的安装，plugins/viberaven 是适用于 Claude Code 和 Cursor 的独立插件：它包含一个技能，说明何时适合对 Vercel + Supabase 应用进行上线前检查，并附带一个固定版本的 MCP 服务。其清单指定了软件包版本；该插件的发布与上述快速入门相互独立。

MCP

VibeRaven 已列入 MCP 注册表，供偏好使用工具而非终端命令的 Agent 使用：

{ "viberaven": { "command": "npx", "args": ["-y", "@viberaven/[email protected]"] } }

主要工具：viberaven_check_readiness（运行本地检查）、viberaven_heal_apply、viberaven_verify、viberaven_audit、viberaven_gate_result 和 viberaven_validate_npm_package（添加 npm 依赖前运行）。

本地 Studio

不带命令运行 npx -y [email protected] 会打开 Studio：一个本地页面，你自己的编码 Agent（Claude Code、Codex 或 Gemini CLI）可在你的文件夹中进行更改；你则可以查看步骤、检查结果、正在运行的应用和差异，并可随时一键撤销。

## 你的第一个应用更改

相同的工作流，完全在本地运行，无需账号：

1. 打开项目。 在项目文件夹中运行 npx -y [email protected]。Studio 会在浏览器中打开。
2. 连接 Agent。 打开 Agents，选择已安装的 CLI，运行 Test connection，然后选择 Use this agent。
3. 展示应用。 选择 Show my app，启动开发服务器。
4. 提出一个小改动。 选择 Ask 获取修改计划而不进行编辑，或选择 Edit 让 Agent 修改文件，然后选择 Make the change。
5. 检查结果。 试用正在运行的应用，查看检查结果，并打开 Review 查看差异。缺少的测试会标记为未检查；页面能够加载并不能证明所有功能都正常。

在 Windows PowerShell 中，如果执行策略阻止了 npx，请使用 npx.cmd。

Studio 也可在 viberaven.dev 上使用：使用 Google 登录，添加你的仓库，并连接一次电脑。你的 Agent 仍在电脑上运行。网站提供 2 次免费更改，之后可订阅 Pro，每月可进行 300 次更改。两种方案都需要你已登录的编码 Agent；其自身账号和使用限制仍然适用。

	Studio 为你提供的功能
你的 Agent，你的机器	Claude Code、Codex 或 Gemini CLI 会在你的文件夹中进行编辑，并提供连接测试以及 Ask 或 Edit 访问权限。
更改旁的依据	在同一处查看实际步骤、项目检查、正在运行的应用和差异。
审查和撤销	阅读每个已更改的文件。撤销会还原可归属到 Claude Code 的编辑；其他更改会保留，供你审查。
应用的服务	在一张地图中查看 Vercel、Supabase、Stripe、身份验证、监控和分析，并逐项标记为代码中已发现、已选择或缺失。不会把仓库中的证据说成实时的服务商检查结果。
版本和发布	对比发布节点，查看与早期版本相比有哪些更改（本地 Studio）。

检查和账号

• 本地 Studio 和仓库检查。 这些检查会在你的机器上运行，无需 VibeRaven 账号。CLI 不会收集遥测数据。
• 通过 viberaven.dev 进行更改。 使用 Google 登录。免费方案每个账号包含 2 次更改；Pro 每月包含 300 次。你的编码 Agent 账号和用量另行计算。网站会存储请求、进度、检查结果、文件路径，以及经过脱敏且大小受限的差异，以便你进行审查。
• 托管的完整检查。 可选：免费方案包含 2 次，Pro 每月包含 50 次，与更改次数分开计算。
• 磁盘上的 Markdown。 所有上下文都以纯文件形式存放在 .viberaven/ 中，你的 Agent 和 git 历史记录都可以读取。
• 依据胜过感觉。 检查结果会指向仓库中的依据。不会仅凭仓库编辑就声称掌握了服务商控制面板的状态。
• 由你掌控的更改。 在 Agent 编辑项目之前，先审查计划和访问模式。清理操作只会生成计划。仓库检查结果清晰，并不等同于安全审计，也不能证明已部署的应用能够正常运行。

参与贡献

欢迎贡献，而且大多数贡献不需要访问私有源代码：

• 阅读贡献指南，了解仓库结构、PR 要求和本地检查。
• 认领一个适合新手的议题：文档、服务商测试数据、示例和翻译。
• 在讨论区分享想法或提问。
• 加入 Discord，直接与维护者交流。

资源

• Supabase Security Advisor 指南：所有警告 · rls_disabled_in_public · security_definer_view · function_search_path_mutable · 可由 anon 调用的 security definer 函数
• 面向 Agent 的入门模板：examples/nextjs-supabase-vercel-production-ready-template
• 机器可读文档：llms.txt · llms-full.txt · skills.json · skills.sh.json
• 示例证明材料：examples/proof/
• 网站：viberaven.dev · npm：viberaven · 问题：ohad6k/VibeRaven/issues

许可证

MIT。当前公开版本：[email protected]。

由 Ohad Krispin 构建（github.com/ohad6k）。

如果 VibeRaven 帮助你交付产品，请为仓库点星，让其他 AI 应用开发者也能找到它。选择 Watch → Custom → Releases，接收版本发布通知。

VibeRaven 公开仓库是 Agent 发现和安装的入口。产品源代码和服务内部实现位于私有仓库。