SuperAPI AI 工具集

create-evlog-enricher

编程与开发

查看项目

更新于 10-16 06:37

技能介绍

用途

create-evlog-enricher 是一个用于在 evlog 项目中创建新内置 enricher 的技能。enricher 的作用是为宽事件添加派生上下文,例如部署元数据、租户上下文等(文档中列举的适用场景)。每个 enricher 都遵循相同的架构,该技能会引导完成全部改动点。

文档明确强调:每个改动点都是必做的,不得跳过;在全部 6 个改动点完成之前,不应认为任务已完成。

主要能力

该技能覆盖创建一个新内置 enricher 所需的 6 个改动点:

  1. packages/evlog/src/enrichers/index.ts:添加 enricher 源码
  2. packages/evlog/test/enrichers.test.ts:添加测试
  3. apps/docs/content/4.enrichers/2.built-in.md:将 enricher 添加到内置文档
  4. apps/docs/content/4.enrichers/1.overview.md:将 enricher 添加到概览卡片
  5. skills/review-logging-patterns/SKILL.md:将 enricher 添加到 Enrichers 部分中的 Built-in 行
  6. 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 暂未提供。