[Bug] 手机远程页对旧版桌面端(≤3.11.2)无兼容降级:新前端订阅 model-selection/provider-settings,旧 host 报 Unknown channel →「模型加载失败」
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 22
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
提交前确认 · Pre-submission checklist
- 我已搜索过现有 issue,确认这不是重复(远程相关 #228/#328/#343 症状不同;#560/#645 为本地 provider registry 问题,本 issue 为服务端前端与旧 host 协议不兼容)
- 我已阅读 CONTRIBUTING.md
问题类别 · Category
模型设置 / 切换 · Model config(表象)/ 远程控制链路(根因)
涉及的 Agent 框架 · Agent framework
ZCode Agent(自研)
严重程度 · Severity
影响体验 · Major(旧版桌面端用户手机远程完全不可用;降级/回滚用户极易误判为本地残留数据问题)
复现频率 · Reproducibility
必现 · Always(桌面端 ≤3.11.2 + 当前线上 remote/v4 前端;与本地数据无关,全新环境亦必现)
环境 · Environment
- ZCode Desktop 3.11.2(macOS arm64,darwin 24.6.0)
- 手机浏览器打开
zcode.z.ai/remote/v4(连接 URL 自带app_version=3.11.2) - 对照:同一机器升级 3.12.3 后同一手机页面立即恢复正常
问题描述 · Description
2026-09-17 16:35 (CST) 前后 zcode.z.ai 更新了 remote/v4 前端(assets/index-*.js 响应头 Last-Modified: Thu, 17 Sep 2026 08:35:17 GMT)。更新后的前端会向桌面 host 订阅 3.12 才引入的两个通道:model-selection 与 provider-settings。旧版桌面端(≤3.11.2)的 host 未注册这两个通道,订阅失败,导致手机页面无法加载模型配置。
用户侧表现:手机扫码后页面右下角弹出「模型配置加载失败」与「模型加载失败,重试」,输入框发送按钮被禁用,刷新与重试均无效;同一桌面端本地 UI 的模型选择完全正常。
桌面端日志证据(3.11.2 运行期间,与手机页打开/重试时刻一一对应,复现窗口内累计 300+ 条):
[error] [host-log] (local-1) [host] Unknown channel: model-selection
[error] [host-log] (local-1) [host] Unknown channel: provider-settings
升级 3.12.3 后同一路径日志变为 local services ready, all channels registered,手机远程立即恢复,错误归零。
时间线证明是服务端前端更新所致、与本地状态无关:
- 2026-09-17 16:35 之前:3.11.2 与 remote/v4 配合正常;
- 16:35 服务端前端更新(本地桌面端未动)→ 此后 3.11.2 手机远程必现「模型加载失败」;
- 本例机器恰好经历了 3.11.2 → 3.12.x → 覆盖安装回 3.11.2,最初误判为"降级残留文件",实际全新环境安装 3.11.2 同样必现(host 缺通道与本地数据无关)。
复现步骤 · Steps to reproduce
- 安装任意 ≤3.11.2 版桌面端(全新环境亦可,无需任何本地历史数据);
- 点左下角手机图标开启「移动端远程控制」,生成二维码;
- 手机扫码打开 remote/v4 页面;
- 页面弹出「模型配置加载失败 / 模型加载失败,重试」,发送被禁用;桌面端日志同步出现
Unknown channel: model-selection/Unknown channel: provider-settings。
期望表现 · Expected behavior
- remote/v4 前端按连接 URL 已携带的
app_version参数做能力协商:对不支持新通道的旧 host 降级为旧版加载路径,或按版本分发旧前端构建; - 至少在检测到旧 host 时给出明确的「请升级桌面端」提示,而不是与真实原因无关的「模型加载失败」文案。
实际表现 · Actual behavior
- 旧版桌面端手机远程静默损坏,错误文案(模型加载失败)与真实根因(前端/Host 协议不匹配)完全脱节;
- 降级/回滚用户几乎必然误判为本地残留数据导致,排查成本很高(本例实际排查后确认与本地数据无关)。
备注 · Additional context
- 临时解法:升级至 3.12.3。
- 关联但根因不同:#228(大会话中继帧超限)、#328(relay 心跳断连循环)、#560 / #645(本地 provider registry 损坏)均非本症状。
- 由于 remote/v4 前端为服务端统一部署,该问题会同时影响所有未升级桌面端的用户,而非个例环境问题。
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the remote/v4 frontend build referenced by assets/index-*.js and trace how the app_version connection parameter is handled before subscribing to model-selection and provider-settings. Compare this with the older host behavior shown in the logs. Done means old hosts either use a compatible loading path or receive a clear upgrade prompt instead of model-loading errors.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- api, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100