For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/mobile/api.md (or send Accept: text/markdown).
移动端 API
应用如何与服务器通信 —— 会话、可达性与负载。
初学者演练
先决条件：阅读下面的两个初学者指南并完成移动本地设置。将Expo值放入apps/mobile/.env.local中；将 EXPO_PUBLIC_API_URL 设置为您的设备可以访问的后端主机。仅限移动设备的结帐没有网络后端，因此请单独启动或连接一个。成功的 Expo 导出证明 JavaScript 捆绑包，而不是设备或购买接受。
简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 URL 的消息。
1、在apps/mobile/.env.local中，将EXPO_PUBLIC_API_URL设置为手机可访问的运行后端地址；请勿从物理设备使用 localhost。
2. 按照移动本地设置启动 Expo、登录并打开工作区、设置和聊天屏幕。
3. 期望来自同一工作区的经过身份验证的数据。如果请求超时，请检查手机和计算机网络，并在仅限移动设备的结帐中单独启动后端。
对于自定义代码，请从提供的 prompts/README.md 开始，然后复制最接近的提示：对于应用程序屏幕为 prompts/new-app-screen.md，对于公共页面为 prompts/new-landing-page.md。对于服务器、数据库或提供商工作，请为您的编码代理提供本指南的任务，并要求其读取 AGENTS.md、.ai/PROJECT_CONTEXT.md 和匹配的 .ai/ 镜像；检查此处指定的确切源文件；列出文件并在编辑前进行检查；保留工作区所有权和仅限服务器的机密；并向您展示差异。告诉它您想要的行为、输入和输出字段、允许的角色、预期的成功和错误以及测试帐户、提供程序或设备。使用样本值；永远不要粘贴真正的秘密。
了解本机范围
Expo 包括本机身份验证/会话和深度链接以及工作区、设置、聊天和 RevenueCat 购买界面。共享业务行为和授权保留在 Web 后端/包中； apps/mobile/src 下的本机客户端调用这些 API 时无需嵌入提供者凭据。
使用会话认证的BFF
/api/mobile 路由涵盖权利、RevenueCat 购买可用性和服务器同步、组织、成员、邀请、审核、API 密钥、webhooks、域、时间表和功能请求。他们保留工作区所有权和角色检查。它们与 sk_ 不记名密钥 /api/v1 公共合约不同。
使用您的设备可访问的 EXPO_PUBLIC_API_URL 和配置的源/方案；公共 Expo 变量从不包含提供者凭据。
在本机目标上进行验证
检查您打算支持的设备/版本上的加载/错误/空状态、重新连接、过期会话、禁止的管理操作和深层链接返回。 Expo 导出证明捆绑，而不是本地交付或购买接受。
安装与配置
应用调用 /api/mobile 和版本化的 /api/v1 端面下的 API,使用成员会话而非 Web 应用的 Cookie 假设。EXPO_PUBLIC_API_URL 是客户端唯一知道的源;它在设计上是公开的,不携带密钥。
会话令牌来自 Better Auth Expo 流程,保存在原生安全存储中 —— 绝不在明文 AsyncStorage 或打包配置中。
GET /api/mobile/entitlement # access state for the member
GET /api/mobile/organization # active workspace context
GET /api/mobile/usage # current-month AI spend, meter caps, and credit balance
GET /api/mobile/appearance # synced appearance bundle (GET/PUT)
POST /api/v1/ai-tasks # authorized work, same as web
Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=实现流程
在第一个认证请求之前解析存储的会话,当服务器报告过期时刷新,被吊销时干净地登出。将 API 不可达和无效会话视为不同状态 —— 一个重试,另一个返回登录。
保持负载与 Web 契约相同:无论哪个客户端调用,服务器都应用相同的工作区、entitlement 和验证规则。
验证与排障
测试飞行模式失败、会话中途令牌过期、已吊销会话,以及带着已存储有效令牌的冷启动。以失败关闭(拒绝)结束的请求是正确的;以失败开放结束的是发布前要修复的 bug。