takumi

Takumi

在工作涉及 Takumi / takumi-js 时使用此技能：无需 Chromium 即可将 JSX、HTML 或节点树渲染为 PNG/JPEG/WebP/ICO/SVG/动画；ImageResponse OG 路由；字体/图片/表情符号；Tailwind tw 与编译后的 css；WASM 打包；或从 next/og / Satori / v1 迁移。

快照：[email protected]，以及匹配的 @takumi-rs/core、@takumi-rs/wasm、@takumi-rs/helpers、@takumi-rs/image-response（于 2026-09-15 发布；截至 2026-10-01 仍是 npm latest）。配套的 PDF 包是 [email protected]。如果版本不同，请根据 source-map.md 刷新信息。

工作流

1. 修改代码前，先检查本地情况：
   • 包：takumi-js（首选一体化包），也可使用 @takumi-rs/core、@takumi-rs/wasm、@takumi-rs/helpers。
   • 版本：目标版本为 v2.14。将 v1 API（loadFonts、fetchedResources、createImageResponse）视为旧版 API。stylesheets 和 keyframes 渲染选项已弃用（将在 v3 中移除）——请使用 css。
   • 运行时：Node/Bun 原生环境，或 Edge / Cloudflare Workers / 浏览器 WASM。takumi-js 会自动选择；takumi-js 和 @takumi-rs/wasm 要求 Node >=20.19。交叉编译部署时，请固定平台原生包的版本。
   • 入口：使用 render / renderSvg / renderAnimation，或使用 takumi-js/response 中的 ImageResponse。使用 takumi-js/node 或 takumi-js/wasm 强制指定后端。浏览器包：takumi-js/wasm/no-init + takumi-js/wasm-url。
   • 样式路径：内联 style、内置 tw、<style>，或 css（字符串、列表或规则对象）。
2. 用户询问最新行为、无法确定已安装的版本，或工作涉及 css / WASM 打包 / 动画时，请刷新文档。请从 source-map.md 开始。
3. 安装、包、render / ImageResponse、输入、缓存和画布尺寸，请参考 setup-core.md。
4. 字体、图片、表情符号、tw、css、表格和列表，请参考 fonts-images-styling.md。
5. 格式、DPR、SVG、动画以及原始帧/ffmpeg 帧，请参考 formats-animation.md。
6. Next.js、TanStack Start、Workers、Nitro、WASM 打包工具及其他宿主环境，请参考 frameworks.md。
7. v1→v2、2.5→2.14 的差异、Satori/next/og 迁移和故障排除，请参考 pitfalls-migration.md。
8. 命令示例优先使用 bun / bunx。切勿将 Fumadocs 注解（[!code --]、[!code highlight]）复制到生成的代码中。

判断

• 默认使用 render(node, options) 或 new ImageResponse(node, options)。只有在多次渲染时需要复用字体／图像缓存，才使用 takumi-js/node（或 @takumi-rs/core）中的 Renderer。
• 始终对 render、renderSvg 和 renderAnimation（以及 napi/WASM Renderer 方法）使用 await。
• 在根节点上设置 w-full h-full（或 width／height: 100%）——仅设置画布大小不会拉伸根节点。
• 通过 fonts（数组或 Promise）按次传入字体。内置后备字体为 Geist Latin，字重为 300–800。其他字体（CJK、自定义品牌字体）都要注册。通用字体 sans-serif 会解析为已注册的字体系列，而不是内置字体。优先使用 takumi-js/helpers 中的 googleFonts；字重范围／axes 可加载可变字体。使用 generic: "monospace"（等）可使 font-mono 正确解析。
• 优先使用 css，而非已弃用的 stylesheets。可传入编译后的 Tailwind、Tailwind v4 源码（@theme、@import "tailwindcss"、@apply），或规则对象 { selector, style }。不要同时传入 css 和 stylesheets。
• tw 是内置的 Tailwind 子集。除非 css 包含 @import "tailwindcss"，否则不会包含 Preflight。未分层的样式表规则优先于实用类；! 可反转此优先级。:root／@theme 上的令牌会驱动实用类（--color-brand-500 → bg-brand-500）。
• 裸 <div> 的样式为 display: block（CSS），而非 flex——与 Satori 不同。旧模板中显式设置的 display: flex 仍然有效。
• 如果用户输入可能影响远程 src／背景 URL，请设置 images.allowUrl（SSRF）。不要跨信任边界共享 fetchCache。默认抓取超时时间为 30s（不是 5s）。
• 在 Node/Bun 上进行多线程渲染时，优先使用原生 takumi-js/node；WASM 为单线程。浏览器／webpack/Turbopack：使用 wasm/no-init + wasm-url，不要使用 Vite 的 ?url 入口。
• 可直接替换 next/og：将导入改为 takumi-js/response。除非项目出于 Takumi 以外的原因已依赖 Chromium／Satori+sharp 流程，否则不要使用这些流程。
• 发票／报告：使用 takumi-pdf，而非 takumi-js。

验证

优先使用仓库现有的检查。对于有实际意义的 Takumi 工作，请包含相关的检查：

• 对路由处理程序／渲染脚本进行类型检查（ImageResponse、RenderOptions、css）。
• 对一张静态 OG 图（1200×630）进行冒烟渲染，并打开生成的字节数据（或访问路由）。
• 确认根节点填满画布；布局异常时使用 drawDebugBorder: true。
• 对于 CJK／自定义字体，确认已设置 fonts／googleFonts，且没有豆腐字形。
• 部署时：确认存在适用于目标 OS／架构的原生绑定（或 Workers 上的 WASM 路径）。takumi-js／WASM 要求 Node 20.19+。
• 从 v1 升级到 v2 后：重新检查 await、fonts／images 选项，以及 new ImageResponse(jsx, opts)。
• 从 2.5 升级到 2.14 后：重新检查 css（不能只检查 stylesheets）、抓取超时时间、64 MiB／64 MP 限制，以及 WASM 打包器入口。