darrylmorley/whatcable 来源：https://github.com/darrylmorley/whatcable # WhatCable > 这根 USB-C 线缆到底能做什么？ 网站：whatcable.uk (https://whatcable.uk)（概览、截图及命令行工具文档） 一个简洁的 macOS 菜单栏应用，用通俗易懂的语言告诉你插在 Mac 上的每根 USB-C 线缆实际能做什么，以及 你的 Mac 为什么充电慢。 USB-C 在同一种接口下隐藏了太多可能性：从仅支持 USB 2.0 充电的线缆，到 240W / 40 Gbps 的 Thunderbolt 4 线缆，放在抽屉里看起来一模一样。macOS 已通过 IOKit 提供了相关信息；WhatCable 将这些信息以友好的菜单栏弹出窗口呈现。 最新版本 (https://github.com/darrylmorley/whatcable/releases/latest) 平台 (https://github.com/darrylmorley/whatcable) 许可证：MIT WhatCable Pro (https://whatcable.uk/pro) WhatCable 弹出窗口 ## 显示内容 每个端口以通俗易懂的语言显示： - 一目了然的标题： Thunderbolt / USB4、USB 设备、已连接显示器、仅充电、慢速 USB / 仅充电线缆、未连接任何设备 - 充电诊断： 当插入设备时，横幅会标识瓶颈所在： - “线缆限制充电速度”（线缆额定功率低于充电器） - “以 30W 充电（充电器最高可提供 96W）”（Mac 请求的功率较低，例如电池接近满电） - “以 96W 正常充电”（所有部分匹配） - “电池已满，未充电”（已插入，电池满电，因此 Mac 不消耗电力） - 会话中故障警告： 如果已插入的线缆在使用过程中出现问题（电源过流，或连接断开后重连），端口上会出现横幅。它会读取端口自身的故障计数器，因此可以捕捉到仅在负载下才显现的故障。 - 数据速度诊断： 通俗易懂的结论，说明限制链路速度的因素：Mac 端口、线缆或设备。例如 “线缆限制数据速度”、“设备运行在 10 Gbps，这是它支持的最快速度，不是线缆问题”，或链路降级启动时的 “运行速度低于预期”。显示在内联、命令行工具及 JSON 中。 - 线缆 e-marker 信息： 线缆实际速度（USB 2.0、5 / 10 / 20 / 40 / 80 Gbps）、电流额定值（3 A / 5 A，最高 60W / 100W / 240W）以及芯片供应商。 - 线缆信任信号： 当 e-marker 报告的值看起来不符合 USB-PD 规范时，会出现橙色卡片，例如供应商 ID 为零、速度/电流/线缆延迟字段中存在保留位模式，或者 VID 不在 USB-IF 公布的列表中。措辞特意加以保留：标记意味着“看起来异常”，而非“这根线缆是假的”。 - 充电器 PDO 列表： 充电器宣传的每个电压配置文件（5V / 9V / 12V / 15V / 20V…），实时突出显示当前协商的配置文件。 - 已连接设备身份： 供应商名称和产品类型，从 PD Discover Identity 响应中解码得出。 - 连接的 USB 设备： 存储设备、集线器及外设，按其插入的物理端口列出，并显示协商速度。 - Thunderbolt 结构： 当 Thunderbolt / USB4 链路激活时，显示每通道速度、代次（TB3、TB4、TB5）以及通过扩展坞的多跳连接的完整交换拓扑。 - 线缆识别： 如果线缆的 e-marker 指纹与捆绑数据库中的已知线缆匹配，则显示品牌和型号，同时附上原始规格。 - 活动传输： USB 2 / USB 3 / Thunderbolt / DisplayPort - 桌面小组件： 小、中、大三种尺寸的 WidgetKit 小组件，在桌面上实时显示线缆状态。 - ⌥-点击 菜单栏图标（或切换设置中的开关）可显示底层 IOKit 属性（供工程师使用）。 点击弹出窗口标题中的 齿轮图标 打开设置，您可以： - 隐藏空端口 - 登录时启动 - 以常规 Dock 应用而非菜单栏图标运行 - 调整字体大小 - 显示技术细节（与 ⌥-点击 显示的原始 IOKit 数据相同） - 切换语言（英语、亚美尼亚语、巴西葡萄牙语、荷兰语、法语、德语、印地语、意大利语、日语、韩语、拉脱维亚语、挪威语、波兰语、俄语、简体中文、西班牙语、繁体中文、土耳其语、乌克兰语，或跟随系统默认设置） - 在连接或断开线缆时接收通知 - 贡献匿名端口和电源诊断数据，以改善硬件覆盖范围（手动选择加入） 右键点击菜单栏图标可进行 刷新、保持窗口打开 切换（方便截图和演示）以及 设置…。Pro 屏幕（电源监视器、协商诊断、显示诊断、已保存线缆）和 许可证… 也在此处。 下方还有：检查更新…、贡献诊断数据…、关于、GitHub 上的 WhatCable 和 退出。 ## WhatCable Pro WhatCable 是免费且开源的。如果您觉得它有用，可以通过购买 WhatCable Pro (https://whatcable.uk/pro) 来支持项目，从而解锁额外功能： - 线缆历史记录： 添加线缆，为其命名，WhatCable 会记录其随时间推移的实际表现。它会在后续连接中识别该线缆，并构建时间线：您上次使用时间、协商结果、是否出现异常行为。包括已保存线缆列表、每根线缆的总体摘要以及端口卡片上的结论。 - 实时功率计量和 PD 合同检查 - 电源监视器，带有实时系统电源输入图表 - 协商诊断： 每次连接的完整分解：Mac 端口、线缆和设备各自支持的内容与协商结果对比，并突出显示薄弱环节，同时进行 e-marker 与 Thunderbolt 控制器交叉检查。 - 显示诊断： 直接从 macOS 读取显示器的实时显示模式，并与 DisplayPort 链路传输的内容进行比较，因此低于最高分辨率或刷新率的屏幕会得到解释。即使在 5K 和 6K 显示器上也能显示真实分辨率，当屏幕通过压缩（DSC）达到最高模式时确认全质量，并命名链中的任何 HDMI 或 DisplayPort 适配器。 - 端口健康计数器和线缆电阻估算 - 终端仪表板： 适用于 SSH 和 tmux 用户的实时全屏视图，显示每个端口、电源和 Thunderbolt 信息。包含三个屏幕（概览、协商、电源），按 Tab 切换，每个端口都有简单的线缆健康结论。运行 whatcable --dashboard - 引脚图和液体检测状态 - Pro 屏幕在应用内打开，并可选择分离到独立窗口 - 即使在不暴露实时每端口计量的 Mac 上也能工作 一次性购买，可在最多两台 Mac 上使用。详情请见 whatcable.uk/pro (https://whatcable.uk/pro)。 购买 WhatCable Pro (https://whatcable.uk/pro) ## 安装 请访问 whatcable.uk (https://whatcable.uk) 获取概览和截图，或直接按以下方式安装。 从 Releases 页面 (https://github.com/darrylmorley/whatcable/releases/latest) 下载最新的 WhatCable.zip，解压缩，然后将 WhatCable.app 拖到 /Applications 文件夹。该应用已使用开发者 ID 签名并经过 Apple 公证，因此不会出现 Gatekeeper 警告。它没有上架 Mac App Store 是有意为之：App Sandbox 会阻止 WhatCable 所依赖的低级 IOKit 读取，因此它通过商店外部的签名和公证方式分发。 需要 macOS 14 (Sonoma) 或更高版本，仅限 Apple Silicon。在 Intel Mac 上，USB-C 端口由 Intel Titan Ridge / JHL9580 Thunderbolt 3 控制器驱动，WhatCable 依赖的 USB-PD 状态和线缆 e-marker 数据无法通过任何公共 IOKit 访问器获取。 > 注意： 手动安装仅提供菜单栏应用。whatcable 命令行工具捆绑在 .app 内部，默认不在您的 PATH 中。如果您想从 shell 中使用它，请参阅下面的命令行界面部分，了解一行符号链接命令。或者通过 Homebrew 安装，这会自动设置命令行工具。 ### Homebrew bash brew install --cask darrylmorley/whatcable/whatcable 这将安装菜单栏应用，并将 whatcable 命令行工具符号链接到您的 PATH 中。 ### Homebrew，仅命令行工具（无菜单栏应用） 如果您不需要菜单栏应用，只需安装命令行工具： bash brew install darrylmorley/whatcable/whatcable-cli 相同的签名和公证二进制文件，单独打包。适用于仅终端或脚本环境。 选择上述两个 Homebrew 安装之一（两者都会安装相同的 whatcable 二进制文件）。Homebrew 6 在首次安装时可能会警告不受信任的第三方 tap。如果现有安装开始抱怨不受信任的 tap，请运行 brew trust darrylmorley/whatcable 或参阅 https://docs.brew.sh/Tap-Trust 了解详情。 ## 命令行界面 whatcable 二进制文件与菜单栏应用一同分发，由相同的诊断引擎驱动： text $ whatcable USB-C 端口 1 ✓ 以 96W 正常充电 线缆：5A, 100W, USB4 40 Gbps 充电器：5V / 9V / 15V / 20V PDO USB-C 端口 2 ! 线缆限制充电速度 线缆：3A, 60W, USB 2.0 设备：外置 SSD, USB 10 Gbps 标志： bash whatcable # 每个端口的人类可读摘要 whatcable --json # 结构化 JSON，可传递给 jq whatcable --watch # 实时流式更新线缆连接/断开（按 Ctrl+C 退出） whatcable --raw # 包含底层 IOKit 属性 whatcable --report # 为已连接线缆打开预填充的 GitHub Issue whatcable --test-kit # 运行诊断探测并提交匿名数据 whatcable --desktop # 以 Dock 模式启动 GUI 应用 whatcable --popover # 以菜单栏模式启动 GUI 应用 whatcable --version whatcable --help Pro 版命令行工具： bash whatcable --monitor # Pro：实时电源遥测（按 Ctrl+C 退出） whatcable --monitor-json # Pro：实时电源遥测，换行符分隔的 JSON whatcable --dashboard # Pro：全屏 TUI 仪表板（Tab 切换屏幕，q 退出） whatcable --activate XXXX-XXXX-XXXX-XXXX # 验证并存储 Pro 许可证 whatcable --licence # 显示当前许可证状态 whatcable --deactivate # 移除存储的许可证 whatcable --pro # 显示 Pro 功能，打开购买页面 对于未授权用户，CLI 会在纯文本输出末尾打印一行 Pro 提示。运行 whatcable --silence-pro-hints 可隐藏（或 --show-pro-hints 可恢复）。当输出被管道、重定向或与 --json 一起使用时，会自动隐藏。 如果您手动安装了 .app 而非通过 Homebrew，CLI 位于 WhatCable.app/Contents/Helpers/whatcable。如果您想在 shell 中使用，请将其符号链接到 PATH： bash ln -s /Applications/WhatCable.app/Contents/Helpers/whatcable /usr/local/bin/whatcable Homebrew 安装会自动为您完成此操作。 ## 工作原理 WhatCable 读取四类 IOKit 服务。无需授权、无需私有 API、无需助手守护进程： | 服务 | 提供的数据 | | — | — | | AppleHPMInterfaceType10/11/12（M3 时代）、AppleHPMInterfaceType18（MacBook Neo A 系列）、AppleTCControllerType10/11（M1 / M2） | 每端口状态：连接、传输、插头方向、e-marker 存在。Type11 是 M2 MacBook Air 用于其 MagSafe 3 端口的类型。 | | IOPortFeaturePowerSource | 来自连接源的全部 PDO 列表，以及当前“获胜”的 PDO。 | | IOPortTransportComponentCCUSBPDSOP、...SOPp、...SOPpp | 来自端口伙伴的 PD Discover Identity VDO（SOP）、线缆近端 e-marker（SOP’）以及远端 e-marker（SOP’’，如果存在）。 | | XHCI 控制器子树 | 每个连接的 USB 设备通过 XHCI 端口节点的 UsbIOPort 注册表路径与其物理端口配对，回退到基于控制器 locationID 高字节和端口 hpm SPMI 祖先的总线索引，适用于不暴露 UsbIOPort 的机器。 | 线缆速度和功率解码遵循 USB Power Delivery 规范（对齐至 USB-PD R3.2 V1.2，2026 年 3 月）。供应商名称来自捆绑的 SQLite 数据库（whatcable.db），该数据库合并了 USB-IF 公布的供应商列表、社区 usb.ids 列表以及用户报告的精选线缆指纹集合。 ## 从源码构建 bash swift build # 编译所有内容 swift run WhatCable # 运行菜单栏应用（开发模式，无小组件或捆绑结构） swift run whatcable-cli # 运行 CLI swift test # 运行测试套件 需要 Swift 5.9+（Xcode 15+）。注意：swift run WhatCable 启动一个可用的开发版本，但没有小组件扩展或正确的 .app 捆绑包。要构建可分发的版本，请使用下面的构建脚本。 ## 构建可分发的 .app bash ./scripts/smoke-test.sh 构建、签名、公证（如果已配置）并进行烟雾测试。生成 dist/WhatCable.app 和 dist/WhatCable.zip。可在任何分支上随时安全运行。不会触及 Homebrew tap。 模式： | 配置 | 结果 | | — | — | | 无 .env | 临时签名。本地可用；在其他 Mac 上 Gatekeeper 会警告。 | | 带有 DEVELOPER_ID 的 .env | 开发者 ID 签名 + 强化运行时。 | | 带有 DEVELOPER_ID 和 NOTARY_PROFILE 的 .env | 完整公证 + 钉扎凭证。所有人都可通过 Gatekeeper。 | 发布版本： bash # 首先编写 release-notes/v.md，然后： ./scripts/release.sh 包装脚本完成整个流程：更新版本号、运行 build-app.sh（构建、签名、公证、烟雾测试并更新本地 cask）、标记并推送提交、使用 notes 文件创建 GitHub release、验证上传资产的 SHA 是否与本地 zip 匹配、将 notes 复制到 tap 并推送 tap。使用 --dry-run 先验证状态。需要 gh（已认证）和 .env.example 中的环境变量。 完整公证的一次性设置： bash # 1. 查找您的签名身份 security find-identity -v -p codesigning # 2. 将 notarytool 凭据存储到钥匙串 xcrun notarytool store-credentials "WhatCable-notary" \ --apple-id "[email protected]" \ --team-id "ABCDE12345" \ --password "" # 在 appleid.apple.com 生成 # 3. 从模板创建 .env cp .env.example .env # ...并填写 DEVELOPER_ID ## 注意事项 - 线缆 e-marker 信息仅对带有 e-marker 的线缆显示。 大多数 60W 以下的 USB-C 线缆没有标记。任何 Thunderbolt / USB4 线缆、任何 5A / 100W+ 的线缆以及大多数优质数据线缆都会带有 e-marker。 - 某些线缆仅在另一端插入设备后才显示其 e-marker。 线缆插头中的芯片由 VCONN（Mac 馈入线缆的小功率轨）供电，仅当主机发出“Discover Identity”消息时才会响应。如果线缆在空载时显示为基本型，请在远端插入充电器、扩展坞或设备，然后再次检查。 - WhatCable 从 Mac 的 USB-C 端口、连接的设备或充电器以及线缆本身读取数据。 它会交叉检查链中每个部分报告的内容，因此如果线缆声称高规格但协商结果较低，您将看到不匹配之处。也就是说，软件无法验证线缆内部的物理连线。如果线缆的 e-marker 芯片声称 240W / 40 Gbps，但实际布线无法达到，那么是芯片在撒谎，而非 WhatCable。信任信号卡片会标记一小部分内部一致性线索（VID 为零、Cable VDO 中的保留位模式、VID 不在 USB-IF 列表中）。这些在预算线缆中很常见，并不一定意味着有问题。它们提供信息，而非结论。 - 桌面机箱正面 USB-C 端口显示设备，但无线缆详情。 在 Apple Silicon 桌面机（Mac mini、Studio）上，正面 USB-C 端口是内部集线器后面的普通 USB 端口，而非像背面 Thunderbolt 端口那样拥有自己的控制器。插入这些端口的任何内容现在都会显示在 内置 USB 端口 部分下，但 Mac 不会暴露这些端口的线缆、电源或 PD 数据，因此无法显示 e-marker 或充电细节。背面 Thunderbolt 端口可正常工作。 - PD 规范覆盖范围： 解码器对齐至 USB-PD R3.2 V1.2（2026 年 3 月）。较早的 3.0 / 3.1 线缆均可正常工作。 - 供应商名称查询使用捆绑数据库（数千条 USB-IF 条目加上社区