fill-protocol

Fill-Protocol 技能

核心原则（不得违反）

1. 打开现有模板——绝不要从头创建。 使用 Document(template_path)，而不是 Document()：重建会丢失页眉徽标、自定义页边距、页脚占位符和页码。在原位替换单元格/段落文本；绝不要只执行 cell.text = "value" 赋值，因为这会清除运行级样式（粗体、颜色、eastAsia 字体）。
2. 编辑前，使用 LibreOffice 无头模式将 .doc 转换为 .docx。 不支持 pandoc -f doc；textutil 会破坏表格结构（合并单元格会丢失）。
3. 根据左侧标签文本匹配单元格，不要使用 table.cell(2, 1) 这类行/列坐标。 模板会不断变化，按坐标匹配可能会悄无声息地出错。
4. 对每个已填充行应用 cantSplit，避免行跨页拆分。
5. 对于 CJK 语言，设置 eastAsia 字体属性，而不只是设置 run.font.name，否则韩文/日文汉字/中文会使用回退字体显示。
6. 验证每次填充操作：解决每一行 [MISS] 和每一行 WARN:（[TABLE-MISS]、[SECTION-MISS]、[RAW-NEWLINE]），然后再提交已填表格。

依赖项

始终需要 Python 包 docxtpl python-docx pyyaml。只有在使用旧版 .doc 模板时才需要 LibreOffice（macOS 上约 700 MB）。随附的 setup.sh 会检测缺少的依赖项：

bash ${CLAUDE_SKILL_DIR}/setup.sh check     # report what's installed (read-only)
bash ${CLAUDE_SKILL_DIR}/setup.sh install   # install missing pieces (asks before each)

代表用户运行此技能时：

1. 如果模板已经是 .docx，完全跳过 LibreOffice。
2. 调用 doc_to_docx.py 之前，运行 setup.sh check。如果缺少 LibreOffice，先询问用户是否要安装，因为安装包约 700 MB。
3. 除非用户在本次会话中明确授权无人值守安装，否则绝不要向 setup.sh install 传入 --yes，因为它会在不提示的情况下安装。
4. 如果用户拒绝，请他们手动转换 .doc（Word/LibreOffice/Pages → 另存为 → .docx），然后使用转换后的文件重新运行。

工作流

步骤 1 — 将旧版 .doc 转换为 .docx（如有需要）

python3 ${CLAUDE_SKILL_DIR}/scripts/doc_to_docx.py path/to/template.doc path/to/template.docx

步骤 2 — 检查模板结构

python3 ${CLAUDE_SKILL_DIR}/scripts/inspect_template.py path/to/template.docx

它会列出每个表格、每个单元格（坐标和内容预览）以及每个顶层段落。 请从该输出中获取 YAML 要使用的准确标签。

步骤 3 — 编写内容 YAML

从 ${CLAUDE_SKILL_DIR}/examples/example_irb_template.yaml 开始。共有三种填充模式；所有键均为 可选。

protections:
  korean_font: "맑은 고딕"   # CJK font (set to "Noto Sans CJK KR", "SimSun",
                              # "MS Mincho", etc. for other locales)
  cant_split: true            # Apply <w:cantSplit/> to every filled row

  # Readability options (defaults shown)
  blank_between_paragraphs: true            # Enter between \n\n chunks
  blank_around_section_header: true         # Enter above/below filled sections
  blank_around_all_section_headers: false   # opt-in; also touches untouched sections
  normalize_page_breaks: true               # empty page-break paragraphs -> pageBreakBefore

# Mode 1 — table key/value (left-label cell → right value cell)
table_kv:
  "Study Title": "Multi-center prospective validation of ..."
  "Principal Investigator": "Last, First (Department)"
  "연구 목적": "본 연구는 ..."

# Mode 2 — section replacement (find numbered header, replace until next header)
section_replace:
  "1. Background":
    "Hepatocellular carcinoma is the third leading cause of ..."
  "4. 연구 배경 및 이론적 근거":
    "..."

# Mode 3 — single paragraph in-place text replacement
paragraph_replace:
  "Title:":
    "Title: Multi-center prospective validation of ..."

更改任何可读性选项的默认值之前，请先阅读 ${CLAUDE_SKILL_DIR}/references/best_practices.md（可读性调节）。

内容规则：只有在通过 /search-lit 确认 DOI 或 PMID 后，才添加参考文献；否则标记为 [UNVERIFIED - NEEDS MANUAL CHECK]；对于任何未经确认的临床定义、诊断标准或指南主张，标记为 [VERIFY] 并询问用户。

步骤 4 — 运行填充

python3 ${CLAUDE_SKILL_DIR}/scripts/fill_form.py \
  --template path/to/template.docx \
  --content  content.yaml \
  --output   path/to/filled.docx

CLI 会为每项填充操作打印 [OK] / [MISS]，然后打印摘要以及所有 WARN: 行。 提交前，调查每个 [MISS] 和 WARN:（原则 6）。

table_kv、section_replace 和 paragraph_replace 下的每个值都会按输入原样写入（012345、12:30、1.10、No 均保持为文本）。空值或列表/映射值会使运行停止并以退出码 2 结束，同时指出对应标签；如需有意清空字段，请写入 ''。如果对一个后面没有编号标题的标题执行 section_replace，则会替换文档中从该处到末尾的所有内容，并在 [OK] 行中显示替换的段落数量。如果最后一个章节后还有签名/日期区块或其他内容，请使用 section_end 将范围限定下来（标题 -> 与保留区块起始段落匹配的正则表达式）：

section_end:
  "18. References": "^Investigator signature"

步骤 5 — 视觉检查

soffice --headless --convert-to pdf path/to/filled.docx

如果没有 LibreOffice（.docx 模板会跳过这一步），请改用 Word 导出 PDF。打开 PDF 并确认：页数合理、表格行没有跨页拆分、没有字体回退到 Times New Roman、所有必填字段均已填写。

当标签或章节标题不匹配、模板没有编号的章节标题（section_end）、单元格需要多行内容或单元格已合并时，请阅读 ${CLAUDE_SKILL_DIR}/references/best_practices.md。

已知限制

• 不直接处理 HWP / HWPX 输入 — 请先将其转换为 .docx。
• 合并单元格：填写参与纵向合并的标签单元格时，可能会覆盖合并区域的内容。请先在副本上测试。
• 嵌入的表单字段（Word 内容控件）：不支持；仅支持普通段落和表格单元格内容。
• 从右向左书写的文字（阿拉伯语、希伯来语）：未经测试。
• 没有后续标题的最后一个章节：除非指定 section_end 模式，否则会一直替换到文档末尾；填充工具无法区分章节正文和末尾内容块。