开源项目怎么证明“每个素材都有户口“？EffectCraft 把资产溯源做成 CI 硬规则

开源项目怎么证明"每个素材都有户口"？EffectCraft 把资产溯源做成 CI 硬规则

【免费下载链接】effectcraft项目地址: https://gitcode.com/gh_mirrors/ef/effectcraft

一个对标 After Effects 的开源合成器，最危险的从来不是"功能还没做齐"，而是某天仓库里混进一张来源不明的图标、一份截图、一个字体文件。功能缺陷可以被 issue 追踪，素材版权风险却可能让整个项目一夜之间失去法律与信任的双重立足点。EffectCraft 的答案是：把"每个素材都有户口"从口头约定升级为一条 CI 硬规则——任何图片、字体、图标、模型权重，只要缺作者、缺来源、缺许可证，合并请求就直接失败。本文以仓库真实源码为依据，拆解这套资产登记与校验机制的全貌。

一、为什么"素材有户口"是开源项目的生死线

EffectCraft 是一个用纯 Rust 从零实现的动态图形与视觉特效合成软件，内置 306 个特效、完整的图层/关键帧/3D 相机灯光/渲染队列工作流，支持 macOS、Windows、Linux 与浏览器端，采用 MIT OR Apache-2.0 双许可。它有一个非常特殊的出身：clean-room（净室）重写——对标 After Effects，但代码完全独立编写，且明确禁止读取、反汇编或复制 Adobe 应用内部的任何内容，也禁止复制 GPL/LGPL/AGPL 代码（参见 AGENTS.md §2）。

这意味着项目对"素材来源"异常敏感：UI 图标不能用 Adobe 的，截图不能拍到 Adobe 产品，连字体、LUT、预设模板都必须是开放许可。正因如此，AGENTS.md §1 把资产规则定义为"绝对规则"（This rule is absolute. Breaking it is the most serious mistake a contributor can make on this project.），并把适用范围划得很宽：不仅包括仓库里的媒体文件，还包括include_bytes!嵌入代码的字节、base64/data URI，甚至"照着别人图标描出来的点列表"。规则优先级高于一切功能开发。

二、双层登记：Sidecar 细颗粒 + ATTRIBUTION.md 全局索引

EffectCraft 的资产登记采用"文件级 sidecar + 仓库级索引"的双层结构，保证每个素材既能在本地查到明细，又能在全局一览无余。

第一层：每个资产文件旁挂一个同名.attributionsidecar。例如 assets/fonts/Inter-Regular.ttf.attribution：

asset: Inter-Regular.ttf title: Inter Regular (UI typeface) author: The Inter Project Authors (Rasmus Andersson et al.) source: https://github.com/rsms/inter license: OFL-1.1 license-file: assets/fonts/OFL-Inter.txt added: 2026-10-01 by Claude (agent) for Brandon Thomas (copied from FilmCraft) notes: Unmodified font file, embedded via include_bytes! in the text engine (crates/text/src/fonts.rs)...

字段虽然只有短短几行，信息却相当完整：作者、来源 URL、SPDX 许可证 ID、许可证全文路径（OFL 等要求随包分发许可证文本）、登记人、登记日期，连"这个字体是通过include_bytes!嵌入文本引擎"这种使用方式都写进 notes——这正是 AGENTS.md §1 定义的"字节也算资产"的落地体现。

第二层：ATTRIBUTION.md 全局索引。仓库根目录的这份清单以表格登记每个资产的Asset | Author | Source | Licence四要素，并把资产分门别类：

• Asset files：字体、应用图标各尺寸派生图、Lottie/SVG/glTF/OBJ 测试夹具等 44 项；
• Screenshots：只允许展示 EffectCraft 自身（由渲染器无头渲染的程序化演示内容），杜绝"截图里出现 Adobe 产品"；
• Code-drawn assets：代码绘制的 UI 图标（crates/ui-egui/src/icons.rs）、程序化演示内容、内置模板等，统一声明为项目原创（MIT OR Apache-2.0）；
• Trained models：MobileSAM、MediaPipe Face Landmarker 等模型权重不随仓库与安装包分发，仅在用户主动请求时从作者官方地址按固定 SHA-256 校验下载，并在用户目录生成<file>.NOTICE.txt；
• First-party brand marks：ArtCraft 商标是唯一的"非开源例外"，单独受 docs/brand/LICENSE-brand.txt 约束，且明确规定 fork 版本必须移除。

这套登记甚至延伸到了二进制分发环节：NOTICE 文件在声明项目双许可的同时，逐项列出随包分发的第三方材料及其许可证文件位置，与 ATTRIBUTION.md 形成"源码可查、产物可审"的闭环。

三、cargo xtask assets：让缺失登记直接杀死 CI

登记机制写得再好，如果靠人肉检查，迟早会出现漏网之鱼。EffectCraft 把这条规则编码成了程序。仓库用 .cargo/config.toml 定义了别名：cargo xtask等价于cargo run --quiet --package xtask --，校验器本体位于 xtask/src/main.rs 的assets()函数。

校验器先定义"什么算资产"——一张覆盖 45 种扩展名的黑名单式清单（ASSET_EXT）：图片类 png/jpg/svg/ico/icns/exr，字体类 ttf/otf/woff2，调色类 cube/3dl/lut，音视频类 wav/mp3/webm/mov，以及 PSD/AEP 等工程文件格式。然后对仓库里每个这类文件依次施加检查：

// xtask/src/main.rs（assets() 核心逻辑，已略去细节） for f in files.iter().filter(|f| is_asset(f)) { if lower.contains("adobe") || lower.contains("aftereffects") { errors.push(format!("{f}: asset paths must not reference Adobe/After Effects")); } match std::fs::read_to_string(&side) { Err(_) => errors.push(format!("{f}: missing attribution sidecar {side}")), Ok(text) => { // 必需字段必须存在且非空：asset/title/author/source/license/added // 许可证不得含 -nc / -nd / adobe / proprietary } } if !index.contains(&format!("`{f}`")) { errors.push(format!("{f}: not listed in ATTRIBUTION.md")); } }

可归纳为五重硬检查：路径检查（资产路径不得含 Adobe/After Effects 字样）、sidecar 存在性（每个资产必须有一个.attribution伴生文件）、字段完整性（asset/title/author/source/license/added六个字段缺一即错）、许可证合法性（NC/ND 类 CC、Adobe、专有许可证一律拒绝）、索引覆盖（资产必须以反引号形式出现在 ATTRIBUTION.md 中）。此外还有一道反向检查：孤儿 sidecar（对应资产文件不存在）同样报错，防止删除资产时留下过期登记。

任何一项不满足，assets()都返回Err，进程以ExitCode::FAILURE退出。而它并不是孤立存在的——xtask/src/main.rs 的ci()把fmt --check、clippy -D warnings、全量测试、分层校验（layers）、资产校验（assets）与 wasm 编译检查串成一条命令，也就是 CONTRIBUTING.md 里写死的"每个提交前必须通过cargo xtask ci"。全绿时输出assets: ok (44 assets attributed)这样的计数结果；一旦有素材失联，CI 当场红掉。

四、治理红利：可信度、可审计与可规模化

把资产溯源做成 CI 硬规则，收获的不只是一份干净的清单。

对下游使用者，这是可审计的信任凭证。你拿到的每个二进制，都能在 NOTICE 与 ATTRIBUTION.md 里反查到每一个字体、图标、模型的作者与许可证全文位置；OFL 字体带许可证文本随包分发，模型权重由 SHA-256 钉死来源，不存在"装完不知道里面混了什么"的黑箱。

对贡献者（尤其是 AI 代理），这是零成本的低摩擦护栏。AGENTS.md 明言规则约束每个"人类和 AI 贡献者"，并给出处理歧义的最终裁决：When in doubt, leave it out——拿不准就直接不引入，自己画或自己生成。配合"最大错误"的定性，新贡献者不需要反复判断"这张图能不能用"，只需要过一遍校验器。

对长期生态，这套机制与项目的其他工程纪律是同构的：crate 分层有cargo xtask layers把关，wasm 构建有cargo xtask wasm把关，资产溯源则有cargo xtask assets把关——三者在ci中合并为统一的提交门槛。资产规则和 clean-room 代码规则互相咬合，共同支撑起"无 FFmpeg、纯 Rust 编码器、无遥测、无强制联网"这些对外承诺的可信度。对一个立志成为 After Effects 开源替代的项目来说，能力可以被追赶，而"每一个字节都来路清白"的纪律，才是最难复制的那部分资产。

【免费下载链接】effectcraft项目地址: https://gitcode.com/gh_mirrors/ef/effectcraft