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

package/server/assets/skills/pdf/docs/docx-contract-roundtrip-professional-case.md

@@ -0,0 +1,328 @@
+# Case: DOC/DOCX legal contract → professional PDF + MD/HTML + round-trip DOCX
+
+Use this case when a user asks to convert a Word contract/template into PDF, Markdown, HTML, and back to DOCX, and the PDF must be a professional legal/contract deliverable rather than a mechanical office export.
+
+## Original user intent and acceptance criteria
+
+**Representative prompt**
+
+> 完成以下 Word 文档双向转换（使用附件合同模板）：
+> 1. DOCX → PDF：保持高保真，中文字体正确显示
+> 2. DOCX → Markdown：列表和表格转为 MD 语法
+> 3. DOCX → HTML：保持样式，可嵌入网页
+> 4. Markdown → DOCX（逆向验证）：将步骤 2 的 MD 转回 DOCX，评估信息损失
+
+**Quality bar**
+
+- PDF Chinese text renders correctly with no mojibake/tofu.
+- PDF page layout is professional for a legal contract: A4, formal cover, readable clauses, controlled whitespace, signature table intact.
+- Headers/footers are inspected from the source and either preserved, intentionally reconstructed, or explicitly reported as absent.
+- Tables have borders, stable widths, and do not overflow the page.
+- Hyperlinks are preserved when the source has real hyperlink relationships.
+- PDF text is selectable/searchable, not screenshot-rendered.
+- MD→DOCX reverse output is generated through the local `docx_engine.py render` route or the active docx equivalent; do not use `python-docx` for generation.
+- Reverse DOCX audit passes and the report lists fidelity-loss items.
+- For PDF generation, render editable HTML through `scripts/make.sh render`; do not use `convert_file`/screenshots.
+- Numbered lists use explicit `<ol>/<li>` or literal numbering; do not rely on CSS counters.
+- No decorative emoji/icons or invented ornamental elements.
+
+## Case artifacts
+
+Editable artifacts live under:
+
+```text
+templates/reformat-default/cases/pku-contract-roundtrip/
+├── source.html       # professional A4 contract HTML; render this to reproduce the PDF
+├── source.md         # Markdown extraction/normalization exemplar
+└── docx_engine.py    # tiny compatibility wrapper for render/audit in environments lacking the historical tool
+```
+
+Do **not** store generated PDFs in the skill. Re-render from `source.html` when needed.
+
+## Route decision: direct DOCX→PDF vs HTML→PDF
+
+For ordinary DOCX→PDF conversion, **native DOCX render/export is the default**. Use docx `docx_to_pdf.py` or LibreOffice/soffice export and verify the result. Do not convert DOCX → Markdown/HTML → PDF just to obtain a PDF; that path discards Word pagination, headers/footers, fields, and table geometry.
+
+Use the professional HTML→PDF reconstruction in this case only when one of these is true:
+
+- the user explicitly asks for a redesigned/professional web-print PDF;
+- the direct DOCX→PDF render is visibly poor (scattered cover, broken signature table, bad CJK font fallback, overflow);
+- the task includes an editable web-embeddable HTML deliverable and the PDF should share that redesigned source.
+
+When taking the HTML route, record it as a **recomposition decision** in the report and still keep the direct render as a reference when possible.
+
+## End-to-end workflow
+
+### 0. Preflight
+
+```bash
+SKILL={{DATA_DIR}}/.builtin-skills/pdf
+DOCX_SKILL={{DATA_DIR}}/.builtin-skills/docx
+WORK=/tmp/contract-roundtrip
+mkdir -p "$WORK"
+
+bash "$SKILL/scripts/make.sh" check
+bash "$DOCX_SKILL/scripts/setup.sh"        # only if env_check is not ready
+export PATH="$HOME/.dotnet:$PATH"
+bash "$DOCX_SKILL/scripts/env_check.sh"
+```
+
+Recovery:
+
+- If `env_check.sh` says dotnet is missing immediately after setup, export `PATH="$HOME/.dotnet:$PATH"` and rerun.
+- Never suppress stderr for `soffice`, `pandoc`, render, or verification commands. Redirect to logs if needed.
+
+### 1. Normalize the source Word file
+
+Legacy `.doc` should first become `.docx`. Pandoc on `.doc` is unreliable.
+
+```bash
+cp "$INPUT_DOC_OR_DOCX" "$WORK/source_input"
+if [[ "$INPUT_DOC_OR_DOCX" == *.doc && "$INPUT_DOC_OR_DOCX" != *.docx ]]; then
+  soffice --headless --convert-to docx --outdir "$WORK" "$INPUT_DOC_OR_DOCX" \
+    2>"$WORK/soffice-docx.log"
+  INPUT_DOCX="$WORK/$(basename "${INPUT_DOC_OR_DOCX%.*}").docx"
+else
+  INPUT_DOCX="$INPUT_DOC_OR_DOCX"
+fi
+```
+
+### 1.5. Direct DOCX→PDF render baseline (default preservation route)
+
+Create a native DOCX-rendered PDF baseline before rebuilding anything. This is the correct route when the user wants faithful Word-to-PDF preservation because DOCX natively carries page geometry, sections, headers/footers, fields, numbering, and table layout.
+
+```bash
+python3 "$DOCX_SKILL/scripts/docx_to_pdf.py"   --input "$INPUT_DOCX"   --output "$WORK/direct-render.pdf" 2>"$WORK/docx-to-pdf.log"   || soffice --headless --convert-to pdf --outdir "$WORK" "$INPUT_DOCX"        2>"$WORK/soffice-pdf.log"
+
+pdfinfo "$WORK/direct-render.pdf" | grep "Page size"
+pdftotext "$WORK/direct-render.pdf" "$WORK/direct-render.txt"
+pdfimages -list "$WORK/direct-render.pdf" > "$WORK/direct-render-images.txt"
+```
+
+If this native baseline is visually professional and satisfies page/text/table/header-footer checks, deliver it as the DOCX→PDF output. Only continue to HTML reconstruction if the baseline fails the professional standard or the user asked for redesign.
+
+### 2. Inspect source structure before choosing the PDF route
+
+Use the source inspection to decide whether a mechanical export is good enough. For legal contracts with signature pages, it usually is not.
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+import zipfile, xml.etree.ElementTree as ET, sys
+p=Path(sys.argv[1])
+ns={'w':'http://schemas.openxmlformats.org/wordprocessingml/2006/main'}
+with zipfile.ZipFile(p) as z:
+    root=ET.fromstring(z.read('word/document.xml'))
+    paras=root.findall('.//w:p', ns)
+    tbls=root.findall('.//w:tbl', ns)
+    hyperlinks=root.findall('.//w:hyperlink', ns)
+    text=''.join(t.text or '' for t in root.findall('.//w:t', ns))
+    print({'paragraphs':len(paras),'tables':len(tbls),'hyperlinks':len(hyperlinks),'chars':len(text)})
+PY "$INPUT_DOCX"
+```
+
+Also inspect the generated Markdown and HTML quickly:
+
+```bash
+pandoc "$INPUT_DOCX" -t markdown+pipe_tables+grid_tables --wrap=none \
+  --extract-media="$WORK/media" -o "$WORK/source.md" 2>"$WORK/pandoc-md.log"
+pandoc "$INPUT_DOCX" -s -t html5 --metadata title="技术服务合同" \
+  -o "$WORK/source.raw.html" 2>"$WORK/pandoc-html.log"
+```
+
+Look for:
+
+- large signature tables with `rowspan`/`colspan`;
+- cover pages represented by many centered paragraphs;
+- empty underlined form fields;
+- comments/tracked changes/headers/footers;
+- real hyperlinks;
+- header/footer content and whether first page differs from later pages.
+
+If the contract PDF looks unprofessional after a raw export, **reconstruct the PDF from semantic HTML** using the strategy below.
+
+### 3. Transformation and terminology rules
+
+No translation is needed for same-language contract conversion, but terminology must stay stable:
+
+| Source term | Keep as | Notes |
+|---|---|---|
+| 委托方（甲方） | 委托方（甲方） | Do not paraphrase as “客户/甲方” only. |
+| 受托方（乙方） | 受托方（乙方） | Preserve party labels. |
+| 技术服务合同 | 技术服务合同 | Main title; no marketing wording. |
+| 签字盖章 | 签字盖章 | Signature/seal section heading. |
+| 北京大学科学研究部监制 | 北京大学科学研究部监制 | Institutional line on cover. |
+| 北京仲裁委员会 | 北京仲裁委员会 | Underline if source underlined. |
+
+When adapting to another contract:
+
+- Preserve legal clause numbers and party labels exactly.
+- Do not summarize clauses unless the user explicitly asks.
+- Empty fields should become form lines/blank blocks, not removed.
+- Do not add brand decorations, icons, or emoji.
+
+### 4. Asset and layout preservation strategy
+
+**PDF is the presentation deliverable.** For legal/contract docs, prioritize a formal contract layout over mechanical fidelity when the raw conversion is ugly.
+
+Use an editable HTML source with:
+
+- A4 `@page` rule and explicit `--format A4` at render time.
+- Running headers/footers for formal contracts, except where a cover page should remain clean. If the source has institutional header/footer text, preserve it; if absent, use a conservative title/template header and centered page footer, and state this reconstruction in the report.
+- CJK legal-document font cascade, e.g. `"Songti SC", "STSong", "Noto Serif CJK SC", "SimSun", serif`.
+- Formal cover: template note, title, expense/category line, form fields, supervising unit.
+- Clause pages: `h2` clause headings, justified paragraphs, 2em indentation, controlled line-height.
+- Fillable blanks: underlined inline spans or `blank-block` divs.
+- Tables: fixed widths, explicit `colgroup`, borders, controlled font size for signature table.
+- Signature page: rebuild wide merged-cell tables manually instead of trusting raw Pandoc table HTML.
+
+Use the case artifact as a starting point:
+
+```bash
+cp "$SKILL/templates/reformat-default/cases/pku-contract-roundtrip/source.html" "$WORK/contract.html"
+# Replace title, parties, clauses, and signature fields from the current source.
+```
+
+**HTML authoring prompt for future agents**
+
+```text
+Rewrite the extracted contract into semantic A4 HTML for a formal Chinese legal contract.
+Keep all legal text, party labels, clause numbers, underlined terms, and blank fields.
+Use Songti/STSong font stack, black/gray only, no icons/emoji.
+Represent numbered lists with explicit ol/li or literal numbering, not CSS counters.
+Represent signature/seal blocks with real HTML tables and borders; avoid overflow.
+Add running headers/footers on non-cover pages; preserve source header/footer text when present, otherwise use conservative document-title header and page footer.
+Do not store or edit the generated PDF; store the editable source HTML.
+```
+
+### 5. Render PDF through html_to_pdf route
+
+```bash
+bash "$SKILL/scripts/make.sh" render \
+  --in "$WORK/contract.html" \
+  --out "$OUTPUT_DIR/contract.pdf" \
+  --format A4 \
+  --wait 1000 2>"$WORK/render.log"
+```
+
+Expected evidence:
+
+```bash
+pdfinfo "$OUTPUT_DIR/contract.pdf" | tee "$OUTPUT_DIR/pdfinfo.txt"
+pdftotext "$OUTPUT_DIR/contract.pdf" "$OUTPUT_DIR/pdf_text.txt"
+pdfimages -list "$OUTPUT_DIR/contract.pdf" | tee "$OUTPUT_DIR/pdfimages.txt"
+```
+
+Pass conditions:
+
+- `pdfinfo` page size is A4 (`595.92 x 842.88 pts`, or close equivalent).
+- `pdftotext` extracts key Chinese terms (e.g. title, institution, clause headings, signature heading).
+- `pdfimages -list` does not show full-page screenshot images unless the source truly had images.
+- Visual spot-check of page 1 and signature page shows professional contract layout and no table overflow.
+- Header/footer text appears on non-cover pages when expected, and does not collide with body content or signature tables.
+
+For a visual spot-check:
+
+```bash
+pdftoppm -r 150 -png -f 1 -l 1 "$OUTPUT_DIR/contract.pdf" "$WORK/page1"
+# Find signature page from pdftotext or page count, then rasterize it too.
+```
+
+### 6. Produce Markdown and HTML deliverables
+
+Markdown should be honest about what it can and cannot represent.
+
+```bash
+pandoc "$INPUT_DOCX" -t markdown+pipe_tables+grid_tables --wrap=none \
+  --extract-media="$OUTPUT_DIR/media" \
+  -o "$OUTPUT_DIR/contract.md" 2>"$WORK/pandoc-md.log"
+```
+
+Normalize headings if the source only uses bold paragraphs for article headings. For example:
+
+```text
+**一、技术服务内容、方式和要求：** → ## 一、技术服务内容、方式和要求
+**十一、签字盖章：** → ## 十一、签字盖章
+```
+
+HTML deliverable should be the same professional editable HTML used for PDF:
+
+```bash
+cp "$WORK/contract.html" "$OUTPUT_DIR/contract.html"
+```
+
+### 7. Reverse Markdown → DOCX verification
+
+If the active docx environment provides a native `docx_engine.py`, use it. If not, use the compatibility wrapper stored in this case as a local `render/audit` driver. The wrapper delegates generation to Pandoc and audits the OOXML package; it does **not** use `python-docx` to generate.
+
+```bash
+cp "$SKILL/templates/reformat-default/cases/pku-contract-roundtrip/docx_engine.py" "$WORK/docx_engine.py"
+python3 "$WORK/docx_engine.py" render \
+  --input "$OUTPUT_DIR/contract.md" \
+  --output "$OUTPUT_DIR/contract_roundtrip.docx"
+
+python3 "$WORK/docx_engine.py" audit \
+  --input "$OUTPUT_DIR/contract_roundtrip.docx" | tee "$OUTPUT_DIR/roundtrip_audit.txt"
+```
+
+Also run docx validation when available:
+
+```bash
+export PATH="$HOME/.dotnet:$PATH"
+dotnet run --project "$DOCX_SKILL/scripts/dotnet/MiniMaxAIDocx.Cli" -- \
+  validate --input "$OUTPUT_DIR/contract_roundtrip.docx" --business \
+  | tee "$OUTPUT_DIR/roundtrip_validate.txt"
+
+dotnet run --project "$DOCX_SKILL/scripts/dotnet/MiniMaxAIDocx.Cli" -- \
+  analyze --input "$OUTPUT_DIR/contract_roundtrip.docx" --json \
+  > "$OUTPUT_DIR/roundtrip_analyze.json"
+```
+
+Pass conditions:
+
+- Audit says `AUDIT PASS` or native equivalent.
+- Business validation passes; warnings about orphaned comments/relationships may be noted if they do not affect the main document.
+- Analysis shows Heading styles for normalized headings and expected table count.
+
+### 8. Fidelity-loss report
+
+Always include a loss report. Suggested table:
+
+| Category | Expected loss / change | Severity |
+|---|---|---|
+| Legacy `.doc` normalization | LibreOffice may reinterpret page breaks, spacing, and old binary Word features. | Medium |
+| Direct Word formatting | Markdown cannot preserve exact font size, line spacing, underline offsets, and manual centering. | Medium |
+| Complex merged tables | Markdown grid tables cannot fully express rowspan/colspan semantics; round-trip DOCX may simplify the table graph. | High |
+| Pagination | Markdown does not preserve exact page breaks; PDF is reflowed to A4 HTML. | Medium |
+| Headers/footers | Markdown usually loses them; PDF HTML must preserve/reconstruct them; reverse DOCX may not recover them unless explicitly generated. | Medium/High for legal |
+| Legal content | Clause text, party labels, and key terms should be preserved exactly. | Critical gate |
+| Images/OLE | Must inventory; absent in the PKU contract exemplar. | Depends |
+| Hyperlinks | Preserve only real hyperlink relationships; report if source has none. | Low/Medium |
+
+## Common pitfalls and recovery
+
+| Pitfall | Symptom | Recovery |
+|---|---|---|
+| Shipping a raw Pandoc/LibreOffice PDF | Cover text is scattered, tables look amateur, signature page overflows. | Rebuild semantic contract HTML from clauses and signature fields; render through `make.sh render`. |
+| Using screenshots for PDF | `pdfimages` shows page-sized images; text not searchable. | Use Playwright HTML→PDF only; verify with `pdftotext`. |
+| Relying on strings only | Text exists but visual layout is unacceptable. | Rasterize page 1 and signature page with `pdftoppm`; inspect layout. |
+| CSS counters for legal numbering | Copy/paste/search loses numbering; nested list levels break. | Use literal numbering or real `<ol><li>` elements. |
+| Wide signature table overflow | Right columns clip or shrink unreadably. | Use fixed `colgroup`, smaller font, controlled line-height, and split overly wide structures if needed. |
+| Missing or colliding headers/footers | Formal contract pages have no running identity/page footer, or footer overlaps signature table. | Reserve header/footer space in `.page`, keep cover clean, add `.running-header`/`.running-footer`, then raster-check body and signature pages. |
+| CJK font mismatch | Chinese glyphs look like Japanese forms or tofu. | Use Songti/PingFang/Noto CJK font stack; verify visually and with `pdftotext`. |
+| Missing dotnet after setup | `env_check.sh` fails even after installing .NET. | `export PATH="$HOME/.dotnet:$PATH"`; rerun env check. |
+| Claiming hyperlink preservation when none exist | User expects clickable links, but source had only underlined text. | Inspect OOXML hyperlink relationships; report “source has no real hyperlinks.” |
+
+## Final reusable workflow checklist
+
+1. Normalize `.doc` → `.docx` with `soffice`.
+2. Inventory paragraphs, tables, hyperlinks, and risky legal-layout features.
+3. Generate Markdown with Pandoc grid/pipe tables; normalize headings.
+4. Generate a native DOCX→PDF baseline and prefer it when it is faithful/professional.
+5. Only if needed, generate professional editable HTML, using the case `source.html` as a legal-contract template.
+6. Add/preserve headers and footers on non-cover pages, reserving print-space so they do not collide with body content.
+7. Render redesigned PDF via `bash pdf/scripts/make.sh render --format A4` only when using the HTML route.
+8. Verify `pdfinfo`, `pdftotext`, `pdfimages`, and visual previews of cover/body/signature pages, including headers/footers.
+9. Reverse Markdown → DOCX through `docx_engine.py render`; audit and validate.
+10. Deliver PDF, MD, HTML, round-trip DOCX, and a fidelity-loss report that states whether PDF came from direct render or HTML recomposition.
+11. If the user says the PDF is not professional, do not defend raw conversion. Reconstruct the contract layout semantically and re-render.

package/server/assets/skills/pdf/docs/email-translation-goldman-two-sessions-case.md

@@ -0,0 +1,346 @@
+# Case: EML research report → Chinese layout-preserving PDF
+
+Use this reference after `docs/pitfalls-index.md` §P5 matches a prompt like
+"Translate this email report into Chinese and save as PDF; keep content and
+charts/icons unchanged." It records a Goldman Sachs macro research email run as
+a reusable production case. The prompt below is optimized from the successful
+run: it separates glossary, hard preservation rules, output schema, and QA flags
+so the agent can reuse it without ad-hoc prompt writing.
+
+## What already existed
+
+Before this case, pdf already had:
+
+- `docs/pitfalls-index.md` §P5 — canonical EML/PDF translation-preserve-layout trace.
+- `templates/translate-preserve-layout/skeleton.html` — generic translated report skeleton.
+- `templates/translate-preserve-layout/README.md` — m09 email translation pitfalls.
+
+This case adds a concrete EML trace: MIME asset extraction, cid replacement,
+Doctype-safe segment extraction, an optimized reusable LLM prompt, in-place HTML
+mutation, A4 render, image/link verification, and a filled HTML exemplar.
+Regenerate PDFs from the HTML when evaluating; do not store the rendered PDF in
+the case.
+
+## Files in this case
+
+- `templates/translate-preserve-layout/cases/goldman-china-two-sessions-cn.html`
+  — filled Chinese HTML from the successful run. It preserves the source email's
+  table layout, Goldman Sachs logo, exhibit images, and hyperlinks.
+
+## Trigger and boundary
+
+Use this case when:
+
+- Input is `.eml` with a formal research/newsletter report in `text/html`.
+- User asks to translate the report, preserve layout/images/icons, and output PDF.
+- Inline assets are referenced via `cid:` and charts are already raster/SVG images.
+- Target language is Chinese or another CJK language where line-height/font
+  cascade must be controlled.
+
+Do not use this case when:
+
+- The email only contains a PDF/DOCX attachment to translate (route to the PDF or
+  DOCX read/translate path first).
+- The user asks for a summary instead of a faithful translated deliverable.
+- The source is scanned/image-only content with no text layer; use vision/OCR per
+  page before translation.
+
+## Successful trace: Goldman Sachs "Two Sessions" email
+
+User request:
+
+```text
+将这个email里的报告翻译成中文并保存为pdf，内容和图标都要保持不变。
+```
+
+Source signals:
+
+- Subject: `China: Local "Two Sessions" point to a lower national growth target this year than last year`.
+- MIME parts: one `text/html` part (~106 KB), five inline PNG parts, plus one
+  hidden remote tracking pixel.
+- Visible report assets after rendering: Goldman Sachs logo + 4 exhibit charts.
+  `pdfimages` lists 6 image rows because the transparent logo also creates an
+  `smask` row.
+- Source HTML rendered cleanly to A4 via Chromium: 7 pages, A4, image rows present.
+- Final Chinese output: 6 pages, A4, ~907 KB, 25 URI link annotations.
+
+## Step-by-step workflow
+
+### 1. Preflight and source parsing
+
+```bash
+bash <SKILL>/scripts/make.sh check 2><TMP>/check.log
+```
+
+Parse the EML with Python's `email` package and preserve every inline image as a
+local file. Replace `cid:<content-id>` references with the exact local filename;
+do not re-encode or run Pillow on the images.
+
+```python
+from email import policy
+from email.parser import BytesParser
+from pathlib import Path
+import json
+
+src = Path("<INPUT.eml>")
+out = Path("<TMP>/email")
+out.mkdir(parents=True, exist_ok=True)
+msg = BytesParser(policy=policy.default).parsebytes(src.read_bytes())
+html = None
+assets = []
+for part in msg.walk():
+    if part.is_multipart():
+        continue
+    payload = part.get_payload(decode=True) or b""
+    ctype = part.get_content_type()
+    if ctype == "text/html":
+        html = payload.decode(part.get_content_charset() or "utf-8", errors="replace")
+    elif ctype.startswith("image/"):
+        cid = (part.get("content-id") or "").strip("<>")
+        fn = part.get_filename() or f"{cid}.{ctype.split('/')[-1]}"
+        (out / fn).write_bytes(payload)
+        assets.append({"cid": cid, "filename": fn, "ctype": ctype, "bytes": len(payload)})
+if html is None:
+    raise SystemExit("no text/html part found")
+for a in assets:
+    html = html.replace(f"cid:{a['cid']}", a["filename"]).replace(f"cid%3A{a['cid']}", a["filename"])
+(out / "source.html").write_text(html, encoding="utf-8")
+(out / "assets.json").write_text(json.dumps(assets, ensure_ascii=False, indent=2), encoding="utf-8")
+```
+
+Baseline-render source HTML to establish page/image behavior:
+
+```bash
+bash <SKILL>/scripts/make.sh render \
+  --in <TMP>/email/source.html \
+  --out <TMP>/email/source_render.pdf \
+  --format A4 --wait 15000 \
+  2><TMP>/render-source.log
+pdfinfo <TMP>/email/source_render.pdf | grep -E "Pages|Page size"
+pdfimages -list <TMP>/email/source_render.pdf | wc -l
+```
+
+### 2. Extract stable translation units
+
+Extract visible text nodes from the HTML. Skip `script/style/noscript/head`,
+conditional comments, build artifacts, bare bullets and punctuation, and hidden
+tracking boilerplate. Keep anchor tags in place; translate only their text node
+content so the `href` target survives unchanged.
+
+Important: BeautifulSoup can expose the doctype as a text-like node. Exclude
+`bs4.element.Doctype`, otherwise the LLM output IDs shift by one and every
+translation is applied to the wrong source node.
+
+```python
+from bs4 import BeautifulSoup, Doctype
+from pathlib import Path
+import json
+
+soup = BeautifulSoup(Path("<TMP>/email/source.html").read_text(encoding="utf-8"), "html.parser")
+skip_exact = {"|", "●", ":", ").", ",", "content", "Company Takeover Disclosure", "END OF DOCUMENT"}
+segments = []
+for s in soup.find_all(string=True):
+    if isinstance(s, Doctype):
+        continue
+    if not s.parent or s.parent.name in ("script", "style", "noscript", "head"):
+        continue
+    txt = " ".join(str(s).split())
+    if not txt or txt in skip_exact:
+        continue
+    if txt.startswith("[if") or "jcr_root" in txt or txt.startswith("// END") or txt.startswith("TODO:"):
+        continue
+    segments.append({"id": len(segments), "text": txt})
+Path("<TMP>/email/translate_units.json").write_text(
+    json.dumps(segments, ensure_ascii=False, indent=2), encoding="utf-8"
+)
+```
+
+### 3. Optimized reusable translation prompt
+
+Call an LLM for translation; do not hand-translate long financial/policy reports.
+Use this optimized prompt instead of the rough one-off prompt from the original
+run. It is designed to prevent terminology drift, ID mismatch, accidental link
+translation, and prose-only preservation failures.
+
+#### System prompt
+
+```text
+你是金融/宏观政策研究报告的专业英译中译者，任务是把 HTML/EML 中抽取出的可见文本节点翻译成简体中文，并让译文可直接放回原 HTML。
+
+硬性规则：
+1. 只输出合法 JSON，不要 Markdown、代码块、解释、前后缀文本。
+2. 输入是 JSON 数组，每项有 id 和 text；输出必须是同长度 JSON 数组，每项只包含 {"id": 原id, "zh": "译文"}，顺序与输入一致，不得合并、拆分、遗漏或新增项目。
+3. 只翻译自然语言；保留所有数字、年份、日期、时间、货币符号、百分比、区间、括号中的缩写、邮箱、电话、URL、股票/基金代码、HTML实体和占位符。
+4. 人名保留英文；无官方中文译名的机构名保留英文。Goldman Sachs、Wind 保留英文。
+5. 链接锚文本可翻译，但不得改写或臆造 URL；如果 text 本身是邮箱/URL/电话，只原样返回。
+6. 不要解释图表，不要补充原文没有的信息，不要重组章节，不要把短锚文本扩写成长句。
+7. 中文使用专业卖方研究语气：准确、克制、书面；避免口语化和宣传腔。
+8. 标点用中文正文标点，但保留数值表达中的半角符号（如 4.5-5.0%、RMB4.6tn、1pp）。
+
+固定术语表（必须一致）：
+- Two Sessions = 两会
+- local Two Sessions = 地方两会
+- national Two Sessions = 全国两会
+- GDP growth target = GDP增长目标
+- real GDP growth = 实际GDP增长
+- CPI inflation target = CPI通胀目标
+- Central Economic Work Conference (CEWC) = 中央经济工作会议（CEWC）
+- Government Work Report = 政府工作报告
+- local government special bond (LGSB) = 地方政府专项债（LGSB）
+- central government special bond (CGSB) = 中央政府特别债（CGSB）
+- Augmented Fiscal Deficit (AFD) = 广义财政赤字（AFD）
+- 15th Five-Year Plan (FYP) = “十五五”规划
+- 4th Plenum = 四中全会
+- Pledged Supplementary Lending (PSL) = 抵押补充贷款（PSL）
+- fiscal deficit = 财政赤字
+- effective on-budget fiscal deficit = 有效预算内财政赤字
+- surveyed unemployment rate = 调查失业率
+- new urban jobs = 城镇新增就业
+
+质量自检后再输出：
+- id 是否逐一对应；
+- 术语是否完全一致；
+- 数字/百分比/货币/缩写是否未被改动；
+- 是否没有 Markdown 代码围栏。
+```
+
+#### User prompt template
+
+```text
+将下面 JSON 数组逐项翻译为简体中文。严格遵守 system prompt 的 JSON 输出格式。
+
+领域提示：这是一封卖方宏观经济研究邮件，主题为中国地方/全国“两会”、GDP增长目标、财政预算、通胀、就业和“十五五”规划。译文将被放回原 HTML 并渲染成 PDF，所以每个 id 的文本必须保持独立，不要跨 id 合并句子。
+
+输入 JSON：
+<PASTE translate_units.json HERE>
+```
+
+#### Post-LLM validation
+
+```python
+import json
+from pathlib import Path
+src = json.loads(Path("<TMP>/email/translate_units.json").read_text(encoding="utf-8"))
+out = json.loads(Path("<TMP>/email/translations.json").read_text(encoding="utf-8"))
+assert len(src) == len(out)
+assert [x["id"] for x in src] == [x["id"] for x in out]
+for s, t in zip(src, out):
+    for token in ("%", "RMB", "GDP", "AFD", "LGSB", "CGSB", "PSL"):
+        if token in s["text"]:
+            assert token in t["zh"], (token, s, t)
+```
+
+If the model returns fenced JSON, strip only the fence and re-parse. If IDs or
+counts do not match, rerun translation with the validation error; do not guess a
+mapping manually.
+
+### 4. Mutate original HTML in place
+
+Apply translations back to the original text nodes by ID. Preserve leading and
+trailing whitespace so inline links remain readable. Then append a CJK-safe print
+style block rather than rebuilding the whole report.
+
+Append this style for the Goldman-style email layout:
+
+```css
+@page { size: A4 portrait; margin: 12mm 10mm; }
+* { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+body, table, td, p, span, font, a, b {
+  font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB",
+               "Microsoft YaHei", "Helvetica Neue", Arial, sans-serif !important;
+}
+p, td.copybody, .copybody, font { line-height: 1.6 !important; }
+img { max-width: 100% !important; height: auto !important; }
+img[src^="https://publishing.gs.com/CI0"] { display: none !important; width: 1px !important; height: 1px !important; }
+figure, img { page-break-inside: avoid; }
+a { color: #446EA6; }
+@media screen {
+  html { background:#d0d0d0; }
+  body { margin:0; padding:20px 0; }
+  #templateContainer { background:#fff; box-shadow:0 4px 24px rgba(0,0,0,.18); }
+}
+```
+
+Do **not** set `page-break-inside: avoid` on every `table` or `tr` in table-heavy
+email HTML. That caused unnecessary blank pages in this run. Protect images and
+figures instead.
+
+### 5. Render
+
+```bash
+bash <SKILL>/scripts/make.sh render \
+  --in <TMP>/email/translated.html \
+  --out <OUTPUT_PATH> \
+  --format A4 --wait 15000 \
+  2><TMP>/render-translated.log
+```
+
+The final case HTML is stored at:
+
+```text
+<SKILL>/templates/translate-preserve-layout/cases/goldman-china-two-sessions-cn.html
+```
+
+### 6. Verification gates
+
+```bash
+pdfinfo <OUTPUT_PATH> | grep -E "Pages|Page size"
+pdfimages -list <OUTPUT_PATH>
+pdftotext -layout <OUTPUT_PATH> - | python3 -c "import sys; print(sys.stdin.read()[:2500])"
+python3 - <<'PY'
+from pypdf import PdfReader
+r = PdfReader("<OUTPUT_PATH>")
+links = 0
+for page in r.pages:
+    for a in page.get('/Annots') or []:
+        obj = a.get_object(); aa = obj.get('/A')
+        if aa and aa.get('/URI'):
+            links += 1
+print('links', links)
+PY
+```
+
+Expected Goldman evidence:
+
+```text
+Pages:           6
+Page size:       595.92 x 842.88 pts (A4)
+PDF size:        ~907 KB
+pdfimages rows:  8 total output lines; visible semantic images = logo + 4 exhibits
+links:           25 URI annotations
+Text extract:    readable Chinese; includes 两会, GDP增长目标, 地方政府专项债, 广义财政赤字, 抵押补充贷款
+```
+
+Image count notes:
+
+- `pdfimages -list | wc -l` includes the two header lines.
+- Transparent PNG logos may create both `image` and `smask` rows.
+- Hidden 1×1 tracking pixels should not be counted as semantic report assets;
+  hiding them is acceptable if the visible report is unchanged.
+
+### 7. Final polish checks
+
+- Terminology: `Two Sessions → 两会`, `GDP growth target → GDP增长目标`,
+  `AFD → 广义财政赤字（AFD）`, `PSL → 抵押补充贷款（PSL）`.
+- Dates and punctuation: convert obvious English dates in Chinese prose where
+  useful (`3 February` → `2月3日`, `4 March` → `3月4日`).
+- No tofu boxes or mojibake in `pdftotext` output.
+- No huge blank pages introduced by over-broad `break-inside: avoid` rules.
+
+## Reuse pattern for another EML report
+
+1. Parse MIME, save inline assets, replace `cid:` with local filenames.
+2. Baseline-render source HTML to measure pages/images.
+3. Extract visible text nodes with stable IDs; exclude `Doctype` and artifacts.
+4. Translate via LLM with the optimized prompt and frozen domain glossary.
+5. Validate JSON length/IDs and preservation tokens before HTML mutation.
+6. Mutate original HTML in place; preserve links and images; append CJK print CSS.
+7. Render with `--format A4 --wait 15000`.
+8. Verify A4, image presence, text readability, terminology, and URI annotations.
+
+## Final response shape
+
+```text
+完成，已翻译并生成 PDF：<OUTPUT_PATH>
+验证：A4；<N>页；图表/图片已保留；链接注释 <N> 个；中文文本可提取且关键术语已检查。
+```