Match the first-party mobile client's connection screen: - the first screen lists saved servers, the one last used leading with its connect button or connected state, the others below, and adding is one tap - servers can be added, edited (name, address, proxy, self-signed) and deleted; deleting the live or last one returns to the list - a password sheet prompts only when the server asks for one, keeps the error and the typed password for a retry - while connected, the instances sheet switches servers - proxy and self-signed options stay per server (the native app's own) - the single-server record and its token migrate automatically - permission cards read a plain signal, fixing a flaky update - bump version to 0.1.2 (build 3)
30 KiB
OpenChamber 手机客户端(asuka/Go)调研与开发计划
调研对象:asuka(Go + 原生控件)v0.1.1 / main,OpenChamber 2.7.0,opencode v2.2.7 目标:Android 优先的手机客户端,MVP = 输入地址 + 密码连接(可选 http/socks5 代理),浏览并操作现有会话
0. 结论
可行,且 asuka 的覆盖度比预期好。 但真正的风险不在 UI,而在三处:
- Android 构建链:本机没有 JDK / Android SDK / NDK。asuka 要求每个平台自己的工具链,第一次搭环境要花半天,且 asuka v0.1.1 在 Linux 上
go install会编译失败(syscall.SO_REUSEPORT),必须从main安装。 - release 版默认禁止明文 HTTP:asuka 只在 debug manifest 里开
usesCleartextTraffic。连http://192.168.x.x:3000这类自建服务需要额外处理(加一个只声明 manifest 的 native 包,或统一走 HTTPS)。 - 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 | 聊天页顶栏打开选择 Sheet(可搜索),切换后同步会话列表 |
| 新建会话 | 会话页「新建」:标题 + 工作目录(服务端默认目录与已加载会话的目录),创建后直接进入聊天 |
| 下一步 | 打磨:图标/splash、中英 i18n、空态与错误页;可选 fork asuka 支持更低 minSdk |
明文 HTTP 的落地方式(用户已确认 release 也要支持):native 包 netcfg 已加入(main.go 里空白导入),Gradle 会把它的 manifest 合并进 release。已实测 release 的合并 manifest 含 usesCleartextTraffic="true",并用 release APK 连上了 http://10.0.2.2:3000:
asuka native new ./netcfg # 生成 Go/Kotlin/Web/desktop 各平台骨架
然后在 netcfg/android/src/main/AndroidManifest.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/AndroidSDKANDROID_HOME=$HOME/SDK/AndroidSDKJAVA_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):
-
探活 + 版本 + 防串服
GET /health(免鉴权) →{status:"ok", openchamberVersion, runtime, compatibility, serverId?}记下serverId,之后重连时校验,避免路由器把同一个 LAN 地址分给了另一台机器。 -
用已有 token 探测
GET /auth/session+Authorization: Bearer <token>→200 {authenticated:true, scope:"client"}/401 {authenticated:false, locked:true}没有配置密码的服务器返回{authenticated:true, disabled:true},此时不需要 token。 -
密码登录并一次拿到设备 token
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 的请求做来源校验。
- token 默认 7 天(服务端
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 |
| 删除 | 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" |
| 事件流 | GET /api/event(SSE,可 ?types=…) |
需要 Bearer |
| OpenCode 就绪 | GET /api/opencode/health?wait=15000 |
服务端没起 opencode 时用 |
| 默认目录 | GET /api/location |
{directory, project} |
Session(节选)
{"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(节选)
{"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 子集)
信封:
{"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不 importui/signal→ CI 里能go test ./...,也能用 CLI 跑真服务。- UI 只读 state 的 signal,动作走 state 的方法;网络在 goroutine,回调
ui.Post。 - 每个打开的会话一个「会话运行时」:SSE 订阅 + 消息缓存 + context 取消,页面
signal.OnCleanup里关闭。
3.2 网络层
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、模拟器。
# 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. 测试
- ocapi 单测:
httptest.Server模拟/health、/auth/session、/api/session、SSE(分块写text/event-stream),覆盖 401 / 429 / 断流 / 取消。 - 真实服务集成:本机跑 OpenChamber(带
--ui-password),用环境变量提供 URL/密码跑-tags=integration;cmd/ocprobe同时是手工冒烟工具。 - UI 冒烟:
asuka dev -p web(快)→ Linux 桌面(原生手感)→ Android 模拟器/真机。仓库里已有uitest无头 UI 测试(internal/appui/root_test.go),CI 可直接跑。 - 手工场景:冷启动连接、错密码+限流、杀进程重开、飞行模式恢复、长会话上滑、流式发送/停止、权限批准/拒绝、归档/删除、切模型、自签证书、代理开关。
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 已验证。
待定:
- 会话范围:MVP 直接展示「所有项目」的全局会话列表(当前实现),还是先选项目/目录再进会话?
- 发布方式:自签名 sideload / 内部分发,还是准备上 Google Play(影响 AAB、签名、隐私声明)?
- 界面语言:先英文再中文,还是首发中英双语?
附:关键源码位置(本机)
- 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)