tbox-agent-app-alipay

tbox-agent-app 的支付宝小程序壳。用一个全屏 web-view 加载你部署好的首页（/ 直出），并把 H5 侧通过桥发来的 JSAPI 请求代理到小程序原生能力（选图、录音、定位、换码登录、分享、支付……）。

定位：给基于 tbox-agent-app 开发的应用作参考项目或直接二开使用。H5（浏览器）与小程序壳跑的是同一份前端代码——浏览器走 Web API，壳里走本桥的原生能力，业务无感知。

工作原理

支付宝小程序壳 (本项目)                         tbox-agent-app 前端 (首页(/))
pages/ai-agent/index  ──web-view src──→        浏览器内运行的 React 应用
        │                                              │
        │  ① H5 my.postMessage({action,apiName,        │  client/src/bridge/*
        │     params,requestId})                       │  callJsapi('chooseImage', …)
        │◀─────────────────────────────────────────────┤
        │  ② onWebViewMessage → 执行 my.xxx / my.call   │
        │     → webViewContext.postMessage(回执)        │
        ├─────────────────────────────────────────────▶│  ③ my.onMessage 按 requestId
        │                                              │     匹配 resolve/reject

桥协议与 tbox-agent-app/client/src/bridge/protocol.ts 完全一致（bridge: 'open-mini-webview-bridge'，action my / my.call），两端是配套的，勿单边改协议常量。

快速开始

1. 配置 H5 地址：编辑 pages/ai-agent/index.ts 顶部的 AI_AGENT_WEB_VIEW_URL，改成你 tbox-agent-app 部署后的首页地址（根 /）。
   • tbox-agent-app 真正会读的 URL 参数只有：container=alipay-miniapp（建议固定带，让 H5 可靠识别壳环境）、user_id（可选，壳子已知用户时透传；否则 H5 走 getAuthCode 换码登录）。其余参数按需自加（默认不消费 channel/agent_id/code/env）。
   • 页面启动参数（scheme 唤起时透传的 query）会自动追加到该 URL。
2. 用支付宝小程序 IDE 打开本目录，填入你的小程序 appId。
3. npm i（仅装 @mini-types/alipay 类型，可选）。
4. 真机预览 / 模拟器运行：进入 pages/ai-agent/index，即可看到 H5 页面，桥能力自动生效。

支持的桥能力

H5 侧 callJsapi(apiName, params, mode) → 壳子统一代理：

| apiName | 模式 | 壳子处理 | |---|---|---| | chooseImage / chooseVideo | invoke | 选完把原生文件读成 base64 dataURL，回 { files: [{ data, name, size }] }（H5 直接走上传链路） | | getLocation / chooseLocation | invoke（强制白名单） | 直接 my.xxx | | getAuthCode | invoke | 直接 my.getAuthCode，回 { authCode }（交给 server 换 userId） | | startRecord / stopRecord | invoke | 走 RecorderManager（mp3/16k，60s 自动停并缓存），stop 回 { audioBase64, format, duration } | | 其它 my.xxx | invoke | 通用代理 | | 底层 API | call | 走 my.call(apiName, params, cb) |

新增能力：H5 直接 callJsapi('someApi', params) 即可；壳子默认通用代理无需改动。需要特殊后处理（如把路径转 base64）时，在 pages/ai-agent/index.ts 的 callJsapiForWebView 里加分支。

注意事项

• JSAPI 权限：选图/录音/定位/getAuthCode 等能力需在支付宝小程序后台为该小程序开通对应权限/类目，否则真机调用会失败。
• 域名白名单：web-view 加载的 H5 域名需加入小程序的业务域名白名单。
• 端口/协议：H5 必须 https；本地联调可用内网穿透或带证书的 dev server。
• 录音预热：页面 onReady 已 prewarmRecorder() 降低首次录音延迟，勿删。

目录结构

tbox-agent-app-alipay/
  app.json / app.ts / app.less        小程序入口与全局
  mini.project.json / tsconfig.json   编译配置
  pages/ai-agent/
    index.axml / index.less / index.json   全屏 web-view 页面
    index.ts                          桥主流程：收消息 → 执行 JSAPI → 回执（⚙️ 改 URL 在这）
    bridge.ts                         消息解析/归一化/回执构建（协议工具，勿改协议常量）
    jsapi-execution.ts                invoke / call 模式决策
    recorder-handler.ts               RecorderManager 录音封装