Tianbiao

Safety Rules

参见 _shared/core/safety-rules.md — 所有安全规则从共享层加载，避免跨技能重复维护。

关键补充：永不覆盖原始模板。所有输出写为新文件（课程/主体名 + - + 文档名）。填表前先备份或只读打开源数据。

填表 (TianBiao / Template-Preserving Form Filler)

严格"照着原表填"的填表技能。核心原则：复制原模板 → 把数据填进对应单元格 → 保持原有字体、边框、合并单元格与版式，绝不从零重排。

The one rule that matters: copy the original template, drop text into the right cells, keep the original formatting. Never rebuild the table from scratch.

Quick Commands

核心理念 / Core Philosophy

从一次真实的期末材料填表任务中提炼：教师给出固定的学校模板（试卷质量分析表、成绩分析表、过程性评价档案等）和原始数据（点名册、作业、讨论记录），要求"严谨地按照原来的格式，只填写内容"。

三条铁律：

1. 不重排，只填充。绝不用 python-docx 从零画表——那样字体、字号、边框、行高、合并单元格都会走样。必须打开原模板，只替换单元格里的文字。
2. 保原字体。填入的文字继承该单元格原有 run 的 rPr（字体、字号、颜色）。仅去除模板里的"示例红字"和"黄色高亮批注"。
3. 明细表要规整。大批量名单（如全班成绩明细）必须：小号字体、表头跨页重复（tblHeader）、行不跨页断裂（cantSplit）、紧凑单元格边距——绝不能让一张表松散地跨好几页还错行。

五步工作流 / Five-Step Workflow

Step 1  转换 Convert
  .doc/.xls 老格式 → .docx/.xlsx（用 LibreOffice headless，保真度远高于 textutil/pandoc）
  soffice --headless --convert-to docx --outdir <dir> <template.doc>

Step 2  摸底 Inspect
  读出模板每个表的可见单元格结构（含 gridSpan/vMerge）、每个关键单元格的字体 rPr。
  确认"哪一行哪一列填什么"，特别注意合并单元格导致的逻辑网格 vs 可见网格差异。

Step 3  准备数据 Prepare Data（两条路径）
  3a. 非结构化资料 → 文本提取 + OCR + 错行纠正 → 结构化字段
      按文件类型路由提取器（PDF文本层/OCR/Office解析），纠正OCR错字和错行，
      校验关键数字回查原文位置，未提取字段列入"需人工补"。详见 rules/text-extraction.md
  3b. 结构化源文件 → 直接读取 + 公式反推
      点名册/成绩表等结构化数据，必要时反推计算公式（如平时=0.2×课堂+0.4×作业均+0.4×测验），
      用全体样本验证吻合。

Step 4  填充 Fill
  打开原模板 docx，按可见单元格索引 vcells(table, row_idx) 定位并写入。
  分析类长文本：克隆模板段落样式（标题段/正文段），保留字体，去高亮，加正文首行缩进。
  明细表：新建紧凑表格（小号宋体 + tblHeader + cantSplit + 窄边距）。

Step 5  校验 Verify
  重新打开输出文件，逐表核对：表数量、行列、字体、边框、每条数据与源一致。
  可选：转 PDF 数页数，确认排版整洁不散乱。

关键实现要点 / Key Implementation Notes

• 可见单元格 vs 逻辑网格：python-docx 的 table.cell(r,c) 会把合并单元格展开成逻辑网格，导致定位错位。填表务必用"可见单元格"：

  from docx.table import _Cell
  from docx.oxml.ns import qn
  def vcells(table, ri):
      tr = table.rows[ri]._tr
      return [_Cell(tc, table) for tc in tr.findall(qn('w:tc'))]
  

• 保字体填值：改单元格首个 run 的 text，删多余 run，剥离 w:color/w:highlight。
• 明细表防散架：每行 w:trPr 加 w:cantSplit；表头行加 w:tblHeader；w:tblCellMar 设窄边距；正文 run 用小字号（如 w:sz=18，即 9pt）。
• 转换引擎：优先 LibreOffice（soffice --headless）。macOS 若缺 LibreOffice.app，brew reinstall --cask libreoffice。textutil/pandoc 只用于读取，不用于生成交付件。

详见 scripts/fill_docx_template.py —— 可复用的填表工具函数库。

Rules

• rules/workflow.md - 完整五步工作流与命令行操作
• rules/text-extraction.md - 从非结构化资料提取文本、OCR识别、错行纠正
• rules/format-preservation.md - 保格式的具体 OOXML 技术（可见单元格、字体继承、明细表防散架）
• rules/data-integrity.md - 数据提取、公式反推与校验
• rules/writing-analysis.md - 分析类表格文字的填写原则（客观、实事求是、尊重学情、不甩锅）
• rules/anti-aigc.md - 填表文字反AIGC与套话规避

适用表格类型 / Supported Form Types

• 试卷质量分析表、试卷成绩分析表（考试课，按试卷/教师为单位）
• 考查课成绩分析报告表（考查课）
• 过程性评价材料档案（封面+评价方案+各环节标准+全体学生成绩明细表）
• 成绩单、考核成绩登记表、点名册
• 各类含固定表头、需要批量填人名/分数的学校表格

边界情况 / Edge Cases

• 模板题型行数 ≠ 数据项数：先增/删模板中可复制的数据行（克隆 w:tr），再填。
• 多班合并 vs 分班：成绩分析"以教师为单位"多班合并填 1 份；质量分析"以试卷为单位"。可同时产出合并版与分班版。
• 合并单元格的续行：填 vMerge=continue 的单元格要留空，只在 restart 行写值。
• 超长名单：拆分到多页时靠 tblHeader+cantSplit 保持每页有表头、行不断裂；必要时进一步缩小字号。
• 纯 Excel 模板：用 openpyxl 打开原 xlsx，只写值不动样式；.xls 先转 .xlsx。

常见问题排查 / Troubleshooting

• 填完字体变了 → 没有继承原 run 的 rPr，或用 python-docx 新建了段落/表格。改为在原单元格上改 text。
• 数据填错格 → 用了 table.cell(r,c) 遇到合并单元格错位。改用 vcells() 可见单元格定位。
• 表格跨页散架/错行 → 缺 cantSplit/tblHeader，或字号过大。补齐并缩小字号。
• %d/%.1f 原样出现在文档里 → 字符串格式化没生效（少了 % (...)）。校验步骤应能抓到。
• .doc 转换丢表格 → 用了 textutil 转 docx（会拍平表格）。改用 LibreOffice。

版本历史 / Version History

See Also / 相关技能

• /公文 from official-document-writer — 需要从零撰写公文正文时（本技能侧重"照模板填"，公文技能侧重"写内容"）
• /人话 from humanizer — 分析类文字需要去AI味、更自然时