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"会直接跳到系统设置对应面板。

授权一次之后，只要你一直使用同一个已安装的 Shellcove Mac App，重启 app 或重启 Mac 都不会让你重新授权。如果你在开发时来回切换 Xcode Debug 构建、临时目录里的 app 和 /Applications/Shellcove.app，macOS 可能会把它们当成不同 App 身份，需要分别授权。

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 you keep using the same installed Shellcove Mac app. During development, switching between Xcode Debug builds, temporary app paths, and /Applications/Shellcove.app can make macOS treat them as different app identities that need separate permission grants.

• iPhone 上 badge 一直黄色（Connecting...）：确认 Mac 上 Shellcove 正在运行；确认两台设备在同一 Wi-Fi / Tailscale / VPN 可达网络；检查 iOS Settings → Shellcove → 本地网络是否开启。
• Badge 红色 + 错误信息：上面会显示具体错码。POSIX 61 / 65 / 60 通常是网络不通，TLS 错码是证书指纹对不上，protocolVersionMismatch 代表 Mac 和 iOS 的大版本线不一致。证书不匹配时进 iOS 设置里 Forget Device，再重新扫码配对。
• Mac 端 Connected iPhones 显示鬼影连接：在那一行点 Disconnect 红色按钮可以强制断开。等 7 秒左右 Mac 也会通过 heartbeat 检测出来。
• iOS app 后台之后断开：这是 iOS 限制。Shellcove 只在前台维持连接，回到前台会自动重连（1 → 16 秒指数退避）。
• 手动 relay 可达性：设置里的 endpoint 行测的是 TCP 连接耗时，不是 ICMP ping。Tailscale ping 成功不等于 Shellcove TCP 端口一定可达，需要确认 ACL / grants 已允许对应 TCP 端口。

• Badge stuck on yellow "Connecting...": confirm Shellcove is running on the Mac; confirm both devices can reach each other over Wi-Fi, Tailscale, or VPN; 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; protocolVersionMismatch means the Mac and iOS apps are on different major.minor protocol lines. For a cert mismatch, 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. Shellcove maintains the connection only while foregrounded. Returning to the foreground auto-reconnects (1 → 16 s exponential backoff).
• Manual relay reachability: endpoint rows measure TCP connect time, not ICMP ping. A successful Tailscale ping does not prove Shellcove TCP ports are allowed; check ACL / grants for the exact TCP port.

• 远程桌面没有画面：先确认 Mac 已授权「屏幕录制」，然后关闭再重新打开「远程桌面」。弱网或 relay 下可能会回落到 TCP 视频路径，首次出画面会慢一点。
• 触控位置不准：先等显示器列表加载完成，再点画面移动光标；如果切换了 Mac 显示器或缩放过画面，先重置缩放再试。
• 窗口文本为空：确认 Mac 已授权「辅助功能」，并让目标 App / 终端窗口成为焦点。有些 App 不向 Accessibility 暴露完整文本，这时请改用远程桌面。
• 窗口文本颜色不完全一致：这是正常的。Shellcove 读取真实字符，样式只使用目标 App 通过 Accessibility 暴露的信息；像素级颜色以远程桌面为准。

• No Remote Desktop picture: first confirm Screen Recording permission is granted on the Mac, then close and reopen Remote Desktop. On weak links or relay endpoints, Shellcove may fall back to the TCP video path and take a little longer to show the first frame.
• Touch position feels wrong: wait until the display list has loaded before moving the cursor. If you switched displays or zoomed the view, reset zoom and try again.
• Window Text is empty: confirm Accessibility permission is granted on the Mac, then focus the target app or terminal window. Some apps do not expose full text through Accessibility; use Remote Desktop for those.
• Window Text colors are not identical: expected. Shellcove reads real characters and only uses style metadata exposed through Accessibility. Use Remote Desktop when exact pixels matter.

• 点击底部「输入到 Mac」会打开全屏输入工作区并自动聚焦系统键盘。写好后点「发送到 Mac」，文本会逐字符输入到 Mac 当前焦点窗口。
• 你可以使用 iOS 听写、微信输入法或任意第三方键盘。Shellcove 只接收最终文本，不请求麦克风或语音识别权限。
• 如果 iOS 听写按钮没有出现，请检查系统键盘/听写设置；这不是 Shellcove 权限开关。
• 发送前请确认首页当前窗口行显示的是你要输入的 Mac App / 窗口。需要切换时，点窗口行打开窗口选择器。

• Tap the bottom "Input to Mac" bar to open the full-screen input workspace and focus the system keyboard. After composing, tap "Send to Mac" and the text is typed into the focused Mac window character by character.
• You can use iOS Dictation, WeChat Keyboard, or any third-party keyboard. Shellcove receives only the final text and does not request Microphone or Speech Recognition permission.
• If the iOS Dictation button does not appear, check system keyboard/dictation settings. It is not a Shellcove permission toggle.
• Before sending, confirm the current-window row shows the Mac app/window you want to target. Tap that row to open the window picker when you need to switch.

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

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