Outlit

Outlit SDK

Outlit 帮助客户成功团队保护并拓展长尾收入。它连接客户数据、监控客户流失风险和扩张机会，并将附有佐证的重点事项呈现给团队。

从产品指南开始，按照指引完成设置并创建第一个重点事项。如需通过程序访问，请参阅开发者和 Agent 指南。

此仓库包含 Outlit 的公开 SDK 和开发者集成包：浏览器、服务端、CLI、工具契约和 Pi 包，用于向 Outlit 发送客户信号，并从 Agent 工作流中查询客户上下文。此仓库不包含托管远程 MCP 服务的实现；如需 MCP、API 和 Agent 元数据，请使用下方 Outlit 官方发现端点。

软件包

此 monorepo 在 @outlit 作用域下包含以下软件包：

• @outlit/core - 核心 SDK 功能和基础客户端
• @outlit/browser - 浏览器专用 SDK，支持自动跟踪页面浏览
• @outlit/node - 用于服务端事件跟踪的 Node.js SDK
• @outlit/cli - Outlit 客户情报 CLI
• @outlit/tools - 用于 API 和 Agent 集成的客户情报工具契约和客户端辅助工具
• @outlit/pi - 提供 Outlit 客户情报工具和技能指南的 Pi 软件包

Agent 和爬虫发现

请使用以下官方资源来获取引用、构建由架构驱动的客户端以及设置 Agent，而不要将生成的规范或服务端元数据复制到此仓库：

界面	官方 URL	用途
文档	https://docs.outlit.ai	产品指南，以及 SDK、CLI、API、MCP 和客户上下文文档
面向 Agent 的文档索引	https://docs.outlit.ai/llms.txt	文档页面的机器可读索引
产品资源索引	https://www.outlit.ai/llms.txt	面向 Agent 的 SDK 软件包、文档、API 契约、MCP、CLI、Pi 和技能索引
OpenAPI 规范	https://docs.outlit.ai/openapi.json	公开 API 和数据接入界面的官方 OpenAPI 契约
API 目录	https://www.outlit.ai/.well-known/api-catalog	用于发现 API、MCP、OAuth、文档和支持资源的链接集
AI 目录	https://www.outlit.ai/.well-known/ai-catalog.json	Outlit API、MCP、技能和 SDK 资源的 Agentic 资源发现目录
MCP Registry 条目	https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.outlit/outlit	ai.outlit/outlit 的官方 MCP Registry 搜索界面
MCP 服务元数据	https://mcp.outlit.ai/.well-known/mcp/server.json	托管远程 MCP 服务的运行时元数据
MCP 服务卡片	https://mcp.outlit.ai/.well-known/mcp/server-card.json	托管远程 MCP 服务的运行时发现卡片
MCP 文档	https://docs.outlit.ai/ai-integrations/mcp	使用工作区 URL 和 OAuth 连接远程 MCP 客户端
Agent 技能	https://docs.outlit.ai/ai-integrations/skills	官方 outlit 和 outlit-sdk 技能安装指南

托管的 MCP 服务和 OAuth 元数据位于 mcp.outlit.ai；此 SDK 仓库是公开软件包和开发者集成界面。

安装

根据集成场景选择合适的包：

包	安装	适用场景
@outlit/browser	npm install @outlit/browser	浏览器应用、React、Next.js、Vue、Nuxt、SvelteKit、Angular、Astro，以及通过 script 标签进行跟踪
@outlit/node	npm install @outlit/node	Node.js 服务、API 路由、作业、webhook、CLI、桌面应用主进程，以及原生 JavaScript 运行时
@outlit/core	npm install @outlit/core	不需要浏览器或 Node 运行时辅助工具的底层自定义 SDK 实现
@outlit/cli	npm install -g @outlit/cli	在终端中访问 Outlit 客户情报和设置工作流
@outlit/tools	npm install @outlit/tools	需要类型化 Outlit 工具网关契约和客户端辅助工具的自定义 API 或 Agent 集成
@outlit/pi	npm install @outlit/pi	需要 Outlit 客户情报工具和技能指引的 Pi Agent
Rust crate	cargo add outlit	Rust 后端、CLI 和 Tauri 后端

跟踪 SDK 示例：

# For browser applications
npm install @outlit/browser

# For Node.js applications
npm install @outlit/node

# For custom implementations
npm install @outlit/core

快速开始

浏览器

import { Outlit } from '@outlit/browser'

const outlit = new Outlit({
  publicKey: 'pk_xxx',
  trackPageviews: true,
  trackForms: true,
})

// Identify a user
outlit.user.identify({
  email: '[email protected]',
  traits: { name: 'John Doe' },
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  customerTraits: { plan: 'pro' },
})

// Track events
outlit.track('button_clicked', {
  button_id: 'signup',
  page: '/homepage',
})

// Track meaningful product activity. Core derives lifecycle stages from
// ordinary events, including your selected activation event.
outlit.track('onboarding_completed', { flow: 'self_serve' })

使用单例 API

import { init, track, user } from '@outlit/browser'

// Initialize once at app startup
init({ publicKey: 'pk_xxx' })

// Then use anywhere
track('page_viewed', { page: '/home' })
user().identify({
  email: '[email protected]',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
})
track('subscription_upgraded', { plan: 'pro' })

在 React 中使用

import { OutlitProvider, useOutlit } from '@outlit/browser/react'

// Wrap your app
function App() {
  return (
    <OutlitProvider publicKey="pk_xxx">
      <MyComponent />
    </OutlitProvider>
  )
}

// Use in components
function MyComponent() {
  const { track } = useOutlit()
  
  return (
    <button onClick={() => track('onboarding_completed')}>
      Click me
    </button>
  )
}

Node.js

import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  publicKey: 'pk_xxx',
})

// Track server-side events (requires identity)
outlit.track({
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  eventName: 'api_request',
  properties: {
    endpoint: '/api/users',
    method: 'GET',
    status: 200,
  },
})
// `customerId`-only track events are valid immediately.
// When you later call identify() with the same customerId and an email,
// Outlit can link that account/workspace to the customer resolved from email.

// Identify a user
outlit.user.identify({
  email: '[email protected]',
  traits: { plan: 'pro' },
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  customerTraits: { plan: 'pro' },
})

// Track ordinary product events. Billing status comes from verified
// integrations such as Stripe, not authoritative SDK commands.
outlit.track({
  customerId: 'cust_123',
  eventName: 'subscription_upgraded',
  properties: { plan: 'pro' },
})

// Flush events before shutdown
await outlit.flush()

功能

• 现代 TypeScript - 全面支持 TypeScript，并提供类型定义
• 支持 Tree-shaking - 通过双 ESM/CJS 导出优化打包体积
• 事件排队 - 自动批处理和刷新事件
• 多平台 - 为浏览器和 Node.js 提供独立的包
• 自动跟踪 - 在浏览器中自动跟踪页面浏览
• 中间件支持 - 轻松集成 Express 等框架
• 身份持久化 - 持久化用户 ID 和匿名 ID
• 高性能 - 开销极低，批处理高效
• 类型安全 - 全面支持 TypeScript 和严格类型

示例

• Pi Agent - 使用 @outlit/pi 在 Pi 中构建客户情报 Agent

开发

本项目采用现代 monorepo 设置，并使用以下工具：

• Bun - 快速的一体化 JavaScript 运行时和包管理器
• Turbo - 用于编排 monorepo 的构建系统
• TypeScript - 类型安全的 JavaScript
• tsup - 快速的 TypeScript 打包器
• Biome - 快速的代码检查和格式化工具
• Playwright - 端到端测试
• Changesets - 版本管理和变更日志

设置

# Install dependencies
bun install

# Build all packages
bun run build

# Run tests
bun run test

# Lint code
bun run lint

# Type check
bun run typecheck

# Format code
bun run format

项目结构

outlit-sdk/
├── .github/workflows/   # CI/CD workflows
├── examples/
│   └── pi-agents/       # Example Pi agents using @outlit/pi
├── packages/
│   ├── browser/         # Browser SDK with React bindings
│   ├── cli/             # Outlit CLI
│   ├── core/            # Shared types and utilities
│   ├── node/            # Node.js SDK
│   ├── pi/              # Pi package for Outlit tools
│   ├── tools/           # Customer intelligence tool contracts
│   └── typescript-config/  # Shared TypeScript configs
├── package.json         # Root package with workspace config
├── bun.lock             # Bun lockfile
├── turbo.json           # Turbo build configuration
└── biome.json           # Biome linter/formatter config

创建 Changeset

进行需要发布的更改时，请创建一个 changeset：

bunx changeset

系统会提示你：

1. 选择受影响的包
2. 选择版本升级类型（patch、minor、major）
3. 编写更改说明

changeset 文件会随你的 PR 一起提交，并用于在发布时生成变更日志。

CI/CD

工作流

• CI（ci.yml）- 在 PR 上运行：代码检查、类型检查、构建、测试
• 发布（release.yml）- 在 main 上运行：向 npm + CDN 发布 canary，创建版本 PR 或发布稳定版本
• 验证 CDN 身份验证（verify-cdn-auth.yml）- 仅手动运行：检查 Workload Identity Federation 交换和 CDN 读取权限；可选的 verify_write 输入会在 __compliance_checks/ 下写入并删除一个很小的测试对象

稳定版本发布有意与 SDK 源代码合并分开进行。有关 Version Packages 检查清单，以及协调契约时必须遵循的先发布 Core 生产版本、再发布稳定 SDK 的顺序，请参阅 docs/release-coordination.md。

必需的密钥

对于负责设置仓库的维护者：

密钥	描述
NPM_TOKEN	具有 @outlit 作用域发布权限的 npm 访问令牌

CDN 部署通过 Workload Identity Federation 向 Google Cloud 进行身份验证，而不是使用已存储的服务账号密钥。维护者需要配置以下仓库变量：

变量	描述
GCP_WORKLOAD_IDENTITY_PROVIDER	完整的 WIF 提供方资源名称（projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>）
GCP_SERVICE_ACCOUNT	部署服务账号邮箱；该账号在 cdn.outlit.ai 存储桶上具有 Storage Object Admin 权限

创建 NPM_TOKEN

1. 前往 npmjs.com 并登录
2. 转到 Access Tokens → Generate New Token → Granular Access Token
3. 设置权限：对 @outlit 包具有读取和写入权限
4. 复制令牌，并在 GitHub 中将其添加为 NPM_TOKEN 密钥

创建 GCP Workload Identity 设置

1. 前往 Google Cloud Console
2. 转到 IAM & Admin → Service Accounts
3. 使用部署服务账号（github-actions-cdn-deploy）
4. 在 cdn.outlit.ai 存储桶上授予“Storage Object Admin”角色
5. 为此仓库创建专用的 Workload Identity Pool，并为 GitHub 配置 OIDC 提供方（颁发者为 https://token.actions.githubusercontent.com）；通过属性条件，将其限制为此仓库的不可变 ID，以及 refs/heads/main 上的 release/verify-cdn-auth 工作流
6. 在服务账号上向该池的 attribute.repository_id principalSet 授予 roles/iam.workloadIdentityUser
7. 将 GCP_WORKLOAD_IDENTITY_PROVIDER 和 GCP_SERVICE_ACCOUNT 添加为仓库变量

不会创建或在 GitHub 中存储服务账号密钥 JSON。

CDN 部署

浏览器 SDK IIFE 包将部署到 Google Cloud Storage：

路径	描述
/canary/outlit.js	来自 main 分支的最新版本（缓存 5 分钟）
/stable/outlit.js	最新稳定版（缓存 1 年）
/v{version}/outlit.js	不可变的版本化发布（缓存 1 年）

npm 标签：

标签	描述
latest	稳定版（npm install @outlit/browser）
canary	来自 main 的最新版本（npm install @outlit/browser@canary）

手动部署（需要 gcloud CLI）：

cd packages/browser && bun run deploy:canary   # Deploy to canary
cd packages/browser && bun run deploy:stable   # Deploy to stable (requires confirmation)
cd packages/browser && bun run deploy:version  # Deploy versioned release

文档

• 开发者文档
• 浏览器 SDK
• Node.js SDK
• Rust SDK
• API 参考
• OpenAPI 规范
• MCP 集成
• Agent 技能

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

许可证

Apache-2.0——详情请参阅 LICENSE。

支持

• 问题：GitHub Issues
• 文档：文档