返回犀客博客

试装手册 · Skill v0.2

Xieke Phone 跨平台安装指南

把带 SIM 的 4G 模块接到 Windows、Mac 或 NAS，再用 Xieke Phone 在 iPhone 和 iPad 上测试通话与短信。三种部署路线共用一个 Skill。

下载部署 SkillZIP了解 Xieke Phone

先备齐试装所需的东西

  • 一只经确认兼容语音与短信的 4G USB 模块、已开通相应服务的 SIM 卡，以及能保持联网的主机。
  • 一个试点账号，以及由服务方单独交付的配置、可信清单 SHA-256 和对应 CPU 架构的网关镜像。
  • 在 iPhone 或 iPad 上取得可用的试点 App。公开的 ZIP 提供预检工具、说明和部署脚本，不含 App 安装文件、账号或镜像。

还没拿到试点配置？可以先做设备预检。请只回报平台、CPU 架构、模块型号和阻碍，不要发送 SIM 号码、配置文件或密钥。

用 WorkBuddy 协助安装

在 WorkBuddy 中选择「技能 → 添加技能 → 上传技能」，导入下载的 ZIP。也可以解压后在本机终端运行脚本，以下命令以解压后的技能目录为起点。

用 xieke-phone-gateway 在这台机器上部署。我已插好 4G 模块，请先检查系统和设备，缺项就告诉我卡在哪一步。
WorkBuddy 导入说明

按模块实际插入的机器选择路线

Windows

windows-wsl
  1. 把模块插到 Windows 11 x64 电脑，从 PowerShell 运行下方预检。也可直接运行包内的试装 EXE；它检查环境，并可按提示准备缺少的组件。
  2. 准备专用 Ubuntu 24.04 WSL 2 发行版和本机 Docker Engine、Compose 插件。用 usbipd list 确认实际 Bus ID，再按微软说明共享并附加这只空闲模块。别照抄别人的 Bus ID。
  3. 在 WSL 内进入技能目录运行 Linux 预检。确认 USB 控制接口、录音和播放节点属于同一只模块。试点配置存到 WSL 自己的 Linux 文件系统。

Windows PowerShell

powershell.exe -NoProfile -File .\scripts\preflight-windows.ps1

保持 WSL 终端开启，核对空闲模块后再共享并附加。把示例中的 ID 换成 usbipd list 列出的值；首次 bind 需要管理员权限。

usbipd list
usbipd bind --busid <BUS-ID>
usbipd attach --wsl --busid <BUS-ID>

在网关的 Linux 环境内

python3 scripts/preflight-linux.py --target windows-wsl --json
微软 USB/IP 操作指南

Mac

macos-vm
  1. 在 Mac 上运行下方预检，核对 CPU、模块和虚拟机软件。Intel Mac 使用 amd64 Linux 客体与镜像；Apple 芯片使用 arm64。
  2. 新建支持 USB 直通的专用 Ubuntu 虚拟机，通过虚拟机的 USB 菜单把整只模块交给客体。在客体中准备 Python 3、Docker Engine 与 Compose 插件。只在 Mac 上看到 USB 设备还不够。
  3. 把技能目录复制到客体，进入目录运行 Linux 预检，核对模块的控制接口以及双向音频节点。网关在虚拟机里运行。

Mac 终端

python3 scripts/preflight-macos.py --json

在网关的 Linux 环境内

python3 scripts/preflight-linux.py --target macos-vm --json
UTM USB 直通指南

NAS

fnos
  1. 把模块插到运行网关的飞牛或兼容 Linux NAS。在该 NAS 的本机终端或已授权 SSH 会话里进入技能目录。
  2. 确认 NAS 可访问本机 Docker Engine 和 Compose 插件，再运行下方预检。只看到 Docker 网页或 USB 设备，不代表系统已提供模块对应的录音、播放和控制接口。
  3. 选择适配 NAS 架构和实际模块的镜像及配置。部分模块需要专用语音适配；缺少对应接口时先停下核对硬件支持。

NAS 终端

python3 scripts/preflight-linux.py --target fnos --json
飞牛账号与 SSH 说明

用独立配置部署网关

Windows 在 WSL 2 内操作，Mac 在 Linux 虚拟机内操作，NAS 在本机操作。把服务方给的配置放进仅当前用户可访问的 Linux 目录（0700），其中 .env 权限设为 0600。下面的示例要替换为实际目录、服务方另行提供的清单摘要，以及表中对应的目标。

profile_dir="$HOME/xieke-phone-pilot"
manifest_sha256='<trusted-64-character-SHA256>'
target='windows-wsl'  # macos-vm / fnos

python3 scripts/verify-profile.py --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target" &&
python3 scripts/deploy-linux.py plan --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target"

先验证配置并查看部署计划。核对计划中的项目名、架构与设备路径，再启动网关并检查状态。

python3 scripts/deploy-linux.py apply --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target" &&
python3 scripts/deploy-linux.py status --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target"

需要撤回试装时，在同一环境使用相同参数，把 apply 换成 rollback。回退会保留项目数据卷。

容器跑起来之后，实测这几项

  • App 注册后，用普通号码实测呼出和呼入，双方都能听到声音。
  • 在带语音菜单的通话中按键，确认菜单有响应。
  • 锁屏后测试系统来电、接听及通话声音，再测试短信收发、锁屏提醒与解锁后的正文。
  • 拔插模块或重启后重新检查设备路径，再测一次。路径变了，请服务方按当前设备更新试点配置。

这是试装流程。设备被识别、容器运行和 App 注册是不同的检查项；只有实际打通电话、收发短信才能确认对应功能。不同模块、NAS 型号及虚拟机组合需要分别验证。