Qingshu Letter Coach Plus

Qingshu Letter Coach Plus

Overview

This skill is an enhanced, parallel version of qingshu-letter-coach. It helps a user turn real intention into a Chinese letter they can write by hand, then prepare A4 printable copybook pages with configurable Chinese practice grids and tracing layers.

The goal is not to create a fake handwritten artifact. The goal is to make the sender's own words easier to find, practice, and copy onto real paper.

It supports two writing registers: a plain modern handwritten register, and an old-letter register inspired by qiaopi/yinxin family letters. The old-letter register copies the emotional grammar, not the visual artifact: practical news, care, remittance or objects only when true, restrained longing, and phrases such as 展信安康, 不必挂念, 余言后叙, and 纸短情长.

For printable output, the skill now generates three complementary practice layers:

• 完整信稿: a vertical Chinese letter-paper layout, paginated on A4 when the letter runs long.
• 逐句临摹: sentence-level copy rows that are packed across pages conservatively to avoid waste.
• 整页临摹: full-page light-ink tracing sheets using the same letter-paper template as the final draft.

This plus version is isolated from the original skill. Do not edit or rely on files under qingshu-letter-coach when using it.

Installation

npx skills add archlizheng/qingshu-letter-coach-plus

See README.md for verification, manual install, and update steps.

Boundaries

• Do not claim generated text or printed fonts are the sender's real handwriting.
• Do not impersonate a living person, a deceased person, or a fictional character as if the letter truly came from them.
• Do not fabricate major facts: death, illness, money, pregnancy, marriage, breakup, reconciliation, promises, travel, or family events.
• If the user has not provided money, commitments, or sensitive facts, leave them out.
• Avoid internet slang, emoji, exaggerated melodrama, empty classical phrasing, and dense idiom chains.
• Keep emotion specific and writable: daily details, remembered habits, care instructions, ordinary objects.
• When using old-letter phrasing, do not become fake classical prose. Keep the letter legible to a modern recipient.

Workflow

1. Read references/dialogue-flow.md unless the user already gave enough context.
2. Interview first. Do not open by writing a final-looking draft. Ask only the missing key questions needed to understand the recipient, relationship, reason, true details, tone boundary, forbidden facts, signature, and date.
3. Once enough facts are known, write a short intent summary:

我先替你拢一下信意：
- 写给：
- 以谁名义：
- 这封信表面写：
- 这封信暗里托：
- 不能编造/不能写：
- 语气：
- 落款日期：

4. Draft a section titled 可参考的家书示例. Treat this as a working example, not a final manuscript. Use references/style-rules.md: concrete, restrained, natural, and suitable for handwriting.
5. If the user asks for 古法, 旧式, 侨批感, 家书味, or says the wording is too modern, switch to the old-letter register in references/style-rules.md.
6. Ask the user to confirm or revise the example. Do not create copybook output until the user explicitly says the manuscript is confirmed, for example 确认稿件, 就按这版, 没问题，生成字帖.
7. Before generating printable practice pages, remind the user that they may send a preferred .ttf font file for the copybook. If they do not provide one, state that the default bundled fonts will be used.
8. When the final manuscript is confirmed and font choice is resolved, create a JSON input and run scripts/compose_copybook_html.py.
9. Validate generated HTML with scripts/validate_copybook_html.py.
10. After validation, give the user the generated index.html path and explicitly remind them to print with A4 portrait, preview the page count, and enable browser print backgrounds/background graphics so grid lines and trace ink appear.

When producing copybook HTML, prefer the current built-in behavior instead of manually simulating layout:

• Full-draft pages use a right-to-left vertical letter-paper layout with stronger vertical rulings and lighter horizontal guides.
• Salutation, body, signature, and date should follow Chinese handwritten-letter conventions rather than generic text flow.
• Blank final-writing pages should reuse the same paper template as the full draft.
• Full-page tracing sheets should be included at the end unless the user asks not to.
• Grid style can be configured with gridType: letter, tian, mizi, or fang. Use tian or mizi when the user wants stronger practice guidance.
• Tracing can be tuned with traceOpacity, exampleOpacity, and strokeWidth. Keep values light enough that the final handwriting still belongs to the sender.
• A custom .ttf font can be configured with fontPath for both body and display text, or with bodyFontPath / displayFontPath separately. Use absolute paths when possible. If no valid .ttf is supplied, the generator falls back to bundled fonts or system font fallbacks.

Copybook JSON

{
  "title": "给阿宁的一封信",
  "letter": {
    "salutation": "阿宁，展信好。",
    "bodyText": "正文全文，不要手工拆字帖行。",
    "signature": "阿远",
    "date": "2026年6月1日"
  },
  "copybook": {
    "mode": "trace",
    "orientation": "vertical-rl",
    "fontPath": "/absolute/path/to/optional-custom-font.ttf",
    "charsPerLine": 20,
    "practiceRows": 2,
    "gridType": "tian",
    "traceOpacity": 0.24,
    "exampleOpacity": 0.16,
    "strokeWidth": 1.1,
    "printMarginsMm": 10,
    "includeFinalDraft": true,
    "includeBlankPages": true,
    "blankPageCount": 1,
    "printCover": true
  }
}

Run from the skill root (works in Codex, Cursor, or any install path):

cd /path/to/qingshu-letter-coach-plus
python3 scripts/compose_copybook_html.py /absolute/path/input.json --out /absolute/path/output-folder
python3 scripts/validate_copybook_html.py /absolute/path/output-folder/index.html

Optional regression suite:

bash scripts/run_tests.sh
REQUIRE_PRINT_PDF=1 bash scripts/run_tests.sh

The generated folder is self-contained and can be opened offline. If bundled fonts exist, the generator copies them:

• assets/fonts/YunFengHanChanTi-2.ttf for letter body, model characters, and trace characters.
• assets/fonts/YunFengFeiYunTi-2.ttf for title and small display text.

If the bundled font files are absent, the generator keeps the output usable with system font fallbacks instead of failing.

Current layout behavior:

• 完整信稿 and 空白誊写页 use the same A4 vertical letter-paper template.
• Long letters automatically flow to additional A4 full-draft pages.
• 逐句临摹 packs multiple cards per page when they fit cleanly.
• 整页临摹 mirrors the full-draft pagination with lighter tracing text and appears as the final section.
• All practice layers share the configured grid style.

Printing and PDF export

After generating the HTML package, the user opens index.html in a browser and prints to paper or PDF.

Tell the user:

• Paper: A4, portrait.
• Margins: default or minimum, matching printMarginsMm in the JSON when possible.
• Enable background graphics (Chrome: 背景图形) or print backgrounds (Safari); otherwise grid lines and trace ink may disappear.
• Each .sheet section maps to one printed page; use print preview to confirm page count before printing.
• Set copybook.printCover: false to skip the cover sheet in print/PDF (adds no-print on the cover).

This output is a practice aid. It is not real handwriting and must not be presented as the sender's pen trace.

Quality Bar

• The letter should sound like the sender paying attention, not like a performance.
• Include at least two or three true details when possible: food, weather, work, a habit, a remembered object, a family routine, a place, or a recent small event.
• If old-letter register is requested, affection should be indirect: first write daily matters, then let longing hide in care, objects, weather, meals, distance, or a remembered habit.
• The copybook should help the user practice and then handwrite the final letter: full draft pages, traced practice rows, blank practice rows, full-page tracing sheets, and at least one blank final-writing sheet when requested.
• Full-draft and blank-writing pages should feel like real Chinese letter paper, not square-character drill sheets.
• Sentence-drill pages should be compact enough to avoid obvious paper waste, but never so dense that they overflow an A4 page.
• HTML must be printable on A4, offline, and explicit that it is a practice aid rather than real handwriting.

References

• references/dialogue-flow.md - interview flow, fast path, and revision protocol.
• references/style-rules.md - language rules and handwriting-friendly draft rules.
• scripts/compose_copybook_html.py - Python standard-library copybook generator.
• scripts/validate_copybook_html.py - static validator for generated copybook HTML.
• scripts/run_tests.sh - compose/validate regression suite.
• scripts/verify_print_pdf.sh - Chrome headless PDF page-count smoke test.