refd

refd

开源 AI 搜索监测——追踪 AI 如何回答有关任意品牌的问题：监测其在 ChatGPT、Perplexity、Gemini、Google AI Mode 和 Google AI Overviews 中的曝光度、提及、引用和排名。使用托管应用 refd.ai，也可以自托管整个技术栈。

这是一个 Bun 工作区单体仓库，包含三个独立部署的 Cloudflare Workers：apps/api（api.refd.ai）——Hono API、OAuth、远程 MCP、每日 cron 和队列消费者，包含所有绑定；apps/dashboard（dash.refd.ai）——仅提供静态资源的 React SPA Worker；apps/web（refd.ai）——静态 Astro 公共网站。与运行时无关的共享代码位于 packages/core。数据来自 BrightData（数据集抓取器和 SERP API），存储在 D1（Drizzle）中，原始负载经 gzip 压缩后存入 R2。

refd 还通过远程 MCP 连接器向 AI Agent 提供相同的工作区智能。默认的 data:read 范围为只读；可选的 data:write 范围会增加受限的设置生命周期、允许启动一份引导报告，并可在明确确认后撤销连接。托管指南见 refd.ai/agents；MCP 连接器指南介绍 Claude、Claude Code、ChatGPT、通用客户端、无头 Agent 使用的个人访问令牌，以及自托管设置。

从指南中只需单击一下，即可将其安装到 Cursor 或 VS Code——也可以使用 claude mcp add-json refd '{"type":"http","url":"https://api.refd.ai/mcp"}'。无头 Agent 使用 Settings → Personal access tokens 中的个人访问令牌，而非 OAuth。

工作原理

账户包含工作区；每个工作区追踪一个品牌——其竞争对手、提示词集和运行记录。每日 cron 会为每个符合定时监测条件的工作区创建幂等运行，然后分发队列消息：每个数据集面 × 样本发送一个批次快照触发器（触发 → 通知 → 获取，并带有兜底轮询），此外还会针对每个提示词 × 样本同步调用一次 SERP，以获取 AI Overviews。系统会为每个受追踪实体评估每条回答（是否提及／引用／首次提及位置），并将原始负载以 gzip 压缩后归档到 R2。未出现 AI Overview 会被记录为有效的“未显示 AIO”，而非失败。运行分发会持久化不可变的启动计划，并通过有限次数的退避重试恢复。队列重新投递时，存储状态最终会收敛；但 BrightData 没有幂等键，因此在服务商接受请求后发生崩溃，可能导致重复的付费任务。

开发

bun install
bun run dev    # applies local migrations, then runs all three Workers behind
               # Caddy on same-site subdomains over real HTTPS

在登录界面注册（使用企业邮箱 + 至少 8 个字符的密码）——系统会自动创建你的第一个工作区，并带你进入可恢复的设置向导：为品牌命名，让系统根据你的网站起草品牌描述，选择竞争对手和提示词，选择引擎，然后实时查看首份报告的生成过程。每个 AI 步骤都可以改为手动输入。标准账户最多可创建五个工作区，每个工作区最多保留 25 个有效提示词，并启用最多三个 AI 界面。ADMIN_EMAILS 中的邮箱不受工作区或有效提示词数量限制，并可启用所有可用界面。

bun run dev 会启动 Caddy（Caddyfile），通过同站子域名代理全部三个 Worker——Astro 位于 **https://refdlocal.io**，仪表板位于 **https://dash.refdlocal.io**，API 位于 **https://api.refdlocal.io**（将这三个地址都添加到 /etc/hosts，指向 127.0.0.1，并运行一次 caddy trust）。在同站子域名上使用真实 HTTPS，可以像生产环境一样测试安全跨源 Cookie、CORS、OAuth 重定向和 WebSocket 流式传输。退出开发进程时，Caddy 也会停止。

本地密钥存放在 apps/api/.dev.vars（已加入 gitignore）：JWT_SECRET、BRIGHTDATA_API_TOKEN、BRIGHTDATA_WEBHOOK_SECRET（本地可选；需要可公开访问的 PUBLIC_BASE_URL）、ADMIN_EMAILS（以逗号分隔的管理员和操作员允许列表），以及 EXA_API_KEY（用于引导流程中的竞争对手搜索，可选）。非密钥的构建时源地址（VITE_API_ORIGIN、PUBLIC_DASHBOARD_ORIGIN 等）按环境写入各应用的 .env.development / .env.production 并提交。分析功能使用由公开网站和仪表板共享的自托管 Umami 实例，因此激活漏斗可以覆盖这两个平台：Web 应用需要 PUBLIC_UMAMI_HOST_URL、PUBLIC_UMAMI_WEBSITE_ID 和 PUBLIC_ANALYTICS_HOSTNAME；仪表板需要将这三项设置为对应的 VITE_* 变量（并使用相同的网站 ID）。其中任何一项未设置，构建都不会生成跟踪代码，这正是自托管部署所需的行为。引导流程还使用两个绑定，而非密钥——Workers AI（AI）和 Browser Rendering（BROWSER）——二者在 apps/api/wrangler.jsonc 中都设为 remote: true，因此本地开发会代理到真实服务，并且账户需要启用这两项服务。

• bun run check — 类型检查（所有工作区） · bun run lint / lint:fix — Biome · bun test — 单元测试
• bun run build — 构建全部三个 Worker · bun run deploy — 构建、迁移 D1，然后部署全部三个 Worker（自托管/手动部署方式；在 refd.ai 上，合并到 main 后会通过 Cloudflare 自动部署全部三个 Worker）

Git worktree 开箱即用，支持 wt：wt create <name> 会运行仓库中已提交的 .wt/setup.sh，安装依赖并复制本地密钥和 wrangler 状态，因此新建的 worktree 与主检出目录用起来一样。

自托管

wrangler queues create refd-ingest && wrangler queues create refd-ingest-dlq
wrangler secret put JWT_SECRET
wrangler secret put BRIGHTDATA_API_TOKEN
wrangler secret put ADMIN_EMAILS       # comma-separated admin/operator allowlist
wrangler secret put EXA_API_KEY        # optional: onboarding competitor search
bun run db:migrate:remote
bun run deploy

bun run deploy 会构建并部署全部三个 Workers（refd-api、refd-dashboard、refd-web）；将它们的自定义域名分别指向 api.、dash. 和根域名。API 工作区自身的 deploy 脚本会先运行远程 D1 迁移，因此单独部署 @refd/api（通过 CI 或 Cloudflare 控制台部署命令）时，总会一并更新数据库架构。（托管部署通过 Cloudflare 的 Git 集成功能，将这些部署脚本配置为在推送到 main 分支时运行，因此 refd.ai 本身无需手动部署。）你需要一个 Cloudflare 账户（使用 Queues 需要 Workers 付费套餐；引导流程还需要启用 Workers AI 和 Browser Rendering）、一个 D1 数据库和一个 R2 存储桶（ID/名称位于 apps/api/wrangler.jsonc），以及一个 BrightData 账户：在 apps/api/wrangler.jsonc 的 vars 中填写数据集 ID（控制台 → Web Scrapers → 各 AI scraper），并创建一个与 BRIGHTDATA_SERP_ZONE 匹配的 SERP API 区域。对于自托管部署，请设置部署来源站点（PUBLIC_BASE_URL、DASHBOARD_ORIGIN、PUBLIC_SITE_ORIGIN、API_ORIGIN）以及 SCHEDULED_MONITORING_POLICY=all；代码库中提交的 entitled 策略适用于 refd.ai，并将定时任务限制为活跃的 pilot 或 subscribed 工作区。定时任务计划（每天 UTC 06:00）、采样数和地理位置也配置在 apps/api/wrangler.jsonc 中。

备注

• AI 回答具有非确定性：托管的定时运行对每个提示词和展示面使用 SAMPLES=1；请根据已完成的多次运行来判断趋势，而非单次采样。运营人员可以为有针对性的手动运行请求更多采样。
• 每次标准完整运行最多包含 25 个活跃提示词 × 3 个已启用展示面 × 采样数（默认值为 25 × 3 × 1 = 75 条记录）。配额会随符合定时监控条件的工作区数量而增加。
• 公共网站既面向 Agent，也面向用户：每个页面都可以在相同路径后追加 .md，以 Markdown 格式访问；/llms.txt 遵循 llmstxt.org 格式并链接到这些 Markdown 版本；/llms-full.txt 则将所有内容内联其中。自托管部署可免费获得此功能。
• 设计系统：DESIGN.md。评分/指标约定：docs/METRICS.md。远程 MCP + OAuth：docs/mcp.md。

贡献

欢迎贡献。设置说明以及 PR 必须通过的检查，请参阅 CONTRIBUTING.md；社区行为规范请参阅 CODE_OF_CONDUCT.md。发现安全问题？请遵循 SECURITY.md 中的流程，而不要公开提交问题。

许可证

MIT © refd