03
数据准备

考勤数据准备

attendance-data-prep
🗂️
数据准备 skills/attendance/
把某客户某月原始考勤源数据整理成「按员工分文件夹」的结构化目录，产出标准化员工清单 reference_roster.xlsx，供下游直接消费。负责「数据从哪来、有哪些人、文件归谁」。
⚡

TRIGGERS

触发场景
▸拿到一个月原始考勤源目录（msg/Excel/PDF/图片混杂）
▸要先抽附件、AI 视觉预处理、按人归档
▸下游 remarks / exception-review 需要 reference_roster
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT · 输入
  • data/raw/<目录名> 源目录
  • 可选底表（账单/工资/人员清单）
  • .msg 附件 / 邮件正文 / PDF / 图片
↗ OUTPUT · 产出
  • reference_roster.xlsx 员工清单
  • 数据收集汇总.xlsx · 人工复核清单.xlsx
  • employees/<姓名>/ 按人归档 + _sources.json
  • vision_extracted_records.jsonl + 视觉提取结果.xlsx
  • _email_texts.jsonl 邮件正文（供 remarks 消费）
🪜

STEPS

处理流程
  1. 1
    抽取 .msg 附件
    解出邮件附件到 attachments/。
  2. 2
    PDF 逐页渲染 PNG
    考勤不依赖 PDF 文本层；即使是文字型 PDF 也逐页出图交给视觉识别。
  3. 3
    AI 视觉结构化预处理
    逐图、逐页 PNG 读取，产出 vision_extracted_records（保留 source_file / page，不猜身份证和小时数）。
  4. 4
    确定底表
    单候选可继续（须说明依据）；多候选必须暂停问用户；无候选进无底表模式。
  5. 5
    确定目标员工范围
    有底表以底表为准；无底表先视觉 + 文件名候选，再由 LLM 语义复核，人工确认前不生成 roster。
  6. 6
    按员工归档
    优先级：Excel 内姓名 > 文件名 > 邮件主题 > 视觉结果 > _unmatched/。
⇄

PIPELINE

与其他 skill 衔接
←
客户来自 triage 分诊；A/D 型由 monthly-reconcile / laoqin-monthly 编排调用。
→
归档结果喂给 exception-review 做异常审核、remarks 算备注。
⤳
人类边界：给人看 Excel，给脚本 / LLM 看 JSON / JSONL，不要把中间文件当交付件。
✓

ACCEPTANCE

闭环验收
⊘

ANTI-PATTERNS

反例检查
✗
公司名、部门名、月份标签被误识别成人名。
✗
manifest 仍 needs_pdf_preprocess，却把 PDF 当已处理。
✗
视觉记录缺 source_file / page，下游无法追溯。
✗
把签到明细/打卡截图直接当成已审批加班。
✗
同名员工只靠姓名归档，未用身份证号或待追问区分。
⌘

RUN

运行命令
RUN · 运行命令
uv run python skills/attendance/attendance-data-prep/scripts/extract_msg_attachments.py \
  data/raw/<目录名> outputs/<目录名>/attachments

uv run python skills/attendance/attendance-data-prep/scripts/preprocess_pdfs_for_vision.py \
  outputs/<目录名> --source-dir data/raw/<目录名> \
  --source-dir outputs/<目录名>/attachments

uv run python skills/attendance/attendance-data-prep/scripts/prepare_attendance_data.py \
  data/raw/<目录名> outputs/<目录名> \
  --attachments-dir outputs/<目录名>/attachments \
  --base-table data/raw/<目录名>/<底表.xlsx>