Codex Bridge Android

这是 codex-bridge 的 Android 客户端项目，用来让手机通过预先配置的 Bridge 地址和访问密钥 appId 访问当前电脑上的 Codex。

当前交付 APK：

D:\Program Files\dev-project\github\codex-bridge-android\codex-bridge.apk
D:\Program Files\dev-project\github\codex-bridge-android\codex-bridge-test.apk

功能

• 保存 Bridge 地址 / 域名和访问密钥 appId。
• 首次打开默认预填 https://bridge.kevinsu.xyz，通常只需要补 appId。
• appId 和 Web 手机端一致：它只是远程访问密钥，不做租户隔离；公网鉴权场景必填，本机无鉴权 Bridge 可留空。
• 获取手机局域网 IPv4，并扫描同网段 4555 端口发现 Bridge。
• 检查 /api/health，确认 Bridge 与电脑端 Codex 状态。
• 保存设置前会校验地址和 appId，避免出现“看起来保存了但其实还没接入”的状态。
• Cloudflare Tunnel 断开时会显示短提示，不再把 1033/530 的整段 JSON 错误塞进设置弹层。
• 主界面按 Android 状态栏安全区下移顶栏，并收紧底部输入栏空状态高度，避免和电量图标重叠或底部留大块空白。
• 点“开启通知”会立即发一条本机测试通知并触发声音/震动，方便确认系统通知、提醒通道和后台监听都已可用。
• 使用和 Web 手机端一致的主交互：顶部栏、项目抽屉、项目内会话列表、聊天主屏、底部 + 操作面板。
• 顶部栏和抽屉头部图标改为原生绘制的线性按钮，不再依赖系统字体符号，视觉质感更接近 Web 手机端 SVG 图标。
• 欢迎页第一屏进一步对齐 Web 手机端：渐变星标徽章、居中空态和 300dp 建议按钮宽度节奏保持一致。
• App 内提示 toast 改为 Web 手机端同款底部深色胶囊，位置、停留时间和最大宽度都保持一致，不再依赖系统 Toast 外观。
• 回复中发送按钮会像 Web 手机端一样淡化为禁用态；通知未开启时，侧栏通知入口保持可点击的“开启通知”，用于触发系统权限申请。
• 侧边栏通知入口改成 Web 手机端同款“铃铛图标 + 文案”组合，并补上 10dp 顶部间距，状态切换时图标和文字同步变色。
• 项目抽屉开合动效对齐 Web 手机端：侧边栏 220ms 滑入/滑出，遮罩同步淡入/淡出。
• 消息气泡正文换行策略对齐 Web 手机端，长 URL、Windows 路径或连续 token 会在气泡内断行，不把消息区撑宽。
• 消息气泡圆角也对齐 Web 手机端：用户气泡右下角收小，assistant 气泡左下角收小，聊天方向更明确。
• 侧边栏项目/会话列表按 Web 手机端的结构展示：标题、最近时间、预览、段数胶囊、项目箭头和未读红点分层显示。
• 侧边栏项目/会话卡片密度进一步贴近 Web 手机端：标题 14sp、元信息 12sp、最小高度 66dp，历史会话多时能多露出几项。
• 侧边栏未读红点改为原生 8dp 圆点，不再依赖 ● 字体符号，红点尺寸和位置更稳定。
• 侧边栏顶部新建按钮固定为 Web 手机端同款“＋ 新会话”，项目内新建只在虚线入口显示“＋ 在此项目新建对话”，避免同层级重复文案。
• 没有历史会话的项目卡片整张按 Web 手机端 .muted 规则降到 0.58 透明度，而不是只把标题变灰。
• 侧边栏项目卡片右侧箭头也改为原生线性绘制，避免 › 字体符号在不同手机字体下偏离 Web 质感。
• 侧边栏抽屉头部进一步收敛到 Web 手机端尺寸：标题、返回/关闭按钮、新会话按钮、通知和设置入口都采用更紧凑的 36/44dp 节奏。
• 进入项目后的会话列表顶部提供 Web 同款“在此项目新建对话”入口。
• 项目内“在此项目新建对话”入口改为 Web 同款透明底虚线边框，当前会话 active 卡片也使用强调色边框。
• 在项目内会话列表按系统返回键时，会先执行 Web 抽屉内的“返回项目”语义；再按一次才关闭抽屉。
• 回复完成后按 Web 手机端同样的规则刷新最近会话：优先使用 projectId，缺失时通过会话 cwd 反推项目并更新排序。
• 电脑端 Codex 回复完成的原生通知事件也会同步更新侧边栏红点、项目最近时间和当前项目会话排序。
• 项目列表排序规则和 Web 手机端一致：最近活跃优先，时间相同再按段数和名称排序。
• 会话列表时间和排序也对齐 Web 手机端：优先用 updatedAt，缺失时兜底 startedAt。
• 项目内历史会话卡片按 Web 手机端分层显示标题、时间和预览，不再把预览挤在时间同一行。
• 历史会话预览为空或与标题重复时会像 Web 手机端一样隐藏，减少重复占位。
• 欢迎页建议按钮在同步完成后与 Web 手机端一致，只展示 Bridge 下发的 prompts；同步前保留本地兜底按钮。
• 支持 codexbridge://chat?baseUrl=...&appId=...&sessionId=... 深链，参数名兼容 Web 手机端的 bridge/accessKey/threadId。
• 接入设置弹层支持小屏滚动，键盘弹起时仍能操作检查连接、创建访问密钥和保存。
• 接入设置弹层视觉进一步对齐 Web 手机端 dialog：400dp 上限、22dp 圆角、轻量标题、paper 输入框和右对齐操作按钮，同时保留 App 的 IP/扫描/appId 创建能力。
• 输入框会像 Web 手机端一样随内容增长到最高 160dp，超过后在输入框内部滚动；聚焦输入时自动收起 + 操作面板。
• 主输入行改为 Web 手机端同款整体圆角胶囊：+、输入区和发送按钮共用一层浅色容器，输入框自身透明无边框。
• 底部 composer 和主输入胶囊补上原生 elevation，对齐 Web 手机端 box-shadow 的轻浮层感。
• 主输入行的 + 与发送按钮也改为原生绘制图标：+ 保持 Web 同款旋转关闭态，发送按钮使用纸飞机实心形状，不再依赖字体箭头。
• + 操作面板打开时，左侧 + 按钮会像 Web 手机端一样进入强调色关闭态；聚焦输入、发送、附件添加完成或点“回图片”都会同步恢复。
• + 操作面板的图片、文件、回图片动作块高度对齐 Web 手机端 72px 节奏，触控面积更接近网页版本。
• + 操作面板动作块改成 Web 同款“浅绿色图标块 + 标签”结构，回图片选中态也改为浅绿色 active 卡片而不是整块深色按钮。
• + 操作面板的图片、文件、回图片图标也改为原生线性绘制，不再依赖 ▧/▤/✦ 这类字体符号，选中态继续由卡片样式表达。
• + 操作面板动作块按压时会按 Web 手机端一样轻缩到 0.98，松手恢复，触摸反馈更接近网页版本。
• 通过 /api/mobile/bootstrap 查看项目，按最近活跃进入项目，再打开历史会话。
• 通过 /api/mobile/chat 流式发送消息，支持边生成边显示 assistant 回复。
• assistant 等待回复时会像 Web 手机端一样显示闪烁光标；收到内容、完成或失败后自动停止闪烁。
• 点击发送时会像 Web 手机端一样自动收起底部 + 面板，让回复区域立刻回到聊天主视图。
• 流式图片事件会像 Web 手机端一样按图片地址去重，避免同一张图被重复渲染。
• 图片消息显示也对齐 Web 手机端：按气泡可用宽度完整等比展开，不再把长图压进固定高度框里。
• 如果网络在流式回复中途断开，已显示的 assistant 文本会像 Web 手机端一样保留，不会被错误提示覆盖。
• 底部 + 面板支持添加图片、添加文件、切换“回图片”模式；附件最多 8 个，和 Web 手机端一致。
• 底部 + 面板使用原生线性图标动作卡，图片、文件、回图片入口更接近 Web 手机端的图标化操作。
• 点击“回图片”后会像 Web 手机端一样自动收起 + 面板，并显示同款“本轮将请求 Codex 回图片”提示。
• 待发送附件胶囊也和 Web 手机端一致显示“图片 · 文件名 / 文件 · 文件名”，发送前就能看清附件类型。
• 待发送附件胶囊的位置也和 Web 手机端一致，显示在输入区提示下方；多个附件会按 Web 的 flex-wrap 手感自动换行，并把高度限制在 86dp 内滚动。
• 用户消息气泡里的附件会像 Web 手机端一样以浅绿色胶囊展示，并区分“图片 · 文件名”和“文件 · 文件名”。
• 消息正文支持系统文本选择，长按气泡可复制整段文本。
• 渲染 assistant 回复里的公网图片 URL、data:image 图片，以及当前 session 工作目录内的本机图片路径；图片按原比例适配显示，长按可复制链接。
• 后台前台服务监听 appId 可用的 /api/mobile/events，电脑 Codex 回复完成后发 Android 本地通知。
• 侧边栏通知按钮和 Web 手机端文案保持一致：未开启显示“开启通知”，监听成功后显示“通知已开”。
• App 内对未查看会话打红点；通知点击后直达对应会话。
• 侧边栏的通知入口会显示“通知已开”，用于确认原生监听服务已经启动。
• 手机端自己发起的对话在模型回复完成后会短响一声并震动约 2 秒，和原生通知提醒保持一致。
• 和 Web 手机端一样，只有 done.status 为空或 completed 时才刷新最近活动并触发完成提醒；interrupted、error、timeout 不误报完成。
• App 从后台回到前台时会静默刷新项目/提示词目录，并保持当前会话不跳走；短时间反复切换会自动节流。

电脑端 Bridge 启动

常规无线/公网访问时，手机不能访问电脑的 127.0.0.1。如果要让 APK 访问，需要让 codex-bridge 监听局域网地址：

cd "D:\Program Files\dev-project\github\codex-bridge"
$env:CODEX_BRIDGE_HOST="0.0.0.0"
$env:CODEX_BRIDGE_PORT="4555"
$env:CODEX_BRIDGE_REQUIRE_AUTH="1"
npm start

建议在电脑端先打开 http://127.0.0.1:4555 创建 appId，再把这个 appId 填进手机 App。外部网络不在同一局域网时，仍然需要 VPN、端口映射、Tailscale/ZeroTier、Cloudflare Tunnel 或 frp 这类通道。

如果手机扫不到，优先检查 Windows 防火墙是否允许 4555 端口入站。

Type-C 真机调试可以走 adb reverse，这时 App 里填 http://127.0.0.1:4555 是有效的：

$adb = Join-Path $env:LOCALAPPDATA 'Android\Sdk\platform-tools\adb.exe'
& $adb reverse tcp:4555 tcp:4555

构建

cd "D:\Program Files\dev-project\github\codex-bridge-android"
.\scripts\build-apk.ps1

APK 输出位置：

codex-bridge.apk
codex-bridge-test.apk
app\build\outputs\apk\debug\app-debug.apk

测试

.\gradlew.bat testDebugUnitTest

边界

当前密钥是 codex-bridge 里的 appId。开启 CODEX_BRIDGE_REQUIRE_AUTH=1 后，Bridge 会把它作为外部应用访问白名单来校验；它不是租户隔离边界。公网场景仍建议配合 HTTPS 或 VPN 使用。

Android 后台监听依赖前台服务，系统会显示一个常驻“Codex Bridge”监听通知。如果系统省电策略过强，需要在手机系统里允许该 App 后台运行。