autoclaw 1.3.4 → 1.3.6

package/dist/tools/render-pdf.js

@@ -0,0 +1,111 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { render as renderPdf } from 'takumi-pdf';
+import { resolveFontLoaders, describeFonts } from './takumi-fonts.js';
+const VALID_SIZES = ['a3', 'a4', 'a5', 'b4', 'b5', 'letter', 'legal', 'ledger'];
+const toolDefinition = {
+    type: "function",
+    function: {
+        name: "render_pdf",
+        description: "Render an HTML template into a paged PDF document with selectable text and embedded subset fonts. Fully offline — no browser, no network, renders in milliseconds. Use for invoices, quotes, reports, packing slips, certificates and any structured document. Content flows across pages automatically; CSS break-before/break-after/break-inside control page breaks, and <thead> repeats on every page of a table. Optional header/footer bands repeat on every page and support page counters via <span class=\"pageNumber\"></span> and <span class=\"totalPages\"></span>. Style with inline styles, a <style> block with regular CSS classes, or the 'tw' attribute (Tailwind v4 utilities) — Tailwind utilities placed in the class attribute are NOT compiled. JavaScript is NOT executed. CJK text needs fonts: common system fonts are auto-detected when font_paths is omitted, and registered families can be referenced via font-family.",
+        parameters: {
+            type: "object",
+            properties: {
+                template: {
+                    type: "string",
+                    description: "HTML fragment for the document body, e.g. '<div style=\"padding:32px\"><h1 style=\"font-size:24px;font-weight:700\">Invoice #1024</h1><table style=\"width:100%\">…</table></div>'. Style via inline styles, a <style> block, or the tw attribute (Tailwind v4 utilities); a plain class attribute only matches CSS selectors, not Tailwind utilities."
+                },
+                css: {
+                    type: "string",
+                    description: "Optional CSS stylesheet applied before layout, e.g. 'tr { break-inside: avoid; }'."
+                },
+                size: {
+                    type: "string",
+                    enum: VALID_SIZES,
+                    description: "Page size. Default 'a4'."
+                },
+                landscape: {
+                    type: "boolean",
+                    description: "Swap page width and height. Default false."
+                },
+                margin: {
+                    description: "Page margin in CSS px: a number applied to all sides, or an object {top,right,bottom,left}. Default 'auto'.",
+                    type: ["number", "object"]
+                },
+                header: {
+                    type: "string",
+                    description: "HTML band repeated at the top of every page, e.g. '<div class=\"text-[10px] text-gray-500\">ACME Ltd</div>'."
+                },
+                footer: {
+                    type: "string",
+                    description: "HTML band repeated at the bottom of every page, e.g. '<div class=\"text-[10px] text-gray-500\" style=\"width:100%;text-align:center\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>'."
+                },
+                font_paths: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Local font files (.ttf/.otf/.ttc/.woff2) to register and embed. Omit to auto-detect common system fonts (incl. CJK). Pass [] to skip font loading (built-in Latin font only)."
+                },
+                title: {
+                    type: "string",
+                    description: "Document title written to the PDF metadata."
+                },
+                outline: {
+                    type: "boolean",
+                    description: "Build a bookmark outline from h1-h6 headings. Default false."
+                },
+                output_path: {
+                    type: "string",
+                    description: "File path to write the PDF. Parent directories are created automatically."
+                }
+            },
+            required: ["template", "output_path"]
+        }
+    }
+};
+const handler = async (args, config) => {
+    const template = typeof args.template === 'string' ? args.template : '';
+    if (!template.trim()) {
+        return "Error: 'template' is required — an HTML fragment for the document body.";
+    }
+    if (!args.output_path) {
+        return "Error: 'output_path' is required.";
+    }
+    const size = String(args.size || 'a4').toLowerCase();
+    if (!VALID_SIZES.includes(size)) {
+        return `Error: Invalid page size '${size}'. Supported sizes: ${VALID_SIZES.join(", ")}.`;
+    }
+    const resolvedPath = path.resolve(process.cwd(), args.output_path);
+    try {
+        const resolved = resolveFontLoaders(args.font_paths);
+        const fontsInfo = describeFonts(resolved);
+        const options = { size };
+        if (resolved.fonts.length > 0)
+            options.fonts = resolved.fonts;
+        if (args.css)
+            options.css = args.css;
+        if (args.landscape)
+            options.landscape = true;
+        if (args.margin != null)
+            options.margin = args.margin;
+        if (args.header)
+            options.header = args.header;
+        if (args.footer)
+            options.footer = args.footer;
+        if (args.title)
+            options.metadata = { title: args.title };
+        if (args.outline)
+            options.outline = true;
+        const bytes = await renderPdf(template, options);
+        fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+        fs.writeFileSync(resolvedPath, Buffer.from(bytes));
+        return `Rendered PDF (${bytes.length} bytes, ${size.toUpperCase()} page size) saved to ${resolvedPath}. Fonts: ${fontsInfo}`;
+    }
+    catch (err) {
+        return `Error rendering PDF: ${err?.message || err}`;
+    }
+};
+export const RenderPdfTool = {
+    name: "PDF Renderer (Takumi)",
+    definition: toolDefinition,
+    handler
+};

package/dist/tools/takumi-fonts.js

@@ -0,0 +1,61 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// Font files registered by the Takumi render tools when a call does not pass
+// font_paths explicitly. Takumi ships only a last-resort Latin font, so without
+// these, CJK and emoji render as tofu in headless containers. Paths mirror the
+// font detection in screenshot.ts and cover Alpine/Debian/Arch packaging plus
+// Windows and macOS system fonts.
+const COMMON_FONT_PATHS = [
+    // Linux — CJK
+    '/usr/share/fonts/noto/NotoSansCJK-Regular.ttc',
+    '/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc',
+    '/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc',
+    '/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc',
+    '/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc',
+    // Linux — emoji
+    '/usr/share/fonts/noto/NotoColorEmoji.ttf',
+    '/usr/share/fonts/truetype/noto/NotoColorEmoji.ttf',
+    '/usr/share/fonts/google-noto-emoji/NotoColorEmoji.ttf',
+    // Windows — msyh.ttc (Microsoft YaHei) covers CJK, seguiemj.ttf covers emoji
+    'C:\\Windows\\Fonts\\msyh.ttc',
+    'C:\\Windows\\Fonts\\simhei.ttf',
+    'C:\\Windows\\Fonts\\arial.ttf',
+    'C:\\Windows\\Fonts\\seguiemj.ttf',
+    // macOS
+    '/System/Library/Fonts/PingFang.ttc',
+    '/System/Library/Fonts/Hiragino Sans GB.ttc',
+    '/System/Library/Fonts/Helvetica.ttc',
+    '/System/Library/Fonts/Apple Color Emoji.ttc',
+];
+// font_paths === undefined -> auto-detect common system fonts
+// font_paths === []        -> skip font loading entirely (built-in Latin font)
+export function resolveFontLoaders(fontPaths) {
+    const paths = fontPaths === undefined
+        ? COMMON_FONT_PATHS.filter(p => fs.existsSync(p))
+        : fontPaths;
+    const fonts = [];
+    const skipped = [];
+    for (const p of paths) {
+        try {
+            const data = fs.readFileSync(p);
+            const name = path.basename(p).replace(/\.(ttf|otf|ttc|woff2?)$/i, '');
+            fonts.push({ name, data });
+        }
+        catch {
+            skipped.push(p);
+        }
+    }
+    return { fonts, families: fonts.map(f => f.name), skipped };
+}
+// One-line summary for tool results so the agent knows which family names it
+// can reference via font-family in templates.
+export function describeFonts(resolved) {
+    if (resolved.families.length === 0) {
+        return 'no extra fonts registered (built-in Latin font only; CJK/emoji need font_paths)';
+    }
+    const parts = [`registered: ${resolved.families.join(', ')}`];
+    if (resolved.skipped.length > 0) {
+        parts.push(`skipped (unreadable): ${resolved.skipped.join(', ')}`);
+    }
+    return parts.join('; ');
+}

package/dist/zip.js

@@ -0,0 +1,149 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as zlib from 'zlib';
+// ---- CRC32 ----
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+// ---- writer ----
+export function createZip(files) {
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    const dosTime = 0;
+    const dosDate = 0x21; // fixed 1980-01-01 for deterministic output
+    for (const file of files) {
+        const name = Buffer.from(file.path.replace(/\\/g, '/'), 'utf8');
+        const crc = crc32(file.data);
+        const deflated = zlib.deflateRawSync(file.data, { level: 9 });
+        const useDeflate = deflated.length < file.data.length;
+        const payload = useDeflate ? deflated : file.data;
+        const method = useDeflate ? 8 : 0;
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6); // UTF-8 names
+        local.writeUInt16LE(method, 8);
+        local.writeUInt16LE(dosTime, 10);
+        local.writeUInt16LE(dosDate, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(payload.length, 18);
+        local.writeUInt32LE(file.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        chunks.push(local, name, payload);
+        const cd = Buffer.alloc(46);
+        cd.writeUInt32LE(0x02014b50, 0);
+        cd.writeUInt16LE(20, 4);
+        cd.writeUInt16LE(20, 6);
+        cd.writeUInt16LE(0x0800, 8);
+        cd.writeUInt16LE(method, 10);
+        cd.writeUInt16LE(dosTime, 12);
+        cd.writeUInt16LE(dosDate, 14);
+        cd.writeUInt32LE(crc, 16);
+        cd.writeUInt32LE(payload.length, 20);
+        cd.writeUInt32LE(file.data.length, 24);
+        cd.writeUInt16LE(name.length, 28);
+        cd.writeUInt32LE(offset, 42);
+        central.push(Buffer.concat([cd, name]));
+        offset += 30 + name.length + payload.length;
+    }
+    const centralBuf = Buffer.concat(central);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(files.length, 8);
+    eocd.writeUInt16LE(files.length, 10);
+    eocd.writeUInt32LE(centralBuf.length, 12);
+    eocd.writeUInt32LE(offset, 16);
+    return Buffer.concat([...chunks, centralBuf, eocd]);
+}
+// ---- reader ----
+export function readZip(buf) {
+    let eocd = -1;
+    const min = Math.max(0, buf.length - 22 - 65535);
+    for (let i = buf.length - 22; i >= min; i--) {
+        if (buf.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error('not a zip archive (end-of-central-directory not found)');
+    const count = buf.readUInt16LE(eocd + 10);
+    const cdOffset = buf.readUInt32LE(eocd + 16);
+    const entries = [];
+    let p = cdOffset;
+    for (let n = 0; n < count; n++) {
+        if (p + 46 > buf.length || buf.readUInt32LE(p) !== 0x02014b50) {
+            throw new Error('corrupt zip archive (bad central directory)');
+        }
+        const method = buf.readUInt16LE(p + 10);
+        const compSize = buf.readUInt32LE(p + 20);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const localOffset = buf.readUInt32LE(p + 42);
+        const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+        const lhNameLen = buf.readUInt16LE(localOffset + 26);
+        const lhExtraLen = buf.readUInt16LE(localOffset + 28);
+        const dataStart = localOffset + 30 + lhNameLen + lhExtraLen;
+        const raw = buf.subarray(dataStart, dataStart + compSize);
+        let data;
+        if (method === 0)
+            data = Buffer.from(raw);
+        else if (method === 8)
+            data = zlib.inflateRawSync(raw);
+        else
+            throw new Error(`unsupported zip compression method ${method} (entry: ${name})`);
+        entries.push({ path: name, data });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+// Reject absolute paths, drive letters, '..' traversal, and directory entries.
+export function safeJoinZipPath(destDir, zipPath) {
+    const norm = zipPath.replace(/\\/g, '/');
+    if (norm.endsWith('/'))
+        return null; // directory entry — created implicitly
+    if (norm.startsWith('/') || /^[a-zA-Z]:/.test(norm)) {
+        throw new Error(`unsafe zip entry (absolute path): ${zipPath}`);
+    }
+    const parts = norm.split('/').filter(s => s.length > 0);
+    if (parts.length === 0 || parts.some(s => s === '..')) {
+        throw new Error(`unsafe zip entry (path traversal): ${zipPath}`);
+    }
+    return path.join(destDir, ...parts);
+}
+// Extract every entry into destDir, creating parents as needed. All paths are
+// validated up-front so an unsafe entry (zip-slip) rejects the whole archive
+// before a single byte is written.
+export function extractZip(buf, destDir) {
+    const entries = readZip(buf);
+    const resolved = [];
+    for (const entry of entries) {
+        const dest = safeJoinZipPath(destDir, entry.path);
+        if (dest === null)
+            continue; // directory entry
+        resolved.push({ dest, data: entry.data });
+    }
+    const written = [];
+    for (const r of resolved) {
+        fs.mkdirSync(path.dirname(r.dest), { recursive: true });
+        fs.writeFileSync(r.dest, r.data);
+        written.push(r.dest);
+    }
+    return written;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoclaw",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "package.json",
     "LICENSE"
@@ -59,7 +60,9 @@
     "nodemailer": "^8.0.0",
     "openai": "^6.18.0",
     "ora": "^9.3.0",
-    "playwright": "^1.58.2"
+    "playwright": "^1.58.2",
+    "takumi-js": "^2.13.5",
+    "takumi-pdf": "^0.14.1"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.9",

package/skills/code2media/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: code2media
+display_name: 代码转多媒体（HTML → 图片/PDF/动图）
+display_name_en: Code to Media (HTML → images/PDF/animations)
+description: Universal renderer — turn any HTML into pixel-perfect PNG/JPEG/WebP images, vector SVG, paged PDFs and animated WebP/GIF. Offline, no browser. Use when the user wants to 把内容/代码/数据变成图片或PDF, 生成图片/OG图/徽章/数据卡片/动图, 生成PDF/报告/发票/工单, or render HTML to image or PDF. For deep scenario optimization see sibling skills (posters, invoices, certificates).
+description_zh: 通用多媒体渲染:把任意 HTML 变成精确的图片(PNG/JPEG/WebP)、矢量 SVG、分页 PDF 和动图(WebP/GIF)。离线渲染,无需浏览器,毫秒级出图,文字排版 100% 精确。通用兜底;海报/发票/证书等具体场景有专属技能时优先用专属技能。
+description_en: Universal multimedia renderer — any HTML becomes precise images (PNG/JPEG/WebP), vector SVG, paged PDFs and animations (WebP/GIF). Offline, no browser, millisecond-per-render. General fallback; prefer dedicated scenario skills (posters, invoices, certificates) when available.
+category: image
+version: 1.2.0
+author: AutoClaw
+---
+
+# 代码转多媒体
+
+把任意 HTML 变成可直接交付的多媒体:图片、矢量 SVG、分页 PDF、动图。底层是 Takumi 渲染引擎(纯计算,无浏览器、无 AI、无网络依赖),**你写什么 HTML,输出就是什么像素**——文字、排版、颜色 100% 精确,相同输入永远得到相同输出。
+
+这是**通用渲染技能**:处理任意自定义图形与文档需求。海报、发票、证书等高频场景有各自独立优化的专属技能,任务精确匹配场景时优先用专属技能;没有匹配场景、或需要完全自定义的产物时,用本技能。
+
+## 何时使用
+
+- 用户要**自定义/长尾**的图形与文档:上面场景技能没覆盖的尺寸、结构、风格,数据驱动的图表卡片,一次性版式
+- 用户要**动图**:加载动画、动态徽章、社媒动图
+- 任务明确命中高频场景时优先用专属技能(它们有独立的排版规范与质量清单):海报/封面/分享卡 → `poster-maker`;发票/报价单/收据/采购单 → `invoice-maker`
+- 不适用:艺术创作、照片类图像(用平台的 AI 生图能力);截图现实网页(用浏览器/截图工具)
+
+## 工作流程
+
+1. **选起点**:优先修改 `templates/` 里的现成模板(见下方清单);没有合适的再从零写。语法规则必须遵守 `@references/syntax-guide.md`,最重要的三条:
+   - Tailwind 工具类写在 **`tw` 属性**里(`class` 属性不编译 Tailwind,只匹配普通 CSS 选择器)
+   - 用 Tailwind v4 规范名(渐变是 `bg-linear-to-br`,不是 v3 的 `bg-gradient-to-br`)
+   - 根元素撑满画布:`tw="w-full h-full ..."`
+2. **写出 HTML 片段文件**(不需要完整 HTML 文档),数据直接填进模板。
+3. **运行渲染脚本**:
+   ```bash
+   node "<技能目录>/scripts/render.mjs" --html card.html -o card.png --width 1200 --height 630
+   ```
+   首次运行会自动安装 takumi-js / takumi-pdf(一次性,需网络);之后完全离线。
+4. **校验并交付**:确认脚本输出 `OK` 与文件存在,把输出路径告诉用户。渲染是毫秒级的,改模板重渲染的成本几乎为零——效果不满意就直接改了再跑。
+
+## 命令速查
+
+```bash
+# 静态图片(png/jpeg/webp),尺寸自定
+node scripts/render.mjs --html card.html -o card.png --width 1200 --height 630
+# 矢量 SVG
+node scripts/render.mjs --html badge.html -o badge.svg --width 560 --height 160
+# 分页 PDF(a3/a4/a5/b4/b5/letter/legal/ledger,自动分页,可加页脚/标题/书签)
+node scripts/render.mjs --html invoice.html --pdf -o invoice.pdf --size a4 --title "采购订单" \
+  --footer '<div style="width:100%;text-align:center;font-size:10px;color:#94a3b8">第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页</div>'
+# 动图(CSS @keyframes 按时间采样,输出 webp/gif/apng)
+node scripts/render.mjs --html anim.html --animation webp -o anim.webp --width 480 --height 480 --fps 30 --duration 1200
+# 附加样式表 / 指定字体 / 跳过字体
+node scripts/render.mjs --html card.html -o card.png --css extra.css
+node scripts/render.mjs --html card.html -o card.png --font /path/MyFont.ttf
+node scripts/render.mjs --html card.html -o card.png --no-fonts   # 纯拉丁文字时更快
+```
+
+JPEG/WebP 可加 `--quality 80`。PDF 表格加 `style="break-inside:avoid"` 防止行被劈开,`<thead>` 会跨页自动重复。
+
+## 模板清单(templates/)
+
+通用示例模板,展示引擎能力面。海报/封面/OG 图在 `poster-maker` 技能,发票/报价单在 `invoice-maker` 技能。
+
+| 文件 | 用途 | 建议参数 |
+| :--- | :--- | :--- |
+| `metrics-card.html` | KPI 数据指标卡(1600x900) | 图片 |
+| `certificate.html` | 结业证书/奖状(1414x1000,金色边框) | 图片 |
+| `weekly-report.html` | 单页 A4 运营周报(KPI + 纯 div 柱状图) | `--pdf` |
+| `badge.html` | SVG 徽章/发布标签(560x160) | 图片(输出 .svg) |
+| `animation.html` | 品牌 Logo 脉冲动画(480x480) | `--animation webp` |
+
+## 批量场景
+
+要批量生成(如 200 份证书、按订单出发票)时:写一个循环脚本,读数据(_CSV/JSON_),把每条数据填进同一份模板后循环调用 `render.mjs`。单张渲染约几十毫秒,200 份几秒完成;输出确定性意味着同一份数据永远得到同样的文件。
+
+## 环境要求与故障排查
+
+- Node.js >= 20.19。
+- 首次运行自动 `npm install`(安装进 scripts/ 目录),之后离线可用;若目标环境完全断网,需在有网环境预装后再拷贝,或提前执行一次安装。
+- 中文/Emoji 显示为方块(豆腐块):容器缺字体。安装 `font-noto-cjk`(Alpine)或 `fonts-noto-cjk`(Debian)后重跑;或用 `--font` 指定字体文件。详见 `@references/syntax-guide.md`。
+- Emoji 默认经 Twemoji CDN 在线获取;完全离线的环境让模板保持纯文本。
+- 渲染报错信息以 `Error` 开头输出在 stderr,按提示修正模板后重试。

package/skills/code2media/references/syntax-guide.md

@@ -0,0 +1,63 @@
+# HTML 模板语法指南
+
+渲染引擎是 Takumi(Rust 排版引擎的 Node 绑定):解析 HTML 片段 → taffy 布局(Flexbox/Grid/block/float)→ 文字排版(含中日韩、RTL、emoji)→ 合成输出。本指南只列**容易踩坑的规则**,完整 CSS 支持范围以引擎能力为准。
+
+## 1. 样式的三条通路
+
+| 方式 | 写法 | 说明 |
+| :--- | :--- | :--- |
+| `tw` 属性 | `<div tw="w-full h-full bg-blue-500">` | **Tailwind v4 工具类的唯一入口** |
+| 内联 style | `<div style="font-size:32px;color:#fff">` | 标准 CSS,最直接 |
+| `<style>` 块 | `<style>.card{background:#0ea5e9}</style>` + `class="card"` | 常规 CSS 选择器,支持 `:is()`、`::before` 等 |
+
+**关键陷阱**:
+- Tailwind 工具类放在 `class` 属性里**不会编译**——整块样式静默失效(背景全透明)。工具类永远写 `tw`。
+- `class` 属性的用途是配合 `<style>` 块里的普通选择器。
+
+## 2. Tailwind v4 命名
+
+用 v4 规范名,v3 旧名不识别:
+- 渐变:`bg-linear-to-br`(不是 `bg-gradient-to-br`)+ `from-blue-600 to-indigo-900`
+- 透明度修饰符可用:`bg-white/10`、`bg-blue-500/20`
+- 常用:`w-full h-full flex flex-col items-center justify-center gap-4 p-16 rounded-2xl rounded-full text-6xl font-bold leading-tight tracking-widest mt-10 space-y-2`
+- 任意值:`text-[10px]`、`w-[220px]`
+
+## 3. 布局要点
+
+- 根元素必须撑满画布:`tw="w-full h-full"`,否则内容按自身高度渲染。
+- 布局引擎:Flexbox、CSS Grid、block、inline、float、`calc()`、绝对定位、z-index 均支持。
+- `w-14 h-14 w-36 text-6xl` 等标准尺寸刻度可用;复杂尺寸用任意值或内联 style。
+
+## 4. 字体
+
+引擎内置仅一个拉丁兜底字体;**中日韩、Emoji 必须注册字体**。渲染脚本自动探测常见系统字体(Windows: msyh/simhei/arial/seguiemj;macOS: PingFang/Hiragino;Linux: Noto CJK/WQY + Noto Emoji),注册后的字体族名 = 文件名去扩展名(如 `msyh`、`NotoSansCJK-Regular`)。
+
+- 模板里跨平台建议写字体栈:`style="font-family:msyh,NotoSansCJK-Regular,NotoSansCJKsc-Regular,wqy-zenhei"`
+- 不指定时使用注册顺序作为回退链,注册了 CJK 字体就能显示中文。
+- 容器缺字体 → 中文显示方块:Alpine `apk add font-noto-cjk font-noto-emoji`;Debian `apt-get install fonts-noto-cjk fonts-noto-color-emoji`。或 `--font /路径/字体.ttf` 显式注册。
+- Emoji 默认走 Twemoji CDN 在线取图(需网络);离线环境模板写纯文本。
+- 等宽/代码:`font-family:monospace` 若未注册对应字体,回退到内置拉丁字体。
+
+## 5. 不支持 / 受限
+
+- **不执行 JavaScript**——图表用纯 `div` 条形图拼,数据直接写进 HTML。
+- CSS 是 Chrome 的子集:`backdrop-filter`、blend modes 支持于图片模式;**PDF 模式不支持** `filter: blur()`、`drop-shadow()`、`backdrop-filter`。
+- 远程图片(`<img src="https://...">`)需要网络;离线场景把图片以本地文件方式避开或不用图。
+- PDF 模式不支持 CSS `@page` 规则——页面尺寸/边距用命令行参数(`--size`、`--landscape`)控制。
+
+## 6. PDF 分页
+
+- 内容超过一页自动分页;`break-before:page`、`break-after:page`、`break-inside:avoid` 控制断点(表格行建议 `break-inside:avoid`)。
+- `<thead>` 跨页自动重复;孤行寡行默认保护。
+- 页眉页脚用 `--header` / `--footer` 参数传入 HTML 片段,内部可用 `<span class="pageNumber"></span>`、`<span class="totalPages"></span>` 注入页码计数(可加 `cjk-decimal` 等计数样式类)。
+- `--title` 写入 PDF 元数据;`--outline` 从 h1-h6 生成书签。
+
+## 7. 动画
+
+- 在 `<style>` 里写 `@keyframes`,元素上加 `animation: 名称 时长 linear infinite`。
+- 脚本对整个场景按 `--fps` 采样 `--duration` 毫秒,输出动画 WebP/GIF/APNG。
+- 变换(rotate/scale/translate)、透明度渐变均可采样;两个以上元素错开 `delay` 能做出层次感(参考 `templates/animation.html`)。
+
+## 8. 确定性与批量
+
+相同输入(模板+参数+字体)永远产出字节一致的文件。批量生成时:循环读数据 → 数据填入模板 → 调 `render.mjs` → 输出按数据键命名。单张几十毫秒,失败重跑零成本。

package/skills/code2media/scripts/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "code2media-scripts",
+  "private": true,
+  "type": "module",
+  "description": "Renderer dependencies for the code2media skill (installed automatically on first run).",
+  "dependencies": {
+    "takumi-js": "^2.13.5",
+    "takumi-pdf": "^0.14.1"
+  }
+}