用途：面向在 Opik 的 sdks/typescript 目录中做开发的场景，说明 TypeScript SDK 的设计模式与改动约束。
主要能力与架构：SDK 采用分层、默认非阻塞的设计，数据先缓冲再异步刷新到后端。要求 Node >= 18，提供 ESM 与 CJS 两种构建。层间流向为：公共 API → OpikClient → 领域对象（Trace/Span）→ BatchQueues → REST Client → 后端。
必要用法：退出前必须刷新缓冲，尤其 CLI 与测试中，使用 await client.flush(); 或全局 await flushAll();。领域对象不负责 HTTP：如 trace.update({ metadata: { key: 'value' } }) 与 trace.end() 只入队更新，不应从领域对象直接调用 REST。公共 API 应从 'opik' 导出，例如 export { Opik, track, flushAll } from 'opik';，不要暴露生成的客户端（如从 'opik/rest_api' 导入 TracesApi）。批量语义：更新等待待处理的创建，删除等待创建与更新，flush() 按顺序刷新所有队列，去抖窗口可通过 OpikConfig 配置。错误处理：HTTP 失败抛出 OpikApiError、OpikApiTimeoutError，404 转译为领域错误如 DatasetNotFoundError、ExperimentNotFoundError，不要吞掉错误，日志需带上下文。
集成规范：集成仅包装公共 API，适配器保持轻薄且非阻塞，必要时提供 flush() 逃生口。修改依赖或最低版本时，需在同一 PR 中更新并核验 README.md 及各集成 README 中的版本引用。测试参考 testing.md 中的 Vitest 模式、mock 与 flush 时机。
限制：以上为资料所载规范，未提供性能指标、收费与平台支持范围等额外信息。