A book is forged into a 2050 library borrowing card. The cover, author, and bibliography are this card's identity; what really needs to be done is to distill the book's original "viewfinder" into an intended image—the author looks at a certain problem from a certain angle and sees an image no one else has seen. The text block explains this image thoroughly, and the diagram block draws it. Glance at the card half a year later, the image comes back, and the book was not read in vain.
A card has two jobs:
- Viewfinder block (text): main sentence
{{FRAME}}points out this image in one sentence, Feynman explanation{{EXP}}explains it to a smart layperson.{{EXP}}must go throughfeynman-eli5skill generation, not handwritten. - Diagram block (image generation): hand the same image to
assets/gen_illustration.pyto draw it. Jigang is the protagonist of every image—the script feeds his ink likeness (assets/ljg-portrait.png) as a character reference to the model, drawing a recognizable him, letting him personally experience that core action in the image—actively doing it, or passively enduring it. The style is Yoshida Seiji-style picture-book feel: otherworldly everyday spaces, warm light slanting in, honey-amber wood-brown warm tones, solid architectural perspective, stacked details of plants, books, and objects, healing places like a magic workshop, old bookstore, or library, naturally handwritten Chinese characters within the scene, Jigang as a small figure dwelling within it. The style is hardcoded in the script; frame only writes what to draw.
The text and the image must tell the same image. If the distillation fails, this card is just a Douban Reading card.
The output is only PNG, no text notes are produced.
Read two references before starting
references/extraction.md— how to distill an intended image from a book, and how to write an image-generation frame. Distillation has six steps: object, angle, old image, intended image, Feynman explanation, verification. If Jigang has already thought the idea through (forging a card right after reading is the norm), use his directly: only go through verification and drawing, do not re-distill.references/visual.md— card body specifications, color scheme, fonts, factory self-check.
Process
输入:书名(或 书名 + 已想透的取景框思想)
↓
1. weread 取真封面 + 书目(见「素材获取」)
2. web 抓作者头像
3. 提封面主色 → 卡身强调色(python3 assets/extract_color.py <封面>)
4. 提炼意向画面(用户给了→校验;没给→extraction.md 六步)
5. {{FRAME}} 主句 + {{EXP}} 费曼讲解(走 feynman-eli5)
6. 写 frame(英文构图:继刚在做什么、隐喻物件、信息流向、3-5 个中文标注每个 ≤5 字),生图:
python3 assets/gen_illustration.py --frame "<...>" --out /tmp/ljg_lib_{slug}_sketch.png
7. 填 assets/library_template.html 占位变量({{SKETCH_IMG}} = file://生成图)
8. 渲染(capture.js,fullpage)
9. Read 成品 PNG 亲眼验,不满意调 frame 重生,然后交付
Material acquisition
Cover + bibliography
Jigang has WeRead, first go through weread skill's /store/search(Read before use ~/.claude/skills/weread/search.md):
curl -s -X POST "https://i.weread.qq.com/api/agent/gateway" \
-H "Authorization: Bearer $WEREAD_API_KEY" -H "Content-Type: application/json" \
-d '{"api_name":"/store/search","keyword":"<书名>","scope":10,"skill_version":"1.0.3"}'
The response packet results[].books[].bookInfo(each result is one book) contains title / author / translator / cover / publisher. The cover URL defaults to s_ thumbnail (70×100, will be blurry when put on the card), replace s_ with t7_ to get 285×411 high definition:.../cover/942/635942/t7_635942.jpg. Download with -H "Referer: https://weread.qq.com/"。
When weread cannot find it, degrade by book type:
- Chinese books / Dedao course-type books → Douban cover, use
l/publiclarge image path (s/publicsmall image will be blurry) - Foreign-language academic books → OpenLibrary:
https://openlibrary.org/search.json?q=<书名>getcover_i, then go through covers CDNhttps://covers.openlibrary.org/b/id/<cover_i>-L.jpg - If none are available → CSS placeholder book cover, do not block
Author portrait
Wikipedia original image is the most stable, Wikipedia API directly gets the original image URL:
curl -s -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
"https://en.wikipedia.org/w/api.php?action=query&titles=<英文名>&prop=pageimages&piprop=original&format=json"
# 拿到 .original.source 后下载(同样带 UA):
curl -sL -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" -o /tmp/ljg_lib_{slug}_avatar.jpg "<original-url>"
Note the thumb path (/thumb/.../480px-xxx.jpg) returns an HTML error page when that size is not cached—use the original image path (remove /thumb/ and size segment), and it must include a User-Agent; missing UA will be blocked by Wikimedia.
Fallback: English Wikipedia has none → Wikipedia REST summary (/api/rest_v1/page/summary/<名字>) → Chinese people go through Baidu Baike → if none exist, omit the avatar (the template author line automatically does not display an avatar), without blocking.
Protagonist reference image
assets/ljg-portrait.png is Ji Gang's real avatar cutout ink image,gen_illustration.py automatically feed it to the model as a character reference. What is generated is him drawn by the model in the style of Seiji Yoshida—recognizable is enough; pixel-level identical face is not pursued. If the avatar needs updating, just replace this png.
Card body accent color
python3 assets/extract_color.py /tmp/ljg_lib_{slug}_cover.jpg
# 输出形如:#c43d30
Extract the most prominent color from the cover as the card body accent color; changing books automatically changes the color: red cover red card, blue cover blue card. Two situations require manual adjustment: when the cover subject is a large area of beige-gray background, the script will pick out a dull background color; reorder by "vividness × frequency" and pick a color from the real pixels that can hold up, do not hardcode it out of thin air; when the cover color is very bright, darken it by half a step so it is readable on the light-colored card body. The accent color only governs the card body (labels, English lines, keyword highlights, signature seal); the color scheme of the diagram board comes with the generated image, and the two do not interfere with each other. Choosing warm colors (brown, orange, green) matches that warm-toned illustration better.
Template variables (library_template.html)
| Variable | Content |
|---|---|
{{ACCENT}} |
Card body accent color hex (extracted from the cover) |
{{COVER}} |
The cover's file:// absolute path |
{{AVATAR_IMG}} |
The entire avatar <img class="avatar" src="file://…">(fill with an empty string if there is no avatar) |
{{TITLE}} {{EN}} {{SUBTITLE}} |
Book title in Chinese / English / subtitle |
{{TAGS}} |
3-4 topic tags, each <span class="tag">…</span> |
{{AUTHOR_CN}} {{AUTHOR_META}} |
Author Chinese name / "English name · Publisher Year" |
{{FRAME}} |
Main sentence of the intended image, keywords use <span class="hl">…</span> dyed with the accent color |
{{EXP}} |
Feynman explanation (feynman-eli5 output), keywords are also dyed |
{{SKETCH_TITLE}} |
Diagram board name (English + Chinese, e.g. Ergodicity 遍历性) |
{{SKETCH_IMG}} |
The generated illustration's file:// absolute path |
Rendering
node ~/.claude/skills/ljg-card/assets/capture.js \
/tmp/ljg_library_{name}.html ~/Downloads/{name}.png 1080 1440 fullpage
Reuse ljg-card's capture.js (playwright installed in ljg-card/node_modules).fullpage cannot be omitted—the card height follows the content; omitting it will leave blank space at the bottom.file:// Referenced local covers and avatars can be rendered directly.
Delivery
- Read the finished PNG and verify it with your own eyes; zoom in on the diagram board. Check against visual.md's factory self-check: cover loads, the explanation fully explains the image, card body color is harmonious, Ji Gang is recognizable, the image is understandable at a glance, Chinese annotations are not blurry, text and image are the same picture, no gap on the right side, no blank space at the bottom. If the generated image is unsatisfactory, adjust the frame and regenerate.
- Report the file path, plus a sentence explaining the refinement of the intended image.
Gotchas
- Cover size:weread
s_is a 70×100 thumbnail, it will definitely be blurry. Switch tot7_(285×411), download withReferer。 - Avatar thumb trap:Wikimedia
/thumb/.../NNNpx-uncached returns an HTML error page. Use the original image path, with User-Agent. - Generated images must be viewed: the same frame produces a different image every time; gemini will blur Chinese annotations, draw Ji Gang unlike himself, and draw the action wrong. After each generation, you must Read and verify it yourself; if not, adjust the frame and regenerate. Before regenerating, save the current one to another path first—the new one is not necessarily better than the old one, do not overwrite a usable one.
- Chinese annotations ≤5 characters: Long annotations and rare characters tend to get blurry. Keep each annotation to within 5 characters; let the body text carry the mechanism details, don't count on the drawing to spell things out clearly.
- Separate annotations in the frame with semicolons or enumeration commas:
/Separating Chinese annotations gets misjudged by the safety hook as a dangerous command and BLOCKED, so don't use slashes. - The frame must be concrete and drawable: Write clearly the actions Ji Gang personally experienced, real metaphorical objects, and how information flows. Abstract propositions can't be drawn—go back to the intended image and render it into visible objects and actions (see extraction.md).
- Stylize the protagonist, don't chase the same face: Generated from the ink-portrait reference, as long as it's recognizable. Don't do face-swap compositing of the real ink portrait.
- The two color sets don't cross over: The card body accent color is extracted from the cover; the diagram board background comes with the generated image.
- /tmp filenames carry the slug: When minting cards in parallel, generated images, covers, and avatars all use unique paths (with the book slug); a shared fixed name will cross images.
- Image generation cost:
gen_illustration.pycalls marswave gemini-3-pro directly, not going through listenhub's interactive gating. Each image requires internet access, spends API quota, and needs to be visually verified once—slower than pure templates, so leave margin when batching out tasks. - {{FRAME}} writes how the view gets changed, not a content summary: The sentence pattern is "It's not originally X, but actually Y," not "what this book talks about." Test: delete the book title and author, and only if the sentence can still stand on its own is it refined enough.