Fullbleed PDF Engine

Fullbleed PDF 引擎

使用可复用的 Python、JavaScript 和 C# 组件，或 HTML/CSS 构建 PDF。采用 MIT 许可。

使用确定性的 Rust 引擎构建发票、报告、对账单和可变数据印刷文件。可使用原生 Rust API、Python 包，或可选的 JavaScript 和 .NET 集成。Python wheel 包含引擎、字体和 CLI，无需第三方 Python 包或系统 PDF 工具链。JavaScript 包包含 WebAssembly 引擎和字体，可用于 Node.js 和浏览器 worker；.NET 包包含用于进程内渲染的原生库。

试用 PDF 组件 · 文档 · 示例 · PyPI · crates.io · npm · 发行说明 · MIT 许可

以上为 Fullbleed 的实际输出。点击任一预览即可查看 PDF，或浏览包含 HTML/CSS、数据和字体设置的设计示例。

比较这两种 HTML/CSS 和 Python 组件设计，页面输出一致，并提供可运行的源码下载（可选启用组件 alpha）。

使用 Python 组合文档

构建可复用的函数组件，支持属性、嵌套子元素、列表和条件内容。使用命名元素和 Python 风格的映射来编写：

from pathlib import Path
import fullbleed
from fullbleed.ui import Document, Heading, Paragraph, Stack, Strong, component

@component
def Line(label, amount):
    return Paragraph(Strong(label), ": ", amount)

@Document(title="Invoice", styles={"@page": {"size": "A4", "margin": "18mm"}})
def Invoice(customer):
    return Stack(
        Heading("Invoice for ", customer, level=1),
        Line("Design", "$120.00"),
        Line("Review", "$40.00"),
        gap="12pt",
    )

Path("invoice.pdf").write_bytes(Invoice("Maple & Finch").render_pdf(fullbleed.PdfEngine()))

此完整工作流已在 2.5.25 中推出。文本会进行转义，组件会编译到同一 HTML/CSS 打印引擎。请参阅组件编写指南，或运行设计好的组件发票示例，其中包含显式字体、可复用行、已付款/未付款状态和 PNG 预览。

可选启用的 Python 组件 alpha提供样式随组件封装、命名自定义部件、基于列的表格以及静态 Bootstrap 5.0.0 组件。可导出包含或移除样式的 HTML，也可将同一文档渲染为 PDF。指南介绍了 class_name，并提供可运行的工具包。此 API 仍处于实验阶段；请按照明确的预发布版本安装说明操作。

对于 JavaScript，可使用函数或 JSX/TSX 组合文档。React 入门指南将带类型的文档组件连接到可编辑数据、实时 PDF 预览和下载功能，并包含完整的组件与样式源码，供自定义使用。

试用 Python 组件 alpha 版

2.6.0a9 预发布版新增了可复用的页眉和页脚 PageBand，以及已确定的页码值 PageNumbers。在预留的页边距中使用普通组件，包括其样式和 class_name 选择器。此外，还提供可携带自身外观的组件、静态 Bootstrap 5.0.0 工具包，以及可选择是否包含样式的 HTML 导出功能。此 API 位于 fullbleed.ui.experimental 下；名称和行为可能会有所变化。请在虚拟环境中显式安装 alpha 版：

python -m pip install --pre "fullbleed==2.6.0a9"

将以下内容保存为 order.py，然后运行 python order.py：

from importlib.resources import files
from pathlib import Path
from fullbleed.ui.experimental import Document, Renderer, Theme, pt, style
from fullbleed.ui.experimental import bootstrap as bs

card = bs.Card(
    bs.Paragraph("Your order has passed its final inspection."),
    title="Ready to ship",
    header="ORDER / 1048",
    footer=bs.Badge("Approved", variant="success"),
).with_parts(title=style(color="#205b47"))

document = Document(card, title="Order summary", lang="en-US",
                    theme=Theme(text=style(font_family="Inter", font_size=pt(11))))
Path("order.html").write_text(document.to_html(include_styles=True), encoding="utf-8", newline="\n")
Path("order.unstyled.html").write_text(document.to_html(include_styles=False), encoding="utf-8", newline="\n")
renderer = Renderer(font_files=[str(files("fullbleed_assets").joinpath("fonts/Inter-Variable.ttf"))])
Path("order.pdf").write_bytes(document.render_pdf(renderer))

class_name 会添加字面类名；Bootstrap 组件会自带默认样式表。.with_style(...) 用于自定义根元素，.with_parts(...) 用于自定义已声明的内部元素。所有 Bootstrap 组件都是静态的，包括 HTML 导出；不会包含 Bootstrap JavaScript。

请继续阅读 Bootstrap 和样式指南、可复用组件指南，或报告和目录。alpha 版运行手册记录了发布门槛和限制。对于尚未发布的检出版本，请使用 python build_backend/fullbleed_build_backend.py wheel --out dist 构建 wheel，然后安装生成的路径。普通的 pip install fullbleed 会选择稳定版通道。

通过 Page(header=PageBand(...), footer=PageBand(...)) 添加页眉页脚和页码。Common Ground 实地笔记示例使用共享品牌组件、带样式的页码和跨三页的表格。此 API 支持按记录编号、隐藏首页页码以及设置空白页策略。适配诊断会指出无法证明其始终处于预留页边距内的内容。HTML 导出使用一个页眉和一个页脚，并带有显式的页面占位符。这些构造函数需要 a9；较早的 a8 wheel 不包含它们。

选择你的语言

语言	安装	开始构建
Python	python -m pip install fullbleed	Python 快速入门
Rust	cargo add fullbleed	原生 Rust 快速入门
Node.js / TypeScript	npm install fullbleed	Node 快速入门 · Next.js PDF 下载
浏览器 JavaScript	npm install --save-exact [email protected]	PDF 组件和 JSX · React 入门项目 · HTML/CSS 入门项目
C# / .NET	dotnet add package FullBleed.DotNet --version 0.2.0	C# 组件和样式 · NuGet 快速入门

当前 JavaScript 包为 0.7.1，封装了引擎 2.5.29，其中包括 导出带样式或不带样式的组件 HTML。 可下载的组件发票和 React 入门项目保留了经过测试的 0.6.0 版本锁定；HTML/CSS Node.js 快速入门以及 JavaScript、Vue 和 Next.js 入门项目使用 0.5.1。这些入门项目锁定的版本封装了引擎 2.5.24。它们都能生成标准 PDF 和预览。Node 中导入 fullbleed，Web 应用中导入 fullbleed/browser。Node 应用可以使用 有界渲染队列 以及可选的进程隔离。 FullBleed.DotNet 0.2.0 使用引擎 2.5.22。其托管库以 .NET 8 为目标，适用于 .NET 8、9 和 10 应用，并支持 C# 文档组件、原生渲染、已编译绑定和预览。其独立 CLI 适配器需要 Python CLI。 Python 包提供完整的 CLI，包括已编译的变量数据作业和印刷配置文件；Rust 指南介绍原生 API。

创建你的第一个 PDF

从 HTML/CSS 操场开始，编辑一份设计精美的发票或报告，并下载真实的 PDF。它在浏览器本地运行，无需账户或上传文档。你也可以使用 Colab 中的 Python 笔记本，或从本地脚本开始：

Python

适用于 Windows、macOS 或 Linux 上的 Python 3.10–3.14：

python -m pip install fullbleed

将此内容保存为 hello.py，然后运行 python hello.py：

from pathlib import Path
import fullbleed

html = "<h1>Invoice INV-1042</h1><p>Consulting: USD 1,200.00</p>"
css = "@page { size: A4; margin: 20mm; } h1 { color: #175c52; }"
pdf = fullbleed.PdfEngine().render_pdf(html, css)
Path("invoice.pdf").write_bytes(pdf)

打开 invoice.pdf。快速入门还介绍了字体、预览和完整项目。可运行的源代码位于 examples/quickstart/hello.py。

Node.js

使用 Node.js 22 或更高版本。运行 npm install fullbleed，将此内容保存为 invoice.mjs，然后运行 node invoice.mjs：

import { writeFile } from 'node:fs/promises';
import { renderPdf } from 'fullbleed';

const result = await renderPdf({
  html: '<h1>Invoice INV-1042</h1><p>Consulting: USD 1,200.00</p>',
  css: '@page { size: A4; margin: 20mm } h1 { color: #175c52 }',
  previewDpi: 96,
});
await writeFile('invoice.pdf', result.pdf);
await writeFile('invoice.png', result.previews[0]);

打开 invoice.pdf 或其 PNG 预览。Node.js 快速入门包含一个可下载的精美发票项目。独立的 Node 包支持 ESM、CommonJS 和 TypeScript。要创建应用路由，请使用 Next.js 入门项目。

浏览器 JavaScript

试用可编辑的浏览器应用，生成发票或报告，修改其 HTML/CSS，并下载 PDF。 渲染在本地 Web Worker 中运行；入门项目不会将文档输入上传到渲染服务。

如需基于它进行开发，下载完整项目。 解压 ZIP，在 fullbleed-browser-starter 中打开终端，并使用 Node.js 22.12 或更高版本运行开发工具：

npm ci
npm run dev

打开 Vite 输出的 localhost URL。浏览器指南 介绍如何将 fullbleed/browser 添加到现有应用、通过 HTTPS 或 localhost 提供其运行时资源、取消操作、自定义字体和静态部署。 此功能会渲染提供的静态 HTML/CSS；不会捕获实时浏览器页面。

Rust

从 Rust 原生快速入门开始。fullbleed crate 提供 FullBleed::builder() 和 render_to_buffer(...)，无需 Python。指南包含可运行的发票和报告示例，使用显式字体并提供 PNG 预览，还提供最新的托管 Rust API 参考。

C# 和 .NET

在 .NET 8、9 或 10 项目中安装 FullBleed.DotNet，并按照 C# 快速入门操作。使用常规方法、LINQ 子项和不可变样式对象组合文档。组件指南介绍 WithClass、附加样式表和内联覆盖，并包含一个使用显式字体的完整发票下载示例。仍支持现有的 HTML/CSS 模板。在 Windows x64、Linux x64、Intel macOS 和 Apple Silicon macOS 上，原生渲染会在 .NET 进程内运行，无需 Python 或浏览器运行时。

选择你的起点

你想构建	从这里开始
独具特色的发票、报告、通知和对账单	包含字体和源文件的设计展示
原生 Rust 应用	Rust 快速入门和可运行示例
Node.js 或 TypeScript 应用	Node 快速入门和设计精美的发票项目
在 Web 应用的浏览器中生成 PDF	浏览器工作线程 SDK、可编辑演示和完整项目
C# 或 .NET 应用	NuGet 快速入门和设计精美的发票
根据 JSON 生成发票	完整且经过检查的示例
编辑 HTML/CSS 时自动重新构建（2.5.0+）	监视模式发票示例
在拉取请求中捕获 PDF 变更	包含经过审核的基线和 CI 工作流的独立项目
在 FastAPI、Flask 或 Django 中提供 PDF 下载	可运行的 Web 应用示例
在 Laravel 中排队生成 PDF 发票	Blade 模板、重试和私有下载（PHP 和 Python）
从 Rust 和 Axum 返回 PDF 响应	包含请求限制和可编辑模板的发票端点
在 AWS Lambda 中生成 PDF	包含本地运行时检查的 Python 容器入门项目
在 n8n 工作流中添加 PDF 附件	Webhook 到 PDF 工作流和本地 Docker 工具包
根据 pandas DataFrame 生成格式精美的 PDF 报告	包含 CSV 数据和验证的分页报告
根据 CSV 生成格式精美的发票	Acme 发票项目
在同一个 PDF 中使用简体中文和英文	包含显式字体设置和字形检查的双语发票
跨页排版的报告	商业报告示例
通过无障碍检查的带标签输出	无障碍工作流
根据一个模板生成多份文档	固定版式和流式排版的可变数据示例
印刷配置文件和 PDF/VT 记录层级	印刷输出和验证范围
编码 Agent 或 MCP 集成	Agent 设置

查看生成的 PDF 及其源文件 →

为什么使用 Fullbleed？

• **部署简单：**为 15 种平台目标预构建 wheel；使用内置工作流时，无需安装浏览器或系统字体。
• **文档可重复生成：**使用显式资源和元数据、确定性渲染，以及 SHA-256 可重复性检查。
• **面向文档的布局：**支持分页、页眉和页脚、表格、模板叠加层以及逐页数据。
• **批量工作流：**编译一次模板，然后绑定固定或可重排的记录。已测工作负载和限制。
• **输出可检查：**提供 PDF 检查、PNG 预览、结构化诊断和配置文件验证工具。

对于未嵌入的 Standard 14 字体，原生预览会使用精简的内置轮廓替代字体，因此无需系统字体即可渲染基本的 Helvetica、Times、Courier、Symbol 和 Dingbats 文本。已注册和嵌入的字体程序优先使用。字体解析跟踪会标识 bundled_substitute 结果；运行时发现报告为 bundled_standard_font_previews。请参阅字体来源、许可证和覆盖范围限制。

Fullbleed 使用静态 HTML/CSS 作为文档布局语言。请查看模板的 CSS 覆盖范围和未实现部分。如果所需结果依赖 JavaScript 或网站实时行为，请使用浏览器。

仅选择配置文件并不能证明符合标准。发布证据记录了执行的检查及其限制。

获取帮助并参与贡献

欢迎在 Discussions中提问使用问题并分享文档。如果遇到可复现的错误或希望提出功能建议，请提交问题。贡献者指南介绍了本地设置、测试以及修改位置。

如果 Fullbleed 对你有帮助，欢迎通过赞助、完善文档或提供实用示例来支持其维护。赞助并非必须；Fullbleed 仍采用 MIT 许可证，可免费使用。

Agent 发现与集成

Agent 无需掌握特定版本的 Fullbleed 知识。已安装的二进制文件会生成一份规范契约，其中包含实际版本、选择边界、功能、从解析器派生的 CLI 界面、结果架构、PDF 配置、示例、限制、Agent Skill 元数据、MCP 工具和验收任务：

fullbleed agent-manifest --json
# Equivalent canonical form:
fullbleed agent-contract --format json

已提交的 fullbleed-agent-contract.json、cli_schema.md 和 llms.txt 均由构建好的 wheel 生成。CI 会检测版本、命令、架构、配置或功能是否出现偏差。运行时自省始终是权威依据。

第一方、无版本限定的 skills/fullbleed/SKILL.md 介绍工具选择以及渲染／预览／诊断／验证循环，不会重复手册内容。它会打包在 wheel 中，并可导出到任何不存在或为空的 Agent Skill 目录：

fullbleed agent skill-path --json
fullbleed agent export-skill .agents/skills/fullbleed --json

你也可以使用 gh skill 直接从固定版本的 GitHub 发布版安装 Skill。指南会说明如何检查其来源和版本；Python 包则提供渲染引擎。

对于支持工具调用的 Agent，请安装单独版本化的适配器，使核心包保持零依赖：

python -m pip install fullbleed-mcp
fullbleed-mcp --root .

stdio 服务会将文档路径限制在所选工作区内，并将所有引擎操作委托给已安装的 Fullbleed 运行时。它提供语义发现、项目创建、渲染／预览、检查、验证、资源，以及固定式／重排式编译 VDP 工具。无依赖的核心也提供 fullbleed mcp --root .。

当用户请求的成品是由结构化内容构建的确定性印刷文档时，请使用 Fullbleed。当用户请求的成品是任意实时网站的截图或交互状态时，请使用浏览器。当必须重写现有页面内容本身时，请使用通用 PDF 编辑器。

可通过 fullbleed agent-acceptance 进行冷启动 Agent 测试；简洁、可复制的工作流见 examples/agent_workflows，与具体方法无关的基准测试框架见 agentdocbench。

本 README 是以下内容的规范使用指南：

• fullbleed CLI（人工工作流及机器／Agent 自动化）
• fullbleed Python 绑定（PdfEngine、AssetBundle、批处理 API）

其他专题参考资料位于 docs/ 中：

• docs/install-non-technical.md（面向非技术用户的分步设置指南）
• docs/css-coverage.md（经过验证的 CSS 覆盖范围、兼容状态和当前缺口）
• docs/README.md
• docs/engine.md
• docs/performance-architecture.md
• docs/performance-pass-2026-08-04.md
• docs/python-api.md
• docs/ui-accessibility.md
• docs/cli.md
• docs/pdf-templates.md

你将获得

• 生成 PDF 无需无头浏览器。
• 确定性的渲染流水线，并支持可选的 SHA256 输出哈希。
• 通过 --repro-record 和 --repro-check 实现可复现工作流。
• 将 PDF 1.7 作为生产环境稳定的默认目标版本。
• 使用 Rust 原生 PDF 模板组合功能，创建 VDP/事务型叠加层。
• 原生 Rust 图像输出可用于叠加层和最终组合输出（--emit-image），无需外部 PDF 光栅化运行时依赖。
• 由特征驱动的页面到模板绑定，并为每个页面生成确定性的组合计划。
• 为 CI 和 AI Agent 提供结构化 JSON 结果架构。
• 离线优先的资源模型，远程资源需显式启用。
• 远程项目模板注册表工作流（new list、new search、new remote）。
• 以 Python 为先的扩展接口，便于定制和构建自定义工作流。
• Rust 执行渲染时，Python 渲染调用会释放 GIL。
• 使用有序标准库工作池进行批量渲染和选定的内部任务。
• 刻意保持精简且经过许可证审查的 Rust 依赖关系图，且无需第三方 Python 运行时或构建包。

并发模型

• Python 绑定的渲染方法通过 Stable ABI 桥接，在 Rust 执行期间释放 GIL。
• 并行批处理 API 使用 Fullbleed 的有序标准库工作池（render_pdf_batch_parallel(...) 和并行文件输出变体）。
• 同一有界工作池实现还用于表格布局和 JIT 绘制路径等选定的内部热点。
• 不要假设每条单文档渲染路径都能端到端地充分利用所有核心。

2.2 版性能

Fullbleed 2.2 保留了精确的 TrueType 字形子集化，并新增了编译后的固定几何可变数据绑定。在五个独立基准测试样例中，与已发布的 2.0.0 相比，PDF 体积缩小了 95.5-97.3%，普通热渲染的速度按几何平均值计算快了 2.90 倍。

全新的仅编译一次 API 会冻结不可变的 Q32.32 显示文档，并可反复链接，而无需重新运行 HTML 解析、选择器匹配、布局、分页或命令规划。对于同一有序 PDF 中相同且未标记的副本，CompiledDocument.render_pdf_batch(...) 会让复制后的页面字典共享每个源页面的内容流。实测 20 份副本的处理路径，按几何平均值计算，每页速度比已发布的 2.0.0 热渲染器快 200.7 倍；在 1,000 页压力测试中，持续吞吐量达到 304,479-666,622 页/秒。

2.2 编译器包含真正的固定几何可变数据处理路径。一个绑定了六个字段的已编译发票，在五次运行的中位数下，将 100,000 条不同记录渲染到内存耗时 283.807 ms（352,352 页/秒）；直接渲染到已刷新、大小为 88.1 MB 的 PDF 则耗时 295.999 ms（337,839 页/秒）。计入一次性编译耗时 4.168 ms 后，直接写入文件的速度为 333,147 页/秒。测试工具验证了全部 100,000 个唯一发票 ID 的页面顺序、准确页数、已解析标记、确定性字节内容，以及缓冲区与文件的 SHA-256 相同。可通过以下命令复现：

python tools/benchmark_fullbleed_vdp.py --records 100000 --repeats 5

固定几何槽位可以保留在不可变的页面空间变换和裁剪区域中。编译器会一次性捕获当前坐标状态程序，并在每条紧凑记录叠加层中重放；它不会重新运行布局，也不会克隆完整的页面显示列表。

Base-14/WinAnsi 槽位绘制仍采用经过实测的字节补丁链接器。注册的嵌入式字体使用命令级叠加程序，因此每个绑定值都会经过整形并纳入字体子集，同时已编译的布局、分页和静态页面流仍可共享。上述吞吐量数据仅描述 Base-14 快速路径，并不代表注册字体整形的性能。 固定内容复制的结果仅适用于内容完全相同的情况；可变数据的结果仅适用于不会导致几何布局重新流动的纯绘制文本。这并不意味着任意新 HTML 或尺寸变化的记录都能快 200 倍。测量数据请参阅 docs/performance-pass-2026-08-04.md，打包矢量 IR、类型化绑定、虚拟链接器和着色器路线图请参阅 docs/performance-architecture.md。

Fullbleed 2.2.5 加固了 2.2.4 引入的第三条编译流程，用于处理尺寸变化的记录：CompiledDocument.render_pdf_reflow_bindings(...)。它只解析并恢复一次模板 DOM，并将遇到的结构流变体编译为带保护条件的定点显示程序。匹配的记录直接绑定到这些程序；工作进程执行预先塑形的文本/TJ 绘制槽、缓存的静态 PDF 页面片段、页面局部 Deflate 和一个有序链接器。显式受信任的结构槽使用 data-fb-bind-html="slot"。无法由任何已编译变体安全放置的值，会通过常规定点布局运行一次，以添加另一个变体。

在独立的 1,000 条不同记录案例研究中，29 次样本的热态直接文件中位数为 216.160 ms：4,626 条记录/秒和 8,096 页/秒。最佳样本为 168.995 ms，达到 5,917 条记录/秒和 10,355 页/秒。该测试生成了精确的 1,750 页 500/300/150/50 重排分布，并验证了全部 24,900 个标记。面向吞吐量调优的 6,870,320 字节 PDF 在所有样本中均保持确定性。在紧凑压缩设置下，编译输出也与常规渲染逐字节完全相同：5,298,961 字节，SHA-256 为 bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138。这是热态已编译变体的结果，并不适用于此前未见过的结构。首次发现变体的渲染耗时为 0.509 s（3,437 页/秒），包括设置、绑定、编译、发现和写入在内的完全冷态作业耗时为 0.588 s（2,975 页/秒）。独立测得的热态中位数相较常规路径的加速比为 43.8 倍。

安装

如果你刚开始使用 Python，或正在新机器上进行设置，请从 docs/install-non-technical.md 开始。

python -m pip install fullbleed

从本地 wheel 安装：

python -m pip install C:\path\to\fullbleed-2.6.0a9-cp310-abi3-win_amd64.whl

从已安装 Rust 的源代码检出目录构建，无需 Python 构建包：

python -m pip install --no-build-isolation --no-deps --editable .

直接创建确定性发布产物：

python build_backend/fullbleed_build_backend.py wheel --out dist
python build_backend/fullbleed_build_backend.py sdist --out dist

平台产物策略：

• Linux wheel 覆盖 x86-64、x86、ARM64、ARMv7、s390x 和 ppc64le 架构的 manylinux2014，以及 x86-64、x86、ARM64 和 ARMv7 架构的 musllinux_1_2。
• Windows wheel 覆盖 x86-64、x86 和 ARM64；macOS wheel 覆盖 Intel 和 Apple silicon。
• CPython 稳定 ABI 使各平台 wheel 均支持 Python 3.10 至 3.14。
• CI 会在每个目标架构上安装并测试所有构建的 wheel，酌情使用原生运行器或 QEMU。发布前，还会在所有受支持的 Python 版本上额外测试 x86-64 manylinux wheel。

单独的 Windows 和 Linux 作业会使用标准 GIL 测试 Python 3.15.0rc3，包括 Python 测试套件，以及与 Python 3.10 之间逐字节的 PDF/预览比较。请参阅预览覆盖范围及其限制。

验证命令接口：

fullbleed --help
fullbleed capabilities --json
fullbleed doctor --json

60 秒快速开始（项目推荐路径）

初始化项目脚手架：

fullbleed init .

fullbleed init 现在会将 Bootstrap（5.0.0）引入项目，放入 vendor/css/bootstrap.min.css， 将 Bootstrap Icons（1.11.3）引入项目，放入 vendor/icons/bootstrap-icons.svg， 将 inter 引入项目，放入 vendor/fonts/Inter-Variable.ttf，写入许可证声明 （vendor/css/LICENSE.bootstrap.txt、vendor/icons/LICENSE.bootstrap-icons.txt、vendor/fonts/LICENSE.inter.txt）， 并使用固定哈希值初始化 assets.lock.json。 生成的脚手架 report.py 还会在主渲染前执行组件挂载冒烟验证，并写入 output/component_mount_validation.json（若缺少字形、实际分页溢出或出现 CSS 未命中信号，则会快速失败）。在当前引擎中， 渲染时分页结果是判断溢出的权威依据；保守的 JIT 布局边界 仍是旧版引擎的兼容性回退方案。 脚手架中的组件现在包含 components/primitives.py，其中提供可复用的 布局／内容辅助工具（Stack、Row、Text、表格／列表辅助工具、键值行等）。 每个脚手架项目还包含 SCAFFOLDING.md，在重构组件前应先阅读。 此外还包含 AGENTS.md，用于在后续编码 Agent 会话中延续以已安装运行时为先的文档工作流程，但不会一概禁止使用其他文档工具。

安装其他项目资源（在项目上下文中，默认安装到 ./vendor/...）：

fullbleed assets install inter --json

Bootstrap 基线说明：

• 项目工作流默认以 Bootstrap（5.0.0）为样式基线。
• 仅当你想在 init 之外显式刷新／管理 Bootstrap 时，才重新运行 fullbleed assets install bootstrap --json。

使用脚手架生成的组件流水线进行渲染：

python report.py

脚手架生成的 report.py 预期产物：

• output/report.pdf
• output/report_page1.png（或引擎图像 API 生成的等效页面预览）
• output/component_mount_validation.json
• output/css_layers.json

规范静态 PDF 参考：

python examples/canonical_reference/report.py

examples/canonical_reference/ 是全面的脚手架形态参考，涵盖 组件组合、分层 CSS、打包字体／SVG、内联 SVG、栅格数据 URI、链接式和独立 HTML 产物、PDF 输出、PNG 预览以及 验证报告。

项目引导模板（fullbleed new）

使用本地模板：

fullbleed new local invoice ./my-invoice
fullbleed new local statement ./my-statement
fullbleed new local accessible ./my-accessible-doc
fullbleed new local reference ./my-reference-doc

从注册表发现远程模板：

fullbleed new list --json
fullbleed new search components --json
fullbleed new remote component-showcase ./my-documents --version 0.1.3 --json

展示项目包含 Northstar 发票和 Common Ground 报告，分别提供 HTML/CSS 和 Python 组件版本，另有一份手工编写的无障碍社区指南。 配套设计共用数据、字体、CSS 和图片素材。安装程序会复制源文件；不会安装依赖项，也不会执行项目。每个工具包都会在 requirements.txt 中固定其经过测试的组件预发布版本。 请按照当前预览指南 在独立环境中安装，比较这四个页面，并通过实时 PDF 预览进行编辑。若想从更精简的项目开始，请选择模板版本为 0.1.2 的 python-components 模板；该精简工具包保留了经过测试的 a6 运行时固定版本。

fullbleed new local accessible 是内容详尽、无障碍优先的模板，展示了 fullbleed.accessibility 运行时接口（引擎验证器、 PMR、面向 PDF/UA 的种子检查以及非视觉跟踪产物）。 fullbleed new local reference 会将规范静态 PDF 参考结构引入项目，生成包含组件层、资源、PDF/PNG 输出、页面数据 和验证报告的脚手架项目。

可选注册表覆盖设置（适用于私有／金丝雀注册表）：

fullbleed new list --registry https://example.com/manifest.json --json

或：

set FULLBLEED_TEMPLATE_REGISTRY=https://example.com/manifest.json
fullbleed new search statement --json

脚手架优先工作流（推荐）

fullbleed init 采用组件优先的编写方式，而非单个大型 HTML 模板。

典型脚手架布局：

.
|-- SCAFFOLDING.md
|-- COMPLIANCE.md
|-- report.py
|-- components/
|   |-- fb_ui.py
|   |-- primitives.py
|   |-- header.py
|   |-- body.py
|   |-- footer.py
|   `-- styles/
|       |-- primitives.css
|       |-- header.css
|       |-- body.css
|       `-- footer.css
|-- styles/
|   |-- tokens.css
|   `-- report.css
|-- vendor/
|   |-- css/
|   |-- fonts/
|   `-- icons/
`-- output/

最佳实践编写模式：

1. 首先阅读 SCAFFOLDING.md，了解项目约定。
2. 在 report.py 中处理组合与数据加载。
3. 在 components/primitives.py 中维护可复用的组件构件。
4. 在 components/header.py、components/body.py 和 components/footer.py 中维护各区块的标记。
5. 在 components/styles/*.css 中维护组件局部样式。
6. 在 styles/tokens.css 和 styles/report.css 中维护页面令牌与组合样式。

推荐的 CSS 层顺序：

1. styles/tokens.css
2. components/styles/primitives.css
3. components/styles/header.css
4. components/styles/body.css
5. components/styles/footer.css
6. styles/report.css

推荐的迭代循环：

1. 在 report.py 中编辑数据加载逻辑和组件属性。
2. 在 components/*.py 中编辑组件标记。
3. 在 components/styles/*.css 和 styles/*.css 中编辑样式。
4. 运行 python report.py。
5. 检查 output/report_page1.png、output/component_mount_validation.json 和 output/css_layers.json。

可选的脚手架诊断：

• 设置 FULLBLEED_DEBUG=1 以输出 JIT 跟踪信息。
• 设置 FULLBLEED_PERF=1 以输出性能跟踪信息。
• 设置 FULLBLEED_EMIT_PAGE_DATA=1 以持久化页面数据 JSON。
• 设置 FULLBLEED_IMAGE_DPI=144（或更高）以提高预览分辨率。
• 设置 FULLBLEED_VALIDATE_STRICT=1，在 CI 中启用更严格的验证门槛。

单次快速渲染（无项目脚手架）

使用内联 HTML/CSS 渲染，并生成可复现性产物：

fullbleed --json render \
  --html-str "<html><body><h1>Hello</h1></body></html>" \
  --css-str "body{font-family:sans-serif}" \
  --emit-manifest build/render.manifest.json \
  --emit-jit build/render.jit.jsonl \
  --emit-perf build/render.perf.jsonl \
  --deterministic-hash build/render.sha256 \
  --repro-record build/render.repro.json \
  --out output/hello.pdf

默认情况下，--deterministic-hash 会写入输出 PDF 的 SHA-256；启用 --emit-image 时，它会生成一个产物集摘要（fullbleed.artifact_digest.v1），涵盖 PDF 的 SHA-256 以及按顺序排列的页面图像 SHA-256 哈希值。JSON 输出会公开 outputs.deterministic_hash_mode（pdf_only 或 artifact_set_v1）；生成图像时，还会包含 outputs.artifact_sha256 和 outputs.image_sha256。

针对已存储的记录重新运行并强制验证可复现性：

fullbleed --json render \
  --html templates/report.html \
  --css templates/report.css \
  --repro-check build/render.repro.json \
  --out output/report.rerun.pdf

根据现有的验证渲染结果生成 PNG 页面产物：

fullbleed --json verify \
  --html templates/report.html \
  --css templates/report.css \
  --emit-pdf output/report.verify.pdf \
  --emit-image output/report_verify_pages \
  --image-dpi 200

仅编译计划（不进行渲染）：

fullbleed --json plan \
  --html templates/report.html \
  --css templates/report.css

模板组合计划（不写入最终结果）：

fullbleed --json plan \
  --html templates/overlay.html \
  --css templates/overlay.css \
  --template-binding config/template_binding.json \
  --templates config/template_catalog.json \
  --emit-compose-plan output/compose_plan.json

PDF 模板组合（VDP / 事务性）

将可变数据叠加到源 PDF 时，请使用内置的 Rust 模板组合路径。

最简 CLI 自动组合流程：

fullbleed --json render \
  --html templates/overlay.html \
  --css templates/overlay.css \
  --asset templates/source.pdf --asset-kind pdf --asset-name source-template \
  --template-binding config/template_binding.json \
  --templates config/template_catalog.json \
  --out output/composed.pdf

组合图像语义：

• 在模板自动组合模式下，--emit-image PNG 会从最终组合后的页面栅格化生成，并报告 outputs.image_mode=composed_pdf。
• 在非组合的 render/verify 运行中，--emit-image 会报告 outputs.image_mode=overlay_document。

最简 template_binding 示例：

{
  "default_template_id": "source-template",
  "feature_prefix": "fb.feature.",
  "by_feature": {
    "front": "source-template",
    "back_blank": "source-template"
  }
}

Python API 组合流程：

import fullbleed

engine = fullbleed.PdfEngine(template_binding=binding_spec)
overlay_bytes, _page_data, _bindings = engine.render_pdf_with_page_data_and_template_bindings(html, css)
open("output/overlay.pdf", "wb").write(overlay_bytes)
plan_result = engine.plan_template_compose(
    html,
    css,
    [("source-template", "templates/source.pdf")],
    0.0,
    0.0,
)
plan = [
    (
        row["template_id"],
        row["template_page"],
        row["overlay_page"],
        row["dx"],
        row["dy"],
    )
    for row in plan_result["plan"]
]
fullbleed.finalize_compose_pdf(
    [("source-template", "templates/source.pdf")],
    plan,
    "output/overlay.pdf",
    "output/composed.pdf",
    annotation_mode="link_only",  # optional: link_only | none | carry_widgets
)

完整的生产示例请参阅 docs/pdf-templates.md 和 examples/template-flagging-smoke/。

CLI 命令一览

命令	用途	JSON Schema
render	将 HTML/CSS 渲染为 PDF，可选生成 PNG 页面文件	fullbleed.render_result.v1
verify	验证渲染路径，可选生成 PDF 和 PNG	fullbleed.verify_result.v1
plan	将输入编译并规范化为清单 + 警告	fullbleed.plan_result.v1
run	使用 Python 模块/文件引擎工厂进行渲染	fullbleed.run_result.v1
inspect pdf	检查 PDF 元数据和合成兼容性	fullbleed.inspect_pdf.v1
inspect pdf-batch	检查多个 PDF，并显示每个文件的状态	fullbleed.inspect_pdf_batch.v1
inspect templates	检查模板目录元数据/兼容性	fullbleed.inspect_templates.v1
compliance	生成供法务/采购使用的许可证/合规报告	fullbleed.compliance.v1
debug-perf	汇总 perf JSONL 日志	fullbleed.debug_perf.v1
debug-jit	筛选/检查 JIT JSONL 日志	fullbleed.debug_jit.v1
doctor	检查运行时能力和健康状况	fullbleed.doctor.v1
capabilities	以机器可读格式显示命令/引擎能力	fullbleed.capabilities.v1
assets list	已安装的软件包和可选远程软件包	fullbleed.assets_list.v1
assets info	软件包详情 + 哈希值/大小	fullbleed.assets_info.v1
assets install	安装内置/远程软件包	fullbleed.assets_install.v1
assets verify	验证软件包和可选锁定约束	fullbleed.assets_verify.v1
assets lock	写入/更新 assets.lock.json	fullbleed.assets_lock.v1
cache dir	缓存位置	fullbleed.cache_dir.v1
cache prune	删除旧的缓存软件包	fullbleed.cache_prune.v1
init	初始化项目脚手架	fullbleed.init.v1
new	创建入门模板文件，或查询/安装远程模板	fullbleed.new_template.v1、fullbleed.new_list.v1、fullbleed.new_search.v1、fullbleed.new_remote.v1

任何命令/子命令的 Schema 发现方式：

fullbleed --schema render
fullbleed --schema assets verify
fullbleed --schema inspect pdf
fullbleed --schema inspect templates

最重要的 CLI 标志

全局机器标志：

• --json：将结构化结果负载输出到 stdout
• --json-only：隐含 --json 和 --no-prompts
• --schema：输出架构定义并退出
• --no-prompts：禁用交互式提示
• --config：从配置文件加载默认值
• --log-level error|warn|info|debug：控制 CLI 日志详细程度
• --no-color：禁用 ANSI 颜色输出
• --version：打印 CLI 版本并退出

渲染／验证／规划的关键标志：

• 输入：--html、--html-str、--css、--css-str --html 接受 .svg 文件，用于直接渲染 SVG 文档；--html-str 接受内联 SVG 标记。
• 页面设置：--page-size、--page-width、--page-height、--margin、--page-margins
• 引擎开关：--reuse-xobjects、--svg-form-xobjects、--svg-raster-fallback、--shape-text、--unicode-support、--unicode-metrics
• PDF／合规性：--pdf-version、--pdf-profile、--color-space、--document-lang、--document-title 面向发布工作流的稳定默认值为 --pdf-version 1.7。 配置文件目标：none、pdfa1a、pdfa1b、pdfa2a、pdfa2b、pdfa2u、pdfa3a、pdfa3b、pdfa3u、pdfa4、pdfa4e、pdfa4f、pdfx4、pdfua1、pdfua2、pdfvt1、wtpdf1r、wtpdf1a、tagged。 别名：a、ua、vt、wt1r、wt1a、pdf/a、pdf/ua、pdf/vt。 输出意图元数据（--output-intent-identifier|--output-intent-info|--output-intent-components）要求提供 --output-intent-icc。 pdfx4 和 pdfvt1 强制使用 PDF 1.6，并要求提供标题和明确的写入日期 （--timestamp current、固定的 UTC 日期，或 --timestamp-source SOURCE_DATE_EPOCH）。 PDF/VT 组合介绍了记录层级、--pdf-vt-job、 私有 DPM、保守的复用提示，以及独立的发布验证边界。 运行 python tools/validate_pdf_profiles.py --download-verapdf --install-pdf-oxide --strict-external 以重新生成配置文件样本、收集 inspect/JIT 证据、重放确定性哈希、使用 veraPDF 验证 PDF/A 和 PDF/UA，并使用 pdf_oxide 验证 PDF/X-4。WTPDF 配置文件使用 veraPDF 的 wt1r/wt1a 进行验证，并包含 PDF Declaration 证据。pdfa4f 会生成并检查关联的 EmbeddedFiles 名称树。pdfvt1 还会生成并检查已解析的 DPart 图（DPartRoot、DPartRootNode、NodeNameList [/Job /Record /Document]、叶节点页面范围， 以及页面 /DPart 引用），其中包括用于 /Start 和 /End 的补充多页样本，结果以细粒度布尔值和 pdfvt_dpart_graph_valid 报告；如需第三方 PDF/VT 认证，请使用专用的 PDF/VT 预检工具， 或使用 --pdfvt-cmd "tool --input {pdf}" --pdfvt-version-cmd "tool --version" --require-dedicated-pdfvt 将其接入同一测试框架。
• 水印：--watermark-text、--watermark-html、--watermark-image、--watermark-layer、--watermark-semantics、--watermark-opacity、--watermark-rotation
• 产物：--emit-jit、--emit-perf、--emit-glyph-report、--emit-page-data、--emit-compose-plan、--emit-image、--image-dpi、--deterministic-hash
• 资源：--asset、--asset-kind、--asset-name、--asset-trusted、--allow-remote-assets
• 配置文件：--profile dev|preflight|prod
• 失败策略：--fail-on overflow|missing-glyphs|font-subst|budget
• 回退策略：--allow-fallbacks（保留回退诊断信息，但不会使 missing-glyphs / font-subst 检查门禁失败）
• 可复现性：--repro-record <path>、--repro-check <path>
• 预算阈值：--budget-max-pages、--budget-max-bytes、--budget-max-ms
• 发布门禁：doctor --strict、compliance --strict --max-audit-age-days <n>

SVG 工作流

Fullbleed 通过三种实用的 CLI 方式支持 SVG：

• 直接通过 --html <file.svg> 渲染 SVG 文档
• 通过 --html-str "<svg ...>...</svg>" 内嵌 SVG 标记
• 通过 --asset <file.svg> 引用 SVG 资源（类型会自动推断为 svg）

将独立 SVG 文件转换为 PDF：

fullbleed --json render \
  --html artwork/badge.svg \
  --out output/badge.pdf

将内嵌 SVG 标记转换为 PDF：

fullbleed --json render \
  --html-str "<svg xmlns='http://www.w3.org/2000/svg' width='200' height='80'><rect width='200' height='80' fill='#0d6efd'/><text x='16' y='48' fill='white'>Hello SVG</text></svg>" \
  --out output/inline-svg.pdf

包含显式 SVG 资源注册的 HTML 模板：

fullbleed --json render \
  --html templates/report.html \
  --css templates/report.css \
  --asset assets/logo.svg \
  --asset-kind svg \
  --out output/report.pdf

SVG 渲染行为标志：

• --svg-form-xobjects / --no-svg-form-xobjects
• --svg-raster-fallback / --no-svg-raster-fallback

分发的 Python wheel 启用了 svg_raster 引擎功能，因此 --svg-raster-fallback 可以将 SVG 文本、滤镜、蒙版和 foreignObject 等不受支持的 SVG 构造栅格化为确定性图像内容。 自定义源码构建必须包含 --features python,svg_raster，才能声明并使用该回退路径。

机器发现：

fullbleed capabilities --json

检查 fullbleed.capabilities.v1 中的 svg 对象，获取 SVG 支持元数据。engine 对象还会报告编译文档/重排可用性，以及支持的单次调用压缩模式。 它会报告已编译的 svg_raster 构建功能，以及原生矢量 SVG、需要栅格回退的 SVG 和 不支持/已知有损的 SVG 功能矩阵。

图像支持矩阵

可安全用于发布的图像支持说明：

• 支持直接输入的栅格格式：PNG 和 JPEG。
• SVG 由上述 SVG 流程处理；在支持的情况下输出原生矢量，对于仅支持回退的功能，在启用 svg_raster 后使用栅格回退。
• 支持的引用方式包括文件系统路径、已注册的捆绑资源、文件/数据 URI、<img>、CSS background-image: url(...)、列表样式图像 和水印图像。
• 不支持或未声明为发布版直接输入格式：WebP、GIF、TIFF、AVIF、 BMP、动图、<picture>、srcset、sizes、密度描述符 以及浏览器样式的响应式图像选择。
• 为确保构建结果确定，优先使用随项目提供的本地资源或已注册的 AssetBundle 输入；必须显式允许远程资源。

按页模板（page_1、page_2、page_n）

Fullbleed 内部使用有序的页面模板。在文档中，最简单的理解方式是：

• page_1：第一页模板
• page_2：第二页模板
• page_n：后续页面重复使用的模板

配置映射：

• CLI 的 --page-margins 键：1、2、……以及可选的 "n"（或别名 "each"）。
• Python 的 PdfEngine(page_margins=...)：使用相同的键模型。
• 缺少的数字页会回退到基础 margin。
• 最后一个已配置的模板会用于剩余页面。

最简 CLI 示例：

{
  "1": {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  "2": {"top": "24mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  "n": {"top": "30mm", "right": "12mm", "bottom": "12mm", "left": "12mm"}
}

fullbleed --json render \
  --html templates/report.html \
  --css templates/report.css \
  --page-margins page_margins.json \
  --header-each "Statement continued - Page {page} of {pages}" \
  --out output/report.pdf

最简 Python 示例：

import fullbleed

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="12mm",
    page_margins={
        1: {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},  # page_1
        2: {"top": "24mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},  # page_2
        "n": {"top": "30mm", "right": "12mm", "bottom": "12mm", "left": "12mm"} # page_n
    },
    header_first="Account Statement",
    header_each="Statement continued - Page {page} of {pages}",
    footer_last="Final page",
)

注意：

• CLI 目前提供 --header-each / --footer-each（以及 --header-html-each / --footer-html-each）。
• 对于 first/last 页眉/页脚变体（header_first、header_last、footer_first、footer_last），请使用 Python API。

资源工作流（CLI）

列出已安装和可用的软件包：

fullbleed assets list --available --json

安装内置资源：

fullbleed assets install bootstrap
fullbleed assets install bootstrap-icons
# `@bootstrap` / `@bootstrap-icons` are also supported aliases

PowerShell 注意事项：

• 为 @ 别名加引号（例如 "@bootstrap"），以避免意外的 shell 解析问题。

安装远程资源包：

fullbleed assets install inter

安装广泛 Unicode 回退包（字体体积较大）：

fullbleed assets install noto-sans

安装到自定义供应商目录：

fullbleed assets install bootstrap --vendor ./vendor

安装到全局缓存：

fullbleed assets install inter --global

安装常用条形码字体（默认选项均符合许可要求）：

fullbleed assets install libre-barcode-128
fullbleed assets install libre-barcode-39
fullbleed assets install libre-barcode-ean13-text

严格失败模式下，根据锁定文件进行验证：

fullbleed assets verify inter --lock --strict --json

预览缓存清理结果，但不删除文件：

fullbleed cache prune --max-age-days 30 --dry-run --json

注意事项：

• 内置软件包既接受普通引用，也接受 @ 引用（bootstrap == @bootstrap、bootstrap-icons == @bootstrap-icons、noto-sans == @noto-sans）。
• noto-sans 是可用的内置回退包，但其体积有意设置得大于 inter；当文档需要更广泛的字形覆盖范围时，请使用它。
• 检测到项目标记（CWD 中存在 assets.lock.json、report.py 或 fullbleed.toml）时，项目安装默认使用 ./vendor/。
• 如果未找到项目标记，除非明确设置 --vendor，否则 assets install 默认使用全局缓存。
• 不要硬编码缓存路径，例如 %LOCALAPPDATA%/fullbleed/cache/...；请使用 assets install --json 并读取 installed_to。
• 已安装的资源会在按类型划分的供应商目录中包含许可证文件（例如 vendor/fonts/、vendor/css/）。
• assets lock --add 目前主要用于添加内置软件包。
• 远程注册表中的条形码软件包目前都是来自 Google Fonts 的 OFL-1.1 字体系列（Libre Barcode）。
• USPS IMB 字体目前无法通过 assets install 自动安装；请使用经过本地审查的字体文件，并单独跟踪其许可信息。

Bootstrap 供应

Bootstrap 内置软件包详情：

• 软件包：bootstrap（别名：@bootstrap）
• 捆绑版本：5.0.0
• 资源类型：CSS（bootstrap.min.css）
• 默认安装位置：vendor/css/bootstrap.min.css（项目模式）
• 许可证：MIT
• 许可证来源：https://raw.githubusercontent.com/twbs/bootstrap/v5.0.0/LICENSE

Bootstrap Icons 内置软件包详情：

• 软件包：bootstrap-icons（别名：@bootstrap-icons）
• 捆绑版本：1.11.3
• 资源类型：SVG 精灵图（bootstrap-icons.svg）
• 默认安装位置：vendor/icons/bootstrap-icons.svg（项目模式）
• 许可证：MIT
• 许可证来源：https://raw.githubusercontent.com/twbs/icons/v1.11.3/LICENSE

Bootstrap 注意事项：

• Bootstrap 已供应，可通过资源流水线安装。
• Bootstrap CSS 作为显式本地资源使用（--asset @bootstrap 或 AssetBundle）；外部 HTML <link rel="stylesheet"> 并非可执行路径。
• Bootstrap preflight 示例仍可用于冒烟测试，但并非 CSS 一致性声明的权威依据。

已验证的 CSS 覆盖范围

完整且持续维护的覆盖范围说明，请参阅 docs/css-coverage.md。

对合并后的组件源码（4379bb4）进行的完整语料对比结果保留如下：共 1,662 个案例，其中 1,619 个 PASS、25 个 FAIL，18 个 REFERENCE-DISPUTED。 独立运行 保留了失败结论。全部 5,489 个已保存输出及其所有评分均与经审查的基线一致。alpha 9 运行手册 要求对新版本进行资格审查，并验证其公开软件包。 此对比并不能证明任意文档都能实现完整的 CSS 一致性或符合性。下方较早日期的结果仅供历史参考，并非当前门槛。

截至 2026 年 5 月 19 日的摘要：

• 跟踪的 CSS 模块：22
• 模块状态：22/22 in_progress
• 完整 CSS 测试固件通道：86/86 个测试固件通过，包含 603 项断言／绘制检查
• 奇偶校验状态检查：通过（tools/generate_css_parity_status.py --check --json）
• 规范验证产物：_css_working/css_parity_status.json
• 规范验证产物：_css_working/tmp/fixture_full_latest.json
• 规范验证产物：_css_working/css_broad_coverage_sprint_s14.md

完整的固定独立 Wheel265 门禁于 2026 年 8 月 9 日结束，1,662 个测试固件中有 1,642 PASS、0 FAIL 和 20 REFERENCE-DISPUTED。对于此指定语料中所有可裁定的测试固件，奇偶一致率严格达到 100%；有争议的参考结果仍会明确列出，不会重新标记为实现通过。更广泛的 Web 平台覆盖范围仍受 docs/css-coverage.md 中模块和已知缺口契约的约束。

2026 年 8 月 5 日验证的流布局／重排加固新增了定高块、一列网格和列式 Flex 的连续切片；避免内容重复；在需要避免分页的图形中保留带样式的空标题；保留 display: contents 网格绘制阶段；并使定位包含块保持原子性。独立评审中的定向 18 项回归集全部通过，结果为 18/18（13 项像素精确，超过阈值的最大差异为 0.97030199%）。此定向诊断不会取代完整的外部语料报告。

目前已验证的行为包括：在广泛的静态文档 CSS 领域实现一等的解析器 -> 求值器 -> 计算器 -> 布局／绘制覆盖（值运算、布局基元、分页／片段化基线、变换第 1 阶段、渐变／效果子集，包括颜色优先和颜色交错的 filter: drop-shadow(...) 及其计算长度、使用 mm 长度的现代 rgb() 阴影颜色、拒绝重复的 drop-shadow(...) 颜色、空的可选滤镜函数默认值、显式／currentColor backdrop-filter: drop-shadow(...) 光栅绘制、严格的 box-shadow 长度／颜色语法及其现代 rgb() 和 mm 绘制覆盖、柔化的模糊内阴影边缘绘制、定向内阴影偏移边缘绘制、受溢出控制的 text-overflow: ellipsis、物理最小／最大盒约束、水平书写模式下 RTL direction 的行内插入、外边距、内边距和边框映射、竖排书写模式下 direction: rtl 的行内插入重映射、vertical-rl 逻辑尺寸／插入／外边距／内边距／边框／最小－最大约束、vertical-lr 逻辑尺寸／最小－最大／插入／外边距／内边距／边框重映射、基本竖排文本列及 vertical-rl 向左、vertical-lr 向右的行进方向，以及确定性诊断）。

已知缺口类别已明确跟踪，以便完成最后的奇偶一致性推进：

• 当前子集之外仍有更多 filter/backdrop-filter 函数覆盖范围，包括 SVG url() 滤镜、超出当前灵活颜色顺序前景和基础背景覆盖范围的高级 drop-shadow() 形式，以及 PDF 原生前景滤镜
• clip-path 语法的高级功能超出当前基本形状子集，包括 SVG 裁剪源、SVG 专用几何框和更深入的边缘语法
• plus-lighter 的 PDF 原生兼容性，以及更深入的嵌套合成/隔离覆盖范围
• 更精细的模糊内阴影边缘保真度
• 当前多层背景图像子集之外仍有更多边缘语义：该子集包括尺寸渐变层的 repeat-x/space/round，以及 PNG url(...) 的显式尺寸/auto-auto 固有尺寸/负尺寸无效/contain/cover/自动维度尺寸/单值尺寸/alpha-stack/默认 repeat-repeat/repeat-y/repeat/repeat-no-repeat/no-repeat-repeat/space-space/round-round/round-space/space-round/round-repeat/round-no-repeat/no-repeat-round/no-repeat-space/space-no-repeat/repeat-space/repeat-round/space-repeat/逻辑重复别名/多层重复轴/背景列表重复/百分比位置/边缘偏移位置/逻辑位置别名/简写位置尺寸重复/content-box 原点裁剪/多层原点裁剪/背景混合 normal/背景混合 multiply/screen 模式/overlay 模式/exclusion 模式/hard-light 模式/darken 模式/lighten 模式/color-dodge 模式/color-burn 模式/soft-light 模式/hue 模式/saturation 模式/color 模式/luminosity 模式/plus-lighter 模式/列表重复/截断/栅格混合/栅格层映射/栅格与渐变混合映射/渐变与栅格混合映射；此外还包括更广泛的栅格混合堆栈组合
• 表格布局边缘语义的强化超出当前固定布局宽度提示、自动宽度、标题位置放置和无效标题位置继承路径
• 完整的竖排文本/布局流超出当前竖排静态布局和基础换行文本列基线

run 命令（Python 工厂互操作）

run 允许 CLI 使用由 Python 创建的引擎实例。

report.py：

import fullbleed

def create_engine():
    return fullbleed.PdfEngine(page_width="8.5in", page_height="11in", margin="0.5in")

CLI 调用：

fullbleed --json run report:create_engine \
  --html-str "<h1>From run</h1>" \
  --css templates/report.css \
  --out output/report.pdf

入口格式：

• module_name:factory_or_engine
• path/to/file.py:factory_or_engine

Rust 图表编译

对于基于 Rust 的视觉/源代码前端，引擎还提供 文档上下文图表编译：常规 CSS 字体 选择与字号、项目字体图例测量/换行、语义表格， 以及可观察的布局失败。生成的 SVG 是派生输出，而非创作源文件。

Python API 快速入门

import fullbleed

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="0.5in",
    pdf_version="1.7",
    pdf_profile="none",
    color_space="rgb",
)

html = "<html><body><h1>Invoice</h1><p>Hello.</p></body></html>"
css = "body { font-family: sans-serif; }"

bytes_written = engine.render_pdf_to_file(html, css, "output/invoice.pdf")
print(bytes_written)

使用 AssetBundle 注册本地资源：

import fullbleed

bundle = fullbleed.AssetBundle()
bundle.add_file("vendor/css/bootstrap.min.css", "css", name="bootstrap")
bundle.add_file("vendor/fonts/Inter-Variable.ttf", "font", name="inter")

engine = fullbleed.PdfEngine(page_width="8.5in", page_height="11in")
engine.register_bundle(bundle)
engine.render_pdf_to_file("<h1>Styled</h1>", "", "output/styled.pdf")

Python API 签名（运行时已验证）

这些签名通过 inspect.signature(...) 从已安装的软件包中验证。

PdfEngine 构造函数：

PdfEngine(
    page_width=None,
    page_height=None,
    margin=None,
    page_margins=None,
    font_dirs=None,
    font_files=None,
    reuse_xobjects=True,
    svg_form_xobjects=False,
    svg_raster_fallback=False,
    unicode_support=True,
    shape_text=True,
    unicode_metrics=True,
    pdf_version=None,
    pdf_profile=None,
    output_intent_icc=None,
    output_intent_identifier=None,
    output_intent_info=None,
    output_intent_components=None,
    color_space=None,
    document_lang=None,
    document_title=None,
    header_first=None,
    header_each=None,
    header_last=None,
    header_x=None,
    header_y_from_top=None,
    header_font_name=None,
    header_font_size=None,
    header_color=None,
    header_html_first=None,
    header_html_each=None,
    header_html_last=None,
    header_html_x=None,
    header_html_y_from_top=None,
    header_html_width=None,
    header_html_height=None,
    footer_first=None,
    footer_each=None,
    footer_last=None,
    footer_x=None,
    footer_y_from_bottom=None,
    footer_font_name=None,
    footer_font_size=None,
    footer_color=None,
    watermark=None,
    watermark_text=None,
    watermark_html=None,
    watermark_image=None,
    watermark_layer="overlay",
    watermark_semantics="artifact",
    watermark_opacity=0.15,
    watermark_rotation=0.0,
    watermark_font_name=None,
    watermark_font_size=None,
    watermark_color=None,
    paginated_context=None,
    jit_mode=None,
    debug=False,
    debug_out=None,
    perf=False,
    perf_out=None,
)

有关常规/斜体字族选择和精确字形映射，请参阅 注册字体。

模块导出：

• PdfEngine
• CompiledDocument
• CompiledFlowCompression
• AssetBundle
• Asset
• AssetKind
• WatermarkSpec(kind, value, layer='overlay', semantics=None, opacity=0.15, rotation_deg=0.0, font_name=None, font_size=None, color=None)
• concat_css(parts)
• vendored_asset(source, kind, name=None, trusted=False, remote=False)
• inspect_pdf(path)
• inspect_template_catalog(templates)
• finalize_stamp_pdf(template, overlay, out, page_map=None, dx=0.0, dy=0.0)
• finalize_compose_pdf(templates, plan, overlay, out, annotation_mode='link_only')
• fetch_asset(url)

PdfEngine 方法：

方法	返回形式
register_bundle(bundle)	None
compile_pdf(html, css)	CompiledDocument
render_pdf(html, css, deterministic_hash=None)	bytes
render_pdf_to_file(html, css, path, deterministic_hash=None)	int（写入的字节数）
render_image_pages(html, css, dpi=150)	list[bytes]
render_image_pages_to_dir(html, css, out_dir, dpi=150, stem=None)	list[str]
render_finalized_pdf_image_pages(pdf_path, dpi=150)	list[bytes]
render_finalized_pdf_image_pages_to_dir(pdf_path, out_dir, dpi=150, stem=None)	list[str]
render_pdf_with_glyph_report(html, css)	(bytes, list)
render_pdf_with_page_data(html, css)	(bytes, page_data_or_none)
render_pdf_with_page_data_and_glyph_report(html, css)	(bytes, page_data_or_none, glyph_report_list)
render_pdf_with_page_data_and_template_bindings(html, css)	(bytes, page_data_or_none, template_bindings_or_none)
render_pdf_with_page_data_and_template_bindings_and_glyph_report(html, css)	(bytes, page_data_or_none, template_bindings_or_none, glyph_report_list)
plan_template_compose(html, css, templates, dx=0.0, dy=0.0)	dict
render_pdf_batch(html_list, css, deterministic_hash=None)	bytes
render_pdf_batch_parallel(html_list, css, deterministic_hash=None)	bytes
render_pdf_batch_to_file(html_list, css, path, deterministic_hash=None)	int
render_pdf_batch_to_file_parallel(html_list, css, path, deterministic_hash=None)	int
render_pdf_batch_to_file_parallel_with_page_data(html_list, css, path, deterministic_hash=None)	(bytes_written, page_data_list)
render_pdf_batch_with_css(jobs, deterministic_hash=None)	bytes
render_pdf_batch_with_css_to_file(jobs, path, deterministic_hash=None)	int

CompiledDocument 方法：

方法	返回形式
stats()	dict
render_pdf(deterministic_hash=None)	bytes
render_pdf_to_file(path, deterministic_hash=None)	int
render_pdf_batch(copies, deterministic_hash=None)	bytes
render_pdf_bindings(bindings, deterministic_hash=None)	bytes
render_pdf_bindings_to_file(bindings, path, deterministic_hash=None)	int
render_pdf_reflow_bindings(bindings, deterministic_hash=None, *, compression="throughput")	bytes
render_pdf_reflow_bindings_to_file(bindings, path, deterministic_hash=None, *, compression="throughput")	int

编译通道只运行一次解析和布局。render_pdf_batch 会虚拟化内容相同且未加标签的页面。固定绑定方法接受列式 dict[str, list[str]] 数据，为每条记录生成几何尺寸固定的独特文本叠层，同时共享静态绘制内容。它们要求槽位键完全匹配、各列长度相同且非零、文本局限于页面内，并且使用未加标签的配置文件。Base-14 文本使用直接字节修补通道；注册的字体则会整形为命令级叠层。绑定值不会触发布局或重排。

重排绑定方法使用相同的精确列契约，但会执行已编译的解析后 DOM 程序。{{slot}} 值会作为字面文本处理，并可能重新整形、换行、调整块尺寸以及改变页数。空元素可以通过 data-fb-bind-html="slot" 选择使用受信任的生成标记；这些值会替换元素的子节点。每个原生工作线程会复用一个 DOM，并通过有界队列按输入顺序链接记录输出。结构化槽位值会作为受信任的标记解析：请清理不受信任的输入，或使用标量 {{slot}} 绑定，这些绑定仍会作为字面文本处理。每次渲染可选择 CompiledFlowCompression.Throughput（默认）或 CompiledFlowCompression.Compact；同一进程中可以安全混用这两种模式。有关信任边界和当前限制，请参阅 docs/python-api.md。

设置 deterministic_hash 后，引擎会将 PDF 的 SHA-256 写入指定的文件路径。 AssetBundle 方法：

• add_file(path, kind, name=None, trusted=False, remote=False)
• add(asset)
• assets_info()
• css()

Python 示例（已通过冒烟检查）

规范脚手架参考：

python examples/canonical_reference/report.py

文本水印 + 诊断信息：

import fullbleed

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="0.5in",
    pdf_version="1.7",
    watermark_text="INTERNAL",
    watermark_layer="overlay",
    watermark_semantics="artifact",
    watermark_opacity=0.12,
    watermark_rotation=-32.0,
    debug=True,
    debug_out="build/invoice.jit.jsonl",
    perf=True,
    perf_out="build/invoice.perf.jsonl",
)

html = "<h1>Invoice</h1><p>Status: Ready</p>"
css = "h1{margin:0 0 8px 0} p{margin:0}"

written = engine.render_pdf_to_file(html, css, "output/invoice_watermarked.pdf")
print("bytes:", written)

批量渲染 + 字形/页面数据检查：

import fullbleed

engine = fullbleed.PdfEngine(page_width="8.5in", page_height="11in", margin="0.5in")

jobs = [
    ("<h1>Batch A</h1><p>Alpha</p>", "h1{color:#0d6efd}"),
    ("<h1>Batch B</h1><p>Beta</p>", "h1{color:#198754}"),
]

written = engine.render_pdf_batch_with_css_to_file(jobs, "output/batch.pdf")
print("batch bytes:", written)

pdf_bytes, glyph_report = engine.render_pdf_with_glyph_report("<p>Hello</p>", "")
print("glyph entries:", len(glyph_report))

pdf_bytes, page_data = engine.render_pdf_with_page_data("<p>Hello</p>", "")
print("page data available:", page_data is not None)

事务性页眉/页脚 + 合计

最简、自包含的 Python 示例（无需外部模板文件），展示：

• 第 2 页及后续页面持续显示页眉。
• 通过 {sum:items.amount} 展开每页小计页脚。
• 通过 {total:items.amount} 展开末页总计页脚。
• 提供结构化 page_data 合计数据，用于自动化和对账检查。

from pathlib import Path
import fullbleed

rows = []
for i in range(1, 121):  # enough rows to force multiple pages
    amount = 10.00 + ((i * 7) % 23) + 0.25
    rows.append(
        f'<tr data-fb="items.amount={amount:.2f}">'
        f"<td>2026-01-{(i % 28) + 1:02d}</td>"
        f"<td>Txn {i:03d}</td>"
        f'<td class="num">${amount:.2f}</td>'
        "</tr>"
    )

html = f"""<!doctype html>
<html>
<body>
  <h1>Monthly Statement</h1>
  <table>
    <thead>
      <tr><th>Date</th><th>Description</th><th class="num">Amount</th></tr>
    </thead>
    <tbody>
      {''.join(rows)}
    </tbody>
  </table>
</body>
</html>
"""

css = """
body { font-family: sans-serif; font-size: 10pt; color: #111; }
h1 { margin: 0 0 8pt 0; }
table { width: 100%; border-collapse: collapse; }
th, td { padding: 4pt; border-bottom: 1pt solid #e1e1e1; }
thead th { background: #f3f6fa; text-transform: uppercase; font-size: 9pt; }
.num { text-align: right; }
"""

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="12mm",
    page_margins={
        1: {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
        2: {"top": "28mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
        "n": {"top": "28mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
    },
    header_html_each=(
        '<div style="display:flex;justify-content:space-between;border-bottom:1pt solid #d9d9d9;">'
        '<div style="font-weight:bold;">Acme Ledger</div>'
        '<div style="font-size:9pt;color:#444;">Statement Continued - Page {page} of {pages}</div>'
        "</div>"
    ),
    header_html_x="12mm",
    header_html_y_from_top="6mm",
    header_html_width="186mm",
    header_html_height="10mm",
    paginated_context={"items.amount": "sum"},
    footer_each="Subtotal (Page {page}): ${sum:items.amount}",
    footer_last="Grand Total: ${total:items.amount}",
    footer_x="12mm",
    footer_y_from_bottom="8mm",
)

pdf_bytes, page_data = engine.render_pdf_with_page_data(html, css)
Path("output_transactional_minimal.pdf").write_bytes(pdf_bytes)

assert page_data["page_count"] >= 2
assert page_data["totals"]["items.amount"]["value"] == sum(
    p["items.amount"]["value"] for p in page_data["pages"]
)
print("Wrote output_transactional_minimal.pdf")
print("Page count:", page_data["page_count"])
print("Grand total:", page_data["totals"]["items.amount"]["formatted"])

API 说明：

• 对于事务性滚动合计（paginated_context）和 HTML 页眉/页脚布局（header_html_*、footer_html_*），请使用 Python PdfEngine API 路径。
• 对于较简单的情况，CLI 目前提供直接文本页眉/页脚标志（--header-each、--footer-each）。

CLI 水印一致性示例：

fullbleed --json render \
  --html-str "<h1>Watermark probe</h1><p>hello</p>" \
  --css-str "body{font-family:sans-serif}" \
  --watermark-text "INTERNAL" \
  --watermark-layer overlay \
  --watermark-opacity 0.12 \
  --watermark-rotation -32 \
  --out output/watermark_probe.pdf

参考图一致性工作流（实用）

以设计参考图（例如参考图导出文件）为目标时，以下循环效果良好：

1. 从 fullbleed init 开始，以便引入并固定 CSS/字体/图标基线。
2. 对于脚手架项目，运行 python report.py，并根据需要设置 FULLBLEED_IMAGE_DPI，以获得更清晰的预览。
3. 对于直接通过 CLI 渲染模板的情况，请通过 CLI（--asset ...）或 AssetBundle 注册资源。
4. 启用图像产物并迭代：

fullbleed --json render \
  --profile preflight \
  --html templates/invoice.html \
  --css templates/invoice.css \
  --asset vendor/css/bootstrap.min.css --asset-kind css --asset-name bootstrap \
  --asset vendor/icons/bootstrap-icons.svg --asset-kind svg --asset-name bootstrap-icons \
  --asset vendor/fonts/Inter-Variable.ttf --asset-kind font --asset-name inter \
  --emit-image output/pages_png \
  --emit-jit output/render.jit.jsonl \
  --emit-perf output/render.perf.jsonl \
  --out output/render.pdf

5. 布局稳定后，使用 --repro-record / --repro-check。

实用技巧：

• 如有全页导出文件，请与其进行比较。
• 在多次迭代中固定预览 DPI（例如 144 或 200）。
• 提交 PNG 基线，以便进行可重复的视觉检查。

公开黄金回归测试套件

goldens/ 下提供了面向发布级渲染的回归测试覆盖，包含三个样例：

• invoice
• statement
• menu

黄金测试契约资源：

• 预期哈希：goldens/expected/golden_suite.expected.json
• 预期 PNG 基线：goldens/expected/png/<case>/<case>_page1.png

使用已提交的预期值运行：

python goldens/run_golden_suite.py verify

有意更新基线：

python goldens/run_golden_suite.py generate

人工 + AI 运行模式

推荐的自动化默认设置：

fullbleed --json-only render ...

此模式对 Agent 安全的原因：

• 对于命令执行 JSON 负载，schema 始终存在。
• 解析器用法错误（exit=2）由 argparse 以用法文本形式输出，而非 JSON 负载。
• ok 表示成功或失败，无需解析文本。
• 可选产物会在 outputs 中明确列出。
• 运行时可进行架构内省（--schema）。

示例解析循环：

import json, subprocess

proc = subprocess.run(
    [
        "fullbleed", "--json-only", "render",
        "--html", "templates/report.html",
        "--css", "templates/report.css",
        "--out", "output/report.pdf",
    ],
    capture_output=True,
    text=True,
    check=False,
)

payload = json.loads(proc.stdout)
assert payload["schema"] == "fullbleed.render_result.v1"
assert payload["ok"] is True
print(payload["outputs"]["pdf"])

MACHINE_CONTRACT.v1

{
  "schema": "fullbleed.readme_contract.v1",
  "package": "fullbleed",
  "cli_entrypoint": "fullbleed",
  "dev_cli_entrypoint": "python -m fullbleed_cli.cli",
  "python_module": "fullbleed",
  "json_discriminator": "schema",
  "core_commands": [
    "render",
    "verify",
    "plan",
    "debug-perf",
    "debug-jit",
    "run",
    "finalize",
    "inspect",
    "compliance",
    "doctor",
    "capabilities",
    "assets",
    "cache",
    "init",
    "new"
  ],
  "result_schemas": [
    "fullbleed.render_result.v1",
    "fullbleed.verify_result.v1",
    "fullbleed.plan_result.v1",
    "fullbleed.run_result.v1",
    "fullbleed.inspect_pdf.v1",
    "fullbleed.inspect_pdf_batch.v1",
    "fullbleed.inspect_templates.v1",
    "fullbleed.compose_plan.v1",
    "fullbleed.compliance.v1",
    "fullbleed.capabilities.v1",
    "fullbleed.doctor.v1",
    "fullbleed.assets_list.v1",
    "fullbleed.assets_info.v1",
    "fullbleed.assets_install.v1",
    "fullbleed.assets_verify.v1",
    "fullbleed.assets_lock.v1",
    "fullbleed.cache_dir.v1",
    "fullbleed.cache_prune.v1",
    "fullbleed.init.v1",
    "fullbleed.new_template.v1",
    "fullbleed.new_list.v1",
    "fullbleed.new_search.v1",
    "fullbleed.new_remote.v1",
    "fullbleed.debug_perf.v1",
    "fullbleed.debug_jit.v1",
    "fullbleed.repro_record.v1",
    "fullbleed.error.v1"
  ],
  "artifact_flags": [
    "--emit-manifest",
    "--emit-jit",
    "--emit-perf",
    "--emit-glyph-report",
    "--emit-page-data",
    "--emit-compose-plan",
    "--emit-image",
    "--image-dpi",
    "--deterministic-hash",
    "--repro-record",
    "--repro-check"
  ],
  "fail_on": ["overflow", "missing-glyphs", "font-subst", "budget"],
  "budget_flags": ["--budget-max-pages", "--budget-max-bytes", "--budget-max-ms"],
  "profiles": ["dev", "preflight", "prod"],
  "pdf_version_default": "1.7",
  "known_exit_codes": {
    "0": "success",
    "1": "command-level validation/operational failure",
    "2": "argparse usage error",
    "3": "CLI runtime/input error wrapper"
  }
}

重要行为说明

• render --json 不能与 --out -（标准输出 PDF 字节）同时使用。
• verify 默认将 PDF 输出到标准输出，除非提供了 --emit-pdf；在机器模式下，请使用 --emit-pdf <path>。
• --emit-image <dir> 会将各页 PNG 写入为 <stem>_pageN.png（stem 来自 --out/--emit-pdf；如果将 PDF 流式输出到标准输出，则为 render）。
• 在模板自动组合运行中，--emit-image 生成的文件会从最终组合页面栅格化，并报告 outputs.image_mode=composed_pdf；否则，image_mode=overlay_document。
• outputs.deterministic_hash_mode 默认为 pdf_only；生成图像文件时则为 artifact_set_v1。
• 如果同时设置了 --emit-page-data 和 --emit-glyph-report，当前引擎会使用组合 API，仅渲染一次；不支持该 API 的旧版引擎则会回退为渲染两次。
• 生产目标为 PDF 1.7。
• run 接受 --html-str，无需同时提供 --html。
• init 现在会生成 COMPLIANCE.md，用于项目级发布审查。
• compliance --json 会输出机器可读的法律/采购诊断信息。
• --watermark-layer underlay 可作为旧版别名使用，并会规范化为 background。
• --emit-manifest 会包含一个 watermark 对象，其中包含 text|html|image|layer|semantics|opacity|rotation|enabled。
• --fail-on overflow 会根据放置数据进行检查，并可能自动启用内部 JIT 规划。
• --fail-on font-subst 会根据缺失字形和回退诊断信息进行检查。
• --allow-fallbacks 允许在 missing-glyphs / font-subst 门禁中将回退诊断信息视为提示，同时仍会在 JSON 输出中报告这些信息。
• --fail-on budget 至少需要一个预算阈值标志。
• --repro-check 会在输入/哈希发生偏移，以及存在锁定数据时锁定哈希不匹配的情况下失败。
• PDF/A 和 PDF/X/VT 配置文件要求提供输出意图元数据；pdfa4、pdfa4e 和 pdfa4f 会自动输出 PDF 2.0。PDF/A、PDF/X/VT、PDF/UA 和 WTPDF 文本输出会强制执行嵌入字体约束，CLI 错误中会包含可操作的提示，建议添加可嵌入的字体资源。
• --pdf-profile pdfua1 会启用带标签的输出和 PDF/UA-1 识别元数据。在对外声明符合性之前，应将验证器/种子跟踪信息视为机器证据。
• 即使存在 --json，argparse 用法错误仍会以代码 2 退出并输出用法文本（而非 JSON）。

相关文档

• Agent 工作流指南：llm.txt
• CLI JSON 契约快速参考：cli_schema.md
• CLI epoch/规范：CLI_EPOCH.md
• PDF 模板/XObject 组合指南：docs/pdf-templates.md
• 许可指南：LICENSING.md
• 第三方声明：THIRD_PARTY_LICENSES.md
• 动态文档示例项目：examples/living_docs_atlas/README.md
• 屋顶工程发票对照示例：examples/roofing_invoice/README.md
• 图标烟雾测试示例：examples/iconography_test/README.md
• 公开黄金回归测试套件：goldens/README.md

许可证

Fullbleed 根据 MIT License（MIT）授权。允许商业使用、 修改、分发，以及在专有软件中使用，但须遵守 LICENSE 中的 保留声明要求。

Cargo 和 PyPI 元数据均声明采用 MIT。

• 版权声明：COPYRIGHT
• 第三方声明：THIRD_PARTY_LICENSES.md
• 实用许可指南：LICENSING.md

有关许可证信息，请访问 fullbleed.dev 或发送邮件至 [email protected]。

许可证完整性门禁（适用于 CI，无需构建）：

python tools/check_license_integrity.py --json