材质库来源与设计：工程材料与显示外观的统一身份

状态：Research Note 版本：0.1.0 日期：2026-09-09 研究问题：Aira 要让 AI 给模型指定材料，并据此校验质量、成本与显示，材质库应该怎么建？哪些外部资料可以直接复用，各自的许可、数据形态与质量边界在哪？工程材料与显示外观应当合并还是分开？对应文档：产品宪法、AMIR v0.1、RFC-0005 导出边界与损失证书、CAD 基线与维护边界前置调研：标准件库来源搜集、开源底座与自研实现重叠审计

本文只做来源判定与结构设计，不改变当前产品目标，也不授权任何实现或依赖引入。仓库此前没有任何材料相关记录：docs/ 全文检索中“材料”只出现在“布尔运算移除材料”、“发布材料”、 “超材料”等无关语境，模型侧（artifact-graph、aira-store、exact-cad-plan）没有材料概念。本文是这条线上的第一份证据。

1. 结论摘要

工程材料与显示外观必须一起做，但耦合点只有一个：材料身份。 这不是设计偏好，而是上游已验证的结构—— FreeCAD 的物性卡通过 Inherits 挂到外观卡的 UUID 上（证据见 §3.1）。分开做的代价是两套目录、两套命名，再加一张映射表，正好是 AGENTS.md 要求消除的重复机制。
⚠️ 许可判定修正：FreeCAD 标准材料卡不是“基本 CC-BY”。 逐卡实测 140 张： LGPL 115 张、CC-BY 21 张、CC-BY-SA 4 张。抽样 3 张得出的“CC-BY 为主”结论是错的（§4.1）。
风险恰好落在最想要的地方：金属牌号库几乎全是 LGPL。 Steel 91/93、Copper 16/16、Aluminum 4/6 是 LGPL；可直接用的 CC-BY 子集是塑料、玻璃、混凝土、木材，加 4 张关键金属 （Steel-Generic、CalculiX-Steel、Aluminum-6061-T6、Aluminum-7075-T6）。
外观层用 physically-based-api（CC0-1.0）： 86 条、69 KB，字段 color/metalness/roughness/ior/specularColor/density 与 THREE.MeshPhysicalMaterial 一一对应，无署名义务。不要用 FreeCAD 的 Appearance 卡—— 它是 OpenInventor 时代的 AmbientColor/DiffuseColor/Shininess 模型，不是 PBR（§5.2）。
mass 是这条线上杠杆最高的产物，且几何成本为零：体积已由 OCCT GProp 提供， ExactCadExpectation 已有 volume，加 mass = density × volume 不需要任何新几何代码，却让 AI 的声明第一次可以被独立于源码地校验。
交换边界比预期窄：sealed WASM 只绑定了 XCAFDoc_ShapeTool/ColorTool/STEPCAFControl_Writer， XCAFDoc_MaterialTool（物性）与 XCAFDoc_VisMaterialTool（PBR）都没有绑定。今天 STEP 只能带名称与颜色；3MF 侧导出器连 Materials 扩展都还没有（§6）。
数据不能直接搬运，必须过闸门：实测 6 张卡的 YieldStrength > UltimateTensileStrength， 3 张用逗号小数（"1200,00 kg/m^3"），ThermalConductivity 只有 39/140 覆盖（§4.3）。
token 上的关键决定是“目录不进 prompt”：140 张卡全文 158 KB ≈ 40k+ token/次；复用 aira_library_reference 的离线生成加按需检索模式后，单次查询约 200–400 token（§7.4）。
边界：数据全部外部导入，Aira 只自研“材料↔实体的绑定语义与守恒”——这恰好是所有上游都没有的部分。

2. 分层框架

层	内容	判定要点
L1 物性数据	密度、弹性、强度、热、成本	许可能否并入分发物；数值语义是否自洽；覆盖率
L2 外观数据	基色、金属度、粗糙度、IOR	是否 PBR；能否直接喂给现有 Three.js 材质
L3 身份与继承	类（Steel）→ 牌号（C22E）的稳定 id	一个 id 能否同时决定 L1 与 L2
L4 绑定与守恒	材料挂在哪个实体上	是否进 AMIR 文档；撤销/重做、保存重开、编辑守恒
L5 派生与校验	质量、成本、可制造性断言	能否被 host 独立测量并否决
L6 交换	STEP / 3MF / glTF	内核绑定是否具备；损失是否可申报

分层的意义与标准件库调研 §2 相同：混在一起谈会把“可复用的数据层”和“必须自研的绑定层”判成同一件事。

3. 为什么必须一起做

3.1 上游证据：FreeCAD 用同一个 UUID 把物性挂在外观上

Materials/Standard/Metal/Aluminum/Aluminum-6061-T6.FCMat（物性卡）声明：

Inherits:
  Aluminum:
    UUID: "d1f317f0-5ffa-4798-8ab3-af2ff0b5182c"

而 Materials/Appearance/Aluminum.FCMat（外观卡）的 General.UUID 正是 d1f317f0-5ffa-4798-8ab3-af2ff0b5182c。同样的对应关系在 CalculiX-Steel → Appearance/Steel（4b849c55-6b3a-4f75-a055-40c0d0324596）与 Default → Appearance/Default（5dbb7be6-8b63-479b-ab4c-87be02ead973）上成立。 140 张标准卡中 121 张带 Inherits。

结论：上游不是“两个库”，而是一条继承链上的两组模型（Models 与 AppearanceModels）。用户直觉正确，而且耦合的具体位置也由上游给定了：在身份/继承层，不在属性层。

3.2 但生命周期不耦合

维度	是否耦合	说法
身份	耦合	一个 `materialId` 同时决定物性与外观；否则要维护第二张映射表
AI 接口	耦合	模型只说一次“6061 铝”；外观若独立指定，既费 token 又可能与材料自相矛盾
导出	耦合	3MF `<basematerials>` 与 STEP XDE 都是“名称+颜色”同一条记录
权威与持久化	不耦合	物性进 AMIR 文档（撤销/重做、保存重开、守恒）；外观是 RenderPacket 上的投影，每次派生，不单独持久化、不单独授权
许可与署名	不耦合	物性来自 CC-BY/LGPL 混合来源，外观来自 CC0；署名义务必须逐行可分，不能合并成一条

这条正好复用仓库既有原则：AGENTS.md 的 “UI 是同一能力的交互投影，不另建执行管线”。外观是材料能力的显示投影，不是第二种材料。

3.3 Aira 的落法：类承载外观，牌号承载物性

class（Steel / Aluminum / Copper / Brass / Plastic / Wood / Glass …）→ 外观（CC0 来源）
grade（Steel-C22E / Aluminum-6061-T6 / PLA …）→ 物性（逐条来源与许可）
materialId = 牌号；外观沿 class 派生，缺牌号时退到类默认值

这与 FreeCAD 的 Inherits 同构，只是把父类的外观从 OpenInventor 换成 PBR。好处是 CC0 外观集只需 ~15 条就能覆盖全部牌号，不随牌号数量增长。

4. L1 物性数据源

4.1 FreeCAD 标准卡的许可分布（逐卡实测，140/140）

数据取自 FreeCAD/FreeCAD@main 的 src/Mod/Material/Resources/Materials/Standard/**，共 140 张、158,326 字节、平均 1,130 字节。

族	CC-BY-3.0/4.0	CC-BY-SA-4.0	LGPL-2.0/2.1-or-later	合计
Metal/Steel	2	–	91	93
Metal/Copper	–	–	16	16
Metal/Aluminum	2	–	4	6
Metal/Alloys、Iron、Titanium	–	–	3	3
Carbon	–	–	1	1
Thermoplast	9	4	–	13
Glass	3	–	–	3
Aggregate	3	–	–	3
Wood	1	–	–	1
Default（根）	1	–	–	1
合计	21	4	115	140

作者分布解释了这个结构：93 张由 M. Münch 贡献的 DIN/EN 钢与铜牌号是 LGPL-2.0-or-later， CC-BY 部分主要来自早期贡献者（Juergen Riegel、Uwe Stöhr、Bernd Hahnebach 等）。

可直接使用的 CC-BY 清单（21 张）： ABS、PLA、PET、PA6、PP、PTFE、PVC、PC-Molded、Acrylic-Glass（以上 Thermoplast，CC-BY-3.0）、 Glass-Generic、Glass-E-GlassFibre、Glass-S2-GlassFibre、Concrete-Generic、Concrete-EN-C35_45、 Reinforcement-FIB-B500、Wood-Generic、Steel-Generic、CalculiX-Steel（CC-BY-3.0）、 Default、Aluminum-6061-T6、Aluminum-7075-T6（CC-BY-4.0）。另有 4 张 CC-BY-SA-4.0：PEEK、PMMA、POM-Copolymer、POM-Homopolymer。

关于 LGPL 数据卡的判断：与标准件调研 §3 对 FreeCAD Fasteners WB（GPL-2.0 数据）的判断一致——把这些文件或其批量转换结果并入专有分发物存在传染性风险，不能默认可用。需要注意两点：

单个数值（“7900 kg/m³”）是事实，多数法域不因许可而受版权保护；受保护的是选择与编排（汇编）与描述性文本。
但欧盟数据库指令（96/9/EC）的 sui generis 权利保护对数据库的实质性提取，即使内容本身是事实。逐条取用与整库转换在这一点上不是同一件事。
因此本文的建议是：LGPL 卡只作交叉核对来源，不做批量转换；是否可用属于法务判断，本文不下结论。[待验证]

其他 FreeCAD 资产：

资产	许可	判定
`Resources/Models/*.yml`（属性本体：Density、IsotropicLinearElastic、Thermal、Hardness、Toughness、Costs、Machinability、Electromagnetic）	LGPL-2.1-or-later（文件头 SPDX）	只借鉴属性命名与分组，不复制文件
FreeCAD/Supplemental-Materials	CC-BY-SA-4.0	❌ 传染性 share-alike，除非愿意把派生材料库以 CC-BY-SA 发布
`Materials/Appearance/*.FCMat`（23 张）	CC-BY-4.0	见 §5.2，非 PBR，不采用数值

4.2 属性覆盖率（140 张标准卡）

属性	覆盖	属性	覆盖
`Density`	140	`ThermalExpansionCoefficient`	132
`YoungsModulus`	137	`ThermalConductivity`	39
`UltimateTensileStrength`	132	`SpecificHeat`	39
`YieldStrength`	125	`SourceURL`	30
`PoissonRatio`	122	`ProductURL`（成本入口）	22

模型使用频次：LinearElastic 133、Thermal 132、MaterialStandard 118、Costs 22、 Electromagnetic 20、Hardness 16、Toughness 15。

判读：密度 100% 覆盖 → mass 派生对全库成立；力学属性 ~90% → 强度类断言要允许“该牌号无此数据”；热属性只有 28% → 热相关能力不能假定有数据；成本几乎为空（22 张只是外链，不是价格）→ 成本估算不能靠这个库。

4.3 数据质量陷阱（实测）

6 张卡 YieldStrength > UltimateTensileStrength：ABS(44.1/38.8)、Acrylic-Glass(73.7/57.7)、 PET(62.8/38.8)、PLA(35.9/26.4)、POM-Copolymer(59.8/56.5)、POM-Homopolymer(67.3/63.8)。对金属这是矛盾值；对热塑性塑料，可能是“屈服应力 vs 断裂应力”的语义差异。无论哪种，直接当作许用应力上界使用都是错的——所以导入闸门要做的是语义校验，不是数值搬运。并且这 6 张全部落在我们最想用的 CC-BY 塑料子集里。
3 张卡使用逗号小数：PC-Molded（"1200,00 kg/m^3"）、AlZn4-5Mg1F35、PEEK-Generic。
Reinforcement-FIB-B500 有 YieldStrength 而 UltimateTensileStrength 为空。
单位以字符串携带（"210000 MPa"、"0.0000236 m/m/K"），混用 MPa/GPa/kPa。

4.4 其他 L1 来源

来源	内容	许可	判定
NIST 材料数据（SRD 150、TRC Alloy Data、Materials Data Repository）	权威物性汇编，有 REST/JSON 访问	美国政府作品，公有领域	✅ 关键牌号的权威值与交叉核对；无署名义务。API 具体可用字段 [待验证]
MatML 3.1（NIST / ASTM E49）	材料属性交换 XML	开放规范	⚪ 只作互操作参考。2004 年定稿，不适合做内部模型
ISO 10303-45 / STEP AP242 材料	交换中的材料表示	标准（付费）	⚪ 只在 §6 的交换判定中相关
MatWeb / ASM Alloy Center / Total Materia / MakeItFrom	牌号数据	专有 ToS	❌ 不抓取、不导入。注意 FreeCAD 有 30 张卡的 `SourceURL` 指向 matweb/ASM（如 `Aluminum-6061-T6`）——数值是事实，但必须保留 FreeCAD 的署名链
OrcaSlicer / PrusaSlicer 耗材配置	FDM 耗材参数	AGPL-3.0	❌ 不复制配置数据；FDM 材料改用 CC-BY 的 Thermoplast 卡加厂商 TDS

5. L2 外观数据源

5.1 physically-based-api（推荐）

许可 CC0-1.0（无署名义务，可直接并入分发物）
规模：86 条、69,037 字节；Metal 30、Manmade 13、Organic 10、Human 10、Crystal 9、Liquid 8、Plastic 6
工程相关条目：Aluminum、Brass、Copper、Iron、Stainless Steel、Titanium、Zinc、Nickel、 Chromium、Lead、Magnesium、Gold、Silver、Plastic (Acrylic/PC/PET/PP/PUR/PVC) 等 ~40 条
每条都带 sources 外链（refractiveindex.info、论文、Wikipedia），来源可追溯

字段映射（无需转换层）：

physically-based	Three.js	备注
`color`（线性 sRGB 三元组）	`MeshPhysicalMaterial.color`	当前 `MaterialSlot.baseColorSrgb` 已是同形状
`metalness`	`.metalness`
`roughness`	`.roughness`
`ior`	`.ior`	需 `MeshPhysicalMaterial`，当前用的是 `MeshStandardMaterial`
`specularColor`	`.specularColor`	同上
`density`	—	不用于物性，只做 §4 密度的类级交叉核对

complexIor 是给离线渲染器的，Aira 不用。

5.2 为什么不用 FreeCAD 的 Appearance 卡

Appearance/Steel.FCMat 的 BasicRendering 模型是 AmbientColor / DiffuseColor / EmissiveColor / SpecularColor / Shininess / Transparency—— OpenInventor/Coin3D 的旧式 Phong 参数，不是 PBR。把它映射到 metalness/roughness 需要一层有损猜测，而 CC0 来源已经直接给出 PBR 值。只借鉴它的类目词表（Aluminum、Brass、Bronze、Copper、Steel、 Plastic、Wood、Stone…），这套词表与 physically-based 的类目高度重合，正好做 §3.3 的 class 词汇。

6. 仓库现状与接入点

位置	现状	对材质库的意义
render-packet.schema.json:243 `MaterialSlot`	只有 `slot`/`role`/`baseColorSrgb`/`opacity`	是显示槽位，不是模型上的材料；外观投影的落点，需扩 PBR 字段
render-packet-objects.ts:104	用 `MeshStandardMaterial` 消费槽位	升到 `MeshPhysicalMaterial` 才能吃 `ior`/`specularColor`
exact-cad-plan.ts:44 `expect.volume`	已有，host 独立校验	`expect.mass` 的直接模板
exact-step-exchange.ts:63	已用 OCCT `GProp` 得到 `volume`	`mass = density × volume` 无新增几何代码
tools.ts:48 `libraryReferenceTool` + `library-reference-data.ts`（424 KB 生成物）	离线生成 + 按需检索 + 分页/批量	材料检索照抄这个模式；符合“不得另建查询执行器”
assemblyExporter.ts:46 `createAssembly`	已用 `XCAFDoc_ShapeTool`/`ColorTool` 写名称与颜色	STEP 侧已有名称/颜色通道
aira-occt-feature-graph.yml:233-244	绑定 `XCAFDoc_DocumentTool`/`ShapeTool`/`ColorTool`/`ColorType`/`LengthUnit`、`STEPCAFControl_Writer`	`XCAFDoc_MaterialTool`（物性）与 `XCAFDoc_VisMaterialTool`（PBR）均未绑定。两者都要改绑定清单并重建 sealed runtime（动 receipt / build-lock / provenance）
export.ts:294	3MF 只发 Core + Beam Lattice	加 `<basematerials>` 是字符串拼接级改动
prepare-cloudflare-static-deployment.mjs:255	只聚合依赖树中的 LICENSE	CC-BY 数据集不是 npm 依赖，署名要显式加条目

7. 设计建议

7.1 数据形态

一次性离线转换脚本，输出规范化 SI 纯数值行；不存单位字符串，不引入单位解析库。 §4.3 的逗号小数、MPa/GPa 混用、语义矛盾全部在转换期解决，运行时不再有解析路径。
每行保留 sourceId / license / attribution，逐行可分，以支持 §3.2 的混合许可署名。
转换产物随构建固化，运行时只读（对照 library-reference-data.ts）。
导入闸门（转换期硬失败，不是警告）：密度必须存在且在合理量级； YieldStrength 与 UltimateTensileStrength 的关系按 class 分别判定（金属要求 yield ≤ UTS）；同 class 的密度与 CC0 来源交叉核对，偏差超阈值即拒绝。

7.2 身份与绑定

materialId 稳定、不可变；class 与 grade 分离（§3.3）。
材料挂在 body/solid 上，进 AMIR 文档：参与撤销/重做、保存重开、编辑守恒与 patch 原子性。
不要做成 viewer-only 的装饰——那样等于没做，且以后要推翻。

7.3 派生与校验

mass = density × volume，host 计算，模型不做算术。
ExactCadExpectation 增加 mass，语义与现有 volume 完全一致（数值或请求中数字构成的算式，host 求值并按相对误差校验）。
这是本条线上唯一新增的产品能力：AI 说“这块支架应重 2.1 kg”，host 用独立于源码的第二次推导否决它。
成本估算不在本轮范围：§4.2 显示 FreeCAD 的 Costs 模型实际只有外链，没有价格。

7.4 AI 接口与 token 预算

做法	量级
目录绝不进 prompt，复用 `aira_library_reference` 的检索/分页/批量	全量 158 KB ≈ 40k+ token/次 → 单次检索 ~200–400 token
AI 只输出 `materialId` 一个短字符串，host 解析全部数值	plan 中不出现物性数字；同时堵死 AI 编造密度的路径
别名/牌号映射放 host 侧（`6061` / `AlMgSi1` / `A96061` / `铝合金6061` → 同一 id）	每次查不中就是一次完整往返；别名表是最高杠杆的省 token 项
派生量由 host 计算	消除算术错误，且不占 token
规范化行 ~120 字节 vs 原卡 1,130 字节	即便将来需要整表，也从 ~40k 降到 ~5k token

工具形态：同一套 AI SDK 工具集内新增一个检索工具，复用既有索引与分页辅助，不新建执行器、不手写工具声明副本（AGENTS.md）。

7.5 交换

3MF：加 <basematerials>（名称 + displaycolor），成本低，且 RFC-0005 的损失证书里可以如实申报“物性未导出”。
STEP：今天只能带名称与颜色。物性需要 XCAFDoc_MaterialTool 绑定并重建 sealed runtime—— 本轮不做，等有真实交换需求再单独开决定。
损失申报按 RFC-0005 的既有形式，不新建报告树。

8. 先复用，再自研（四项）

真实需求：模型带可信物性，使质量可算、AI 断言可被独立校验、导出不静默丢语义；同一材料同时决定显示。
上游设施：FreeCAD 材料卡（main，140 张标准卡，逐卡许可）与其 Inherits 身份结构； physically-based-api（CC0，86 条）；NIST 公有领域数据；已有的 OCCT GProp 体积；已有的 libraryReferenceTool 检索模式；3MF Materials & Properties 扩展规范。
已证实差异：115/140 张卡是 LGPL，不能默认并入分发物；Models/*.yml 本体是 LGPL-2.1； Supplemental 库是 CC-BY-SA；FreeCAD 外观模型非 PBR；6 张卡强度值语义不自洽、3 张逗号小数；热属性覆盖仅 39/140；成本模型实为外链；XCAFDoc_MaterialTool 与 XCAFDoc_VisMaterialTool 均未绑定； 3MF 导出器无 Materials 扩展。欧盟数据库权利下“整库提取”的边界 [待验证]。
决定与边界：数据全部外部导入并在转换期规范化与校验； Aira 只负责材料↔实体的绑定语义、文档守恒、派生校验与检索接口。不自研材料数据、不自研单位解析、不自研零件级 PBR 采集、不新建检索执行器、不新建报告树。

9. 待定与风险

LGPL 金属牌号库是否可用属于法务判断。 §10 的执行计划不依赖这个判断：金属覆盖改由公有领域来源承担，LGPL 卡降级为只读校核源，因此该判断只影响“能否再多一层交叉核对”，不影响能否交付。
CC-BY 署名的具体承载位置未定：现有 THIRD-PARTY-LICENSES.md 生成器只扫依赖树。
MeshStandardMaterial → MeshPhysicalMaterial 的性能影响未实测 [待验证]。
本文对 FreeCAD 上游状态的判定基于 main 分支 2026-09-09 的快照；上游材料卡许可分布可能变化。