butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e67764589af68f08619b5ac7e18b2112fb1c1bd
auto_control/doc/staffdeck/KNOWLEDGE_BASE.md
T
butubb 4e67764589 docs: 新增 StaffDeck 数字员工知识库与岗位说明 
- doc/staffdeck/KNOWLEDGE_BASE.md:接入方式(MCP http://<host>:8033/mcp 首选/REST 备选)、服务端配置项、19 个 de_* 工具清单(读写分类)、通用约定(serial/坐标空间/busy 占用锁/错误码)、推荐操作模式与常见配方、红线、当前边界
- doc/staffdeck/JOB_SPEC.md:岗位描述、看板摘要(指标口径+文本/JSON 汇报模板)、岗位执行约束(L0-L3 授权分级/硬红线/操作规范/失败重试/审计)、SOP 工作流、应拒绝与转人工清单
- doc/DEVELOPMENT.md:§7 文档索引与 §5.6 同步映射登记这两份
2026-09-10 10:28:53 +08:00

9.3 KiB
Raw Blame History

知识库 · 设备自动化平台（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
Reference in New Issue View Git Blame Copy Permalink