旺财填表助手是一个面向离线办公场景的本地智能填表工具。它帮助用户选择待填表格、选择参考资料、确认字段规则，再把可追溯的内容填入新的 .xlsx 文件，并生成审计报告。
项目目标很克制：不做通用聊天机器人，不让模型自由操作文件，只做白盒、可复核、可离线部署的填表流程。
- 读取和分析
.xlsx待填表，识别表头、标题、空白格、待填列和常见键值型表单。 - 支持图片/PDF 待填表先经 OCR 生成
.xlsx草稿，再进入人工确认和填表流程。 - 支持多份参考资料：
.txt、.md、.json、.csv、.docx、.xlsx、.pptx、有文本层 PDF，以及图片/扫描 PDF OCR 草稿。 - 支持自然语言规则编译和白盒规则表：用户可以点选字段、来源、填法、筛选条件和变化方式。
- 支持 NuExtract 2B 抽取，Qwen 2B 做解释、摘要和必要补充；两个模型都通过本地 llama.cpp server 运行。
- 支持填表审计：每个结果保留目标单元格、填入值、来源文件、证据片段、置信度和复核状态。
- 支持批量发票 OCR 草稿导入台账，重复发票、低置信和缺字段进入复核。
- 支持运行环境探测，按本机内存和 CPU 自动选择模型上下文、线程数和 OCR worker 数。
程序运行本身不要求预装 WPS。
当前核心链路直接解析和写入 .xlsx，不调用 WPS 或 Office COM；OCR、PDF 渲染和模型服务也走项目内适配器。
建议安装 WPS 的原因是：
- 用户需要打开、核对和手工微调生成的
.xlsx。 - 旧格式
.wps/.doc/.xls/.et需要外部转换器时，可由 WPS 或 LibreOffice 转成现代 OpenXML 格式。
第一版最佳输入格式是 .xlsx、.docx、.txt、.pdf 和常见图片格式。
当前发布包主要面向 Windows x64 离线办公电脑；国产桌面系统、ARM 设备或 Windows 兼容层需要单独适配和实测。
| 场景 | 建议配置 | 说明 |
|---|---|---|
| 最低可用 | 4 核 CPU、8GB 内存、10GB 可用磁盘 | 可做小批量填表、清晰发票 OCR；模型默认 4096 上下文，OCR 1 worker。 |
| 推荐配置 | 6-8 核 CPU、16GB 内存、15GB 可用磁盘 | 适合常规批量填表、多文件参考资料和图片/PDF OCR。 |
| 批量/OCR 较多 | 8 核以上 CPU、24GB+ 内存、20GB 可用磁盘 | 适合较大上下文、批量发票、扫描件较多的场景；模型默认 8192 上下文。 |
运行边界：
- 不需要独立显卡，默认走 CPU 推理和 CPU OCR。
- 不要求联网，完整离线包应包含模型、llama.cpp、OCR 依赖和配置文件。
- 不要求预装 WPS/Office；WPS 主要用于打开、核对和手工微调输出
.xlsx。 - 不要求 Docker；Docker 只用于开发者检查发布包依赖是否齐全。
- 如果完整包没有内置
runtime\python\python.exe，OCR/PDF/转换器自检需要机器上有 Python 3.12。面向完全离线单位发包时，建议随包带runtime\python。 - 安装包含模型后体积较大，解压和安装时建议预留比压缩包更大的临时空间。
推荐目录结构：
WangcaiOfficeAssistant/
build/
WangcaiFormAssistant.exe
wangcai_form_assistant_cli.exe
config/
default.json
models/
nuextract/
NuExtract-2.0-2B-Q4_K_M.gguf
qwen3.5-2b-q4km/
Qwen3.5-2B-Q4_K_M.gguf
runtime/
llama_cpp/
ocr/
converters/
tests/
docs/
模型文件较大，不建议提交到 Git。发布离线包时可以随包提供模型，也可以让用户按说明放到 models/ 目录。
默认配置中模型 contextSize、threads、threadsBatch 为 0，表示按主机自动计算：
- 24GB+：模型上下文 8192，OCR 提高并行度。
- 16GB：模型上下文 6144。
- 8GB：模型上下文 4096，OCR 保守使用 1 个 worker。
- 低内存：模型上下文 2048，优先保证能跑。
一键安装到本机：
一键安装.cmd默认安装到 %LOCALAPPDATA%\WangcaiFormAssistant，并创建“旺财填表助手”快捷方式。也可以指定安装目录：
一键安装.cmd E:\WangcaiFormAssistant启动桌面程序：
启动旺财填表助手.cmd或直接运行：
build\WangcaiFormAssistant.exe命令行自检：
一键自检.cmd发布包依赖完整性检查：
py -3.12 scripts\check_release_dependencies.py --root .
installer\docker_dependency_check.cmdDocker 检查是可选工程检查，只验证发布包文件清单、相对路径和模型/OCR 依赖是否齐全；实际离线部署不依赖 Docker。
常用 CLI：
build\wangcai_form_assistant_cli.exe runtime-probe
build\wangcai_form_assistant_cli.exe model-status --config config\default.json
build\wangcai_form_assistant_cli.exe analyze-xlsx --workbook tests\fixtures\sample_form.xlsx
build\wangcai_form_assistant_cli.exe rule-draft --workbook tests\fixtures\sample_form.xlsx --output-rules tests\outputs\sample_rules.json
build\wangcai_form_assistant_cli.exe dry-run --workbook tests\fixtures\sample_form.xlsx --reference-file tests\fixtures\contract_summary.txt --reference-file tests\fixtures\application_note.txt --rules tests\fixtures\sample_field_rules.json --write-output --output-workbook tests\outputs\sample_filled.xlsx --output-json tests\outputs\sample_audit.jsonOCR 示例：
build\wangcai_form_assistant_cli.exe ocr-draft --source tests\fixtures\generated\real_invoice_cn.png --engine rapidocr --output-json tests\outputs\real_invoice_draft.json --review-json tests\outputs\real_invoice_review.json
build\wangcai_form_assistant_cli.exe ocr-form-to-xlsx --source tests\fixtures\generated\real_invoice_cn.png --output-workbook tests\outputs\ocr_form_draft.xlsx --output-json tests\outputs\ocr_form_report.json关闭模型常驻进程：
build\wangcai_form_assistant_cli.exe model-cleanup --config config\default.json需要 CMake、Ninja 和 MSVC。可在 Visual Studio x64 Native Tools Command Prompt 中执行：
cmd /c _build_debug.cmd全功能测试：
py -3.12 scripts\run_full_release_test.pyGUI 冒烟测试：
py -3.12 scripts\run_gui_smoke_test.py当前完整真机测试报告：
docs/测试报告/旺财填表助手全功能真机测评报告_20260630.md
报告覆盖：
- 普通表格填报。
- 花名册筛选。
- 合同台账。
- 批量发票。
- OCR 图片/PDF。
- 图片/PDF 待填表转
.xlsx。 - 自然语言规则编译。
- 模型常驻、进程清理和离线路径检查。
项目代码采用 Apache-2.0。第三方组件、运行时和模型遵循各自许可证，详见：
LICENSETHIRD_PARTY_NOTICES.md
打包发布时，模型卡、OCR 依赖、llama.cpp、RapidOCR、ONNX Runtime、pypdfium2 等组件的许可证和来源说明必须随包保留。
GPU 加速版采用独立发行包，不影响 CPU 默认版。建议 NVIDIA 8GB 显存以上机器使用。
- CPU 版启动：
start_wangcai_form_assistant.cmd/启动旺财填表助手.cmd - GPU 版启动：
start_wangcai_form_assistant_gpu.cmd/启动旺财填表助手-GPU.cmd - CPU 版配置：
config/default.json，运行时：runtime/llama_cpp - GPU 版配置：
config/gpu.json，运行时：runtime/llama_cpp_cuda - GPU Preview v0.1.0 已补齐 Windows CUDA llama.cpp runtime，运行包为
WangcaiFormAssistant-GPU-Preview-v0.1.0-runtime.tar.gz。 - GPU 包不重复包含 GGUF 模型；安装时需要把 GPU runtime 包、NuExtract 2B 模型包、Qwen 2B 模型包解压到同一个目录。
- GPU 版第一阶段只加速 NuExtract/Qwen 这两个 llama.cpp 模型；OCR、PDF 转换和复核链路仍默认走 CPU/RapidOCR 路线。
GPU 环境检查：
检查GPU环境.cmd
build\wangcai_form_assistant_cli.exe model-status --config config\gpu.jsonGPU Preview 发布说明见 docs/release/GPU-Preview-v0.1.0发布说明.md，GPU 真机测试报告见 docs/测试报告/旺财填表助手GPU预览版测试报告_20260701.md。