telemetry-terminology-similarity

遥测术语相似度

对三个独立层中的遥测字段名称进行两两相似度评分。输出原始分数——不设阈值、不做聚类、不提供意见。使用结果的 AI Agent 会应用自己的领域判断。

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方法——请立即修复此文件，不要拖延。只针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 审查遥测／日志记录架构中的命名冲突
• 比较两个 JSONL 日志架构的字段重叠情况
• 检测 trace_id、traceId、request_id、correlation_id 这类风格问题
• 在发布遥测变更前验证字段命名的一致性

架构

5 层评分流水线——每一层都能捕捉其他层遗漏的问题：

┌─────────────────────────────────────────────────────────┐
│  Layer 1: NORMALIZE                                     │
│  camelCase/snake_case split + abbreviation expansion    │
│  wordninja for concatenated words                       │
│  "traceId" → "trace id", "ts" → "timestamp"            │
├─────────────────────────────────────────────────────────┤
│  Layer 2: SYNTACTIC (RapidFuzz, 0-100)                  │
│  token_set_ratio on normalized forms                    │
│  Catches: trace_id ↔ traceId, level ↔ log_level        │
├─────────────────────────────────────────────────────────┤
│  Layer 3: TAXONOMIC (WordNet Wu-Palmer, 0.0-1.0)        │
│  Head-noun synonym detection via hypernym tree          │
│  Catches: level ↔ severity, error ↔ fault, op ↔ action │
├─────────────────────────────────────────────────────────┤
│  Layer 4: SEMANTIC (sentence-transformers, 0.0-1.0)     │
│  Cosine similarity via all-MiniLM-L6-v2 embeddings     │
│  Catches: error ↔ exception, user_id ↔ account_id      │
├─────────────────────────────────────────────────────────┤
│  Layer 5: CANONICAL (--canonical flag, optional)        │
│  RapidFuzz vs bundled OTel/OCSF/CloudEvents dictionary  │
│  Catches: http_method → http.request.method (OTel)      │
├─────────────────────────────────────────────────────────┤
│  Output: All pairs scored + canonical anchors.          │
│  Agent decides what to act on — tool computes, judges.  │
│  Use proposer-prompt.md for structured rename proposals.│
└─────────────────────────────────────────────────────────┘

两阶段工作流：评分 → 提议

此技能分为两个阶段：

1. 阶段 1 — 评分（term_similarity.py）：计算 5 层的原始相似度分数。工具负责计算，不输出意见。
2. 阶段 2 — 提议（references/proposer-prompt.md）：内置的提示词模板，用于处理评分 JSON，并要求大模型生成结构化的重命名提议，附带置信度级别、证据引用和明确的例外选项。

这两个阶段经过刻意分离。阶段 1 是确定且可复现的；阶段 2 则应用只有掌握对话上下文的大模型才能提供的领域判断。

依赖项

均通过 uv run 安装（PEP 723 内联元数据——无需全局安装）：

软件包	用途	大小
sentence-transformers	语义嵌入（MiniLM-L6）	~80 MB
rapidfuzz	快速模糊字符串匹配（C++）	~1.3 MB
wordninja	概率式单词拆分	~0.5 MB
nltk	WordNet Wu-Palmer 同义词检测	~30 MB
orjson	快速 JSON 序列化	~0.3 MB

首次运行时会下载 all-MiniLM-L6-v2 模型（约 80 MB）和 WordNet 数据（约 30 MB）。

脚本位置

分析脚本位于此技能的 references/ 目录中。使用前请解析路径：

# SSoT-OK: marketplace path resolution for cross-repo invocation
SCRIPT_DIR="$(dirname "$(find ~/.claude/plugins -path '*/telemetry-terminology-similarity/references/term_similarity.py' -print -quit 2>/dev/null)")"
SCRIPT="$SCRIPT_DIR/term_similarity.py"

以下示例均假设已设置 $SCRIPT。如果直接在 cc-skills 仓库中调用，请使用相对路径。

用法

直接分析字段名称

# SSoT-OK: uv run handles PEP 723 inline deps
uv run --python 3.14 "$SCRIPT" \
  trace_id traceId request_id correlation_id \
  level severity log_level priority

从 Python 代码库中提取字段

使用 Python 正则表达式提取（macOS 不支持 grep -P）：

python3 -c "
import re, glob
fields = set()
for f in glob.glob('**/*.py', recursive=True):
    text = open(f).read()
    for m in re.finditer(r'\"([a-z][a-z0-9_]*?)\":', text):
        fields.add(m.group(1))
for f in sorted(fields):
    print(f)
" | uv run --python 3.14 "$SCRIPT"

从标准输入分析（通过 jq 等命令传入）

head -1 telemetry.jsonl | jq -r 'keys[]' | uv run --python 3.14 "$SCRIPT"

分析 JSONL 文件中的字段

uv run --python 3.14 "$SCRIPT" --jsonl /path/to/telemetry.jsonl

比较两个 JSON 架构

uv run --python 3.14 "$SCRIPT" --schema-a schema_v1.json --schema-b schema_v2.json

控制输出大小

uv run --python 3.14 "$SCRIPT" --top 30 field1 field2 field3   # Top 30 pairs
uv run --python 3.14 "$SCRIPT" --top 0 field1 field2 field3    # All pairs
uv run --python 3.14 "$SCRIPT" --json field1 field2 field3     # JSON output

对照规范标准（OTel/OCSF/CloudEvents）查询

# Anchor each field against 1,453 bundled canonical names from OTel + OCSF + CloudEvents
uv run --python 3.14 "$SCRIPT" --canonical http_method http_status request_id severity

输出会增加一个 === CANONICAL ANCHORS === 部分，显示每个字段最接近的标准名称。适用于“是否应该重命名以符合行业标准”的决策。

生成结构化重命名提议（阶段 2）

使用 --json --canonical 运行后，将输出粘贴到 references/proposer-prompt.md 中。这是一个内置的提示词模板，可生成原子化、便于审查的重命名提议，并附带置信度级别和明确的例外选项。

# Phase 1: Score
uv run --python 3.14 "$SCRIPT" --json --canonical [fields...] > analysis.json

# Phase 2: Apply proposer prompt (paste analysis.json into the template)
# The LLM produces structured proposals.json — review atomically

参数

参数	默认值	描述
--top	50	按综合得分显示排名前 N 的配对（0 = 全部）
--canonical	false	使用捆绑的 OTel/OCSF/CloudEvents 字典查询各字段
--jsonl	—	从 JSONL 文件提取字段（所有唯一键）
--schema-a/-b	—	跨架构比较（两个 JSON 架构文件）
--json	false	输出结构化 JSON，而不是文本

输出格式

文本输出（默认）

Fields analyzed: 21
Unique after normalization: 19

=== EXACT DUPLICATES (after normalization) ===
  trace_id  ==  traceId
  timestamp  ==  ts

=== SCORED PAIRS (sorted by combined score) ===
    syn    tax    sem   comb  pair
    ---    ---    ---   ----  ----
  100.0  0.000  0.560  1.000  level                     <-> log_level
    0.0  1.000  0.472  1.000  error                     <-> fault
   66.7  0.909  0.457  0.909  operation                 <-> action
   46.2  0.833  0.251  0.833  level                     <-> severity
   28.6  0.667  0.700  0.700  error                     <-> exception

每组配对有三个独立得分——Agent 会读取这三个得分并据此判断：

• syn（句法）：高 = 表面名称变体
• tax（分类）：高 = WordNet 同义词（上位词树）
• sem（语义）：高 = 嵌入相似度（分布式）
• comb（综合）：max(syn/100, tax, sem) — 排序键

JSON 输出（--json）

结构化 JSON，包含 exact_duplicates 和 scored_pairs 数组。

各层的作用

场景	syn	tax	sem	哪一层占优
trace_id vs traceId	100.0	0.0	1.0	句法
level vs severity	46.2	0.833	0.251	分类
error vs fault	0.0	1.000	0.472	分类
operation vs action	66.7	0.909	0.457	分类
error vs exception	28.6	0.667	0.700	语义
user_id vs account_id	47.1	0.0	0.792	语义

缩写词典

规范化器会展开常见的遥测缩写：

缩写	展开形式	缩写	展开形式
ts	timestamp	uid	user id
req	request	resp	response
err	error	msg	message
svc	service	env	environment
op	operation	lvl	level
evt	event	ctx	context
acct	account	cfg	configuration
dur	duration	lat	latency

通过编辑 term_similarity.py 中的 ABBREVIATIONS 添加特定领域的缩写。

故障排查

问题	原因	解决方案
ModuleNotFoundError	缺少依赖	使用 uv run（PEP 723 会自动解析）
模型下载缓慢	首次运行	首次下载后会缓存（总计约 110 MB）
从其他仓库运行时找不到脚本	未解析路径	按“脚本位置”一节设置 $SCRIPT
grep: invalid option -- P	macOS 缺少 PCRE	改用 python3 -c "import re..." 模式

执行后复盘

此技能完成后，在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口已变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通方案？ — 如果你不得不临时变通（使用不同标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时重复采用相同的变通方案。

仅在问题真实且可复现时更新，不要基于推测更新。