> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwenintelligence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 参考

> 调用已发布的 Mobile-Use Agent，支持标准版和专属版。提交任务文本和当前屏幕截图，通过 metadata 传入设备与应用上下文，以 SSE 返回下一步手机界面操作。界面操作由调用方执行，执行后携带会话 ID 和最新截图继续调用。

<Info>
  API 版本：`2026-08-31`。调用前请先完成[实例创建、配置与发布](./guide#接入流程)。
</Info>

## 接入前提

- 在 [SDK 中心](https://api.aliyun.com/api-tools/sdk/MaasQIService?version=2026-08-31\&language=java-async-tea\&tab=primer-doc) 安装 SDK。
- 已开通 Mobile-Use Agent 服务，准备已发布的 Mobile-Use Agent 实例 ID 及其访问密钥。
- Mobile-Use Agent 提供标准版和专属版，按所选实例的版本调用。
- 使用 SDK 完成 AccessKey 认证；实例访问密钥另放在 X-QI-Agent-Api-Key，不能替代 AccessKey 签名。
- 设置 Content-Type: application/json、Accept: text/event-stream，stream 必须为 true。

### 调用方式

- 方法与路径：`POST /gui/v1/chat/completions`。
- X-QI-Instance-Id 指定实例，按已发布配置执行；请求体 model 是兼容占位，不能切换模型。
- 响应为 SSE 增量事件，不是一个完整 JSON；持续读取到流结束，并检查流内错误。

### 会话管理

首轮可省略 X-QI-Session-Id，从 SSE 正文保存 qi\_session\_id，后续通过同名请求头续接。同一会话顺序调用；不同会话使用不同标识。不要依赖网关透传自定义响应头，实际标识以 SSE 正文为准。

## 流控信息

当前云产品 API 请求速率暂未透出。

## 授权信息

为 RAM 用户或 RAM 角色授权时，可在权限策略的 `Action` 元素中使用以下操作：

| 操作                                      | 访问级别 | 资源类型    | 条件关键字 | 关联操作 |
| --------------------------------------- | ---- | ------- | ----- | ---- |
| `maasqiservice:GuiChatCompletionStream` | None | 全部资源 \* | 无     | 无    |

请通过 [RAM 访问控制](https://ram.console.aliyun.com/)完成授权。

## 请求语法

```text
POST /gui/v1/chat/completions HTTP/1.1
```

## 基本信息

| 字段           | 值                          |
| ------------ | -------------------------- |
| 方法           | `POST`                     |
| 路径           | `/gui/v1/chat/completions` |
| 协议           | HTTPS、SSE                  |
| 认证方式         | AK                         |
| Content-Type | `application/json`         |
| Accept       | `text/event-stream`        |
| 响应类型         | `text/event-stream`        |

## 请求参数

### Header 参数

| 参数                   | 类型     | 必填 | 说明                                                     |
| -------------------- | ------ | -- | ------------------------------------------------------ |
| `X-QI-Agent-Api-Key` | string | 是  | Agent 实例访问密钥，用于 QICloud Customer 接口鉴权。                 |
| `X-QI-Instance-Id`   | string | 是  | 已发布的 Mobile-Use Agent 实例 ID，必须与 X-QI-Agent-Api-Key 对应。 |
| `X-QI-Session-Id`    | string | 否  | 可选会话标识。首步可省略，由服务端生成；后续 Mobile-Use Agent 步骤必须传回同一值续接状态。 |

### Body 参数

Mobile-Use Agent 调用请求体。首次调用提交当前目标和截图；续轮提交上一动作真实结果及新截图，不重放历史消息。Chat Completions 字段使用 snake\_case，stream 设为 true。

| 参数                                       | 类型      | 必填 | 说明                                                                                                                             |
| ---------------------------------------- | ------- | -- | ------------------------------------------------------------------------------------------------------------------------------ |
| `allowed_token_ids`                      | array   | 否  | 允许生成的 Token ID 白名单。                                                                                                            |
| `allowed_token_ids[]`                    | integer | 否  | 一个允许生成的 Token 整数 ID，需使用目标模型的词表 ID。                                                                                             |
| `bad_words`                              | array   | 否  | 禁止生成的词或字符串列表。                                                                                                                  |
| `bad_words[]`                            | string  | 否  | 一个不希望模型生成的词或字符串。                                                                                                               |
| `chat_template_kwargs`                   | object  | 否  | vLLM/OpenAI-Compatible 模板参数对象。请求值会覆盖模型默认同名值并原样传给 Mobile-Use Agent 主模型。                                                         |
| `chat_template_kwargs.enable_thinking`   | boolean | 否  | chat\_template\_kwargs.enable\_thinking：请求级模型思考开关，覆盖同名默认值。Mobile-Use Agent 响应不会因开启该开关而返回 reasoning\_content。                   |
| `chat_template_kwargs.preserve_thinking` | boolean | 否  | 是否在续轮中保留已有思考上下文；按 vLLM/Qwen chat\_template\_kwargs 原样透传。                                                                       |
| `frequency_penalty`                      | number  | 否  | 频率惩罚参数，透传给 Mobile-Use Agent 主模型。                                                                                               |
| `ignore_eos`                             | boolean | 否  | 是否忽略 EOS 并继续生成。                                                                                                                |
| `include_reasoning`                      | boolean | 否  | 是否请求上游生成推理字段；Mobile-Use Agent 对客结果不会直接暴露内部思考。                                                                                  |
| `logprobs`                               | boolean | 否  | 模型兼容参数，JSON 字段为 logprobs。是否接受及生效取决于实例所用模型；当前 Mobile-Use Agent 响应不提供 Token 对数概率明细。                                              |
| `max_completion_tokens`                  | integer | 否  | OpenAI 兼容最大补全 Token 数，提供时必须大于 0。                                                                                               |
| `max_tokens`                             | integer | 否  | OpenAI 兼容最大生成 Token 数，提供时必须大于 0。                                                                                               |
| `messages`                               | array   | 是  | 当前 Mobile-Use Agent 步骤消息。首步只能包含一条 user；后续步骤只能是一条 tool 后跟一条 user，不允许携带完整多轮历史。                                                   |
| `messages[].content`                     | array   | 否  | 消息内容。user 使用内容数组，包含恰好一张当前截图，并可附加任务文字；截图支持公开 HTTPS URL 或 Base64 图片 Data URL。role=tool 时填上一动作的真实执行结果，可为非空字符串、对象或数组。              |
| `messages[].content[].image_data`        | string  | 否  | input\_image 的兼容内联图片字段；可传 Base64 Data URL。                                                                                     |
| `messages[].content[].image_url`         | object  | 否  | 截图引用。支持 image\_url 字符串或包含 url 的对象；此处展示对象形式。                                                                                    |
| `messages[].content[].image_url.url`     | string  | 否  | 公开可访问的 HTTPS 图片 URL，或 Base64 图片 Data URL。每轮 user 消息必须且只能包含一张当前截图；已过期或无法访问的图片地址会被拒绝。                                            |
| `messages[].content[].text`              | string  | 否  | 文本内容，可描述当前操作目标或补充当前页面状态。                                                                                                       |
| `messages[].content[].type`              | string  | 否  | 内容项类型。文本使用 text 或 input\_text；截图使用 image\_url 或 input\_image。                                                                  |
| `messages[].role`                        | string  | 否  | 消息角色。当前输入必须以 user 结尾；存在上一轮执行回执时前一条必须为 tool。                                                                                    |
| `messages[].tool_call_id`                | string  | 否  | role=tool 时必填，引用上一轮 Mobile-Use Agent 响应的 tool\_call id。                                                                        |
| `metadata`                               | object  | 否  | Mobile-Use Agent 步骤元数据。支持 screen\_width、screen\_height、available\_apps 和兼容字段 harness\_message；tool 回执与 harness\_message 不可同时传。 |
| `metadata.app_list`                      | array   | 否  | available\_apps 的兼容别名；同样是 App 名称字符串数组。                                                                                         |
| `metadata.app_list[]`                    | string  | 否  | 单个应用名称；与 available\_apps 的数组项含义一致。                                                                                             |
| `metadata.available_apps`                | array   | 否  | Mobile-Use Agent 标准版 的应用名称补充列表，JSON 字段为 available\_apps。新传入列表替换之前的补充项，但默认应用仍保留；空数组不清空默认应用。Mobile-Use Agent 专属版 不使用此列表。         |
| `metadata.available_apps[]`              | string  | 否  | 单个应用名称，使用设备上的真实应用显示名。                                                                                                          |
| `metadata.harness_message`               | string  | 否  | 旧客户端的 Mobile-Use Agent Harness 回执文本；与前置 tool 消息不能同时传。新客户端优先使用 \[tool,user] 消息。                                                 |
| `metadata.screen_height`                 | integer | 否  | 屏幕高度正整数。base64 图片会从图片本身解析宽高；URL 图片时该值用于运行时屏幕尺寸。                                                                                |
| `metadata.screen_width`                  | integer | 否  | 屏幕宽度正整数。base64 图片会从图片本身解析宽高；URL 图片时该值用于运行时屏幕尺寸。                                                                                |
| `min_p`                                  | number  | 否  | vLLM Min-P 采样参数。                                                                                                               |
| `min_tokens`                             | integer | 否  | 最少生成 Token 数。                                                                                                                  |
| `mm_processor_kwargs`                    | object  | 否  | 多模态预处理器参数，按键原样透传给 Mobile-Use Agent 主模型。                                                                                        |
| `mm_processor_kwargs.max_dynamic_patch`  | integer | 否  | 示例：视觉模型允许的最大动态图像 patch 数。                                                                                                      |
| `model`                                  | string  | 否  | 为 OpenAI 客户端兼容保留；路由时忽略，模型由实例已发布配置决定，响应 model 固定为空字符串。                                                                          |
| `n`                                      | integer | 否  | 建议设为 1。该参数是否被模型接受取决于模型；当前 Mobile-Use Agent 响应不会透出多个候选动作。                                                                       |
| `parallel_tool_calls`                    | boolean | 否  | 模型兼容的并行工具调用开关，不会扩大本接口可用的 Mobile-Use Agent 动作集合。                                                                                |
| `presence_penalty`                       | number  | 否  | 存在惩罚参数，透传给 Mobile-Use Agent 主模型。                                                                                               |
| `prompt_logprobs`                        | integer | 否  | 模型兼容参数，JSON 字段为 prompt\_logprobs。是否接受取决于模型；当前 Mobile-Use Agent 响应不返回输入 Token 概率明细。                                             |
| `reasoning_effort`                       | string  | 否  | OpenAI 兼容推理强度，例如 low、medium、high。                                                                                              |
| `repetition_penalty`                     | number  | 否  | vLLM 重复惩罚参数。                                                                                                                   |
| `response_format`                        | object  | 否  | 模型兼容的结构化输出选项，不改变本接口最终的 Mobile-Use Agent 工具调用结构。请避免设置与动作协议冲突的输出约束。                                                              |
| `response_format.type`                   | string  | 否  | 响应格式类型，例如 text、json\_object 或 json\_schema。                                                                                    |
| `seed`                                   | integer | 否  | 随机种子。                                                                                                                          |
| `skip_special_tokens`                    | boolean | 否  | 是否跳过特殊 Token。                                                                                                                  |
| `stop`                                   | array   | 否  | 停止序列。兼容单个字符串或字符串数组；此处展示数组形式。                                                                                                   |
| `stop[]`                                 | string  | 否  | 一个停止字符串。模型是否接受及停止行为取决于模型。                                                                                                      |
| `stop_token_ids`                         | array   | 否  | vLLM 停止 Token ID 列表。                                                                                                           |
| `stop_token_ids[]`                       | integer | 否  | 一个停止 Token 的整数 ID，需使用目标模型的词表 ID。                                                                                               |
| `stream`                                 | boolean | 是  | 是否使用 SSE 流式响应。本接口必须传 true。                                                                                                     |
| `stream_options`                         | object  | 否  | OpenAI 兼容流式选项。                                                                                                                 |
| `stream_options.include_usage`           | boolean | 否  | 是否在 data:\[DONE] 之前输出 usage 统计块。                                                                                               |
| `structured_outputs`                     | object  | 否  | vLLM 结构化输出约束。                                                                                                                  |
| `structured_outputs.choice`              | array   | 否  | 允许的枚举文本集合。                                                                                                                     |
| `structured_outputs.choice[]`            | string  | 否  | 一项允许模型选择的文本值。                                                                                                                  |
| `temperature`                            | number  | 否  | 采样温度，覆盖 Mobile-Use Agent 主模型默认值。默认为 0，建议设置为 0。                                                                                 |
| `top_k`                                  | integer | 否  | vLLM Top-K 采样参数。                                                                                                               |
| `top_logprobs`                           | integer | 否  | 模型兼容参数，JSON 字段为 top\_logprobs。是否接受取决于模型；当前 Mobile-Use Agent 响应不返回候选 Token 概率明细。                                                |
| `top_p`                                  | number  | 否  | Top-P 核采样参数，覆盖 Mobile-Use Agent 主模型默认值。                                                                                        |

### JSON 字段写法

以下示例为 HTTP JSON 请求体。Chat Completions 字段使用 snake\_case，例如 stream\_options、include\_usage、chat\_template\_kwargs、image\_url；参数表的设计名称可能显示为驼峰，请按示例中的 JSON 键发送。

### 请求示例

以下请求体已使用 Python SDK 通过预发网关验证。实例 ID 和访问密钥通过请求头传入。此处使用 1×1 PNG 测试图，仅用于接口连通性验证；实际操作时必须替换为设备当前真实截图及其宽高，不能据此认为设备动作已执行。

```json
{
  "model": "",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "观察当前屏幕并返回下一步操作"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/screenshot-current.png"
          }
        }
      ]
    }
  ],
  "metadata": {
    "screen_width": 1,
    "screen_height": 1,
    "available_apps": [
      "设置",
      "浏览器"
    ]
  },
  "tools": [],
  "chat_template_kwargs": {
    "enable_thinking": false
  },
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 0.2,
  "max_completion_tokens": 2048
}
```

### 截图与动作回执

1. 首轮只传一条 user，包含任务目标和恰好一张当前截图。图片必须为有效的公开 HTTPS URL，或 Base64 图片 Data URL（data:image/png;base64,...）。
2. 合并 SSE 中的 tool\_calls，完整解析 function.arguments 后，由调用方执行动作；不要在参数尚未拼接完成时执行。
3. 续轮使用返回的会话 ID，messages 仅传 `[tool,user]`，不要重放历史 assistant 消息。tool\_call\_id 使用上一轮返回的 ID，content 填真实执行结果；user 带最新截图。
4. 收到结束或用户接管动作时停止自动执行或转交用户，动作建议本身不代表设备已执行成功。

续轮 messages 格式（动作确实执行成功后才能填写成功回执）：

```jsonc
[
  {
    "role": "user",
    "content": [
      # 注意：仅上轮为take_over和open时需要注入text信息，
      # 具体内容见：返回参数->补充说明
      {
        "type": "text",
        "text": "这是操作后的屏幕，请继续"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/screenshot-next.png"
        }
      }
    ]
  }
]
```

请替换截图地址、tool\_call\_id 和实际执行结果。

### 设备元数据

- screen\_width、screen\_height 填截图的实际像素宽高，URL 截图建议提供；Base64 图片可读取自身尺寸。
- Mobile-Use Agent 标准版 的 available\_apps（兼容别名 app\_list）是应用名称补充列表。新列表替换之前的补充项，但默认应用仍保留；Mobile-Use Agent 专属版 不使用此列表。
- 新接入请使用 tool 消息回执；旧方式 metadata.harness\_message 不可与 tool 消息同时传。
- tools 应省略或为空数组。Mobile-Use Agent 思考开关不会让响应返回 reasoning\_content；自定义响应格式也不能改变 Mobile-Use Agent 对外动作协议。

### 模型兼容参数

请求中显式提供的采样参数优先于模型默认值，chat\_template\_kwargs 按键合并。请用嵌套形式 `"chat_template_kwargs":{"enable_thinking":true}`，其中的键也保持 snake\_case。扩展参数是否支持、允许范围和效果取决于实例所选模型；不支持的参数可能被模型拒绝。

Agent 不原样转发模型的完整响应：当前不返回 logprobs、top\_logprobs 或 prompt\_logprobs 明细；n 建议保持 1，不承诺返回多候选结果。

## 返回参数

SSE 流式响应元数据。业务事件连续返回，最终以 data:\[DONE] 结束；完整格式见返回参数补充说明。

| 参数          | 类型     | 必填 | 说明                                                                  |
| ----------- | ------ | -- | ------------------------------------------------------------------- |
| `requestId` | string | 否  | 由 POP 网关生成的请求标识，用于网关链路追踪；Agent 请求 ID 以 SSE 正文中的 qi\_request\_id 为准。 |

### SSE 读取规则

响应 Content-Type 为 text/event-stream。以空行分隔事件，解析 data: 后的 JSON；忽略冒号开头的心跳注释。一次网络读取不一定是一个完整事件，需缓存并拼接后解析。

### 数据字段

| 字段                                | 使用方式                                                                                                      |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| id / created                      | 响应标识与创建时间（Unix 秒）。                                                                                        |
| object / model                    | object 为 chat.completion.chunk；model 为空字符串。                                                               |
| qi\_session\_id / qi\_request\_id | 保存会话与请求标识，用于续接及排查。                                                                                        |
| choices\[0].delta.content         | 按顺序拼接的正文增量。                                                                                               |
| choices\[0].delta.tool\_calls     | 按 index 拼接动作调用，function.arguments 为 JSON 字符串，完整解析后由调用方执行。                                                 |
| choices\[0].finish\_reason        | 非空表示内容结束，常见 stop、tool\_calls、length；之后仍可能返回用量事件。                                                          |
| qi\_event                         | 进度或错误信息，不拼入正文。                                                                                            |
| usage                             | include\_usage=true 时独立返回，choices 为空数组；prompt\_tokens、completion\_tokens、total\_tokens 是 Token 用量，不是最终账单。 |

### 完成与异常

通常按角色、内容或进度、finish\_reason、可选 usage、data:\[DONE] 的顺序返回。事件数量及分片边界不固定。

- progress 可展示 message，不要写死阶段数量。
- error 表示执行失败，即使 HTTP 为 200。读取 code、http\_status、message、retryable，部分错误还包含 param、reason。
- \[DONE] 仅代表流结束，不单独代表成功；断开且无结束标记时，结果可能不完整。

流内错误示例（只展示相关字段）：

```text
data:{"qi_event":{"type":"error","stage":"input_validation","code":"invalid_parameter","http_status":400,"message":"The reference image URL has expired. Upload the image again or provide a new signed URL.","retryable":false,"reason":"image_url_expired"}}

data:[DONE]
```

HTTP/网关错误参见错误码表；流已建立后的错误按 qi\_event 处理。

### UI 动作空间说明

模型通过工具调用返回动作。`function.arguments` 为动作 JSON，通过 `action_type` 区分动作类型，由客户端负责执行。

#### 动作类型

| `action_type`   | 含义            | 参数                                                    |
| --------------- | ------------- | ----------------------------------------------------- |
| `click`         | 点击            | `x`、`y`：点击坐标                                          |
| `double_click`  | 双击            | `x`、`y`：双击坐标                                          |
| `long_press`    | 长按            | `x`、`y`：长按坐标                                          |
| `drag`          | 拖拽或滑动         | `start_x`、`start_y`：起点；`end_x`、`end_y`：终点             |
| `type`          | 向当前聚焦的输入框输入文本 | `text`：输入内容                                           |
| `open`          | 打开 App        | `text`：App 名称，客户端需将 App 名称映射为包名或启动方式                  |
| `system_button` | 按系统键          | `button`：`back`（返回）、`home`（桌面）、`enter`（回车）、`menu`（菜单） |
| `wait`          | 等待            | `duration`：等待指定秒数                                     |
| `take_over`     | 暂停，等待人工介入     | `text`：提示或问题；`tag`：介入类型                               |
| `terminate`     | 结束任务          | `status`：结果状态，取值为 `success` 或 `failed`；`answer`：最终回答  |

#### 补充说明

- 坐标以当前截图左上角为原点，`x` 轴向右、`y` 轴向下，单位为像素。
- 普通动作执行后，客户端携带新截图请求下一轮；`terminate` 用于结束循环。
- 执行 `open` 后，客户端检查目标 App 是否位于前台，并在下一轮 `user` 消息中同时携带新截图和以下文本反馈：
  - `已经成功打开{App 名称}`
  - `未成功打开{App 名称}`
- 执行 `take_over` 后，客户端展示 `text` 并暂停。人工操作完成后，下一轮 `user` 消息中同时携带新截图和用户输入；无输入时反馈：
  - `用户已经完成操作，请继续执行`
- 以上反馈均作为下一轮 `user` 消息的文本内容发送，无需额外构造 `tool` 消息。
- 详细流程见最小实现 Demo。

### QI GUI Agent 客户接入最小实现

```python
#!/usr/bin/env python3
"""QI GUI Agent —— 客户接入最小实现（单文件，依赖 Pillow）。

接入模型：客户端负责「截图 + 执行」，QI 负责「决策」。
每一轮把当前截图和任务发给 QI，QI 返回一个动作（点击/滑动/输入…），
客户端在设备上执行后，带着新截图请求下一轮，直到 QI 返回 terminate。

    ┌─────────┐  session_id + query + screenshot   ┌─────────┐
    │ 客户端   │ ─────────────────────────────────▶ │   QI    │
    │(截图/执行)│ ◀───────────────────────────────── │ (决策)  │
    └─────────┘        action: click/swipe/...      └─────────┘

运行：
    export QI_AK_ID=your_ak_id
    export QI_AK_SECRET=your_ak_secret
    export GUI_API_KEY=qis_xxx
    export GUI_INSTANCE_ID=GUI_xxx
    python qi_min_demo.py --device emulator-5554 --task "打开设置，进入 WiFi 页面"
"""
from __future__ import annotations

import argparse
import base64
import json
import hashlib
import hmac
from datetime import datetime, timezone
from io import BytesIO
from math import ceil, floor, sqrt
import os
import re
import subprocess
import time
import http.client
import urllib.parse
import uuid

from PIL import Image

TEMPERATURE = 0  # QI GUI Agent 的温度系数请设为 0。
MAX_IMAGE_PIXELS = 1_536_000
IMAGE_RESIZE_FACTOR = 28  # Qwen2.5-VL 使用 28，Qwen3-VL 使用 32。

ENDPOINT = os.environ.get("QI_ENDPOINT", "https://maasqiservice.cn-beijing.aliyuncs.com/gui/v1/chat/completions")
ACS_ACTION = os.environ.get("QI_ACS_ACTION", "GuiChatCompletionStream")
ACS_VERSION = os.environ.get("QI_ACS_VERSION", "2026-08-31")

# 桌面 / 系统类（Launcher、系统设置、AOSP 默认应用、输入法、系统服务、测试用 App）。
SYSTEM_APP_MAP: dict[str, str] = {
    # 桌面
    "桌面": "com.google.android.apps.nexuslauncher",
    # 系统设置
    "Settings": "com.android.settings",
    "设置": "com.android.settings",
    # 联系人
    "Contacts": "com.google.android.contacts",
    "Google Contacts": "com.google.android.contacts",
    # 时钟
    "Clock": "com.google.android.deskclock",
    "Google Clock": "com.google.android.deskclock",
    # 相机
    "Camera": "com.android.camera2",
    # 短信
    "SMS": "com.google.android.apps.messaging",
    "信息": "com.android.mms",
    # 邮件（系统 / 测试）
    "邮件": "com.android.email",
    "Mail": "com.gmailclone",
    # 录音
    "AudioRecorder": "com.android.soundrecorder",
    # 地图 & 浏览器
    "Maps": "com.google.android.apps.maps",
    "地图": "com.google.android.apps.maps",
    "Chrome": "com.android.chrome",
    # 日历
    "Calendar": "org.fossify.calendar",
    "Google Calendar": "com.google.android.calendar",
    # 文件管理
    "files": "com.google.android.documentsui",
    "Files": "com.android.fileexplorer",
    "Google Files": "com.google.android.apps.nbu.files",
    # 相册
    "Gallery": "gallery.photomanager.picturegalleryapp.imagegallery",
    "相册": "com.coloros.gallery3d",
    "照片": "com.coloros.gallery3d",
    # Google 系统服务
    "Google": "com.google.android.googlequicksearchbox",
    "Google Chat": "com.google.android.apps.dynamite",
    "Android System WebView": "com.google.android.webview",
    "查找中心": "com.google.android.apps.adm",
    # 输入法
    "Gboard": "com.google.android.inputmethod.latin",
    "搜狗输入法定制版": "com.sohu.inputmethod.sogouoem",
    "微信输入法": "com.tencent.wetype",
    # OEM 系统服务
    "智能推荐服务": "com.opos.ads",
    "快应用服务框架": "com.nearme.instant.platform",
}

# 常见 App（名称 -> 包名），含常用别名。
COMMON_APP_MAP: dict[str, str] = {
    # ── 电商 / 生活 ──
    "淘宝": "com.taobao.taobao",
    "天猫": "com.tmall.wireless",
    "天猫超市": "com.tmall.wireless",
    "京东": "com.jingdong.app.mall",
    "拼多多": "com.xunmeng.pinduoduo",
    "闲鱼": "com.taobao.idlefish",
    "美团": "com.sankuai.meituan",
    "大众点评": "com.dianping.v1",
    "盒马": "com.wudaokou.hippo",
    "盒马生鲜": "com.wudaokou.hippo",
    "淘宝闪购": "me.ele",
    "小象超市": "com.meituan.retail.v.android",
    "什么值得买": "com.smzdm.client.android",
    "山姆会员商店": "cn.samsclub.app",
    "Temu": "com.einnovation.temu",
    "阿里巴巴": "com.alibaba.wireless",
    "天猫养车": "com.ncarzone.tmyc",
    "菜鸟": "com.cainiao.wireless",
    # ── 出行 / 地图 ──
    "滴滴": "com.sdu.didi.psnger",
    "滴滴出行": "com.sdu.didi.psnger",
    "高德地图": "com.autonavi.minimap",
    "高德": "com.autonavi.minimap",
    "12306": "com.MobileTicket",
    "铁路12306": "com.MobileTicket",
    "哈啰": "com.jingyao.easybike",
    "Uber": "com.ubercab",
    "携程旅行": "ctrip.android.view",
    "Trip.com": "ctrip.english",
    "飞猪旅行": "com.taobao.trip",
    "航旅纵横": "com.umetrip.android.msky.app",
    "东方航空": "com.rytong.ceair",
    "爱彼迎": "com.airbnb.android",
    "Booking.com缤客": "com.booking",
    "Expedia": "com.expedia.bookings",
    "租租车": "com.zuzuChe",
    "OsmAnd": "net.osmand",
    # ── 社交 / 通讯 ──
    "微信": "com.tencent.mm",
    "qq": "com.tencent.mobileqq",
    "QQ": "com.tencent.mobileqq",
    "钉钉": "com.alibaba.android.rimet",
    "飞书": "com.ss.android.lark",
    "微博": "com.sina.weibo",
    "新浪微博": "com.sina.weibo",
    "小红书": "com.xingin.xhs",
    "知乎": "com.zhihu.android",
    "脉脉": "com.taou.maimai",
    "Telegram": "org.telegram.messenger",
    "WhatsApp": "com.whatsapp",
    "X": "com.twitter.android",
    "LinkedIn": "com.linkedin.android",
    "Slack": "com.Slack",
    "Reddit": "com.reddit.frontpage",
    "Quora": "com.quora.android",
    "豆瓣": "com.douban.frodo",
    "腾讯会议": "com.tencent.wemeet.app",
    # ── 视频 / 音乐 / 阅读 ──
    "抖音": "com.ss.android.ugc.aweme",
    "TikTok": "com.zhiliaoapp.musically",
    "哔哩哔哩": "tv.danmaku.bili",
    "b站": "tv.danmaku.bili",
    "爱奇艺": "com.qiyi.video",
    "优酷视频": "com.youku.phone",
    "网易云音乐": "com.netease.cloudmusic",
    "qq音乐": "com.tencent.qqmusic",
    "QQ音乐": "com.tencent.qqmusic",
    "Spotify": "com.spotify.music",
    "小宇宙": "app.podcast.cosmos",
    "AntennaPod": "de.danoeh.antennapod",
    "VLC": "org.videolan.vlc",
    "Retro Music": "code.name.monkey.retromusic",
    "Pi Music Player": "com.Project100Pi.themusicplayer",
    "今日头条": "com.ss.android.article.news",
    "头条": "com.ss.android.article.news",
    "Substack": "com.substack.app",
    # ── 工具 / 效率 ──
    "支付宝": "com.eg.android.AlipayGphone",
    "wps": "cn.wps.moffice_eng",
    "wps office": "cn.wps.moffice_eng",
    "WPS Office": "cn.wps.moffice_eng",
    "夸克": "com.quark.browser",
    "夸克网盘": "com.quark.clouddrive",
    "百度网盘": "com.baidu.netdisk",
    "浏览器": "mark.via",
    "Brave": "com.brave.browser",
    "网易邮箱": "com.netease.mail",
    "网易邮箱大师": "com.netease.mail",
    "QQ邮箱": "com.tencent.androidqqmail",
    "Gmail": "com.google.android.gm",
    "Google Docs": "com.google.android.apps.docs.editors.docs",
    "Google Drive": "com.google.android.apps.docs",
    "Google Keep": "com.google.android.keep",
    "Google Slides": "com.google.android.apps.docs.editors.slides",
    "Google Tasks": "com.google.android.apps.tasks",
    "Google Fit": "com.google.android.apps.fitness",
    "Google Play Books": "com.google.android.apps.books",
    "Joplin": "net.cozic.joplin",
    "Zotero": "org.zotero.android",
    "NotebookLM": "com.google.android.apps.labs.language.tailwind",
    "GitHub": "com.github.android",
    "Termius": "com.server.auditor.ssh.client",
    "Reqable": "com.reqable.android",
    "Tailscale": "com.tailscale.ipn",
    "ZeroTier One": "com.zerotier.one",
    "Surfboard": "com.getsurfboard",
    "Bitwarden": "com.x8bit.bitwarden",
    "Authenticator": "com.google.android.apps.authenticator2",
    "LibChecker": "com.absinthe.libchecker",
    "Server酱": "com.ft07.serverchan.app3.server_app3",
    "Duolingo": "com.duolingo",
    "欧路词典": "com.eusoft.eudic",
    "Bluecoins": "com.rammigsoftware.bluecoins",
    "Broccoli": "com.flauschcode.broccoli",
    # ── AI ──
    "千问": "com.aliyun.tongyi",
    "ChatGPT": "com.openai.chatgpt",
    "DeepSeek": "com.deepseek.chat",
    "Gemini": "com.google.android.apps.bard",
    "Grok": "ai.x.grok",
    "Perplexity": "ai.perplexity.app.android",
    "豆包": "com.larus.nova",
    # ── 金融 / 银行 ──
    "招商银行": "cmb.pb",
    "中国工商银行": "com.icbc",
    "中国银行": "com.chinamworld.bocmbci",
    "中国建设银行": "com.chinamworld.main",
    "民生银行": "cn.com.cmbc.newmbank",
    "网商银行": "com.mybank.android.phone",
    "微众银行": "com.webank.wemoney",
    "BOCHK 中银香港": "com.bochk.app.aos",
    "ZA Bank": "com.zhongan.ibank",
    "云闪付": "com.unionpay",
    "银联可信服务安全组件": "com.unionpay.tsmservice",
    "动卡空间": "com.citiccard.mobilebank",
    "同花顺": "com.hexin.plat.android",
    "东方财富": "com.eastmoney.android.berlin",
    "天弘基金": "com.thfund.client",
    "Wise": "com.transferwise.android",
    "Pocket": "au.com.commsec.android.CommSecPocket",
    # ── 运营商 / 政务 ──
    "中国移动": "com.greenpoint.android.mc10086.activity",
    "中国电信": "com.ct.client",
    "网上国网": "com.sgcc.wsgw.cn",
    "交管12123": "com.tmri.app.main",
    "浙里办": "com.hanweb.android.zhejiang.activity",
    "杭州市民卡": "com.smk",
    # ── 智能家居 / IoT ──
    "米家": "com.xiaomi.smarthome",
    "小米运动健康": "com.mi.health",
    "小米音箱": "com.xiaomi.mico",
    "小米商城": "com.xiaomi.shop",
    "海尔智家": "com.haier.uhome.uplus",
    "萤石云视频": "com.videogo",
    "小佩宠物": "com.petkit.android",
    "bebird": "com.molink.john.hummingbird",
    "Tesla": "com.teslamotors.tesla",
    "DJI Fly": "dji.go.v5",
    "LEGO® Builder": "com.lego.legobuildinginstructions",
    # ── 游戏 / 娱乐 ──
    "崩坏：星穹铁道": "com.miHoYo.hkrpg",
    "恋与深空": "com.papegames.lysk.cn",
    "大麦": "cn.damai",
    "小布咕": "com.sinyee.babybus.story",
    # ── 其他 ──
    "麦当劳": "com.mcdonalds.gma.cn",
    "McDonald's": "com.mcdonalds.app",
    "酷安": "com.coolapk.market",
    "逍遥游": "com.redteamobile.roaming",
    "无忧行": "com.cmi.jegotrip",
    "e充电": "com.sgcc.evs.echarge",
    "钱包": "com.finshell.wallet",
    "amaysim": "au.com.amaysim.android",
    "Mattermost": "com.mattermost.rn",
    "向日葵远程控制": "com.oray.sunlogin",
    "阿里云": "com.alibaba.aliyun",
}

APP_MAP = SYSTEM_APP_MAP | COMMON_APP_MAP

def validate_config() -> None:
    """只报告缺失变量名，不输出凭据；在截图或设备操作前检查。"""
    required = ("QI_AK_ID", "QI_AK_SECRET", "GUI_API_KEY", "GUI_INSTANCE_ID")
    missing = [name for name in required if not os.environ.get(name, "").strip()]
    if missing:
        raise ValueError("缺少必填环境变量：" + ", ".join(missing))
    endpoint = urllib.parse.urlsplit(ENDPOINT)
    if (endpoint.scheme != "https" or not endpoint.hostname or endpoint.username is not None
            or endpoint.password is not None or endpoint.query or endpoint.fragment):
        raise ValueError("QI_ENDPOINT 必须是无账号、query 和 fragment 的 HTTPS URL")

def sign_headers(body: bytes, session_id: str, request_id: str, *, stream: bool = False) -> dict:
    """ACS3 签名：body 必须与实际发送字节完全一致。会话 ID 复用，请求 ID 每轮更新。"""
    validate_config()
    endpoint = urllib.parse.urlsplit(ENDPOINT)
    body_hash = hashlib.sha256(body).hexdigest()
    headers = {
        "host": endpoint.netloc,
        "content-type": "application/json; charset=utf-8",
        "accept": "text/event-stream" if stream else "application/json",
        "x-acs-action": ACS_ACTION,
        "x-acs-version": ACS_VERSION,
        "x-acs-date": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
        "x-acs-signature-nonce": str(uuid.uuid4()),
        "x-acs-content-sha256": body_hash,
        "X-QI-Agent-Api-Key": os.environ["GUI_API_KEY"],
        "X-QI-Instance-Id": os.environ["GUI_INSTANCE_ID"],
        "X-QI-Session-Id": session_id,
        "X-QI-Request-Id": request_id,
    }
    token = os.environ.get("QI_STS_TOKEN", "")
    if token:
        headers["x-acs-security-token"] = token
    signed = dict(sorted((k.lower(), v.strip()) for k, v in headers.items()
                         if k.lower() in ("host", "content-type") or k.lower().startswith("x-acs-")))
    names = ";".join(signed)
    canonical = "\n".join([
        "POST", endpoint.path or "/", "",
        "".join(f"{k}:{v}\n" for k, v in signed.items()), names, body_hash,
    ])
    to_sign = "ACS3-HMAC-SHA256\n" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
    signature = hmac.new(os.environ["QI_AK_SECRET"].encode("utf-8"),
                         to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
    headers["Authorization"] = (
        f"ACS3-HMAC-SHA256 Credential={os.environ['QI_AK_ID']},"
        f"SignedHeaders={names},Signature={signature}"
    )
    return headers

def resolve_package(name: str) -> str:
    """App 名解析成包名。"""
    assert name in APP_MAP, f"未知的 App 名：{name}"
    return APP_MAP[name]

# ======================================================================
# 1. QI 客户端：一次请求 = 一轮决策
# ======================================================================
def smart_resize(width: int, height: int) -> tuple[int, int]:
    """按 Qwen-VL 的像素预算和倍数对齐规则计算发送尺寸。"""
    if max(width, height) > 200 * min(width, height):
        raise ValueError("截图长边与短边的比值不能超过 200")

    factor = IMAGE_RESIZE_FACTOR
    max_pixels = MAX_IMAGE_PIXELS - 1  # 保持像素数严格低于上限。
    min_pixels = 4 * factor ** 2
    aligned_width = max(factor, round(width / factor) * factor)
    aligned_height = max(factor, round(height / factor) * factor)
    aligned_pixels = aligned_width * aligned_height

    if aligned_pixels > max_pixels:
        shrink = sqrt(width * height / max_pixels)
        return (floor(width / shrink / factor) * factor,
                floor(height / shrink / factor) * factor)
    if aligned_pixels < min_pixels:
        grow = sqrt(min_pixels / (width * height))
        return (ceil(width * grow / factor) * factor,
                ceil(height * grow / factor) * factor)
    return aligned_width, aligned_height

def prepare_screenshot(data: bytes) -> tuple[str, tuple[int, int], tuple[int, int]]:
    """返回图片 data URL、原图尺寸和发送尺寸。"""
    with Image.open(BytesIO(data), formats=("PNG", "JPEG")) as image:
        original_size = image.size
        sent_size = smart_resize(*original_size)
        image_format = image.format
        if sent_size != original_size:
            output = BytesIO()
            image.resize(sent_size, Image.Resampling.LANCZOS).save(output, format=image_format)
            data = output.getvalue()
    url = f"data:image/{image_format.lower()};base64,{base64.b64encode(data).decode()}"
    return url, original_size, sent_size

def restore_action_coordinates(action: dict, original_size: tuple[int, int],
                               sent_size: tuple[int, int]) -> dict:
    """将发送图片上的坐标还原为原始截图像素。"""
    if original_size == sent_size:
        return action
    action_type = action.get("action_type")
    if action_type in ("click", "double_click", "long_press"):
        keys = ("x", "y")
    elif action_type == "drag":
        keys = ("start_x", "start_y", "end_x", "end_y")
    else:
        return action

    restored = action.copy()
    for key in keys:
        axis = 0 if key.endswith("x") else 1
        original, sent = original_size[axis], sent_size[axis]
        coordinate = round(float(action[key]) * original / sent)
        restored[key] = max(0, min(original - 1, coordinate))
    return restored

def qi_request(messages: list, metadata: dict, session_id: str) -> dict:
    """调用 QI，返回本轮动作（dict，含 action_type）。

    AK 签名 + Agent API Key + Instance ID 鉴权；session_id 贯穿一个任务。
    """
    body = json.dumps({
        "model": "",
        "temperature": TEMPERATURE,
        "messages": messages,
        "metadata": metadata,
        "tools": [],
        "stream": False,
    }, ensure_ascii=False).encode("utf-8")

    request_id = f"round-{uuid.uuid4().hex}"
    # data=body 直接发送已签名的字节，不能再次 JSON 序列化。
    endpoint = urllib.parse.urlsplit(ENDPOINT)
    conn = http.client.HTTPSConnection(endpoint.hostname, endpoint.port, timeout=300)
    try:
        # urllib 会把 X-QI-* 改为 X-Qi-*；直接发送以保留网关要求的头名称。
        conn.request("POST", endpoint.path or "/", body=body,
                     headers=sign_headers(body, session_id, request_id, stream=False))
        resp = conn.getresponse()
        raw = resp.read()
        if resp.status >= 400:
            detail = raw.decode("utf-8", errors="replace")
            for name in ("QI_AK_ID", "QI_AK_SECRET", "GUI_API_KEY", "GUI_INSTANCE_ID", "QI_STS_TOKEN"):
                value = os.environ.get(name)
                if value:
                    detail = detail.replace(value, "[redacted]")
            raise RuntimeError(f"QI HTTP {resp.status}: {detail}")
        data = json.loads(raw)
    finally:
        conn.close()

    arguments = data["choices"][0]["message"]["tool_calls"][0]["function"]["arguments"]
    return json.loads(arguments)

# ======================================================================
# 2. ADB 执行器：把 QI 的动作落到设备上
# ======================================================================
class AdbExecutor:
    def __init__(self, device: str):
        self.device = device

    def adb(self, *args: str, binary: bool = False, check: bool = False,
            timeout: float | None = None):
        out = subprocess.run(["adb", "-s", self.device, *args], capture_output=True,
                             check=check, timeout=timeout)
        return out.stdout if binary else out.stdout.decode(errors="replace").strip()

    def available_apps(self) -> list[str]:
        """查询当前设备，返回 APP_MAP 中已安装的 App 名称。"""
        output = self.adb("shell", "pm", "list", "packages", check=True, timeout=30)
        installed = {line.removeprefix("package:").strip() for line in output.splitlines()
                     if line.startswith("package:")}
        return [name for name, package in APP_MAP.items() if package in installed]

    def screenshot(self) -> bytes:
        return self.adb("exec-out", "screencap", "-p", binary=True)

    def foreground_package(self) -> str | None:
        """当前前台 App 的包名：从 dumpsys 里抓 `包名/Activity` token。"""
        out = self.adb("shell", "dumpsys", "activity", "activities")
        for line in out.splitlines():
            if "mResumedActivity" in line or "mFocusedApp" in line:
                m = re.search(r"([A-Za-z][A-Za-z0-9_.]*)/[A-Za-z0-9_.$]+", line)
                if m:
                    return m.group(1)
        return None

    def execute(self, action: dict) -> str:
        """执行一个 QI 动作，返回简短状态字符串。"""
        t = action["action_type"]
        if t == "click":
            self.adb("shell", "input", "tap", str(action["x"]), str(action["y"]))
        elif t == "double_click":
            x, y = str(action["x"]), str(action["y"])
            self.adb("shell", "input", "tap", x, y)
            time.sleep(0.1)
            self.adb("shell", "input", "tap", x, y)
        elif t == "long_press":
            x, y = str(action["x"]), str(action["y"])
            self.adb("shell", "input", "swipe", x, y, x, y, "1000")
        elif t == "drag":
            self.adb("shell", "input", "swipe",
                     str(action["start_x"]), str(action["start_y"]),
                     str(action["end_x"]), str(action["end_y"]), "400")
        elif t == "type":
            b64 = base64.b64encode(action["text"].encode()).decode()
            self.adb("shell", "am", "broadcast", "-a", "ADB_INPUT_B64", "--es", "msg", b64)
        elif t == "open":
            self.adb("shell", "monkey", "-p", resolve_package(action["text"]),
                     "-c", "android.intent.category.LAUNCHER", "1")
        elif t == "system_button":
            key = {"back": "KEYCODE_BACK", "home": "KEYCODE_HOME",
                   "enter": "KEYCODE_ENTER", "menu": "KEYCODE_MENU"}[action["button"]]
            self.adb("shell", "input", "keyevent", key)
        elif t == "wait":
            time.sleep(action.get("duration", 1))
        return f"{t} ok"

# ======================================================================
# 3. 主循环：截图 → 请求 QI → 执行动作 → 下一轮
# ======================================================================
def run_task(executor: AdbExecutor, task: str, apps: list, max_steps: int, delay: float):
    session_id = f"sess-{uuid.uuid4().hex[:16]}"
    print(f"session: {session_id} | task: {task} | apps: {apps}")

    # next_text：下一轮 user 消息里可选携带的一段文本。仅两种情况写入：
    #   1) open 后：前台 App 校验结果（已经/未成功打开 xx）；
    #   2) take_over 恢复后：用户输入文本，或默认「用户已经完成操作，请继续执行」。
    next_text = None

    for step in range(1, max_steps + 1):
        image_url, original_size, sent_size = prepare_screenshot(executor.screenshot())

        # 每轮只发一条 user 消息 + 一张当前截图，多轮上下文由 QI 按 session_id 维护。
        # 首轮 text 是任务；后续轮仅在需要时带 next_text。
        text = task if step == 1 else next_text
        content = ([{"type": "text", "text": text}] if text else [])
        content.append({"type": "image_url", "image_url": {"url": image_url}})
        messages = [{"role": "user", "content": content}]
        metadata = {"available_apps": apps} if step == 1 else {}
        next_text = None  # 本轮已消费，重置

        action = qi_request(messages, metadata, session_id)
        action = restore_action_coordinates(action, original_size, sent_size)
        action_type = action["action_type"]
        print(f"[step {step}] {action_type}: {action}")

        if action_type == "terminate":  # 任务结束
            print(f"完成 status={action.get('status')} answer={action.get('answer')}")
            return

        if action_type == "take_over":
            # 阻塞等待用户输入。有输入则回传该文本，否则用默认继续文案。
            print(f"需要人工介入：{action.get('text')}")
            user_input = input(">>> 请输入补充信息后回车继续（直接回车表示已完成操作）：").strip()
            next_text = user_input or "用户已经完成操作，请继续执行"
            print(f"已提交：{next_text}")
            continue

        executor.execute(action)
        time.sleep(delay)

        # open 动作后校验前台 App 是否已是目标，结果作为下一轮的文本回传。
        if action_type == "open":
            name = (action.get("text") or "").strip()
            ok = executor.foreground_package() == resolve_package(name)
            next_text = f"已经成功打开{name}" if ok else f"未成功打开{name}"
            print(f"前台校验：{next_text}")

    print(f"达到最大步数 {max_steps}")

def main():
    p = argparse.ArgumentParser(description="QI GUI Agent 最小接入 demo")
    p.add_argument("--task", required=True, help="任务指令，如：打开设置进入 WiFi 页面")
    p.add_argument("--app", nargs="*", default=[], help="设备可用 App 名列表，真机模式留空则自动探测")
    p.add_argument("--device", default=os.environ.get("ANDROID_DEVICE", "emulator-5554"))
    p.add_argument("--max-steps", type=int, default=100)
    p.add_argument("--step-delay", type=float, default=1.2)
    args = p.parse_args()
    try:
        validate_config()
    except ValueError as exc:
        p.error(str(exc))

    executor = AdbExecutor(args.device)
    try:
        apps = args.app or executor.available_apps()
    except (OSError, subprocess.SubprocessError) as exc:
        stderr = getattr(exc, "stderr", None)
        detail = stderr.decode(errors="replace").strip() if stderr else str(exc)
        p.exit(1, f"无法查询设备 {args.device} 的已安装 App：{detail}\n")
    run_task(executor, args.task, apps, args.max_steps, args.step_delay)

if __name__ == "__main__":
    main()
```

### 排查与重试

- 未建立 SSE 时按 HTTP 状态和错误码表处理；AccessKey 签名认证与 Customer 实例密钥校验不同。
- 参数错误、服务未开通、额度不足、会话冲突，先修正条件再调用。图片过期或无权限时更换有效链接。
- 流内错误按 qi\_event.retryable 判断是否退避重试；不要把 HTTP 200 或 \[DONE] 单独当作成功。
- 反馈问题时提供时间、接口名、qi\_request\_id 和网关 RequestId，不要提供密钥、完整签名链接或敏感输入。

## 返回示例

```json
{
  "requestId": "request-20260904-001"
}
```

## 错误码

| HTTP 状态码 | 错误码                     | 错误信息                                                          | 说明                            |
| -------- | ----------------------- | ------------------------------------------------------------- | ----------------------------- |
| `400`    | `ContentFilter`         | Your request was blocked by the content filter.               | 请求被内容安全策略拦截。                  |
| `400`    | `InvalidParameter`      | The specified request parameter is invalid.                   | 指定的请求参数无效。                    |
| `401`    | `InvalidApiKey`         | The specified API key is invalid.                             | 指定的 API Key 无效。               |
| `403`    | `ServiceNotActivated`   | The required Agent service is not activated for this account. | 当前账号未开通所请求的 Agent 服务，无法调用该接口。 |
| `404`    | `InvalidAgentNotFound`  | The published Agent is not found.                             | 未找到已发布的 Agent。                |
| `409`    | `IdempotencyConflict`   | The request ID was reused with different request parameters.  | 请求 ID 被用于不同的请求参数。             |
| `409`    | `SessionConflict`       | The session state conflicts with the request.                 | Session 状态与请求冲突。              |
| `413`    | `RequestEntityTooLarge` | The request body is too large.                                | 请求体过大。                        |
| `429`    | `QuotaExhausted`        | The Agent trial quota has been exhausted.                     | Agent 试用额度已耗尽。                |
| `500`    | `InternalError`         | An internal server error occurred.                            | 发生内部服务器错误。                    |
| `502`    | `UpstreamServiceError`  | The upstream Agent runtime failed to complete the request.    | 上游 Agent Runtime 未能完成请求。      |
| `503`    | `ServiceUnavailable`    | The service is temporarily unavailable.                       | 服务暂时不可用。                      |

## 变更历史

| 日期         | API 版本     | 变更内容                                                                                       |
| ---------- | ---------- | ------------------------------------------------------------------------------------------ |
| 2026-11-11 | 2026-08-31 | 更新 ADB 接入 Demo，支持自动筛选已安装 App、截图等比缩小及动作坐标还原，移除单图模式。Demo 默认温度设为 0，并补充 temperature 默认为 0 的说明。 |
| 2026-10-23 | 2026-08-31 | 补充动作空间和客户接入最小实现。                                                                           |
| 2026-09-15 | 2026-08-31 | 首次发布流式调用文档。                                                                                |
