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% 的可能性標註是對的，應判為"待確認"
• 與預期明顯矛盾，且複核後無法找到合理解釋

  7w4.net小蔥技能站，你的AI助手技能庫。

• 資料欄位提供的事實資訊明確不支援該結果

判定"待確認"的條件（有疑就標待確認）：

• 結果欄位為空值或缺失
• 資料欄位資訊不足以唯一確定結果
• 存在歧義或多種合理解釋
• 資料欄位本身有噪聲/矛盾/不完整
• 你的判斷和標註不一致，但不能 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 行），分批處理並告知使用者進度
• 若資料欄位包含敏感資訊（如身份證號、手機號），在校驗過程中注意隱私保護，不在批註中完整引用
• 若結果欄位為空值，校驗結果標註為"待確認"，批註說明"結果欄位為空，無法校驗"
• 每行獨立推理：不要因為前幾行的結果影響後續行的判斷
• 寧可"待確認"也不要誤判"錯誤"：誤判錯誤的代價遠大於漏檢

這是一個設計嚴謹的資料校驗Skill，校驗邏輯非常專業——通過四步推理鏈和"寧寬勿嚴"原則最大程度避免誤判，對語音轉寫文本等複雜場景也有完善處理。文件流程清晰、示例充分，新手容易上手。稍有不足的是，部分操作細節（如分批結果如何呈現、自檢如何抽檢）描述不夠具體，遇到邊界情況時可能需要自己摸索。總體質量良好，專業度和易用性兼顧。