数据脱敏

SDK 默认在上报到 Langfuse 前对 input/output 进行脱敏处理，以防止敏感信息泄露。

内置脱敏规则

规则名	类型	匹配内容	效果
key-credential	key	password / passwd / pwd / secret / token / api_key / access_token / refresh_token / authorization / cookie	字段值替换为 ***
kv-credential	value	password=xxx、"token": "xxx" 等文本	替换为 password=***
auth-header	value	Bearer xxx / Basic xxx	替换为 Bearer *** / Basic ***
email	value	邮箱地址	alice@example.com → a***@example.com
cn-mobile	value	中国手机号	13812345678 → 138****5678
cn-idcard	value	18 位身份证号	保留前 6 后 4
bank-card	value	13~19 位银行卡号	保留前 4 后 4

脱敏范围

重要说明

• 脱敏只作用于 input 和 output
• metadata 不脱敏（避免业务 ID、组织 ID 被误伤）
• 不要把真正敏感的大对象塞到 metadata 里

自定义规则

方式一：代码注册

import { registerRules } from "@yingdao-ai/agent-observability"

registerRules([
  {
    kind: "value",
    name: "openai-sk",
    pattern: "sk-[A-Za-z0-9]{32,}",
  },
  {
    kind: "key",
    name: "salary",
    pattern: "^salary$",
  },
])

方式二：环境变量

export LANGFUSE_MASK_RULES='[
  {"kind":"value","name":"openai-sk","pattern":"sk-[A-Za-z0-9]{32,}"},
  {"kind":"key","name":"hr-fields","pattern":"^(employee_id|salary)$"}
]'

规则类型定义

type RedactRuleConfig = {
  kind: "key" | "value"  // key 规则按字段名匹配，value 规则按值内容匹配
  name: string           // 规则名，用于标识和管理
  pattern: string        // 正则表达式
  flags?: string         // 正则 flags，默认 "gi"
  replacement?: string   // 替换字符串，默认 "***"
}

• kind: "key" — 匹配对象的 key 名称，命中时整个 value 替换为 ***
• kind: "value" — 匹配字符串内容，命中时替换匹配部分

管理自定义规则

import { registerRules, clearExtraRules, listExtraRules } from "@yingdao-ai/agent-observability"

// 查看已注册的自定义规则名
listExtraRules()  // string[]

// 清空所有自定义规则
clearExtraRules()

直接调用脱敏函数

import { redact } from "@yingdao-ai/agent-observability"

const clean = redact({ password: "secret123", name: "Alice" })
// => { password: "***", name: "Alice" }

故障排查

脱敏没生效：

1. 内置规则先看对应的格式是否在覆盖范围内
2. 自定义规则确认 LANGFUSE_MASK_RULES 是合法 JSON 数组
3. 用 listExtraRules() 检查规则是否成功注册
4. 注意 metadata 不脱敏，这是当前设计