lovstudio-fill-form

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

fill-form — Fill Word Form Templates

fill-form — 填充Word表单模板

This skill fills in Word document form templates (.docx) with user-provided data. It detects table-based form fields (label in one cell, value in the adjacent cell) and populates them automatically.

此技能使用用户提供的数据填充Word文档表单模板（.docx）。它会检测基于表格的表单字段（一个单元格为标签，相邻单元格为值）并自动填充。

When to Use

使用场景

User has a
```
.docx
```
form template with blank fields to fill
User wants to fill in an application form, registration form, etc.
Document uses Word tables for form layout (label | value cell pairs)
User mentions 填表, 申请表, 登记表, or wants to automate form filling

用户拥有带有空白字段的
```
.docx
```
表单模板
用户需要填充申请表、登记表等表单
文档使用Word表格进行表单布局（标签 | 值单元格对）
用户提及填表、申请表、登记表，或希望实现表单填写自动化

Workflow (MANDATORY)

工作流程（必须遵守）

You MUST follow these steps in order:

你必须按以下顺序执行步骤：

Step 1: Scan the template

步骤1：扫描模板

Discover all fillable fields:

bash

python lovstudio-fill-form/scripts/fill_form.py --template <path> --scan

发现所有可填写字段：

bash

python lovstudio-fill-form/scripts/fill_form.py --template <path> --scan

Step 2: Pre-fill from known context

步骤2：从已知上下文预填充

Before asking the user, try to fill as many fields as possible from:

User memory — name, title, organization, etc.
Context files — if the user provides reference documents (e.g. STARTER-PROMPT.md, project docs), extract relevant info to fill content-heavy fields
Conversation context — anything already mentioned

For content-heavy fields (e.g. "主要内容/简介/摘要"), actively compose the content by synthesizing from context files, user's known expertise, and the topic/title.

在询问用户之前，尝试从以下来源填充尽可能多的字段：

用户记忆 — 姓名、头衔、机构等信息
上下文文件 — 如果用户提供参考文档（如STARTER-PROMPT.md、项目文档），提取相关信息填充内容较多的字段
对话上下文 — 已提及的任何信息

对于内容较多的字段（如“主要内容/简介/摘要”），通过整合上下文文件、用户已知专业知识以及主题/标题，主动撰写内容。

Step 3: Ask only what you don't know

步骤3：仅询问未知信息

Use
AskUserQuestion
to collect ONLY the fields you cannot fill from context.

Group fields into a single question
If ALL fields are unknown, list them all
If the user says some fields can be left blank (e.g. "其他朋友会帮我填"), respect that and leave those empty
Do NOT force the user to provide every field

使用
AskUserQuestion
仅收集无法从上下文中填充的字段。

将字段整合为一个问题
如果所有字段都未知，列出全部字段
如果用户表示某些字段可留空（例如“其他朋友会帮我填”），请尊重用户意愿并保留这些字段为空
不得强制用户提供所有字段

Step 4: Fill and save

步骤4：填充并保存

Write a JSON data file (avoids shell escaping issues with long text), then run:

bash

python lovstudio-fill-form/scripts/fill_form.py \
  --template <path> \
  --data-file /tmp/form_data.json

Output path rules:

Default:
```
<template_dir>/<name>_filled.docx
```
(same directory as the template)
If the template is in a temp directory or system path, save to user's document directory or ask the user where to save
Use
```
--output
```
to override explicitly

编写JSON数据文件（避免长文本的shell转义问题），然后运行：

bash

python lovstudio-fill-form/scripts/fill_form.py \
  --template <path> \
  --data-file /tmp/form_data.json

输出路径规则：

默认：
```
<template_dir>/<name>_filled.docx
```
（与模板同一目录）
如果模板位于临时目录或系统路径，保存到用户的文档目录，或询问用户保存位置
使用
```
--output
```
参数可显式覆盖默认路径

CLI Reference

CLI参考

Argument	Default	Description
`--template`	(required)	Path to template .doc/.docx file
`--output`	`<template_dir>/<name>_filled.docx`	Output .docx path
`--scan`	false	List all detected form fields
`--data`	`""`	JSON string with field→value mapping
`--data-file`	`""`	Path to JSON file with field→value mapping
`--font`	Platform CJK serif	Font name for filled text
`--font-size`	`11`	Font size in points

参数	默认值	描述
`--template`	必填	模板.doc/.docx文件的路径
`--output`	`<template_dir>/<name>_filled.docx`	输出.docx文件的路径
`--scan`	false	列出所有检测到的表单字段
`--data`	`""`	包含字段→值映射的JSON字符串
`--data-file`	`""`	包含字段→值映射的JSON文件路径
`--font`	平台CJK衬线字体	填充文本的字体名称
`--font-size`	`11`	字体大小（磅）

How Field Detection Works

字段检测原理

Table-based (primary): Scans all tables for rows with label→value cell pairs. A label cell contains short text (CJK or Latin); the adjacent cell is the value field.
Merged rows: Detects full-width merged cells with "Label：" pattern as large text areas.
Paragraph fallback: If no tables found, detects "Label：value" patterns in paragraphs.

基于表格（主要方式）：扫描所有表格，查找包含标签→值单元格对的行。标签单元格包含短文本（CJK或拉丁）；相邻单元格为值字段。
合并行：检测带有“标签：”格式的全宽合并单元格，将其视为大文本区域。
段落 fallback：如果未找到表格，则检测段落中的“标签：值”格式。

Limitations

限制

```
.doc
```
files are auto-converted to
```
.docx
```
via macOS
```
textutil
```
, which loses table structure. For best results, use
```
.docx
```
templates directly. If you only have
```
.doc
```
, convert with LibreOffice first:
```
libreoffice --headless --convert-to docx file.doc
```
Fields are matched by normalized label text (whitespace removed). If a label contains unusual formatting, the match may fail — use
```
--scan
```
to verify detection.

```
.doc
```
文件会通过macOS的
```
textutil
```
自动转换为
```
.docx
```
，此过程会丢失表格结构。为获得最佳效果，请直接使用
```
.docx
```
模板。如果只有
```
.doc
```
文件，请先使用LibreOffice转换：
```
libreoffice --headless --convert-to docx file.doc
```
字段通过标准化标签文本（移除空格）进行匹配。如果标签包含特殊格式，匹配可能失败——请使用
```
--scan
```
验证检测结果。

Dependencies

依赖项

bash

pip install python-docx --break-system-packages

bash

pip install python-docx --break-system-packages