Data Tag - 数据标注与校验

概述

本技能负责对 Excel 中的数据进行标注校验。根据用户提供的数据字段和结果字段，逐行判断结果字段的值是否准确，直接在结果字段的 cell 上进行标注，不新增任何列：

• 错误 → 结果字段 cell 标红色 + 添加批注（说明错误原因及正确答案）
• 待确认 → 结果字段 cell 标黄色 + 添加批注（说明不确定的原因）
• 准确 → 无特殊标记

输出文件保存在原文件夹，命名为 原文件名-标注版.xlsx，不覆盖原文件。

工作流程

第一步：接收与理解输入

收到用户请求后，确认以下信息：

1. Excel 文件路径：用户提供的待校验 Excel 文件
2. 数据字段：用于判断结果是否准确的数据列（可多列）
3. 结果字段：需要校验的目标列（也是需要颜色标注和添加批注的列）
4. 校验规则（可选）：用户指定的特殊校验逻辑；若未提供，则根据数据字段与结果字段的语义关系自动推断

若用户未明确指定数据字段和结果字段，主动询问确认后再开始校验。

第二步：读取与理解数据（含数据特征分析）

1. 使用 scripts/validate_data.py 读取 Excel 文件全部内容
2. 展示前 5 行数据供用户确认字段映射是否正确
3. 确认数据字段和结果字段的列名与实际列名一致
4. ⚠️ 数据特征分析（关键步骤）：在开始校验前，必须先完成以下分析：
• 统计结果字段的所有取值：列出所有出现过的值及其频次（即标注标签集合）
• 理解数据字段的内容特征：是结构化数据（数值/枚举）还是非结构化数据（自由文本/语音转写文本/描述性文本）
• 识别数据质量问题：数据字段是否存在噪声（错别字、口语化表达、语音转写错误、标点缺失、换行/分段等）
• 推断标注任务类型：分类标注、情感标注、信息提取、数值计算、还是其他类型
• 建立标注规则假设：基于数据和标签的关系，形成"什么样的数据应该对应什么标签"的初步规则假设
• 向用户展示分析结果，确认理解是否正确后再进入校验

第三步：逐行校验标注（核心步骤 — 精确推理）

⚠️ 此步骤是标注准确性的关键，必须严格执行以下推理流程。

3.1 分批处理策略

• 每批处理 不超过 20 行（数据复杂度高时减少到 10 行）
• 每批处理完后，自我检查本批结果的一致性，再继续下一批
• 禁止一次性处理所有行后一并输出——这会导致后半段数据的校验质量严重下降

3.2 每行必须完成的推理链（Chain-of-Thought）

对每一行数据，必须在内部完成以下 四步推理，不可跳步：

Step 1 — 原文理解：

• 逐字读取数据字段的完整原文，不要截断、概括或脑补
• 特别注意：语音转写文本可能包含错别字、漏字、谐音替代、口语化表达——必须读懂说话人的实际意图，而非字面含义
• 长文本中的关键信息可能藏在中间或末尾，不能只看开头就下结论
• 如果数据字段有换行符 \n，那是真实的换行，文本是连续的

Step 2 — 独立判断：

• 基于 Step 1 理解的内容，独立推断这条数据应该对应什么结果
• 在得出自己的判断之前，不要看结果字段的值——先形成预期，再去比对
• 如果数据信息不足以唯一确定结果，记录"信息不足"

Step 3 — 比对分析：

• 将 Step 2 的独立判断与结果字段的实际值进行比对
• 如果一致 → 准确
• 如果不一致 → 先暂停，进入 Step 4 的复核，不要直接判定错误

Step 4 — 复核确认（防止误判的关键步骤）：

• 当 Step 3 判定为"不一致"时，必须做以下复核：

1. 重新审视原文：是否遗漏了某段关键信息？是否误解了口语/方言/谐音表达？
2. 考虑语义等价：结果字段的值和你的判断是否表述不同但含义相同？（如"盈利"vs"赚钱"，"投诉"vs"不满"）
3. 考虑合理性：结果字段的标注是否存在某种你没想到的合理解释？
4. 考虑标签粒度：结果字段的标签体系可能和你的理解粒度不同（如你认为应标"有贷款需求"，但标签体系只有"意向客户"/"非意向客户"）
5. 复核后仍然确认矛盾 → 判定"错误"
6. 复核后发现可能有合理解释但不确定 → 判定"待确认"
7. 复核后发现确实正确 → 改判"准确"

3.3 校验判定标准

判定"准确"的条件（宽松判准，严格判错）：

• 与预期完全一致
• 语义等价（表述不同但含义相同）
• 属于多种合理答案之一
• 在合理误差范围内（数值误差 ≤5%）

判定"错误"的条件（必须高度确信）：

• ⚠️ 判定"错误"需要非常高的确信度——如果有 >20% 的可能性标注是对的，应判为"待确认"
• 与预期明显矛盾，且复核后无法找到合理解释
• 数据字段提供的事实信息明确不支持该结果

判定"待确认"的条件（有疑就标待确认）：

• 结果字段为空值或缺失
• 数据字段信息不足以唯一确定结果
• 存在歧义或多种合理解释
• 数据字段本身有噪声/矛盾/不完整
• 你的判断和标注不一致，但不能 100% 确定标注是错的

3.4 特殊数据类型处理

语音转写文本：

• 预期噪声：错别字、漏字、同音字替代、标点缺失、口语化冗余（"嗯"、"那个"、"就是说"）
• 读取策略：先通读全文理解整体语境，再提取关键意图信息
• 不要因为转写错误而误判标注——要理解说话人的真实意图
• 例：转写为"我想贷看"，实际意图可能是"我想贷款"

长文本/多段信息：

• 不能只看开头或前几个句子
• 关键信息可能在文本的任何位置
• 如果文本包含矛盾信息（前半段说 A，后半段说 B），标为"待确认"

枚举/分类标签：

• 先从数据中统计出完整的标签集合
• 确保你的预期判断使用的标签在标签集合内
• 如果你认为"正确答案"不在标签集合中，说明你可能误解了标签体系的定义

3.5 防止常见错误模式

以下是历史上常见的错误判定模式，必须避免：

第四步：写入校验结果

不新增任何列，直接在结果字段的 cell 上进行标注：

1. 对结果字段的 cell 进行颜色标注：
• 校验结果为"错误" → 结果字段 cell 填充红色背景（#FF4444），白色加粗字体
• 校验结果为"待确认" → 结果字段 cell 填充黄色背景（#FFD966），加粗字体
• 校验结果为"准确" → 无特殊颜色
2. 对错误和待确认的结果字段 cell 添加 Excel 批注（Comment）：
• 批注内容为批示文字，说明错误原因或不确定原因
• 批注作者标记为 "data-tag"
3. 输出文件命名规则：原文件名-标注版.xlsx，保存在原文件所在目录
4. 向用户展示校验统计摘要

输出文件命名示例：

• 原文件 数据.xlsx → 输出 数据-标注版.xlsx
• 原文件 test_results.xlsx → 输出 test_results-标注版.xlsx

第五步：自检与汇报

5.1 自检（在汇报前执行）：

完成所有行的校验后，必须抽检至少 5 行判定为"错误"的数据（如果错误行不足 5 行则全部复查）：

• 重新走一遍 Step 1-4 的完整推理链
• 如果复查后发现之前的判定有误，修正结果后再写入
• 抽检发现的修正率如果 >20%，应对全部"错误"行进行复查

5.2 汇报：

向用户输出校验摘要，包括：

• 总行数
• 准确行数及占比
• 错误行数及占比（红色标注 + 批注）
• 待确认行数及占比（黄色标注 + 批注）
• 典型错误示例（最多 3 条，展示具体数据字段值、当前标注值、建议正确值）
• 输出文件路径

使用脚本

读取与写入 Excel

使用 scripts/validate_data.py 脚本处理 Excel 的读取和写入操作：

# 读取 Excel 并输出 JSON 格式数据
python3 scripts/validate_data.py read <excel_path> [--sheet <sheet_name>] [--limit <n>]

# 分析数据特征和标签分布（在校验前必须执行，用于理解数据）
python3 scripts/validate_data.py analyze <excel_path> --data-fields <field1,field2,...> --result-fields <field1,field2,...> [--sheet <sheet_name>]

# 一次性写入所有字段的校验结果（推荐，避免多次加载导致标注覆盖）
python3 scripts/validate_data.py write-batch <excel_path> <output_path> --all-results <json_results>

# 写入单个字段的校验结果（仅适用于只有一个结果字段的场景）
python3 scripts/validate_data.py write <excel_path> <output_path> --result-field <field> --results <json_results>

analyze 命令参数说明（校验前必须执行）：

• excel_path：Excel 文件路径
• --data-fields：数据字段名，多个字段用逗号分隔
• --result-fields：结果字段名，多个字段用逗号分隔
• 输出：标签分布、数据特征、是否为语音转写文本等分析结果
• 用途：帮助你在校验前理解标签体系和数据质量，避免标签体系错位导致的误判

write-batch 命令参数说明（推荐）：

• excel_path：原始 Excel 文件路径
• output_path：输出路径，格式为 原目录/原文件名-标注版.xlsx
• --all-results：JSON 字符串，格式为 {"字段名1": [{"校验结果": "准确/错误/待确认", "批示": "原因说明"}, ...], "字段名2": [...], ...}

write 命令参数说明（单字段，仅适用于只有一个结果字段的场景）：

• excel_path：原始 Excel 文件路径
• output_path：输出路径，格式为 原目录/原文件名-标注版.xlsx
• --result-field：结果字段名（需要标色和添加批注的列）
• --results：JSON 字符串，格式为 [{"校验结果": "准确/错误/待确认", "批示": "原因说明"}, ...]

⚠️ 重要：当有多个结果字段时，必须使用 write-batch 命令一次性写入所有字段的校验结果。不要对每个字段单独调用 write 命令，因为每次 write 都会从原始 Excel 重新加载，导致之前字段的标注被覆盖丢失。

标注方式：

注意：执行脚本前先检测系统可用的 Python 命令（python 或 python3），使用可用版本执行。

校验逻辑参考

详细的校验逻辑和常见场景处理方式，参见 references/validation_rules.md。

注意事项

• 始终保留原始 Excel 文件不变，校验结果写入新文件
• 输出文件命名必须为 原文件名-标注版.xlsx，保存在原文件同目录
• 不新增任何列，校验结果通过颜色和批注直接标注在结果字段的 cell 上
• 批注内容仅对"错误"和"待确认"的行添加，"准确"的行无批注
• 若 Excel 文件较大（超过 1000 行），分批处理并告知用户进度
• 若数据字段包含敏感信息（如身份证号、手机号），在校验过程中注意隐私保护，不在批注中完整引用
• 若结果字段为空值，校验结果标注为"待确认"，批注说明"结果字段为空，无法校验"
• 每行独立推理：不要因为前几行的结果影响后续行的判断
• 宁可"待确认"也不要误判"错误"：误判错误的代价远大于漏检