23J1633/a2s_app

A2S 手机端

中文

A2S 生态（同系列开源仓库）

A2S 按组件拆分为以下同系列仓库，所有者均为 23J1633。/ A2S is split into the following sibling repositories, all owned by 23J1633.

| 仓库 / Repository | 作用 / Role | GitHub |
|---|---|---|
| A2Switch | Windows 桌面控制中心 / Windows desktop control center | 23J1633/A2Switch |
| cc2server | Claude Code 桥接器 / Claude Code bridge | 23J1633/cc2server |
| codex2server | Codex 桥接器 / Codex bridge | 23J1633/codex2server |
| dsh2server | DeepSeek Harness 插件 / DeepSeek Harness plugin | 23J1633/dsh2server |
| server-api | 中转服务与 Web 控制台 / relay server and Web console | 23J1633/server-api |
| a2s_app | Flutter Android 客户端 / Flutter Android client | 23J1633/a2s_app |

a2s_app 是 A2S 的 Flutter Android 控制端，Android application ID 为 io.a2s.mobile。它沿用服务器网页端的工作流：先选择设备，再单独选择设备上的智能体，进入聊天；左侧抽屉集中管理历史会话、统计、设置和扫码配对。界面使用 Material 3，支持浅色、深色、系统主题、动态取色、减少动画和真实品牌图标。

已实现能力

- 服务器地址和管理员 key 手动登录；管理员 key 只用于登录和查看设备摘要。
- 设备 key 二次解锁；未解锁设备不能读取会话、工作区、文件、任务、终端或下发命令。
- 一次性二维码配对：支持相机扫描和相册图片识别，二维码刷新、过期、重复兑换和撤销均有明确提示。
- 设备与智能体分离选择，内置 Claude、OpenAI Codex、DeepSeek Harness 的真实 SVG 品牌图标。
- 聊天、流式事件、停止/中断、历史搜索、重命名、分叉、归档/恢复、附件、Markdown、工具调用、审批和结构化提问。
- 工作区目录和文本预览、运行轨迹、任务/目标、模型/权限/审批设置、插件配置、统计、日志和高级方法调试。
- 真实远程终端：xterm 显示、命令发送、Ctrl/Esc/Tab、方向键、尺寸同步、保活、回放和断线重连。
- 服务器管理页：管理员 key 只在内存中使用，可查看/重命名/撤销移动设备，登记/吊销设备 key，生成或作废配对二维码并读取服务日志。
- SSE 事件序号去重、断线回拉、请求幂等、手机心跳、草稿按服务器/设备/智能体/会话隔离保存。

连接地址

在 App 中填写服务器的完整插件端点，例如：

http://127.0.0.1:50443/a2s-api

App 会在该地址后使用 /mobile/v1 手机协议；/dsh-api 别名同样支持。Pixel 9 Pro 模拟器本地联调使用：

adb reverse tcp:50443 tcp:50443

然后在 App 中填写 http://127.0.0.1:50443/a2s-api。生产环境应使用 HTTPS，系统证书校验保持开启。

手动连接与扫码配对

手动连接需要管理员 key；登录后只能看到设备摘要。点击设备并输入 A2Switch 本地设备 key 才能解锁该设备。

服务端网页端的“设置 → 移动设备连接”进入后会按已勾选设备自动生成二维码，也可以手动刷新；改变勾选或端点会轮换并撤销旧码。二维码包含端点、随机票据和一次性授权信息，有效期为 5 分钟，服务器同时只保留一张有效码。App 的“设置 → 扫描二维码”支持相机和相册识别，成功后会保存独立手机凭据并解锁二维码勾选的设备。

远程终端

终端默认关闭。需要在对应 A2Switch/桥接器配置中显式打开 allowRemoteTerminal 后，App 的“工具 → 终端”才会显示连接能力。Windows 桥接器默认启动 PowerShell，Linux/macOS 使用 $SHELL 或 /bin/bash。每个桥接器最多 4 个终端，每个终端保存 1 MiB 回放，120 秒无保活会回收。

本地开发

cd D:\Project\A2S\a2s_app
flutter pub get
flutter analyze
flutter test
flutter build apk --debug
flutter build apk --release --split-per-abi

安装调试 APK：

adb install -r D:\Project\A2S\artifacts\a2s_app-debug.apk

本次交付的 APK 为本地测试签名，只用于联调和验收。SHA-256（artifacts/a2s_app-debug.apk）：

5DA9050F27FFD6829ADBFB06913405092066C0CBFBD9674CFFF464281C0A54D6

Release 签名

源码不会回退到调试签名。没有 android/key.properties 时可以生成未签名的 Release 分包，用于 CI 验证，但不能直接上架。正式发布前：

1. 复制 android/key.properties.example 为 android/key.properties；
2. 创建并妥善保管 upload keystore；
3. 填写 storeFile、storePassword、keyAlias、keyPassword；
4. 执行 flutter build apk --release --split-per-abi；
5. 使用 Android SDK 的 apksigner verify --print-certs  复核签名。

key.properties、.jks、.keystore 和 android/local.properties 均已加入 .gitignore。本机已验证三个 ABI 的未签名 Release 分包可完整构建；最终商店签名必须由发布者自己的密钥完成。

Windows 上若 Pub 缓存在 C: 而项目在 D:，Kotlin 增量缓存会因跨盘符路径失效。项目已在 android/gradle.properties 中关闭 Kotlin 增量编译，以换取可复现的 Debug/Release 构建。

目录说明

- lib/main.dart：Material 3 页面、抽屉、设备/智能体选择、扫码、聊天、工作区、轨迹、终端和设置。
- lib/state/app_state.dart：Riverpod 状态、手机凭据、SSE 重连、事件回拉、草稿和交互应答。
- lib/core/api_client.dart：HTTP 手机协议适配器和请求幂等 ID。
- assets/a2s-logo.png、assets/brands/*.svg：A2S、Claude、OpenAI、DeepSeek 品牌图标。

服务端手机协议和管理页位于 server-api/lib/mobile.js、server-api/public/js/settings.js。服务端接口端点、一次性配对和授权模型见仓库根目录的移动端验收报告。

许可证

代码采用 MIT License，见 LICENSE。Claude、OpenAI、DeepSeek 等名称和品牌图标属于各自权利人，仅用于标识兼容的智能体。

English

a2s_app 是 A2S 的 Flutter Android 控制器。其 Android 应用 ID 为 io.a2s.mobile。工作流程与 Web 控制台一致：选择设备，在该设备上选择智能体，然后进入聊天。导航抽屉提供历史记录、统计信息、设置和二维码配对。Material 3 UI 支持浅色/深色/系统主题、动态颜色、减少动态效果以及真实的智能体标识。

功能

- 手动服务器/管理员密钥登录，随后进行单独的设备密钥解锁步骤。
- 从相机或图库进行一次性二维码配对，并具有清晰的刷新、过期、重放和撤销状态。
- 为 Claude、Codex 和 DeepSeek Harness 分别选择设备和智能体。
- 聊天、流式传输、停止/中断、搜索、重命名、分叉、归档/恢复、附件、Markdown、工具、审批和结构化问题。
- 工作区和文本预览、轨迹、任务/目标、模型、权限、插件设置、统计信息、日志和高级方法调试。
- 具有 xterm 渲染、控制键、调整大小、保活、重放和重连的真实远程终端。
- 对移动客户端、设备密钥、配对票据和日志进行服务器管理。
- SSE 序列去重、积压恢复、幂等请求、心跳，以及按服务器/设备/智能体/会话隔离的草稿。

连接与配对

输入完整的插件端点，例如 https://example.com/a2s-api。应用会推导出 /mobile/v1；也接受旧版 /dsh-api 别名。生产部署必须使用 HTTPS 并进行正常的证书验证。对于连接到本地服务的 Android 模拟器，请运行 adb reverse tcp:50443 tcp:50443 并使用 http://127.0.0.1:50443/a2s-api。

手动连接仅使用管理员密钥进行身份验证并列出设备摘要。在提供其 A2Switch 设备密钥之前，设备将保持锁定状态。Web 控制台则可以为选定的设备签发一个五分钟、一次性的二维码票据；兑换该票据会创建一个单独的移动凭据。

远程终端
终端访问默认处于禁用状态，只有在为桥接显式启用 allowRemoteTerminal 后才会出现。Windows 使用 PowerShell；Linux/macOS 使用 $SHELL 或 /bin/bash。每个桥接最多允许四个终端，保留 1 MiB 的回放，并在 120 秒无 keepalive 后回收终端。

开发

flutter pub get
flutter analyze
flutter test
flutter build apk --debug
flutter build apk --release --split-per-abi

发布签名绝不会回退到调试签名。复制 android/key.properties.example，提供发布者的上传密钥库值，构建拆分的 APK，并使用 apksigner 验证它们。密钥库和本地签名配置会被 Git 忽略。

项目布局与许可证

lib/main.dart 包含 Material UI；lib/state/app_state.dart 负责 Riverpod 状态、凭据、SSE 恢复、草稿和响应；lib/core/api_client.dart 实现移动端 HTTP 协议。品牌资源位于 assets/ 下。代码使用 MIT 许可证；第三方名称和商标仍归其各自所有者所有。