create-evlog-enricher

创建 evlog Enricher

向 evlog 添加一个新的内置 Enricher。每个 Enricher 都基于 evlog/toolkit 提供的公共工具包原语 defineEnricher 构建，因此社区 Enricher 与内置 Enricher 具有相同的结构。

PR 标题

feat(core): add the {name} enricher

Enricher 属于核心包的公开接口（evlog/enrichers），因此除非已有专用 scope，否则请使用 core scope。

触点检查清单

#	文件	操作
1	packages/evlog/src/enrichers/index.ts	添加 Enricher 源码（一次 defineEnricher 调用）
2	同一文件：createDefaultEnrichers()	决定是否将该 Enricher 纳入默认组合（见下文）
3	packages/evlog/test/toolkit/enrichers.test.ts	添加测试（每个 Enricher 一个 describe 块）
4	apps/docs/content/5.use-cases/5.enrichers.md	添加该 Enricher 的章节，并更新导入列表；如适用，还要更新“All built-in enrichers”默认组合文本
5	skills/review-logging-patterns/SKILL.md	在 Enrichers 部分的 Built-in: 行添加该 Enricher
6	packages/evlog/README.md	在 Built-in Enrichers 部分添加该 Enricher（根目录的 README.md 是指向此文件的符号链接）
7	.changeset/{name}-enricher.md	创建 changeset（minor）

重要提示：完成全部 7 个触点后，才能认为任务已完成。

是否应将其纳入 createDefaultEnrichers()？

createDefaultEnrichers() 通过 composeEnrichers（来自 ../shared/compose）组合 user agent、geo、request size 和 trace context。只有当新 Enricher 普遍适用，且只读取请求（headers/env）时，才将其添加到组合中。任何需要特定服务配置或会产生额外开销的 Enricher 都应保持为可选项。更改默认组合会影响每个现有的 createDefaultEnrichers() 使用者：请在 changeset 中明确说明。

命名约定

占位符	示例（UserAgent）	用法
{name}	userAgent	事件字段键使用 camelCase
{Name}	UserAgent	函数和接口名称使用 PascalCase
{DISPLAY}	User Agent	易读的显示名称

第 1 步：Enricher 源码：基于 defineEnricher 构建

将 Enricher 添加到 packages/evlog/src/enrichers/index.ts。完整的注释模板请参阅 references/enricher-template.md。

其约定是 defineEnricher<T>({ name, field, compute }, options?)。你只需提供一段逻辑：

• compute(ctx)：返回计算出的值（类型为 T），或返回 undefined 以跳过。

其余工作由 defineEnricher 处理：

• 通过 mergeEventField 合并（遵循 options.overwrite，默认值为 false）
• 隔离错误（捕获并记录抛出的错误，不会继续传播）
• 当 compute 返回 undefined 时跳过

关键规则：

• 使用工具包辅助函数：使用 getHeader() 进行不区分大小写的请求头查找，使用 normalizeNumber() 处理数字字符串。两者都来自 ../shared/headers（并由 evlog/toolkit 重新导出）。
• 单个事件字段：每个 Enricher 都会在 ctx.event 上写入一个顶层字段。如果 Enricher 还必须固定顶层字段（例如 createTraceContextEnricher 对 event.traceId / event.parentSpanId 所做的处理），请将 defineEnricher 的结果包装在闭包中，模式请参阅该 Enricher。
• 工厂模式：create{Name}Enricher(options: EnricherOptions = {}) 会直接返回 defineEnricher(...) 的结果（通常如此）；如果 Enricher 还会固定顶层字段，则通过精简的闭包包装器返回（参见上面的单个事件字段规则）。
• 不产生副作用：绝不抛出错误，也不记录日志；发生问题时依赖 defineEnricher 内置的错误处理。
• 导出 Info 类型：导出用于描述字段形状的 {Name}Info 类型，并与工厂函数一同导出。

第 2 步：测试

在 packages/evlog/test/toolkit/enrichers.test.ts 中添加测试，遵循现有结构（每个 enricher 一个 describe 块）和 packages/evlog/test/README.md 中的约定。

必需的测试类别：

1. 根据来源设置字段：验证 enricher 是否正确填充事件字段，并读取其实际读取的数据（ctx.request、ctx.response、process.env、ctx.event 或请求头）
2. 来源数据缺失时跳过：验证缺少必需输入时不会设置字段
3. 保留现有数据：验证 overwrite: false（默认值）不会替换用户提供的字段
4. 按要求覆盖：验证 overwrite: true 会替换现有字段
5. 处理边界情况：处理空字符串和格式错误的值；对于基于请求头的 enricher，还要测试不区分大小写的查找
6. 默认组合：如果该 enricher 被加入 createDefaultEnrichers()，则扩展该组合的测试

第 3 步：更新 Enrichers 文档页面

编辑 apps/docs/content/5.use-cases/5.enrichers.md：

1. 将该 enricher 添加到顶部的导入列表
2. 按照现有章节的结构添加一个 ## {DISPLAY} 章节：

## {DISPLAY}

[One-sentence description of what the enricher does.]

**Sets:** `event.{name}`

\`\`\`typescript
const enrich = create{Name}Enricher()
\`\`\`

**Output shape:**

\`\`\`typescript
interface {Name}Info {
  // fields
}
\`\`\`

**Example output:**

\`\`\`json
{
  "{name}": {
    // example values
  }
}
\`\`\`

3. 如果该 enricher 被加入默认组合，则更新“All built-in enrichers”章节中关于 createDefaultEnrichers() 所组合内容的说明。

自定义 enricher 编写文档位于单独的 apps/docs/content/6.extend/5.custom-enrichers.md，除非工具包契约本身发生变化，否则无需修改。

第 4 步：更新公开 Skill

在 skills/review-logging-patterns/SKILL.md（发布于 evlog.dev）中找到 Enrichers 章节，并将该 enricher 添加到 Built-in: 行。

第 5 步：更新 README

将该 enricher 添加到 packages/evlog/README.md 中的 Built-in Enrichers 章节（根目录的 README.md 是指向该文件的符号链接）。

第 6 步：Changeset

创建 .changeset/{name}-enricher.md，添加 minor 版本升级说明，描述该 enricher 设置的内容及适用场景。如果默认组合有所变化，请明确说明。

验证

cd packages/evlog
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run build