WhatCable：让 Mac 识别 USB-C 线缆能力的菜单栏神器
项目地址：https://github.com/darrylmorley/whatcable
作者：Darryl Morley | 开源协议：MIT | Stars：3.8k+
一、问题背景：USB-C 的"黑盒"困境
USB-C 接口统一了充电、数据传输和视频输出，但一个 Type-C 口可以承载的能力差异巨大：
- 一根普通的 USB 2.0 充电线（仅支持 5V/2A，约 10W）
- 一根 Thunderbolt 4 线缆（支持 40 Gbps 数据、最高 240W 供电）
- 两者外观完全相同，用户无法从物理上区分
macOS 虽然通过 IOKit 暴露了底层信息，但对普通用户来说过于技术化。WhatCable 正是为了解决这个问题而生——它把复杂的硬件信息翻译成人类语言，让你一眼就知道每根线能干什么。
二、核心功能一览
2.1 端口诊断（以通俗语言呈现）
每个 USB-C 端口会显示以下信息：
| 信息类型 | 示例内容 |
|---|---|
| 快速概览 | Thunderbolt/USB4 / USB 设备 / Display 连接 / 仅充电 / 慢速充电线 / 未连接 |
| 充电诊断 | “线材限制充电速度” / “当前充电 30W（充电器可达 96W）” / “充电良好，96W” / “电池已满，不充电” |
| 数据传输诊断 | “线材限制传输速度” / “设备运行在 10 Gbps，已达最快，非线材问题” |
| E-Marker 信息 | 实际速度（USB 2.0 / 5/10/20/40/80 Gbps）、电流额定值（3A/5A/60W/100W/240W）、芯片厂商 |
| 信任信号 | 当 E-Marker 报告异常时（零 VID、保留位模式等），显示橙色警告卡，提示"此线材可能有问题" |
| 充电器 PDO 列表 | 充电器支持的所有电压档位，实时高亮当前协商档位 |
| 连接设备身份 | 从 PD Discover Identity 响应中解码出的厂商名称和产品类型 |
| Thunderbolt 拓扑 | 活动链路的每车道速度、代际（TB3/TB4/TB5）及多跳交换机拓扑 |
| 桌面小组件 | 支持 Small/Medium/Large 三种尺寸的 WidgetKit 组件，直接在桌面查看状态 |
2.2 设置选项
- 隐藏空端口
- 登录时自动启动
- 作为 Dock 应用运行（而非菜单栏图标）
- 调整字体大小
- 多语言支持（英语、亚美尼亚语、意大利语、波兰语、简体中文，或跟随系统）
- 线缆插拔通知
- 可选提交匿名诊断数据以改善硬件覆盖率
2.3 命令行工具
whatcable # 人类可读摘要
whatcable --json # JSON 结构化输出，可配合 jq 使用
whatcable --watch # 流式更新，实时监控线缆变化
whatcable --raw # 包含底层 IOKit 属性
whatcable --report # 预填 GitHub Issue，一键上报可疑线材
whatcable --test-kit # 运行诊断探针并提交匿名数据
三、技术架构深度解析
3.1 读取的四类 IOKit 服务
WhatCable 不使用任何私有 API、辅助守护进程或特权 entitlements，而是直接读取系统提供的四类内核扩展：
| 服务 | 提供的信息 |
|---|---|
AppleHPMInterfaceType10/11/12（M3 时代）、AppleTCControllerType10/11（M1/M2）、IOPort（M4 Mac mini 前置端口） |
各端口状态：连接/断开、传输协议、插入方向、E-Marker 存在性 |
IOPortFeaturePowerSource |
来自连接源的完整 PDO 列表，含实时"获胜"PDO |
IOPortTransportComponentCCUSBPDSOP 系列 |
PD Discover Identity VDO，包括端口伙伴（SOP）、线材近端 E-Marker（SOP’）、远端 E-Marker（SOP’'，若存在） |
| XHCI 控制器子树 | 将每个连接的 USB 设备与物理端口配对，通过 XHCI 端口节点的 UsbIOPort 注册表路径实现 |
3.2 线速与功率解码规范
线速和功率解码严格遵循 USB Power Delivery 规范（R3.2 V1.2，2026年3月版）。厂商名称来自内置的 SQLite 数据库（whatcable.db），该库合并了 USB-IF 发布的厂商列表、社区 usb.ids 列表，以及用户上报的精选线材指纹。
3.3 信任信号机制
软件无法验证线材内部芯片是否真实，因此 WhatCable 实现了一套"信任信号"机制：
- 橙色警告卡出现在 E-Marker 报告异常数值时，措辞谨慎：“此标识看起来异常”，而非"这是假货"
- 检测的特征包括：零 VID、速度/电流/延迟字段中的保留位模式、不在 USB-IF 发布列表中的 VID
- 这种" hedged signaling"设计避免了误判，同时提醒用户保持警惕
3.4 源码模块结构
Sources/
├── WhatCable/ # 主菜单栏应用 UI（SwiftUI Popover、设置、通知）
├── WhatCableCore/ # 共享诊断逻辑、PD 位解码、文本格式化
├── WhatCableDarwinBackend/ # IOKit 监听器（端口状态、PD 身份、电源源、USB 设备、Thunderbolt 拓扑）
├── WhatCableAppKit/ # AppKit 级窗口和面板管理
├── WhatCablePlugins/ # Pro 功能（功耗监测、授权、线材诊断视图、液触检测）
├── WhatCableWidget/ # WidgetKit 扩展（Small/Medium/Large 桌面组件）
└── WhatCableCLI/ # CLI 二进制，与 App 共享 Core/Backend/Plugins
四、安装与运行
4.1 方式一：手动下载
- 访问 GitHub Releases
- 下载
WhatCable.zip，解压后将WhatCable.app拖入/Applications - 签名和公证由构建脚本自动处理，Gatekeeper 无警告
4.2 方式二：Homebrew（推荐）
brew tap darrylmorley/whatcable
brew install --cask whatcable
Homebrew 版本会自动将 CLI 符号链接到 /usr/local/bin/whatcable。
4.3 为什么没有上架 Mac App Store？
App Sandbox 会阻止对底层 IOKit 的读取，而这正是 WhatCable 依赖的核心功能。因此项目选择以签名+公证的方式分发，而非上架 App Store。
4.4 系统要求
- macOS 14 (Sonoma) 或更高版本
- 仅限 Apple Silicon（Intel 平台的 USB-C 端口由 Intel Titan Ridge/JHL9580 Thunderbolt 3 控制器驱动，无法获取所需的 USB-PD 状态和 E-Marker 数据）
五、WhatCable Pro：付费增值版
免费版已经非常强大，Pro 版（$4.99，一次性购买，支持最多 2 台 Mac）解锁以下高级功能：
| 功能 | 说明 |
|---|---|
| 实时功耗监测 | Live Power Meter，带输入功率图表 |
| PD 合同检查 | 完整的逐连接分析，对比端口/线材/设备各自支持 vs 实际协商结果，突出薄弱环节 |
| 端口健康计数器 | 统计端口使用情况，估算线材电阻 |
| Pin diagrams | 引脚图和液触检测状态 |
| Pro 界面 | 独立窗口展示，可分离为独立窗口 |
| 兼容无功耗暴露的 Mac | 即使 Mac 不暴露实时端口功耗，也能工作 |
六、隐私与安全
- 所有数据本地处理：WhatCable 直接从 IOKit 读取 USB-C 端口状态，全部在本地完成，不会向任何服务器发送数据
- 更新检查：定期检查 GitHub Releases API，请求中不包含个人数据或硬件信息
- 诊断数据：设置中有"贡献诊断数据"按钮，点击后才收集并提交匿名端口和功耗数据，完全可选
- 线材报告：“Report this cable” 按钮预填 GitHub Issue，用户需手动点击提交，提交前数据对用户可见
七、Linux 移植：usbeehive
@abrauchli 为 Linux 开发了 Rust 移植版 usbeehive，通过读取内核 typec sysfs 接口而非 IOKit，是独立实现而非 Fork。
安装：cargo install usbeehive
八、项目数据概览
| 指标 | 数据 |
|---|---|
| GitHub Stars | 3.8k+ |
| Forks | 101 |
| Issues | 13 |
| Pull Requests | — |
| 分支数 | 11 |
| Tags | 59 |
| Commits | 308+ |
| 最新版本 | v0.5.13（build 27） |
| 编程语言 | Swift（Swift 5.9+ / Xcode 15+） |
| 许可证 | MIT |
| 最低 macOS | 14 (Sonoma) |
| 平台 | Apple Silicon ONLY |
九、总结与评价
WhatCable 是一个典型的"小而美"的开发者工具——它精准地解决了一个看似小众但普遍存在的问题：用户不知道手里的 USB-C 线到底能跑多快、充多少电。
项目的工程实践值得学习：
- 纯 IOKit 方案：不依赖任何私有 API，只读取系统公开接口，安全性和可持续性极佳
- 清晰的分层架构：Core/Backend/Plugins 三层分离，便于维护和扩展
- 保守的信任信号设计：不对线材真伪下定论，而是给出警示，体现了良好的风险意识
- 开源+Pro 商业模式：免费版足够好用，Pro 版解决进阶需求，商业模型清晰
对于 macOS 开发者而言，WhatCable 展示了如何通过 IOKit 深入系统底层，并将复杂信息以友好方式呈现给用户。对于普通用户，它是辨别"真假快充线""假 Thunderbolt 线"的实用工具。
本文基于 WhatCable 项目 README、源码结构和 GitHub 仓库信息整理撰写。
评论