Takumi 配置与能力¶

Takumi 在进程内执行 Rust 原生排版，不启动浏览器，不执行 JavaScript，也不访问网络。

安装与选择¶

uv add "entari-plugin-htmlrender[takumi]>=0.1.0,<0.2"

plugins:
  htmlrender:
    provider: takumi
    startup: probe
    provider_config:
      max_concurrency: 4

配置¶

下表字段均位于 provider_config：

完整路径	默认值	说明
`provider_config.load_default_fonts`	`true`	加载 Takumi 默认字体
`provider_config.fonts`	`[]`	启动时注册的字体
`provider_config.font_cache_policy`	`revalidate`	默认字体文件 cache policy
`provider_config.max_concurrency`	`min(cpu_count, 4)`	native 调用并发上限，1–64
`provider_config.compiled_cache_max_entries`	`128`	compiled LRU 条目上限
`provider_config.compiled_cache_max_source_bytes`	`33554432`	compiled cache 的模板 source UTF-8 字节预算（非 native 常驻内存）；条目数量硬上限仍由 `compiled_cache_max_entries` 提供
`provider_config.html_options.presets`	`chromium`	`chromium` 或 `none`
`provider_config.html_options.tailwind_property`	`null`	Tailwind 属性名
`provider_config.html_options.max_depth`	`null`	parser 最大深度
`provider_config.default_lang`	`null`	默认语言
`provider_config.font_families`	`[]`	字体回退顺序

fonts 中每个条目的字段如下；未知字段会被拒绝：

字段	默认值	约束
`path`	必填	非空字体文件路径
`name`	`null`	注册后的字体族名称
`weight`	`null`	`1`–`1000`
`style`	`null`	字体 style
`subset_of`	`null`	作为指定字体族的子集注册
`generic_family`	`null`	CSS generic family，如 `sans-serif`、`serif`、`monospace`、`emoji`
`cache_policy`	`null`	`immutable` / `revalidate`；为空时继承 `font_cache_policy`

字体示例：

plugins:
  htmlrender:
    provider: takumi
    resources:
      local_access:
        allowed_paths: [/app/fonts]
    provider_config:
      load_default_fonts: false
      fonts:
        - path: /app/fonts/NotoSansSC-Regular.otf
          name: Noto Sans SC
          generic_family: sans-serif
          cache_policy: immutable
      font_families: [Noto Sans SC, sans-serif]

只有随镜像不可变的字体才应使用 immutable。运行中的 native renderer不会热替换已注册字体；文件变化后需重建 composition。字体路径同样受resources.local_access.allowed_paths 约束。

缓存使用与诊断¶

Takumi runtime 对重复的 HTML/CSS native 编译使用有界 singleflight LRU。compiled_cache_max_source_bytes 的单位是输入 source 的 UTF-8 bytes，不是 native heap；调优时必须同时观察条目上限。

from entari_plugin_htmlrender.capabilities import TakumiCapability

async def cache_stats(takumi: TakumiCapability) -> tuple[int, int, int]:
    async with takumi.lease_session() as session:
        await session.render_svg_html("<strong>cached</strong>", width=320)
        stats = session.compiled_cache_stats
        return stats.hits, stats.misses, stats.evictions

统计是当前 runtime 的只读快照。公共 API 不提供 compiled cache clear；需要释放 native compiled object 或替换已注册字体时，由 Entari 关闭并重新加载 service。字体 revalidate、native image cache 与完整调优流程见缓存组件与调优。

能力边界¶

Takumi 支持静态 HTML、文本、模板和大多数 Markdown；下列需求会明确失败：

JavaScript、远程网络资源和页面导航；
无法在 Preparation 阶段物化的 @import、字体或图片；
Provider 无法表达的 conditional stylesheet；
浏览器页面、User-Agent、header 与 selector 操作。

PreparedAsset 直接把 bytes 交给 native renderer，不创建临时文件。

平台约束¶

项目当前锁定的 takumi-py==0.2.0 提供 macOS 11+ ARM64、manylinux 2.17+ x86-64/AArch64 和 Windows x86-64 wheel。Linux wheel 只链接 glibc、libgcc 等 manylinux 基线运行库，不需要 EGL、OpenGL、Cairo 或 Fontconfig 动态库；Alpine/musl、macOS x86-64、Windows ARM64 等没有匹配 wheel 的平台会尝试源码构建，需要 Rust、maturin 与相应 native toolchain。上游仍将 API 和 wheel target 标记为 testing stage，升级锁定版本时应重新核对发布文件。

Takumi 自带的 Latin fallback 不能覆盖业务所需字符集。需要中文或其他脚本时，应通过 provider_config.fonts 把字体随部署交付；这属于内容资源，不是系统动态库依赖。

typed Capability¶

SVG 与动态字体注册是 Takumi 专属 managed capability：

from entari_plugin_htmlrender.capabilities import TakumiCapability

async def render_svg(takumi: TakumiCapability) -> str:
    async with takumi.lease_session() as session:
        return await session.render_svg_html("<strong>Hello</strong>", width=320)

lease_session() 绑定并持有当前有效 lease。调用方不得让 session 逃逸出上下文，也不应保存为进程级单例；已返回的 bytes、SVG 字符串与 cache stats snapshot 不受该限制。

需要尚未进入稳定 API 的上游能力时，可通过 lease_native_renderer() 显式租用native renderer。该入口返回 object，调用方自行恢复上游 typing，并承担同步执行、并发、native panic、资源归一化与底层错误语义；详见Capability 参考。

选择建议¶

需要脚本、网页导航或浏览器布局语义时选择 Playwright；内容完全受控、希望避免浏览器进程，或需要 Takumi SVG/字体/native 能力时选择 Takumi。

启用或再分发 Takumi 前，请自行检查 takumi-py 当前版本的许可与平台 wheel；这里不构成法律意见。