Novel to WeChat

Produce a publication package for each story while preserving the original prose. Treat chaptered and continuous stories as equally supported inputs. This workflow is agent-neutral: it can run from Codex, Claude Code, Cursor, or any other agent that can read files, run scripts, call an image model, and write output files. The $novel-to-wechat form is an optional Codex shortcut, not a requirement.

Before starting, read references/agent-compatibility.md and map each capability to the host agent's tools.

The current plugin is copy-only and ends after generating the self-contained copy page.

The generated page copies rich text with images when supported, falls back to DOM selection and plain text, and leaves final paste inspection to the user.

Agent-neutral invocation

Users can invoke this workflow in ordinary language, for example:

• “Use the novel-to-wechat workflow on these Markdown stories and return a copy-ready WeChat article.”
• “Turn this story into a cover, paragraph-level illustrations, and self-contained HTML.”

In Codex, $novel-to-wechat is also available. In Claude Code and other agents, use the skill name or the natural-language request; do not assume Codex-specific commands, paths, or bundled runtimes.

Apply defaults

• Use full-auto unless the user requests prompt review, prompts only, or a partial rework.
• Create one body illustration for every real chapter with prose.
• For prose without chapters, select semantic scene beats and place images after suitable existing paragraphs. Never invent visible chapter headings.
• Preserve every body paragraph. Do not polish, rewrite, abridge, continue, or repartition the story unless requested.
• Keep separate stories in separate packages. Build a batch index instead of merging them.
• Avoid blocking questions when title, author, or art style can be inferred safely. Report assumptions in the result.
• Pause before image generation only when the requested mode requires it, the plan exceeds 8 body images, or a visual ambiguity would materially change the work.
• End the workflow with the local copy package and a manual paste check.

Run the workflow in order

1. Normalize the source

Use the host agent's declared Python runtime or isolated virtual environment for every Python script. If the host provides a bundled workspace runtime, prefer it; otherwise use a compatible isolated Python. Do not assume Codex-specific runtime paths.

For pasted prose, save the text verbatim as a task-local UTF-8 Markdown file. For each input story, create its own working directory and run:

<workspace-python> scripts/ingest_novel.py <input> --out <story-dir>/source.json

Inspect source.json. Correct only deterministic parsing mistakes such as a title mistaken for a paragraph. Do not alter the prose.

2. Plan art and placements

Read references/planning-and-prompts.md completely before planning images.

Read all source paragraphs, then create:

• <story-dir>/visual-bible.json
• <story-dir>/illustration-plan.json

Use paragraph IDs from source.json for every source basis and placement. Let semantic reasoning choose scenes; do not use word count alone to choose a picture. Use word count only as a density guardrail for continuous prose.

For chaptered sources, cover every real chapter that contains prose. For continuous sources, identify internal scene, time, place, goal, conflict, perspective, and emotional changes without exposing those internal beats as headings in the final article.

3. Commit prompts before images

Create both files before invoking image generation:

• <story-dir>/prompts/prompts.json
• <story-dir>/prompts/prompts.md

Ensure every planned image has exactly one prompt and every prompt cites source paragraph IDs. Keep prompts.md readable in Chinese; keep prompts.json machine-valid and complete.

Run the preflight gate:

<workspace-python> scripts/validate_story_package.py \
  --source <story-dir>/source.json \
  --plan <story-dir>/illustration-plan.json \
  --prompts <story-dir>/prompts/prompts.json \
  --report <story-dir>/qa-preflight.json

Fix every error before proceeding. In review-prompts mode, stop here and show the prompt book. In prompts-only mode, deliver the planning files and finish.

4. Generate images

Use the host agent's configured image-generation capability for all generative creation and visual revisions. If no image model is available, deliver the complete prompt book and a prompts-only package, or use user-supplied images; never silently substitute stock search or programmatic drawings.

Generate the text-free cover-master first. When a character appears in multiple images, establish a character/style reference and reuse it wherever the image tool supports references. Generate body illustrations in reading order, carrying forward the visual-bible anchors.

Save each result under the exact image_file declared in the plan. Do not ask the image model to render Chinese titles, captions, watermarks, or logos.

Check each image against both its source paragraphs and prompt. Automatically revise a failed image at most twice. Preserve accepted images during partial retries.

Run the image gate:

<workspace-python> scripts/validate_story_package.py \
  --source <story-dir>/source.json \
  --plan <story-dir>/illustration-plan.json \
  --prompts <story-dir>/prompts/prompts.json \
  --images-dir <story-dir>/images \
  --require-images \
  --report <story-dir>/qa-images.json

Treat an image timestamp earlier than prompts.json as a hard failure.

5. Compose cover variants

Use the cover script only for deterministic crop and accurate Chinese typography; use the image-generation tool for any creative image change.

<workspace-python> scripts/compose_cover.py \
  <story-dir>/images/cover-master.png \
  --out-dir <story-dir>/images \
  --title "<title>" \
  --author "<author>"

Adjust --focus-x and --focus-y if the feed crop cuts off the subject. Keep the feed crop text-free. Generate title text only in header-title.jpg.

6. Render the publishing package

Read references/output-contract.md completely before rendering.

<workspace-python> scripts/render_wechat.py \
  --source <story-dir>/source.json \
  --visual-bible <story-dir>/visual-bible.json \
  --plan <story-dir>/illustration-plan.json \
  --prompts <story-dir>/prompts/prompts.json \
  --images-dir <story-dir>/images \
  --out-dir <story-dir>

Generate a self-contained HTML copy page with embedded images and inline styles. Generate a DOCX fallback unless the user explicitly declines it.

7. Verify before delivery

Run structural QA:

<workspace-python> scripts/verify_output.py <story-dir>

For every generated DOCX, use the host agent's document renderer (or LibreOffice) to render all pages to PNG. Set FONTCONFIG_FILE to this skill's assets/fonts.xml when the renderer supports it so isolated LibreOffice profiles can discover CJK system fonts. If DOCX rendering is unavailable, still deliver HTML/Markdown and clearly report that visual DOCX QA was not run:

FONTCONFIG_FILE=<skill-dir>/assets/fonts.xml \
  <workspace-python> <documents-renderer>/render_docx.py \
  <story-dir>/公众号成稿.docx --output_dir <story-dir>/qa-docx-pages

Inspect every page at full size for missing Chinese glyphs, clipped images, awkward page breaks, crowding, and missing paragraphs. Treat absent Chinese text as a failed render even when structural extraction succeeds. Re-render after each correction. Then rerun verify_output.py with --rendered-pages-dir.

Open 公众号复制页.html in a host browser and verify the local preview visually. Exercise its copy button against a disposable rich-text field when practical. If browser access is unavailable, perform static HTML checks and state the limitation. Do not claim target-editor paste compatibility; retain DOCX as the fallback.

For a batch, build the shared index after all individual packages pass:

<workspace-python> scripts/build_batch_index.py <batch-root>

Handle revisions without restarting

• Rework only the requested illustration, cover crop, prompt, or layout area.
• Keep existing IDs and filenames stable so placements do not drift.
• Update the corresponding prompt record before regenerating an image.
• Rerun the image gate, renderer, DOCX render QA, and output verification after any image or placement change.
• The workflow ends with the local copy package.

Deliver the useful surface

Link the user to each 公众号复制页.html, 公众号成稿.docx, and prompt book. Summarize the number of stories, body illustrations, any inferred art direction, continuous-prose placement decisions, and any unresolved QA caveat. Do not overwhelm the user with internal intermediate files unless requested.