数据标准词根定义工具

本技能帮助用户将字段描述拆解为词根，与已有词根库匹配后生成英文全称和简称，最终输出标准化的 Excel 报告。

工作流程

步骤 1：读取输入并去重

读取用户提供的输入文件（Excel 或文本文件），提取字段描述列。

• Excel 输入：读取第一个 sheet，取"字段描述"或"描述"列（列名模糊匹配：字段描述、字段名称、描述、description、name）
• 文本输入：每行作为一个字段描述
• 去重后得到唯一的字段描述列表

如果用户未提供输入文件，提示用户上传包含字段描述的 Excel 或文本文件。

步骤 2：字段描述标准化（由 LLM 处理）

由执行 skill 的大模型对原始字段描述进行标准化处理，提升分词质量。

标准化规则（LLM 执行）：

1. 去除虚词：删除无意义的虚词

   • 虚词列表：的、之中、中的、了、着、过、与、及、和、或、等、一个、一下、看
   • 示例：PMS的项目编码 → PMS项目编码
   • 示例：凭证中的凭证日期 → 凭证日期

2. 去重优化：删除重复出现的业务概念

   • 示例：凭证中的凭证日期（凭证重复）→ 凭证日期
   • 示例：客户名称的客户代码（客户重复）→ 客户代码

3. 长度控制：字段描述超过 15 个字符时，进行智能总结

   • 保留核心语义，去除修饰性词语
   • 示例：这是一个用来记录客户详细信息的字段 → 客户详细信息
   • 示例：已经识别过的次数统计数值 → 识别次数

4. 语义优化：修正口语化或不规范的表达

   • 示例：啥状态 → 状态

LLM 需要输出：

• normalized: 清洗后的描述
• normalize_remark: 简述做了哪些清洗操作（如"去除虚词'的'、去重"）

步骤 3：LLM 智能分词

由 LLM（即执行 skill 的 AI 本身）对清洗后的字段描述进行智能词根分词。

分词规则：

• 将字段描述拆分为最小语义单元（词根），不要留整段不分
• 示例：公司名称 → ["公司", "名称"]
• 示例：用户注册手机号码 → ["用户", "注册", "手机", "号码"]
• 示例：订单创建时间 → ["订单", "创建", "时间"]
• 示例：员工身份证号 → ["员工", "身份证", "号"]
• 示例：商品一级分类名称 → ["商品", "一级", "分类", "名称"]
• 示例：IP地址 → ["IP", "地址"]
• 示例：客户ID → ["客户", "ID"]
• 示例：国投证券 → ["国投", "证券"]
• 示例：操作系统 → ["操作", "系统"]
• 示例：是否正在充电 → ["是否", "正在", "充电"]
• 英文缩写（如 ID、IP、URL、API、SDK、OAID）作为一个独立词根保留原样
• 专有名词也需要拆分，不要作为一个整体保留

分词应基于数据标准领域的常见语义理解，强制拆分为最小语义单元（词根）。

强制拆分原则：

• 所有组合词必须拆分到不能再拆为止
• 示例：企业微信 → ["企业", "微信"]（不是 ["企业微信"]）
• 示例：可转订单 → ["可转", "订单"]（不是 ["可转订单"]）
• 示例：坐舱 → ["座舱"]（已经是最小单元则保留）
• 示例：已付款 → ["已", "付款"]（拆分为"已"+"付款"）
• 示例：已核销金额 → ["已", "核销", "金额"]
• 示例：购买方纳税人识别号 → ["购买方", "纳税人", "识别", "号"]

唯一保留整体的情况： 英文缩写（ID、IP、URL、API、SDK、OAID等）作为一个独立词根保留原样。

步骤 4：生成分词 JSON

将步骤 2-3 的结果写入 JSON 文件，格式如下：

{
    "客户ID": {
        "original": "客户ID",
        "normalized": "客户ID",
        "tokens": ["客户", "ID"],
        "normalize_remark": ""
    },
    "PMS的项目编码": {
        "original": "PMS的项目编码",
        "normalized": "PMS项目编码",
        "tokens": ["PMS", "项目", "编码"],
        "normalize_remark": "去除虚词'的'"
    },
    "凭证中的凭证日期": {
        "original": "凭证中的凭证日期",
        "normalized": "凭证日期",
        "tokens": ["凭证", "日期"],
        "normalize_remark": "去除虚词'中的'、去重'凭证'"
    }
}

保存到临时文件（如 /tmp/data_std_tokens.json）。

步骤 5：匹配词根库,翻译未匹配词根

检查步骤 4 的输出，按以下规则处理：

1. 英文/数字词根自动处理

• 纯英文词根（如 BU、ULR）：直接使用小写形式，无需翻译
• 纯数字词根（如 123）：直接使用原值
• 英文+数字组合（如 ID2）：直接使用小写形式

2. 中文词根翻译 对于未在词根库中找到的中文词根，由 LLM 翻译这些词根的英文全称和简称。

翻译要求：

• 翻译应为数据标准领域的常用术语
• 优先使用行业通用表达（如"注册"→"register"而非"sign up"）
• 单个英文单词优先，复合概念用下划线连接（如 package_name）

英文简称缩写规则：

自定义缩写需遵循专业术语缩写原则：

1. ≤5 个字母的英文单词，直接使用原词作为简称（不做缩写）
2. >5 个字母的英文单词，按以下规则生成简称：
   • 取单词的前两个字母作为开头
   • 从剩余部分中选取关键辅音字母（排除元音 A, E, I, O, U）
   • 整体长度控制在 <=8 个字母
3. 示例：
   • license → lcns
   • register → rgst
   • description → dscrpt
   • address → adrs
   • securities → scty
   • battery → bttr
   • currently → crrnt
   • charging → chrg
4. 常见缩写直接使用： ID, IP, URL, API, SDK, OAID, SQID 等
5. 复合词（下划线连接的），各部分分别缩写后下划线拼接：
   • total_amount → ttl_amnt
   • package_name → pkg_name（package 7字母 → pkg，name 4字母 ≤5 直接保留）
   • guotou 只有 6 个字母 → guotou（按规则取前2+辅音 = gutt，但专有名词建议保留更可读的形式）

将翻译结果写入 JSON 文件：

{
    "国投": ["guotou", "gt"],
    "证券": ["securities", "scty"]
}

步骤 6：调用脚本生成最终 Excel

脚本接收 JSON 文件，生成三个 sheet：

• Sheet 1 分析结果：词库匹配的直接填，未匹配的英文位置留空
• Sheet 2 词根明细：所有词根（含词库匹配、本次翻译、自动处理），来源列标明来源
• Sheet 3 命名建议：全部补全，翻译的词根也填入英文，给出完整可用的字段英文名

脚本位置： scripts/ 目录下

使用方法：

# 1. LLM 批量分词（调用 Minimax API）
python3 scripts/llm_tokenize.py \
    --input /path/to/字段描述.txt \
    --output /tmp/tokens.json \
    --batch-size 100

# 2. 检查词根库匹配情况（可选，用于查看哪些词根需要翻译）
python3 scripts/check_tokens.py \
    --tokens /tmp/tokens.json \
    --root-lib /path/to/词根库.xlsx

# 3. LLM 翻译未匹配词根（如果有不匹配的词根）
# 首先从 check_tokens 输出中提取未匹配词根，然后调用翻译
python3 scripts/llm_translate.py \
    --tokens /tmp/unmatched_tokens.json \
    --output /tmp/translations.json \
    --batch-size 30

# 4. 生成最终 Excel 报告
python3 scripts/generate_excel.py \
    --tokens /tmp/tokens.json \
    --translations /tmp/translations.json \
    --root-lib /path/to/词根库.xlsx \
    --output /path/to/输出报告.xlsx

脚本说明：

• llm_tokenize.py：调用 LLM API 批量分词，输出 JSON 格式的分词结果
• llm_translate.py：调用 LLM API 翻译未匹配词根
• check_tokens.py：检查分词结果与词根库的匹配情况，输出未匹配词根列表
• generate_excel.py：生成最终的 Excel 分析报告（三个 Sheet）
• read_input.py：读取 Excel/文本输入，输出去重后的字段描述 JSON（可选，主要用于非 API 方式）

输出 Excel

最终输出一个 Excel 文件，包含三个 sheet 页。

Sheet 1：分析结果

所有字段描述的完整分析结果，包含原始描述和清洗后的描述。

| 原始描述 | 清洗后描述 | 分词结果 | 英文全称 | 英文简称 | 数据来源 | 清洗说明 |

连接方式： 英文全称和英文简称均用逗号 , 连接多个词根。

未匹配处理： 词根库中未查到的词根，对应英文位置直接留空（不填翻译、不加多余下划线），但保留逗号分隔符占位。

颜色区分：

• 🟢 绿色底 — 词库匹配：所有词根均在词根库中找到
• 🟡 黄色底 — 部分匹配+翻译：部分词根来自词库，部分为本次翻译
• 🔴 红色底 — 全部翻译：所有词根均为本次翻译

Sheet 2：词根明细

汇总本次处理涉及的所有词根（去重），包含词库匹配、本次翻译和自动处理的。

| 中文词根名称 | 英文全称 | 英文简称 | 出现频次 | 来源 |

• 出现频次：该词根在所有字段描述中出现的次数（跨字段累计），帮助识别高频词根，优先补充到词根库

颜色区分：

• 🟢 绿色底 — 词库匹配：从词根库中查找到
• 🔴 红色底 — 本次翻译：词库中未找到，本次新翻译的中文词根
• 🔵 蓝色底 — 自动处理：英文/数字词根，自动使用原值

这张表方便用户审核后将有价值的词根补充到词根库中。

Sheet 3：命名建议

包含所有字段描述的最终命名建议，英文用下划线连接（而非逗号分隔）。

| 字段描述 | 分词结果 | 英文全称 | 英文简称 | 数据来源 |

英文连接规则： 多个词根的英文用 _ 下划线拼接。如：

• 客户ID → customer_id / cust_id
• 订单日期 → order_date / ordr_dt

颜色区分同 Sheet 1。

"数据来源"列说明：

• 词库匹配：所有词根均在词根库中找到
• 部分匹配+翻译：部分词根来自词库，部分为本次翻译
• 全部翻译：所有词根均为本次翻译

Excel 样式规范

输出 Excel 采用以下样式规范：

1. 表头样式

   • 深蓝色背景（#4472C4）
   • 白色粗体字
   • 居中对齐

2. 数据区域样式

   • 所有单元格添加细边框
   • 文字左对齐，垂直居中
   • 频次列居中对齐

3. 功能特性

   • 冻结首行（滚动时表头固定）
   • 自动调整列宽（最大60字符）
   • 首行加高 22px

4. 颜色体系

   • 绿色 #C6EFCE — 词库匹配
   • 黄色 #FFEB9C — 部分匹配
   • 红色 #FFC7CE — 全部翻译
   • 蓝色 #BDD7EE — 自动处理

输入文件指引

首次使用时，向用户确认以下两个文件：

1. 字段描述文件（必需）：包含待处理字段描述的 Excel 或文本文件
2. 词根库文件（必需）：已有的词根映射 Excel 文件，包含"中文词根名称"、"英文全称"、"英文简称"三列

如果用户之前提供过词根库路径，检查 memory 中是否有记录。

注意事项

代码 生产逻辑

• 读文件和写文件 用代码 单独出来
• 字段描述标准化、分词、词根未匹配到词根库的翻译由 LLM API 完成

API 调用脚本：

• llm_tokenize.py：调用 Minimax LLM API 进行批量分词
• llm_translate.py：调用 Minimax LLM API 翻译未匹配词根

三个 Sheet 的区别：

• Sheet 1（分析结果）：词库有就填，没有就留空 —— 用于审核哪些词根缺失
• Sheet 2（词根明细）：汇总所有词根及来源 —— 用于审核翻译质量，决定哪些补充到词根库
• Sheet 3（命名建议）：全部补全 —— 用于直接取用最终字段英文名

其他注意事项：

• 标准化很重要：字段描述中的虚词（的、之中等）会严重影响分词和匹配质量，建议始终使用标准化预处理
• 英文/数字自动处理：纯英文词根（如 ID、BU、ULR）和数字会自动处理，无需人工翻译
• 分词质量直接影响后续匹配效果，应尽量精确
• 翻译结果需要符合数据标准命名规范，避免口语化表达
• 简称缩写应保持一致性和可读性
• Sheet 2 的词根明细是核心价值之一，帮助用户持续完善词根库
• 英文复合词统一用下划线连接，命名建议 sheet 直接给出可用的字段英文名