用途
create-evlog-enricher 是一个用于在 evlog 项目中创建新内置 enricher 的技能。enricher 的作用是为宽事件添加派生上下文,例如部署元数据、租户上下文等(文档中列举的适用场景)。每个 enricher 都遵循相同的架构,该技能会引导完成全部改动点。
文档明确强调:每个改动点都是必做的,不得跳过;在全部 6 个改动点完成之前,不应认为任务已完成。
主要能力
该技能覆盖创建一个新内置 enricher 所需的 6 个改动点:
packages/evlog/src/enrichers/index.ts:添加 enricher 源码packages/evlog/test/enrichers.test.ts:添加测试apps/docs/content/4.enrichers/2.built-in.md:将 enricher 添加到内置文档apps/docs/content/4.enrichers/1.overview.md:将 enricher 添加到概览卡片skills/review-logging-patterns/SKILL.md:将 enricher 添加到 Enrichers 部分中的 Built-in 行README.md+packages/evlog/README.md:将 enricher 添加到 README 的 enrichers 部分
命名约定
文档给出了一组占位符及其用法:
{name}:事件字段键,camelCase,例如userAgent{Name}:函数/接口名,PascalCase,例如UserAgent{DISPLAY}:人类可读显示名,例如User Agent
使用方式
第 1 步:Enricher 源码
将 enricher 添加到 packages/evlog/src/enrichers/index.ts。完整带注释模板见 references/enricher-template.md。关键架构规则包括:
- Info 接口:定义 enricher 输出的形状(如 UserAgentInfo、GeoInfo)
- 工厂函数:
create{Name}Enricher(options?: EnricherOptions)返回(ctx: EnrichContext) => void - 使用 EnricherOptions:接受
{ overwrite?: boolean }控制合并行为 - 使用 mergeEventField():将计算数据与已有事件字段合并,遵循 overwrite
- 使用 getHeader():大小写不敏感的头部查找辅助函数
- 设置单一事件字段:
ctx.event.{name} = mergedValue - 提前返回:当所需头部缺失时跳过富化
- 无副作用:enricher 只修改 ctx.event,绝不抛出异常或记录日志
第 2 步:测试
将测试添加到 packages/evlog/test/enrichers.test.ts。必需的测试类别:
- 从头部设置字段:验证 enricher 正确填充事件字段
- 头部缺失时跳过:验证所需头部不存在时不设置字段
- 保留已有数据:验证
overwrite: false(默认)不会替换用户提供的字段 - 请求时覆盖:验证
overwrite: true会替换已有字段 - 处理边界情况:空字符串、格式错误的值、大小写不敏感的头部名
遵循 enrichers.test.ts 中已有的测试结构,每个 enricher 有各自的 describe 块。
第 3 步:更新内置文档
编辑 apps/docs/content/4.enrichers/2.built-in.md,为新 enricher 添加新章节。每个 enricher 章节结构为:## {DISPLAY}、一句话描述、**Sets:** event.{name}、create{Name}Enricher() 代码示例、输出形状(interface {Name}Info)、示例输出(JSON),以及针对平台特定说明或限制的相关提示。
第 4 步:更新概览页
编辑 apps/docs/content/4.enrichers/1.overview.md,在 ::card-group 区块中(Custom 卡片之前)为新 enricher 添加卡片,包含 icon、title、to(指向 /enrichers/built-in#{anchor})和简短描述。
第 5 步:更新 skills/review-logging-patterns/SKILL.md
在分发给用户的公开技能 skills/review-logging-patterns/SKILL.md 中,找到 Enrichers 部分,将新 enricher 添加到 Built-in 行,形如:Built-in: createUserAgentEnricher(), createGeoEnricher(), ..., create{Name}Enricher() — all from evlog/enrichers.
第 6 步:更新 README
将 enricher 添加到 packages/evlog/README.md 的 enrichers 部分(根 README.md 是指向它的符号链接)。将 enricher 添加到 enrichers 表格,包含其事件字段和输出形状。
PR 标题
建议的 PR 标题格式为 feat: add {name} enricher。具体措辞可随 enricher 变化(如 feat: add user agent enricher、feat: add geo enricher),但应始终遵循 feat: 约定式提交前缀。
验证
完成所有步骤后运行:
cd packages/evlog
bun run build # Verify build succeeds
bun run test # Verify tests pass
限制
文档未提供 enricher 的具体可用平台列表、收费信息或价格;仅提及需为平台特定说明或限制添加相关提示。其余功能细节以技能文档所述为准,未提及的 facts 暂未提供。