officecli-word-form

# OfficeCLI Word-Form Skill **This skill is INDEPENDENT, not a scene layer on docx.** A form's payload — `<w:sdt>` controls, `<w:ffData>` legacy fields, `<w:fldChar>` mail-merge, `documentProtection` — is a distinct element class from docx's paragraph/heading/style primitives. Its QA is different too: docx's Delivery Gate cares about visual layout and live PAGE fields, this skill's cares about data plumbing (protection enforced / alias+tag / items injected / name ≤ 20 / no underscore anti-pattern). **Reverse handoff:** if the user's document has no fillable fields (report, letter, memo, thesis, proposal), route to `officecli-docx` or a docx scene skill — don't use this one. ## 运行环境与交付链（本系统专用，先读这一段） **`officecli` 已经预装在运行环境的 PATH 中，不要联网安装、不要 curl。** `Bash` 工具直接调用即可，自检用 `officecli --version`。 所有命令在当前会话工作目录执行，输入输出使用相对路径或用户指定的真实路径。一次完整作业 = 3 步 + 1 步交付： ``` # Step 1（仅当用户上传过原始文件）把 artifact 送进沙盒 sandbox_put_artifact(artifact_id="<用户文件的 file_id>", dest_path="./in.docx") # Step 2 用 Bash 跑 officecli —— 本文件下面讲的全部命令都在这一步里 Bash("officecli create ./out.docx") # Step 3 把成稿从沙盒取出、登记成 artifact，拿到新的 file_id sandbox_get_artifact(src_path="./out.docx", name="终稿.docx") # Step 4（必做）交付给用户 pin_to_workspace(file_ids=["<新 file_id>"]) ``` **铁律**： - `sandbox_put_artifact` = 放**进**沙盒，`sandbox_get_artifact` = 从沙盒**取出**，别搞反；两个路径参数使用当前工作目录内的相对路径或真实绝对路径。 - 拿到 `file_id` 却不 `pin_to_workspace` 就等于没交付，用户看不到文件。多个产物一次性放进同一个列表，别分多次调用。 - 下文示例里的 `$FILE` 指实际文件；相对路径按当前会话工作目录解析。 - 下文的可视化质检（`view <file> screenshot` / `view <file> html`）依赖沙盒内的 Chromium，镜像已预装；截图失败就按下文 fallback 走 `view html`，并如实标注「未做视觉验证」，不要谎报 PASS。 - **导出 PDF 不要用 `officecli view <file> pdf`** —— 那个模式依赖本系统没有安装的 exporter 插件，必然失败。改用沙盒里的 LibreOffice： `soffice --headless --convert-to pdf --outdir . ./out.docx`。.xlsx / .pptx 换掉扩展名同理，但要沙盒里装了 LibreOffice Calc / Impress 才转得动；转换报错就如实告诉用户 PDF 没导出成功、主产物仍是原文件，不要谎报已导出。 ## Help-First Rule This skill teaches what a real form needs, not every CLI flag. When a prop / alias / enum is uncertain, consult help BEFORE guessing: `officecli help docx [element] [--json]` (e.g. `sdt`, `formfield`, `field`). Help is pinned to the installed CLI version and is authoritative — when this skill and help disagree, **help wins** (the prop set on `sdt` in particular has grown over time; trust `help docx sdt`, not a hardcoded list). ## Mental Model & Inheritance A Word form is a `.docx` plus four OpenXML payload layers plain-docx skills do not touch: **`<w:sdt>`** content controls (types: text / richtext / dropdown / combobox / date / picture / group), **`<w:ffData>`** legacy FormField (still the only way to get a real checkbox — SDT `type=checkbox` is not implemented), **`<w:fldChar>`** complex fields (MERGEFIELD, REF, PAGEREF, SEQ, IF — template-time, not user-fill), and **`documentProtection`** (the lock that makes non-field text read-only in Word — and, on the CLI, `protection=forms` locks non-field content edits (those need `--force` or `raw-set`) but still allows form-field (SDT) edits, which is the point of forms protection). **No inheritance from docx v2.** docx's Delivery Gate (cover-fill %, live-PAGE check) does NOT apply — form QA is `view forms` + `query sdt alias+tag` + `protectionEnforced`. **Reverse handoff to docx.** Route back to `officecli-docx` for reports / letters / memos / thesis / pitch decks / any document with no editable fields. Use **this** skill when the document's purpose is data capture or template merge. ## Shell & Execution Discipline **One command at a time. Read output before the next.** OfficeCLI is incremental — every `add` / `set` / `remove` immediately mutates the file. All recipes below use `FILE=form.docx` as a shell variable. **Three shell-escape layers:** 1. **Quote every path with `[N]`** — zsh/bash glob-expand brackets. `officecli get "$FILE" /body/sdt[1]` fails with `no matches found`. Correct: `officecli get "$FILE" '/body/sdt[1]'`. 2. **Single-quote any prop containing `$`** — `"Total: $50,000"` becomes `"Total: ,000"` after `$50` variable expansion. Correct: `'Total: $50,000'`. 3. **`--after find:<text>` uses outer single quotes, never inner double quotes** — `--after find:"Client Signature:"` makes the quotes part of the search string; match fails. Correct: `--after 'find:Client Signature:'`. **`WARNING: UNSUPPORTED` (exit 2) is a silently-wrong element.** The CLI created the element *without* the rejected prop. Any UNSUPPORTED in your build log means a prop name the current CLI does not accept on that element — stop, check `help docx <element>` for the right prop name (most SDT props such as `items`/`format`/`lock` ARE accepted now; `maxlength` is not), fix the command, and re-run. Do not ship on top. **`protection=forms` is the LAST structural command.** Once it is set, `protection=forms` locks non-field content (those edits need `--force` or `raw-set`) but still allows form-field (SDT) edits — which is the point of forms protection. A non-field content edit (e.g. `set /body/p[N] --prop text=`) is refused (`ERROR: Document is protected … use --force`); a form-field edit (e.g. `set /body/sdt[N] --prop text=` / `--prop alias=`) succeeds (exit 0). Use `Query("editable")` to find fillable fields. So finish all non-field (static layout) edits first, then lock; if you must edit static content afterward, pass `--force` (or temporarily clear protection, edit, re-lock). ### `--after find:` micro-playbook `--after find:<text>` matches the **first** occurrence. Bad anchor = wrong insertion location, expensive to debug. Three rules: 1. **Anchor must be globally unique.** In bilingual contracts "甲方签字" matches both parties — use a unique phrase like "甲方签字（Service Provider）" or full English title. 2. **After insert, `/body/p[last()]` is unreliable** — the find insertion changes `<w:body>` child order. To continue operating on the new paragraph, read its real paraId: `officecli query "$FILE" paragraph --json | jq -r '.data.results[-1].format.paraId'`. 3. **Chinese + full-width parens `（）`** match literally in `find`, but when unsure, `officecli view "$FILE" text | grep -n "锚点"` first to confirm the exact bytes in the file. ```bash # Trap: first-match hits 甲方 only, 乙方 missed officecli add "$FILE" /body --type sdt --after 'find:签字' # Fix: two signatories, two unique anchors officecli add "$FILE" /body --type sdt --prop alias=Party_A_Name --prop tag=party_a \ --after 'find:甲方签字（Service Provider）' PID_A=$(officecli query "$FILE" paragraph --json | jq -r '.data.results[-1].format.paraId') officecli add "$FILE" "/body/p[@paraId='$PID_A']" --type sdt --prop alias=Party_A_Title --prop tag=party_a_title ``` Inline SDT via `--after find:` is added as a child of the matched paragraph, not as a new paragraph — use this when label + SDT must share a line. ## What makes a real form (identity) A real fillable form requires **structured fields** + **document protection**. | Approach | Word user sees | CLI-readable | Real form? | |---|---|---|---| | SDT controls + `protection=forms` | Gray-bordered fields; rest locked | `query sdt` / `view forms` | **YES** | | FormField checkbox + `protection=forms` | Real clickable checkbox; rest locked | `query formfield` / `view forms` | **YES** (checkbox only) | | MERGEFIELD placeholders | `«CustomerName»` merged by downstream engine | `query field` | **YES** (template-time) | | Underscores `___` / blank lines | Visual-only; whole doc editable | No — no structured fields | **NO** | **Do not simulate fields with underscores.** `姓名：_______________` produces zero structured data and leaks past every verification. Always use `--type sdt` or `--type formfield`. **Checkbox is formfield, NOT SDT.** `--type sdt --prop type=checkbox` exits 1 (`SDT type 'checkbox' is not implemented`). Every checkbox in every recipe uses `--type formfield --prop type=checkbox`. **MERGEFIELD is a separate track.** `view forms` lists SDT + formfield only; `query field` lists complex fields only. Two disjoint inventories; both valid in one file. ## Requirements for Outputs (hard floor) Every form must satisfy these — Delivery Gate enforces each as an executable check. 1. `protection=forms` enforced (`get $FILE /` → `protectionEnforced=True`). 2. Every SDT has both `alias` + `tag`. 3. Every dropdown/combobox has non-empty `items=...` in `view forms`. 4. Every date SDT shows the intended `format=...`. 5. Every locked SDT shows `lock=sdtLocked` / `contentLocked` / `sdtContentLocked` as intended. 6. Zero `WARNING: UNSUPPORTED` in build log. 7. Zero `type=checkbox` on any SDT. 8. Every formfield `name` ≤ 20 characters. 9. Zero underscore-line / blank-line placeholders. 10. Field types match user intent (short text / paragraph / fixed list / list+custom / date / boolean). ## Three Paths (core decision) SDT props are **first-class on `add`** — confirm the current set with `officecli help docx sdt`. Today that includes `type, tag, alias, text, items, format, lock, placeholder/placeholderText, date.*` and the SDT types `text / richtext / dropdown / combobox / date / group / picture`. So most forms are pure `add` — no raw-set, no Word template. Two paths remain only for the genuinely-unreachable cases. **Pick the path before writing a single command.** ### Path A — Pure CLI (the default for almost everything) **Use when**: any text / richtext / dropdown / combobox / date / picture / group SDT — including its options, date format, and lock. Pass the props straight on `add`; verify each persists with `get '/body/sdt[N]' --json`. ```bash # dropdown WITH its options and a non-default date format, in one add each — no raw-set: officecli add "$FILE" /body --type sdt \ --prop type=dropdown --prop alias="Department" --prop tag=dept \ --prop items="Engineering,Finance,HR" officecli add "$FILE" /body --type sdt \ --prop type=date --prop alias="Start Date" --prop tag=start \ --prop format="yyyy年MM月dd日" # lock works on add AND set: officecli add "$FILE" /body --type sdt --prop type=text --prop tag=full_name \ --prop alias="Full Name" --prop text="Enter full name" --prop lock=sdtLocked # protection comes last, once all fields exist: # officecli set "$FILE" / --prop protection=forms ``` ### Path B — CLI + `raw-set` bridge (only an attribute help does NOT expose) **Use when**: you need an SDT attribute that `help docx sdt` does not list (e.g. a `<w:listItem>` whose `w:value` must differ from its display text, or a sdtPr child with no `--prop`). `raw-set` is OfficeCLI's universal OpenXML fallback — `officecli --help` lists it as a top-level command. For ordinary dropdowns use `--prop items=` (Path A); raw-set here is the exception, not the rule. ```bash # Display text ≠ stored value — not expressible via items=, so inject the listItems directly: officecli add "$FILE" /body --type sdt --prop type=dropdown --prop alias="Department" --prop tag=dept officecli raw-set "$FILE" /document \ --xpath "//w:sdt[w:sdtPr/w:tag/@w:val='dept']/w:sdtPr/w:dropDownList" \ --action append \ --xml '<w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Engineering" w:value="ENG"/><w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Finance" w:value="FIN"/>' ``` ### Path C — Word template (only what no API reaches) **Use when**: a **real SDT checkbox** (`type=checkbox` still exits 1 — use a legacy FormField instead, see §Legacy FormField), a `placeholderDocPart` prompt-text part, or custom richtext appearance / cross-part nesting beyond `--prop` reach. Picture and grouped SDTs are NO LONGER here — they add fine via Path A. ```bash # One-time in Word: Developer tab → Insert Content Control → Save as template.docx cp templates/onboarding_with_signature.docx "$FILE" officecli open "$FILE" officecli view "$FILE" forms # inspect embedded controls + paths officecli set "$FILE" '/body/sdt[@sdtId=3]' --prop text="Jane Smith" officecli set "$FILE" / --prop protection=forms ``` ### Decision table | Need | Path | Note | |---|---|---| | text / richtext SDT with default string | **A** | `--prop type/alias/tag/text` | | text SDT that must be locked | **A** | `--prop lock=sdtLocked` works on `add` (and `set`) | | dropdown / combobox **with options** | **A** | `--prop items="A,B,C"` | | date SDT with non-default format | **A** | `--prop format="yyyy年MM月dd日"` | | signature picture SDT, grouped SDT | **A** | `--prop type=picture` / `type=group` add directly | | dropdown whose stored value ≠ display text | **B** | raw-set append `<w:listItem w:value=…>` | | real checkbox | **FormField** | `--type formfield --prop type=checkbox` (see §Legacy FormField) | | mail-merge placeholder | **MERGEFIELD** | `--type field --prop fieldType=mergefield` (see §MERGEFIELD) | | real SDT checkbox / placeholder part / custom appearance | **C** | build skeleton in Word, fill via CLI | ## Quick Start — Path A + FormField (minimal intake form) Two SDT text fields, one checkbox, protection. Paste and adapt; this is the smallest form worth shipping. ```bash FILE=intake.docx officecli close "$FILE" 2>/dev/null; rm -f "$FILE" # preflight: clear stale resident / prior file (cold-start after CLI upgrade commonly leaks a resident) officecli create "$FILE" officecli open "$FILE" officecli set "$FILE" / --prop title="Employee Onboarding Intake" \ --prop docDefaults.font="Calibri" --prop docDefaults.fontSize="12pt" officecli add "$FILE" /body --type paragraph \