Files
openchamber-android-native/PLAN.md
T
blumia 2fb4a8ea79 feat: context usage ring and tool image previews
- the composer shows a context ring and percentage from the last
  token-bearing assistant message, toned at 75% and 90%; tapping opens a
  sheet with the model, used tokens, limits, output reserve and turn cost
- images a tool call names (read attachments as data URLs, input paths,
  and image paths in output text) get a link under the tool row; tapping
  previews it from the data URL or /api/fs/raw, allowing paths outside
  the workspace
- directory-scoped requests now send x-opencode-directory-encoding: uri,
  which scoped routes such as /api/fs/raw need to decode the header
- ocprobe gains a raw file command for checking previews

Bump version to 0.2.2 (build 16).
2026-11-18 02:15:11 +08:00

513 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`) |
| 上下文占用 | 输入区右侧环形进度 + 百分比(绿/橙/红阈值 75%/90%,与官方一致);点击打开详情 Sheet:模型、已用 tokens、上下文上限、输出预留、占用百分比、本轮费用;阈值按 `上限 - min(输出, 32K)` 计算 |
| 工具图片预览 | 工具调用涉及图片时(read 的 `state.attachments` data URL、输入 `filePath/path`、输出文本中的绝对图片路径),在工具行下显示图片链接;点击后从 data URL 解码或经 `/api/fs/raw`(带 `allowOutsideWorkspace=true`,工作区外的 /tmp 截图也能看)取回,全屏 Sheet 预览并缓存 |
| 目录请求头 | `x-opencode-directory` 附带 `x-opencode-directory-encoding: uri`,修复 scoped 请求(如 `/api/fs/raw`)被当成未解码路径的问题 |
| 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 xmlns:android="http://schemas.android.com/apk/res/android">
<application android:usesCleartextTraffic="true" />
</manifest>
```
库 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 <token>`
→ `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: <percent-encoded 绝对路径>`;列表接口也可用 `?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]=<abs>` | 透传 opencode |
| Agent 列表 | `GET /api/agent?location[directory]=<abs>` | 同上 |
| 待批权限 | `GET /api/permission/request?location[directory]=<abs>` | 启动时补齐 |
| 批复权限 | `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)