# 知识库 · 设备自动化平台（auto_control）接入说明

> 读者：StaffDeck 数字员工（外部 Agent）。
> 目的：让你知道**能做什么、怎么调、什么不能做**，从而安全地代为操作手机设备。
> 版本：2026-09-10 | 权威工具清单以 `doc/MCP.md` 为准，配置以 `mcp_server/config.py` 为准。

---

## 1. 这个平台是什么

一台**安卓设备自动化中台**：管理一批手机（网络 `IP:5555` 或 USB 串号），支持定时任务、步骤编排、看屏/操作，以及本知识库要用的 **MCP 工具**。

- 平台本体：Web 服务（默认 `http://<host>:18050`），提供任务/分组/设备/看板等管理能力。
- 你能用的入口：**MCP Server（推荐）**，它把平台已有的设备能力封装成 19 个工具。

---

## 2. 接入方式

### 2.1 首选：MCP（HTTP / streamable）
- 地址：`http://<host>:8033/mcp`（FastMCP，`transport="http"`）。
- 调用方式：支持 MCP 的客户端直接连；工具名即 `de_*`（见 §3）。
- **鉴权现状**：MCP 层**无独立鉴权**——它自身用 `MCP_PLATFORM_USER/PASS` 登录平台（会话 + CSRF 由服务端内部处理，你不用管）。因此**谁能访问 8033 谁就能操控设备**，务必只在内网/Tailscale 内暴露，不要裸露公网。
- **审计**：每次调用（含只读）都会写一行 JSON 审计（工具、serial、参数摘要、结果）。

### 2.2 备选：平台 REST（`http://<host>:18050`）
仅在你不支持 MCP 时使用。认证是「表单登录 → 会话 Cookie + `X-CSRF-Token`」，无 API Token，接入成本较高。常用端点见 §9。

### 2.3 服务端配置（由部署方设置，你只需知道含义）

| 变量 | 默认 | 含义 / 对你的影响 |
|---|---|---|
| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听地址与端口 |
| `MCP_ALLOW_WRITE` | `0`（**只读**） | `1` 才允许点按/滑动/输入等**写操作**；为 0 时写工具返回 `write_disabled` |
| `MCP_ALLOWED_SERIALS` | 空 | 逗号分隔设备白名单；非空时只允许这些 serial。**注意：为空时当前代码只校验 serial 非空，并不自动限平台设备池**——如需收紧请让部署方配置白名单 |
| `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址 |
| `MCP_PLATFORM_USER` / `_PASS` | `admin` / 空 | 服务端登录平台用，与你无关 |
| `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
| `MCP_SCREENSHOT_WIDTH` / `MCP_JPEG_QUALITY` | `540` / `70` | 截图缩放宽/JPEG 质量（见坐标约定） |
| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计文件路径 |

启动（部署方操作，供排障参考）：
- 220 生产容器：`scripts/start.sh` 会自动后台拉起（`MCP_ENABLED=0` 可关）。
- 本机/手工：`MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> python -m mcp_server.mcp_server`

---

## 3. 工具清单（19 个 `de_*`）

### 只读（观测，不触发设备占用锁；任务运行中也安全）
| 工具 | 入参 | 返回要点 | 用途 |
|---|---|---|---|
| `de_list_devices()` | — | `[{serial, model, online, worker_status, foreground_app}]` | 先看有哪些设备可用 |
| `de_screenshot(serial)` | serial | `{image(JPEG base64), width, height, native_size, screen_state}` | 看当前屏（**必须**先截图才能坐标点按） |
| `de_ui_tree(serial, limit=150)` | serial, limit | `{count, elements:[{text,id,desc,class,clickable,bounds}]}` | 拿可点击元素（**优先用它定位**） |
| `de_ocr(serial)` | serial | `{count, texts:[{text,score}]}` | UI 树里没有的渲染文字（WebView/图片） |
| `de_foreground_app(serial)` | serial | `{foreground_app: pkg}` | 当前前台 App |
| `de_list_apps(serial, keyword?)` | serial, keyword | `{count, packages:[pkg]}` | 找包名（配合 `de_open_app`） |
| `de_read_clipboard(serial)` | serial | `{clipboard}` | 读剪贴板 |
| `de_list_tasks()` | — | 平台任务计划列表 | 只读了解平台任务（**不能增改**） |

### 写操作（会先检查设备是否被任务占用；`MCP_ALLOW_WRITE=1` 才可用）
| 工具 | 入参 | 说明 |
|---|---|---|
| `de_tap_text(serial, text)` | serial, text | **首选**语义点击：按屏上文字找并点（UI 树→OCR 兜底）；找不到返回 `text_not_found` |
| `de_tap_element(serial, by, value, index=1)` | by=`text/id/desc/text_contains/desc_contains`, value, index | 元素定位点击（配合 `de_ui_tree`） |
| `de_tap(serial, x, y)` | serial, x, y | 坐标点击（截图坐标系，自动吸附到最近可点元素；返回 `snapped`/`label`） |
| `de_swipe(serial, x1,y1,x2,y2, duration?)` | 坐标 | 滑动 |
| `de_press_key(serial, key)` | key=`back/home/enter/menu/recent/delete` | 按键 |
| `de_type_text(serial, text)` | serial, text | 输入文字（中文/引号/换行可用） |
| `de_set_clipboard(serial, text)` | serial, text | 写剪贴板 |
| `de_open_app(serial, package)` | serial, package | 冷启动 App（adb monkey） |
| `de_stop_app(serial, package)` | serial, package | 强制结束 App |
| `de_wake(serial)` / `de_sleep(serial)` | serial | 亮屏解锁 / 息屏（走平台 `/api/device/screen_all`） |

> 平台级工具（**任务创建/修改/启停、分组、设备池管理、备份等**）**目前没有 MCP 工具**，只有上面这些设备能力；需要它们时请通过 REST（§9）或在平台 Web 后台操作。

---

## 4. 通用调用约定

### 4.1 设备标识 `serial`
- 网络设备：`IP:5555`（如 `100.100.10.13:5555`、`192.168.20.206:5555`）。
- USB 设备：纯串号（无冒号，如 `ZY322XXXX`）。
- 用 `de_list_devices()` 获取当前可用清单，**不要凭空猜 serial**。

### 4.2 坐标空间（重要）
- `de_screenshot` 返回的是**缩放图（≤540px 宽）+ `native_size`（原生分辨率）**。
- `de_tap` / `de_swipe` 的坐标用**截图坐标系（display 空间）**，服务端按最近一次截图比例换算原生。
- **必须先 `de_screenshot` 再坐标操作**，否则报「请先执行 de_screenshot」。
- 屏幕可能旋转/滚动，坐标随时会变——**优先文字/元素定位，坐标仅兜底**。

### 4.3 设备占用锁（busy）
- 写工具执行前会检查该设备是否有平台任务在跑：`running`/`connecting` → 返回 **`device_busy`**（“AI 不与任务抢设备”）。此时**换设备或等待**，不要硬重试。
- 只读工具（截图/UI树/OCR/列表）不受此限制。

### 4.4 错误码
| 错误 | 含义 | 应对 |
|---|---|---|
| `write_disabled` | 服务端未开写门控 | 告知部署方开 `MCP_ALLOW_WRITE=1` |
| `device_busy` | 设备正被任务占用 | 换设备 / 等任务结束 |
| `device_offline` | 设备不可达 | 换设备；报运维 |
| `device_not_allowed` | 不在白名单 | 换设备；让部署方加白名单 |
| `text_not_found` | 屏上没有该文字 | 截图确认；改用 `de_ui_tree`/`de_ocr` |
| `platform_unavailable` | 平台不可达 | 稍后重试；报运维 |
| `invalid_param` | 参数不合法 | 修参数 |

---

## 5. 推荐操作模式（务必遵守，能显著提高成功率）

1. **文字语义点击优先**：`de_tap_text("关注")` ＞ `de_ui_tree` 找元素 + `de_tap_element` ＞ `de_tap` 坐标兜底。
2. **每关键步后截图验证**：操作是否生效看截图/UI 树，别连续盲点。
3. **不重复同坐标**：点击后画面无变化，禁止反复点同一坐标（多数 App 会误触）。
4. **先确认前台与页面**：`de_foreground_app` / 截图确认在正确页面再操作。
5. **一次一个明确目标**：拆成小步，每步可验证。

### 常见配方
- **看视频养号（示意）**：`de_list_devices` → 选设备 → `de_open_app(pkg)` → 循环〔`de_screenshot` 确认在视频页 → 等待 → `de_swipe` 上滑〕→ 结束 `de_stop_app`。
- **打开指定 App**：`de_list_apps(keyword)` 拿包名 → `de_open_app(package)` → 截图确认首页。
- **输入文字**：`de_tap_text` 或 `de_tap_element` 点输入框 → `de_type_text` → 截图确认。
- **巡检截图**：`de_screenshot` + `de_foreground_app` + `de_ocr`，只读汇报。

---

## 6. 红线与安全（**不可违反**）

1. **绝不 `adb kill-server`、绝不 `adb disconnect`**（会断开所有设备共享的 adb 通道，影响全部运行中任务）。你也不需要这些操作。
2. **不抢任务设备**：遇到 `device_busy` 就避开。
3. **写操作前先确认**：不确定后果的操作（发送评论/私信、删除、支付类）**不要执行**，先截图回报请人工确认。
4. **不做破坏性动作**：卸载应用、清除数据、改系统设置等一律不做。
5. **留痕**：你的每次调用都进审计，请让动作与目标一致。
6. **隐私**：不要把设备上读到的个人信息/凭据复述或外传。

---

## 7. 当前边界（别越界期待）

- MCP **没有任务创建/修改/启停**（只有只读 `de_list_tasks`）。
- MCP **无独立鉴权**（靠网络隔离），不要假设有 token。
- `MCP_ALLOWED_SERIALS` 为空时**不会**自动限制为平台设备池（设计语义未实现）。
- 平台 REST 的 CSRF 校验在当前版本可能未强制（按端点契约使用即可）。

---

## 8. 相关文档

- 工具手册（逐工具参数/返回/示例）：`doc/MCP.md`
- MCP 设计/分层与现状对照：`doc/MCP_DESIGN.md`
- 平台接口目录：`doc/API.md`
- AI 生成任务（规划，未实现）：`doc/AI_TASK_GEN.md`