LightCraft 资产归因管理实践:ATTRIBUTION.md 清单与 `cargo xtask assets` 强制校验机制

原创2026-10-08 13:41:372,303 阅读

LightCraft 资产归因管理实践:ATTRIBUTION.md 清单与 cargo xtask assets 强制校验机制

LightCraft 是一个用纯 Rust 实现的 Adobe Lightroom 净室(clean-room)复刻项目,这意味着它对"不能使用 Adobe 任何素材"有着极端严格的洁癖式要求。assets/ATTRIBUTION.md 就是这个约束体系的核心载体:它是仓库中每一个图片、图标、字体、声音、视频、RAW 文件与色彩配置文件的全量归因清单(attribution manifest),规定了每件资产的路径模式、作者、来源、许可证、入库日期和修改说明。读完本文,你将了解如何为开源项目建立可机审的资产版权账本:清单的表格规范如何定义、cargo xtask assets 如何把这份 Markdown 变成 CI 门禁、以及 LightCraft 对字体、公共领域照片、商标素材等典型资产的处置方式。

归因清单的定位:AGENTS.md 中的绝对规则

assets/ATTRIBUTION.md 开篇即声明其存在依据:"Every asset shipped in this repository is listed here (see the asset rules in AGENTS.md). No asset may come from Adobe products."

这条"资产规则"在项目宪法 AGENTS.md 的 "Assets: icons, images, fonts (ABSOLUTE RULE — never violate)" 一节中展开,要点如下:

  • 禁止任何 Adobe 资产:不允许使用 Lightroom/Creative Cloud 的图标、截图、预设、配置文件、LUT、UI 位图——即使只作为临时占位符或"参考副本"也不行。观察 Adobe 界面以模仿其布局与行为是被允许的,但复制或描摹其资产不是;
  • 包括 Adobe 的开源资产也禁止:Source Sans/Serif/Code、Source Han 等字体(即使它们是 OFL 许可)、Adobe Fonts、Adobe 发布的图标集、示例照片、色彩配置文件或 LUT,一律不用;
  • 每个资产必须有一张许可证牌:只允许自研原创(如代码中用矢量路径绘制的图标、程序生成的演示照片)、公共领域/CC0、Creative Commons(需遵守署名)、OFL(字体)、宽松开源许可(MIT/Apache-2.0/BSD/ISC),或由创作者开放授权的贡献;
  • 每个资产必须有 ATTRIBUTION.md 条目(路径、标题、作者/创作者、来源 URL 或 "original work"、许可证、加入日期、修改说明),需要时还须附带许可证文本文件(如 assets/fonts/OFL-*.txt)。条目必须与资产在同一个 commit 中加入,没有归因条目的资产不得提交;
  • 唯一例外是 docs/brand/:那里的 ArtCraft 名称与标志是商标而非开源,条款见 docs/brand/LICENSE-brand.txt;
  • 字体存放在独立仓库(craft-fonts),本仓库不提交字体文件(Inter 是已有例外);
  • 机器强制:cargo xtask assets 会在上述任一条件被破坏时使构建失败,并且"永远不要为了过 CI 而削弱这个检查——要么修正归因,要么移除资产"。

清单结构:七列表格与路径模式语法

assets/ATTRIBUTION.md 的主体是一张七列 Markdown 表格,列定义为:Path | Asset | Creator | Source | Licence | Added | Modifications。其中 Path 列的写法有一套受限通配语法,它不是任意 glob,而是被校验器精确实现的子集:

  • * 匹配任意个非 / 字符(例如 assets/fonts/Inter-*.ttf 不会跨目录匹配);
  • 以 / 结尾的模式覆盖整个目录(例如 crates/scenes/ 匹配其下所有文件)。

这套语法在 xtask/src/assets.rs 的 glob 函数中被实现(约 L20-L33),核心是一条递归规则:遇到 * 时"要么跳过它继续匹配,要么消耗路径中一个非 / 字符";以 / 结尾的模式则要求剩余路径以下一字符为 / 开头,从而保证不会把 crates/scenes/ 误匹配到 crates/scenesx/。对应的单元测试 xtask/src/assets.rs 直接验证了这两个边界:

assert!(glob("docs/images/*-tetons.jpg", "docs/images/ba-tetons.jpg"));
assert!(!glob("docs/images/*.jpg", "docs/images/sub/x.jpg"));   // * 不跨目录
assert!(glob("crates/scenes/", "crates/scenes/a/b.png"));
assert!(!glob("crates/scenes/", "crates/scenesx/b.png"));       // 前缀不误伤

当前仓库的完整归因表

以下是 assets/ATTRIBUTION.md 中登记的全部资产条目(原文档骨架内容,逐行继承):

Path Asset Creator Source Licence Added Modifications
assets/fonts/Inter-*.ttf(Regular, Medium, SemiBold) Inter Rasmus Andersson SIL Open Font License 1.1(许可文本见 assets/fonts/OFL-Inter.txt) 2026-09-30 none
assets/app-icon/(lightcraft.svg 及其衍生的 PNG/ICNS/ICO/SVG 文件) LightCraft 应用图标(猞猁) LightCraft 项目所有者(绘制于 ArtCraft) 原创作品(矢量化的所有者手绘稿,见 assets/app-icon/README.md) MIT OR Apache-2.0(assets/app-icon/LICENSE.txt) 2026-10-02 矢量化为 SVG;由 packaging/icons.sh 渲染为 PNG/ICNS/ICO
assets/camera-profiles/*.json 相机色彩配置文件(矩阵 + 色相/饱和度/明度表),内建于 LightCraft ILCE-7M4:Harald Hoyer 原创作品:由 lightcraft-cli calibrate 针对贡献者本人的 RAW 照片与其机内 JPEG 拟合(597 张 ILCE-7M4 照片,2026);仅聚合色彩统计,无图像内容;不含任何 Adobe 或第三方配置文件数据 MIT OR Apache-2.0 2026-10-07 none
crates/scenes/(生成的图像) 程序化演示照片 LightCraft 贡献者 原创作品(运行时生成,无源图像) MIT OR Apache-2.0 2026-09-30 n/a
crates/ui-egui/src/icons.rs 以代码中矢量路径绘制的 UI 图标 LightCraft 贡献者 原创作品 MIT OR Apache-2.0 2026-09-30 n/a
docs/images/*-tetons.jpg、docs/images/grid-pd.jpg(包含它的截图) "The Tetons and the Snake River" Ansel Adams(1942),美国国家档案馆 公共领域(美国联邦政府作品) 2026-09-30 在 LightCraft 中显影;出现在应用截图中
docs/images/*-migrant-mother.jpg、docs/images/grid-pd.jpg "Migrant Mother" Dorothea Lange(1936),美国农业部 FSA / 国会图书馆 公共领域(美国联邦政府作品) 2026-09-30 在 LightCraft 中显影;出现在应用截图中
docs/images/*-earthrise.jpg、docs/images/grid-pd.jpg "Earthrise"(AS08-14-2383) NASA / Bill Anders,阿波罗 8 号(1968) 公共领域(NASA) 2026-09-30 在 LightCraft 中显影;出现在应用截图中
docs/images/*-blue-marble.jpg、docs/images/grid-pd.jpg "The Blue Marble"(AS17-148-22727) NASA,阿波罗 17 号乘组(1972) 公共领域(NASA) 2026-09-30 在 LightCraft 中显影;出现在应用截图中
docs/images/*.jpg(UI) LightCraft 应用截图 LightCraft 贡献者 原创作品(使用 docs/showcase/ 工具截取) MIT OR Apache-2.0 2026-09-30 n/a
docs/brand/(artcraft-logo 与 artcraft-mark,SVG 和 PNG) ArtCraft 字标与标志 ArtCraft Team 原创作品 ArtCraft 商标,见 docs/brand/LICENSE-brand.txt(非开源) 2026-10-01 none
craft-fonts:可选构建输入,不是本仓库中的文件 BIZ UDPGothic(Regular, Bold)、BIZ UDMincho Regular、Shippori Mincho Regular 森泽株式会社 / BIZ UDGothic 与 BIZ UDMincho 项目作者;Shippori Mincho 项目作者(依 craft-fonts 的归因) SIL Open Font License 1.1(每个字体在 craft-fonts 中的 OFL.txt;发布包中携带为 OFL-<family>.txt) 2026-10-06 仅在以 CRAFT_FONTS_DIR 构建的版本中内嵌(所有官方发布版);web(wasm32)构建仅内嵌 BIZ UDPGothic Regular

原文档末尾还有两条 Notes,它们解释了表格外同样重要的政策:

  • Adobe 创作或发布的字体(Source Sans/Serif/Code、Source Han 等)即使带有 OFL 许可也不使用——资产规则排除一切 Adobe 产物。Source Sans 3 已于 2026-09-30 被移除并替换为 Inter;
  • 日文字体(BIZ UDPGothic、BIZ UDMincho、Shippori Mincho)不在本仓库中,而是存放在独立的 craft-fonts 仓库,仅在通过可选构建输入 CRAFT_FONTS_DIR 构建的版本中被内嵌(所有官方发布版)。永远不要把字体文件提交到本仓库;新字体应加入 craft-fonts。

机审实现:cargo xtask assets 的校验逻辑

归因文档不是"君子协定",它由 xtask/src/assets.rs 编译成硬门禁。该模块的文件头注释直接引用了 AGENTS.md 的规则来源:"Asset attribution check (AGENTS.md 'Assets' rule)"。整个检查由四部分构成。

1. 资产范围:扩展名白名单

ASSET_EXT(xtask/src/assets.rs)列出了被视为"资产"的所有小写扩展名:

const ASSET_EXT: &[&str] = &[
    "png", "jpg", "jpeg", "gif", "webp", "avif", "svg", "ico", "icns", "bmp",
    "ttf", "otf", "woff", "woff2", "wav", "mp3", "ogg", "flac", "mp4",
    "mov", "tif", "tiff", "dng", "cr2", "cr3", "nef", "arw", "raf", "orf",
    "rw2", "rwl", "raw", "pef", "heic", "jxl", "psd", "cube", "icc", "icm",
    "xmp",
];

覆盖面从 UI 素材(png/svg/字体)到本产品的核心业务数据格式(DNG/CR3/NEF 等 RAW、ICC 色彩配置、XMP 元数据、PSD、立方体 LUT),说明该校验是围绕"图像管理软件会接触到的一切二进制素材"设计的。非这些扩展名的文件直接跳过。

2. 两条"一票否决"规则:禁止格式与禁止命名

/// Adobe-specific formats we never ship (camera/lens profiles, Lightroom templates).
const FORBIDDEN_EXT: &[&str] = &["dcp", "lcp", "lrtemplate", "lrcat", "lrsmcol", "aco", "ase", "abr"];
const FORBIDDEN_NAME: &[&str] = &["adobe", "lightroom", "photoshop", "creative cloud", "creativecloud"];
  • 任何 .dcp(相机配置文件)、.lcp(镜头配置文件)、.lrtemplate 等 Adobe 专有格式出现即失败——这些格式本身"看起来就像来自 Adobe",无论内容如何都拒绝入库;
  • 文件名包含 adobe、lightroom、photoshop、creative cloud 等字样即被标记为 "asset name suggests Adobe material"。

这两条规则与"禁止 Adobe 资产"的总纲互为表里:前者封死格式通道,后者封死命名通道(防止有人用改名方式混入)。

3. 归因覆盖与许可证文件存在性检查

check 函数(xtask/src/assets.rs)对 git 追踪的每个资产文件依次判定:

  1. 若命中 FORBIDDEN_EXT → 直接报错 ".{ext} files (Adobe profile/template formats) must never be committed";
  2. 扩展名不在 ASSET_EXT 中 → 跳过(非资产);
  3. 文件名命中 FORBIDDEN_NAME → 报 Adobe 材质嫌疑;
  4. 没有任何 ATTRIBUTION.md 路径模式匹配该文件 → 报 "no entry in assets/ATTRIBUTION.md (add path, creator, source, licence, date, modifications)"。

随后还做一遍反向校验:解析表格里 Licence 列(第 5 列)中反引号包裹的路径(parse 函数从每行取 cells[0] 与 cells[4] 中的 backtick 片段),逐一确认许可证文件真实存在,否则报 "references missing licence file"。这防止了"条目写了 assets/fonts/OFL-Inter.txt 但文件其实没提交"的账实不符。

4. 文件来源:git ls-files 而非文件系统遍历

入口 run 函数(xtask/src/assets.rs)通过

Command::new("git").args(["ls-files", "--cached", "--others", "--exclude-standard"])

枚举文件,保证检查的是"将被提交的视角"(已暂存 + 未忽略的新文件),同时过滤掉不在磁盘上的陈旧条目。全部通过时输出统计行:

assets: {n} asset files, all attributed

模块内还有第二个单元测试 flags_unattributed_forbidden_and_missing_licence(xtask/src/assets.rs),用一个迷你表格验证四类报错:无归因条目(assets/icons/x.svg)、禁止格式(p/camera.dcp)、Adobe 嫌疑命名(assets/fonts/Adobe-Foo.otf)、缺失许可证文件(OFL-Foo.txt),同时确认已归因文件、目录模式覆盖文件与 .rs 源码都不会误报。

在 CI 流水线中的位置

cargo xtask assets 是 cargo xtask ci 七个步骤之一。从 xtask/src/main.rs 的 cmd_ci 可以看到步骤顺序:

fmt → clippy (-D warnings) → test → parity → layers → assets → wasm

任一步失败即中止并打印 "CI summary"(ok/FAIL/skip 三个分区)。AGENTS.md 将其表述为质量门禁:"Quality gates before every commit: cargo xtask ci (fmt, clippy -D warnings, tests, layers, assets, wasm)"。因此资产合规不是发布前的抽检,而是每次提交的必经之路——这恰是"净室项目资产纪律"能够长期维持的关键:靠人自觉必然腐化,靠 CI 才能把规则变成不变式。

三类典型资产的处置细节

结合归因表与相关源码,可以看 LightCraft 对几类高风险资产的具体处理方式。

字体:仓库内 Inter + 仓库外 CRAFT_FONTS_DIR

Inter 三个字重(assets/fonts/Inter-Regular.ttf 等)带 OFL 许可文本 assets/fonts/OFL-Inter.txt,在仓库内闭环管理。日文字体则完全走"外部构建输入"模式:crates/engine/build.rs 在设置 CRAFT_FONTS_DIR 时把 craft-fonts 仓库中的字体内嵌为 lightcraft_engine::CRAFT_FONTS(wasm32 构建只嵌 BIZ UDPGothic Regular),未设置时该列表为空——构建、测试照常运行,只是日文字形缺失,相关测试自动跳过。发布打包脚本(如 packaging/windows/package.ps1、packaging/env.sh)会检测 CRAFT_FONTS_DIR 并把各字体的 OFL.txt 以 OFL-<family>.txt 随发布包分发。这条"字体不入仓库、许可随包发布"的链路在 NOTICE 中同样有对应声明。

应用图标:单源 SVG + 脚本再生成

归因表把 assets/app-icon/ 整个目录作为一条记录,Licence 列指向 assets/app-icon/LICENSE.txt(MIT OR Apache-2.0)。assets/app-icon/README.md 补充了来源细节:猞猁图标是项目所有者在 ArtCraft 中的手绘稿(2880 px,三色键控:墨色 #0b0b0c、纸色 #efe9dc、LightCraft 琥珀 #f2a516),矢量化为 lightcraft.svg 后成为唯一权威源;packaging/icons.sh 从该 SVG 用 resvg 渲染出 16–1024 px 的全套 PNG、hicolor 主题目录、.ico(经 cargo xtask ico 打包)与 .icns(iconutil)。所有输出均提交入库,"so building and packaging never need these tools"——这正是归因表中 "rendered to PNG/ICNS/ICO by packaging/icons.sh" 修改说明的落地。

公共领域照片与商标

docs/images/ 下的四张历史照片(Ansel Adams 的 Tetons、Dorothea Lange 的 Migrant Mother、NASA 的 Earthrise 与 Blue Marble)全部为美国联邦政府/公共领域作品,且 Modifications 列统一注明"developed in LightCraft"——即截图里展示的是用本软件处理后的效果,素材本身零版权风险。而 docs/brand/ 是唯一的非开源例外:ArtCraft 商标明确"not open source",只许原样使用、禁止再绘制或派生,条款见 docs/brand/LICENSE-brand.txt;NOTICE 也把这一点独立成段重申。

另一个值得注意的条目是 assets/camera-profiles/*.json:相机色彩配置文件(当前仓库内为 assets/camera-profiles/ILCE-7M4.json,包含 3×3 颜色矩阵与 72×5×5 的色相/饱和度/明度查找表,由 597 张 ILCE-7M4 照片拟合而成)被归因声明特别标注为"aggregate colour statistics only, no image content; no Adobe or third-party profile data"——在净室语境下,配置文件是最容易被质疑的资产类别,因此归因条目主动交代了数据来源、生成工具(lightcraft-cli calibrate)与样本规模,把"这不是 Adobe DCP"作为可审计事实写进清单。

对开源项目的可借鉴之处

LightCraft 的这套机制可以概括为四个可复用的设计点:

  1. Markdown 表格即数据库:归因清单是人类可读的 Markdown,但列结构固定(Path 列与 Licence 列被机器解析),不需要额外的数据库或 YAML 副本,单一事实来源;
  2. 受限通配而非完整 glob:只实现 *(不跨目录)与尾斜杠目录两种模式,语义无歧义,校验器几十行即可穷尽,测试直接断言边界行为;
  3. 正向覆盖 + 反向存在性双查:既查"文件有无条目",也查"条目引用的许可证文件是否存在",双向堵住账实不符;
  4. 格式级与命名级黑名单前置:.dcp/.lcp 等 Adobe 专有格式与 Adobe 系命名在进入归因匹配之前就被一票否决,把最危险的合规风险压缩成两条常量表。

配合"条目与资产同 commit 提交"的流程约束和 cargo xtask ci 的流水线强制,这份 assets/ATTRIBUTION.md 从一份文档变成了项目资产供应链上的不变式:任何新素材想入库,要么先写清它的来源与许可,要么被 CI 拦下。

登录后查看全文
lightcraft