Files
openchamber-android-native/PLAN.md
T
blumia e240a33e31 feat: one server button, and only primary agents to pick
The session screen now has a single server icon that opens the instance
list; picking an instance drops the live connection and connects to it,
and disconnecting moved into that list. A custom SVG rack stands in for
the missing server symbol on Android.

The agent sheet lists primary agents only: a session cannot run a
subagent (General, Explore) as its own agent.

Bump version to 0.1.5 (build 6).
2026-11-16 13:21:20 +08:00

31 KiB
Raw Blame History

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 选择 只列 mode=primary 的 Agent,子智能体(General/Explore)不再出现
模型/Agent 聊天页顶栏打开选择 Sheet(可搜索),切换后同步会话列表
新建会话 会话页「新建」:标题 + 工作目录(服务端默认目录与已加载会话的目录),创建后直接进入聊天
下一步 打磨:图标/splash、中英 i18n、空态与错误页;可选 fork asuka 支持更低 minSdk

与官方移动端连接界面的差异(有意保留)

  • 官方用「代理请求头(如 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:

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/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

    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
删除 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 不 import ui/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. 测试

  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)