ds-harness-remote-fast/apps/android/AGENTS.md

5.6 KiB
Raw Blame History

Android Guide for Agents

本文件定义 apps/android 的移动端专属常青规范;仓库全局边界、协议、测试政策与文档约束见根目录 AGENTS.md。

  • Expo SDK 57:当前使用 expo ~57.0.x、react 19.2.x、react-native 0.86.x,涉及 Expo API 先核对 https://docs.expo.dev/versions/v57.0.0/。
  • 运行形态:
    • 因依赖 react-native-webrtc 与本地原生模块,不可使用 Expo Go,须用 Development Build 或原生 APK。
    • Release APK 内嵌 JS bundle,验收前必先核对包装形态。

构建、检查与离线渲染器

  • 修改共享包后先在根目录执行 pnpm --filter './packages/**' -r build,再跑 @dsh-remote/android 的 check、test、build 或 android。
  • build:renderers 生成忽略目录 src/generated/ 下的 4 类离线 WebView 产物(terminal、pdf、mermaid、intelligent-ui)。
  • check 与 test 均会自动串联 build:renderers 与 verify:workspace;严格只读勘察请在隔离副本运行或直接调用 vitest run。
  • CI Release APK 通过 DSH_REQUIRE_INTELLIGENT_UI=true 校验固定提交的 Intelligent UI 渲染器。
  • 离线渲染安全边界:
    • 数学公式由 mathjax-full 本地生成 SVG(math-svg.ts)。
    • Mermaid(mermaid@12.2.0)经禁网严格 CSP 隐藏 WebView 渲染后,须按白名单正则重建元素与属性再交给 react-native-svg(防非法属性闪退 Android 原生)。
    • 含 foreignObject 图表仅走 javaScriptEnabled={false} 全屏查看。
    • PDF 限单页画布只读预览(禁脚本、外链与明文缓存);预览上限:图片 8 MiB、PDF 16 MiB、Office 源 50 MiB。

原生模块、后台连接与外部导航

  • 原生代码位置(改动后必须重建 APK):
  • 前台服务与链路恢复:
    • RemoteForegroundService 与 PARTIAL_WAKE_LOCK 按连接代次串行隔离,仅在连接及后台最多 3 次自动重连期间持有。
    • 已建链每 25s 及回前台执行加密 harness.transport.describe(5s 超时);旧代次回调禁停新连接,断线禁重放 Prompt、审批或终端输入。
    • 不得把通知存在等同于息屏持续联网(受系统 Doze 与厂商冻结限制)。
  • 外部导航与认证入口:
    • 外部会话打开经独立 externalOpenRevision 解锁抽屉、切回 Agent 模式并关闭 Host 切换层;未知 Host/Session 须显式报错横幅,不回退连接其他设备。
    • 扫码登录限点击触发、校验同源 /api/v1/auth/ 并于 complete 后立即停止轮询。
    • 客户端不接入 DSH-Go 配对链接(OAuth 回调限 dshremote://oauth)。

会话架构、离线草稿、动效与多语言

  • 数据面与附件:
    • 仅接官方 Typert、codex.app.*、agent.acp.* 与 plugin.route.call(已移除早期 ApiProxy)。
    • Harness 图片发送完整 ImageAttachmentRef;Markdown 工作区图片仅复用授权 workspaceFiles 内存预览(不读手机本地路径,外部 HTTP 图不自动联网)。
    • 活动坞(待办/目标/job/list|follow)按当前 sessionId 只读订阅并在切换时取消。
  • 聊天模块与离线草稿门禁:
    • chat-screen.tsx 负责页面编排;输入区与菜单分别位于 composer.tsx 与 action-menu.tsx。
    • 附件、消息投影、滚动、提及、快捷提示词与返回键分别由 chat/use-chat-{attachments,transcript,scroll,mentions,prompts,back-handler}.ts 管理。
    • 输入可编辑性由 composer-gate.ts 的 composerEditable 控制(仅权限切换与上传中锁定,与 connected 解耦)。
    • 断线发送由 submitIntent 判 'offline' 保留草稿不清空;store 侧 sendMessage 在插 local: 乐观行前对非 connected 返回 'rejected'(禁走禁止回填草稿的 'kept')。
    • browse-memory 按 Server/账号/Host identity 隔离保存加密草稿、收藏、阅读位置与最近记录。
    • 不持久化对话正文、审批句柄或待发队列;Bot 模式草稿仅存组件内存。
  • DS-Bot 与 vendor/ds-bot:
    • BotRemoteClient 绑定连接代次,打开会话须经同 Host Bot state 与官方 Session catalog 核对(禁建虚拟持久化会话);/btw 失败不退回普通 Prompt。
    • 卡片纯原生声明式渲染(禁执行模型 HTML/JS);vendor/ds-bot/ 保留上游原样与 Apache-2.0。
    • 取消统一检查 signal.aborted(兼容 RN AbortSignal)。
  • 动效、响应式与 9 语言:
    • 弹层与切换使用 motion.ts 令牌(含 reduced-motion 降级)与 SheetModal(遮罩淡入 + 不透明面板位移 + 退场保末次快照)。
    • responsive.ts 适配自动旋转与宽屏双栏(≥760 dp 条件启用内联 HostSessionsDrawer)。
    • 新增或修改界面文案须同步更新 src/locales/ 全部 9 套语言(与 app.json 一致),渲染时按 key 读取。