一个为 ZCode Remote 打造的 Android 原生客户端，提供沉浸式全屏体验，告别浏览器地址栏与工具栏的干扰。
-blue){kind=icon}
- 🖥️ 沉浸式全屏 —— 内容铺满整个屏幕，隐藏浏览器的地址栏、工具栏与菜单
- 🎨 沉浸式状态栏 —— 透明状态栏，内容延伸到刘海屏边缘
- 📋 会话管理 —— 粘贴一次连接 URL，保存后下次一键进入，无需重复复制
- 🌙 暗色主题 —— 对齐 ZCode Remote 网页的
zai-dark风格，长时间使用不刺眼 - 🔄 横竖屏自适应 —— 横竖屏切换不重新加载页面（避免大体积 bundle 重载）
- 🔒 本地存储 —— 会话凭证仅存在应用沙箱内，不上传任何服务器
| 技术 | 用途 |
|---|---|
| Kotlin 2.0 | 主语言 |
| Jetpack Compose + Material3 | UI 框架 |
| WebView | 加载 ZCode Remote 网页（套壳方案） |
| Navigation Compose | 页面路由 |
| DataStore Preferences | 会话本地持久化 |
基于对 zcode.z.ai/remote/v4 的实际调研：
- 它是 Vite 打包的 SPA，移动端 viewport 友好
- 无 CSP / X-Frame-Options 限制，WebView 可正常加载
- 网页本身 UI 已设计完善
套壳能 100% 复用官方网页的所有功能，核心痛点（浏览器 UI 干扰 + 不能全屏）恰好是套壳能完美解决的，无需原生重写。
- 在电脑端 ZCode 打开「远程」功能，复制生成的连接 URL（形如
https://zcode.z.ai/remote/v4?sid=...） - 打开 ZRemote，点「粘贴」按钮或手动粘贴 URL
- 点「连接」，进入沉浸式全屏会话
- 退出时可选择保存会话，下次直接从「已保存的会话」一键进入
⚠️ 连接 URL 带一次性凭证（含时间戳），过期后会提示AUTH_FAILED，重新从电脑端复制最新的即可。
- Android Studio（Hedgehog 2023.1.1 或更新）
- JDK 17
- Android SDK 34
# 1. 克隆
git clone https://github.com/PanCodeInventory/ZRemote.git
cd ZRemote
# 2. 生成 Gradle Wrapper（首次需要，或直接用 Android Studio 打开自动生成）
gradle wrapper --gradle-version 8.7
# 3. 配置 SDK 路径（写入 local.properties，已 gitignore）
echo "sdk.dir=$HOME/Library/Android/sdk" > local.properties
# 4. 构建 Debug APK
./gradlew assembleDebug
# 产物：app/build/outputs/apk/debug/app-debug.apk也可以直接用 Android Studio 打开项目目录，Sync Gradle 后点 Run。
前往 Releases 下载最新的 ZRemote-debug.apk，传到手机安装即可（需开启「允许未知来源应用」）。
app/src/main/java/com/zcode/client/
├── MainActivity.kt # 入口，承载 Navigation + 窗口模式
├── ui/
│ ├── SessionViewModel.kt # 会话列表状态管理
│ ├── theme/ # 暗色主题（Color / Type / Theme）
│ └── screen/
│ ├── ConnectScreen.kt # 粘贴 URL 连接页
│ ├── SessionScreen.kt # WebView 全屏会话页（核心）
│ └── SessionListScreen.kt # 已保存的会话列表
├── web/
│ ├── WebViewConfig.kt # WebView 配置（DOM Storage / Cookie / wss）
│ └── ZCodeWebViewClient.kt # WebViewClient（加载 / 错误回调）
└── data/
├── Session.kt # 数据模型
├── SessionStore.kt # DataStore 持久化
└── UrlValidator.kt # URL 校验
WebViewConfig.kt 中每一项配置都基于对 ZCode Remote 的调研结论，请勿随意关闭：
| 配置 | 原因 |
|---|---|
javaScriptEnabled |
SPA 必需 |
domStorageEnabled |
会话凭证存在 localStorage |
CookieManager.setAcceptCookie |
CDN 下发反爬 Cookie，关掉会被拦 |
mixedContentMode = ALWAYS_ALLOW |
防止降级资源被拦 |
- 扫码登录（解析电脑端二维码，免复制 URL）
- 多服务器支持（自建 / 内网 ZCode 部署）
- 文件下载 / 上传（WebView 文件选择回调）
- 推送通知（远端有新消息时提醒）
MIT License © 2026 潘崇实 (PanCodeInventory)
本项目为第三方客户端，与 ZCode 官方无隶属关系。
ZCode Remote 的所有功能与版权归官方所有。