开发者文档

Docs

快速上手、四个 SDK、16 个模块、约 270 个端点。封闭 Beta——我们只发布真正交付的内容，而非我们但愿存在的内容。

Quickstart

几分钟内发出第一个事件

安装 → 初始化 → 追踪。Web 与服务端身份已为你缝合，注册表契约在 CI 中强制执行。

01
安装这些包
Bun、pnpm 或 npm——任你选择。零依赖的浏览器包 gzip 后仅 8.1 KB，服务端 SDK 已在 Node 20+ 与 Bun 上测试通过。
```
bun add @gurulu/web @gurulu/node
```
02
在浏览器中追踪
用 publicKey 初始化——其余一切自动完成：anonymous_id（UUIDv7）、会话、GCM v2 授权状态，以及 5 个自动采集信号（click、pageview、form_submit、scroll、rage_click）。
```
import { gurulu } from '@gurulu/web';

gurulu.init({
  publicKey: 'pk_live_xxx',
  endpoint: 'https://ingest.gurulu.io',
});

gurulu.track('signup_completed', { plan: 'pro' });
```

在服务端验证结果

从你的服务端发送资金流转与 signup_completed 类事件——这样用户的浏览器就无法伪造它们。personId 为必填，归因从这里触发。

import { gurulu } from '@gurulu/node';

const client = gurulu({
  secretKey: process.env.GURULU_SECRET_KEY,
});

await client.track('purchase_completed', {
  personId: user.id,
  amount: 149,
  currency: 'EUR',
});

04
把注册表当作契约来用
事件名不是自由字符串——它们由注册表通过带类型的代码生成而来。在 CI 中运行 `gurulu validate`，契约漂移会让 PR 失败。
```
gurulu pull               # registry → typed code-gen
gurulu validate           # contract drift check
gurulu push events.ts     # add/update event contracts
```

SDK 与工具

4 个通道，4 个包

脚本（浏览器）、SDK（服务端）、CLI（注册表）与 MCP（Cursor、Claude Code、Lovable）。全部在 NPM 上公开。

MCP 服务器

@gurulu/mcp-server

list_events、add_event、validate_event 等工具。你的 AI 编辑器可以读取注册表——它不再瞎猜 `bet.placed`，而是改用注册表里的 `bet_placed`。

claude mcp add gurulu -- npx -y @gurulu/mcp-server

Cursor / Claude Code / LovableDetails

Web SDK

@gurulu/web

零依赖浏览器包。5 个自动采集信号 + 手动 track + identify + 授权 + 可选加入的会话回放（第 2 阶段）。或者通过 t.js CDN 投放一行脚本标签即可。

bun add @gurulu/web

8.1 KB gzipDetails

服务端 SDK

@gurulu/node

基于 secretKey 的结果验证、批量刷写、23 个 Webhook 校验器（Stripe、Shopify、LemonSqueezy、Custom 及另外 19 个），以及 Hono/Express/Fastify 中间件。

bun add @gurulu/node

Node 20+ · Bun · EdgeDetails

CLI

@gurulu/cli

gurulu init / pull / push / validate / doctor。把注册表接入你的 Git 流程——events.ts 是唯一真相来源，漂移在 CI 中被捕获。

bun add -g @gurulu/cli

@gurulu/cliDetails

模块目录

第 0 阶段 + 第 1 阶段 — 16 个模块

每个模块交付了多少张 Postgres 表、ClickHouse 视图与 REST 端点——一目了然。

Module

Package

Endpoints

Phase

M01

auth-tenant@gurulu/auth

@gurulu/auth

10 PG

—

22 EP

M02

storage@gurulu/db

@gurulu/db

1 PG

12 CH

—

M03

observability-own@gurulu/observability

@gurulu/observability

—

3 CH

5 EP

M04

consent-engine@gurulu/consent

@gurulu/consent

5 PG

—

15 EP

M05

identity-engine@gurulu/identity

@gurulu/identity

6 PG

2 CH

8 EP

M06

event-registry@gurulu/registry

@gurulu/registry

6 PG

—

19 EP

M07

event-health@gurulu/health

@gurulu/health

5 PG

4 CH

11 EP

M08

attribution-engine@gurulu/attribution

@gurulu/attribution

4 PG

3 CH

20 EP

M09

ingest-api@gurulu/ingest

@gurulu/ingest

4 PG

3 CH

11 EP

M10

event-pipeline@gurulu/pipeline

@gurulu/pipeline

2 PG

3 CH

5 EP

M11

sdk-web@gurulu/web

@gurulu/web

—

M12

sdk-server@gurulu/node

@gurulu/node

—

M13

playground@gurulu/playground

@gurulu/playground

4 PG

—

16 EP

M14

cli-mcp@gurulu/cli + mcp-server

@gurulu/cli + mcp-server

—

15 EP

M15

dashboardapps/dashboard

apps/dashboard

—

2 EP

M16

notifications@gurulu/notifications

@gurulu/notifications

5 PG

—

15 EP

M17

experiments@gurulu/experiments

@gurulu/experiments

2 PG

1 CH

8 EP

M18

popups@gurulu/activation

@gurulu/activation

1 PG

1 CH

7 EP

M19

tours@gurulu/activation

@gurulu/activation

2 PG

—

6 EP

M20

personalization@gurulu/activation

@gurulu/activation

1 PG

—

6 EP

M21

boardsapps/dashboard

apps/dashboard

2 PG

—

7 EP

M22

llm-analytics@gurulu/registry + web

@gurulu/registry + web

1 PG

2 CH

4 EP

M23

heatmaps@gurulu/web

@gurulu/web

—

2 CH

3 EP

M24

observability-suite@gurulu/observability

@gurulu/observability

3 PG

3 CH

7 EP

PG = Postgres 表 · CH = ClickHouse 表或物化视图 · EP = 公开 REST 端点

模块指南

新模块，步步上手

受众、目的地、联盟、AI 晨间摘要、playground crawler 的操作指南。

受众

把 cohort 转成实时、自动同步的受众。

目的地

Meta CAPI + Google Ads + Webhook — 凭据 KMS 加密。

联盟计划

Stripe Connect Express + 20-30% 阶梯佣金，12 个月经常性。

AI 晨间摘要

每天早晨的 workspace 摘要，5 模型永不掉线 fallback 链。

Playground 爬虫

JS-heavy SPA 的服务端 crawl + pattern detection。

API 速查表

REST 表面——分组呈现

从第 0 + 1 阶段表面中精选的端点。完整列表（约 270 个）随封闭 Beta 的租户接入一并提供。

认证与租户

魔法链接为主，OAuth Google + GitHub PKCE S256 为辅。无需密码。

POST/v1/auth/magic-link
POST/v1/auth/magic-link/verify
GET/v1/auth/oauth/:provider
POST/v1/auth/session/refresh
POST/v1/auth/session/revoke
POST/v1/auth/api-keys

Ingest

公开数据平面——https://ingest.gurulu.io。校验关卡（接受 / 警告 / 隔离 / 拒绝）在接入时运行。

POST/v1/track
POST/v1/batch
POST/v1/identify
POST/v1/alias
POST/v1/webhook/:provider

事件注册表

真相层的契约来源。强制 snake_case；为 3 种语言（TS、Python、Swift）生成代码。

GET/v1/registry/events
POST/v1/registry/events
GET/v1/registry/events/:key
POST/v1/registry/validate
GET/v1/registry/code-gen
GET/v1/registry/packs

Identity

7 步解析、3 级置信度、仅追加的合并账本。每一次合并都可逆。

POST/v1/identity/resolve
GET/v1/identity/person/:id
GET/v1/identity/person/:id/timeline
POST/v1/identity/merge
GET/v1/identity/merge-ledger

事件健康度

ML 异常 + 去重 + 覆盖率 + CAPI 不匹配。把 SDK 发出的内容与你的服务端实际收到的内容相比对。

GET/v1/health/events
GET/v1/health/events/:key
GET/v1/health/anomalies
GET/v1/health/coverage
POST/v1/health/dedup-check

Attribution

客户自定义策略 + 多模型（首次 / 末次 / 线性 / 时间衰减 / 位置 / 数据驱动）+ 溯源轨迹。

POST/v1/attribution/policy
POST/v1/attribution/compute
GET/v1/attribution/touchpoints/:personId
GET/v1/attribution/explain/:outcomeId

授权与 DSR

GCM v2，与 GDPR / CCPA / KVKK 对齐。DSR 导出 + 遗忘队列，SLA 为 60 秒。

POST/v1/consent
GET/v1/consent/:personId
POST/v1/consent/dsr/export
POST/v1/consent/dsr/forget

管理与运维

工作区、成员、审计日志、healthz。https://api.gurulu.io 是控制平面。

GET/v1/workspaces
POST/v1/workspaces/:id/members
GET/v1/audit-log
GET/v1/healthz

认证：Bearer JWT（用户）或 pk_/sk_ API 密钥（服务端到服务端）。所有响应均为 UTF-8 JSON，错误遵循 RFC 7807 problem+json。

数据模型

Universe Kernel——契约化且可解释

Universe Kernel 原则：每一个事件、每一张表、每一个端点从第一天起就承载完整的字段集合。界面随后才上线，数据形状永不扩张。

必填字段

每一个事件、每一行数据都携带这套字段——日后无需 ALTER TABLE。Universe Kernel 是强制项。

tenant_id
workspace_id
anonymous_id | person_id
session_id
source_context
confidence
consent_state
health_status

3 类事件

禁止混用类别——不同的接入、不同的归因、不同的报告。

Interaction浏览器自动采集：click、pageview、scroll。并非结果。
Intentadd-to-cart、checkout_started 等意图信号。从第一天起就在数据模型中分离，并在第 2 阶段及之后产品化。
Outcomepurchase_completed、signup_completed——服务端事件。归因从这里触发。

校验关卡

接入时让每一个事件依据注册表经过 4 项裁决。契约漂移会在 CI 中让 PR 失败——它绝不会抵达生产环境。

acceptwarnquarantinereject

深入了解

Docs

几分钟内发出第一个事件

安装这些包

在浏览器中追踪

在服务端验证结果

把注册表当作契约来用

4 个通道，4 个包

MCP 服务器

Web SDK

服务端 SDK

CLI

第 0 阶段 + 第 1 阶段 — 16 个模块

新模块，步步上手

受众

目的地

联盟计划

AI 晨间摘要

Playground 爬虫

REST 表面——分组呈现

认证与租户

Ingest

事件注册表

Identity

事件健康度

Attribution

授权与 DSR

管理与运维

Universe Kernel——契约化且可解释

必填字段

3 类事件

校验关卡

相关页面