# @cherrystudio/analytics-client 中文文档

规范地址：https://npmcn.com/package/%40cherrystudio/analytics-client/

版本：1\.4\.0
npm 元数据更新时间：2026-09-20T05:19:27.138Z
中文译文更新时间：2026-11-09T12:33:52.985Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cherrystudio/analytics-client
原文对照：https://npmcn.com/package/%40cherrystudio/analytics-client/?lang=original
项目主页：https://github.com/CherryHQ/cherry-studio-analytics#readme
源码仓库：https://github.com/CherryHQ/cherry-studio-analytics

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.7 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：0 个
- peer 依赖：typescript \>=4\.7\.0
- 首次发布：2026-02-08T08:58:02.477Z
- 最新版本发布：2026-09-20T05:19:26.965Z
- 近 30 天下载量：19085（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

Cherry Studio应用程序的分析客户端

## 安装

```sh
npm install @cherrystudio/analytics-client
```

也可以使用：`pnpm add @cherrystudio/analytics-client`、`yarn add @cherrystudio/analytics-client`、`bun add @cherrystudio/analytics-client`

## README

# @cherrystudio/分析-客户

樱桃工作室应用的分析客户SDK. 支持以自动缓冲和冲出来进行批量事件跟踪.

## 安装

```bash
npm install @cherrystudio/analytics-client
# or
pnpm add @cherrystudio/analytics-client
# or
yarn add @cherrystudio/analytics-client
```

## 快速启动

```typescript
import { AnalyticsClient } from '@cherrystudio/analytics-client'

// Initialize the client
const analytics = new AnalyticsClient({
  clientId: 'user-uuid-here',
  channel: 'cherry-studio',
})

// Track token usage
analytics.trackTokenUsage({
  provider: 'openai',
  model: 'gpt-4',
  input_tokens: 100,
  output_tokens: 200,
})

// Drain within the shutdown budget before app exit
await analytics.destroy()
```

## API 密码

### 构造选项

```typescript
interface AnalyticsClientOptions {
  /** Analytics service base URL (default: https://analytics.cherry-ai.com) */
  baseUrl?: string
  /** Client unique identifier (UUID) */
  clientId: string
  /** Channel/application name */
  channel: string
  /** Enable automatic batching (default: true) */
  autoBatch?: boolean
  /** Auto-flush threshold and maximum events per request (default: 10) */
  batchSize?: number
  /** Maximum queued events; newest events drop on overflow (default: 1000) */
  maxQueueSize?: number
  /** Queued plus active requests across all endpoints (default: 100), concurrency: 1 */
  maxPendingRequests?: number
  /** Maximum serialized bytes per event (default: 65536) */
  maxEventBytes?: number
  /** Maximum serialized bytes per event request (default: 262144) */
  maxBatchBytes?: number
  /** Batch flush interval in milliseconds (default: 5000) */
  flushInterval?: number
  /** Request timeout in milliseconds (default: 10000) */
  timeout?: number
  /** Custom fetch function (for Node.js or custom implementations) */
  fetch?: typeof fetch
  /** Retry/backoff settings; defaults to three retries */
  retry?: RetryOptions
  /** Additional request headers */
  headers?: Record<string, string>
  /** Called when an error occurs */
  onError?: (error: Error) => void
}
```

### 方法

#### `trackTokenUsage(data, timestamp?)`

跟踪 AI 符号使用 .

提供者为 `local-embedding`,或者其输入和输出符号计数均为0,被忽略,不排队或发送到分析服务.

```typescript
analytics.trackTokenUsage({
  provider: 'openai',      // AI provider name
  model: 'gpt-4',          // Model name
  input_tokens: 100,       // Input token count
  output_tokens: 200,      // Output token count
})

// With custom timestamp (for offline tracking)
analytics.trackTokenUsage(data, new Date('2025-01-15T10:30:00Z'))
```

#### `track(eventType, data, timestamp?)`

跟踪一个通用事件 。 用于自定义事件类型 。 数据得到验证 输入时被快照, 以及当前客户端的ID和事件时间 . 非 JSON 数据、 无效/ 未定义数据、 无效日期和超大小事件 个人通过 `onError`不给这批货下毒.

```typescript
analytics.track('custom_event', {
  action: 'button_click',
  value: 42,
})
```

#### `flush()`

最多在请求中, 在呼叫开始时排队的模糊事件 `batchSize` 事件。 返回确认的合并计数,或 `null` 如果队列为空。 同步呼叫者共享活动冲出. 在冲出时添加的事件等待下一场冲出 .

```typescript
const result = await analytics.flush()
// { success: true, count: 5 }
```

#### `sendImmediate(eventType, data, timestamp?)`

立即发送一个事件 不批量.

```typescript
await analytics.sendImmediate('token_usage', {
  provider: 'anthropic',
  model: 'claude-3',
  input_tokens: 50,
  output_tokens: 150,
})
```

#### `setClientId(clientId)`

更新未来事件的客户端ID(如用户登录后). 排队事件 保留其原始身份; 不同身份分别发送 批发。 习惯 `Client-Id` 标题跟踪每个请求的身份.

```typescript
analytics.setClientId('new-user-uuid')
```

#### `getQueueSize()`

在队列中获取当前待定事件的数量 .

```typescript
const pending = analytics.getQueueSize()
```

#### `destroy(options?)`

关闭客户端,停止接受新工作,并等待所有终点和解. 默认是一个优雅的排水 **总预算30秒**,包括: 冷却和回击。 期满时,请求中止,其余数据为 本地丢弃。 结果报告终生交货计数器和 `timedOut`。 。 。 . 屡相召还同相允. 立即取消也可以 中断已经运行的优雅关闭.

```typescript
const result = await analytics.destroy({ timeoutMs: 30000 })
// { acknowledgedEvents, discardedEvents, pendingEvents: 0, pendingRequests: 0, timedOut }

// Consent revocation: cancel in-flight requests and cooldowns, discard queued data.
await analytics.destroy({ flush: false })
```

撤销同意的申请必须使用 `flush: false`;仅仅取消 获取包装器无法中断 SDK 冷却 。 关机后, `track()` 拒绝报告通过 `onError`;即时/活动发送拒绝 承诺。 不重复使用已关闭的客户端 .

#### `getDeliveryStats()`

返回寿命的本地计数器 : `acknowledgedEvents`, (中文(简体) ), `discardedEvents`, (中文(简体) ), `pendingEvents` (包括飞行中活动)和 `pendingRequests`活动 请求只帮助进行请求计数。 忽略的象征性事件不在此列. `discardedEvents` 表示 SDK 不再保留事件; 模糊的网络 失败可能意味着服务器已经接受了它 。 这些柜台不是帐单 或服务器持续性保证. `getQueueSize()` 只计算已排队的批次事件.

## 实例

### 电子辅助

```typescript
import { AnalyticsClient } from '@cherrystudio/analytics-client'
import { app } from 'electron'

const analytics = new AnalyticsClient({
  clientId: getMachineId(),
  channel: 'cherry-studio',
  onError: (error) => console.error('Analytics error:', error),
})

// Track usage
analytics.trackTokenUsage({
  provider: 'openai',
  model: 'gpt-4',
  input_tokens: 100,
  output_tokens: 200,
})

// Flush on app quit
app.on('before-quit', async (event) => {
  event.preventDefault()
  await analytics.destroy()
  app.exit()
})
```

### 有节点的节点.js

```typescript
import { AnalyticsClient } from '@cherrystudio/analytics-client'
import fetch from 'node-fetch'

const analytics = new AnalyticsClient({
  clientId: 'server-instance-id',
  channel: 'cherryin-backend',
  fetch: fetch as unknown as typeof globalThis.fetch,
})
```

### 禁用自定义

```typescript
const analytics = new AnalyticsClient({
  clientId: 'user-uuid',
  channel: 'cherry-studio',
  autoBatch: false, // Disable auto batching
})

// Manually send each event
await analytics.sendImmediate('token_usage', { ... })
```

### 自定义批次设置

```typescript
const analytics = new AnalyticsClient({
  clientId: 'user-uuid',
  channel: 'cherry-studio',
  batchSize: 50,        // Flush when 50 events accumulated
  flushInterval: 10000, // Or every 10 seconds
})
```

## 许可证

麻省理工学院

## 交货和重试限制

这个SDK提供了最佳的,内相遥测. 每批货最多可以 `1 + retry.maxRetries` 请求尝试(默认:共四次)。 一旦预算 已用尽,或发生不可弥补的错误,尝试的批次是: **丢弃**, (中文(简体) ), 不放回队列中。 手册 `flush()` 拒绝; 自动冲出报告 结束 `onError`。失败的冲出 `AnalyticsFlushError` 带有 `result` 毕生送货柜台的快照 冲浪在初始时继续穿过其他批次 在报告第一次失败前快照; 一个错误批次无法屏蔽 数据背后。 在冲出时添加的事件等待下一场冲出 .

HTTP 408、429和5xx回复和支持的网络错误可通过 默认; 其他 HTTP 错误不是 . `retryAllErrors` 默认为 `false`。 。 。 . `Retry-After` (秒或 HTTP 日期) 设置一个全客户端的冷却器 分批事件、即时事件和活动要求。 蝙蝠侠留在记忆中 在等待的时候,等待是不会减少尝试的. `retry.maxDelay` (默认) 30秒)的盖子只有指数回放;更长的服务器冷却被尊重, 包括在当前批次用完复试之后。 短暂的失败也 适用于后续批次。 HTTP 204 确认请求 没有JSON尸体, 并计算所有提交的事件 承认。 报告无效的HTTP答复机构 因为服务器可能已经接受了事件.

`batchSize` 是自动冲出阈值和最大请求批次 尺寸. `maxQueueSize` 默认为1,000起未决事件,不包括飞行中事件 批号。 完成后,最新事件将放弃,并通过 `onError`。 。 。 . 所有终点均采用单向请求道. `maxPendingRequests` 队列已加 活动请求( 默认 100); 立即/ 活动请求在溢出时被拒绝 . 批量冲出等待容量,而不是丢弃普通批量. `batchSize` 财务报告和审定财务报表 `maxBatchBytes` 二者都制约了批量,以及 `maxEventBytes` 限制个别事件。 所有字节限制都是UTF-8序列大小.

`destroy()` 在总时间内排出被否决的有效批次 预算。 超时取消工作; 它不会绕过服务器冷却 。 呼叫者 离开前必须等待关闭。 待定的事件不保存到磁盘中 .

这些界限可以防止无限期队列重放, 但不能提供精确的一次 发送: 服务器接受后网络超时仍可导致限制 重试。 可靠的分解需要稳定的事件ID和服务器侧 一能为相. 失败/过多的事件不会持续到以后恢复.

## 常见问题

### @cherrystudio/analytics-client 是什么？

Cherry Studio应用程序的分析客户端

### 如何安装 @cherrystudio/analytics-client？

在项目目录运行 npm install @cherrystudio/analytics-client，或使用 pnpm add / yarn add / bun add。

### @cherrystudio/analytics-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cherrystudio/analytics-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cherrystudio/analytics-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cherrystudio/analytics-client 可以商用吗？

@cherrystudio/analytics-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cherrystudio/analytics-client 的下载量有多少？

根据 npm 官方下载统计，@cherrystudio/analytics-client 在 2026/10/10 – 2026/11/08 这 30 天内被下载 19,085 次，日均约 636 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cherrystudio/analytics-client 还在维护吗？

最新版本 1\.4\.0 发布于 2026/09/20（1 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。