autoclaw 1.3.4 → 1.3.6

package/skills/code2media/scripts/render.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// HTML -> image / SVG / paged PDF / animation, powered by Takumi (no browser).
+// Self-contained CLI for agent skills: auto-installs takumi-js/takumi-pdf on
+// first run, renders an HTML fragment file to the requested output format.
+//
+// Usage:
+//   node render.mjs --html card.html -o card.png --width 1200 --height 630
+//   node render.mjs --html badge.html -o badge.svg
+//   node render.mjs --html invoice.html --pdf -o invoice.pdf [--size a4] [--title "t"] [--footer '<div>...</div>']
+//   node render.mjs --html anim.html --animation webp -o anim.webp [--fps 30] [--duration 1200]
+//   node render.mjs --html card.html -o card.png --font /path/Font.ttf [--font ...] | --no-fonts
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const MIN_NODE = 20;
+const nodeMajor = Number(process.versions.node.split('.')[0]);
+if (nodeMajor < MIN_NODE) {
+  console.error(`Error: Node.js >= ${MIN_NODE}.19 required, found ${process.versions.node}.`);
+  process.exit(1);
+}
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(path.join(SCRIPT_DIR, 'package.json'));
+
+function ensureDependencies() {
+  try {
+    require.resolve('takumi-js');
+    require.resolve('takumi-pdf');
+    return;
+  } catch { /* fall through to install */ }
+  console.error('First run: installing takumi-js and takumi-pdf (one-time, needs network)...');
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  execFileSync(npm, ['install', '--no-fund', '--no-audit', 'takumi-js', 'takumi-pdf'], {
+    cwd: SCRIPT_DIR, stdio: 'inherit', shell: process.platform === 'win32'
+  });
+  // Re-check after install so failures surface as a clear error.
+  try {
+    require.resolve('takumi-js');
+    require.resolve('takumi-pdf');
+  } catch {
+    error('dependency install finished but takumi-js/takumi-pdf still not resolvable; check network / npm registry access.');
+  }
+}
+ensureDependencies();
+
+const { render, renderSvg, renderAnimation } = await import('takumi-js');
+const { render: renderPdf } = await import('takumi-pdf');
+
+// ---- args ----
+const args = process.argv.slice(2);
+const ALIASES = { output: ['o'] };
+function opt(name) {
+  for (const key of [name, ...(ALIASES[name] || [])]) {
+    const token = key.length === 1 ? `-${key}` : `--${key}`;
+    const i = args.indexOf(token);
+    if (i !== -1) return args[i + 1];
+  }
+  return undefined;
+}
+function flag(name) {
+  return args.includes(`--${name}`);
+}
+function error(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+const htmlFile = opt('html');
+const output = opt('output');
+if (!htmlFile) error("'--html <file>' is required (an HTML fragment file to render).");
+if (!output) error("'-o/--output <file>' is required.");
+const template = fs.readFileSync(htmlFile, 'utf-8');
+if (!template.trim()) error(`${htmlFile} is empty.`);
+
+const cssFile = opt('css');
+const css = cssFile ? fs.readFileSync(cssFile, 'utf-8') : undefined;
+
+// ---- fonts: auto-detect common system fonts unless --no-fonts / --font given ----
+const COMMON_FONT_PATHS = [
+  '/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',
+  '/usr/share/fonts/noto/NotoColorEmoji.ttf',
+  '/usr/share/fonts/truetype/noto/NotoColorEmoji.ttf',
+  '/usr/share/fonts/google-noto-emoji/NotoColorEmoji.ttf',
+  'C:\\Windows\\Fonts\\msyh.ttc',
+  'C:\\Windows\\Fonts\\simhei.ttf',
+  'C:\\Windows\\Fonts\\arial.ttf',
+  'C:\\Windows\\Fonts\\seguiemj.ttf',
+  '/System/Library/Fonts/PingFang.ttc',
+  '/System/Library/Fonts/Hiragino Sans GB.ttc',
+  '/System/Library/Fonts/Helvetica.ttc',
+  '/System/Library/Fonts/Apple Color Emoji.ttc',
+];
+
+function resolveFonts() {
+  if (flag('no-fonts')) return [];
+  const fontOpts = args.flatMap((a, i) => (a === '--font' ? [args[i + 1]] : []));
+  const paths = fontOpts.length > 0 ? fontOpts : COMMON_FONT_PATHS.filter(p => fs.existsSync(p));
+  const fonts = [];
+  for (const p of paths) {
+    try {
+      fonts.push({ name: path.basename(p).replace(/\.(ttf|otf|ttc|woff2?)$/i, ''), data: fs.readFileSync(p) });
+    } catch { /* skip unreadable */ }
+  }
+  return fonts;
+}
+const fonts = resolveFonts();
+
+const width = Number(opt('width')) || 1200;
+const height = Number(opt('height')) || 630;
+const quality = opt('quality') ? Number(opt('quality')) : undefined;
+
+try {
+  fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+
+  // ---- PDF mode ----
+  if (flag('pdf')) {
+    const options = { size: (opt('size') || 'a4').toLowerCase(), fonts };
+    if (css) options.css = css;
+    if (flag('landscape')) options.landscape = true;
+    if (opt('title')) options.metadata = { title: opt('title') };
+    if (opt('footer')) options.footer = opt('footer');
+    if (opt('header')) options.header = opt('header');
+    if (flag('outline')) options.outline = true;
+    const VALID_SIZES = ['a3', 'a4', 'a5', 'b4', 'b5', 'letter', 'legal', 'ledger'];
+    if (!VALID_SIZES.includes(options.size)) {
+      error(`invalid page size '${options.size}'. Supported: ${VALID_SIZES.join(', ')}.`);
+    }
+    const bytes = await renderPdf(template, options);
+    fs.writeFileSync(output, Buffer.from(bytes));
+    console.log(`OK PDF ${bytes.length} bytes -> ${output}`);
+    process.exit(0);
+  }
+
+  // ---- animation mode ----
+  const animFormat = opt('animation');
+  if (animFormat) {
+    const VALID_ANIM = ['webp', 'gif', 'apng'];
+    const fmt = animFormat.toLowerCase();
+    if (!VALID_ANIM.includes(fmt)) error(`invalid animation format '${animFormat}'. Supported: ${VALID_ANIM.join(', ')}.`);
+    const bytes = await renderAnimation({
+      width, height,
+      fps: Number(opt('fps')) || 30,
+      format: fmt,
+      scenes: [{ node: template, durationMs: Number(opt('duration')) || 1000 }],
+      fonts, ...(css ? { css } : {})
+    });
+    fs.writeFileSync(output, Buffer.from(bytes));
+    console.log(`OK animation ${fmt.toUpperCase()} ${bytes.length} bytes -> ${output}`);
+    process.exit(0);
+  }
+
+  // ---- static image / SVG mode ----
+  const format = (opt('format') || path.extname(output).replace('.', '') || 'png').toLowerCase();
+  if (format === 'svg') {
+    const svg = await renderSvg(template, { width, height, fonts, ...(css ? { css } : {}) });
+    fs.writeFileSync(output, svg, 'utf-8');
+    console.log(`OK SVG ${Buffer.byteLength(svg)} bytes -> ${output}`);
+  } else {
+    const VALID = ['png', 'jpeg', 'webp'];
+    if (!VALID.includes(format)) error(`invalid format '${format}'. Supported: png, jpeg, webp, svg (or use --pdf / --animation).`);
+    const options = { width, height, format, fonts, ...(css ? { css } : {}) };
+    if (quality != null && (format === 'jpeg' || format === 'webp')) options.quality = quality;
+    const bytes = await render(template, options);
+    fs.writeFileSync(output, Buffer.from(bytes));
+    console.log(`OK ${format.toUpperCase()} ${width}x${height} ${bytes.length} bytes -> ${output}`);
+  }
+} catch (err) {
+  console.error(`Error rendering: ${err?.message || err}`);
+  process.exit(1);
+}

package/skills/code2media/templates/animation.html

@@ -0,0 +1,19 @@
+<style>
+  @keyframes pulse-ring {
+    0%   { transform: scale(0.55); opacity: 0.9; }
+    100% { transform: scale(1.5);  opacity: 0; }
+  }
+  @keyframes spin { to { transform: rotate(360deg); } }
+  @keyframes breathe {
+    0%, 100% { transform: scale(1); }
+    50%      { transform: scale(1.12); }
+  }
+</style>
+<div tw="w-full h-full flex items-center justify-center bg-slate-900">
+  <div style="position:absolute;width:200px;height:200px;border-radius:9999px;background:#3b82f6;animation:pulse-ring 1.2s linear infinite"></div>
+  <div style="position:absolute;width:200px;height:200px;border-radius:9999px;background:#3b82f6;animation:pulse-ring 1.2s linear infinite 0.6s"></div>
+  <div tw="w-36 h-36 rounded-3xl bg-linear-to-br from-blue-500 to-indigo-600 flex items-center justify-center" style="animation:breathe 1.2s ease-in-out infinite">
+    <span tw="text-6xl font-bold text-white" style="font-family:arial">A</span>
+  </div>
+  <div style="position:absolute;margin-top:220px;width:0;height:0;border-left:18px solid transparent;border-right:18px solid transparent;border-bottom:30px solid #f59e0b;animation:spin 2s linear infinite"></div>
+</div>

package/skills/code2media/templates/badge.html

@@ -0,0 +1,6 @@
+<div tw="w-full h-full flex items-center justify-center bg-transparent">
+  <div tw="flex items-center gap-3 rounded-full px-10 py-5" style="background:#1e293b;border:2px solid #3b82f6">
+    <span tw="text-3xl font-bold text-white" style="font-family:arial">render_pdf</span>
+    <span tw="text-3xl font-bold px-4 rounded-full" style="background:#2563eb;color:#fff">new</span>
+  </div>
+</div>

package/skills/code2media/templates/certificate.html

@@ -0,0 +1,9 @@
+<div tw="w-full h-full flex flex-col items-center justify-center bg-linear-to-b from-amber-50 to-white" style="font-family:msyh,NotoSansCJK-Regular,NotoSansCJKsc-Regular,wqy-zenhei;border:16px solid #d4af37">
+  <p tw="text-3xl tracking-widest text-amber-700">C E R T I F I C A T E</p>
+  <h1 tw="text-6xl font-bold text-slate-800 mt-10">张伟</h1>
+  <p tw="text-2xl text-slate-500 mt-8">完成《AutoClaw 大规模自动化实战》课程</p>
+  <div tw="flex items-center gap-16 mt-16 text-lg text-slate-400">
+    <span>证书编号: AC-2026-0001</span>
+    <span>签发日期: 2026-09-03</span>
+  </div>
+</div>

package/skills/code2media/templates/metrics-card.html

@@ -0,0 +1,25 @@
+<div tw="w-full h-full bg-white p-12 flex flex-col" style="font-family:msyh,NotoSansCJK-Regular,NotoSansCJKsc-Regular,wqy-zenhei">
+  <div tw="flex justify-between items-center">
+    <h1 tw="text-4xl font-bold text-slate-800">自动化周报</h1>
+    <span tw="text-xl text-slate-400">2026-09-01 ~ 09-07</span>
+  </div>
+  <div tw="flex gap-6 mt-10 flex-1">
+    <div tw="flex-1 rounded-2xl bg-blue-50 text-blue-600 p-8 flex flex-col justify-center">
+      <span tw="text-2xl opacity-70">任务总数</span>
+      <span tw="text-6xl font-bold mt-3">1,284</span>
+    </div>
+    <div tw="flex-1 rounded-2xl bg-emerald-50 text-emerald-600 p-8 flex flex-col justify-center">
+      <span tw="text-2xl opacity-70">成功率</span>
+      <span tw="text-6xl font-bold mt-3">99.2%</span>
+    </div>
+    <div tw="flex-1 rounded-2xl bg-amber-50 text-amber-600 p-8 flex flex-col justify-center">
+      <span tw="text-2xl opacity-70">平均耗时</span>
+      <span tw="text-6xl font-bold mt-3">3.4s</span>
+    </div>
+    <div tw="flex-1 rounded-2xl bg-purple-50 text-purple-600 p-8 flex flex-col justify-center">
+      <span tw="text-2xl opacity-70">节省工时</span>
+      <span tw="text-6xl font-bold mt-3">217h</span>
+    </div>
+  </div>
+  <p tw="text-lg text-slate-400 mt-8">Generated by AutoClaw · deterministic render, no AI involved</p>
+</div>

package/skills/code2media/templates/weekly-report.html

@@ -0,0 +1,86 @@
+<div tw="w-full h-full flex flex-col p-10" style="font-family:msyh,NotoSansCJK-Regular,NotoSansCJKsc-Regular,wqy-zenhei">
+  <div tw="flex justify-between items-center">
+    <div>
+      <h1 tw="text-3xl font-bold text-slate-900">服务流量周报</h1>
+      <p tw="text-sm text-slate-400 mt-1">2026-08-31 ~ 2026-09-06 · 自动生成于每周一 09:00</p>
+    </div>
+    <span tw="px-4 py-1.5 rounded-full bg-emerald-50 text-emerald-600 text-sm font-semibold">全部指标正常</span>
+  </div>
+
+  <div tw="flex gap-4 mt-6">
+    <div tw="flex-1 rounded-xl bg-slate-50 p-4">
+      <p tw="text-xs text-slate-400">总请求</p>
+      <p tw="text-2xl font-bold text-slate-800 mt-1">2,417,393</p>
+      <p tw="text-xs text-emerald-600 mt-1">▲ 8.2% 环比</p>
+    </div>
+    <div tw="flex-1 rounded-xl bg-slate-50 p-4">
+      <p tw="text-xs text-slate-400">平均延迟</p>
+      <p tw="text-2xl font-bold text-slate-800 mt-1">86ms</p>
+      <p tw="text-xs text-emerald-600 mt-1">▼ 12ms 环比</p>
+    </div>
+    <div tw="flex-1 rounded-xl bg-slate-50 p-4">
+      <p tw="text-xs text-slate-400">错误率</p>
+      <p tw="text-2xl font-bold text-slate-800 mt-1">0.03%</p>
+      <p tw="text-xs text-slate-400 mt-1">持平</p>
+    </div>
+    <div tw="flex-1 rounded-xl bg-slate-50 p-4">
+      <p tw="text-xs text-slate-400">可用性</p>
+      <p tw="text-2xl font-bold text-slate-800 mt-1">99.99%</p>
+      <p tw="text-xs text-emerald-600 mt-1">目标 99.9%</p>
+    </div>
+  </div>
+
+  <div tw="mt-6">
+    <h2 tw="text-lg font-bold text-slate-800">每日请求量(万次)</h2>
+    <div tw="flex items-end gap-3 mt-4" style="height:180px">
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">286</span>
+        <div tw="w-full rounded-t-lg bg-blue-500" style="height:52%"></div>
+        <span tw="text-xs text-slate-500">周一</span>
+      </div>
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">312</span>
+        <div tw="w-full rounded-t-lg bg-blue-500" style="height:58%"></div>
+        <span tw="text-xs text-slate-500">周二</span>
+      </div>
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">298</span>
+        <div tw="w-full rounded-t-lg bg-blue-500" style="height:55%"></div>
+        <span tw="text-xs text-slate-500">周三</span>
+      </div>
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">405</span>
+        <div tw="w-full rounded-t-lg bg-blue-600" style="height:76%"></div>
+        <span tw="text-xs text-slate-500">周四</span>
+      </div>
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">452</span>
+        <div tw="w-full rounded-t-lg bg-blue-600" style="height:85%"></div>
+        <span tw="text-xs text-slate-500">周五</span>
+      </div>
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">351</span>
+        <div tw="w-full rounded-t-lg bg-blue-400" style="height:65%"></div>
+        <span tw="text-xs text-slate-500">周六</span>
+      </div>
+      <div tw="flex-1 flex flex-col items-center gap-2">
+        <span tw="text-xs text-slate-400">313</span>
+        <div tw="w-full rounded-t-lg bg-blue-400" style="height:58%"></div>
+        <span tw="text-xs text-slate-500">周日</span>
+      </div>
+    </div>
+  </div>
+
+  <div tw="mt-6 flex gap-6">
+    <div tw="flex-1">
+      <h2 tw="text-lg font-bold text-slate-800">异常事件</h2>
+      <ul tw="mt-3 space-y-2 text-sm text-slate-600">
+        <li>· 周四 14:20 缓存集群扩容,耗时 6 分钟,无请求失败</li>
+        <li>· 周五 09:05 上游依赖抖动 3 分钟,错误率瞬时升至 0.4% 后恢复</li>
+      </ul>
+    </div>
+    <div tw="flex-1 rounded-xl bg-blue-50 p-5">
+      <p tw="text-sm text-blue-900 leading-relaxed"><b>结论:</b>流量随工作日稳步增长,峰值出现在周五;延迟与错误率均在预算内,下周继续观察周五早高峰容量水位。</p>
+    </div>
+  </div>
+</div>

package/skills/invoice-maker/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: invoice-maker
+display_name: 发票生成器（报价单/收据/采购单）
+display_name_en: Invoice Maker (quotes, receipts, purchase orders)
+description: Generate formal business documents as paged PDFs — invoices, quotes, purchase orders, receipts, statements — with proper tables, tax lines, page numbers and bilingual layouts. Use when the user wants to 开发票/生成发票/报价单/收据/采购单/对账单/账单/付款通知 or make an invoice/quote/receipt PDF.
+description_zh: 生成正式商务票据 PDF:发票、报价单、收据、采购单、对账单、账单。金额右对齐、税行规范、表格跨页表头重复、页码页脚,中英双语排版可选。离线毫秒级渲染,支持按订单数据批量出票。
+description_en: Generate formal business document PDFs — invoices, quotes, purchase orders, receipts, statements. Right-aligned amounts, tax lines, repeating table headers across pages, page-number footers, optional bilingual layouts. Offline, batch-ready.
+category: office
+version: 1.0.0
+author: AutoClaw
+---
+
+# 发票生成器
+
+把订单/交易数据变成正式的商务票据 PDF:发票、报价单、收据、采购单、对账单、账单。本技能沉淀了**票据的版式结构、金额规范和批量开票模式**,产出的 PDF 文字可选中、字体已内嵌,可直接邮件发送或归档。
+
+## 何时使用
+
+- 用户要"开/生成"一张正式单据:发票、报价单、收据、采购单、对账单、账单、付款通知
+- 从订单表(CSV/JSON)批量出票
+- 不适用:非票据类报告(运营周报等用 code2media);证书奖状(用 code2media 模板);艺术排版海报(用 poster-maker)
+
+## 版式结构(票据的骨架)
+
+```
+[抬头区]   公司名 + 单据类型/编号        日期/有效期/联系人(右对齐)
+[客户区]   致:客户名 + 一句话背景说明(浅底色块)
+[明细表]   # | 项目 | 规格说明 | 数量 | 单价 | 小计(表头浅灰底)
+[合计区]   小计 → 税 → 含税总计(右对齐,总计最大最粗)
+[条款区]   付款条款/有效期/免责,小号灰字,可中英双语
+```
+
+参考 `templates/`:`invoice.html`(采购订单,60 行明细跨页示例)、`quote.html`(报价单)。
+
+## 金额与排版规范(硬性)
+
+- **金额一律右对齐**,带千分位(`¥ 104,940.00`);数量/单价/小计列都用 `text-align:right`
+- **总计行最大最粗**,小计/税行用灰色小一号;税行单独列出,不和总计混算
+- 表格行加 `style="border-bottom:1px solid #e2e8f0"`,表头浅灰底 `background:#f1f5f9`
+- 表格行加 `break-inside:avoid` 防跨页劈行;`<thead>` 会跨页自动重复,明细多也不怕
+- 页脚固定放页码:`第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页`
+- 编号规则清晰可见(如 `QU-2026-0912`),日期用完整格式;中英双语条款便于跨境
+- 渲染命令:
+
+```bash
+node "<技能目录>/scripts/render.mjs" --html invoice.html --pdf -o invoice.pdf --size a4 \
+  --title "发票 INV-2026-0001" \
+  --footer '<div style="width:100%;text-align:center;font-size:10px;color:#94a3b8">第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页</div>'
+```
+
+## 批量开票(swarm 模式)
+
+按订单表出票:循环读每行数据 → 把 `templates/invoice.html` 的抬头/明细/合计替换成该订单 → 渲染为 `invoices/<订单号>.pdf`。单张约几十毫秒,千张订单分钟级完成;输出确定,重跑同数据得到同文件。列宽字段(公司名/品名)超长时截断或换行,不要溢出表格。
+
+## 交付前检查
+
+- [ ] 总计 = 明细之和(含税计算正确,税率单列)
+- [ ] 单据编号、双方名称、日期完整
+- [ ] 明细超过一页时:第 2 页起表头是否重复、页码是否正确
+- [ ] 中文无豆腐块(容器需 `font-noto-cjk` 字体包,或 `--font` 指定)
+- [ ] PDF 文字可选中、可搜索(本技能默认满足)
+
+## 环境要求
+
+Node.js >= 20.19;首次运行自动安装 takumi-js/takumi-pdf(一次性,需网络)。非票据的自定义文档用 `code2media` 通用技能。

package/skills/invoice-maker/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/invoice-maker/scripts/package.json

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

package/skills/invoice-maker/scripts/render.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// HTML -> image / SVG / paged PDF / animation, powered by Takumi (no browser).
+// Self-contained CLI for agent skills: auto-installs takumi-js/takumi-pdf on
+// first run, renders an HTML fragment file to the requested output format.
+//
+// Usage:
+//   node render.mjs --html card.html -o card.png --width 1200 --height 630
+//   node render.mjs --html badge.html -o badge.svg
+//   node render.mjs --html invoice.html --pdf -o invoice.pdf [--size a4] [--title "t"] [--footer '<div>...</div>']
+//   node render.mjs --html anim.html --animation webp -o anim.webp [--fps 30] [--duration 1200]
+//   node render.mjs --html card.html -o card.png --font /path/Font.ttf [--font ...] | --no-fonts
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const MIN_NODE = 20;
+const nodeMajor = Number(process.versions.node.split('.')[0]);
+if (nodeMajor < MIN_NODE) {
+  console.error(`Error: Node.js >= ${MIN_NODE}.19 required, found ${process.versions.node}.`);
+  process.exit(1);
+}
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(path.join(SCRIPT_DIR, 'package.json'));
+
+function ensureDependencies() {
+  try {
+    require.resolve('takumi-js');
+    require.resolve('takumi-pdf');
+    return;
+  } catch { /* fall through to install */ }
+  console.error('First run: installing takumi-js and takumi-pdf (one-time, needs network)...');
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  execFileSync(npm, ['install', '--no-fund', '--no-audit', 'takumi-js', 'takumi-pdf'], {
+    cwd: SCRIPT_DIR, stdio: 'inherit', shell: process.platform === 'win32'
+  });
+  // Re-check after install so failures surface as a clear error.
+  try {
+    require.resolve('takumi-js');
+    require.resolve('takumi-pdf');
+  } catch {
+    error('dependency install finished but takumi-js/takumi-pdf still not resolvable; check network / npm registry access.');
+  }
+}
+ensureDependencies();
+
+const { render, renderSvg, renderAnimation } = await import('takumi-js');
+const { render: renderPdf } = await import('takumi-pdf');
+
+// ---- args ----
+const args = process.argv.slice(2);
+const ALIASES = { output: ['o'] };
+function opt(name) {
+  for (const key of [name, ...(ALIASES[name] || [])]) {
+    const token = key.length === 1 ? `-${key}` : `--${key}`;
+    const i = args.indexOf(token);
+    if (i !== -1) return args[i + 1];
+  }
+  return undefined;
+}
+function flag(name) {
+  return args.includes(`--${name}`);
+}
+function error(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+const htmlFile = opt('html');
+const output = opt('output');
+if (!htmlFile) error("'--html <file>' is required (an HTML fragment file to render).");
+if (!output) error("'-o/--output <file>' is required.");
+const template = fs.readFileSync(htmlFile, 'utf-8');
+if (!template.trim()) error(`${htmlFile} is empty.`);
+
+const cssFile = opt('css');
+const css = cssFile ? fs.readFileSync(cssFile, 'utf-8') : undefined;
+
+// ---- fonts: auto-detect common system fonts unless --no-fonts / --font given ----
+const COMMON_FONT_PATHS = [
+  '/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',
+  '/usr/share/fonts/noto/NotoColorEmoji.ttf',
+  '/usr/share/fonts/truetype/noto/NotoColorEmoji.ttf',
+  '/usr/share/fonts/google-noto-emoji/NotoColorEmoji.ttf',
+  'C:\\Windows\\Fonts\\msyh.ttc',
+  'C:\\Windows\\Fonts\\simhei.ttf',
+  'C:\\Windows\\Fonts\\arial.ttf',
+  'C:\\Windows\\Fonts\\seguiemj.ttf',
+  '/System/Library/Fonts/PingFang.ttc',
+  '/System/Library/Fonts/Hiragino Sans GB.ttc',
+  '/System/Library/Fonts/Helvetica.ttc',
+  '/System/Library/Fonts/Apple Color Emoji.ttc',
+];
+
+function resolveFonts() {
+  if (flag('no-fonts')) return [];
+  const fontOpts = args.flatMap((a, i) => (a === '--font' ? [args[i + 1]] : []));
+  const paths = fontOpts.length > 0 ? fontOpts : COMMON_FONT_PATHS.filter(p => fs.existsSync(p));
+  const fonts = [];
+  for (const p of paths) {
+    try {
+      fonts.push({ name: path.basename(p).replace(/\.(ttf|otf|ttc|woff2?)$/i, ''), data: fs.readFileSync(p) });
+    } catch { /* skip unreadable */ }
+  }
+  return fonts;
+}
+const fonts = resolveFonts();
+
+const width = Number(opt('width')) || 1200;
+const height = Number(opt('height')) || 630;
+const quality = opt('quality') ? Number(opt('quality')) : undefined;
+
+try {
+  fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+
+  // ---- PDF mode ----
+  if (flag('pdf')) {
+    const options = { size: (opt('size') || 'a4').toLowerCase(), fonts };
+    if (css) options.css = css;
+    if (flag('landscape')) options.landscape = true;
+    if (opt('title')) options.metadata = { title: opt('title') };
+    if (opt('footer')) options.footer = opt('footer');
+    if (opt('header')) options.header = opt('header');
+    if (flag('outline')) options.outline = true;
+    const VALID_SIZES = ['a3', 'a4', 'a5', 'b4', 'b5', 'letter', 'legal', 'ledger'];
+    if (!VALID_SIZES.includes(options.size)) {
+      error(`invalid page size '${options.size}'. Supported: ${VALID_SIZES.join(', ')}.`);
+    }
+    const bytes = await renderPdf(template, options);
+    fs.writeFileSync(output, Buffer.from(bytes));
+    console.log(`OK PDF ${bytes.length} bytes -> ${output}`);
+    process.exit(0);
+  }
+
+  // ---- animation mode ----
+  const animFormat = opt('animation');
+  if (animFormat) {
+    const VALID_ANIM = ['webp', 'gif', 'apng'];
+    const fmt = animFormat.toLowerCase();
+    if (!VALID_ANIM.includes(fmt)) error(`invalid animation format '${animFormat}'. Supported: ${VALID_ANIM.join(', ')}.`);
+    const bytes = await renderAnimation({
+      width, height,
+      fps: Number(opt('fps')) || 30,
+      format: fmt,
+      scenes: [{ node: template, durationMs: Number(opt('duration')) || 1000 }],
+      fonts, ...(css ? { css } : {})
+    });
+    fs.writeFileSync(output, Buffer.from(bytes));
+    console.log(`OK animation ${fmt.toUpperCase()} ${bytes.length} bytes -> ${output}`);
+    process.exit(0);
+  }
+
+  // ---- static image / SVG mode ----
+  const format = (opt('format') || path.extname(output).replace('.', '') || 'png').toLowerCase();
+  if (format === 'svg') {
+    const svg = await renderSvg(template, { width, height, fonts, ...(css ? { css } : {}) });
+    fs.writeFileSync(output, svg, 'utf-8');
+    console.log(`OK SVG ${Buffer.byteLength(svg)} bytes -> ${output}`);
+  } else {
+    const VALID = ['png', 'jpeg', 'webp'];
+    if (!VALID.includes(format)) error(`invalid format '${format}'. Supported: png, jpeg, webp, svg (or use --pdf / --animation).`);
+    const options = { width, height, format, fonts, ...(css ? { css } : {}) };
+    if (quality != null && (format === 'jpeg' || format === 'webp')) options.quality = quality;
+    const bytes = await render(template, options);
+    fs.writeFileSync(output, Buffer.from(bytes));
+    console.log(`OK ${format.toUpperCase()} ${width}x${height} ${bytes.length} bytes -> ${output}`);
+  }
+} catch (err) {
+  console.error(`Error rendering: ${err?.message || err}`);
+  process.exit(1);
+}