OpenClaw iOS 第三方字体溯源清单:SIL OFL 合规、SHA-256 校验与可变字体打包实战
OpenClaw iOS 第三方字体溯源清单:SIL OFL 合规、SHA-256 校验与可变字体打包实战
OpenClaw 的 iOS 客户端(含 Watch App 与 Live Activity 组件)将 Inter、Red Hat Display、JetBrains Mono 三套第三方字体二进制随包分发,并依托 apps/ios/THIRD_PARTY_FONTS.md 这份"第三方字体溯源清单"(Third-Party Font Provenance)维护可审计的合规证据。本文以该清单为骨架,结合仓库中字体的实际加载、注册、使用与测试代码,完整讲解如何核对字体来源、验证哈希、理解可变字体轴,以及维护一条从清单到二进制的闭环。
一、这份清单解决什么问题
apps/ios/THIRD_PARTY_FONTS.md 开宗明义:清单中列出的字体二进制会被重新分发到 iOS App、Watch App 和 Live Activity 三个目标中,因此文件要求每次增删、替换打包字体时,都必须保持该清单与 apps/ios/Sources/Fonts/ 目录同步。
同时文档划清了两种受众:
- 面向维护者的审计:本清单记录的是"被重新分发的精确二进制资产"(exact redistributed binary assets),包括上游项目、许可证类型、不可变上游来源(immutable upstream source)与 SHA-256 摘要,供维护者逐字节核对;
- 面向用户的声明:设置页中的 "Settings Licenses"(设置-许可证)界面使用
apps/ios/Resources/Licenses/*.txt向用户展示致谢文本,清单本身不承担用户可见的合规展示职责。
一句话概括这份文档的契约:"目录里有什么字体,清单就必须记录什么字体;清单记录的哈希,必须与目录中二进制计算出的哈希一致。" 文档标注的"Last verified: 2026-07-03"即为最近一次全量核验时间。
二、六款打包字体的完整溯源清单
清单以一张表格记录了 6 个字体文件。以下为完整继承并整理的清单内容(上游来源以纯文本形式保留提交级 pin 信息):
| 打包文件 | 上游项目 | 许可证 | 不可变上游来源(commit 级 pin) | SHA-256 |
|---|---|---|---|---|
apps/ios/Sources/Fonts/Inter[opsz,wght].ttf |
Inter | SIL Open Font License 1.1 | google/fonts e4572de9…:ofl/inter/Inter[opsz,wght].ttf |
29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031 |
apps/ios/Sources/Fonts/Inter-Italic[opsz,wght].ttf |
Inter | SIL Open Font License 1.1 | google/fonts e4572de9…:ofl/inter/Inter-Italic[opsz,wght].ttf |
acd98e64795781b2058f07b18475e0ecee2a0fe2b42a49e2f9e37d0d6bf66ce6 |
apps/ios/Sources/Fonts/JetBrainsMono-Regular.ttf |
JetBrains Mono | SIL Open Font License 1.1 | JetBrains/JetBrainsMono cd5227bd…:fonts/ttf/JetBrainsMono-Regular.ttf |
a0bf60ef0f83c5ed4d7a75d45838548b1f6873372dfac88f71804491898d138f |
apps/ios/Sources/Fonts/JetBrainsMono-Medium.ttf |
JetBrains Mono | SIL Open Font License 1.1 | JetBrains/JetBrainsMono cd5227bd…:fonts/ttf/JetBrainsMono-Medium.ttf |
31c92d01a8a08528b718a43addf0ad3df0af2ca4b7b3290a452f70f358e14d3d |
apps/ios/Sources/Fonts/JetBrainsMono-SemiBold.ttf |
JetBrains Mono | SIL Open Font License 1.1 | JetBrains/JetBrainsMono cd5227bd…:fonts/ttf/JetBrainsMono-SemiBold.ttf |
1b3bfa1ed5665a4ce3f9feb68d2d4e40e70bf8b4b7d9a3edd418f321b4e166a0 |
apps/ios/Sources/Fonts/RedHatDisplay[wght].ttf |
Red Hat Display | SIL Open Font License 1.1 | google/fonts e4572de9…:ofl/redhatdisplay/RedHatDisplay[wght].ttf |
46c9d4c4a2415e7e72020b318f5cda2bcbc9018d78b1a67e480a76d8d6e4b379 |
几个值得注意的细节:
- 三家上游全部采用 SIL Open Font License 1.1,这是字体领域最常见的自由许可证之一,允许将字体随软件捆绑、嵌入与再分发,前提是保留版权声明与许可证全文、不得单独出售字体文件、修改版不得使用保留字体名——这与仓库在 apps/ios/Resources/Licenses/ 目录存放许可证全文的做法一一对应;
- 两个 Google Fonts 来源的字体(Inter、Red Hat Display)都 pin 在同一提交
e4572de9…,而 JetBrains Mono 来自 JetBrains 官方仓库的cd5227bd…提交,说明清单记录的是"上游某一历史时刻的精确快照"而非滚动更新的 latest,这正是"不可变来源"的意义——哈希在任意时刻都可复现核对; - 六个文件的实际存在性可直接在 apps/ios/Sources/Fonts/ 目录中确认,与清单一一对应,无多余文件。
三、三套字体在 App 中的实际分工
清单中的字体并非"打包即用"的摆设,它们构成了 OpenClaw iOS 完整的品牌排版体系。核心实现在 apps/ios/Sources/Design/OpenClawTypography.swift 的 OpenClawType 枚举中,按用途划分为三大族:
| 排版族 | PostScript 名称 | 字体文件 | 用途 |
|---|---|---|---|
| Display | RedHatDisplay-Regular |
RedHatDisplay[wght].ttf |
大标题(title1/title2/title3)、headline 等醒目层级 |
| Body | Inter-Regular / Inter-Italic |
Inter[opsz,wght].ttf、Inter-Italic[opsz,wght].ttf |
正文、callout、subhead、footnote、caption 等常规文本 |
| Mono | JetBrainsMono-Regular/Medium/SemiBold |
三份 JetBrainsMono 静态字体 | 等宽代码/技术信息(mono、monoSmall、monoFootnote 等) |
从源码看,三种字重体系各有分工:
- Display 族通过
Display枚举定义了光学字重常量:opticalSemiBold: 650、opticalBold: 750、heavyTitle: 800,用于大标题与强调层级; - Body 族在
Body枚举中定义regular: 400、medium: 500、semiBold: 600、bold: 700四档字重; - Mono 族直接以静态字体的 PostScript 名称
JetBrainsMono-Regular、JetBrainsMono-Medium、JetBrainsMono-SemiBold引用三份独立文件——这也是清单中 JetBrainsMono 需要打包三个文件、而 Inter 只需两个可变字体的根本原因。
OpenClawType.registeredPostScriptNames 数组(源码注释明确要求"与 project.yml 中的 UIAppFonts 保持一致")汇总了全部 6 个注册名称,是测试与打包注册的单一事实来源。
四、可变字体原理:wght 与 opsz 轴的使用方式
清单中 Inter 与 Red Hat Display 的文件名带有 [opsz,wght] / [wght] 标记,说明它们是可变字体(variable font)。OpenClaw 的排版代码展示了如何在运行时用 CoreText 操纵字体轴:
private static let fontWeightAxis = NSNumber(value: 2_003_265_652) // "wght"
private static let opticalSizeAxis = NSNumber(value: 1_869_640_570) // "opsz"
let descriptor = UIFontDescriptor(fontAttributes: [
.name: name,
kCTFontVariationAttribute as UIFontDescriptor.AttributeName: variations,
])
let base = UIFont(descriptor: descriptor, size: size)
wght(字重轴)与opsz(光学尺寸轴)以四字节标签的数值形式("wght"= 2003265652,"opsz"= 1869640570)传给kCTFontVariationAttribute,从而用一个字体文件实例化出任意字重,无需为每档字重打包独立文件;- Body 族的
scaledBodyUIFont会把opsz轴值夹在min(max(size, 14), 32)区间内,让小字号与大字号分别获得适配的光学设计; - Display 族只操作
wght轴,配合heavyTitle: 800等常量生成标题所需的重字重; - 排版代码统一走
UIFontMetrics(forTextStyle:).scaledFont(for:maximumPointSize:),即所有字体都随系统 Dynamic Type 缩放,并设置maximumPointSize上限(导航栏 44、内联标题 22、分段控件 16、Tab 栏 13 等),保证辅助功能超大字号下布局不失控。
这一设计直接解释了清单的打包策略:可变字体"一族一文件",静态字体"一字重一文件"。
五、打包与注册机制:UIAppFonts 与扩展目标
字体文件被分发到三个目标,靠的是 iOS 的 UIAppFonts 机制与 XcodeGen 工程配置:
- apps/ios/project.yml 中主 App 目标(
OpenClaw)的UIAppFonts依次列出 6 个文件:RedHatDisplay[wght].ttf、Inter[opsz,wght].ttf、Inter-Italic[opsz,wght].ttf、JetBrainsMono-Regular.ttf、JetBrainsMono-Medium.ttf、JetBrainsMono-SemiBold.ttf; - 三个
Info.plist(apps/ios/Sources/Info.plist、apps/ios/WatchApp/Info.plist、apps/ios/ActivityWidget/Info.plist)均包含<key>UIAppFonts</key>,Watch App 与 Live Activity 扩展也通过project.yml中各自的UIAppFonts:声明将这些字体打进扩展包; - 扩展目标使用的排版入口与主 App 保持同源:Watch App 走 apps/ios/WatchApp/Sources/WatchClawTypography.swift 的
WatchClawType,Live Activity 走 apps/ios/ActivityWidget/OpenClawActivityTypography.swift 的OpenClawActivityType,二者都以Font.custom(...)引用Inter-Regular、RedHatDisplay-Regular、JetBrainsMono-Regular等清单内字体。
需要注意的是:UIAppFonts 只是让 UIKit/CoreText 能按名称找到字体,清单负责保证这些名称对应的二进制内容与上游一致——两者共同构成"可运行 + 可审计"的完整链路。
六、许可证合规与用户可见声明
SIL OFL 1.1 的再分发义务要求随软件附带版权声明与许可证全文。仓库通过两层结构落实:
- 用户可见层:apps/ios/Resources/Licenses/ 目录存放所有第三方组件的致谢文本,其中
Inter.txt、JetBrains Mono.txt、Red Hat Display.txt对应清单中的三套字体。以 apps/ios/Resources/Licenses/Inter.txt 为例,文件头明确标注版权信息("Copyright 2016 The Inter Project Authors")、来源、版本(Google Fonts variable release)、许可证类型,并列明打包的两个文件Inter[opsz,wght].ttf与Inter-Italic[opsz,wght].ttf,随后附上 SIL OFL 1.1 全文(含 5 条许可与条件、终止条款、免责声明); - 维护者审计层:即本文主题文档
THIRD_PARTY_FONTS.md,以机器可读的表格记录精确二进制资产,二者互补而非重复。
设置页的 Settings Licenses 界面正是读取这些 *.txt 文件向用户呈现致谢的,仓库中也存在对应的加载与测试逻辑(参见 apps/ios/Tests/LicenseDocumentLoaderTests.swift 等测试文件),确保用户始终能看到与打包版本匹配的许可证声明。
七、哈希校验命令与维护流程
文档给出了验证本地文件哈希的标准命令(在仓库根目录执行):
find apps/ios/Sources/Fonts -maxdepth 1 -type f -print | sort | xargs shasum -a 256
该命令的语义拆解:
find apps/ios/Sources/Fonts -maxdepth 1 -type f:仅枚举字体目录第一层的普通文件,不递归子目录,正好对应"被分发到三个目标的二进制资产"这一范围;-print | sort:按文件名排序,保证输出顺序稳定、便于与清单逐行比对;xargs shasum -a 256:对每个文件计算 SHA-256 摘要,输出格式为<hash> <filename>。
将输出与第二节表格中的哈希逐一比对即可完成核验。由于清单记录了"不可变上游来源",任何一次从上游重新拉取字体后,都可以同时校验"上游快照哈希 == 本地文件哈希",防止静默引入被篡改或版本漂移的二进制。
维护流程的闭环可以概括为:新增/替换/删除字体 → 更新 apps/ios/Sources/Fonts/ → 同步本清单的表格 → 同步 project.yml 的 UIAppFonts 与各 Info.plist → 更新 Resources/Licenses/*.txt → 全量 shasum -a 256 复核 → 更新 "Last verified" 日期。
八、测试如何守住这条契约
仓库用测试把"清单 ↔ 打包 ↔ 运行"三者的同步关系固化为可执行断言,核心在 apps/ios/Tests/OpenClawTypographyTests.swift:
- 字体可加载:遍历
OpenClawType.registeredPostScriptNames中的 6 个名称,逐一断言UIFont(name:size:)非空("Missing bundled font"),直接验证清单字体确实进入了 App bundle; - 扩展目标注册齐全:解析
project.yml中OpenClawActivityWidget、OpenClawWatchApp两段,断言包含- path: Sources/Fonts与UIAppFonts:,并逐一检查 6 个字体文件名;同时解析 ActivityWidget 与 WatchApp 的Info.plist,断言<key>UIAppFonts</key>及其下的<string>条目齐全; - 可变字体轴可实例化:用
kCTFontVariationAttribute构造wght: 900的 RedHatDisplay 描述符,断言读回的变化值确实为 900,验证可变字体在运行时可按需取重; - Dynamic Type 缩放:对比
.large与.accessibilityExtraExtraExtraLarge两种preferredContentSizeCategory下的缩放字号,断言辅助功能字号严格大于默认字号; - 排版边界审计:内置一个"品牌字体边界扫描器"(
unbrandedTextCallOffenders),递归扫描主 App、WatchApp、共享 ChatUI 的 Swift 源码,凡Text/Label上出现.font(.body)、.font(.headline)等系统字体覆盖即判为违规,强制所有界面文字必须走OpenClawType/WatchClawType/OpenClawChatTypography等品牌入口。
由此,从清单文档到字体二进制、从 UIAppFonts 注册到运行时排版,整条链路都有文档约束 + 测试断言双重守护——这正是 THIRD_PARTY_FONTS.md 作为"维护者审计入口"在工程中的完整价值。