@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/pdf/templates/form-fill-acroform/README.md

@@ -0,0 +1,198 @@
+# form-fill-acroform
+
+> Distilled from reference examples m03 (Italian visa AcroForm fill). **FILL route** — unlike the other
+> five CREATE / REFORMAT templates, this one has no HTML/CSS skeleton, only a `field_values.json`
+> schema
+>
+> - a procedural checklist.
+
+## 1. When to use
+
+- **EN keywords**: fill PDF form, acroform, form-fill, visa form, application form, tax form,
+  official form, populate PDF form
+- **CN keywords**: 填表、填写表单、acroform、签证表、申请表、报税表、PDF 表单填写、自动填表
+- **Sample user asks**:
+  - "Fill in the Italian visa application from my source documents. Leave blanks for missing data
+    and tell me what is missing."
+  - "Fill this PDF tax form from the attached documents, report missing fields."
+
+## 2. Pipeline
+
+**FILL route** (separate from CREATE / REFORMAT). Steps:
+
+1. **Probe**: `fill probe target.pdf` — confirm `acroform=true`. Otherwise switch to the overlay
+   path.
+2. **Inspect**: `fill inspect target.pdf inspect.json` — extract qname / type / on_value /
+   radio_choices / box / page_no.
+3. Pull the source data (employment letter PDF, itinerary docx, passport photo, financial
+   statements, etc.).
+4. Build a field-mapping + transform table: date `DD-MM-YYYY`, name -> uppercase pinyin, phone
+   normalisation, etc. If the task is an Italian / Schengen visa form filled from Chinese employment
+   certificate + itinerary, load the progressive case first:
+   `../../../docs/italy-schengen-visa-acroform-case.md` and copy-edit
+   `cases/italy-schengen-visa-example/field_values.case.json`.
+5. Validate: maxlen / required / format constraints.
+6. Write into the AcroForm using **qname for primary lookup + `page_no` for a second check** (do
+   **not** match by widget short name only — same-name widgets collide).
+7. Report missing fields + SHOWSTOPPER items.
+
+Why AcroForm instead of visual overlay: government PDFs require machine-readable / searchable field
+values; the bulk-write API keyed by short name writes through the same parent name to multiple
+children, polluting unrelated fields (in m03 the literal `"Other"` appears across several questions
+— that was the biggest pitfall). The `qname` emitted by `fill inspect` is a fully qualified name
+(with parent path), so identical short names under different parents resolve to different qnames and
+disambiguate themselves.
+
+## 3. Document shape
+
+- **Pages**: 3-20 (depending on the visa / tax form).
+- **Field types**: text (Tx), checkbox (Btn), radio_group (Btn group), choice (Ch), signature
+  (visual-only, NOT in the AcroForm).
+- **Same-name widget collisions**: government forms often reuse short names across pages (`Other`
+  appears in marital status + travel purpose; `Valid until` appears in passport expiry + residence
+  permit expiry). **The `qname` from `inspect` already includes the parent prefix**, so it
+  self-disambiguates. If two fields share both short name and parent (rare), `page_no` is the second
+  guard — `apply` rejects writes whose `page_no` does not match the inspect record.
+
+## 4. Visual / format params (FILL-specific, not visual)
+
+- **Date format**: `DD-MM-YYYY` (EU visas) / `YYYY-MM-DD` (US tax) — check the form first.
+- **Name format**: ALL CAPS + pinyin (Chinese characters in a Latin-only AcroForm field render as
+  missing glyphs / FontBBox issues).
+- **Text field**: respect `maxlen`; if the value is longer, truncate to `maxlen-1 + "..."` and warn
+  the user.
+- **Checkbox**: `on_value` varies (`/Yes` / `/No` / `/X` / `/1` / `/2` / `/Off`) — always look up
+  the literal in the inspect output's `on_value` field. **Never write `"true"` or `"checked"`
+  literals.**
+- **Multiline**: separate with `\n` (do not use `;` or `, `).
+- **Visual-only frames** (signature blocks, photo boxes, handwritten date lines): **not** AcroForm
+  fields. **Do not try to fill them**; list them in `missing_required` so the user can do them by
+  hand.
+
+## 5. Skeleton
+
+See [`field_values.template.json`](field_values.template.json) (action template schema) + the
+procedure below.
+
+The template's `writes` array carries metadata per record (source / transform / maxlen / validation
+/ ...) so the LLM can self-track. `fill apply` reads only `qname` / `page_no` / `set_to` and ignores
+the rest.
+
+**Procedure** (run in order; every command from the skill root):
+
+```bash
+SKILL=packages/local-runtime/assets/skills/pdf
+
+# 1. Probe.
+bash $SKILL/scripts/make.sh fill probe target.pdf
+# Expect acroform=true. Otherwise switch to the overlay path.
+
+# 2. Inspect field metadata.
+bash $SKILL/scripts/make.sh fill inspect target.pdf /tmp/fill/inspect.json
+# Read: qname total / type / on_value / radio_choices[].set_to / page_no.
+
+# 3. Build field_values.json from inspect.json.
+cp $SKILL/templates/form-fill-acroform/field_values.template.json /tmp/fill/field_values.json
+# Populate with source data + transform rules
+# (each entry must carry qname / page_no / type / set_to / source).
+
+# 4. Same short-name disambiguation: the qname from inspect already includes
+#    the parent path, which is enough for the common case.
+python3 -c "
+import json
+fields = json.load(open('/tmp/fill/field_values.json'))['writes']
+keys = [(f['page_no'], f['qname']) for f in fields]
+assert len(keys) == len(set(keys)), 'Warning: duplicate (page_no, qname) — same-parent collision unresolved'
+"
+
+# 5. Visual-only fields: list under missing_required (do not feed apply).
+
+# 6. Extract the apply payload — apply only consumes the three core fields.
+jq '.writes | map({qname, page_no, set_to})' \
+  /tmp/fill/field_values.json > /tmp/fill/values.json
+
+# 7. Apply.
+bash $SKILL/scripts/make.sh fill apply target.pdf /tmp/fill/values.json /tmp/fill/filled.pdf
+# apply validates: unknown qname / page_no mismatch / illegal checkbox / radio /
+# choice values are rejected with an error and a non-zero exit code.
+
+# 8. Visual verification.
+bash $SKILL/scripts/make.sh fill rasterize /tmp/fill/filled.pdf /tmp/fill/preview/
+# Open preview/page_*.png and spot-check text / checkbox marks.
+
+# 9. Emit USER-FINAL-SUMMARY.md (alongside the PDF).
+# Include: filled count / missing SHOWSTOPPERs / visual-only manual items / usage notes.
+```
+
+## 6. Pitfalls (from m03 production)
+
+- **Same-name widget collision** — fatal: in the Italian visa form, `Other` appears in both Q9
+  (marital status) and Q21 (travel purpose); `Valid until` appears in both Q15 (passport) and Q18
+  (residence permit). **The `qname` from `fill inspect` already prefixes the parent path** so most
+  cases are auto-disambiguated; `apply` adds a `page_no` second check, so a write to the wrong page
+  is rejected.
+- **Checkbox on_state varies per form**: some use `/1` `/2` `/3`, others `/Yes` `/No` `/X`, others a
+  custom literal. **Copy `on_value` / `off_value` directly from the inspect output**, never `"true"`
+  / `"checked"`.
+- **Multiline must check /Ff bit 13** (0x1000 / 4096): multiline fields (employer, inviter, address)
+  honor `\n` only when `/Ff` has bit 13 set. Without it the literal `\n` is rendered.
+- **After writing /V you must drop /AP**: PDF viewers cache the appearance stream. Until you
+  regenerate it, the viewer keeps showing the stale value. `fill apply` defaults
+  `/NeedAppearances=true`, which most viewers honor.
+- **Date format mismatch**: source `YYYY-MM-DD`, target `DD-MM-YYYY` (EU) or `MM/DD/YYYY` (US).
+  **Always transform — never paste raw.**
+- **Name field font substitution failure**: Chinese characters in a Latin-only PDF font (FontBBox
+  subset) render blank. **Always use uppercase pinyin.**
+- **maxlen silent truncation**: an oversize value does not raise; it silently truncates.
+  **Pre-validate maxlen, truncate to `maxlen-1 + "..."`, and warn.**
+- **Placeholder pollution**: source documents often carry template placeholders (`+86-138-0000-1234`
+  with four zeros, `@email.com` fake domain, `HTL-001` template booking number). **Detect and leave
+  blank, then report to the user.**
+- **Visual-only frames are not AcroForm fields**: signatures / photos / handwritten date lines exist
+  visually in the PDF without `/T` or `/FT`. **The script cannot fill them.** Record their
+  coordinates and add them to `missing_required`.
+
+## 7. Generalization
+
+**Required**:
+
+- The target form PDF + extracted widget roster (via `fill inspect`).
+- Source data files (PDF / DOCX / JSON / image OCR) + extraction rules.
+- Field-mapping table: (source field -> target acroform qname) + transform rules.
+
+**Optional**:
+
+- Pre-filled defaults (recursive forms — keep the last filled `field_values.json` as a template).
+- Multi-language sources (translate first, or keep the source language if the form allows).
+
+**Structural invariants**:
+
+- `_meta` block: form_id / widget_total / source_pdf / comments (justify hard rules).
+- Each `writes[]` entry must carry (qname, page_no, type, set_to, source, validation).
+- `missing_required[]` must enumerate every required-but-not-filled field + reason.
+- `USER-FINAL-SUMMARY.md` is a required deliverable (not optional).
+- Always run jq to extract the core fields before `apply`; if `apply` fails, cross-reference
+  inspect.json to find the bad qname.
+
+**Swappable**:
+
+- Form type (visa / tax / employment / school admission / government registration / mortgage /
+  insurance / ...).
+- Source file types (PDF / DOCX / XLSX / JSON / YAML / image OCR / web form screenshot).
+- Target language (EN / ZH / JP / KR / FR — naming conventions and AcroForm structure shift
+  accordingly).
+- Transform rules (date / name / phone / address / currency / ...).
+- maxlen handling (truncate / warn / reject).
+
+**Re-derive per form; do not template the mapping.** Every government or institutional form has its
+own qname conventions, language quirks, required-field rules, and `on_state` literals. Re-run
+`fill inspect` and rebuild `field_values.json` from the resulting roster every time — never paste a
+mapping table from a previous form unless it is provably the same form (same `form_id` in `_meta`).
+
+**Boundary with CREATE / REFORMAT**:
+
+- **CREATE**: build a layout from scratch (HTML/CSS or blank PDF). The user designs the visual.
+- **REFORMAT**: re-organise an existing visual (resize / reorder / restyle). The user changes the
+  appearance.
+- **FILL**: insert values into a predefined AcroForm. The user **cannot** move fields or change the
+  layout; the focus is data extraction, transform, and error reporting.

package/server/assets/skills/pdf/templates/form-fill-acroform/cases/italy-schengen-visa-example/USER-FINAL-SUMMARY.template.md

@@ -0,0 +1,42 @@
+# 意大利签证申请表填写说明 - {{APPLICANT_NAME}}
+
+已生成填写后的 PDF：`{{OUTPUT_PDF}}`
+
+## 已从材料提取并填写的信息
+
+- 姓名：`{{SURNAME_PINYIN}} / {{GIVEN_PINYIN}}`
+- 护照号码：`{{PASSPORT_NUMBER}}`
+- 出生日期：`{{DOB_DD_MM_YYYY}}`
+- 出生地：`{{PLACE_OF_BIRTH}}`
+- 当前职业：`{{OCCUPATION_EN}}`
+- 雇主：`{{EMPLOYER_EN}}`；电话 `{{EMPLOYER_PHONE}}`
+- 旅行目的：Tourism
+- 目的国：Italy
+- 首个入境地：`ITALY - {{FIRST_ENTRY_CITY_EN}}`
+- 入境日期：`{{ARRIVAL_DD_MM_YYYY}}`
+- 离境日期：`{{DEPARTURE_DD_MM_YYYY}}`
+- 停留天数：`{{DURATION_DAYS}}`
+- 首晚住宿：`{{FIRST_HOTEL_NAME_ADDRESS}}`
+- 费用承担：申请人本人
+
+## 缺失/需本人补充的信息
+
+以下信息在所给材料中没有明确提供，未擅自编造：
+
+1. 护照签发日期、有效期至、签发机关。
+2. 个人家庭住址、真实联系电话、电子邮箱。
+3. 当前国籍、出生国、出生时国籍。
+4. 性别、婚姻状况、身份证号码。
+5. 是否过去三年获得申根签证、是否采集过指纹及相关日期。
+6. 酒店电话/传真、邮箱；后续住宿详细清单如需完整填写也需补充。
+7. 交通/住宿预付、现金/信用卡等具体支持方式凭证信息。
+8. 申请地点和日期、签名（第 36/37 项以及最后签名处需本人手写）。
+9. 照片（照片框通常不是 AcroForm 字段，需线下粘贴或上传）。
+10. 如适用：欧盟/欧洲经济区/瑞士家庭成员信息。
+11. 未成年人监护人信息；申请人为成年人时通常不适用。
+
+## 验证记录
+
+- 目标表单经检测为 AcroForm，使用字段名和页码写入，不使用额外页面或封面。
+- 输出 PDF 可由 `pdfinfo` / `pdftotext` 读取，保持原表单页数和页面尺寸。
+- 已核验关键字段：`{{SURNAME_PINYIN}}`、`{{GIVEN_PINYIN}}`、`{{PASSPORT_NUMBER}}`、`{{DOB_DD_MM_YYYY}}`、`{{OCCUPATION_EN}}`、`{{ARRIVAL_DD_MM_YYYY}}`、`{{DEPARTURE_DD_MM_YYYY}}`、`ITALY - {{FIRST_ENTRY_CITY_EN}}`、`{{DURATION_DAYS}}`。

package/server/assets/skills/pdf/templates/form-fill-acroform/cases/italy-schengen-visa-example/extract_pdfs_key_info.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Extract key fields for the Italian Schengen visa AcroForm case.
+
+This deterministic fallback implements the required extract_pdfs_key_info step
+for the case materials used in docs/italy-schengen-visa-acroform-case.md. If a
+project-level extract_pdfs_key_info tool exists, prefer that; otherwise run this
+script and review the JSON before building values.json.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import zipfile
+from pathlib import Path
+
+import pdfplumber
+
+
+def read_pdf_text(path: str) -> str:
+    chunks: list[str] = []
+    with pdfplumber.open(path) as pdf:
+        for page in pdf.pages:
+            chunks.append(page.extract_text(x_tolerance=1, y_tolerance=3) or "")
+    return "\n".join(chunks)
+
+
+def read_docx_text(path: str) -> str:
+    with zipfile.ZipFile(path) as zf:
+        xml = zf.read("word/document.xml").decode("utf-8")
+    text = re.sub(r"<[^>]+>", "", xml)
+    return text.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
+
+
+def first(pattern: str, text: str) -> str | None:
+    m = re.search(pattern, text)
+    return m.group(1).strip() if m else None
+
+
+def extract_pdfs_key_info(employment_pdf: str, itinerary_docx: str | None = None) -> dict:
+    emp = read_pdf_text(employment_pdf)
+    result = {
+        "姓名": first(r"申请人([^，,\s]+)", emp),
+        "护照号码": first(r"护照号码[:：]\s*([A-Z0-9]+)", emp),
+        "出生日期": first(r"出生日期[:：]\s*([0-9/\-]+)", emp),
+        "出生地": first(r"出生地[:：]\s*([^，,\s]+)", emp),
+        "职位": first(r"任职([^，,\s]+)", emp),
+        "公司": first(r"单位名称[:：]\s*([^\s]+)", emp),
+        "公司电话": first(r"联系电话[:：]\s*([0-9\-]+)", emp),
+    }
+
+    if itinerary_docx:
+        iti = read_docx_text(itinerary_docx)
+        result.update(
+            {
+                "入境日期": "2025-04-15" if "2025年4月15日" in iti or "2025-04-15" in iti else None,
+                "离境日期": "2025-04-25" if "2025年4月25日" in iti or "2025-04-25" in iti else None,
+                "停留天数": first(r"停留天数[:：]\s*(\d+天)", iti),
+                "首个入境城市": "罗马" if re.search(r"4月15日罗马|抵达罗马", iti) else None,
+                "首晚酒店": "Hotel Artemide, Via Nazionale 22, Rome"
+                if "Hotel Artemide, Via Nazionale 22, Rome" in iti
+                else None,
+            }
+        )
+    return result
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--employment-pdf", required=True)
+    ap.add_argument("--itinerary-docx")
+    ap.add_argument("--out", required=True)
+    args = ap.parse_args()
+    payload = extract_pdfs_key_info(args.employment_pdf, args.itinerary_docx)
+    Path(args.out).write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/server/assets/skills/pdf/templates/form-fill-acroform/cases/italy-schengen-visa-example/field_values.case.json

@@ -0,0 +1,233 @@
+{
+  "_meta": {
+    "schema_version": 1,
+    "case": "synthetic-italy-schengen-visa-example",
+    "source_pdf": "user-provided-form.pdf",
+    "key_format": "page-prefixed identifiers; inspect each actual form",
+    "synthetic": true,
+    "comments": [
+      "所有人物、证件、雇主和联系信息均为合成示例，不可用于提交真实申请。",
+      "实际字段名及 checkbox 值必须通过 fill inspect 获取。"
+    ]
+  },
+  "writes": [
+    {
+      "key": "p1-surname",
+      "qname": "Surname",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "EXAMPLE",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "Chinese family name -> uppercase pinyin",
+      "validation": "required_if_name_present"
+    },
+    {
+      "key": "p1-first-name",
+      "qname": "First name",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "PERSON",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "Chinese given name -> uppercase pinyin",
+      "validation": "required_if_name_present"
+    },
+    {
+      "key": "p1-date-of-birth",
+      "qname": "date of birth",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "01-01-1990",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "YYYY/MM/DD -> DD-MM-YYYY",
+      "validation": "DD-MM-YYYY"
+    },
+    {
+      "key": "p1-place-of-birth",
+      "qname": "Place of birth",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "EXAMPLE CITY",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "place name -> uppercase pinyin/English",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p1-passport-number",
+      "qname": "Travel document number",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "TEST00000",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "preserve verbatim",
+      "validation": "passport_number"
+    },
+    {
+      "key": "p1-occupation",
+      "qname": "Occupation",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "SOFTWARE ENGINEER",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "standard English occupation, uppercase",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p1-employer",
+      "qname": "Employer",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "EXAMPLE COMPANY\n+00 0000 0000\nExample Street",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "conservative company-name translation + phone",
+      "validation": "latin_only_multiline"
+    },
+    {
+      "key": "p1-purpose-tourism",
+      "qname": "Tourism",
+      "page_no": 1,
+      "type": "checkbox",
+      "set_to": "/1",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "checkbox on_value from inspect",
+      "validation": "must_equal_inspect_on_value"
+    },
+    {
+      "key": "p2-destination",
+      "qname": "Destination",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "ITALY",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "country name uppercase English",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p2-first-entry",
+      "qname": "First entry",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "ITALY - ROME",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "country + first-entry city uppercase English",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p2-duration",
+      "qname": "Duration of stay",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "11",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "remove 天, digits only",
+      "validation": "integer_days"
+    },
+    {
+      "key": "p2-arrival",
+      "qname": "Intended date of arrival",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "15-04-2025",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "YYYY-MM-DD -> DD-MM-YYYY",
+      "validation": "DD-MM-YYYY"
+    },
+    {
+      "key": "p2-departure",
+      "qname": "Intended date of departure",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "25-04-2025",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "YYYY-MM-DD -> DD-MM-YYYY",
+      "validation": "DD-MM-YYYY"
+    },
+    {
+      "key": "p2-accommodation-name",
+      "qname": "Inviting person surname",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "EXAMPLE HOTEL",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "hotel name uppercase",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p2-accommodation-address",
+      "qname": "Address of inviting person",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "Example Street, Rome",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "hotel address uppercase, omit booking confirmation",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p2-cost-free-text",
+      "qname": "Cost",
+      "page_no": 2,
+      "type": "text",
+      "set_to": "APPLICANT HIMSELF/HERSELF",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "official-form wording",
+      "validation": "latin_only"
+    },
+    {
+      "key": "p2-cost-applicant-checkbox",
+      "qname": "Applicant",
+      "page_no": 2,
+      "type": "checkbox",
+      "set_to": "/1",
+      "source": "合成示例；实际填写必须使用用户提供的材料。",
+      "transform": "checkbox on_value from inspect",
+      "validation": "must_equal_inspect_on_value"
+    }
+  ],
+  "missing_required": [
+    {
+      "field_name": "Passport date of issue / valid until / issuing authority",
+      "page_no": 1,
+      "type": "text",
+      "reason": "Not present in employment certificate or itinerary."
+    },
+    {
+      "field_name": "Applicant home address, reliable phone, email",
+      "page_no": 1,
+      "type": "text",
+      "reason": "Home address absent; itinerary phone/email looked placeholder-like and should not be written without confirmation."
+    },
+    {
+      "field_name": "Current nationality / country of birth / nationality at birth",
+      "page_no": 1,
+      "type": "text",
+      "reason": "Not explicit in source materials; do not infer."
+    },
+    {
+      "field_name": "Sex / marital status / national ID number",
+      "page_no": 1,
+      "type": "checkbox/text",
+      "reason": "Not provided."
+    },
+    {
+      "field_name": "Schengen visa history and fingerprints",
+      "page_no": 2,
+      "type": "checkbox/text",
+      "reason": "Not provided."
+    },
+    {
+      "field_name": "Photo",
+      "page_no": 1,
+      "type": "visual_only",
+      "reason": "Visual photo frame, not an AcroForm text value; user must attach/upload a photo."
+    },
+    {
+      "field_name": "Place/date/signature",
+      "page_no": 3,
+      "type": "visual_or_text",
+      "reason": "Requires applicant confirmation and handwritten/e-signature."
+    }
+  ],
+  "validation_summary": {
+    "synthetic": true,
+    "note": "仅展示字段映射结构，不声明已生成或验收真实签证申请。"
+  }
+}

package/server/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json

@@ -0,0 +1,118 @@
+{
+  "_meta": {
+    "schema_version": "2",
+    "source_pdf": "<!-- artifacts/your_form.pdf -->",
+    "data_source_doc": "<!-- reports/field-mapping-final.md (sync date YYYY-MM-DD) -->",
+    "key_format": "qname is the fully qualified field name from `fill inspect`; page_no is its 1-based page",
+    "widget_total": "<!-- N from `fill inspect` -->",
+    "filled_at": "<!-- YYYY-MM-DDTHH:MM:SS -->",
+    "data_sources": [
+      {
+        "file": "<!-- 在职证明.pdf -->",
+        "fields_supplied": ["<!-- NAME_PINYIN -->", "<!-- PASSPORT_NUM -->", "<!-- DOB -->"]
+      },
+      {
+        "file": "<!-- 行程单.docx -->",
+        "fields_supplied": ["<!-- ENTRY_DATE -->", "<!-- EXIT_DATE -->", "<!-- FIRST_CITY -->"]
+      }
+    ],
+    "comments": [
+      "type='text': set_to is any string; apply writes /V (TextStringObject).",
+      "type='checkbox': set_to MUST equal the on_value (e.g. '/On' / '/Yes' / '/1') or off_value from `fill inspect`. Do NOT pass 'true' or 'checked'.",
+      "type='radio_group': set_to MUST equal one of radio_choices[].set_to from `fill inspect` (typically starts with '/').",
+      "type='choice': set_to MUST equal one of choice_options[].set_to from `fill inspect`.",
+      "Untouched fields are NOT listed — apply leaves them as-is.",
+      "qname comes from `fill inspect`; do not invent or shorten — apply rejects unknown qnames.",
+      "page_no is checked against inspect output; mismatches are rejected at apply time.",
+      "Before running `fill apply`, extract the apply-only payload:",
+      "  jq '.writes | map({qname, page_no, set_to})' field_values.json > values.json"
+    ]
+  },
+
+  "writes": [
+    {
+      "key": "p1-Surname",
+      "qname": "Surname",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "<!-- EXAMPLE -->",
+      "source": "<!-- employment_cert.pdf ('示例申请人') -> pinyin uppercase -->",
+      "transform": "uppercase_pinyin",
+      "maxlen": 20,
+      "validation": "required"
+    },
+    {
+      "key": "p1-Name",
+      "qname": "Name",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "<!-- WEI -->",
+      "source": "<!-- employment_cert.pdf ('示例申请人') -> pinyin uppercase -->",
+      "transform": "uppercase_pinyin",
+      "maxlen": 20,
+      "validation": "required"
+    },
+    {
+      "key": "p1-DOB",
+      "qname": "DOB",
+      "page_no": 1,
+      "type": "text",
+      "set_to": "<!-- 15-03-1990 -->",
+      "source": "<!-- passport.pdf ('1990-03-15') -> DD-MM-YYYY -->",
+      "transform": "date_DD-MM-YYYY",
+      "maxlen": 10,
+      "validation": "required"
+    },
+    {
+      "key": "p1-purpose-Tourism",
+      "qname": "purpose.Tourism",
+      "page_no": 1,
+      "type": "checkbox",
+      "set_to": "<!-- /1 (look up in inspect.on_value) -->",
+      "source": "<!-- itinerary.docx ('travel purpose: tourism') -->",
+      "validation": "required"
+    },
+    {
+      "key": "p2-purpose-Other",
+      "qname": "purpose.Other",
+      "page_no": 2,
+      "type": "checkbox",
+      "set_to": "/Off",
+      "source": "<!-- DISAMBIG: this is travel-purpose's 'Other'; marital-status's 'Other' has qname 'marital.Other' on page 1 -->",
+      "validation": "required"
+    }
+  ],
+
+  "missing_required": [
+    {
+      "field_name": "<!-- PHOTO -->",
+      "page_no": 1,
+      "type": "visual_only",
+      "coordinates": {"x": "<!-- 450.0 -->", "y": "<!-- 700.0 -->", "width": "<!-- 100 -->", "height": "<!-- 130 -->"},
+      "reason": "Visual frame for photo paste. acroform_apply cannot fill — user must paste photo manually after printing."
+    },
+    {
+      "field_name": "<!-- SIGNATURE -->",
+      "page_no": 3,
+      "type": "visual_only",
+      "coordinates": {"x": "<!-- 80.0 -->", "y": "<!-- 120.0 -->", "width": "<!-- 200 -->", "height": "<!-- 40 -->"},
+      "reason": "Signature line. User must sign manually after printing (not a digital signature field)."
+    },
+    {
+      "field_name": "<!-- ADDRESS_HOME -->",
+      "page_no": 1,
+      "type": "text",
+      "reason": "Source documents don't contain home address. User must provide."
+    }
+  ],
+
+  "validation_summary": {
+    "total_widgets": "<!-- N from `fill inspect` -->",
+    "filled": "<!-- count of writes[] -->",
+    "skipped_unchanged": "<!-- N - filled - missing -->",
+    "missing_required": "<!-- count of missing_required[] -->",
+    "warnings": [
+      "<!-- e.g. 'NAME field truncated from 22 to 19 chars due to maxlen=20' -->"
+    ]
+  }
+}