Ảnh minh hoạ chương và section

Trạng thái (03.10.2026): 216 quyển, 5.395 ảnh (215 quyển của 18 cộng đồng + quyển thí điểm). 29 quyển "chưa phân loại" chưa có ảnh: chưa thuộc cộng đồng nào, chưa có bìa để lấy DNA.

Mỗi chương và mỗi section của một quyển có một ảnh minh hoạ 16:9, vẽ bằng thuật toán dạng SVG, hiện ở đầu trang chương/section trên tokyo. Thí điểm: "Đêm trống" (db-hospitality-01), 5 chương + 20 section = 25 ảnh (03.10.2026). Quy mô cả kệ: 1.175 chương + 4.598 section.

Khác bìa sách ở hai điểm, cả hai là quyết định của người soạn

	Bìa sách	Ảnh minh hoạ
Màu	bốn màu token cố định	đa dạng: mỗi chương một sắc, mỗi section lệch quanh sắc chương
Lưu ở đâu	tệp SVG trong repo	không có tệp: Worker vẽ từ cảnh + DNA trong D1 lúc phục vụ

Vì sao không lưu tệp: 5.773 ảnh × 30-60 KB là hàng trăm MB thêm vào repo (đã ~350 MB). Lưu cảnh (JSON vài KB) thì repo nhẹ, và sửa bộ vẽ là cả kệ đẹp lên cùng lúc.

Đa dạng nhưng cùng một nhà: DNA của quyển

Mỗi quyển lưu một DNA (book_art_styles.style_json + prompt), là những khía cạnh giữ nguyên ở mọi ảnh:

• dải độ bão hoà và độ sáng (nền, phần tối), độ tương phản, chế độ màu nhấn (bù hoặc liền kề);
• nét (độ dày), bo góc, bóng (độ đậm), hạt giấy (mật độ), khung (bo tròn/viền trong);
• ánh sáng (hướng, độ loé);
• bày biện (dress): kiểu phòng chung (ốp tường, khung tranh, đèn tường, thảm; mặt bàn có tấm lót, giấy lẻ);
• vật ký hiệu: một vật nhỏ ở cùng chỗ trong mọi ảnh (quyển "Đêm trống": chìa khoá phòng thẻ màu nhấn).

Chỉ sắc độ thay đổi: chương k có sắc gốc = base_hue + (k-1) × 137,5° (góc vàng, nên hai chương cạnh nhau luôn khác hẳn màu); section lệch tối đa section_spread độ quanh sắc chương, nên các section của một chương là một họ màu.

Lưu ở đâu

Thứ	Ở đâu
Nguồn sự thật	api.conan.school/content/books/illustrations/<ebook_id>.json: style, style_prompt, items (mỗi khoá chN hoặc chN-sM có scene + why)
DNA	D1 book_art_styles (ebook_id, style_json, prompt)
Từng ảnh	D1 book_illustrations (id, ebook_id, target_type, target_id, chapter/section, prompt, scene_json, meta_json, version)
Bộ vẽ	api.conan.school/src/domains/book-art/ (svg.ts, palette.ts, render.ts, sổ vật motifs/: common.ts + một tệp mỗi cộng đồng)
Phục vụ	GET /api/book-art/<id>.svg?v=<băm>, công khai, giữ bộ đệm một năm ở trình duyệt và ở Cloudflare (Cache API); API chương/section trả illustration_url

meta_json giữ: câu chuyện (why), vật chính, danh sách vật, góc máy, số khối, dung lượng.

Lệnh

cd api.conan.school
npx tsx scripts/book_illustrations.ts preview db-hospitality-01   # SVG + trang xem /tmp/ill-<id>/index.html
npx tsx scripts/book_illustrations.ts check db-hospitality-01     # cửa kiểm
npx tsx scripts/book_illustrations.ts sql db-hospitality-01 > migrations/<prefix>_book_illustrations_<id>.sql

Script chạy chính bộ vẽ của Worker, nên ảnh xem ở máy là ảnh người đọc thấy.

Đợt cả kệ (03.10.2026)

18 agent, mỗi cộng đồng một agent, mỗi agent vẽ 30-49 vật của ngành (tổng khoảng 780 vật) rồi phân cảnh cho 11-12 quyển. Người điều phối xem bảng ảnh của từng kệ và trả lại khi chưa đạt; hai lỗi trả lại nhiều nhất:

• Một khuôn cho mọi ảnh: kệ đầu tiên nộp (Food) dùng "quầy giữa + vài vật nhỏ + giỏ góc" cho cả 300 ảnh, vật chính nhỏ. Sau đó brief thêm luật: mỗi quyển ít nhất 5 kiểu bố cục, không kiểu nào quá 6 ảnh, vật chính 35-55% chiều cao khung. Phần lớn agent tự viết assert cho luật này trong bộ sinh của mình.
• why ghép tên vật + dán nguyên Guiding Question: phải viết tay một câu kể ảnh nói gì.
• Một vật xuất hiện ở gần mọi ảnh (tủ mát 20/25 ảnh, đồng hồ treo tường ở mọi ảnh): giới hạn ở những ảnh câu chuyện thật sự cần.

Migration: một tệp mỗi quyển, 20261008a001-a215 (lớn nhất 75 KB; tệp làm D1 bỏ dở là 372 KB).

Mức chi tiết của thí điểm, nói thẳng

25 ảnh của "Đêm trống" có 276-741 khối, trung vị 412: thưa hơn bìa sách (bìa 501-1.739). Lý do: bìa vẽ tay từng cảnh bằng mã riêng, còn minh hoạ ghép từ thư viện 24 vật dùng chung + lớp bày biện tự động. Đổi lại, cách này mới làm được 5.773 ảnh. Muốn dày hơn thì làm giàu thư viện vật và lớp bày biện, không viết thêm cảnh: mỗi vật làm giàu một lần là mọi ảnh dùng vật đó đẹp lên.

Chi tiết quy trình và bẫy: skill book-illustrations.