5.6 KiB
5.6 KiB
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):
with-remote-foreground-service.js与remote-foreground-service/:提供前台服务RemoteForegroundService、下载、ProcessText、原生逐帧键盘高度同步RemoteKeyboardInsetsModule(DshRemoteKeyboardInsets)及通知多语言资源。modules/remote-transport/:提供RemoteWebSocketBinary(单帧 ≤65,535 字节),供workspace.upload.lan.v1二进制直传避免 JS Base64 转码。
- 前台服务与链路恢复:
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只读订阅并在切换时取消。
- 仅接官方 Typert、
- 聊天模块与离线草稿门禁:
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(兼容 RNAbortSignal)。
- 动效、响应式与 9 语言:
- 弹层与切换使用
motion.ts令牌(含 reduced-motion 降级)与SheetModal(遮罩淡入 + 不透明面板位移 + 退场保末次快照)。 responsive.ts适配自动旋转与宽屏双栏(≥760 dp 条件启用内联HostSessionsDrawer)。- 新增或修改界面文案须同步更新
src/locales/全部 9 套语言(与app.json一致),渲染时按 key 读取。
- 弹层与切换使用