adding-event-type

name	adding-event-type
description	Use when extending event support in opencode-stats-engine, such as new SDK events, missing projections, or schema changes

新增事件类型

Overview

新增事件类型需要横跨共享类型、转换器、注册、投影和测试五个层级，漏掉任何一步都会导致数据流断裂。

When to Use

• OpenCode SDK 新增了需要持久化的事件
• Dashboard 统计缺失某类事件的数据
• 现有事件需要补充投影字段
• 需要为新事件扩展数据库 schema

When NOT to Use

• 修复已有转换器的 bug（直接改对应文件）
• 仅调整 Dashboard 前端展示（不涉及后端事件处理）
• 修改现有事件的 schema 但不需要新增事件类型

Quick Reference

步骤	文件/目录	操作
1	packages/shared/src/types/events.ts	更新 StatsEvent 联合类型
2	packages/engine/src/event/converters/	新增转换器，导出 eventType 和 convert
3	packages/engine/src/event/converter.ts	在 REGISTERED 中注册
4	packages/engine/src/projection/	如需投影，更新 handler 的 handles
5	packages/engine/src/db/migrations/	如需新列，新增迁移并更新 schema
6	packages/engine/tests/event/	添加转换器测试，必要时补投影/API 测试

Constraints

• 禁止将 tool_input、tool_output、message_body、raw_input、raw_output 写入元数据
• *_ms 字段保持 UTC 毫秒 epoch，时区转换只在 Dashboard API 边界做
• 运行时只用 Bun，模块系统保持 ESM，代码检查用 Biome

Common Mistakes

• 新增转换器但忘记在 REGISTERED 中注册
• 写了投影 handler 但没更新 handles 数组
• 写了迁移文件但没更新 schema 定义
• 测试只覆盖转换器，没覆盖投影逻辑