安卓原生客户端 bqv/dsh-android

DSH — 原生 Android 客户端

DeepSeek Harness（DSH）主机的原生 Jetpack Compose Android 客户端。它重新实现了官方 DSH Web UI，不用 WebView，也不往主机上装任何东西：它发出的每个调用，Web 客户端本来就会发，走的是主机自己的公开 HTTP + WebSocket API。

接口是通信协议，不是 DOM。不往主机里注入任何东西，也不需要主机侧插件。

一段对话。智能体的过程折叠在一行摘要下面（1 tool call · 1 message），提示词的上下文作为独立行跟着它走，会话自己的统计信息放在输入框下面。Chat 旁边的 Trajectory 标签页展示同一轮对话在模型眼里的样子——输入、工具调用、结果。

抽屉按主机自己的 Workspace 注册表给会话分组，而不是靠猜路径，底部把 Settings 和 About 配成一对：Settings 只放真正能设置的东西，About 放关于应用的事实——主机、登录方式、版本、平台，以及当前打开会话的路由。（截图里会话列表打了码；那是别人的会话，不属于本仓库。）

还欠一张截图：Shell 标签页，展示主机 shell 座位里跑着 htop 的终端，深色模式。

环境要求

- Android 8.0（API 26）或更新。 minSdk 是 26；compileSdk 和 targetSdk 是 34，用 build-tools 35.0.0 构建。
- JDK 17 和 Gradle 8.7，解压在 .toolchain/ 下，目录名为 jdk-17.0.20.1+1 和 gradle-8.7。build.sh 假定这两个目录已经存在；它不会去下载。
- Android SDK，带 platform 34 和 build-tools 35.0.0。local.properties 把 sdk.dir 指向它（开发机上为 sdk.dir=/opt/android-sdk），build.sh 另外还会导出 ANDROID_HOME/ANDROID_SDK_ROOT。
- 没有 Gradle wrapper。每次调用 Gradle 都从 build.sh 进，它把 GRADLE_USER_HOME、ANDROID_USER_HOME 和 XDG_DATA_HOME 重定向到 .toolchain/，所以构建不往 $HOME 写任何东西，在 workspace-write 沙箱里也能跑。
- 主机通常在私有局域网里走明文 HTTP 访问；应用的网络安全配置允许明文传输，所以直接输入 http:// URL 也能用。

构建与安装

bash build.sh :app:assembleDebug
-> app/build/outputs/apk/debug/app-debug.apk

bash build.sh :app:testDebugUnitTest
342 tests, all JVM: the VT parser, the protocol gates, the key tables,
and the scroll rules — which run a real Compose layout under Robolectric

这套测试（app/src/test/java/…）之所以存在，是因为 VT 核心和终端的顺序门控都是纯 Kotlin，不含任何 Android 代码：构建机没法在真机上跑的那一半功能，就靠字节级测试钉死。

每次推送到 main、每次提 pull request，CI 都会跑这套测试并构建同一个 APK，所以完全不用本地工具链也能拿到 APK：

- Actions 标签页 → Build 工作流 → 你那次提交的运行 → Artifacts → dsh-android-debug-<sha>，或者
- 该次运行的摘要，里面会写明文件名和大小。

这个 APK 用标准 debug 密钥签名，所以能直接覆盖安装已有的 debug 构建（uk.xa0.dsh.debug），不用先卸载——包名和本地构建产出的完全一样。.github/workflows/build.yml 只负责复现 .toolchain/ 目录结构，然后调用 build.sh，所以本地构建和 CI 构建不会跑偏。

安装到单台设备：

tools/install.sh <serial> # installs the debug APK just built
tools/install.sh <serial> <apk> # or an explicit APK

- build.sh 自己会拿构建锁（.build.lock），tools/install.sh 拿 .install.lock；两把锁都放在 checkout 里，因为 /tmp 上的 flock 在这里不算互斥锁。第二个调用者会等待，而不是交错执行。
- Debug 构建带 .debug 应用 ID 后缀（uk.xa0.dsh.debug）。
- adblease <serial> <command...> 把一整串设备操作——安装、启动、点击、截屏——放在同一份按设备分配的租约下执行，这样两次验证运行不会中途互相打断。$SERIAL 和 $ADB 会导出给命令。它是通用的设备基础设施，所以和其余 adb 管道（~/bin/adb-wireless）一起放在这个 checkout 之外：

adblease 127.0.0.1:5555 sh -c 'adb -s $SERIAL shell input tap 48 128'

指向主机并登录

把 Server 设成主机 HTTP 入口的地址，例如 http://192.168.1.110/。只填 host:port 也接受，会自动补上 http://。有两种登录方式：

1. 主机的登录表单。 输入账号和密码；应用会以 application/x-www-form-urlencoded 向 POST /auth/login 提交，带上 provider=password。主机返回它的会话 cookie，harness 前面的 nginx 还会注入 dsh-auth- cookie。两者都保存在 CookieJar 里，进程退出也不丢，之后每次调用都会带上。密码存在 EncryptedSharedPreferences（AES-256-GCM，密钥在 Android Keystore 里），所以会话过期后能静默重新登录从设置界面退回打开的对话记录。
2. 粘贴 cookie。 设置界面的 Advanced 字段接受原始 name=value cookie（dsh-auth-… 或 dsh_auth_session=…），并绕过表单。这条路径适用于直接通过其载体端口访问的主机，这种主机没有 /auth/login 入口；账号留空。

主机无法访问时，不会让你退出登录。超时、连接被拒或 socket 掉线都视为暂时性故障：首次连接停留在设置界面并显示主机的消息，之后按 3/6/9/12 秒重试；在线界面上掉线时，对话记录保持可见并显示横幅，同时 mux 重新连接。只有 HTTP 401/403（或重定向到登录页）才算凭据被拒，也只有这种情况才会再次提供登录。

模拟器指向同一台机器上的主机： 模拟器自己的 127.0.0.1 是模拟器，不是主机，所以要通过模拟器的 NAT 别名访问主机：http://10.0.2.2:8081/。（载体端口也会通过 adb reverse tcp:8081 tcp:8081 反向映射进来，adb 用户服务会对每个注册的模拟器应用这一映射——但在这台机器的模拟器上，该中继注册后并不传输字节，所以不要依赖模拟器内部的 127.0.0.1:8081。细节和测量结果在 docs/HANDOFF.md。）无论哪种方式，都粘贴载体 cookie——回环载体没有登录表单。

线路协议

一元调用是 POST /api/<namespace>/<method>，携带 harness 信封：

{"type":"client-request","rpcId":"…","method":"session/list","payload":{"args":{…}}}
→ {"type":"server-response","rpcId":"…","result":{"ok":true,"value":{…}}}

参数键是主机服务方法的参数名，这就是为什么 session/list 接受 _request，而 session/prompt 接受 request。

所有流式数据都走同一个 WebSocket，/api/remote.mux，承载逻辑流：

→ {"type":"open","streamId":"s1","endpoint":"session/follow","payload":{"args":{…}}}
← {"type":"item","streamId":"s1","value":{…}}
← {"type":"end","streamId":"s1"}

用到四个端点：

- session/follow —— 对话记录 snapshot、持久 event 帧，以及实时 assistant-stream 的 start/chunk/end 帧（token 增量）。
- session/control —— 一个 baseline，加上每个会话的 queue / projection / jobs 增量：待处理队列、后台任务和折叠投影。
- workspace/follow —— 工作区注册表，抽屉按它分组，目录选择器从它采用。
- $events —— 转发的主机事件，包括 waterfalls，例如 approval/request 和 user-questions/request。waterfall 必须应答，否则智能体会卡住；用 POST /api/$events/result 携带 {clientId, eventId, outcome} 来结算。

RemoteMux 在重连后会重放其打开的注册，所以掉线的 socket 会恢复流式传输，而不是悄悄冻结 UI。

应用目前能做什么

会话与抽屉

- 从宿主注册表进行工作区分组，外加宿主的 Ungrouped 分桶；按 Workspace/List 分组，按 Manual/Last updated 排序，支持分区折叠和「Show more」分页、Archived 过滤器，以及子代理会话嵌套在父会话下，并带每行子代理展开。三个抽屉偏好都会在重启后保留。
- 在名册上进行本地标题/路径过滤，外加宿主内容搜索（session/search），防抖 250 ms，并按宿主的顺序合并。
- 状态圆点：进行中的方块追逐、绿色完成、琥珀色警告。你在别处时完成的会话行会保留客户端「done」标记，直到你打开它们。
- 会话行操作：Rename、Fork session（session/fork）、Copy session id、Archive（workspace/archiveSession）；Settings 可取消归档。
- 从主屏幕新建会话（cwd 和 workspace 根据注册表解析），以及通过目录选择器 Add workspace（directoryPicker/list、directoryPicker/createDirectory、workspace/create）。
- 抽屉页脚中的 Refresh（带最小旋转时间，这样快速宿主不会看起来像没反应）、Settings 和 New Session。

转录

- 用户气泡、助手 markdown、可折叠的「Think」推理，带实时「Thinking…」行、计划/待办卡片、插件和错误通知、压缩标记，以及子代理谱系。
- 每工具卡片：bash/pwsh 终端、write/edit diff、带行范围的 read、智能体读取的图片内联绘制、grep/glob 命中列表、web_search / web_fetch，以及 ask_user_question 的问答记录。嵌套子调用渲染为树；其他任何内容回退到带 IN/OUT 卡片的通用展开。
- 实时 token 流式传输并节流，这样每秒数百个增量也能保持流畅；每轮进程折叠并带摘要；「Deep diving…」状态带已用时钟；每条消息的时钟和复制操作；返回底部按钮。
- Chat / Trajectory / Shell 视图标签页：第二个是模型的输入/输出账本，第三个是会话的 PTY（见下文 The Shell tab）。
- 反向分页：滚动到最早加载的行会通过 session/page 拉取更早的一页，这样长会话不会受限于跟随窗口。
- 每轮完成后有一行交付物，打开文本预览。
- 页眉中为你面前的会话提供后台任务席位：运行中的任务及其状态，由 session/control 的 jobs 增量提供，并为你在另一个会话时结束的任务提供「done」标记。计数是打开会话的，绝不是碰巧最后报告的那个会话的。

The Shell tab

- 视图条是 Chat / Trajectory / Shell。第三个是真正的 PTY，基于宿主的原生 terminal Remote 命名空间（environment、shells、list、create、follow、write、resize、rename、close），在转录使用的同一个 /api/remote.mux 上流式传输。它被标记为 Shell 而不是终端之所以有两个席位，是因为它承载的是该命名空间的客户端视图，而不是宿主注册的视图——Web 客户端自己的终端面板也是用同一份材料拼出来的（docs/research/chrome-ui.md §5.3）。
- 宿主 shell · 完全访问是默认席位：每个工作区一个专用会话，在工作区根目录创建，在其中有任何终端之前就赋予 danger-full-access，然后归档，这样它永远不会出现在抽屉里。顺序本身就是这个特性。terminal/create 从会话的策略中获取 shell 的隔离配置，而宿主在该会话中有终端打开时拒绝模式变更——「Close browser terminals before changing the Session sandbox mode」——所以先打开的终端会是一个被隔离的 shell，却挂在一个标着「完全访问」的席位下。不在任何工作区中的会话会在会话自己的 cwd 打开宿主 shell，而不是去猜一个工作区根目录。
- 本会话 · 工作区写入 / 只读是会话自己的终端，受该会话运行的任何策略隔离。之所以有两个席位，是因为隔离是会话的策略，没有按终端覆盖的机制：在 workspace-write 下，宿主用 bwrap 包裹 shell（--ro-bind / /、--unshare-pid、--tmpfs /tmp，只有工作区绑定为可写），所以对它来说文件系统是只读的，htop 也只能看到自己的 PID 命名空间。宿主 shell 就是从中逃逸的出口，按工作区提供，而不必移动用户正在使用的会话的模式。
- 每个席位标签都带有其中生效的策略（「宿主 shell · 完全访问」「本会话 · 工作区写入」），这就取代了一次性的「此终端已沙箱化」提示：你面前的 shell 由它能触及的范围来命名，而当会话的访问模式变化时，标签会重新标注。
- 网格是一个带块状光标的 Canvas——100×40 的屏幕就是 4,000 个单元格，而 htop 每秒会重绘其中大部分好几次——还有一行按键，用于软键盘无法产生的键：Esc、Tab、^C、^D、一个 Ctrl 锁存键、方向键、PgUp/PgDn 和 Home/End。保留多个终端的会话每个终端得到一个标签；一次屏幕上只显示一个网格。
- VT 核心（app/src/main/java/uk/xa0/dsh/term/）是手写的，且不依赖 Android：跨块边界的增量 UTF-8、光标寻址、EL/ED、插入/删除行和字符、DECSTBM 滚动区域、带保存/恢复的 ?1049 备用屏幕、?25/?7/?6/?1 和 ANSI 插入模式、支持 16/256/真彩色的 SGR、ESC(0 ACS 画线表、写回 PTY 的 DSR/DA 应答，以及有界回滚。
- 已在模拟器上验证——这个限定条件正是重点：网格跟随面板（stty size 与面板的 56×16 一致，为 16×56），287 列的行会换行，执行 seq 1 60 后最后十六行可见，提示符在底部，htop 在宿主 shell 中不受隔离地渲染（165 个任务，框字符，没有幽灵光标），exit 会报告 shell 已停止，终端选择器能区分两个终端。网络断开后重新连接尚未验证：模拟器的 svc wifi/data 不会触及这个应用使用的路径（eth0/10.0.2.15），所以断开再恢复还没有实际测试过。

输入区

- 发送，并在回合运行期间停止。运行中长按发送，可选择排队或引导；默认行为在设置里配置。
- 模型 chip 与选择器按服务商分组，包含某条路由接受的推理强度选项；智能体预设 chip 与选择器（agentPresets/list）；访问模式 chip 与选择器（permissionPresets/catalog，通过宿主的 /permission 命令应用）；Plan chip，用于退出 plan 模式。
- 上下文计量条，带 token 明细对话框，以及会话统计胶囊（回合/步骤及吞吐量，token 用量及缓存命中），每个都能打开详情面板。
- 卡片上方的停靠区：审批（Allow once / Reject）、提问（选项、多选、自定义文本、plan 审查）、待办、目标栏（暂停/恢复/编辑/清除），以及队列停靠区（编辑、移除、引导，带本地「Sending…」回显，直到宿主接收该行）。
- 附件：+ 按钮打开添加/命令菜单，系统文件选择器把文件暂存为上传回执（fileUploads/upload），或以 {type:"image"} 内联发送图片。图片可以不带说明文字直接发送。
- / 打开宿主的命令清单（commands/list → commands/execute）；@ 打开引用选择器（fileReferences/list、sessionReferenceResolver/candidates）。两者都按光标位置精确匹配，并把提及内容插入到 token 处，而不是草稿末尾。

文件

- 标题栏的文件夹座位打开会话的 Files 面板：transcript 触及过的文件，带编号文本预览。优先使用 transcript 已携带的内容；其余内容用 workspaceFiles/read 读取，范围限定在打开的会话内。
- 交付物 chip 会在面板中打开它所指的文件。

设置

- 只读移植了 web 设置弹窗的五个分区——General、Models、Plugins、Agent presets、Archived sessions——外加 Connection 和 Session 分区，用于展示这个客户端自身的信息。
- 可实时操作的只有客户端本地项：主题（system/dark/light）、忙碌时 Enter 的行为、新会话默认预设，以及 Archived session 的取消归档。任何需要写入宿主设置的项目都只显示为值，因为远程浏览器会落在 memory 设置作用域里，写入会被丢弃。
- 退出登录会清空 cookie jar 和已存储的凭据。

后台行为

- dataSync 前台服务让事件 socket 保持打开，不需要 Activity，所以审批或提问仍能送达装在口袋里的手机。它常驻通知在自有的「Connection status」渠道上，重要性为 LOW。
- 另一个通知渠道承载审批、提问、会话进入空闲/完成、会话错误和被阻塞的目标。每条通知都深链到对应会话。
- Android 13+ 上会请求 POST_NOTIFICATIONS，并提供电池优化豁免，否则 OEM 的电池管理器会回收进程，socket 也随之断掉。

账户余额

token 面板的费用行会打开 DeepSeek 账户余额：GET /user/balance，用你在该界面粘贴的 API key 读取。这是本应用唯一不发给你的主机的请求——DeepSeek 没有充值或用量 API，所以余额就是它能告诉你的关于账户的全部信息，充值会在浏览器中打开 platform.deepseek.com/top_up。key 存放在应用的加密偏好设置里，只发送到 api.deepseek.com，不发给任何其他地方。

分享进来

本应用会出现在 Android 分享面板中，支持任意文件类型：把图片或文档分享给 DSH，会把它附加到当前打开会话的输入框，和点 + 按钮完全一样，所以不必先保存再手动附加。分享可以冷启动应用——文件会等待应用连接完成、并有了可暂存它们的会话。只接受 content:// URI；分享的一段文本不算附件，会被忽略。

有意为之的差异与缺口

docs/PARITY.md 是逐项对照的清单；简要版本如下：

- 通知会渲染成可见的行，而网页端把它们藏在折叠的回合过程中——触屏 UI 没有 hidden="until-found" 那种展开方式把它们找回来。
- 单选问题旁边输入的备注会和选项一起发送（{selected, custom}）；网页端在你触碰其中一个时会清空另一个。
- 除客户端本地偏好设置外，设置是只读的（见上文）。
- 终端中未实现：回滚缓冲的渲染*——尾部内容会保留但不绘制——鼠标上报、终端搜索、同屏显示多个终端、sixel/kitty 图形、OSC 8 超链接、括号粘贴和 IME 组合区域。
- 其他地方未实现：Files 之外的右侧面板标签栏、拖拽重排和抽屉底部的渐隐，以及 Markdown 图片/引用/mermaid/数学公式。
- 任务的「完成」标记存在内存中：重启应用会清掉它，应用关闭期间结束的任务不会重新播报，因为会话的首次观察从不标记它——这条规则防止一个会话的任务在另一个会话上点亮圆点。
- 模型 chip 显示的是下一回合将运行什么，取自会话的 modelSelection.next。主机已接受但还没有回合运行过的变更（next 与 lastUsed 不同）会标记为待定；仍在外面的选择宿主会显示 applying…；目录不再列出的路由，会用宿主自己的 provider/model 命名，并标记为不可用。session/selectModel 从不追溯生效，所以标签会刻意显示 next，而不是上次实际运行的内容——显示 lastUsed 的标签会把上一个模型当成下一个来宣传。

- 在新会话界面选中的模型会被记录，并应用到该界面创建的会话；在那之前还没有会话 id 可供选择。
- session/selectModel 既是全局的，也是按会话的。它会同步设置会话的 next，同时异步设置宿主的全局默认值（session/modelCatalog.default）——在 0.2.0-rc.2 上实测为 0.4–2 秒。没有自己选择的会话，运行的就是这个默认值。这个延迟是个陷阱：调用后立刻重新读取目录，看到的仍是旧默认值，所以基于默认值构建的标签可能宣传一个会话并不会运行的模型。只要会话有自己的 next，标签就读它；新会话界面在进入时会重新读取目录，因为界面打开期间，其他会话或客户端都可能改动那个默认值。
- 有个宿主侧限制，应用无法修复：瀑布流会分发给每个已注册的 $events 客户端，且要等每个客户端都应答后才结束。所以只有当本应用是唯一的事件客户端时，Skip 或审批才具有决定性（开着的浏览器标签页会让它一直挂起）。

仓库结构

app/src/main/java/uk/xa0/dsh/
data/ 加密配置存储：宿主、凭据、主题、抽屉偏好 net/ DshClient（cookies + unary RPC）、RemoteMux（流复用器）、TerminalClient（终端命名空间）、PersistentCookieJar term/ VT 核心与终端自身的规则：模拟器、按键编码、席位、流闸门——不含 Android，所以 JVM 测试套件可以驱动它 model/ 日志 → 可渲染行：转录归约器、轨迹、文件、搜索、统计、工具树 ui/ Compose 界面与组件：聊天、抽屉、设置、安装引导、轨迹、终端、主题、markdown app/src/test/java/uk/xa0/dsh/term/ VT 解析器、协议闸门与按键表的 JVM 测试 docs/ HANDOFF.md（工作状态）、PARITY.md（对齐台账）、research/（逆向工程规格） tools/ install.sh（APK 安装）、dsh-api.mjs（经回环的一个网关 RPC）、gh-secrets.py（Actions secrets）；adb/模拟器服务与设备租约是通用宿主基础设施，不在本检出目录内 build.sh Gradle 入口点；固定工具链、缓存与构建锁 docs/images/ 上面的截图 .github/ 构建与发布工作流：每次推送跑 JVM 测试套件并产出一个可安装的 APK，每个版本标签发布一个 release app/build.gradle.kts, settings.gradle.kts, gradle.properties, local.properties Gradle 与 SDK 配置

文档

- docs/HANDOFF.md — 仓库结构、构建与设备循环、各种陷阱
- docs/PARITY.md — 与原生 Web UI 的 parity 路线图，包含每一处有意为之的差异及其背后的理由。
- docs/SCROLL-DIAG.md — 潜伏的滚动诊断：记录了什么，以及如何从设备上读回这些记录。
- docs/JOBS.md — job Remote 命名空间在运行中的宿主实际提供的形态（job/list、job/follow、job/kill），以及确立这一形态的探测。随包发布的 typert 描述符与该宿主不一致，而 roster 已不再位于 session/control，jobs 席位就是这样变空的。
- docs/research/ — 逆向工程参考：设计系统、wire 协议、transcript/UI 节点模型、设置与面板、composer 菜单、通知管道，以及移动端远程环境。