内容
# funnel-analytics-agent
**英文** | [中文](README.zh-CN.md)
> 每天早晨的简报 + 实时异常警报，适用于独立产品发布。读取 Vercel + OpenPanel + HyperDX + Supabase + Product Hunt，提前发现问题。
[](LICENSE)
[](https://pypi.org/project/funnel-analytics-agent/)
[](#)
由 [Alex Ji](https://github.com/alex-jb) 创建 — 独立创始人，正在开发 [VibeXForge](https://github.com/alex-jb/vibex)。源于这个想法：
> *在 Product Hunt 发布日，我的仪表盘标签页有 Vercel + OpenPanel + HyperDX + Supabase + Product Hunt + GitHub。切换这些标签页需要 1 小时/天。错过一个 5xx 错误 2 小时 = 损失了发布机会。*
## 功能
两种模式，一个代理：
**简报模式** — 每天早晨运行（cron），从所有数据源编译 Markdown 简报，放入你的 Obsidian 知识库。你可以在 30 秒内阅读完毕。
**警报模式** — 在发布窗口期间每 10 分钟运行一次，如果发现任何关键/警报级别的问题，则退出并返回代码 `2`。你的包装脚本会通知你（Telegram、Slack、ntfy.sh）。
数据源（v0.9，8 个总计）：
- **Vercel** — 最新部署状态、过去 24 小时内的部署、失败的部署
- **Product Hunt** — 直播投票数、评论数、发布日的趋势检查
- **Supabase advisor** — 安全性和性能检查；单独显示每个严重问题
- **OpenPanel** — 跟踪事件（signup_completed、project_submit_completed 等）过去 24 小时内的计数；当事件计数降至 0 时发出警告（跟踪回归）
- **HyperDX** — 过去 N 小时内的错误日志计数；严重程度从 info → warn → alert 随着计数超过 10 / 50 的阈值而增加
- **构建质量** — build-quality-agent 本地日志中过去 24 小时的预推送审查（判决、BLOCK 计数、token 支出）
- **代理支出** — 跨代理 Anthropic $ MTD 聚合，来自 `~/.<agent>/usage.jsonl` 文件
- **VibeX** — 直接 SQL 拉取核心发布板指标（新创作者/提交/累计播放/阶段分布）；零 Claude 调用。可以通过 `VIBEX_PROJECT_REF` 配置（或重用 `SUPABASE_PROJECT_REF` 如果是同一个项目）
## 安装
```bash
git clone https://github.com/alex-jb/funnel-analytics-agent.git
cd funnel-analytics-agent
pip install -e .
cp .env.example .env
# 填写 VERCEL_TOKEN, PH_DEV_TOKEN 等
```
## 使用
```bash
# 一次性简报（默认）
funnel-analytics-agent
# 将简报写入文件（例如 Obsidian 知识库）
funnel-analytics-agent --out ~/Documents/alex-brain/morning-briefs/$(date +%Y-%m-%d).md
# 实时警报模式 — 如果有关键问题，则退出并返回代码 2
funnel-analytics-agent --alert
# 限制特定数据源
funnel-analytics-agent --source vercel --source producthunt
```
### Product Hunt 发布日 cron 设置
```cron
# 发布窗口期间每 7 分钟运行一次 — 警报模式
7,17,27,37,47,57 * * * 1 /usr/local/bin/funnel-analytics-agent --alert || curl -d "PH alert" ntfy.sh/your-topic
# 每天 7:03 AM 运行 — 简报模式
3 7 * * * /usr/local/bin/funnel-analytics-agent --out ~/Documents/alex-brain/morning-briefs/$(date +\%Y-\%m-\%d).md
```
## 设计选择
- **每个数据源独立失败。** Vercel API 宕机？你的简报仍然可以获取 Product Hunt 统计信息。失败的数据源列在简报底部；不会导致整个代理失败。
- **没有外部依赖（暂时）。** 纯标准库 `urllib` — 没有 requests、httpx、API 客户端 SDK。保持安装快速和 pip-install-friendly。
- **Markdown 输出。** 输出是人类可读的 Obsidian / VS Code，而不是仪表盘服务。
- **退出代码用于 cron，而不是推送通知。** v0.1-v0.3 不包含 Telegram/Slack 适配器 — 你的 cron 包装脚本负责通知。保持代理的表面积小。
- **7 天基准线自动构建。** 无需种子历史数据。24 小时 cron 运行后基准线开始形成；7 天后变得稳固。启动模式（无历史）仅跳过增量计算 — 从不阻止输出。
## 路线图
- [x] **v0.1** — Vercel + Product Hunt 数据源 · 简报模式 · 警报模式 · cron友好
- [x] **v0.2** — OpenPanel、HyperDX、Supabase advisor 数据源（5 个数据源，总共 30 个测试）
- [x] **v0.3** — 7 天基准线 · `delta_pct` 丰富 · >50% 降幅的严重性提升 · 41 个测试
- [x] **v0.4** — 推送通知适配器（ntfy.sh / Telegram / Slack）+ macOS launchd 安装程序（54 个测试）
- [x] **v0.5** — 每个报告顶部使用 Claude 总结的简报（Haiku 4.5 默认；~$0.0008/run；优雅降级）
- [x] **v0.8** — MCP 服务器：从 Claude Desktop 查询早晨简报 / 实时警报 / 每个数据源的状态
## MCP 服务器（Claude Desktop / Cursor / Zed）
将简报、警报状态和各个数据源作为 AI 助手可以调用的工具公开。
```bash
pip install 'funnel-analytics-agent[mcp]'
```
然后添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"funnel-analytics": {
"command": "funnel-analytics-mcp",
"env": {
"VERCEL_TOKEN": "...",
"VERCEL_PROJECT_ID": "...",
"PH_DEV_TOKEN": "...",
"PH_LAUNCH_SLUG": "your-launch-slug",
"OPENPANEL_CLIENT_ID": "...",
"OPENPANEL_CLIENT_SECRET": "...",
"HYPERDX_API_KEY": "...",
"SUPABASE_PERSONAL_ACCESS_TOKEN": "...",
"SUPABASE_PROJECT_REF": "...",
"ANTHROPIC_API_KEY": "..."
}
}
}
}
```
工具：
- `get_brief(include_summary)` — 完整的 Markdown 早晨简报
- `get_alerts()` — 警报模式输出：`All clear` 或每个数据源的严重性
- `get_source(name)` — 单个数据源（vercel / producthunt / openpanel / hyperdx / supabase）
- `usage_summary()` — 当地使用日志中的 Anthropic token + $ 总计
## 许可证
MIT。
## 🧩 [Solo Founder OS](https://github.com/alex-jb/solo-founder-os) 栈的一部分
一个不断增长的 MIT 许可代理集合，它们共享 `solo-founder-os` 作为基础 — cron、eval、reflexion、AnthropicClient、HITL 队列、通知器。每个代理都独立有用；一起它们涵盖了整个一人公司的 workflow。
🌐 整个栈在 [vibexforge.com](https://vibexforge.com) 上实时生产环境中运行。
| 代理 | 功能 |
|---|---|
| [solo-founder-os](https://github.com/alex-jb/solo-founder-os) | 共享基础库（cron · eval · reflexion · 技能库 · DGM-lite）。每个其他代理都依赖于它。 |
| [build-quality-agent](https://github.com/alex-jb/build-quality-agent) | 预推送 Claude 差异审查器 + 本地构建运行器 — 在发货前捕获 CI-killing 更改。 |
| [customer-discovery-agent](https://github.com/alex-jb/customer-discovery-agent) | Reddit 痛点刮刀 + Claude 聚类用于产品验证。 |
| [orallexa-marketing-agent](https://github.com/alex-jb/orallexa-marketing-agent) | AI 营销代理 — 提交项目一次，获取 X / Reddit / HN / Dev.to / 小红书 + 7 个平台的原生帖子。支持 [vibexforge.com](https://vibexforge.com)。 |
| [vc-outreach-agent](https://github.com/alex-jb/vc-outreach-agent) | 冷邮件起草器 — 投资者（vc 模式）或付费客户（客户模式，从 v0.9.0 合并而来）。HITL 队列 + SMTP 发送器。 |
| [cost-audit-agent](https://github.com/alex-jb/cost-audit-agent) | 6 个提供商（Vercel / Anthropic / OpenPanel / HyperDX / Supabase / GitHub Actions）的月度账单审计，带有美元标记的浪费发现。 |
| [bilingual-content-sync-agent](https://github.com/alex-jb/bilingual-content-sync-agent) | EN ⇄ 中文 i18n 差异 + Claude 翻译 + HITL 应用。批量 API 路径 @ 50% 折扣。 |
| [customer-support-agent](https://github.com/alex-jb/customer-support-agent) | 用户消息分类 → 自动草拟回复 → HITL 队列。关闭 L5 客户支持层。 |
| [payments-agent](https://github.com/alex-jb/payments-agent) | 过期发票提醒起草器。Stripe 形状类型 + MockProvider 备用 + 硬货币安全提示规则。 |
*每个代理的行在 README 中省略。安装对您有帮助的代理 — `pip install <agent-name>`。*
