维护指南

测试

在包目录运行测试和类型检查（不能从 repo root 直接跑测试）：

bun test ./test --timeout 30000
bun typecheck

测试覆盖：

文件	覆盖点
observer.test.ts	observer/run/generation/tool/alias/score/auto-close
langfuse-direct.test.ts	Langfuse observation 创建、trace id、generation、tool、reasoning、score、release/version
redactor.test.ts	内置脱敏、自定义规则、递归结构、容错
flush-gate.test.ts	pending 注册、超时、waitAll

Checklist

修改类型定义

改 src/types.ts 或 transports/types.ts 时：

• 同步更新 AgentRun、LangfuseDirectTransport 和 API 文档

修改生命周期

改 generation/tool/run 生命周期时：

• 补 observer.test.ts
• 确认 OpenCode adapter 事件映射是否需要同步调整

修改 Langfuse 上报字段

• 补 langfuse-direct.test.ts
• 在 Langfuse UI 验证 trace/generation/span 展示

升级 Langfuse 或 OpenTelemetry 依赖

升级 @langfuse/* 或 @opentelemetry/* 时，重点验证：

1. findHeaderSlot() — 遍历 OTEL exporter 内部结构刷新 headers，需验证 token 刷新仍有效
2. applyMaskInPlace — 覆盖脱敏范围，确认 attribute key 没有变化

修改脱敏规则

• 必须新增 redactor.test.ts
• 避免宽数字规则误伤 metadata

修改 Transport 鉴权

验证 LangfuseDirectTransport 的 authHeaders(sessionId) 仍能拿到最新 session token。

发布流程

发布到 npm 的三个通道：

# alpha 内部验证
npm run release:alpha -- --otp=123456

# beta 预发布
npm run release:beta -- --otp=123456

# latest 稳定版
npm run release:latest -- --otp=123456

发布命令会自动：

1. 验证版本和 CHANGELOG
2. 运行测试和类型检查
3. 提交变更
4. 发布到 npm
5. 创建 git tag 并推送

详见 RELEASE.md。

包结构

.
├── src/
│   ├── index.ts              # 导出入口
│   ├── observer.ts           # AgentObserver 主类
│   ├── run.ts                # AgentRun、Generation、ToolSpan
│   ├── types.ts              # 类型定义
│   ├── context.ts            # ObservationContext
│   ├── flush-gate.ts         # FlushGate
│   ├── redactor.ts           # 数据脱敏
│   └── transports/
│       ├── types.ts          # Transport 接口
│       └── langfuse-direct.ts # Langfuse direct transport
└── test/
    ├── observer.test.ts
    ├── langfuse-direct.test.ts
    ├── redactor.test.ts
    └── flush-gate.test.ts