When to Use
- User provides a Word template (.docx) with
{{field_name}}格式的占位符 - User wants to fill the template with specific content (text, form data, OCR results, etc.)
- User has multiple templates and wants a unified filling approach
Template Standard（模板规范）
占位符格式：{{field_name}}
公司名称：{{company_name}}
联系人：{{contact_person}}
日期：{{date}}
金额：{{amount}}
| 格式 | 示例 | 说明 |
|---|---|---|
{{field_name}} |
{{公司名称}} |
标准占位符 |
{{field_name}} |
{{company_name}} |
英文字段名也行 |
| 多行 | {{address_line1}}\n{{address_line2}} |
支持换行 |
技能会自动识别 {{...}} 模式作为占位符。
Architecture
┌─────────────────────────────────────────────────────────┐
│ WordMaster Skill │
├─────────────────────────────────────────────────────────┤
│ extract → map → fill │
│ (结构识别) (智能映射) (精准填充) │
│ │
│ • 段落/表格 • LLM mapping • 按位置替换 │
│ • 占位符检测 • 规则匹配 • 编码处理 │
│ • 标签提取 • 顺序填充fallback • 验证 │
└─────────────────────────────────────────────────────────┘
Parameters
| Parameter | Required | Description |
|---|---|---|
template |
Yes | Path to Word template (.docx) |
user_input |
Yes | Content to fill in (text, JSON, key-value pairs) |
output |
No | Output path (default: output-filled.docx) |
Execution Pipeline
Step 1: Extract - scripts/extract.py
分析模板结构，提取所有占位符和标签信息。
python3 scripts/extract.py <template.docx>
Output:
{
"segments": [...],
"total": 1935,
"placeholder_count": 586,
"table_structures": [
{"table": 2, "rows": 23, "cols": 4, "label_col": 0}
]
}
自动识别内容：
- 段落占位符 vs 表格占位符
- 占位符类型 (*, /, ___, 空白等)
- 表格结构（行数、列数、标签列位置）
- 乱码标签检测
Step 2: Map - scripts/map.py
将用户输入映射到占位符位置。
python3 scripts/map.py "<user_input>" <extract_output.json>
多策略 fallback（保证任何模板都能产出结果）：
| Strategy | Description | Fallback Trigger |
|---|---|---|
| LLM mapping | 调用 LLM 理解语义后映射 | API key 缺失或失败 |
| Rule-based | 标签关键词匹配 | 匹配率 < 70% |
| Sequential | 按顺序填充 | 匹配率 < 50% |
支持输入格式：
- key: value, key2: value2 (冒号分隔)
- key value, key2 value2 (逗号分隔)
- 多行格式
- 纯文本 key-value
Step 3: Fill - scripts/fill.py
按位置替换占位符。
python3 scripts/fill.py <template.docx> <mapping.json> <output.docx>
Step 4: Verify - scripts/verify.py
验证输出质量。
python3 scripts/verify.py <output.docx> [mapping.json] [extract.json]
检查项：
- 所有占位符是否已替换
- 编码是否正确（无乱码）
- 文件是否可读
Output Protocol
STATUS_UPDATE: Validating template...
STATUS_UPDATE: Found {n} placeholders
STATUS_UPDATE: Analyzing table structures...
STATUS_UPDATE: Parsing user input ({n} KV pairs)...
STATUS_UPDATE: [Strategy 1] Trying LLM mapping...
STATUS_UPDATE: Mapping complete: {n}/{n} placeholders
STATUS_UPDATE: Filling document...
STATUS_UPDATE: Verifying output...
RESULT_READY: /path/to/output.docx
Error Handling
| Error | Meaning | Recovery |
|---|---|---|
ERROR: Template not found |
文件不存在 | 检查路径 |
ERROR: No placeholders found |
模板无占位符 | 确认模板格式 |
ERROR: Office skill failed |
Word 操作失败 | 检查 office 技能 |
WARNING: Low mapping coverage |
映射率低 | 检查输入格式 |
CLI Usage
# 完整流水线
python3 scripts/e2e.py <template.docx> --input "<user_input>" --output <output.docx>
# 单独使用各阶段
python3 scripts/extract.py template.docx > extract.json
python3 scripts/map.py "key: value" extract.json > mapping.json
python3 scripts/fill.py template.docx mapping.json output.docx
python3 scripts/verify.py output.docx mapping.json extract.json
Environment Variables
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
LLM API key (用于智能映射) |
ANTHROPIC_BASE_URL |
LLM API URL (默认: https://api.minimaxi.com/anthropic) |
Examples
Basic Usage
user_input="公司名称: 测试公司, 地址: 北京市, 联系人: 张三"
python3 scripts/e2e.py 模板.docx --input "$user_input" --output 结果.docx
With Explicit Stages
# Extract structure
python3 scripts/extract.py 模板.docx > extract.json
# Map content
python3 scripts/map.py "公司名称: 测试公司" extract.json > mapping.json
# Fill template
python3 scripts/fill.py 模板.docx mapping.json 结果.docx
# Verify
python3 scripts/verify.py 结果.docx mapping.json extract.json
Extending
添加新的占位符类型： 修改 extract.py 中 _is_placeholder() 函数。
添加新的输入格式： 修改 map.py 中 parse_user_input() 函数。
添加新的映射策略： 在 map.py 中 map_content() 添加新的策略函数。
Notes
- 模板标准格式：
{{field_name}}- 每个字段都要明确标记 - 兼容旧格式
*、/、___等作为占位符 - 表格自动检测第一列为标签列
- 编码问题自动检测并标记【待确认】
- LLM 映射失败时自动 fallback 到规则/顺序映射
