Shellcove Support

iPhone 端的 Shellcove 需要搭配 Mac 端一起使用。Mac 端是免费的，从下面下载并拖到「应用程序」文件夹即可。已通过 Apple 公证，Gatekeeper 不会弹未识别开发者警告。

系统要求：macOS 13 Ventura 或更新版本，Apple Silicon / Intel 都支持。

The Shellcove iPhone app pairs with a Mac client. The Mac client is free — download and drag it into Applications. Both the DMG and the app inside are signed with our Apple Developer ID and notarized by Apple, so Gatekeeper opens it without prompts.

Requirements: macOS 13 Ventura or newer; Apple Silicon and Intel both supported.

1. 在 Mac 上打开 Shellcove，等主窗口显示配对二维码。
2. iPhone 上点击"Scan QR"，第一次会请求相机权限，允许。
3. 把 iPhone 摄像头对准 Mac 屏幕上的二维码。识别成功后 iPhone 会自动跳到主界面。
4. 顶部的小圆点会先变黄（连接中），约 1–2 秒后变绿（已连接）。Mac 主窗口的"Connected iPhones"会显示这台 iPhone。
5. 第一次连接 iOS 系统会请求"本地网络"权限，记得允许。如果错过了，到 iOS 设置 → Shellcove 里打开本地网络开关。

1. Open Shellcove on the Mac and wait for the main window to show the pairing QR.
2. On the iPhone, tap "Scan QR" — the first time will request camera permission.
3. Aim the iPhone camera at the QR on the Mac screen. On scan, the iPhone returns to the Home view automatically.
4. The dot at the top of the iPhone screen turns yellow (connecting), then green (connected) in 1–2 seconds. The Mac's "Connected iPhones" row will list this iPhone.
5. On first connection iOS asks for "Local Network" permission — allow it. If you missed the prompt, go to iOS Settings → Shellcove → Local Network and turn it on.

Shellcove Mac 端需要两项权限才能正常工作：

• 辅助功能：用于把 iPhone 发来的按键和鼠标事件注入到系统。
• 屏幕录制：用于把 Mac 屏幕实时投屏到 iPhone / iPad 上。

主窗口的 Permissions 段会显示当前状态。如果有红色感叹号，点旁边的"Open Settings"会直接跳到系统设置对应面板。

授权一次之后，只要 Mac 端用同一个 Apple Development 证书签名，重启 app 或重启 Mac 都不会让你重新授权。如果你每次 build 都要重授一遍，多半是 ad-hoc 签名导致的——在 Xcode 的 Signing & Capabilities 里选好你的 Team。

Shellcove on the Mac needs two permissions to work:

• Accessibility: required to synthesize the keystrokes and mouse events sent from the iPhone.
• Screen Recording: required to mirror the Mac screen live to the iPhone / iPad.

The main window's Permissions section shows the current status. If you see a red exclamation mark, the "Open Settings" button next to it jumps straight to the right pane in System Settings.

Once granted, permissions persist across app restarts and Mac reboots — as long as the Mac app stays signed with the same Apple Development certificate. If you find yourself having to re-grant on every rebuild, that's a sign you're picking up an ad-hoc signature; pick your team in Xcode's Signing & Capabilities tab.

• iPhone 上 badge 一直黄色（Connecting...）：确认 Mac 上 Shellcove 在前台运行；确认两台设备在同一 Wi-Fi 网络；检查 iOS Settings → Shellcove → 本地网络是否开启。
• Badge 红色 + 错误信息：上面会显示具体错码。POSIX 61 / 65 / 60 通常是网络不通，TLS 错码是证书指纹对不上——这种情况进 iOS 设置里 Forget Device，再重新扫码配对。
• Mac 端 Connected iPhones 显示鬼影连接：在那一行点 Disconnect 红色按钮可以强制断开。等 7 秒左右 Mac 也会通过 heartbeat 检测出来。
• iOS app 后台之后断开：这是 iOS 限制，目前 V1 只在前台维持连接。回到前台会自动重连（1 → 16 秒指数退避）。

• Badge stuck on yellow "Connecting...": confirm Shellcove is in the foreground on the Mac; confirm both devices are on the same Wi-Fi; check iOS Settings → Shellcove → Local Network is on.
• Red badge with an error: the underlying error code is shown right below. POSIX 61 / 65 / 60 typically means network unreachable; a TLS code means the cert fingerprint mismatched — in that case Forget Device in iOS Settings and re-scan the QR.
• Ghost connection in the Mac's Connected iPhones list: click the red Disconnect button on that row to force-drop it. The Mac's own heartbeat will also clean it up within ~7 seconds.
• iOS disconnects when backgrounded: iOS restriction; V1 maintains the connection only while in the foreground. Returning to the foreground auto-reconnects (1 → 16 s exponential backoff).

• 长按麦克风按钮说话，松开后会把识别到的文本作为键盘输入发到 Mac 当前焦点窗口。
• 语音识别全程在本机完成，音频不会上传。第一次使用会请求麦克风和语音识别权限。
• 识别精度依赖 iOS 系统的 Speech 框架。混合中英文的指令通常没问题。

• Hold the mic button to speak; on release the transcribed text is sent to the Mac as keyboard input directed at the focused window.
• Recognition runs entirely on-device — audio is never uploaded. First use prompts for microphone and speech-recognition permission.
• Accuracy depends on Apple's Speech framework. Mixed Chinese/English commands generally work fine.

问题没在上面找到答案？发邮件给 [email protected]，或到 反馈页 填表（也是发到同一个邮箱）。

Couldn't find your issue above? Email [email protected], or use the feedback form (it routes to the same address).