OpenClaw iOS 第三方字体溯源清单:SIL OFL 合规、SHA-256 校验与可变字体打包实战

原创2026-09-08 21:32:501,897 阅读
文章标签:人工智能AI 应用AI AgentAgent 框架多智能体工具调用MCP 服务MCP Clients交互助手大模型本地部署代码智能体Agent 记忆语音媒体生成即时通讯插件系统CLI桌面应用移动开发跨平台前端

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 工程配置:

需要注意的是:UIAppFonts 只是让 UIKit/CoreText 能按名称找到字体,清单负责保证这些名称对应的二进制内容与上游一致——两者共同构成"可运行 + 可审计"的完整链路。

六、许可证合规与用户可见声明

SIL OFL 1.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 条许可与条件、终止条款、免责声明);
  2. 维护者审计层:即本文主题文档 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 作为"维护者审计入口"在工程中的完整价值。

登录后查看全文
openclaw