与 iOS 伴侣配对

检查两端的连接情况

同伴是正在运行的桌面边车的客户端。它不托管项目数据库、几何内核、模型提供程序或工作流运行程序。 Before pairing, confirm that the desktop opens its projects and that the phone can route to the desktop through Wi-Fi, Personal Hotspot, or an already configured overlay/VPN network.

使用包含以下内容的本机 iOS 构建 modules/companion-net。 Expo Go 缺少此模块，无法进行固定连接。该软件包还具有浏览器开发回退功能，但浏览器获取不实现本机固定策略。清单中的 Android 配置不提供 Swift 模块的 Android 等效项。

bun install
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile test
bun run --cwd apps/mobile ios

iOS 运行命令需要 macOS、Xcode 和 CocoaPods。物理设备构建需要可信的设备和签名团队。 bun run --cwd apps/mobile build 导出 JavaScript；它不会创建可安装的 IPA。请参阅 移动参考 用于布局和运输实施。

启用桌面网关

打开桌面设置 → 设备及其移动配套面板，或使用 /settings/companion。打开网关，然后创建命名配对并显示其二维码。这是一个独立于普通环回 API 的侦听器：IPv4 上的 HTTPS 0.0.0.0，默认端口 8443。

该服务接受整数端口 1024–65535。如果其他应用程序占用了所选端口，则启用失败；选择一个空闲端口并使用生成的地址创建链接。允许通过桌面防火墙连接您想要使用的网络。该应用程序不会创建公共中继、端口转发或 VPN。

启用状态和端口保持不变。 Sidecar 重新启动后，网关会在本地 API 准备就绪后尝试恢复。证书和私钥文件位于 sidecar 数据目录下 companion/ 子目录；私钥是使用仅限所有者的权限编写的。本机应用程序信任来自配对的证书，而不是每个本地证书都是安全的一般承诺。

通过桌面 API 检查并启用

对于可重复的开发设置，请使用您控制的独立 sidecar 的启动令牌。将端口 43111 替换为其就绪事件端口。这些是桌面管理调用；不允许电话令牌管理自己的网关。

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token
CADCAM_PAIR_DIR=$(mktemp -d /tmp/cadcamfun-pair-guide.XXXXXX)

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/enable"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"port":18443}'

状态包含启用状态、可为空的端口/指纹、建议的主机和设备条目。在证书存在之前，指纹可以为空。一个公众 健康探测 建立环回进程的健康状况；它并不证明 HTTPS 网关已启用、可访问或接受设备令牌。使用 配套API 以获得精确的管理模式。

创建一个命名配对

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/pair"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Workshop iPhone","host":"192.168.1.20"}'   -o "$CADCAM_PAIR_DIR/pairing.json"

CADCAM_DEVICE_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_PAIR_DIR/pairing.json")

将示例主机替换为电话可以到达的地址，或省略可选主机以使用发现。该名称已被修剪，并且必须包含 1–60 个字符。成功是 HTTP 201 id 和 link。创建令牌并不启用监听器；单独启用它。

该链接携带设备令牌、证书指纹、主要 HTTPS 来源、名称和可选的备用主机。显示或私下传输至手机；这是一个凭证。桌面存储令牌哈希而不是其明文。在此实现中，记录没有过期字段，因此显式撤销过时的设备，而不是假设它会过期。

在 iOS 上加载配对

1. 打开已安装的 CADCAMFUN 应用程序的“连接”屏幕。
2. 选择扫描配对二维码并授予相机访问权限，或使用粘贴配对链接。
3. 对于手动输入，请通过连接表单提供桌面地址、令牌和完整的证书指纹。
4. 当 iOS 提示时允许本地网络访问。相机访问和网络访问是单独的权限。
5. 等待运行状况/引导程序探测成功并且应用程序打开项目。

解析器需要没有用户信息、路径内容、查询或片段的 HTTPS 源。令牌必须是 16–4096 字符，不含空格/控制字符；指纹恰好是 64 十六进制字符。在请求开始之前，无效链接将被拒绝。

发现的备用来源已进行重复数据删除。客户端对候选者进行竞赛，使用第一个成功的连接，中止其他连接，并保存成功的源。 Discovery 广告最多六个合适的私有 IPv4 地址，包括 Wi-Fi、热点和 Tailscale 式 IPv4 范围；当前 IPv4 侦听器不会通告发现的 IPv6 主机。

证书固定检查哪些内容

Swift 传输使用短暂的 URLSession 实例和自定义信任委托。它获取叶证书的 DER 字节，计算 SHA-256，并仅当该哈希等于配对指纹时才接受连接。需要 HTTPS，并且拒绝重定向。如果模块丢失，本机调用者不会默默地回退到取消固定的获取。

这支持桌面的自签名证书，而不接受任意自签名服务器。信任决策来自配对 QR/链接。更换桌面证书会改变这一决定；创建新的可信配对而不是抑制不匹配。

普通的浏览器/curl 信任错误并不等同于测试应用程序的本机委托。浏览器可能会拒绝正确固定的自签名服务器，因为它使用不同的信任存储。通过已安装的应用程序进行验证并检查实际故障，而不是全局禁用证书验证。

设备身份验证成功后，网关会记录其当前服务状态的最后查看时间戳。刷新桌面设备状态以确认经过身份验证的流量。这表明代币的使用；它并不能证明每个项目行动都成功，也不能证明持久的安全审计跟踪。

了解设备令牌范围

设备令牌受方法/路径允许列表的限制。它本质上不是只读的，并且不选择一个项目。接受的请求将在桌面的应用程序身份下转发，并仍然受到端点授权的约束。切勿将配对描述为仅仅提供被动监控。

助理权限和待决问题是单独的会话交互。当需要时，在移动用户界面中回答它们。可以到达回复端点的令牌并不意味着每个工具操作都已获得批准。

使用会话并恢复连接

选择一个项目来检查其概述、历史记录、拉取和工作流程运行。助手会话通过其提供程序设置在桌面上执行。首先在那里配置提供者。手机会记住配对桌面的选定项目和每个项目的最后一个会话；更改桌面标识会清除该映射。

前台检查探针的预算为 15 秒。失败的检查会后退最多 30 秒，并将应用程序向前推进会触发另一个探测。后台状态与离线状态分开跟踪。点击手机设置中的桌面行以手动重新检查。

排队的助理消息最多保留 50 个条目，超出该限制的最旧条目将被删除。他们稍后重试并可能保留其会话标识符。这是有界消息传递支持，而不是离线 CAD 计算或一次性执行。写入/转动中断后，请检查桌面会话和项目，然后再重复相同的更改。

故意撤销或取消配对

curl --fail-with-body -X DELETE   "$CADCAM_URL/api/companion/devices/$CADCAM_DEVICE_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

每个新请求都会检查令牌，因此使用已撤销令牌的后续请求会失败。撤销不会显式终止已转发的流。禁用网关会停止监听器； POST /api/companion/disable 是管理端点。

电话设置 → 取消与此电话配对会删除本地保存的配对并返回到“连接”。它不会调用桌面撤销端点。停用设备时使用这两个操作。要仅轮换设备凭证，请将其撤销并发出新的配对；更换整个证书也会更改每部手机的 PIN 码。

分层诊断故障

本机 CI 构建未签名的模拟器应用程序并检查真实的网关配对/项目列表。单独的 CI 检查类型检查、逻辑测试和 JavaScript 导出。这些并不能证明物理设备签名、TestFlight 分发、远程网络路由或真实模型提供者。

重复的错误令牌会受到限制：60 秒内来自一个 IP 地址的 10 次失败尝试会导致来自该地址的进一步请求返回 HTTP 429，直到窗口到期。重新配对后的 429 通常表示仍在重试旧设备令牌。

实施图

管理合同是 packages/api/src/groups/companion.ts。 Sidecar 生命周期和路由策略位于 services/companion.ts 和 companion-gateway.ts。电话解析、连接恢复、存储和UI都在 lib/pairing.ts, server.tsx, storage.ts， 和 app/connect.tsx。本机信任委托是 modules/companion-net/ios/CompanionNetModule.swift.

对于支持报告，请保留应用程序版本、连接方法、非秘密网关主机/端口、确切的错误/状态以及本机模块是否存在。编辑令牌、配对链接、模型凭据和私钥。添加 系统接口 比较两个开发过程时的版本结果。

配对的手机可以拨打什么电话

通过网关的每个请求都必须携带设备令牌并匹配此允许列表。其他一切，包括凭证、插件、文件、账单和 /api/companion 本身，被拒绝。已承认的请求将使用应用程序令牌转发到环回 API，而手机永远不会看到该令牌。

配对链接剖析

cadcamfun://pair?host=https%3A%2F%2F192.168.1.20%3A8443&token=<43-char base64url>&fp=<sha256 hex>&name=Ada%27s+iPhone&hosts=https%3A%2F%2F100.64.0.7%3A8443

该证书是自签名 P-256 证书，其主题备用名称包括 localhost, 127.0.0.1，以及机器的可到达的私有地址。它保存在 <dataDir>/companion，因此配对在重新启动后仍然有效。更换它会改变指纹并需要重新配对。

网关管理API

失败的承载尝试会根据 IP 地址进行限制：在 10 秒内发生 60 次失败后，网关将应答 HTTP 429（“失败尝试次数过多”），直到窗口过去。否则，错误或撤销的令牌将获取 HTTP 401。

网关状态，已捕获

{ "enabled": false, "port": null, "fingerprint": null, "host": "172.30.0.2", "devices": [] }

如果 host 不是您的手机可以到达的地址（例如容器或 VPN 接口），即使其他一切都正确，配对也会在网络层失败。

在 3D