开放侦察员

创建 AI 侦察员，持续在网络上搜索，并在找到您所需内容时通知您。

关于

开放侦察员是一个基于 AI 的监控平台，允许您创建“侦察员”——按计划自动运行的任务，用于持续搜索和跟踪信息。无论您是在寻找附近的餐厅、关注 AI 新闻，还是追踪其他任何更新，侦察员都会全天候工作，帮您找到所需内容，并在发现后立即通知您。

技术栈

• Next.js 15
• React 19
• TypeScript
• Tailwind CSS v4
• Supabase（数据库 + 认证 + 边缘函数）
• pgvector（用于语义搜索的向量嵌入）
• Firecrawl SDK（@mendable/firecrawl-js）
• OpenAI API（AI 代理 + 嵌入）
• Resend（电子邮件通知）

快速入门

先决条件

• Node.js 18+
• bun（默认）、npm 或 pnpm
• Supabase 账户（supabase.com）
• OpenAI API 密钥（platform.openai.com）
• Firecrawl API 密钥（firecrawl.dev）
• Resend API 密钥（resend.com）——用于电子邮件通知
• Google Cloud 控制台账户（用于 Google OAuth — 可选）

1. 克隆并安装

git clone https://github.com/firecrawl/open-scouts
cd open-scouts
bun install  # 或：npm install / pnpm install

2. 创建 Supabase 项目

1. 访问 supabase.com
2. 创建一个新项目
3. 等待项目完成配置

3. 启用所需扩展

在您的 Supabase 控制台中：

1. 转到 数据库 → 扩展
2. 搜索并启用：
   • pg_cron（用于定时任务）
   • pg_net（用于从数据库发起 HTTP 请求）
   • vector（用于对执行摘要进行 AI 驱动的语义搜索）
   • supabase_vault（用于安全存储凭据——通常默认启用）

4. 设置环境变量

通过复制示例文件，在根目录下创建 .env 文件：

cp .env.example .env

然后在 .env 文件中填写您的实际值。

.env.example 文件包含所有必需的环境变量，并附有详细说明和获取每个 API 密钥的直接链接。

5. 运行数据库设置

首先，关联您的 Supabase 项目（同步密钥所必需）：

bunx supabase login        # 登录 Supabase CLI（一次性操作）
bunx supabase link --project-ref <your-project-ref>  # 在 Supabase 控制台 URL 中找到项目引用

然后运行设置脚本：

bun run setup:db  # 或：npm run setup:db / pnpm run setup:db

这将：

• 创建所有必要的表（scouts、scout_executions、scout_execution_steps 等）
• 添加用户认证支持（user_id 列、行级安全）
• 启用实时订阅
• 为 AI 生成的执行摘要设置向量嵌入
• 配置 可扩展调度架构（pg_cron + pg_net + vault）
• 自动将您的 Supabase URL 和服务角色密钥存储到 vault 中
• 设置用于侦察员调度和清理的 cron 作业
• 同步边缘函数密钥 来自您的 .env 文件（OPENAI_API_KEY、FIRECRAWL_API_KEY、RESEND_API_KEY）

注意： 设置脚本会检查是否已启用所需的扩展（vector、pg_cron、pg_net）。如果未启用，请按照屏幕上的指示在 Supabase 控制台中启用它们，然后再次运行脚本。

6. 设置认证

开放侦察员使用 Supabase Auth 进行用户认证，支持电子邮件/密码和 Google OAuth。

启用电子邮件/密码认证（默认启用）

1. 转到 Supabase 控制台 → 认证 → 提供商 → 电子邮件
2. 确保已打开“启用电子邮件提供商”
3. 根据需要在 认证 → 电子邮件模板 中配置电子邮件模板

启用 Google OAuth（可选但推荐）

1. 创建 Google OAuth 凭证：

   • 访问 Google Cloud 控制台
   • 创建一个新项目或选择现有项目
   • 转到 APIs & Services → Credentials
   • 单击 Create Credentials → OAuth client ID
   • 选择“Web application”作为应用类型
   • 添加授权的 JavaScript 源：
     • http://localhost:3000（开发环境）
     • https://your-domain.com（生产环境）
   • 添加授权的重定向 URI：
     • https://<your-project-ref>.supabase.co/auth/v1/callback
   • 复制 Client ID 和 Client Secret

2. 在 Supabase 中配置：

   • 转到 Supabase 控制台 → 认证 → 提供商 → Google
   • 打开“启用 Google 提供商”
   • 粘贴您的 Client ID 和 Client Secret
   • 保存

7. 部署边缘函数

将侦察员执行代理和电子邮件函数部署到 Supabase Cloud：

bunx supabase functions deploy scout-cron
bunx supabase functions deploy send-test-email

注意： 当您运行 setup:db 时，密钥（OPENAI_API_KEY、FIRECRAWL_API_KEY、RESEND_API_KEY）会自动同步。如果您需要手动更新它们：

bunx supabase secrets set OPENAI_API_KEY=sk-proj-...

8. 设置 Resend（电子邮件通知）

当侦察员找到结果时，系统会向您的账户邮箱发送电子邮件通知。

1. 在 resend.com 创建一个 Resend 账户
2. 从 Resend 控制台获取您的 API 密钥
3. 将其添加到 .env 文件中，并再次运行 setup:db 以同步，或者手动设置：

   bunx supabase secrets set RESEND_API_KEY=re_...
   

4. 在 resend.com/domains 验证自定义域名，以便可以发送到任何邮箱

重要——免费层级限制：

• 如果未验证域名，Resend 仅能发送到您的 Resend 账户邮箱
• 免费层级每月包含 3,000 封邮件（每日上限 100 封）

测试电子邮件设置：

1. 在应用程序中转到 设置
2. 单击 发送测试邮件 以验证配置
3. 检查您的收件箱以确认测试邮件

9. Firecrawl 配置

Open Scouts 使用 Firecrawl 进行网页抓取和搜索。

📌 重要提示：无需配置环境变量

您不需要在环境变量中配置 Firecrawl API 密钥。 每位用户可以直接在应用内的 设置 页面添加自己的自定义 Firecrawl API 密钥。这是大多数用户的推荐方式。

自定义 API 密钥（推荐）

使用 Open Scouts 的最简单方法：

1. 在 firecrawl.dev 注册
2. 从 仪表板 获取您的 API 密钥
3. 前往 Open Scouts 应用中的 设置
4. 在 Firecrawl 集成 部分输入您的 Firecrawl API 密钥
5. 点击 保存 —— 您就可以开始使用了！

每位用户管理自己的 API 密钥，使用情况会记录到其个人的 Firecrawl 账户中。

服务器端 API 密钥（可选——适用于自托管）

如果您是自托管用户，并希望为所有用户提供一个共享的 API 密钥：

1. 在 firecrawl.dev 注册
2. 从 仪表板 获取您的 API 密钥
3. 将其添加到您的 .env 文件中：

   FIRECRAWL_API_KEY=fc-your-key-here
   

4. 设置边缘函数密钥：

   npx supabase secrets set FIRECRAWL_API_KEY=fc-your-key-here
   

注意： 如果用户在设置中添加了自己的自定义 API 密钥，则会使用其个人密钥，而不是服务器端的共享密钥。

合作伙伴集成（企业级——封闭测试版）

⚠️ 合作伙伴密钥功能目前处于封闭测试阶段，仅对企业客户开放。 此功能尚未公开提供。

合作伙伴集成的工作原理（可用时）：

• 当用户注册时，系统会自动为其创建一个唯一的 Firecrawl API 密钥
• 每个用户的使用情况会被单独跟踪
• 密钥安全地存储在 user_preferences 表中
• 如果用户的密钥失效，系统会自动回退到共享的合作伙伴密钥
• 用户可以在 设置 → Firecrawl 集成 中查看其连接状态。

10. 运行开发服务器

bun run dev  # 或：npm run dev / pnpm run dev

打开 http://localhost:3000，即可看到应用。

工作原理

用户认证流程

1. 公共首页：用户无需登录即可浏览着陆页
2. 创建侦察员：当用户输入查询并按下回车键时，系统会提示他们登录
3. 登录/注册：用户可以通过电子邮件/密码或 Google OAuth 进行身份验证
4. 继续流程：认证完成后，侦察员的创建过程会自动继续
5. 用户隔离：每个用户只能查看和管理自己的侦察员。

侦察员系统

1. 创建侦察员：定义您想要监控的内容（例如：“查找我附近最近的印度餐厅”或“查找任何人工智能新闻”）
2. AI 代理设置：系统会自动配置搜索查询和策略
3. 设置频率：选择运行频率（每小时、每 3 天、每周）
4. 配置通知：在设置中添加您的邮箱，以便在侦察员找到结果时接收提醒
5. 持续监控：调度器每分钟检查一次，并单独触发到期的侦察员
6. AI 总结：每次成功执行都会生成一段简洁的单句摘要，并附带语义嵌入
7. 接收通知：当侦察员发现新结果时，您将收到电子邮件提醒（如果已配置邮箱）
8. 查看结果：在侦察员页面上实时查看所有发现的结果及 AI 生成的摘要。

手动执行

点击任意侦察员页面上的 “立即执行” 按钮，即可立即触发执行，无需等待定时任务。

邮件通知

当侦察员找到结果时，您将自动收到发送到账户邮箱的邮件提醒：

• 自动发送：只有在侦察员成功找到结果时才会发送邮件
• 丰富内容：精美的 HTML 邮件，包含侦察员的结果和链接
• 测试：使用设置中的“发送测试邮件”按钮来验证配置。

邮件服务：由 Resend 提供（免费套餐包含每月 3,000 封邮件）

注意： 在 Resend 的免费套餐中，如果没有验证过的域名，邮件只能发送到您的 Resend 账户邮箱。请在 resend.com/domains 验证自定义域名，以便可以发送到任何邮箱。

架构

• 前端：使用 Supabase Realtime 实现实时更新的 Next.js 应用程序
• 数据库：PostgreSQL（Supabase），配备 pg_cron 用于调度和 pgvector 用于语义搜索
• 认证：Supabase Auth（电子邮件/密码 + Google OAuth）
• AI 代理：OpenAI GPT-4 结合函数调用（搜索与抓取工具）
• AI 总结：每次成功执行后都会自动生成带有向量嵌入的单句摘要
• 边缘函数：基于 Deno 的无服务器函数，负责协调代理的执行
• 网页抓取：Firecrawl API 用于搜索和内容提取（支持通过合作伙伴集成实现按用户分配 API 密钥）。

可扩展的调度架构

Open Scouts 使用一种设计用于扩展至数千个侦察员的调度模式：

每分钟：
pg_cron → dispatch_due_scouts() → 查找到期的侦察员 → pg_net HTTP POST
                                                          ↓
                                    ┌──────────────────────┼──────────────────────┐
                                    ↓                      ↓                      ↓
                              边缘函数          边缘函数          边缘函数
                              （侦察员 A）              （侦察员 B）              （侦察员 C）
                              [隔离]             [隔离]             [隔离]

• 调度器（SQL）：每分钟通过 pg_cron 运行，查询到期的侦察员，并触发单独的 HTTP 请求
• 隔离执行：每个侦察员都在独立的边缘函数调用中运行，拥有完整的资源（256MB 内存，400 秒超时）
• 自动清理：另一个 cron 作业每 5 分钟清理卡住的执行任务
• Vault 集成：Supabase 凭证安全地存储在 Vault 中，并由调度器读取。

安全性

• 行级安全（RLS）：所有数据库表都启用了 RLS 策略，确保用户只能访问自己的数据
• 用户隔离：侦察员、消息和执行记录都与已认证用户相关联
• 安全的认证流程：OAuth 令牌和会话由 Supabase Auth 管理
• 服务角色：服务器端操作（cron 作业、边缘函数）使用服务角色以获得特权访问权限
• API 密钥存储：在使用合作伙伴集成时，Firecrawl API 密钥会存储在服务器端的 user_preferences 表中，绝不会暴露给客户端。

构建生产环境

bun run build  # 或：npm run build / pnpm run build
bun start      # 或：npm start / pnpm start

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT

Open Scouts 快速上手指南

环境准备

• 系统要求：Node.js 18+（推荐使用 LTS 版本）
• 前置依赖：
  • Supabase 账户（数据库与认证）
  • OpenAI API Key（AI 代理）
  • Firecrawl API Key（网页抓取，应用内配置）
  • Resend API Key（邮件通知，可选）
  • Google Cloud Console（Google OAuth，可选）

中国开发者加速提示：安装依赖时使用国内镜像加速：

npm config set registry https://registry.npmmirror.com
# 或使用 pnpm
pnpm config set registry https://registry.npmmirror.com

安装步骤

1. 克隆项目并安装依赖：

   git clone https://github.com/firecrawl/open-scouts
   cd open-scouts
   bun install  # 或 npm install / pnpm install
   

2. 创建 Supabase 项目：

   • 访问 supabase.com → 新建项目

3. 启用 Supabase 扩展：

   • 在 Supabase Dashboard → Database → Extensions，启用：
     • pg_cron
     • pg_net
     • vector

4. 配置环境变量：

   cp .env.example .env
   

   • 编辑 .env 文件填入 API Key（参考 .env.example 说明）

5. 设置数据库：

   bunx supabase login
   bunx supabase link --project-ref <your-project-ref>  # 从 Supabase URL 获取
   bun run setup:db
   

6. 配置邮件通知（Resend）：

   • 在 resend.com 获取 API Key
   • 添加到 .env 后运行：

     bun run setup:db
     

7. 部署边缘函数：

   bunx supabase functions deploy scout-cron
   bunx supabase functions deploy send-test-email
   

基本使用

1. 启动开发服务器：

   bun run dev
   

   • 访问 http://localhost:3000

2. 创建第一个 Scout：

   • 输入查询（如 AI news）→ 系统提示登录
   • 登录后（邮箱/Google OAuth）→ 设置频率（如 每天）→ 保存

3. 触发执行：

   • 在 Scout 页面点击 "Run Now" 立即执行
   • 或等待定时触发（根据设置的频率）

4. 查看结果：

   • 成功执行后生成 AI 摘要（如 最新 AI 新闻：GPT-5 发布）
   • 邮件通知（如配置了 Resend）→ 在 Scout 页面实时查看结果

关键提示：Firecrawl API Key 无需在环境变量配置，直接在应用内 Settings → Firecrawl Integration 添加即可。