docfill
docfill 是一个本地文档填充命令行工具。它从 Excel 或 SQLite 读取结构化数据，按业务条件筛选出需要使用的数据行，再把数据填入 Word 或 Excel 模板中的 {{字段名}} 占位符。
本工具的定位是“小型、稳定、便于数字员工调用”。它只负责本地数据到本地模板的填充，不内置业务系统登录、审批流、Web 界面、模板设计器或权限系统。
核心理解
task.json 是某一种业务报表的固定任务说明书，命令行 --var 是本次运行传入的具体条件。
不同业务 = 不同 task.json
本次运行的日期、工单编号、人员、批次 = --var
真实数据 = Excel 或 SQLite
模板文件 = Word 或 Excel
优先级：
数据表里的字段 > 命令行 --var > task.json 里的 vars
例如 task.json 中写了：
"vars": {
"date": "2026-06-18"
}
运行时执行：
dist/docfill-darwin-arm64 run -c task.json --var date=2026-06-19 --var ticket_no=GD-001
实际使用的是：
date = 2026-06-19
ticket_no = GD-001
也就是 --var date=2026-06-19 会覆盖 task.json 里的默认 date=2026-06-18。
最小实践
进入仓库目录：
cd /Users/zhaoyilun/Documents/xls_doc
构建本机二进制：
bash scripts/build.sh
输出示例：
/Users/zhaoyilun/Documents/xls_doc/dist/docfill-darwin-arm64
运行“按日期 + 工单编号筛选一条工单并生成 Word”的测试任务：
dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-002 --verbose
输出示例：
log: load config path=manual_tests/04_filter_work_order_to_word/task.json
log: read data type=excel path=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/source_work_orders.xlsx
log: read data type=excel path=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/source_work_orders.xlsx rows=3
log: filter rows=3 matched=1 expect=one
log: render row=1 output=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/out/work_order_2026-06-18_GD-002.docx
generated 1 file(s)
- /Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/out/work_order_2026-06-18_GD-002.docx
查看生成结果：
open manual_tests/04_filter_work_order_to_word/out
更多可运行案例见 HOWTO.md 和 manual_tests/README.md。
常用命令
构建：
bash scripts/build.sh
运行一个任务：
dist/docfill-darwin-arm64 run -c task.json
运行任务并传入本次筛选条件：
dist/docfill-darwin-arm64 run -c 工单日报.json --var date=2026-06-18 --var ticket_no=GD-002
输出诊断日志：
dist/docfill-darwin-arm64 run -c task.json --verbose
重新生成本地测试素材：
/Users/zhaoyilun/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 scripts/make-manual-test-materials.py
运行自动化冒烟测试：
bash scripts/smoke.sh
运行 Go 测试：
go test -count=1 ./...
筛选配置示例
Excel 工单表：
日期 工单编号 客户名称 系统来源 处理结果 下一步
2026-06-18 GD-001 A 公司 PMS3.0 已派单 等待现场反馈
2026-06-18 GD-002 B 公司 D5000 已完成 归档并同步日报
2026-06-19 GD-001 C 公司 风控平台 待复核 补充截图
task.json：
{
"vars": {
"date": "2026-06-18"
},
"data": {
"type": "excel",
"path": "./source_work_orders.xlsx",
"sheet": "工单",
"header_row": 1
},
"filter": {
"equals": {
"日期": "{{date}}",
"工单编号": "{{ticket_no}}"
},
"expect": "one"
},
"template": {
"path": "./work_order_template.docx"
},
"output": {
"path": "./out/work_order_{{日期}}_{{工单编号}}.docx",
"overwrite": true
}
}
运行：
dist/docfill-darwin-arm64 run -c task.json --var date=2026-06-18 --var ticket_no=GD-002
筛选含义：
找到 日期 = 2026-06-18，并且 工单编号 = GD-002 的那一行。
filter.expect 支持：
one: 必须只匹配一行，适合工单、单份日报、单个报表。many: 允许匹配多行，适合按日期生成多个人或多个部门的报表。
未配置 filter 时，工具沿用旧行为：读取到的每一行都会生成一个输出文件。
核心规则
- 配置文件使用 JSON。
- 数据源支持
.xlsx和 SQLite.db。 - 模板与输出支持
.docx和.xlsx。 - 模板占位符格式为
{{字段名}}。 - Excel 数据的表头行提供字段名，SQLite 查询结果的列名提供字段名。
- 常用场景是通过
filter.equals先筛选数据，再填充模板。 - 多个筛选条件之间是“全部满足”关系。
- 筛选只支持等值匹配，不支持模糊匹配、范围查询、OR 或复杂表达式。
- 复杂情况建议业务人员整理 Excel，例如新增“填报批次”“业务唯一标识”等辅助列。
vars提供默认变量，命令行--var key=value可以覆盖同名变量。- 数据行字段优先于
vars和--var。 _row是内置变量，表示当前输出对应的结果行序号，从1开始。- 默认不覆盖已存在文件，只有
output.overwrite: true才允许覆盖。 - 成功结果写入 stdout，诊断日志和错误写入 stderr，便于数字员工或调度脚本判断执行结果。
退出码
0: 执行成功。1: 配置、数据、模板或输出处理失败。2: 命令行参数错误。
错误输出格式：
docfill: [ERROR_CODE] message
hint: repair suggestion
context: key=value
常见筛选错误：
DATA_FILTER_FIELD: 筛选字段不在数据表中。DATA_FILTER_VALUE: 筛选条件引用的变量没有提供。DATA_FILTER_NO_MATCH: 没有找到符合条件的数据行。DATA_FILTER_MULTI_MATCH: 期望匹配一行，但实际匹配多行。
完整错误码、日志说明和集成建议见 HOWTO.md。
文档索引
- HOWTO.md: 完整使用说明，包含最小实践、详细配置、输入输出示例、错误处理和数字员工调用建议。
- manual_tests/README.md: 本地真实测试素材说明。
- docs/digital-employee-runbook.md: 面向数字员工或调度脚本的最小运行约定。