Smart Form Filler（智能填表）
总流程
- 定位模板 → 2. 提取字段 → 3. 准备数据 → 4. 确认映射 → 5. 执行填写 → 6. 验证交付
第 1 步：定位模板
确定用户要填的文件（docx/pdf）。若是 .doc 老格式或加密文件，先用 office-doc-suite 等工具转为 docx 再处理。
第 2 步：提取字段
<python> scripts/extract_fields.py <form.docx|form.pdf> --json fields.json
输出字段清单（label、kind、location、context）。kind 三种：
- underline：下划线填空（字面 ____ 或带下划线格式的空白 run）
- table-cell：表格中"标签 | 空单元格"
- acroform：PDF 表单域
第 3 步：准备数据
数据可能来自三种渠道，统一整理为 data.json（扁平键值对象，键为字段标签）：
- 对话直供：直接从用户消息中取值
- 结构化文件（Excel/JSON/CSV）：读出后按字段名映射
- 从其他文档提取（简历、证件扫描件、旧表）：抽取与字段清单对应的信息
匹配规则、同义词表、易混淆字段、值格式规整见 references/field-matching.md。匹配不确定时必须先问用户；用户未提供且无法推断的字段留空并报告，严禁编造。
第 4 步：确认映射
把「字段 → 值」映射表展示给用户确认后再填写（含敏感信息如身份证号时必须确认）。用户明确说"直接填"时可跳过。
第 5 步：执行填写
Word：
<python> scripts/fill_docx.py <template.docx> --data data.json --output filled.docx
脚本自动处理：字面下划线替换（按视觉宽度补空格、加下划线格式、保留标签前缀）、下划线格式空白 run、表格水平/垂直回填。输出 JSON 报告 filled（已填项）和 unused_keys（数据中未用到的键，需检查是否漏填或键名不匹配）。
PDF：
<python> scripts/fill_pdf_form.py <template.pdf> --data data.json --output filled.pdf
若输出 {"error": "no_acroform"}，说明是扫描件/扁平 PDF，改用文本覆盖方案（reportlab 生成覆盖层或转 docx 处理），并向用户说明。
第 6 步：验证交付
- 重新读取 filled 文件抽查 2-3 个关键字段的实际值
- 检查
unused_keys为空；不为空则排查键名或位置 - 用 present_files 交付成品文件，附一句填写结果摘要（共 N 项、待补 M 项）
运行环境
- Python 3.9+，依赖：
python-docx、pypdf - 首次使用前安装：
pip install python-docx pypdf（WorkBuddy 环境中安装到托管 venv，禁止全局安装） - 命令中的
<python>指当前会话可用的 Python 解释器路径，按实际环境替换
注意事项
- .doc/.doc 老格式、加密 PDF 先转换再填
- PDF 中文字段值依赖 PDF 内嵌字体；填完后务必提醒用户打开检查显示效果
- 复杂表格（合并单元格、跨页表格）脚本可能识别不全，用 extract_fields 结果人工核对字段数
- 填写前不要改动原模板；始终输出到新文件
