poetry-book

Poetry Book

Compile a set of sourced materials into a readable, verifiable, rebuildable poetry book, technical feature, or handout. The deliverable is an actual PDF, not merely typesetting suggestions or LaTeX fragments.

Inputs and principles

1. First confirm the theme, author scope, time range, output language, and required style; if the user has not specified a theme, use song-mist。
2. Inventory and preserve the original files. Record each work, passage, dating, basis for dating, annotation, and source item by item; do not mix source files with the editorial layer.
3. Organize the materials into the normalized JSON shown in examples/book.json . The engine receives this JSON; do not claim that arbitrary PDFs, images, or web pages can be turned into a book directly without reading and structuring them.
4. Default delivery is simplified Chinese horizontal typesetting. Traditional Chinese originals may be retained for textual research, but the formal manuscript must be converted according to the user's requirements and spot-checked; do not change it to vertical typesetting without authorization.
5. Place works with known years into chapters in ascending order by date.start ; if only a range can be determined, retain the range and "approximately"; place works that cannot be dated into appendix, and do not fabricate years. The engine will not silently reorder incorrect sequences.
6. Each work must have a stable ID and at least one source. Headnotes,gloss annotations, andcomment commentary should be written according to evidence; do not mass-generate vague appreciation for ordinary works.
7. Numbers should state only the actual quantities of materials processed, and must not claim that "nothing under heaven has been omitted". Uncertain attribution, variant readings, duplicate body text, and missing sources must be explicitly indicated.

Environment and output

Requires latexmk, LuaLaTeX, Ghostscript, Python 3, and fontTools, PyMuPDF, Pillow; technical article mode additionally uses PyYAML, and LaTeX uses fancyvrb, booktabs, tabularx. The system requires Source Han Serif SC VF, Early Summer Serif, and LXGW WenKai. The skill bundles BabelStoneHan, I.Ming and their licenses; the main Chinese font file can also be specified via POETRY_BOOK_MAIN_FONT to compute fallback for rare characters.

If dependencies are missing, report clearly and stop; do not silently switch to Last Resort or Unifont, and do not install software without consent.

The output directory must not exist or must be empty, to prevent overwriting user materials. For rebuilding, use a new directory, or run again only after the user has explicitly handled the old output.

Six themes

ID	Name	Suitable mood
song-mist	Misty Rain and Negative Space	Default; rice white, pale ink, distant mountains, river surface, and vermilion seals
celadon	Celadon Sky Blue	Warm, clear, and restrained blue-green layered mountains
ink-zen	Ink Zen Still Illumination	Gray-white, ink mountains, ensō, and ink commentary
cinnabar-seal	Cinnabar Seal Album	Rice paper, cinnabar, and connoisseur seals
moon-river	Moonlit Red Cliff	Blue-gray, bright moon, river water, and night sailing
bamboo	Bamboo Shadows and Clear Wind	Pale blue-green, sparse bamboo, and leaf shadows

List only currently implemented templates. List themes:

python3 "$HOME/.agents/skills/poetry-book/scripts/build_style.py" --list

Build and acceptance

python3 "$HOME/.agents/skills/poetry-book/scripts/render_book.py" \
  --input "/absolute/path/book.json" \
  --theme "song-mist" \
  --output "/absolute/path/new-output-directory"

The command checks the manuscript and dependencies, compiles LaTeX, copies the finished product, and automatically performs PDF acceptance. Successful output includes:

• A PDF named after the complete book title.
• build/ The LaTeX, compilation log, work-page mapping, and build manifest in
• manifest.json、font-usage.json and book.works。
• validation-report.json。
• preview/ representative pages and contact sheets in .

Validation does not only check the compilation exit code. It also includes book title metadata, page dimensions, actual page placement of work IDs, representative body text, missing characters and reference errors in logs, layout overflow, font embedding, illegal fallback fonts, out-of-bounds pages, abnormal blank pages, horizontal layout sampling, and full-page parsing by Ghostscript.

Technical Articles and Course Handouts

Ordinary Markdown can directly enter technical article mode without first manually converting it into a poetry data structure:

python3 "$HOME/.agents/skills/poetry-book/scripts/render_article.py" \
  --input "/absolute/path/article.md" \
  --theme "celadon" \
  --title "文章主标题" \
  --subtitle "文章副标题" \
  --author "作者或栏目名" \
  --seal "印章文字" \
  --output "/absolute/path/new-output-directory"

Supports YAML metadata, headings, bold text, inline code, HTTP/HTTPS links, ordered/unordered lists, images, fenced code, simple pipe tables, and blockquotes.--series、--edition、--date、--subject can override the default metadata;--require "必须出现的语句" can be repeated for critical content acceptance checks.

• The source text is read-only; the converted source.md、book.json and source-manifest.json remain in the materials directory. The default materials directory is <输出名>-assetsnext to the output directory, and can also be specified with --assets-dir .
• Network images are allowed only over HTTPS, with a 25MB limit per image, and dimensions and SHA-256 are recorded. When using --offline , downloading is prohibited; only existing images with consistent validation are used.
• Articles do not display the chronological basis or duplicate year titles of poetry; source manuscript line numbers are used for chapter source and missing-paragraph checks.
• Images preserve aspect ratio; article validation also includes image count, links, residual Markdown, and specified key sentences.
• Complex HTML, nested lists, tables with escaped pipes, mathematical formulas, etc. are not currently supported; unsupported structures should be handled explicitly rather than silently omitted.

The complete case is in examples/laozhang-deepinfer/: the Lao Zhang DeepInfer technical article, 7 original images, and a source list. Code, table, blockquote, and link fixtures are in examples/technical-fixture.md。

Manuscript Structure Quick Reference

• metadata：title、author is required;subtitle、series、edition、seal、subject、keywords is configurable.
• frontmatter、backmatter: a chapter array composed of heading and paragraphs .
• chapters: each chapter contains id、title、years、intro、works。
• appendix: optional, with the same structure as chapters, used for works without a date or spanning periods.
• works[]：id、title、type、paragraphs、date、sources is required;date contains at least one of start、end、label、evidence，sources .intro、gloss、comment is optional.
• document_type：book(default) or article. Articles can use works[].blocks to represent paragraphs, headings, lists, images, code, tables, blockquotes, and horizontal rules; the legacy paragraphs manuscript remains compatible.
• index: defaults to true, generating a title index; technical articles usually disable the title index and enter the table of contents through article sections.

See examples/book.jsonfor a complete runnable example. When manuscript fields are invalid, work IDs are duplicated, body text is empty, years are in reverse order, or sources are missing, the command should exit with a non-zero status and give the field location.

Completion Criteria

Only after both the PDF and validation-report.json are generated, the report passed is true, and the cover and representative pages have been reviewed, may completion be reported to the user. Provide PDF, report, and preview links in the reply, and explain the theme, page count, work count, material scope, and any uncertain conventions; matters not covered by tests must not be claimed as verified.