smolanalytics

# smolanalytics [](https://github.com/Arjun0606/smolanalytics/actions/workflows/ci.yml) [](LICENSE) [](https://goreportcard.com/report/github.com/Arjun0606/smolanalytics) [](https://github.com/Arjun0606/smolanalytics/releases) **你的 AI 助手承认它会幻觉你的数字。而我的不会。这是 CI 测试。** 只有当分析数据的 AI 答案与仪表盘上的数据完全匹配时，分析结果才有意义。[协议测试](internal/api/agreement_test.go)在 CI 中运行，如果它们有差异，则会导致构建失败。你可以直接在 Cursor 或 Claude Code 中询问 *"本周激活是否有所改善？*"，并从你的实际数据中获得由 [MCP](https://modelcontextprotocol.io) 支持的模型答案，这样就不需要支付 AI 费用，也不会有黑箱操作。它会给出一个结论，告诉你需要修复什么。只需运行一个 MIT 许可的二进制文件，你的数据就不会离开你的服务器。  _{这是使用演示数据运行的真实产品。你可以在 30 秒内自己运行它。（[静态图像](docs/dashboard.png))} ## 立即查看，无需安装 **[smolanalytics-demo.fly.dev](https://smolanalytics-demo.fly.dev)** 是使用演示数据运行的真实产品。现在可以直接访问。顶部有结论，询问栏，你的事件和页面以芯片形式显示。点击 `checkout`，或输入 "visitors to /pricing"，并获得准确的计算答案。整个过程只需一步即可完成。 ## 自己运行（30 秒） ```sh # Docker docker run -p 8080:8080 ghcr.io/arjun0606/smolanalytics demo ``` 或获取二进制文件： ```sh curl -fsSL https://raw.githubusercontent.com/Arjun0606/smolanalytics/main/install.sh | sh smolanalytics demo ``` 或使用 Go： ```sh go run github.com/Arjun0606/smolanalytics/cmd/smolanalytics@latest demo ``` 给它几秒钟来拉取和加载数据，然后打开 `localhost:8080`。相同的完整仪表盘，现在在你的机器上。（如果端口 8080 忙，可以使用 `-p 8081:8080` 并打开 `localhost:8081`。）询问栏显示你的实际事件名称和页面作为芯片，因此询问是确定的，而不是猜测：点击 `checkout` 或输入 "visitors to /pricing" 并获得准确的计算答案。 ## 两种询问方式（哪种是哪种） smolanalytics 在两个界面上以纯英文回答问题。它们是不同的，保持它们一致是整个模型的关键： - **仪表盘询问栏** 询问关于你的 **数据**。它内置，无需设置，确定。它不读取你的代码：它知道你的事件和页面是因为它们在你的数据中，并且它将它们显示为芯片，因此你永远不会猜测名称。适合于 "本周有多少次结账？", "访问 /pricing 的访客数量", "人们在哪里流失？"。 - **通过 MCP 的编码代理** （Cursor / Claude Code）询问 **代码感知** 问题。它拥有你的代码库，你的跟踪计划（`smolanalytics.plan.json`）和 MCP 上的 smolanalytics，因此它连接了两者：询问 "PQR 页面的 MAU 是多少" 代理知道 PQR 是代码中的 `/pqr` 路由，然后为它查询 smolanalytics。这是你仪器 ("在 checkout 流中添加跟踪") 和验证的地方。 重复的指标永远不需要重新输入：固定你构建的任何报告（或让你的代理调用 `save_report`），它会在仪表盘上每次访问时渲染，因此重复的指标永远不需要重新输入。 ## 为什么存在 每个分析工具现在都有一个 AI 助手，但它被安装在他们的应用中，你需要为它付费，并且你仍然需要离开编辑器才能使用它。smolanalytics 翻转了这一点：分析数据直接来到你已经工作的地点，由你已经付费的模型回答。 - **在编辑器中免费询问。** 它是一个 MCP 服务器：连接 Claude / Cursor / Claude Code 并用纯英文询问。你的模型进行推理，因此不需要 API 密钥和计费 AI 积分。仪表盘还有一个内置的询问栏，无需设置。 - **答案是计算的，而不是生成的。** 其他所有工具的 AI 助手都承认它会幻觉。我们的调用确切的确定性报告（不是猜测的 SQL），因此它返回的数字是真实的计算数字或没有。你的模型仍然可以问错问题，但它不能编造答案。而且这不是承诺，而是 CI：[协议测试](internal/api/agreement_test.go) 断言 MCP 答案和 HTTP API 答案对于相同的问题每次构建都是相同的，永远如此。没有第二个查询路径可以漂移。 - **内置 Google 搜索控制台。** `smolanalytics gsc auth` （自带 OAuth 客户端，两个环境变量）并且你的顶部搜索查询（点击，印象，位置，最大移动者）出现在仪表盘上，在 `search_console_report` MCP 工具中，与访客登陆后做了什么一起显示。 - **真正的产品分析和网页分析，一个工具。** 漏斗，留存，趋势，细分，生命周期，粘性，路径，群体，B2B 账户，以及类似 Plausible 的网页视图（访客，实时，现在的页面，推荐者，UTM 来源，设备）。通常的答案是 "运行 Plausible 和更重的某物"；这是两者合一，在一个二进制文件中。 - **一个二进制文件，而不是集群。** 没有 Kafka/ClickHouse/Redis，没有 12 小时的调试和自托管。`docker run` 就可以了。你的数据永远不会离开你的服务器，也不会训练任何人的模型。 - **一个实例，所有项目。** SDK 将每个事件标记为其站点的托管域名：指向你运行的每个产品到同一个实例，在仪表盘上切换站点，过滤任何报告（或任何 MCP 问题）按站点，并按产品分类早晨简报。你不需要每个项目一个服务器。 - **默认漂亮。** 服务器渲染，瞬间，固执己见。它看起来是设计好的，而不是拼凑的。 - **开源（MIT），真正自托管。** 拥有整个东西，没有付费功能被剥夺。自托管版本没有限制。 **为什么不直接使用 Mixpanel 或 PostHog？** 它们更深入，但有三点它们 **结构上无法匹配**，因为这会破坏他们的业务： （1）**AI 是你的，所以它是免费的** （他们计量他们的）； （2）**答案来自确切的报告，而不是生成的 SQL**，并且 CI 强制它们与仪表盘匹配，而他们的 MCP 文档不承诺这一点； （3）**你的数据永远不会离开你的服务器** （他们的生活在他们的云中）。相同的漏斗/留存，价格的一小部分，它告诉你需要修复什么，而不是让你挖掘。你甚至可以在移动任何东西之前试用它：`plan check --source=posthog` 在你的现有 PostHog 项目上运行我们的跟踪漂移门控，当你切换时，`smolanalytics import` 重放你的历史记录，原始时间戳 ([docs/migration.md](docs/migration.md))。 ## 最私有的分析运行 每个托管分析工具，包括隐私优先的工具，仍然要求你信任 **他们的** 服务器来处理你用户的 数据。smolanalytics 保留没有云参与：它是一个二进制文件在你自己的服务器上，因此数据在物理上永远不会离开你的基础设施。 - **没有第三方。** 没有什么需要签署 DPA，没有处理器需要披露，没有跨越国界的东西。对 "谁可以看到这些数据？" 的答案是：只有你。 - **没有第三方 Cookie，没有指纹识别，没有跨站点跟踪。** 浏览器 SDK 使用第一方匿名 ID 而不是其他东西。 - **无 Cookie 模式，无需同意横幅。** `smolanalytics.init(key, { anonymous: true })` 在访客的设备上 **不存储任何内容**；服务器派生一个每天旋转的匿名 ID 而不是（Plausible 的模型）。访客在一天内无法链接，漏斗在一天内仍然有效，识别用户（登录后）保持完整的分析。同意横幅成本 ~55% 的数据；此模式不需要。 - **删除权，内置。** `DELETE /v1/users/{id}/data` （或询问你的 AI： *"删除用户 u123 的所有数据"*) 删除一个人的事件，跨越每个存储层。GDPR 请求在其他地方需要排队，而在这里是一个调用。 - **它从不训练模型。** 没有模型和供应商，因此没有人可以训练你的数据。 - **架构上私有，而不是政策上。** 它不是因为隐私页面上的承诺而私有；它因为没有其他人参与而私有。 Plausible，Fathom 和 Simple Analytics 很不错，比 Google 更私密。但它们仍然是你发送数据给的云。自托管是数据根本不会离开的版本。 ## 构建以超越其制作者 押注于小型工具不意味着押注于背后的人。架构使我们变得不必要： - **MIT，无 CLA。** 没有可以撤销的许可证，也没有重新授权的杠杆 ([LICENSE](LICENSE))。如果你不再喜欢我们，可以随时 fork。 - **一个静态二进制文件，无外部服务。** 它调用没有托管的 API，没有许可证服务器，也不会打电话回家。它不知道我们的存在。 - **你的数据是打开的文件在你自己的磁盘上。** 一个追加日志，封印成列段，格式和兼容性保证写在 [STABILITY.md](STABILITY.md) 和 [docs/design/storage.md](docs/design/storage.md) 中。 - **随时导出。** `GET /v1/export` 将所有内容以 CSV 或 JSONL 形式提供给你，JSONL 直接回滚到 `/v1/events`。 - **永远不需要我们。** 如果这个仓库明天消失，你的实例不会注意到。 ## 在你的编辑器中询问（重点） 这是代码感知的界面：你的编码代理拥有你的代码库，你的跟踪计划和 MCP 上的 smolanalytics，因此它用你自己的术语回答问题。询问 "PQR 页面的 MAU 是多少" 代理知道 PQR 是代码中的 `/pqr` 路由，然后为它查询 smolanalytics。（对于快速的数据问题，无需代码查找，仪表盘询问栏更快，无需设置。参见上面的 "两种询问方式"。） 连接一次： ```sh smolanalytics connect # 将其连接到你已安装的所有编码助手 ``` 就这样：重启编辑器并询问 *"本周用户在哪里流失？*。它 检测到已安装的助手并合并配置（保留你已经有的任何 MCP 服务器）。以 `<name>` 为目标： | 助手 | `connect <name>` | 它配置 | |---|---|---| | Claude Desktop | `claude` | `claude_desktop_config.json` | | Claude Code | `claude-code` | 为你运行 `claude mcp add` | | Cursor | `cursor` | `~/.cursor/mcp.json` | | Windsurf | `windsurf` | `~/.codeium/windsurf/mcp_config.json` | | VS Code (Copilot) | `vscode` | 用户 `mcp.json` （`servers` 键） | | Cline | `cline` | `cline_mcp_settings.json` | 任何 MCP 客户端都有效：它是一个标准的 stdio + Streamable-HTTP 服务器。 **使用 Lovable、Bolt、v0 或 Replit 构建？** 你不需要上述任何一个。 [注册](https://smolanalytics.com)，创建一个项目，它给你一个提示， 粘贴到你的应用构建器中。构建器的 AI 安装代码片段并将其线路 你的关键事件本身。从那时起，仪表盘用纯英文回答问题，晨间简报通过电子邮件发送：零代码，零终端。更多信息请参阅 [smolanalytics.com/for/lovable](https://smolanalytics.com/for/lovable)。 <details><summary>手动连接（或指向正在运行的/远程服务器的 HTTP）</summary> **stdio** （本地，无需服务器，直接读取你的数据文件）： ```json { "mcpServers": { "smolanalytics": { "command": "smolanalytics", "args": ["mcp"] } } } ``` **HTTP** （指向正在运行的实例，本地或远程，共享其实时数据）： ```json { "mcpServers": { "smolanalytics": { "url": "http://localhost:8080/mcp" } } } ``` **Claude Code, HTTP:** `claude mcp add --transport http smolanalytics http://localhost:8080/mcp` **Zed:** 添加到 `context_servers` 在设置。 **VS Code:** 顶级键是 `servers`，而不是 `mcpServers`. （当设置写密钥时，添加 `"headers": { "Authorization": "Bearer YOUR_KEY" }` 旁边 url。） </details> 然后直接在编写代码的窗口中询问： ``` 你 ▸ 激活情况如何，Pro 的转换率是否比免费版本更好？ AI ▸ 激活率为 62%（1,051 个注册用户中有 657 个达到“激活”）。 Pro 的转化率是免费用户的 2.4 倍：45% 注册用户 → 结账 vs 19% 免费。 泄漏是免费用户在激活 → 结账时发生的（仅 31% 继续）。想要激活后的路径吗？ ``` 你的模型获得 **47 工具 + 13 个内置提示**。编辑器运行 **整个** 东西，而不仅仅是查询： - **询问：** `whats_notable` （*要修复的结论），`overview`，`list_events`，`funnel`，`retention`，`trends`，`breakdown`，`web_overview` （流量一目了然），`lifecycle`，`stickiness`，`paths`，`groups` （B2B 账户），`recent_events`，`user_activity`，每个都可按属性筛选（`plan=pro`，`source=hn`，…）。 - **执行：** *"如果注册用户数量低于 10 人，请提醒我"* → `create_alert`; *"将警报发送到 Slack"* → `add_webhook`; *"跟踪付费用户作为一个群体"* → `create_cohort`; *"将该漏斗固定到我的仪表盘"* → `save_report`，以及每个的列表/删除。所有在你的编辑器中创建的东西都会立即出现在仪表盘上（相同的存储，一个真实来源）。保存的报告在仪表盘上每次访问时都会渲染，因此重复的指标永远不需要重新输入。 - **运行实例：** 重命名项目，设置时区和保留率，创建/撤销 API 密钥，完整的设置对等价，无需浏览器。 - **验证仪表化** （为 AI 辅助构建而构建）：编写跟踪的代理声明它与 `set_tracking_plan` 一起，然后 `instrumentation_health` 检查现实与计划一致：哪些事件流动，哪些从未到达，哪些预期属性缺失。循环关闭：*构建 → 仪表化 → 验证 → 监视*，都在编辑器中。 - **提示：** 13 个命名作业由 MCP 客户端原生支持：`instrument-my-app` （完整设置，端到端），`whats-broken-today` （早晨检查），`weekly-review` 和 `monthly-report` （创始级总结），`funnel-leak`，`launch-day`，`money-pages` （已经在触及的 SEO 收益），以及其他。完整的库及其每个读取的内容和答案形状：[docs/prompts.md](docs/prompts.md)。 ### 配备代理？使跟踪自动化 如果 Claude Code 或 Cursor 编写你的功能，它也可以编写你的仪表化： 一个块在你的仓库的 `CLAUDE.md` / `AGENTS.md` / `.cursorrules` 告诉你的代理添加 `track()` 每次它运输，保留 `smolanalytics.plan.json` 当前，并 使用 `smolanalytics plan check` 部署后验证事件实际流动。复制粘贴块和完整的构建 → 仪表化 → 验证循环：[docs/agents.md](docs/agents.md](https://github.com/Arjun0606/smolanalytics/blob/main/docs/agents.md). 已经在 PostHog 上？`plan check --source=posthog` 在你的现有 PostHog 项目上运行相同的门控，无需服务器，无需迁移。 ## 发送事件（2 分钟，零仪表化） 将代码片段粘贴进去，它会 **自动捕获页面浏览和点击事件**，让你可以获得真实的数据而无需手动标记事件。添加 `track()` 以获取关键时刻（注册，激活）以获得漏斗。 ```html <script src="https://YOUR_HOST/sdk.js"></script> <script> smolanalytics.init("YOUR_WRITE_KEY", { host: "https://YOUR_HOST" }); // 就是这样：页面浏览和点击被自动捕获。 // 可选，用于漏斗： smolanalytics.track("signup", { plan: "pro" }); smolanalytics.identify("user_123", { email: "a@b.com" }); // 登录时 </script> ``` … 或直接从任何语言的任何平台发送事件（单个事件或批量）： ```sh curl -X POST https://YOUR_HOST/v1/events \ -H "Authorization: Bearer YOUR_WRITE_KEY" \ -d '{"name":"signup","distinct_id":"user_123","properties":{"plan":"pro"}}' ``` ### 从任何平台：网页，移动设备，服务器 摄取是一个 HTTP 端点，因此 **移动应用，后端和所有其他设备都以相同的方式发送事件**。不需要沉重的 SDK： ```swift // iOS (Swift) var req = URLRequest(url: URL(string: "\(host)/v1/events")!) req.httpMethod = "POST"; req.setValue("Bearer \(key)", forHTTPHeaderField: "Authorization") req.setValue("application/json", forHTTPHeaderField: "Content-Type") req.httpBody = try JSONSerialization.data(withJSONObject: ["name": "signup", "distinct_id": userId]) URLSession.shared.dataTask(with: req).resume() ``` ```kotlin // Android (Kotlin / OkHttp) val body = """{"name":"signup","distinct_id":"$userId"}""".toRequestBody("application/json".toMediaType()) client.newCall(Request.Builder().url("$host/v1/events").addHeader("Authorization","Bearer $key").post(body).build()).enqueue(cb) ``` ```js // React Native / Node / js 后端 fetch(`${host}/v1/events`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` }, body: JSON.stringify({ name: "purchase", distinct_id: userId, properties: { amount: 工单 } }) }); ``` ```python # Python 后端 requests.post(f"{host}/v1/events", headers={"Authorization": f"Bearer {key}"}, json={"name": "signup", "distinct_id": user_id, "properties": {"plan": "pro"}}) ``` 浏览器 SDK 还增加了自动捕获 + 批量处理；其他地方，只需 5 行 POST。相同的引擎，相同的“在编辑器中询问”，相同的结论，无论您的产品运行在什么平台上。 甚至更简单：在 Cursor/Claude Code 中粘贴 *这* 并让它仪表化你的应用程序。 > “添加 smolanalytics：加载 `https://YOUR_HOST/sdk.js`，使用我的密钥初始化，并跟踪关键时刻（注册，激活）以及 `identify()` 登录。” **框架指南** （复制粘贴，每个 2 分钟）： [Next.js](docs/nextjs.md) · [React](docs/react.md) · [Vue](docs/vue.md) · [后端](docs/backend.md) （Node/Python/Go/Ruby/PHP） · [移动设备](docs/mobile.md) （iOS/Android/RN）。查看 [`examples/`](examples/) 以获取可运行的页面 + curl 脚本。 ## 比较 诚实版本：我们 **并不** 比大型工具更深入。赌注是不同形状的： | | smolanalytics | Plausible / Fathom | Mixpanel / Amplitude | PostHog | |---|:---:|:---:|:---:|:---:| | 漏斗 · 留存 · 路径 · 用户群体 | ✅ | ⚠️ Plausible: 付费层级 · Fathom: ❌ | ✅ | ✅ | | 网络分析（页面 · 来源 · 实时） | ✅ | ✅ | ⚠️ | ✅ | | 用简单英语提问 | ✅ **你的 AI，免费** | ❌ | 💲 他们的 AI | 💲 他们的 AI + MCP | | AI 的数据与仪表盘匹配 | ✅ **始终，如同引擎** | n/a | ⚠️ | ⚠️ 他们的文档： *"可能与 UI 不匹配"* | | 自主部署 | ✅ 一个二进制文件 | ✅ | ❌ | ⚠️ Kafka + ClickHouse 集群 | | 拥有你的数据 · 导出 | ✅ | ✅ | ⚠️ | ✅ | | 价格 | 免费 / 自主部署 | 💲 | 💲💲💲 | 免费层级 + 💲 | 关于准确性那一行：PostHog 的 MCP 是真实且优秀的，但它通过生成 HogQL 来回答问题，并且 [他们的文档](https://posthog.com/tutorials/mcp-analytics) 注意到结果 "有时与 PostHog 的仪表盘不同：采样、时区处理、默认过滤器、缓存"，建议 "验证 UI" 以确保重要的数据准确。我们的工具不会有差异：MCP 工具调用的是仪表盘渲染的相同的确定性报告，没有第二种路径导致数据不一致。 ## 我们永远不会添加的功能 分析工具的墓地是 "一个工具变成了九个"。会话重放、功能标志、A/B 测试、调查、数据仓库：其他工具做得很好，而将它们捆绑在一起就是你需要一个集群和一个定价计算器的原因。我们保持一个二进制文件，它可以准确回答关于你的事件的问题。如果你超越了这一点，你会知道，而且你的数据导出是干净的。 同样在永远不会添加的列表中：**多节点、集群、高可用性**。每个实例只有一个写入者，这就是为什么存储引擎不需要共识协议：崩溃恢复是重放一个日志，而不是选举领导者。当我们添加第二个节点时，我们继承分布式系统的税收，这使得其他工具在自主部署时需要一个周末。需要更多的隔离？运行更多实例（每个项目一个），这也是整个云的设计。 ## 部署（生产环境） 一个静态二进制文件，无 cgo，无集群。它可以在任何地方运行。 ```sh # Docker（持久事件日志在卷上） docker run -p 8080:8080 -v $PWD/data:/data \ -e SMOLANALYTICS_WRITE_KEY=$(openssl rand -hex 16) \ -e SMOLANALYTICS_PASSWORD=$(openssl rand -hex 12) \ ghcr.io/arjun0606/smolanalytics # Fly.io（持久卷 + 通过 fly.toml 的健康检查） fly launch --copy-config && fly deploy ``` **默认安全：** `serve` 绑定到 `127.0.0.1:8080`（仅本地）。要公开它，请设置 `ADDR=0.0.0.0:8080`，然后需要 **必填** 仪表盘密码：服务器在公共接口上拒绝未经身份验证的请求以提供真实数据（仅在受信任的网络上使用 `SMOLANALYTICS_ALLOW_UNAUTHENTICATED=1` 覆盖）。`demo` 免除（临时数据）。 配置（所有 env）：`ADDR`（默认 `127.0.0.1:8080`），`SMOLANALYTICS_DB`（事件日志路径），`SMOLANALYTICS_WRITE_KEY`（在摄入 + MCP 时需要密钥），`SMOLANALYTICS_PASSWORD`（仪表盘登录，公开服务器时必填），`SMOLANALYTICS_RETAIN_DAYS`（丢弃旧于 N 天的事件；默认：永久保留），`SMOLANALYTICS_MAX_EVENTS`（仅保留最新的 N 个事件，内存防护栏，以防止数据洪水降级为压缩而不是 OOM）。健康检查在 `/healthz`，版本信息在 `/version`。 **晨报，自主部署：** `smolanalytics brief` 打印脉搏（访客 + 事件与前一周的比较）和 "需要注意" 的发现，来自服务器使用的同一个事件日志（设置 `SMOLANALYTICS_DB` 为相同路径）。运行中的服务器还在 `GET /v1/brief` 处提供相同的摘要，以 JSON 格式，供您自行交付。每天早上用它发送： ```sh # 每天 8 点，通过电子邮件或直接发送到 Slack 0 8 * * * SMOLANALYTICS_DB=/data/smolanalytics.data smolanalytics brief | mail -s "analytics brief" you@example.com 0 8 * * * SMOLANALYTICS_DB=/data/smolanalytics.data smolanalytics brief --webhook=https://hooks.slack.com/services/XXX/YYY/ZZZ ``` 运行多个产品到一个实例？SDK 为每个事件标记 `site`，一旦多个站点报告，简报添加每个产品的细分：每月发送一次，一个简报涵盖所有产品。 从 **设置** (`/settings`) 管理所有内容：账户 + 密码、API 密钥、数据保留、事件分类、导出、Webhook、阈值警报和审计日志。 **无锁定：** 随时使用 `GET /v1/export?format=csv` 或 `?format=jsonl` 导出所有内容（JSONL 直接回滚到 `/v1/events`）。它也可以在导入时使用：`smolanalytics import` 从 PostHog、Umami 或任何事件 CSV 文件中重放历史记录，并保留原始时间戳。参见 [docs/migration.md](docs/migration.md)。 **备份：** 你的数据是普通文件，所以备份就是一份副本。最简单的配方是每晚运行导出端点的 cron 任务： ```sh 0 3 * * * curl -s -H "Authorization: Bearer $KEY" "https://YOUR_HOST/v1/export?format=jsonl" | gzip > /backups/events-$(date +\%F).jsonl.gz ``` 恢复只需一个 curl 请求即可恢复到 `/v1/events`，无论是在这个工具中还是在其他工具中。 **如果我们消失了：** 你们不会受到影响。MIT 二进制文件将永远运行，你们的事件存储在普通文件中，位于 **你们** 的磁盘或 **你们** 的存储桶中，导出只需一个 curl 请求。没有电话回家，没有许可服务器，也没有封闭的控制平面依赖于你们的数据。你们运行的开发环境与生产环境相同：没有单独的 "自主部署模式"，它是秘密的第二类版本。不要相信我们：磁盘格式及其兼容性保证在 [STABILITY.md](STABILITY.md) 和 [docs/design/storage.md](docs/design/storage.md) 中有详细说明，所以你们可以在发送单个事件之前验证退出路径。 ## 内部结构 事件存储方式（整个写入路径，一个二进制文件内）： ``` SDK / POST /v1/events │ ▼ 追加日志 ──（每批次 fsync，一个 ACK 表示数据已写入磁盘） │ 每 50k 事件密封 ▼ 不可变列式段（压缩、CRC校验，大约 7 字节/事件） │ 可选 ▼ S3 / R2 / Tigris （与历史大小无关的内存占用） ``` 只有一个写入者，即你的实例，这就是为什么它不需要共识协议、协调服务和集群。崩溃恢复是 "重放一个日志"，而不是 "重建一个仲裁"。完整的推理（以及我们已知放弃的内容）在 [docs/design/storage.md](docs/design/storage.md) 中；术语在 [glossary](docs/glossary.md) 中固定。 - `internal/{funnel,retention,trends,paths,engagement,groups,cohort,query}`：确定性分析引擎（每个报告，完全测试）。 - `internal/store`：具有三个后端接口的 `Store` 接口：内存、持久追加日志（单机）和列式段层（`store/segment` + `store/blob`），密封成本地磁盘或 S3/R2 上的压缩段。数十亿事件占用平面内存，约 7 字节/事件。 - `internal/mcp`：MCP 服务器（stdio + Streamable HTTP），"用你自己的 AI 提问" 层。 - `internal/api`：单二进制 HTTP 服务器：摄入、SDK、仪表盘、探索、设置、身份验证、Webhook、警报、审计。 - `cmd/smolanalytics`：二进制文件（`serve`、`demo`、`mcp`、`connect`、`gsc`、`import`、`brief`、`plan`、`scrub`）。 ```sh make demo # 种子 + 服务 make race # 测试与竞争检测器 ``` ## 不想运行它？→ smolanalytics 云 **自主部署是免费层级，无限制，永久免费。** 如果你不想运行服务器，或者你是一个 **团队**，[托管云](https://smolanalytics.com) 可以提供单二进制文件无法实现的功能： - **零运维：** 我们为每个项目托管一个隔离的实例；扩展、备份和正常运行时间由我们负责。 - **你的整个团队：** 邀请、角色、共享项目（开源软件设计为单操作员）。 - **每日简报：** 每天通过电子邮件 + Slack 发送你的 "需要关注" 的摘要，无需你维护服务器或配置 cron（自主部署等效：`smolanalytics brief` + cron）。 - **扩展 + 保留：** 数百万事件，更长的历史记录，无需运维。 云定价很简单：**14 天全功能试用**（所有功能，无需信用卡），然后从 **9 美元/月** 开始。超出部分不会锁定你的仪表盘。相同的产品，相同的 "在编辑器中提问"，相同的数据所有权，只是托管了。 **[开始试用 →](https://smolanalytics.com)** ## 贡献 欢迎 PR。保持小规模、正确且无依赖。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题：[SECURITY.md](SECURITY.md)。 ## 许可证 [MIT](LICENSE)，永久有效。无 CLA，无 rug-pull 重新授权：业务是托管云，而不是许可证。随意使用、分叉、托管、出售它的托管服务。 ## 展示 使用 smolanalytics？添加徽章，它可以帮助其他人找到该工具： ```md [](https://github.com/Arjun0606/smolanalytics) ``` [](https://github.com/Arjun0606/smolanalytics)