图书填表专家（bookform-pro）

概述

从用户指定的 WorkBuddy 工作空间中自动读取全部图书资料文件，智能解析内容并直接填充至喂投表格中的缺失字段。全自动流程，无需中间审核，直接输出填表结果。

核心能力：

• 工作空间资料自动读取与多格式解析（docx/xlsx/txt/pdf 等）
• 图书封面图（立体封面）自动识别与插入：docx XML精确识别 → 时间等比例缩放（H=4cm） → OneCellAnchor 居中 → 行高5cm → 列宽23字符
• 5 级智能字段匹配引擎，图书字段专项优化
• 严格保留原则：仅填充空白字段，严禁修改原表格中任何字段名称、字段标签、单元格文本、合并结构、格式样式
• 标准化输出至 output/ 目录，即填即用

⚠️ 关键填写原则（必须严格遵守）

核心铁律：填表的本质是"把数据填进空格里"，不是"改写表格"。

1. 严禁改动字段名称

   • 表格中的字段标签（如"书　名"、"出版时间"、"字　数"等）一律保持原样
   • 不得对字段名做任何修改：不能改文字、不能加注、不能补充说明、不能删除空格
   • 不得在字段名前后添加任何说明性文字（如"（原名XXX）"）

2. 严禁改动现有内容

   • 任何非空单元格都不得覆盖、修改或清空
   • 已填写的字段保留原值，不重复填写

3. 只填写空白字段

   • 仅在空白单元格中填入对应的数据值
   • 表格的所有原有结构（合并、列宽、字体、边框等）原样保留

4. 不擅自改写字段语义

   • 如果资料文件中的某个信息无法直接对应表格中现有的字段，不要强行填到某个字段中
   • 找不到对应字段时，应放入"图书简介"、"内容简介"等综合性字段
   • 不要为某个找不到位置的信息创建新字段

5. 作者/出版社等"无字段"信息的处理

   • 表格中没有"作者"列时，不要修改"书名"字段来塞入作者
   • 出版社、作者等信息应作为补充内容写入"图书简介"等通用字段中

6. 🔴 严禁无依据填充（零容忍）

   • 每条填入的字段值必须在源文件中找到明确的字段标签对应，不可凭推测、常规、行业惯例填充
   • 反例：源文件无"图书分类"标签 → ❌ 不可凭内容描述推测为"少儿科普"
   • 反例：源文件定价为 38.00 元 → ❌ 不可填入 32.00（必须逐个核实，不可混用其他图书数据）
   • 正例：源文件明确标注"图书分类：少儿科普" → ✅ 可填入"少儿科普"
   • 正例：源文件表格中"定价 | 38.00元" → ✅ 可填入 38.00
   • 字段标签+字段值必须同时出现在源文件中，只有字段值没有标签（或反之）均视为无依据

7. 🔴 套装书定价规则（全X册）

   • 当书名含**"（全X册）"、"（共X册）"、"（X册套装）"**等括注时，这是一套多册书的整体
   • 源文件中通常有两种价格：套价（高） + 单价/本（低）
   • 必须取套价（高价）填入，因为表格中的一行代表整套书
   • 识别依据：
     • "定价：96.00元 32元/本" → 96.00是套价，32元/本是单价 → ✅ 填 96.00
     • "定价：96.00元 32.00/本" → 同样逻辑 → ✅ 填 96.00
     • "定价：38.00元" → 单一价格（无"/本"）= 套价/普通价 → ✅ 填 38.00
   • 反例："定价：96.00元 32元/本"，书名含"（全3册）" → ❌ 填入 32.00（误取单价）
   • 若书名不含套书标注（如"我们的汉字"），即使源文件有多个价格，也按单一图书取值

前置条件

• 运行环境已安装 Python 3.13+ 及 python-docx、openpyxl 库
• WorkBuddy markitdown 技能可用（用于转换 docx/pdf 等复杂格式）
• 用户已在工作空间中上传图书相关资料文件
• 用户提供一份待填充的表格（支持 .docx、.xlsx、.xls）

工作空间配置

不硬编码工作空间路径，采用以下优先级策略定位：

1. 用户明确指定（最高优先级）：用户告知的工作空间绝对路径
2. 当前会话工作空间：当前 WorkBuddy 会话所在的 {PROJECT_DIR}
3. 交互询问：以上均无法确定时，询问用户提供工作空间路径或名称

工作空间目录记为 {WORKSPACE_DIR}，后续所有文件检索均基于此路径。

输入/输出规范：

• 输入文件：位于 {WORKSPACE_DIR}/input/ 或工作空间根目录
• 输出文件：统一输出至 {WORKSPACE_DIR}/output/（如不存在则自动创建）

数据源：工作空间资料

扫描与分类

使用 Glob 工具扫描工作空间中所有文件（模式：**/*），按类型分类处理：

文件过滤规则

• 跳过临时文件：~$*、._*、系统隐藏文件
• 跳过版本控制目录：.git/、.svn/
• 跳过 .workbuddy/ 目录（内部配置，非业务数据）

内容提取策略

从解析后的文本中提取结构化图书信息：

1. 键值对模式 — 字段名：值、字段名: 值、【字段名】值
2. 加粗标题模式 — markitdown 转换后的 **字段名** 值
3. 表格模式 — markitdown 转换后的 | 字段 | 值 | 表格
4. 段落模式 — "由 XXX 著，XXX 出版" 等自然语言表述

工作流程

整个流程分为 3 步，无需用户审核，全自动执行：

第 1 步：工作空间资料读取

1. 按工作空间配置章节的策略定位 {WORKSPACE_DIR}
2. 使用 Glob 扫描工作空间，获取完整文件清单
3. 对每个文件按类型调用对应工具解析：
   • docx/pdf → 使用 markitdown 技能转换 → 解析结构化数据
   • xlsx → 使用 openpyxl 直接读取
   • txt/md/csv → 使用 Read 工具读取
   • 图片 → 使用 Read 工具的多模态能力识别文字
4. 汇总所有解析结果，构建结构化的"图书信息知识库"
5. 向用户汇报：共扫描多少文件、识别出多少本图书条目

第 2 步：喂投表格解析与智能匹配

1. 确认用户提供的表格文件绝对路径，识别格式：
   • .docx → 使用 python-docx 解析表格结构
   • .xlsx / .xls → 使用 openpyxl 解析
2. 解析表格结构，识别每个字段名称、位置、当前值
3. 列出所有空白字段，作为待填充目标
4. 对表格中的每条记录（每本图书），执行智能匹配：

A. 表格类型识别

• Word 表格（.docx）：使用 python-docx 读取 table.rows 和 table.cells，注意合并单元格的正确处理
• Excel 表格（.xlsx）：使用 openpyxl 读取 ws.iter_rows()，注意 merged_cells 合并区域

B. 字段位置锁定（关键步骤）

填写前必须先精确定位每个字段的单元格位置：

对 Word 表格：table.cell(row_idx, col_idx) 或 table.rows[r].cells[c]
对 Excel 表格：ws.cell(row=row_idx, column=col_idx)

字段定位原则：

• 先用「字段名关键词」扫描所有单元格，找到标签所在位置
• 根据表格布局推断"标签单元格"和"值单元格"的相邻关系
• 常见布局：左标签+右值、上标签+下值、跨列合并的值单元格

C. 字段匹配

对每个缺失字段，使用 5 级匹配策略在工作空间资料中查找：

1. L1 精确匹配 — 字段名完全一致（置信度 1.0）
2. L2 同义词匹配 — 字段名语义等同，如"著者→作者"（置信度 0.9）
3. L3 关键词匹配 — 字段包含关键词，如"图书定价→定价"（置信度 0.7）
4. L4 类型推断 — 根据值格式推断字段，如 "978-7-..."格式 → ISBN（置信度 0.6）
5. L5 上下文匹配 — 段落语义分析推断（置信度 0.5）

D. 结果判定与来源核实

⚠️ 关键原则：字段标签 + 字段值必须在源文件中同时出现。仅凭内容描述推测（如"这是一本科普书" → 类别=少儿科普）视为无依据，不得填入。

第 3 步：直接输出填表文件

1. 使用 python-docx（Word）或 openpyxl（Excel）直接写入填充数据
2. 严格保留原则——严禁以下行为：
   • ❌ 不得修改、删除、覆盖任何字段名称（标签单元格）
   • ❌ 不得修改任何非空单元格的内容
   • ❌ 不得拆分、合并或重组单元格结构
   • ❌ 不得改变单元格的颜色、字体、字号、边框
   • ❌ 不得改变列宽、行高、对齐方式
   • ❌ 不得在字段名后添加"（原名XXX）"等说明文字
   • ✅ 只能在空白单元格中填入数据值
   • ✅ 综合性信息（出版社、作者、获奖等）应填入"图书简介"等已存在的综合字段
3. 文件命名：[原文件名]_已填写.docx 或 [原文件名]_已填写.xlsx
4. 输出至 {WORKSPACE_DIR}/output/
5. 向用户汇报填表结果：共填充多少字段、有哪些字段因表格无对应位置未填入
6. 提供文件路径供用户直接下载使用

字段匹配策略

详见 references/field_mapping_rules.md，其中包含完整的图书字段同义词映射表和匹配规则。

核心匹配管道：

原始文本 → [预处理] → [图书定位 S1-S5] → [字段匹配 L1-L5] → [结果聚合]

同义词映射（部分）：

作者 = 著者 = 编者 = 编著者 = Author
ISBN = 书号 = ISBN号 = 标准书号
出版社 = 出版机构 = 出版单位 = Publisher
定价 = 价格 = 售价 = 原价 = 单价
内容简介 = 内容介绍 = 内容摘要 = 简介
出版时间 = 出版日期 = 出版年 = 上市时间

错误处理与用户反馈

字段匹配层面

文件处理层面

表格解析层面

封面图填写工作流

触发条件

当待填充表格中含有封面图/封面相关字段列，且工作空间中存在图书资料文件（docx 等包含内嵌图片的文档）时，自动触发此子流程。这是必选流程，不可跳过。

工作流程（5步）

第 1 步：从资料文件精确识别封面图

⚠️ 核心原则： 封面图必须通过 docx 内部 XML 精确识别，禁止仅凭文件大小猜测、禁止插入无关图片。

识别算法（按优先级）：

1. 解析 word/_rels/document.xml.rels → 建立 rId → 图片文件名映射
2. 解析 word/document.xml → 找到所有含 a:blip 元素的段落，收集其上下文（前 3 段文本）
3. 判定优先级：
   • P0：段落上下文含"商品主图（封面）"等显式标注 → 直接确认为封面图
   • P1：段落上下文含书名关键词 → 确认
   • P2：文档中的第一张图片 → 回退策略
4. 从 zip 中提取该图片到临时目录

第 2 步：AI视觉确认书名

对提取的封面图，使用 Read 工具的多模态能力读取图片，确认书名与表格匹配：

1. 读取图片文件（Read 工具支持 PNG/JPG 等格式的多模态识别）
2. 从图片中识别书名（立体封面图通常在正面显著位置显示主标题）
3. 记录：书名、副标题（如有）、是否套装封面、图片来源路径

第 3 步：构建图片-书名映射

将识别结果整理为映射 JSON：

{
  "mappings": [
    {
      "book_name": "少年读天工开物",
      "image_path": "<临时目录>/提取的封面图.png",
      "target_column": ""
    }
  ]
}

• target_column 为空时脚本会自动检测"封面图"列
• 书名匹配采用模糊匹配策略（包含关系、核心词匹配）

第 4 步：插入图片到目标单元格

根据目标文档格式调用对应命令：

Word 文档 (.docx)：

C:UsersASUS.workbuddybinariespythonversions3.13.12python.exe scripts/cover_image_inserter.py insert-word <输入.docx> <输出.docx> --mapping ''

Excel 表格 (.xlsx)：

C:UsersASUS.workbuddybinariespythonversions3.13.12python.exe scripts/cover_image_inserter.py insert-excel <输入.xlsx> <输出.xlsx> --mapping ''

第 5 步：调整单元格布局

插入图片后，自动调整封面图所在单元格的行高和列宽。

图片尺寸与布局规范（最终版）

图片居中算法（Excel）

使用 OneCellAnchor 精确控制图片在单元格内的位置：

常量：
  CELL_W_EMU = 1800000   # 单元格宽度（固定 5cm EMU）
  CELL_H_EMU = 1800000   # 单元格高度（固定 5cm EMU）

计算：
  img_w_emu = img.width × 9525
  img_h_emu = img.height × 9525
  col_offset = (CELL_W_EMU - img_w_emu) / 2   # 水平居中偏移
  row_offset = (CELL_H_EMU - img_h_emu) / 2   # 垂直居中偏移

锚定：
  AnchorMarker(col=E-1, colOff=col_offset, row=N-1, rowOff=row_offset)
  OneCellAnchor(_from=marker, ext=XDRPositiveSize2D(cx=img_w_emu, cy=img_h_emu))

⚠️ CELL_W_EMU 使用固定 5cm 而非从列宽反算： Excel 列宽（字符数）与 EMU 之间没有可靠的线性转换。使用固定 5cm 值确保图片始终在视觉范围内居中，不超出单元格边框。

封面图字段识别关键词

脚本自动查找以下字段名变体：

封面图写入原则（最终版）

1. 精确识别封面图（禁止无关图片） — 通过 docx 内部 XML（word/document.xml）分析段落位置关系。找到标题段落后或"商品主图（封面）"标注后的首张图。禁止仅凭文件大小猜测、禁止从工作空间随机选取图片。
2. 仅插入空白单元格 — 目标单元格已有内容时跳过并记录
3. 不修改任何现有内容或格式 — 与文字填表保持一致的严格保留原则
4. 封面图高度 4cm，宽度等比例缩放 — 使用 openpyxl 内部像素单位（EMU = value × 9525），序列化前先除以 9525
5. 封面图所在行高调整为 5cm — 仅调整含图片的行（141.73pt），其他行不变
6. 封面图所在列宽调整为 23 字符 — 仅当插入封面图时才设置，无封面不调整列宽
7. 图片在单元格内水平+垂直居中 — 使用 OneCellAnchor + AnchorMarker 设置 colOff/rowOff 偏移量，基于固定 CELL_W_EMU=1800000（5cm），确保图片不超出单元格边缘
8. 按书名精确匹配 — 使用与文字字段相同的模糊匹配策略（清理特殊字符 → 精确匹配 → 包含匹配）

封面图精确识别算法

通过 docx 内部 XML 分析，三级优先级保障识别准确率：

解析 word/_rels/document.xml.rels  →  rId → 图片文件名映射
解析 word/document.xml            →  含 a:blip 元素的段落
收集每张图前 3 段文本作为上下文    →  判定优先级

判定优先级：

• P0（最高优先级）："商品主图（封面）"等显式标注 → 直接确认
• P1（高优先级）：上下文含书名关键词 → 确认
• P2（回退策略）：文档首张图 → 兜底

提取后的图片保存到临时目录（.workbuddy/temp/covers_v2/），以便后续插入表格。

错误处理

脚本使用说明

所有脚本通过 managed Python 运行，统一环境配置：

set PYTHONPATH=C:UsersASUS.workbuddybinariespythonworkspace
C:UsersASUS.workbuddybinariespythonversions3.13.12python.exe scripts/<脚本名>.py <命令> <参数...>

fill_book_table.py — Excel 处理核心

read                               → 解析表格结构，输出 JSON
fill <输入路径> <输出路径> --fill-data JSON    → 直接写入数据，保持原始格式不变

workspace_reader.py — 工作空间资料解析

scan   <工作空间目录> [--include PATTERN]     → 扫描文件清单，输出 JSON
parse  <文件路径...> --output JSON             → 批量解析文件为结构化数据
extract <解析结果JSON>                         → 从解析结果构建图书信息知识库

scan   <工作空间目录> [--include PATTERN]     → 扫描文件清单，输出 JSON
parse  <文件路径...> --output JSON             → 批量解析文件为结构化数据
extract <解析结果JSON>                         → 从解析结果构建图书信息知识库

field_matcher.py — 智能字段匹配

match  --field <字段名> --source <知识库JSON> --book <图书名>
       → 单字段匹配，返回 {value, confidence, alternatives, status}

batch  --mapping <映射JSON> --source <知识库JSON>
       → 批量匹配，处理多个字段

cover_image_inserter.py — 封面图插入器

scan-images   <工作空间目录> [--pattern PATTERN]  → 扫描封面图片文件，输出清单 JSON
insert-word    <输出路径> --mapping JSON → 将封面图插入 Word 表格
insert-excel   <输出路径> --mapping JSON→ 将封面图插入 Excel 表格

限制与注意事项

1. 严禁编造信息（零容忍）：所有填充内容必须来源于工作空间资料文件中明确标注的字段标签。不得自行编造、推测、套用其他图书数据、或使用外部信息（如网络搜索）。
   • ❌ "这是一篇关于汉字的少儿读物" → 推测类别为"少儿科普"（仅有描述性文字，无"图书分类"标签）
   • ❌ 某书定价填为 32.00，但源文件明确写"定价：38.00元"（未逐个核实，混用数据）
   • ✅ 源文件写"图书分类：少儿科普" → 可填入"少儿科普"
   • ✅ 源文件表格中"定价 ｜ 38.00元" → 可填入 38.00
   • 若资料中确实不存在，保留空白，并在汇报时告知用户
2. 严禁修改表格字段名：填表只能"填空"，不能"改写字段"。字段名（标签单元格）是表格设计者的意图，擅自修改会破坏表格语义
3. 严禁覆盖现有内容：非空单元格一律不动，避免误删用户已填数据
4. 严禁把无字段信息强塞到有字段位置：资料里有"作者"但表格没"作者"列时，应放入"图书简介"等综合字段，不应修改"书名"字段
5. 输出目录固定：所有输出文件统一进入 {WORKSPACE_DIR}/output/，不污染其他目录
6. 格式严格保留：只写入数据值，不改变原始表格的任何格式属性——单元格颜色、字体、字号、边框、列宽、行高、合并单元格、条件格式、数据验证等全部原样保留。唯一例外：封面图所在行的行高调整为 5cm，封面图所在列的列宽调整为 23 字符（仅当有封面插入时）。
7. 同名图书去重：若工作空间资料中包含同名图书的多份资料，优先使用信息更完整的来源
8. 套装书定价规则：书名含"（全X册）"标注时，源文件通常有套价（高）+ 单价（低），**必须取套价（高价）**填入。反例：源文件"定价：96.00元 32元/本" → ❌ 取 32.00 是取单价；✅ 取 96.00 是套价。书名无套书标注则不受此规则影响
9. 全自动流程：整个填表流程无需中间审核，直接输出最终文件。用户收到文件后自行校验数据准确性

Word 表格填写的特殊注意事项

当填表目标是 Word (.docx) 文档时，需要注意以下差异：

1. 使用 python-docx 而非 openpyxl：

   from docx import Document
   doc = Document(docx_path)
   table = doc.tables[0]
   

2. 正确处理合并单元格：

   • table.rows[r].cells[c] 在合并区域中会返回相同对象
   • 只在合并区域的第一个单元格填写内容，其他位置会被自动覆盖
   • 通过 cell._tc.find('.//{http://schemas.openxmlformats.org/wordprocessingml/2006/main}gridSpan') 检查水平合并
   • 通过 vMerge 检查垂直合并

3. 逐行扫描定位字段：

   for r, row in enumerate(table.rows):
       for c, cell in enumerate(row.cells):
           text = cell.text.strip()
           if '字段名关键词' in text:
               # 这就是字段标签单元格
               value_cell = table.rows[r].cells[c+1]  # 右侧通常是值
   

4. 写入内容时不要破坏格式：

   • 直接赋值 cell.text = "新值" 会清空原段落但保留单元格格式
   • 如果要保留段落格式（字体、颜色），需要操作 cell.paragraphs[0].runs[0]
   • 简单场景下用 cell.text 即可

5. 常见 Word 表格布局：

   • 两列布局：[标签] [值]
   • 多列布局：[标签1] [值1] [标签2] [值2]
   • 标签跨多列：[标签（合并）] [值（合并）]
   • 行底标签：[值（跨多列）] / [标签（跨多列）]