汉字镜 · Hanzi Lens

Turn one Han character into a source-backed visual explanation. The character is the subject: do not infer a person's character, fate, relationships, or identity unless the user explicitly changes the scope.

character
→ Unicode + font coverage
→ source hierarchy
→ fact / commentary / interpretation boundary
→ semantic model
→ professional Exhibit
→ domain + visual release gates

Required references

Read these completely before authoring:

1. references/research-standard.md
2. references/visual-grammar.md
3. references/output-contract.md

Read references/user-config.md when brand or output configuration is unresolved.

The dependency lov-professional-infographic is mandatory. Read its SKILL.md and required references before creating or reviewing the Exhibit.

Non-negotiable outcome

For the standard visual route, deliver:

• a verified reading with region or standard attached;
• Unicode identity and a passing glyph-coverage report;
• form analysis that distinguishes semantic, phonetic, and uncertain parts;
• historical lexicography with exact source labels;
• at least two classical examples in context;
• one governing semantic relationship, not a dictionary card wall;
• an explicit boundary between fact, commentary, interpretation, and visual metaphor;
• editable exhibit/poster.html and high-resolution exhibit/poster.png;
• source.md, research.json, brief.md, font-report.json, exhibit/audit.json, and hanzi-audit.json;
• full-size and thumbnail human review.

Never invent oracle-bone or bronze forms, turn a modern component mnemonic into historical etymology, flatten regional readings into one standard, or use unsupported rarity and auspiciousness scores.

Workflow

0. Resolve context and ask once

Use conversation context to prefill the character, focus, locale, aspect, and brand. Before running the first generation command, use AskUserQuestion once for the smallest unresolved choice. Recommended defaults:

• scope: character only;
• locale: compare mainland and Taiwan standards when they differ;
• output: explanation + professional infographic;
• aspect: 16:9 master;
• brand: shared user profile.

Do not re-ask options the user already fixed. If the runtime does not expose AskUserQuestion, ask one concise plain-text question.

1. Create the research project

python3 "$SKILL_DIR/scripts/hanzi_lens.py" inspect "翕"

python3 "$SKILL_DIR/scripts/hanzi_lens.py" scaffold "翕" \
  --request "解释「翕」这个汉字" \
  --locale both \
  --output-dir "<project>"

The scaffold is intentionally incomplete and non-destructive. Never write into a non-empty output directory.

2. Prove that the glyph can render

Run before visual authoring:

python3 "$SKILL_DIR/scripts/hanzi_lens.py" font-check "翕" \
  --portable \
  --output "<project>/font-report.json"

For Extension B and later ideographs, IVS sequences, or a zero-match result, select and test an explicit font file. Do not substitute an image of a different glyph.

3. Research by source level

Browse and verify the character. Follow references/research-standard.md. Record exact evidence in source.md and structured evidence in research.json.

Required distinctions:

Layer	Meaning
Standard / dictionary fact	Current code point, reading, radical, strokes, recorded sense
Historical lexicography	What a named historical dictionary says
Commentary	What a named commentator infers from that dictionary
Interpretation	A modern synthesis supported by the above
Visual metaphor	Geometry used to help comprehension, never presented as paleography

If sources disagree, show the disagreement. Do not silently choose the most poetic version.

4. Build the semantic model

Complete research.json and brief.md before visual code.

Choose one governing relationship:

• tension or motion, such as inward ↔ outward;
• root meaning → semantic branches;
• form component → function → recorded use;
• two or more characters × consistent criteria;
• documented chronological form evolution.

Every visible branch, arrow, coordinate, or contrast must map to a source ID.

Run the domain preflight:

python3 "$SKILL_DIR/scripts/hanzi_lens.py" audit \
  --project "<project>"

Warnings about a missing Exhibit are expected at this stage; research errors must be fixed before continuing.

5. Write the action title and scaffold the Exhibit

The title must state a supported finding about the character. Avoid topic labels such as “认识某字”.

python3 "$SKILL_DIR/scripts/hanzi_lens.py" exhibit \
  --project "<project>" \
  --title "<source-supported action title>" \
  --template driver-tree \
  --aspect 16:9

Template guidance is in references/visual-grammar.md. The generated template is only a semantic skeleton. Replace every placeholder while preserving the dependency's auditable data-* contracts.

6. Author for the character, not around it

• Make the target glyph a dominant plotted mark, not a decorative watermark.
• Use form, motion, contrast, or semantic branching as the main visual proof.
• Use code-rendered HTML/CSS/SVG for all text, glyphs, labels, quotes, and sources.
• Generated imagery is rarely needed. It must never fabricate ancient forms, calligraphy attribution, or pseudo-script.
• Put regional reading differences and scholarly disputes next to the relevant mark.
• Keep the brand subordinate.

7. Render and inspect

python3 "$SKILL_DIR/scripts/hanzi_lens.py" render \
  --project "<project>" \
  --scale 2

Open exhibit/poster.png at original size and at approximately 320 px wide. Review:

1. Can the reader repeat the governing insight after five seconds?
2. Does the glyph remain the subject?
3. Does the visual prove the title without reading every quote?
4. Can every claim be traced to a source ID?
5. Are fact, commentary, interpretation, and metaphor distinguishable?
6. Are rare glyphs, regional readings, and caveats legible?
7. Is there any generic card wall, fake ancient form, or empty container?

Revise deliberately. A machine pass is not the final judgment.

8. Run the strict release gate

python3 "$SKILL_DIR/scripts/hanzi_lens.py" audit \
  --project "<project>" \
  --human-review passed \
  --review-note "<full-size and thumbnail evidence>" \
  --strict

Release only when both the Hanzi domain audit and the delegated professional infographic audit pass with zero errors and zero warnings.

CLI reference

python3 "$SKILL_DIR/scripts/hanzi_lens.py" --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" inspect --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" scaffold --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" font-check --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" exhibit --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" render --help
python3 "$SKILL_DIR/scripts/hanzi_lens.py" audit --help

User configuration

Resolution order:

1. explicit CLI flags;
2. SKILL_HANZI_LENS_* environment variables;
3. shared SKILL_SKILLS_* environment variables;
4. ${SKILL_PROFILE_PATH:-$HOME/.skill-publisher/skills/profile.json};
5. safe defaults under $HOME/Documents.

Relevant variables:

Variable	Meaning
SKILL_HANZI_LENS_OUTPUT_DIR	Hanzi Lens output root
SKILL_HANZI_LENS_INFOGRAPHIC_SKILL_DIR	Dependency skill directory
SKILL_OUTPUT_DIR	Shared output root
SKILL_SKILLS_INSTALL_DIR	Shared skill installation directory
SKILL_PROFILE_PATH	Shared profile JSON
SKILL_PROFILE_PATH	Shared brand profile

Never hard-code a private workspace or brand path into a reusable project.

Runtime context (shared)

运行前读取本 Skill 包的 skill.yaml，由宿主提供 skill-runtime/v1 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。

• 只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。
• required: true 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。
• 报错提供可复制的 context_id、字段路径与来源，诊断内容避开秘密、完整私人路径和原始配置。

通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 task-specific（仅本次）还是 reusable（可跨任务复用）。
2. task-specific 只修改当前任务，不改 Skill。
3. reusable 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. reusable 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。