# OpenChamber 手机客户端(asuka/Go)调研与开发计划 > 调研对象:asuka(Go + 原生控件)v0.1.1 / main,OpenChamber 2.7.0,opencode v2.2.7 > 目标:Android 优先的手机客户端,MVP = 输入地址 + 密码连接(可选 http/socks5 代理),浏览并操作现有会话 --- ## 0. 结论 **可行,且 asuka 的覆盖度比预期好。** 但真正的风险不在 UI,而在三处: 1. **Android 构建链**:本机没有 JDK / Android SDK / NDK。asuka 要求每个平台自己的工具链,第一次搭环境要花半天,且 **asuka v0.1.1 在 Linux 上 `go install` 会编译失败**(`syscall.SO_REUSEPORT`),必须从 `main` 安装。 2. **release 版默认禁止明文 HTTP**:asuka 只在 debug manifest 里开 `usesCleartextTraffic`。连 `http://192.168.x.x:3000` 这类自建服务需要额外处理(加一个只声明 manifest 的 native 包,或统一走 HTTPS)。 3. **asuka 仍在 0.1.x**:API 还会变。需要 pin 版本,并且**先用 Web 目标(已验证可构建)和 Linux 桌面目标做 UI 迭代**,再落到 Android。 **建议不要直接写界面**:先花 0.5–1 天写一个不依赖 UI 的 Go 客户端包 + CLI 探针,连本机 OpenChamber 跑通 「健康检查 → 密码登录换 token → 列会话 → 拉消息 → 订阅 SSE → 发一条 prompt」, 把协议层的不确定性一次性消掉,再投入 UI 和 Android 环境。这样 Android 环境出问题也不会堵住进度。 --- ## 0.1 进展(2026-11-15) M0 完成,并继续做到了 M3。所有验证都连的是本机正在运行的 OpenChamber 2.7.0(无密码): | 项 | 结果 | | --- | --- | | Go 版本 | **mise 安装的 1.26.3**(`which go` → `~/.local/share/mise/installs/go/1.26.3/bin/go`),不是系统 Go | | asuka CLI | 从 `@main`(`v0.1.2-0.20261114215826-2602a98fec66`)安装成功;`@latest` 在 Linux 编译失败(`syscall.SO_REUSEPORT`) | | 协议层 | `internal/ocapi`:health、`/auth/session`(密码登录 + 设备 token)、会话列表/分页、消息分页、prompt/interrupt/model/agent、权限、SSE、代理、证书指纹 | | CLI 探针 | `cmd/ocprobe`:对真实服务器跑通 `health`、`sessions`、`messages`、`events`(收到 `server.connected`) | | 界面 | 连接页 + 会话列表 + 聊天页(`internal/appui`),`asuka build --platform web` 通过(14.5 MB wasm) | | 持久化 | `internal/storage`:连接信息进 store,token 进 `asuka/sdk/secure`(Android Keystore);安装 ID 用于设备去重 | | 自动恢复 | 冷启动读 token 自动重连;token 失效自动清除并提示重新输入密码;401 统一登出 | | 实时 | 连接后订阅 `/api/event`:列表增量、运行状态、权限计数;断线退避重连,恢复后重读列表与当前会话尾部 | | 聊天 | 消息分页(30/页,向上加载)、Markdown 流式渲染、思考/工具结果折叠、乐观发送(客户端 `msg_` id)、停止、错误提示 | | 测试 | `go test ./... -race` 全绿;`uitest` 无头测试覆盖:密码登录、错密码、免密服务器、token 自动重连、token 失效、打开会话、发送消息、SSE 流式增量、权限卡片与回复 | | Android 真机 | 模拟器(Android 36 / x86_64)安装 debug 包,连接本机 OpenChamber,会话列表与聊天页均正常(截图见下) | | release 构建 | `asuka build -p android` 产出 `dist/OpenChamber.aab`;合并后的 release manifest 含 `usesCleartextTraffic="true"`(由 `netcfg` 模块合入),明文 HTTP 在 release 可用 | | 会话操作 | 滑动归档/删除、长按菜单、重命名(Alert 输入框)、删除二次确认 | | 权限审批 | 聊天页内联卡片(允许一次/总是允许/拒绝),启动时补齐待批列表,SSE 实时增删 | | 多实例 | 保存多个服务器,按最近使用排序;首屏选择连接,连接后可切换;添加/编辑/删除;从旧的单连接记录自动迁移 | | 连接界面(对齐官方) | 首连引导 →「手动输入地址」;有保存时列表:最近使用的置顶卡片(连接/已连接)、其他服务器、添加按钮;每行「…」菜单(连接/编辑/删除,删除二次确认);密码按需弹层、失败保留并可从表单重试;连接失败时回到表单并保留输入 | | 顶栏服务器入口 | 会话页只保留一个「服务器」图标按钮,打开实例列表;点选实例即断开当前连接并连到所选实例;「断开当前连接」移入实例列表 | | 首屏无导航栏 | 未连接时直接显示服务器列表(自带标题),不再套用带「新建/刷新」的应用栏;连接后才建立导航栈与动作栏 | | 轮次页脚 | 每个回合结束后显示「模型 · Agent · 耗时」,右侧「…」打开操作面板(时间戳、复制回答、从这里分叉);模型名由 `/api/model` 解析,耗时按 prompt→完成计算;模型图标改用内置 SVG(不依赖平台符号表) | | 用户消息操作 | 每条用户消息下有「时间 · 复制 · …」一排;「…」面板含时间戳、复制消息、从此消息前分叉 | | 长会话加载 | 首屏只取最新 30 条(倒序);请求 `x-openchamber-part-shells: v1` 让服务端省略已完成工具结果(本会话 530KB→180KB);展开工具时再按消息 id 取全文;流式期间用事件本地更新工具/步骤,不再反复拉整页;60s 超时 + 重试;连接建立不重复同步 | | 会话搜索 | 顶栏搜索按钮展开输入框,350ms 去抖后走服务端 `search` 参数,可清除恢复全量 | | 附件 | 输入区可添加照片/文件(最多 5 个,单个 ≤10MB),以 data URL 随 prompt 发送;发送前显示可移除的附件条 | | 回到最新 | 上滑离开底部后出现「最新」悬浮按钮,回到末尾并重新贴底 | | 朗读回答 | 回合菜单可用系统 TTS 朗读回答,或停止朗读 | | 图片内联预览 | 发送的图片附件保留本地副本,消息气泡内直接显示缩略图(200×150 圆角),不受后续重载影响 | | 撤回 | 用户消息菜单「撤回此消息及之后」:二次确认后 stage+commit 服务端 revert,删除该消息及之后内容 | | 应用图标 | 使用 OpenChamber 官方图标(`assets/icon.png`,取自 `packages/mobile/assets/icon-only.png`) | | Agent 选择 | 只列 `mode=primary` 的 Agent,子智能体(General/Explore)不再出现 | | 模型/Agent | 聊天页顶栏打开选择 Sheet(可搜索),切换后同步会话列表 | | 新建会话 | 会话页「新建」:标题 + 工作目录(服务端默认目录与已加载会话的目录),创建后直接进入聊天 | | 下一步 | 打磨:splash、中英 i18n、空态与错误页;归档会话查看/恢复;可选 fork asuka 支持更低 minSdk | ### 终端功能评估(未实现) - **官方实现**:`/api/terminal/ws` WebSocket(v3 二进制 JSON 控制帧),携带 URL-token 鉴权与 relay 路由;客户端需做 ANSI/终端仿真渲染、行列 resize、输入回传、触摸滚动/选择。 - **方案 A:原生终端视图(Kotlin 包)**——把 Termux 系的 `terminal-view`(Android TerminalView)作为 asuka native view 集成;体验最好(复制/选择/IME),但要把输入流、resize、主题、生命周期接到 Go 侧,工作量约 2–4 天并要维护。 - **方案 B:Go 端 ANSI 渲染到 `ui.Canvas`/原生 TextView**——有现成 Go VT 解析器(charmbracelet/x/ansi、vt10x),但按网格逐格绘制性能与文本选择是难点;适合只读日志场景。 - **方案 C:`ui.WebView` + 本地 xterm.js**——最快(1–2 天),交互完整,但回到 WebView 渲染,偏离 asuka 原生初衷,且需处理 WebView 的 WS 与凭证注入。 - **建议**:先做方案 A 的 PoC(纯查看 + 输入),若 asuka native view 集成顺利再做完整版;否则退而求其次用 C 快速交付。 ### 与官方移动端连接界面的差异(有意保留) - 官方用「代理请求头(如 Cloudflare Access)」;原生版用 **HTTP/SOCKS5 代理 + 自签证书信任**,按需求保留。 - 官方有二维码扫描 / Pairing v2 / Relay;原生版尚未做(asuka 有 `sdk/scan`,可后续补)。 - 官方表单有 client token 字段;原生版以密码登录自动签发设备 token,不要求手填 token。 - 官方在应用内以「Instances」面板管理;原生版用同内容的底部全屏 Sheet,语言与结构保持一致。 **明文 HTTP 的落地方式**(用户已确认 release 也要支持):native 包 `netcfg` 已加入(`main.go` 里空白导入),Gradle 会把它的 manifest 合并进 release。已实测 release 的合并 manifest 含 `usesCleartextTraffic="true"`,并用 release APK 连上了 `http://10.0.2.2:3000`: ```bash asuka native new ./netcfg # 生成 Go/Kotlin/Web/desktop 各平台骨架 ``` 然后在 `netcfg/android/src/main/AndroidManifest.xml` 写: ```xml ``` 库 manifest 会合并进 app 的 manifest;`asuka` 只在 debug manifest 里自带这条,所以 release 需要它。若想更严格,可用 `android:networkSecurityConfig` 只放行 RFC1918 网段。 ### 环境(已就绪) - JDK 21:`~/SDK/jdk-21`(TUNA 镜像的 Temurin 21.0.13),给 Gradle 本身 - JDK 17:`~/SDK/jdk-17`(Temurin 17.0.21),Android 工程要 Java 17 toolchain;在 `~/.gradle/gradle.properties` 里登记: `org.gradle.java.installations.paths=/home/blumia/SDK/jdk-21,/home/blumia/SDK/jdk-17` - Android SDK:`~/SDK/AndroidSDK` - `ANDROID_HOME=$HOME/SDK/AndroidSDK` - `JAVA_HOME=$HOME/SDK/jdk-21` - 组件:platform-tools、platforms;android-36、build-tools;36.0.0、NDK 30.0.16248370、emulator、system-images;android-36;google_apis;x86_64 - 模拟器:AVD `oc36`(Android 36,x86_64),无窗口启动: `emulator -avd oc36 -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect` - Gradle:wrapper 需要 `gradle-8.14.3-bin.zip`;`services.gradle.org` 在本机超时,已从腾讯镜像 `https://mirrors.cloud.tencent.com/gradle/` 下载并放进 `~/.gradle/wrapper/dists/gradle-8.14.3-bin/cv11ve7ro1n3o1j4so8xd9n66/` - release 签名:本机用测试 keystore `~/SDK/test-upload.jks`(`ASUKA_KEYSTORE`、`ASUKA_KEY_ALIAS=upload`、密码 `testpass`);正式发布请换成自己的上传密钥 - 运行:`asuka dev --platform android`(首次会启动模拟器/安装 debug 包) --- ## 1. asuka 调研 ### 1.1 它是什么 / 怎么工作 - Go 写业务和界面,每个平台用**自己的原生控件**渲染(Android 是 Android Views + Material 3),不是 WebView,也不是 canvas。 - 组件函数**只执行一次**;之后靠 signals 做细粒度更新。**组件体里读 signal 只读到那一次**,必须用 `signal.Func` / `ui.Val` 这类 accessor(`asuka vet` 会自动检查这类错误)。 - **所有 signal 写入必须在主线程**。网络、SSE、文件都要在 goroutine 里做,结果用 `ui.Post` 回主线程。 - `asuka dev -p android` 默认热重载:Go 代码跑在电脑上,手机里的 player 负责显示;`--no-hot` / release 才把 Go 编进 APK。 - Android 构建参数(asuka 自带 Gradle 工程):`minSdk 33`、`compileSdk / targetSdk 36`、AGP 8.12、Kotlin 2.1.20、JDK 17。release 产物是 `.aab`。 ### 1.2 MVP 需要的组件(已确认存在) | 需求 | asuka 能力 | | --- | --- | | 页面导航、标题栏、返回 | `ui.Stack` + `ui.UseNavigator` + `ui.ScreenOptions{Title, Actions, Search}` | | 底部 tab | `ui.Tabs`(Android 上是 Material 底部导航) | | 会话列表 | `ui.List`(回收列表)+ `Section`(按项目分组)+ `OnRefresh`(下拉刷新)+ `SwipeActions`(归档/删除)+ `OnEndReached`(分页) | | 聊天时间线 | `ui.List{Anchor: ui.AnchorBottom, OnStartReached: 加载更早}`:新消息贴底、行高变化保持贴底,用户上滑后不打扰 | | Markdown / 代码块 | `asuka/sdk/markdown`:`markdown.View{Text, Streaming}`,流式追加只重排正在写的那一块;GFM、表格、脚注、数学 | | 输入框 | `ui.TextField{Multiline, Lines, Selection, Placeholder}`,键盘避让靠 `ui.SafeArea` | | 弹窗 / 确认 | `ui.Sheet`、`ui.Alert`、`ui.ActionSheet` | | 安全存 token | `asuka/sdk/secure`(Android = Android Keystore AES-GCM + 私有 SharedPreferences) | | 轻量设置 | `asuka/sdk/store` 的 `store.Signal`(跨启动保留) | | 前后台 | `app.OnLifecycle(Foreground/Background/MemoryWarning)` | | 图片展示(后续) | `ui.Image`(http(s) 直读,Android 有磁盘缓存) | | 通知(后续) | `asuka/sdk/notify` / `asuka/sdk/push` | ### 1.3 已经踩到的坑 - **v0.1.1 在 Linux 编译失败**: `internal/devtunnel/listen_unix.go:19` 用了 `syscall.SO_REUSEPORT`(Linux 的 `syscall` 没有),main 已改成 `golang.org/x/sys/unix`。 → 必须 `go install github.com/egoist/asuka/cmd/asuka@main`,并在项目 `go.mod` 里 pin 住伪版本。 - **本机可运行的验证**:`asuka new` + `asuka build --platform web` 成功(6.2 MB wasm / 1.7 MB gzip)。 - **Linux 桌面目标可用**:GTK4 + libadwaita 1.7.6 运行时已装,可直接 `asuka dev`(GTK 窗口)做原生手感调试;缺 `libadwaita-1` 的 pkg-config 不影响(asuka 是动态加载)。 - **不要用 WebView 渲染聊天**:`ui.WebView` 存在,但那样就退回现有 Capacitor 方案了;Markdown 用官方 `sdk/markdown`。 --- ## 2. 服务端对接 ### 2.1 结构 ``` [手机 app] --HTTPS/HTTP--> [OpenChamber :3000] ├─ /auth/*, /api/client-auth/* 认证与设备 token ├─ /api/session/*, /api/event, ... 透传 opencode v2 API └─ /health, /api/opencode/health 探活与版本 ``` `/api/*` 基本是 opencode v2 API 的通用反代(`packages/web/server/lib/opencode/proxy.js`),所以按 opencode v2 的契约写,OpenChamber 升级时兼容性最好。 ### 2.2 认证(MVP 核心,已验证) 官方 Capacitor 客户端的字段可以直接照抄(`packages/ui/src/apps/mobileConnections.ts`): 1. **探活 + 版本 + 防串服** `GET /health`(免鉴权) → `{status:"ok", openchamberVersion, runtime, compatibility, serverId?}` 记下 `serverId`,之后重连时校验,避免路由器把同一个 LAN 地址分给了另一台机器。 2. **用已有 token 探测** `GET /auth/session` + `Authorization: Bearer ` → `200 {authenticated:true, scope:"client"}` / `401 {authenticated:false, locked:true}` 没有配置密码的服务器返回 `{authenticated:true, disabled:true}`,此时不需要 token。 3. **密码登录并一次拿到设备 token** ```http POST /auth/session Content-Type: application/json { "password": "……", "trustDevice": true, "issueClientToken": true, "clientLabel": "OpenChamber Native", "clientKind": "mobile", "deviceName": "Pixel 9", "devicePlatform": "android", "deviceModel": "Pixel 9", "dedupeKey": "<本机安装 ID,稳定不变>" } ``` → `{authenticated:true, clientToken:"oc_client_…", client:{…}}` - token 默认 **7 天**(服务端 `OPENCHAMBER_UI_TRUSTED_SESSION_TTL_DAYS`),只存哈希;过期/撤销后 API 返回 401。 - `dedupeKey` 让同一台手机反复登录只占**一条**设备记录(官方用 localStorage UUID;我们用 `store.Signal` 持久化一个 UUID)。 - 密码错误有限流:返回 `429 {retryAfter}`,UI 必须显示冷却。 - 之后所有请求带 `Authorization: Bearer oc_client_…`,**不要依赖 cookie**(原生客户端没有 cookie jar;relay 场景 cookie 也过不去)。 - 不要发 `Origin` 头(Go 默认不发);服务端只对带 Origin 的请求做来源校验。 ### 2.3 会话与消息接口(已验证) 目录作用域:会话类请求带 `x-opencode-directory: `;列表接口也可用 `?directory=`(OpenChamber 会规范化)。不传 directory 的 `/api/session` 是**全局列表**,每条会话自带 `location.directory`,所以「全部会话」视图一次请求就够。 | 功能 | 请求 | 说明 | | --- | --- | --- | | 会话列表 | `GET /api/session?limit=50&order=desc[&directory=][&search=][&archived=]` | `{data:[Session], cursor:{next,previous}}`,cursor 不透明 | | 运行中会话 | `GET /api/session/active` | `{data:{ses_x:{type:"running"}}}` | | 会话详情 | `GET /api/session/{id}` | `{data:Session}` | | 消息分页 | `GET /api/session/{id}/message?limit=50&order=desc&cursor=` | `{data:[Message], cursor:{next}}`,倒序取最新,往前翻历史 | | 发送消息 | `POST /api/session/{id}/prompt` | `{id?, text, files?, agents?, skills?}`,正文流式回来 | | 中断 | `POST /api/session/{id}/interrupt` | `{interrupted:true}` | | 切换模型 | `POST /api/session/{id}/model` | `{model:{providerID,id,variant?}}` | | 切换 Agent | `POST /api/session/{id}/agent` | `{agent:"build"}` | | 新建会话 | `POST /api/session` | `{title?, agent?, model?, location:{directory}}` | | 改名 / 归档 | `PATCH /api/session/{id}` | `{title?}` / `{archived:true|false}` | | 删除 | `DELETE /api/session/{id}` | 204 | | 模型列表 | `GET /api/model?location[directory]=` | 透传 opencode | | Agent 列表 | `GET /api/agent?location[directory]=` | 同上 | | 待批权限 | `GET /api/permission/request?location[directory]=` | 启动时补齐 | | 批复权限 | `POST /api/session/{id}/permission/{requestID}/reply` | `{decision:"once"|"always"|"reject", message?}` | | 事件流 | `GET /api/event`(SSE,可 `?types=…`) | 需要 Bearer | | OpenCode 就绪 | `GET /api/opencode/health?wait=15000` | 服务端没起 opencode 时用 | | 默认目录 | `GET /api/location` | `{directory, project}` | **Session(节选)** ```jsonc {"id":"ses_…","projectID":"…","agent":"build", "model":{"id":"…","providerID":"…","variant":"default"}, "cost":0,"tokens":{"input":0,"output":0,"reasoning":0,"cache":{"read":0,"write":0}}, "title":"…", "time":{"created":1794734543641,"updated":…,"busy":…,"idle":…,"viewed":…,"archived":…}, "location":{"directory":"/home/me/project"}, "metadata":{"openchamber":{"work":{"state":"open"}}}} ``` **Message(节选)** ```jsonc {"id":"msg_…","type":"user","text":"…","files":[…],"time":{"created":…}} {"id":"msg_…","type":"assistant","agent":"build","model":{…}, "content":[ {"type":"text","text":"…"}, {"type":"reasoning","text":"…","time":{…}}, {"type":"tool","id":"call_…","name":"shell","executed":false, "state":{"status":"completed","input":{…},"content":[{"type":"text","text":"…"}]}, "time":{"created":…,"completed":…}}], "time":{"created":…,"streamed":…,"completed":…}, "finish":"stop","cost":0,"tokens":{…}} // 其它类型:synthetic / shell / system / skill / compaction / agent-switched / model-switched / idle ``` ### 2.4 SSE 事件(MVP 子集) 信封: ```jsonc {"id":"evt_…","created":1794734734543,"type":"session.text.delta", "location":{"directory":"/home/me/project"}, "durable":{"aggregateID":"ses_…","seq":42,"version":1}, "data":{…}} ``` | 事件 | 用途 | | --- | --- | | `server.connected` | 连接建立 | | `session.created/renamed/archived/unarchived/deleted` | 列表增量 | | `session.execution.started/succeeded/failed/interrupted` | 忙/闲状态(启动时再配合 `/api/session/active` 做全量对齐) | | `session.step.started/streamed/ended/failed` | assistant 消息出现与结束(tokens/cost/finish) | | `session.text.started/delta/ended` | 正文流式 | | `session.reasoning.*` | 思考流式(可折叠) | | `session.tool.input.*/called/progress/success/failed` | 工具状态机 | | `session.shell.started/ended` | 会话内 shell | | `session.usage.*`、`session.retry.scheduled` | 成本与重试提示 | | `permission.asked/replied` | 手机端弹审批 | 连接策略: - `net/http` + `bufio.Scanner` 解析 `data:` 行;用 `?types=` 只订阅需要的类型(但 `server.connected` 总会发)。 - 断线指数退避重连(1s → 30s + jitter);**恢复后对当前会话重取一页消息做全量对齐**——服务端明确事件流是 volatile(慢消费者会被断开,断线期间事件丢失)。 - `durable.seq` 可用于检测缺口,MVP 用全量对齐更简单可靠。 - 切后台 Android 可能掐断连接:回前台重连 + 重同步,不做后台常驻。 --- ## 3. 客户端架构 ### 3.1 目录结构 ``` openchamber-android-native/ # 本目录,新 Go module ├── PLAN.md ├── asuka.json # app 名称/ID/图标/Android 配置 ├── main.go # app.Run(App) ├── cmd/ocprobe/ # M0 探针 CLI(连真实服务器,验收协议层) ├── internal/ocapi/ # 纯 Go 客户端,零 UI 依赖,可单测 │ ├── client.go # baseURL / token / transport(代理、TLS)/ 错误模型 │ ├── auth.go # /health、/auth/session │ ├── sessions.go # 列表/详情/新建/改名/归档/删除/active │ ├── turn.go # prompt / interrupt / model / agent │ ├── messages.go # 分页 │ ├── permissions.go # 列表与回复 │ ├── catalog.go # /api/model、/api/agent、/api/location │ ├── events.go # SSE 解码 + 重连 │ └── *_test.go # httptest + 真实服务集成 ├── internal/state/ # signals 与业务动作(把 ocapi 结果搬到 UI) ├── internal/storage/ # secure token、store.Signal 设置、安装 ID └── app/ # 界面 ├── app.go # Tabs/Stack 根 ├── connect.go # 地址 / 密码 / 代理 / 自签证书 ├── sessions.go # 会话列表 ├── chat.go # 消息 + composer ├── message.go # 消息渲染(user / assistant / tool / reasoning) ├── permissions.go # 权限审批 └── settings.go ``` 原则: - `internal/ocapi` 不 import `ui`/`signal` → CI 里能 `go test ./...`,也能用 CLI 跑真服务。 - UI 只读 state 的 signal,动作走 state 的方法;网络在 goroutine,回调 `ui.Post`。 - 每个打开的会话一个「会话运行时」:SSE 订阅 + 消息缓存 + context 取消,页面 `signal.OnCleanup` 里关闭。 ### 3.2 网络层 ```go type Client struct { base *url.URL token string // oc_client_… http *http.Client serverID string // /health 的 serverId,重连时校验 } func NewClient(base string, opts Options) (*Client, error) // opts: Proxy, InsecureTLS, Timeout ``` - **HTTP 代理**:`Transport.Proxy = http.ProxyURL(u)`(`http://host:port` / `https://`,走 CONNECT)。 - **SOCKS5**:`golang.org/x/net/proxy.SOCKS5("tcp", host, nil, proxy.Direct)` 得到 `DialContext`,赋给 `Transport.DialContext`(不做认证,符合需求)。 - **TLS**:默认系统校验;「信任自签证书」开关 → 记录 SHA-256 指纹 + `VerifyPeerCertificate` 固定,比 `InsecureSkipVerify` 更可感知。 - **超时**:普通请求 20s;SSE 不设 `Client.Timeout`,用 `context` 取消 + 读超时看门狗。 - **错误归一化**:`ErrUnauthorized`(401)、`ErrRateLimited`(429+retryAfter)、`ErrOffline`、`ErrNotOpenChamber`(`/health` 不带 `openchamberVersion`)。 - **目录作用域**:`x-opencode-directory: url.PathEscape(dir)`,列表再带 `?directory=`。 ### 3.3 UI 结构 ``` App ├── 未连接: ConnectScreen │ ├── 服务器地址(自动补协议、去尾斜杠) │ ├── 密码(Secure) │ ├── 高级:代理类型 [无 / HTTP / SOCKS5] + 地址 │ ├── 高级:信任自签证书 │ └── 连接 → /health → /auth/session → 存 token └── 已连接: Tabs ├── 会话 │ ├── 列表(按项目分组;标题、模型、更新时间、运行中) │ ├── 下拉刷新 / 触底分页 / 搜索 │ ├── 滑动:归档 / 删除 │ └── → ChatScreen │ ├── 消息列表(AnchorBottom、日期分组、顶部加载更早) │ ├── assistant:markdown.View(Streaming) + reasoning 折叠 + tool 折叠摘要 │ ├── user:气泡 + 附件占位 │ ├── 忙碌:停止按钮 + 状态/错误行 │ ├── composer:多行输入、模型/agent 菜单 │ └── 标题栏:重命名 / 归档 / 删除 / 切换模型 └── 设置(连接信息、重新登录、代理、关于) ``` 关键交互: - **贴底**:`AnchorBottom` + 发送后 `ui.ScrollToEnd`。 - **流式性能**:assistant 正文放在 `signal.NewFunc(string, nil)`;合并 30–60ms 内的事件再写 signal;`markdown.View{Streaming:true}` 只重排最后一块。 - **工具调用**:一行摘要(`shell · 命令` / `read · 文件`),点击展开,展开状态放在外部 `map[callID]bool`(行会被回收,状态不能放在行里)。 - **权限审批**:`permission.asked` 时 `ui.Alert` 显示 action/resource,三个按钮 once/always/reject;`permission.replied` 后关闭。 - **401**:任何请求 401 → 清 token → 连接页,地址/代理保留。 --- ## 4. MVP 范围与验收 | # | 功能 | 验收标准 | | --- | --- | --- | | 1 | 地址 + 密码连接 | 支持 `host:port` 自动补协议;不可达 / 非 OpenChamber / 密码错误 / 限流都有明确提示 | | 2 | 可选代理(HTTP/SOCKS5,无认证) | 开/关都能连;地址错误时提示;无需认证字段 | | 3 | 自签证书开关 | 默认严格校验;打开后可连,并显示指纹 | | 4 | token 持久化 | 杀进程重开保持登录;过期/撤销 → 401 → 重登提示 | | 5 | 会话列表 | 全部项目的会话(标题/项目/更新时间/运行中);下拉刷新;分页;搜索 | | 6 | 会话操作 | 新建、重命名、归档、删除;操作后列表即时更新 | | 7 | 聊天查看 | 历史(markdown、代码块、工具调用、思考折叠);上滑加载更早;贴底 | | 8 | 流式回复 | 文字逐步出现;思考/工具状态实时;结束显示耗时/token | | 9 | 发送 / 停止 | 空消息不可发;发送后清空;运行中可停止 | | 10 | 模型 / Agent 切换 | 当前模型可见;切换后对后续消息生效 | | 11 | 权限审批 | 待批请求可见,可 once/always/reject;结果同步 | | 12 | 断线恢复 | 断网提示;恢复后重连 SSE 并补齐当前会话 | | 13 | Android 真机/模拟器 | 可安装运行;明文 HTTP / 自签证书场景按设计工作 | **不在 MVP**:终端、文件/Git/PR、图片附件、语音、推送、Pairing v2 / Relay、多服务器切换。桌面/web 目标只用于调试,不算交付。 --- ## 5. 里程碑 | 阶段 | 内容 | 产出 | 估算 | | --- | --- | --- | --- | | **M0** 环境与协议探针 | 安装 asuka(`@main`)+ 建 Go module;`cmd/ocprobe`:health → 登录 → 列会话 → 拉消息 → SSE 打印 → 发 prompt;`asuka build -p web` 验证工具链 | ✅ 已完成(见 §0.1),真实服务器验证通过 | 0.5–1d | | **M1** ocapi | 客户端包 + 类型 + 代理/TLS + 错误模型;`httptest` 单测 + 真实服务集成测试 | ✅ 完成(含 catalog/permissions/证书单测) | 1–2d | | **M2** 连接与会话列表 | ConnectScreen、secure token、state 层、SessionsScreen(先 web/Linux 目标) | ✅ 完成(自动重连、401 重登、实时列表) | 1–2d | | **M3** 聊天 | ChatScreen、消息渲染、markdown 流式、分页、composer、interrupt、自动贴底 | ✅ 完成(含 SSE 流式与工具/思考折叠) | 2–3d | | **M4** 操作与权限 | 新建/改名/归档/删除、模型/agent、权限审批、401/429/断网处理 | 验收表全绿(桌面) | 1–2d | | **M5** Android | 装 SDK/NDK/JDK + 模拟器/真机;明文 HTTP 与自签证书策略落地;真机跑通 | 手机上完整走通 | 1–2d | | **M6** 打磨与发布 | 图标/splash、i18n(zh-Hans/en)、空态/骨架屏、release AAB、CI | 可分发的构建 | 1–2d | 合计约 **8–12 人日**。M5 的环境安装可与 M1–M3 并行(下载耗时长)。 --- ## 6. 本机环境搭建(无 Android SDK) 现状:Go 1.26.3(mise)✅、`/dev/kvm` ✅、网络 ✅、asuka CLI 可从 `@main` 安装 ✅;缺 JDK、Android SDK/NDK、模拟器。 ```bash # 1) JDK 17/21(Gradle 需要;asuka 会读 JAVA_HOME) sudo apt install openjdk-21-jdk-headless # 2) Android command-line tools(不需要 Android Studio) mkdir -p ~/Android/Sdk/cmdline-tools cd /tmp && curl -LO https://dl.google.com/android/repository/commandlinetools-linux-13114758_latest.zip unzip -q commandlinetools-linux-*.zip -d ~/Android/Sdk/cmdline-tools mv ~/Android/Sdk/cmdline-tools/cmdline-tools ~/Android/Sdk/cmdline-tools/latest export ANDROID_HOME=$HOME/Android/Sdk export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH # 3) 接受许可并安装(compileSdk 36 / build-tools 36 / 最新 NDK) yes | sdkmanager --licenses sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" \ "ndk;28.0.13004108" "emulator" "system-images;android-36;google_apis;x86_64" # 4) 模拟器 avdmanager create avd -n oc36 -k "system-images;android-36;google_apis;x86_64" -d pixel_7 emulator -avd oc36 & # 5) 构建与运行 go install github.com/egoist/asuka/cmd/asuka@main # 注意:不能用 @latest asuka dev --platform android --device emulator-5554 ``` - 模拟器访问宿主机用 `10.0.2.2`;或 `adb reverse tcp:3000 tcp:3000` 后用 `http://127.0.0.1:3000`。真机同一 Wi-Fi 用内网 IP。 - `asuka build --platform android` 产出 Play 用的 `.aab`;要侧载 APK 就对生成的 Gradle 工程跑 `./gradlew assembleDebug`,或用 `bundletool build-apks --mode=universal`。 - 首次 Gradle 构建会下载依赖,比较慢。 --- ## 7. 风险与对策 | 风险 | 影响 | 对策 | | --- | --- | --- | | asuka 0.1.x API 变动 | 升级破坏 | `go.mod` pin 伪版本;CI 固定 asuka 版本;升级单独 PR + 冒烟 | | v0.1.1 在 Linux 编译失败 | 装不上 CLI | 从 `@main` 安装并记录 commit(`0.1.2-0.20261114215826-2602a98fec66`) | | Android release 禁明文 HTTP | 连不上 `http://LAN:3000` | native 包 manifest 合并 `usesCleartextTraffic`(方案见 §0.1,M5 实测);或强制 HTTPS(Caddy / Tailscale) | | 自签证书 | TLS 失败 | 「信任该证书」+ 指纹固定;默认严格校验 | | SSE 断线/后台被杀 | 消息不同步 | 回前台重连 + 当前会话全量对齐;退避重连;UI 显示连接状态 | | 组件只跑一次 + 行回收 | 展开态错乱 | 行内状态放全局 `map[id]` signal;行只读 accessor | | 长会话 / 大工具输出 | 卡顿、内存 | 50 条/页分页;工具输出折叠 + 截断;只保留最近 N 条 | | Markdown 复杂度 | 渲染差异 | 官方 `sdk/markdown`(CommonMark + GFM + 数学);代码块自定义渲染 | | 权限回复枚举变化 | 审批失败 | M0 探针实测(协议 2.2.6:`once` / `always` / `reject`);失败降级为只读提示 | | SOCKS5 DNS 行为 | 解析失败 | SOCKS5 远程解析;用域名和 IP 两种目标测试 | | token 7 天过期 | 突然 401 | 统一 401 拦截 → 重登;设置页显示到期时间 | | 模拟器/真机不可用 | 无法验收 M6 | 先装 emulator + x86_64 镜像;真机 USB + `adb reverse` | --- ## 8. 测试 1. **ocapi 单测**:`httptest.Server` 模拟 `/health`、`/auth/session`、`/api/session`、SSE(分块写 `text/event-stream`),覆盖 401 / 429 / 断流 / 取消。 2. **真实服务集成**:本机跑 OpenChamber(带 `--ui-password`),用环境变量提供 URL/密码跑 `-tags=integration`;`cmd/ocprobe` 同时是手工冒烟工具。 3. **UI 冒烟**:`asuka dev -p web`(快)→ Linux 桌面(原生手感)→ Android 模拟器/真机。仓库里已有 `uitest` 无头 UI 测试(`internal/appui/root_test.go`),CI 可直接跑。 4. **手工场景**:冷启动连接、错密码+限流、杀进程重开、飞行模式恢复、长会话上滑、流式发送/停止、权限批准/拒绝、归档/删除、切模型、自签证书、代理开关。 --- ## 9. 已定与待定 已定(2026-11-15): - 代码放在当前目录 `~/Sources/openchamber-android-native`,独立 Go module。 - 明文 HTTP:**release 也要支持**内网 `http://` ⇒ M5 需要一个 native 包放行 cleartext(做法见 §0.1)。 - M0 已完成;M1–M3 完成;M4 完成权限审批与会话操作,剩模型/Agent 切换与新建会话。 - Android:debug 与 release(AAB 及用其生成的 release APK)都已在模拟器上连通本机服务器;release 的明文 HTTP 已验证。 待定: 1. **会话范围**:MVP 直接展示「所有项目」的全局会话列表(当前实现),还是先选项目/目录再进会话? 2. **发布方式**:自签名 sideload / 内部分发,还是准备上 Google Play(影响 AAB、签名、隐私声明)? 3. **界面语言**:先英文再中文,还是首发中英双语? --- ## 附:关键源码位置(本机) - OpenChamber 认证:`packages/web/server/lib/ui-auth/ui-auth.js`(`/auth/session`、限流、信任设备) - 设备 token:`packages/web/server/lib/client-auth/remote-clients.js`、`pairing.js` - `/api/*` 反代与 `/health`:`packages/web/server/lib/opencode/{proxy,core-routes,routes}.js` - 真实客户端调用:`packages/ui/src/lib/opencode/client.ts`(`x-opencode-directory`、prompt / interrupt / permission 参数) - 现有移动端连接流程:`packages/ui/src/apps/mobileConnections.ts` - opencode v2 协议:`~/.bun/install/global/node_modules/@opencode/{protocol,schema}/dist` - asuka 源码:`~/go/pkg/mod/github.com/egoist/asuka@v0.1.2-0.20261114215826-2602a98fec66` (`examples/chat/main.go` 是聊天列表 + composer 的现成范例;`sdk/markdown` 是流式 Markdown)