Omi Uber Call App 深度解析基于公开 Uber Deep Link 的零凭证叫车集成方案【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/FriendOmi Uber Call App 是 Omi 智能穿戴生态中的一款 Chat Tools 插件服务其核心能力是把帮我叫辆 Uber 去机场这类自然语言请求实时转换为可直接打开的 Uber 深度链接Deep Link从而在不申请 Uber 合作伙伴凭证、不调用受限的 Ride Request API 的前提下完成叫车衔接。读完本文你将掌握该服务的完整架构清单发布、工具端点、链接构建引擎、本地运行与 Omi App Store 接入方式以及其围绕用户确认、绝不静默下单设计的安全模型。一、设计背景为什么用公开 Deep Link 而非 Ride Request APIUber 官方提供的 Ride Request API 属于受限能力通常要求开发者具备合作伙伴资质并持有 API Key接入门槛高、审核链路长。而 Uber 面向普通用户的移动端https://m.uber.com/ul/与uber://深度链接流程是公开的任意 App 都可以拼装带目的地的链接把用户引导进 Uber 客户端内完成后续操作。Omi Uber Call App 选择了后者这一决策带来两个直接收益零凭证接入整个服务不需要保存 Uber OAuth token、API Key、支付凭据或任何客户数据见 README.md。确认权始终留在用户手中调用方只能预填行程最终的接送点、车型product、价格与支付确认全部在 Uber App 内由用户亲自完成杜绝静默下单风险。从仓库目录结构看该服务位于 plugins/uber_call是 plugins/README.md 中明确标注的独立部署于 monorepo 部署工作流之外的 standalone 服务仅依赖三行requirements.txt自包含程度高。二、整体架构与核心组件该服务是一个极简的 FastAPI 应用代码量集中在两个文件中文件职责plugins/uber_call/main.pyFastAPI 入口健康检查、Chat Tools 清单、call_uber工具端点plugins/uber_call/uber_links.py深度链接构建引擎位置建模、坐标校验、URL 编码与链接拼装plugins/uber_call/requirements.txt依赖声明fastapi、httpx、uvicorn[standard]服务对外暴露三个 HTTP 端点GET /health—— 健康检查返回{status: ok}main.pyGET /.well-known/omi-tools.json—— 供 Omi 识别的 Chat Tools 工具清单POST /api/call_uber—— 实际的叫车工具端点。数据流如下Omi 端在用户说出Call Uber to ...后根据清单中声明的call_uber工具描述向/api/call_uber发起 POST服务用uber_links.py中的build_locationbuild_uber_deep_links生成web_link移动网页版与app_linkuber://协议版两条链接连同自然语言回复一并返回给 Omi最终呈现给用户。三、Chat Tools 清单/.well-known/omi-tools.json详解Omi 的插件生态通过.well-known/omi-tools.json暴露工具清单使 Omi 能够发现并调用第三方能力。该服务在 main.py 中静态返回如下结构{ tools: [ { name: call_uber, description: Prepare an Uber ride link for the users requested destination. Use this when the user asks to call, book, or open Uber. The user must confirm the ride inside Uber., endpoint: /api/call_uber, method: POST, parameters: { type: object, properties: { destination: { type: string, description: Required destination name or address, for example SFO airport. }, dropoff_address: { type: string, description: Optional exact dropoff formatted address. }, dropoff_latitude: { type: number, description: Optional dropoff latitude. }, dropoff_longitude: { type: number, description: Optional dropoff longitude. }, pickup_address: { type: string, description: Optional pickup formatted address. Defaults to users current location. }, pickup_latitude: { type: number, description: Optional pickup latitude. }, pickup_longitude: { type: number, description: Optional pickup longitude. }, product_id: { type: string, description: Optional Uber product_id if the app owner wants to preselect a ride type. } }, required: [destination] }, auth_required: false, status_message: Preparing Uber ride link... } ] }清单中的几个关键设计值得注意required仅包含destination这是Fails fast原则的声明端体现——唯一必须由 Omi 提供的字段是目的地其余全部可选auth_required: false明确标注该工具无需鉴权与零凭证架构自洽status_messageOmi 在调用过程中向用户展示的中间态提示文案description末尾强调 The user must confirm the ride inside Uber把安全约束写进给 LLM 的系统提示从语义层面约束 Omi 不要产生已下单的错误表述。在 test_main.py 中test_manifest_parameters_are_json_schema_object用例验证了清单的parameters.type object且destination在required数组中保证清单契约不被误改。四、call_uber端点与请求参数模型POST /api/call_uber接收CallUberRequest模型main.py完整字段如下字段类型必填说明destinationstring是用户想去的目的地如SFO airportpickup_addressstring否上车点格式化地址缺省用当前位置pickup_latitude/pickup_longitudefloat否上车点经纬度dropoff_addressstring否精确的下车点格式化地址dropoff_latitude/dropoff_longitudefloat否下车点经纬度product_idstring否预设 Uber 车型 ID如 UberX / UberXL 对应 IDuid/app_id/tool_namestring否Omi 侧会话与工具标识geolocationobject否Omi 提供的用户位置对象作为上车点的兜底来源4.1 地理位置兜底解析当 Omi 携带了geolocation而调用方未显式传 pickup 坐标时端点通过_geo_value辅助函数做多键名容错解析main.py纬度优先取geolocation.latitude其次geolocation.lat经度依次尝试longitude、lng、lon地址依次尝试formatted_address、address。解析优先级为显式payload.pickup_*字段 geolocation兜底main.py。这也是为什么test_main.py中test_bad_geolocation_returns_400用例传入{latitude: nearby}这类非法字符串时服务会返回 400 与could not convert string to float的 detailtest_main.py。4.2 响应格式成功时返回三个字段main.py{ result: Uber is ready for 1455 Market Street, San Francisco. Open this link to review and confirm the ride in Uber: https://m.uber.com/ul/?actionsetPickuppickupmy_locationdropoff[formatted_address]1455%20Market%20Street%2C%20San%20Franciscodropoff[nickname]1455%20Market%20Street%2C%20San%20Francisco, web_link: https://m.uber.com/ul/?actionsetPickup..., app_link: uber://?actionsetPickup... }result面向用户的自然语言回复已内嵌web_linkOmi 可直接朗读/展示web_link移动端网页版链接可在浏览器中打开app_linkuber://协议链接用于唤起已安装的 Uber 客户端。若destination、dropoff_address均缺失导致无法构建链接build_uber_deep_links会抛出ValueError端点将其转换为HTTPException(status_code400)返回main.py。五、深度链接构建引擎uber_links.py源码级解析这是整个插件最核心的部分值得逐层拆解。5.1 基础常量与数据模型UBER_WEB_BASE_URL https://m.uber.com/ul/ UBER_APP_BASE_URL uber://UberLocation是不可变 dataclassuber_links.py承载单个地点的四要素latitude、longitude、nickname、formatted_address并提供两个语义判断方法has_coordinates()经纬度是否齐全缺一不可has_label()昵称或格式化地址是否存在。UberDeepLinks则是web_link/app_link的成对容器uber_links.py。5.2 输入清洗与坐标校验链接构建前有一道严格的净化校验管线_clean_textuber_links.py将字符串按空白拆分后重排再合并折叠连续空格与换行清洗后为空串则视为None。这解释了为何destination 会被判定为无效。_normalize_floatuber_links.py兼容float/int/str三种类型输入统一转float空值返回None。_valid_lat_lnguber_links.py纬度必须在[-90, 90]经度必须在[-180, 180]且对每个坐标独立校验——即使只传了一个坐标越界同样拒绝。build_location将以上三步串成入口uber_links.py任何越界坐标都会抛出带明确错误信息的ValueError。配套的 test_coord_bounds.py 覆盖了边界值(90, -180)通过、(91, 0)/(0, 181)/(-91, 0)/(0, -181)拒绝、以及单坐标越界lat200、lng181拒绝等场景。5.3 链接拼装规则build_uber_deep_linksuber_links.py按以下规则生成参数固定动作所有链接都以actionsetPickup开头即设置上车点并进入叫车流程。目的地兜底若显式提供了destination而dropoff缺少标签既无 nickname 也无 formatted_address则把destination同时作为 dropoff 的nickname和formatted_address填充。快速失败当destination为空、dropoff 既无标签又无坐标时直接抛ValueError(A destination or dropoff location is required)uber_links.py对应 test_uber_links.py 中test_destination_is_required与test_whitespace_destination_is_rejected两个用例。pickup 参数若有坐标或标签则逐项写入pickup[latitude]、pickup[longitude]、pickup[nickname]、pickup[formatted_address]否则退化为pickupmy_location让 Uber 使用手机定位。dropoff 参数同样写入dropoff[latitude]、dropoff[longitude]、dropoff[nickname]、dropoff[formatted_address]。车型预设product_id非空时附加product_id参数用于指定 UberX/UberXL 等车型。5.4 URL 编码细节_encode_queryuber_links.py是保证链接可被 Uber 服务端正确解析的关键.join(f{quote(key, safe[])}{quote(value, safe)} for key, value in params)参数名key使用safe[]保留方括号dropoff[formatted_address]这类键名不能被转义参数值value使用safe全量转义因此示例中的地址会被编码为1455%20Market%20Street%2C%20San%20Francisco。test_uber_links.py 的两个主用例完整验证了这条链路test_destination_builds_mobile_web_and_app_links断言web_link以https://m.uber.com/ul/?开头、app_link以uber://?开头并包含actionsetPickup、pickupmy_location、dropoff[formatted_address]SFO%20Airport与dropoff[nickname]SFO%20Airporttest_coordinates_and_product_id_are_preserved则验证坐标与product_id的透传无损。六、本地运行与验证按 README.md 的步骤在仓库根目录下即可拉起服务cd plugins/uber_call python3 -m venv .venv . .venv/bin/activate pip install -r requirements.txt uvicorn main:app --reload --port 8080依赖版本下限由 requirements.txt 锁定fastapi0.111.0、httpx0.27.0供 FastAPITestClient使用、uvicorn[standard]0.30.0。启动后可先验证健康检查curl http://localhost:8080/health # {status:ok}再验证清单与工具端点curl http://localhost:8080/.well-known/omi-tools.json curl -X POST http://localhost:8080/api/call_uber \ -H Content-Type: application/json \ -d {destination: SFO Airport}返回的web_link形如https://m.uber.com/ul/?actionsetPickuppickupmy_locationdropoff[nickname]SFO%20Airportdropoff[formatted_address]SFO%20Airport可直接在手机浏览器打开验证跳转。七、Omi App Store 接入配置要让真实 Omi 设备调用该工具需在 Omi 中创建一个External Integration应用并配置两个 URLREADME.mdApp Home URLhttps://your-hostChat Tools Manifest URLhttps://your-host/.well-known/omi-tools.json配置完成后用户安装该集成并说出Call Uber to 1455 Market Street, San FranciscoOmi 会命中清单中的call_uber工具向/api/call_uber发送 POST并把返回的链接呈现给用户。由于web_link已内嵌在result的自然语言回复中Omi 既可以直接朗读结果也可以引导用户点击打开链接。需要注意生产部署时your-host必须是可以被 Omi 服务端公网访问的 HTTPS 域名本地localhost:8080仅适用于开发调试。八、安全与合规设计该插件把确认权归还用户落实到了代码与语义两个层面README.md绝不静默下单服务只产出链接不触发任何真实订单actionsetPickup仅预填上车点用户进入 Uber 后仍需亲自确认接送点、车型、价格与支付方式。零敏感数据落盘不存储 Uber OAuth token、API Key、支付凭据或客户数据auth_required亦为false。地理位置最小使用即使 Omi 提供了geolocation也仅用于预填 pickup 坐标不做任何持久化或外传。语义层约束工具描述与返回的result文案都刻意使用 review and confirm 措辞从提示词层面避免 LLM 或用户误解为已完成叫车。此外坐标校验纬度[-90,90]、经度[-180,180]与输入清洗_clean_text共同保证了拼入链接的数值与文本是合法、可解析的从源头降低生成畸形链接的概率。九、测试体系仓库为该插件提供了三层测试覆盖链接构建、端点行为与坐标边界# 在仓库根目录执行 python3 -m unittest plugins/uber_call/test_uber_links.py python3 -m unittest plugins/uber_call/test_main.py python3 -m unittest plugins/uber_call/test_coord_bounds.py测试文件覆盖点plugins/uber_call/test_uber_links.py目的地生成移动网页/App 双链接、坐标与product_id透传、空目的地/纯空白目的地快速失败plugins/uber_call/test_main.py清单parameters为 JSON Schema object 且destination必填、非法geolocation返回 400plugins/uber_call/test_coord_bounds.py坐标边界值通过、越界成对/单坐标拒绝test_main.py使用 FastAPI 官方TestClient若未安装httpx会以unittest.skipIf优雅跳过test_main.py保证依赖不全时其余测试仍可运行。十、总结与适用场景Omi Uber Call App 展示了一条极具参考价值的受限 API 替代路径当目标服务的官方写接口需要高门槛资质时通过其公开的深度链接协议完成预填 用户确认的轻量集成既规避了凭证管理带来的安全面又保住了核心体验。该模式适合任何需要把用户引导进第三方 App 完成后续操作的场景——打车、支付、导航、内容分享均可类比复用。对开发者而言本插件的可迁移资产包括多键名容错的geolocation兜底解析、独立的坐标/文本净化管线、参数名保留方括号的编码策略以及清单契约 端点测试双保险的验证思路。相关实现均可直接阅读 plugins/uber_call 目录下的源码与测试继续深入研究。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考