别只盯星数:AirCard 文档里藏着哪些好用但没人提的功能
别只盯星数:AirCard 文档里藏着哪些好用但没人提的功能
大多数人对 AirCard 的认识停留在 README 首页那行 Apple Wallet Card Skinner:把喜欢的图片刷进钱包卡面,双击侧键、Face ID、点卡、闪存、重启,五步收工。但在星数与五步教程之外,这个仓库真正值钱的东西,几乎都写在 docs/ 目录和 Swift/Python 后端那些"没人在 README 里展开讲"的角落:一套能区分"扫描到"与"已验证"的卡片识别协议、一个把一张壁纸切成锁屏密码键盘十个键位的切片引擎、一个既能导入 Cowabunga/Nugget 主题又能重新打包导出的 .passthm 编辑器,以及一个不需要联网、单 HTML 文件就完成的离线卡面排版工具。这篇文章只讲这些"文档里藏着"的功能:它们各自的源码依据、真实的使用边界,以及一个能立刻上手的最小实践。
逐项过一遍 README 之外的配置项
1. 卡片列表不是"手机钱包的截图",而是一套确认协议
README 只写了"点击 Scan Cards 然后点选卡片",但真正决定你能否刷对的逻辑,在 Sources/WalletDiscovery.swift 里。它把识别信号分成三个等级:
- 本次扫描匹配(Matched in this scan):
WalletScanParser用六条正则从统一日志里抠出带路径的.pkpass/.cache/.pkcache引用,或者PDCardFileManager: writing card、PDPassLibrary: wrote pass、VerificationCheck.这类明确的事件; - 缓存候选(Payment entries to confirm):来自 wallet_catalog.py 读取的 Mac 本地
RemoteDevices.archive,只有"机型匹配 + 存在一次活体扫描确认的卡片 ID 命中"时,才把同一缓存里的其余支付卡补进来; - 保存的旧记录(Saved IDs to confirm):只在当前 iPhone 重新暴露这些 ID 之前保持隐藏,绝不参与刷入。
这套设计直接回应了一个经典坑:iOS 的日志里 passIDs<a href="https://link.gitcode.com/i/3124f102adde8926917e9e738d0efb06" target="_blank">InSession]、passIDs[global] 等结构有时会把卡片 ID 打出来,但 ID 出现 ≠ 卡片此刻在手机上。仓库的 [docs/wallet-missing-cards-2026-09-22.md 记录了一个真实案例:国泰会员卡的 nfcd 日志里出现了完整 ID,但现有解析器不覆盖 passIDs[global] 多行结构,因此卡始终没有进入列表;中国银行银联卡则因为激活标识和卡片文件 ID 是两种不同的标识、且本机缓存缺失映射而无法识别。结论写得很克制:"这不能证明卡片损坏、银联整体不受支持或 iOS 永远无法提供该 ID",只说明当前解析范围与缓存不足以完成映射。
这意味着你在界面上看到的"卡片"分为两类:带绿色确认标记的(本轮活体验证过,可刷)和仅作为候选的。README 让你"点选卡片后立即检测",真正严谨的用法是配合 WalletDiagnosticsView 里那个 Check missing cards 抽屉(实现在 Sources/WalletDiagnosticsView.swift),它把"Pending Payment Cards"和"Pending Passes / Memberships"分开列出,用 … 加 ID 后六位区分同名卡——因为同名会员卡不会自动合并。
2. 三个"没人提"的按钮:Read Cache、Save IDs、Reconnect
README 的排障章节之外,界面工具栏还有一组容易被当成摆设的控件,它们各自对应一个独立的诊断链路:
- Read Cache:调用 wallet_catalog.py 重新解析 Mac 本地
~/Library/Passes里的RemoteDevices.archive与Cards/*.pkpass/pass.json。注意它不触发 iCloud 刷新,只是重读本地元数据;缓存损坏时界面会显示诊断信息而不是宣称"手机零卡"。 - Save IDs(Add Manually):把 16–64 位的卡片 ID 粘贴保存(实现见 AirCardApp.swift 的
addCardHash)。保存后它们保持隐藏,直到当前 iPhone 的扫描重新命中;文档明确警告"不要从别人的截图复制标识"。 - Reconnect:重新执行
checkDevice,并区分四种失败语义——device_helper缺失、无设备、检测失败、未返回可用输出。代码注释里专门写了一句:"返回空输出意味着后端根本没跑起来,而不是线松了;这时候跟用户说'重插线'会把他们引向错误的方向。"
3. 刷入队列的真正规则:勾选 + 配图 + 已验证
README 说"Flash Skins (N Cards)",但 docs/guides/MULTI-CARD.zh-CN.md 给出了精确条件:已勾选、已分配图片路径、且处于"本次扫描已验证"集合,三者缺一不可。ready to flash 只是"配置条件满足",不是"图片有效"也不是"手机写入成功"。分配图片会自动勾选该卡(setCardImage 里 isSelected = true),所以配图后要再核对一次勾选状态。
还有两个没人细看的按钮语义:
| 按钮 | 实际作用 | 不会做什么 |
|---|---|---|
| 卡面右上角 ×(Remove skin) | 清除 Mac 上该卡待应用的图片与路径 | 不向手机写入原图 |
| Clear All(Apple Wallet 页) | 清空并保存 Mac 端卡片列表 | 不删除 Wallet 卡片、不清理手机缓存、不恢复卡面 |
刷入队列在首张失败卡之后整体停止,之前的写入不回滚,同一张失败卡内部也可能有部分文件已写入——后端在 aircard_backend.py 的 cmd_flash 里先做批量写入,失败后逐文件重试,随后才清理 .cache 与 .pkcache 两类渲染缓存;缓存清理失败会把整张卡标记为失败,而不是"部分成功"。多卡场景的正确姿势是:Deselect All → 只勾选失败的那张 → 重新配图 → 单卡重试,不必把所有成功的卡重刷一遍。
4. 被 README 一笔带过的 .passthm 三套"Universal"
README 里有一行 TIP 说 AirCard "自动为所有系统语言和 Bold Text 生成缓存位图",但没解释界面里其实是三种不同的 Universal(详见 docs/guides/THEME-CREATOR.zh-CN.md):
- All Languages (Universal):展开
KEYPAD_LOCALES里 17 种语言命名(en、ru、uk、ja、ko、zh、ar、he等,见 aircard_backend.py),只影响语言文件命名,不修改 iPhone 系统语言; - Universal (Regular + Bold):同一份图像同时生成
--white.png和--white-bold.png两套文件; - Target → Universal (All 8, 9, 10):同时写入
TelephonyUI-8/-9/-10三个缓存目录。
界面提示"Universal 模式会闪约 600 个文件",这个数字只是估算,实际随主题与目标变化。选择具体语言(比如 uk)+ 单一字重,刷入速度会明显提升,因为写入文件数大幅减少——这是 README 之外最实用的一个性能开关。选择准确的语言和字重通常比全选 Universal 更可靠,全选不能解决所有加载与兼容问题。
5. _big 标记、Cyrillic 副标与源包结构的保留边界
.passthm 其实是一个 zip 包。后端 aircard_backend.py 的 parse_passthm_archive 做了四层文件名归一化:对每个数字键生成无副标变体 {lang}-{d}---white.png、标准拉丁副标变体、俄语/乌克兰语的西里尔副标变体(CYRILLIC_SUBTEXTS_RU/UK 两张表),以及源素材自带的自定义副标。刷入时会保留包内的 _big/_small 标记文件。
但 docs/guides/THEME-CREATOR.zh-CN.md 把边界写得很清楚:Theme Creator 不是无损编辑器——同一数字的不同语言、字重版本不会作为独立图层保留;重新导出会重新打包资源与 _big 标记,原包的 _small 标记或特殊结构不保证保留;对矩形整图切片重新缩放或平移后会重新按圆形裁切。需要保留这些差异时,正确做法是保留原包并逐项比较新包,而不是用编辑器二次导出。
三个被低估的使用场景实测
场景一:不连接 iPhone,先做"导出后本机检查"
Theme Creator 的导出与检查完全不需要手机。最小闭环是:
- 在
Passcode (.passthm) → Theme Creator里用 Poster Slice (Puzzle) 拖入一张壁纸,用 Zoom & Framing 滑杆(0.5–3.0 倍)调整构图; - 点击 Export .passthm... 导出;
- 切到 Apply .passthm 重新导入刚导出的文件,逐个核对 0–9 的预览;
- 想检查 PNG 本身:把导出的包复制一份,把副本扩展名改成
.zip解压查看,原始.passthm留给导入。
这里有个关键细节(源码在 AirCardApp.swift 的 KeypadLayout 与 PasscodeThemeExporter):整图切片基准是 915 × 1148(iOS TelephonyUI @3x 网格,按钮直径 75pt、列宽 101.67pt),这跟钱包卡面的 1536 × 969 是两套完全不同的坐标系。数字 0 在 Seamless Poster 模式下使用底部整行图像(isZeroSeamless 分支),切到 Circle Buttons 时才按 225px 圆形裁切。检查导出文件时重点看 0 的底部与各键的透明边缘。
同一份主题包还可以验证兼容性:cmd_inspect_passthm 会扫描 zip 条目名里是否出现 TelephonyUI-8/-9 来猜测目标目录,所以先导入再看包的检测目录,再用已连接设备的 Auto-detect 复核——包内目录名不是当前手机型号的检测结果。
场景二:把"已刷过"的状态变成可查的工程事实
界面左下角的状态栏会显示 N of M verified cards selected · X changed · Y already on iPhone,这个 changed 计数背后是 AirCardApp.swift 里一套很少被提及的机制:每张卡的皮肤文件在分配时就算出 SHA-256 签名(CardItem.signature(of:)),刷入成功后以 udid|cardHash 为键记录签名到 UserDefaults;下次 cardsNeedingFlash 会比较当前图片签名与已刷签名,相同则跳过,按钮文案也会从 Flash Skins (N) 变成 Re-flash All (N)。
这对多卡工作流的意义很大:同一张图改了一点点 → 签名变化 → 只重刷这一张;完全没动 → 跳过,不重复写盘。它把"我到底刷没刷过"从一个记忆问题变成了一个可校验的工程状态。
场景三:离线排版卡面,构图与 AirCard 像素级对齐
仓库里躺着一个几乎没人引用的工具:tools/card-artwork/,整个工具就是一个 index.html,内置全部 CSS 与 JS,CSP 禁止任何网络连接,图片只在本地 Canvas 处理。它的初始裁切几何与 AppViewModel.prepareCardImage 完全一致:按 max(1536 / width, 969 / height) 等比放大后居中,导出始终是 1536 × 969 PNG。
实测流程:下载 index.html 用浏览器打开(地址栏以 file:// 开头即可),拖入图片,用水平/垂直取景滑杆与缩放调整构图,选择保留透明通道或填充白/黑底,导出 原名-aircard-1536x969.png,再拖进 AirCard 预览。它解决的是 README 里反复出现的"图被裁掉了"问题——AirCard 原生准备路径会把图片居中裁到 1536 × 969,正方形素材上下会被裁掉,纸板素材边缘也会切;在离线工具里先把构图排好,重要文字放中间,比反复刷机试错高效得多。如果一定要手动排版,按约 1.585:1(1536:969)的比例准备即可。
与常见制卡工具的能力对照小结
把仓库文档与源码摊开看,AirCard 相对同类工具的能力边界其实很清晰。下表依据仓库内 docs/guides/COMPATIBILITY.zh-CN.md 的"按阶段记录证据"原则整理:
| 能力维度 | AirCard 的做法 | 关键依据 |
|---|---|---|
| 卡片识别 | 区分"本次扫描匹配 / 缓存候选 / 旧记录",只有活体验证过的 ID 可刷 | Sources/WalletDiscovery.swift、wallet_catalog.py |
| 皮肤一致性 | 皮肤文件 SHA-256 签名比对,未变更的卡自动跳过 | AirCardApp.swift isSkinFlashed/cardsNeedingFlash |
| 缓存失效 | 真实删除 .cache/.pkcache 里的 FrontFace/PlaceHolder/Preview,而不是覆盖写入 |
apply_card_skin.py remove_files |
| 主题兼容 | 导入后按包结构 + 语言/字重/目标目录四维归一化再刷入 | aircard_backend.py parse_passthm_archive |
| 主题编辑 | 支持 Poster Slice / Individual Keys / 编辑已有包三种入口,但明确"非无损" | docs/guides/THEME-CREATOR.zh-CN.md |
| 离线排版 | 单 HTML 离线裁切工具,与 App 内原生裁切几何一致 | tools/card-artwork/index.html |
| 验证边界 | 连接 / 扫描 / 刷入 / 手机显示四阶段分开记录,自动化测试 ≠ 真机验证 | docs/guides/COMPATIBILITY.zh-CN.md |
值得一提的还有仓库自带的测试资产:tests/ 里既有 test_card_flash.py(模拟素材写入、PDF 转换与缓存失败)、test_card_scanner.py(协议与合成卡片路径)、test_backend_passthm.py(主题包解析),也有 Swift 侧的 WalletCardBindingTests.swift、test_wallet_viewmodel.swift,以及 tools/card-artwork/tests/crop.test.cjs(216 组边界组合)。这些测试让上面所有"文档里藏着"的能力都有可回归的代码级证据——但文档自己也强调,自动化检查不能替代具体手机的扫描、刷入与刷新验证。
结语
AirCard 的 README 是一张精修过的门面,而 docs/ 与源码才是它真正的用户手册。那些"没人提"的功能——活体验证协议、SHA-256 皮肤去重、_big 标记保留、西里尔副标归一化、离线裁切几何对齐——没有一个是为了凑功能清单而存在的,它们全部对应着真实踩过的坑:日志里的 ID 不代表卡片在手机上,缓存文件覆盖写不触发 Wallet 重绘,Universal 全选不等于兼容性更好,旧主题包的 _small 结构经不起二次打包。读懂这些边界,比记住那五步流程有用得多。
仓库内的素材文件 assets/skins/ 提供了四套可直接拖入预览的卡面(纸板卡、极简 Apple、Amex 黑卡、金色卡),下载后拖到 AirCard 的卡片上即可体验上述完整链路;需要自备构图时,优先使用 tools/card-artwork/ 里的离线工具先裁好 1536 × 969,再交给 AirCard 应用。