Wiki AI

ZCode Web 与手机远控

3分钟阅读

packages/web

@zcode/web 是 Web 客户端，核心是手机远控 SPA（mobile remote control）。

  • 入口 web/src/main.tsx：复用 @zcode/ui 的 Root 与 V4 会话组件，通过 @zcode/client 的 connectViaWebSocket / connectViaProtocol + acked relay protocol 连外部 relay。
  • auth/：Zai OAuth 登录/回调。
  • share/：会话分享落地页与预览客户端。
  • webRemoteControl*.ts：生命周期、主题种子、版本守卫、workspace bridge。
  • 构建四个 base：/remote、/remote/v3、/remote/v4、/remote/__test__（见根 package.json build 脚本）。
  • 它是 clientMode = web-remote-replayable 的真实来源。

手机远控架构

上游 docs/web-remote-control/web-remote-control-architecture.md 的关键约束：

  • 手机 /remote 只 attach 已有 Host/CLI，不创建独立 Agent、Local Host 或远程会话。
  • 通过 shared-host attachment 进入桌面已有 Window Host，复用同一 task runtime owner。
  • relay 与 Main 只做鉴权、配对、心跳、帧透传与 attachment 调度，不保存任务队列、快照等业务状态。
  • 手机采用 web-remote-replayable：gap 时靠 snapshot 重同步；与桌面 desktop-continuous 的恢复语义不能互相扩散。

详见 server-remote、zcode-protocol。

会话分享

  • @zcode/web-share：独立分享入口，不经完整 Web bootstrap。渲染前同步 applyTheme() 防止浅色壳套深色 Markdown；复用 web/src/share + web/src/auth + share-ui；支持 OAuth callback 路由 /cn/share/callback、/share/callback 与 mock owner token。
  • @zcode/share-ui：极薄，只导出 ConversationShareReadonlyTimeline（转发自 ui/src/v4/ConversationShareReadonlyTimeline.tsx）+ Theme + styles.css，避免暴露完整 @zcode/ui 边界。

Android 远控壳（packages/android）

packages/android 是 Compose + WebView 的远控壳（无 package.json，Gradle Kotlin）：

  • MainActivity.kt：解析 zcode://remote 与 https://zcode.z.ai/remote deep link、扫码/最近链接、WebView 打开远控。
  • RemoteControlKeepAliveService.kt：前台 dataSync Service，注释明确”只给远控会话一个用户可见保活边界，真正状态恢复交给 web 端 replayable snapshot”。
  • 依赖 camera2 + ML Kit barcode、Compose BOM，minSdk 24 / targetSdk 36。

统一发行包里的 Web 模式

顶层统一分发包的 zcode --web 启动”现有本地 HTTP/WebSocket server + Web assets + Agent”，保持 localhost 绑定、自动端口、非 loopback 默认 token。注意这与 cli-tui 中 Agent CLI 自身没有 --web 参数不冲突——分流发生在 bin/zcode.mjs launcher。详见 distribution。

相关页面

关系图谱

反向链接