Add a Go client for OpenChamber built with Asuka's native widgets. - internal/ocapi: health, password-to-device-token auth, session and message paging, prompt/interrupt/model/agent, permissions, SSE events, HTTP/SOCKS5 proxies and certificate pinning - internal/storage: connection settings plus a device token in the platform keystore, with a per-install id for server-side dedupe - internal/appui: connect, session list and chat screens with streaming Markdown, reasoning/tool folding, permission cards and session actions - netcfg: native module that enables cleartext HTTP in release builds - cmd/ocprobe: terminal probe for the API - headless UI tests (uitest) and the research/plan document
478 lines
30 KiB
Markdown
478 lines
30 KiB
Markdown
# 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 实时增删 |
|
||
| 下一步 | M4 余项:模型/Agent 切换、新建会话;M5:Android 真机 + release 明文 HTTP |
|
||
|
||
**明文 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)
|