Android设备远程控制(dtnsbot)

dtnsbot安卓设备-无障碍服务 HTTP API 接口文档

基础信息

  • 基础URL（base_url）: http://[设备IP]:58082 或 base_url （默认的设备IP为: 127.0.0.1 亦即默认的base_url为 http://127.0.0.1:58082 )
  • 所有请求方式: GET/POST
  • 端点格式要求： 【端点】务必使用完整的http-url-api调用
  • 响应格式: JSON (部分命令返回纯文本)

目录

  1. 系统控制命令
  2. 应用操作命令
  3. 坐标点击命令
  4. 手势滑动命令
  5. 截图功能命令
  6. UI信息命令
  7. 语音API命令
  8. 配置管理命令
  9. 收藏悬浮窗命令
  10. 识图机灵命令
  11. GPS定位命令
  12. 文本操作命令
  13. 命令执行器
  14. 辅助命令
  15. 错误码说明
  16. 文件上传下载
  17. poplang脚本与编程

1. 系统控制命令

1.1 返回主页

  • 命令: home
  • 描述: 模拟按下Home键，返回系统桌面
  • 示例: 
    GET /api/?command=home
  • 响应: "返回主页"

1.2 返回上一级

  • 命令: back
  • 描述: 模拟按下返回键
  • 示例: 
    GET /api/?command=back
  • 响应: "执行返回"

1.3 显示最近任务

  • 命令: recent
  • 描述: 显示最近使用的应用列表
  • 示例: 
    GET /api/?command=recent
  • 响应: "显示最近任务"

1.4 打开通知栏

  • 命令: notifications
  • 描述: 下拉打开通知栏
  • 示例: 
    GET /api/?command=notifications
  • 响应: "显示通知"

1.5 电源菜单

  • 命令: power
  • 描述: 显示电源菜单（关机、重启等）
  • 示例: 
    GET /api/?command=power
  • 响应: "电源菜单"

1.6 锁屏

  • 命令: lock
  • 描述: 锁定屏幕
  • 示例: 
    GET /api/?command=lock
  • 响应: "锁屏"

1.7 分屏模式

  • 命令: split
  • 描述: 进入分屏模式（需要 Android 7.0+）
  • 示例: 
    GET /api/?command=split
  • 响应: "分屏模式"

2. 应用操作命令

2.1 打开应用

  • 命令: open_[应用名]

  • 描述: 打开指定的应用

  • 参数:

    • appName: 应用名称（在URL路径中）

  • 示例: 

    GET /api/?command=open_设置
GET /api/?command=open_微信

  • 响应: "正在打开 微信"

2.2. 获取应用列表

获取设备上所有已安装的可启动应用列表。

请求

GET /api/?command=get_apps

或

POST /api/
Content-Type: application/x-www-form-urlencoded

command=get_apps

响应示例

{
  "status": "success",
  "count": 156,
  "apps": [
    {
      "name": "微信",
      "packageName": "com.tencent.mm",
      "activityName": "com.tencent.mm.ui.LauncherUI"
    },
    {
      "name": "设置",
      "packageName": "com.android.settings",
      "activityName": "com.android.settings.Settings"
    },
    {
      "name": "Chrome浏览器",
      "packageName": "com.android.chrome",
      "activityName": "com.google.android.apps.chrome.Main"
    }
  ]
}

响应字段说明

字段 类型 说明
status string 状态：success 或 error
count number 应用总数
apps array 应用列表数组
├─ name string 应用显示名称
├─ packageName string 应用包名
└─ activityName string 启动 Activity 完整类名

错误响应

{
  "status": "error",
  "message": "获取应用列表失败: 权限不足"
}

3. 坐标点击命令

3.1 点击坐标

  • 命令: click_at_[x],[y]
  • 描述: 在屏幕指定坐标执行点击操作
  • 参数: 坐标值在命令路径中
  • 示例: 
    GET /api/?command=click_at_500,800
  • 响应: "坐标点击命令已发送: (500, 800)"

3.2 长按坐标

  • 命令: long_click_at_[x],[y]
  • 描述: 在屏幕指定坐标执行长按操作（1秒）
  • 示例: 
    GET /api/?command=long_click_at_500,800
  • 响应: "长按命令已发送: (500, 800)"

3.3 测试点击

  • 命令: test_click
  • 描述: 测试点击屏幕中心点
  • 示例: 
    GET /api/?command=test_click
  • 响应: "测试点击命令已发送"

3.4 获取屏幕信息

  • 命令: screen_info
  • 描述: 获取屏幕分辨率信息
  • 示例: 
    GET /api/?command=screen_info
  • 响应: "屏幕分辨率: 1080x2340"

4. 手势滑动命令

4.1 左滑

  • 命令: swipe_left
  • 描述: 从屏幕中心向左滑动
  • 示例: 
    GET /api/?command=swipe_left
  • 响应: {"status": "success", "direction": "left"}

4.2 右滑

  • 命令: swipe_right
  • 描述: 从屏幕中心向右滑动
  • 示例: 
    GET /api/?command=swipe_right
  • 响应: {"status": "success", "direction": "right"}

4.3 上滑

  • 命令: swipe_up
  • 描述: 从屏幕中心向上滑动
  • 示例: 
    GET /api/?command=swipe_up
  • 响应: {"status": "success", "direction": "up"}

4.4 下滑

  • 命令: swipe_down
  • 描述: 从屏幕中心向下滑动
  • 示例: 
    GET /api/?command=swipe_down
  • 响应: {"status": "success", "direction": "down"}

4.5 自定义滑动

  • 命令: swipe_at_[startX],[startY],[endX],[endY],[duration]
  • 描述: 从起点到终点执行自定义滑动
  • 参数:
    • startX: 起始X坐标
    • startY: 起始Y坐标
    • endX: 结束X坐标
    • endY: 结束Y坐标
    • duration: 持续时间（毫秒，可选，默认500ms）
  • 示例: 
    GET /api/?command=swipe_at_500,800,200,800,1000
  • 响应: {"status": "success", "action": "swipe"}

5. 截图功能命令

5.1 拍摄截图

  • 命令: screenshot
  • 描述: 触发截图操作
  • 示例: 
    GET /api/?command=screenshot
  • 响应: "截图处理中..."

5.2 获取截图结果（Base64）

  • 命令: get_screenshot_result
  • 描述: 获取上次截图的Base64编码数据
  • 示例: 
    GET /api/?command=get_screenshot_result
  • 响应 (成功):
    {
  "status": "success",
  "type": "screenshot",
  "width": 1080,
  "height": 2340,
  "format": "PNG",
  "data_size": 102400,
  "data": "base64编码的图片数据",
  "timestamp": 1647859200000
}
  • 响应 (失败):
    {
  "status": "error",
  "message": "没有可用的截图，请先执行截图命令",
  "timestamp": 1647859200000
}

5.3 直接获取截图

  • 命令: get_screenshot_direct
  • 描述: 直接获取当前屏幕截图（压缩为WEBP格式）
  • 参数:
    • quality: 图片质量 0-100（可选，默认30）
  • 示例: 
    GET /api/?command=get_screenshot_direct&quality=60
  • 响应 (成功):
    {
  "status": "success",
  "type": "screenshot",
  "width": 720,
  "height": 1560,
  "screen_width": 1080,
  "screen_height": 2340,
  "original_width": 1080,
  "original_height": 2340,
  "scale": 1.5,
  "format": "WEBP",
  "data_size": 51200,
  "data": "base64编码的图片数据",
  "timestamp": 1647859200000
}

5.4 获取截图OCR结果

  • 命令: get_screenshot_ocr
  • 描述: 对当前截图进行OCR文字识别

请求参数

参数名 类型 必填 描述
command string 是 固定值：get_screenshot_ocr

请求示例

GET /api/?command=get_screenshot_ocr

响应格式

返回JSON格式的数据，包含截图OCR识别的结果。

响应参数

参数名 类型 描述
status string 状态值："success"（成功）或 "failed"（失败）
type string 固定值："screenshot_ocr"
data object/string 成功时：OCR识别结果对象；失败时：错误信息
timestamp long Unix时间戳（毫秒）

成功响应示例

{
  "status": "success",
  "type": "screenshot_ocr",
  "data": {
    "status": "success",
    "type": "screenshot_ocr",
    "data": {
      "success": true,
      "text": "识别出的文字内容...",
      "confidence": 88,
      "processingTime": "1655ms",
      "language": "eng+chi_sim",
      "details": {
        "blocks": 1,
        "paragraphs": 1,
        "lines": 7,
        "words": 55
      },
      "hocr": "<div class='ocr_page'...>...</div>",
      "tsv": "1\t1\t0\t0\t0\t0\t0\t0\t1200\t2000\t-1\t\n...",
      "box": null
    },
    "timestamp": 1773585652996
  },
  "timestamp": 1773585652996
}

失败响应示例

{
  "status": "failed",
  "type": "screenshot_ocr",
  "data": null,
  "timestamp": 1773585652996
}

OCR结果对象字段说明

字段名 类型 描述
success boolean OCR识别是否成功
text string 识别出的完整文字内容
confidence int 识别置信度（0-100）
processingTime string 处理耗时（如"1655ms"）
language string 使用的OCR语言模型
details object 识别详情（块数、段落数、行数、词数）
hocr string hOCR格式的识别结果
tsv string TSV格式的识别结果
box object 文本框坐标信息（可能为null）

功能流程

  1. 调用takeScreenshotForOCR()方法截图
  2. 调用recognizeImageWithOCRResult()方法进行OCR识别
  3. 如果主方法失败，会尝试一次重试
  4. 返回识别结果或失败信息

注意事项

  • 需要Android 7.0+系统支持截图功能
  • OCR API服务器地址通过配置项OCR_API_BASE_URL设置
  • 默认使用eng+chi_sim（中英文）语言模型
  • 截图会压缩为JPEG格式（质量80%）后上传
  • OCR API超时时间为30秒
  • 失败时会在悬浮窗显示提示信息"❌ 图片文字识别失败"

5.5 设置截图最大尺寸

  • 命令: set_screenshot_max_size
  • 描述: 设置截图的最大宽度和高度
  • 参数:
    • width: 最大宽度
    • height: 最大高度
  • 示例: 
    GET /api/?command=set_screenshot_max_size&width=800&height=1200
  • 响应:
    {
  "status": "success",
  "message": "设置成功"
}

6. UI信息命令

6.1 获取UI节点信息

  • 命令: get_uinfo
  • 描述: 获取当前窗口的UI节点信息
  • 示例: 
    GET /api/?command=get_uinfo
  • 响应: "UI信息已获取，共 42 个节点"

6.2 获取UI信息结果

  • 命令: get_uiinfo_result
  • 描述: 获取上次获取的UI节点信息详情
  • 示例: 
    GET /api/?command=get_uiinfo_result
  • 响应:
    {
  "status": "success",
  "type": "ui_info",
  "timestamp": 1647859200000,
  "data": {
    "packageName": "com.android.settings",
    "className": "android.widget.FrameLayout",
    "nodes": [...]
  }
}

6.3 获取布局信息

  • 命令: dump_layout
  • 描述: 获取当前窗口的布局信息（文本格式）
  • 示例: 
    GET /api/?command=dump_layout
  • 响应: "布局信息已获取"

6.4 获取布局信息结果

  • 命令: get_layout_result
  • 描述: 获取上次获取的布局信息详情
  • 示例: 
    GET /api/?command=get_layout_result
  • 响应:
    {
  "status": "success",
  "type": "layout_info",
  "timestamp": 1647859200000,
  "data": "布局信息文本内容..."
}

7. 语音API命令

7.1 语音识别

  • 命令: speech_recognize
  • 描述: 对上传的音频文件进行语音识别
  • 请求方式: POST
  • 参数:
    • audio: base64编码的WAV音频数据（必填）
    • language: 语言代码（可选，默认zh-CN）
      • zh-CN - 中文
      • en-US - 英文
      • ja-JP - 日语
      • ko-KR - 韩语
  • 示例 (POST):
    POST /api/
Content-Type: multipart/form-data

command=speech_recognize&audio=[base64音频数据]&language=zh-CN
  • 响应 (成功):
    {
  "status": "success",
  "message": "识别出的文字内容",
  "language": "zh-CN",
  "timestamp": 1647859200000
}
  • 响应 (失败):
    {
  "status": "error",
  "message": "语音识别失败原因",
  "timestamp": 1647859200000
}

7.2 语音合成

  • 命令: speech_synthesize
  • 描述: 将文本合成为语音
  • 参数:
    • text: 要合成的文本（必填）
    • language: 语言代码（可选，默认zh-CN）
    • voice: 语音类型（可选，默认default）
    • speed: 语速 0.5-2.0（可选，默认1.0）
  • 示例: 
    GET /api/?command=speech_synthesize&text=你好世界&language=zh-CN&speed=1.0
  • 响应 (成功):
    {
  "status": "success",
  "audio": "base64编码的WAV音频数据",
  "text": "你好世界",
  "language": "zh-CN",
  "voice": "default",
  "speed": 1.0
}
  • 响应 (失败):
    {
  "error": "语音合成失败原因"
}

8. 配置管理命令

8.1 设置配置项

  • 命令: set_config
  • 描述: 设置指定的配置项
  • 参数:
    • key: 配置键名（必填）
    • value: 配置值（必填）
  • 支持的配置键:
    • IBBOT_AGENT_BASE_URL - iBBot服务器地址
    • dtnsbot_secret_key - API认证密钥
    • OCR_API_BASE_URL - OCR服务器地址
    • system_prompt - AI角色设定提示语
    • floating_button_command - 浮窗按钮指令
    • floating_button_mode - 浮窗按钮模式
  • 示例: 
    GET /api/?command=set_config&key=IBBOT_AGENT_BASE_URL&value=http://192.168.1.100:8080
  • 响应:
    {
  "status": "success",
  "message": "配置已更新"
}

8.2 获取配置项

  • 命令: get_config
  • 描述: 获取指定的配置项或所有配置
  • 参数:
    • key: 配置键名（可选，不传则获取所有）
  • 示例 (获取单个):
    GET /api/?command=get_config&key=IBBOT_AGENT_BASE_URL
  • 响应:
    {
  "status": "success",
  "key": "IBBOT_AGENT_BASE_URL",
  "value": "http://192.168.1.100:8080"
}
  • 示例 (获取所有):
    GET /api/?command=get_config
  • 响应:
    {
  "status": "success",
  "config": {
    "IBBOT_AGENT_BASE_URL": "http://192.168.1.100:8080",
    "dtnsbot_secret_key": "xxxxxx",
    "system_prompt": "你是一个专业助手"
  }
}

8.3 重置配置

  • 命令: reset_config
  • 描述: 重置所有配置为默认值
  • 示例: 
    GET /api/?command=reset_config
  • 响应:
    {
  "status": "success",
  "message": "配置已重置为默认值"
}

8.4 设置iBBot地址

  • 命令: set_ibbot_url
  • 描述: 快捷设置iBBot服务器地址
  • 参数:
    • url: 服务器地址（必填）
  • 示例: 
    GET /api/?command=set_ibbot_url&url=http://192.168.1.100:8080
  • 响应:
    {
  "status": "success",
  "message": "iBBot地址已更新",
  "url": "http://192.168.1.100:8080"
}

8.5 设置密钥

  • 命令: set_secret_key
  • 描述: 快捷设置API密钥
  • 参数:
    • key: 密钥值（必填）
  • 示例: 
    GET /api/?command=set_secret_key&key=my_secret_key_123
  • 响应:
    {
  "status": "success",
  "message": "密钥已更新",
  "key": "my_se..."
}

8.6 设置AI角色

  • 命令: set_system_prompt
  • 描述: 设置AI角色提示语
  • 参数:
    • prompt: 角色提示语（必填）
  • 示例: 
    GET /api/?command=set_system_prompt&prompt=你是一个专业助手，请用简洁语言回答
  • 响应:
    {
  "status": "success",
  "message": "AI角色已设置",
  "prompt": "你是一个专业助手..."
}

8.7 获取AI角色

  • 命令: get_system_prompt
  • 描述: 获取当前AI角色提示语
  • 示例: 
    GET /api/?command=get_system_prompt
  • 响应:
    {
  "status": "success",
  "prompt": "你是一个专业助手..."
}

8.8 配置帮助

  • 命令: config_help
  • 描述: 获取配置管理帮助信息
  • 示例: 
    GET /api/?command=config_help
  • 响应: 文本形式的帮助信息

9. 收藏悬浮窗命令

9.1 显示收藏悬浮窗

  • 命令: 显示收藏
  • 描述: 显示收藏悬浮窗按钮
  • 示例: 
    GET /api/?command=显示收藏
  • 响应: "收藏悬浮窗已显示"

9.2 隐藏收藏悬浮窗

  • 命令: 隐藏收藏
  • 描述: 隐藏收藏悬浮窗按钮
  • 示例: 
    GET /api/?command=隐藏收藏
  • 响应: "收藏悬浮窗已隐藏"

9.3 切换收藏悬浮窗

  • 命令: 切换收藏
  • 描述: 切换收藏悬浮窗的显示状态
  • 示例: 
    GET /api/?command=切换收藏
  • 响应: "收藏悬浮窗已切换"

9.4 设为机灵模式

  • 命令: set_smart_mode
  • 描述: 将收藏按钮设置为机灵模式
  • 示例: 
    GET /api/?command=set_smart_mode
  • 响应:
    {
  "status": "success",
  "mode": "机灵"
}

9.5 设为收藏模式

  • 命令: set_collection_mode
  • 描述: 将收藏按钮设置为收藏模式
  • 示例: 
    GET /api/?command=set_collection_mode
  • 响应:
    {
  "status": "success",
  "mode": "收藏"
}

9.6 切换模式

  • 命令: toggle_collection_mode 或 切换模式
  • 描述: 切换收藏按钮的工作模式
  • 示例: 
    GET /api/?command=toggle_collection_mode
  • 响应:
    {
  "status": "success",
  "mode": "机灵"
}

9.7 获取当前模式

  • 命令: get_collection_mode
  • 描述: 获取收藏按钮的当前模式
  • 示例: 
    GET /api/?command=get_collection_mode
  • 响应:
    {
  "status": "success",
  "mode": "机灵"
}

9.8 设置浮窗指令

  • 命令: set_floating_command
  • 描述: 设置浮窗按钮点击执行的指令
  • 参数:
    • value: 指令内容
  • 示例: 
    GET /api/?command=set_floating_command&value=图片机灵
  • 响应:
    {
  "status": "success",
  "message": "浮窗指令已设置为: 图片机灵",
  "command": "图片机灵"
}

9.9 获取浮窗指令

  • 命令: get_floating_command
  • 描述: 获取当前浮窗按钮指令
  • 示例: 
    GET /api/?command=get_floating_command
  • 响应:
    {
  "status": "success",
  "command": "图片机灵"
}

10. 识图机灵命令

10.1 识图机灵

  • 命令: image_smart 或 识图机灵
  • 描述: 截图并进行OCR识别，然后生成智能回复
  • 参数:
    • lang: OCR语言（可选，默认eng+chi_sim）
      • eng+chi_sim - 中英文
      • chi_sim - 简体中文
      • eng - 英文
      • jpn - 日文
      • kor - 韩文
  • 示例: 
    GET /api/?command=识图机灵&lang=eng+chi_sim
  • 响应 (立即):
    {
  "status": "accepted",
  "message": "识图机灵任务已接受",
  "task_id": "img_smart_1647859200000",
  "timestamp": 1647859200000
}

10.2 图片机灵

  • 命令: 图片机灵
  • 描述: 同识图机灵
  • 示例: 
    GET /api/?command=图片机灵
  • 响应: 同上

10.3 万能机灵

  • 命令: 万能机灵
  • 描述: 跟图片机灵一样
  • 示例: 
    GET /api/?command=万能机灵
  • 响应: 同上

10.3.2 全屏机灵

  • 命令: 全屏机灵
  • 描述: 滚动屏幕截图OCR识别并进行AI回复（即图片机灵只能截屏当前屏幕、全屏机灵可以滚动截屏）
  • 示例: 
    GET /api/?command=全屏机灵
  • 响应: 同上

10.3.2.1 全屏机灵（参数版本）

命令格式
/api/?command=full_smart_{滚动高度},{等待时间}
参数说明
参数 类型 说明 默认值
滚动高度 整数 每次滚动距离（像素） 屏幕高度的70%
等待时间 整数 滚动后等待时间（毫秒） 5000
使用示例
示例 说明
full_smart 使用默认参数
full_smart_1000,3000 滚动1000px，等待3000ms
full_smart_500,2000 滚动500px，等待2000ms
full_smart_800,1000 滚动800px，等待1000ms
支持的别名命令
  • 全屏机灵
  • 滚动机灵
  • 长文机灵
  • full_screen_smart
  • scroll_smart
响应示例
{
    "status": "accepted",
    "message": "全屏机灵任务已接受，滚动高度: 1000px，等待时间: 3000ms",
    "task_id": "full_smart_1734567890123"
}
完整请求示例
http://192.168.1.49:58082/api/?command=full_smart_1000,3000
注意事项
  1. 任务异步执行，完成后结果自动复制到剪贴板
  2. 滚动高度建议范围：100-2000px
  3. 等待时间建议范围：500-10000ms
  4. 执行时会显示进度悬浮窗

10.4 获取任务状态

  • 命令: get_task_status
  • 描述: 获取异步任务的处理状态
  • 参数:
    • task_id: 任务ID
  • 示例: 
    GET /api/?command=get_task_status&task_id=img_smart_1647859200000
  • 响应:
    {
  "status": "completed",
  "task_id": "img_smart_1647859200000",
  "message": "任务处理完成",
  "timestamp": 1647859200000
}

11. GPS定位命令

11.1 获取当前位置

  • 命令: get_gps
  • 描述: 获取当前GPS位置信息
  • 示例: 
    GET /api/?command=get_gps
  • 响应:
    {
  "latitude": 31.2304,
  "longitude": 121.4737,
  "accuracy": 10.5,
  "time": 1647859200000,
  "provider": "gps",
  "address": "上海市浦东新区..."
}

11.2 开始定位

  • 命令: start_gps
  • 描述: 开始持续定位
  • 示例: 
    GET /api/?command=start_gps
  • 响应:
    {
  "status": "started",
  "message": "位置服务已启动，正在获取位置..."
}

11.3 停止定位

  • 命令: stop_gps
  • 描述: 停止定位服务
  • 示例: 
    GET /api/?command=stop_gps
  • 响应:
    {
  "status": "stopped",
  "message": "位置服务已停止"
}

11.4 获取定位状态

  • 命令: gps_status
  • 描述: 获取当前定位服务状态
  • 示例: 
    GET /api/?command=gps_status
  • 响应:
    {
  "status": "running",
  "location_service": "已开启",
  "formatted_location": "纬度: 31.2304, 经度: 121.4737",
  "location_data": {...}
}

12. 文本操作命令

12.1 输入文本

  • 命令: input_[文本]
  • 描述: 在当前焦点输入框中输入文本
  • 参数: 文本内容在命令路径中
  • 示例: 
    GET /api/?command=input_hello%20world
  • 响应: "正在输入: hello world"

12.2 点击文本

  • 命令: click_[文本]
  • 描述: 点击包含指定文本的UI元素
  • 参数: 文本内容在命令路径中
  • 示例: 
    GET /api/?command=click_确定
  • 响应: "正在点击: 确定"

12.3 复制到剪贴板

  • 命令: paste_[文本]
  • 描述: 将文本复制到剪贴板
  • 参数: 文本内容在命令路径中
  • 示例: 
    GET /api/?command=paste_要复制的文本
  • 响应: "正在粘贴: 要复制的文本"

12.4 获取剪贴板内容

  • 命令: get_clipboard_text
  • 描述: 获取剪贴板中的文本内容
  • 示例: 
    GET /api/?command=get_clipboard_text
  • 响应:
    {
  "status": "success",
  "type": "screenshot_ocr",
  "data": "剪贴板中的文本内容",
  "timestamp": 1647859200000
}

12.2 输入法功能

输入法发送ime_send 命令支持以下多种格式：

1. 下划线格式（与 click_at 风格一致）

# 发送文本
/api/?command=ime_send_你好世界

# 清空后发送
/api/?command=ime_send_&clear=true你好世界

# 发送并按回车
/api/?command=ime_send_&enter=true你好世界

# 逐字输入（文本_延迟）
/api/?command=ime_send_delayed_你好世界_100

2. 空格分隔格式

/api/?command=ime_send 你好世界

/api/?command=ime_send_delayed 你好世界 100

3. 参数格式

/api/?command=ime_send&text=你好世界&clear=true&enter=true

/api/?command=ime_send_delayed&text=你好世界&delay=100

4. 中文命令格式

/api/?command=输入文本 你好世界

/api/?command=逐字输入 你好世界 100

其他输入法命令使用方法：

5. 获取当前输入框内容

curl "http://设备IP:58082/api/?command=ime_get_text"

6. 清空输入框

curl "http://设备IP:58082/api/?command=ime_clear"

7. 逐字输入（模拟真人）

curl "http://设备IP:58082/api/?command=ime_send_delayed&text=你好世界&delay=100"

13. 命令执行器

13.1 执行命令

  • 命令: exec
  • 描述: 在设备上执行系统命令（需要Node.js服务）
  • 参数:
    • cmd: 要执行的命令
    • timeout: 超时时间（毫秒，可选）
    • cwd: 工作目录（可选）
  • 示例: 
    GET /api/?command=exec&cmd=ls -la&cwd=/sdcard
  • 响应:
    {
  "ret": true,
  "msg": "success",
  "data": {
    "command": "ls -la",
    "exitCode": 0,
    "stdout": "文件列表...",
    "stderr": "",
    "executionTime": 123,
    "cwd": "/sdcard"
  }
}

13.2 异步执行命令

  • 命令: exec_async
  • 描述: 异步执行系统命令
  • 参数:
    • cmd: 要执行的命令
    • timeout: 超时时间（可选）
    • cwd: 工作目录（可选）
  • 示例: 
    GET /api/?command=exec_async&cmd=ping 8.8.8.8
  • 响应:
    {
  "status": "accepted",
  "message": "命令已接受，正在异步执行",
  "task_id": "exec_1647859200000",
  "command": "ping 8.8.8.8",
  "cwd": "默认目录",
  "timestamp": 1647859200000
}

13.3 执行系统命令（简化版）

  • 命令: system 或 sh
  • 描述: 执行系统命令的简化版本
  • 参数:
    • cmd: 要执行的命令
    • cwd: 工作目录（可选）
  • 示例: 
    GET /api/?command=system&cmd=ls&cwd=/sdcard
  • 响应:
    {
  "status": "success",
  "exitCode": 0,
  "stdout": "文件列表...",
  "stderr": "",
  "cwd": "/sdcard",
  "timestamp": 1647859200000
}

13.4 检查执行服务状态

  • 命令: check_exec_service
  • 描述: 检查命令执行服务是否正常运行
  • 示例: 
    GET /api/?command=check_exec_service
  • 响应:
    {
  "status": "online",
  "message": "执行服务正常运行",
  "port": 58083,
  "timestamp": 1647859200000
}

14. 辅助命令

14.1 帮助信息

  • 命令: help
  • 描述: 获取所有可用命令的帮助信息
  • 示例: 
    GET /api/?command=help
  • 响应: 文本形式的帮助信息

14.2 iBBot处理

  • 命令: ibbot_process
  • 描述: 调用iBBot处理API处理命令
  • 参数:
    • command: 要处理的命令
  • 示例: 
    GET /api/?command=ibbot_process&command=今天天气怎么样
  • 响应:
    {
  "status": "success",
  "message": "已复制到剪贴板",
  "result": "iBBot处理结果"
}

14.3 iBBot智能回复

  • 命令: ibbot_smart_reply
  • 描述: 调用iBBot智能回复API
  • 参数:
    • context: 上下文信息（可选）
  • 示例: 
    GET /api/?command=ibbot_smart_reply&context=用户询问天气
  • 响应:
    {
  "status": "success",
  "message": "已复制到剪贴板",
  "reply": "智能回复内容"
}

14.4 收藏文章

  • 命令: 收藏
  • 描述: 收藏当前文章或内容
  • 示例: 
    GET /api/?command=收藏
  • 响应: "文章收藏请求已发送"

14.5 智能回复

  • 命令: 机灵 或 智能回复
  • 描述: 基于当前界面生成智能回复
  • 示例: 
    GET /api/?command=机灵
  • 响应: "正在生成智能回复..."

15. 错误码说明

15.1 HTTP状态码

状态码 说明
200 请求成功
400 请求参数错误
404 命令不存在
500 服务器内部错误

15.2 通用错误响应格式

{
  "status": "error",
  "message": "错误描述信息",
  "timestamp": 1647859200000
}

15.3 常见错误消息

错误消息 说明
"没有可用的截图，请先执行截图命令" 截图缓存为空
"图片压缩失败" 图片处理失败
"坐标格式错误" 坐标参数格式不正确
"截图功能需要 Android 7.0+" 系统版本不支持
"缺少音频数据参数: audio" 语音识别缺少音频数据
"缺少文本参数: text" 语音合成缺少文本
"配置项不存在: [key]" 配置键不存在
"命令执行失败: [原因]" 系统命令执行失败

16. 文件上传下载

1. 文件上传

方式：Base64 上传

GET /api/?command=file_upload&filename=test.txt&file_data=[base64编码文件]&path=/storage/emulated/0/Download/

参数说明

参数 必填 说明
command 是 固定值: file_upload
filename 否 文件名，不填则自动生成
file_data 是* Base64编码的文件数据
path 否 目标路径，默认: /storage/emulated/0/Download/

*注：使用Base64方式时必须提供file_data；使用multipart方式时需通过表单上传文件

成功响应示例

{
  "status": "success",
  "message": "文件上传成功",
  "file_name": "test.txt",
  "file_path": "/storage/emulated/0/Download/test.txt",
  "file_size": 1024,
  "timestamp": 1678901234567
}

失败响应示例

{
  "status": "error",
  "message": "文件上传失败: 磁盘空间不足",
  "timestamp": 1678901234567
}

2. 文件下载

GET /api/?command=file_download&path=/storage/emulated/0/Download/test.txt

参数说明

参数 必填 说明
command 是 固定值: file_download
path 是 要下载的文件完整路径

响应

  • 成功: 返回文件二进制流，Content-Type: application/octet-stream
  • 失败: 返回JSON格式错误信息

失败响应示例

{
  "status": "error",
  "message": "文件不存在或无法读取",
  "timestamp": 1678901234567
}

3. 文件列表

GET /api/?command=file_list&path=/storage/emulated/0/Download/&recursive=false

参数说明

参数 必填 说明
command 是 固定值: file_list
path 否 目录路径，默认: /storage/emulated/0/
recursive 否 是否递归列出，默认: false

成功响应示例

{
  "status": "success",
  "path": "/storage/emulated/0/Download/",
  "parent_path": "/storage/emulated/0",
  "file_count": 5,
  "directory_count": 2,
  "files": [
    {
      "name": "文档",
      "path": "/storage/emulated/0/Download/文档",
      "is_directory": true,
      "is_file": false,
      "last_modified": 1678901234000,
      "can_read": true,
      "can_write": true,
      "hidden": false,
      "file_count": 3
    },
    {
      "name": "test.txt",
      "path": "/storage/emulated/0/Download/test.txt",
      "is_directory": false,
      "is_file": true,
      "size": 1024,
      "size_formatted": "1.00 KB",
      "extension": "txt",
      "last_modified": 1678901234000,
      "can_read": true,
      "can_write": true,
      "hidden": false
    }
  ],
  "storage": {
    "total_space": 12884901888,
    "free_space": 5242880000,
    "usable_space": 5242880000,
    "total_formatted": "12.00 GB",
    "free_formatted": "4.88 GB",
    "usable_formatted": "4.88 GB"
  },
  "timestamp": 1678901234567
}

失败响应示例

{
  "status": "error",
  "message": "路径不存在或不是目录: /invalid/path",
  "timestamp": 1678901234567
}

17 poplang脚本与编程

POP 语言与 JavaScript 执行 API 文档

1. 执行 POP 脚本 pop_eval

同步执行一段 POP 语言脚本。POP 脚本可以是多行命令，也可以是一个操作数组。

命令别名: pop_eval、执行pop

参数:

参数名 类型 必填 说明
script string 是 POP 脚本内容（支持多行，需 URL 编码）
code string 备选 与 script 等价，二选一即可

示例请求:

# 简单 Toast 测试
curl "http://192.168.1.100:58082/api/?command=pop_eval&script=show-toast%20msg"

**示例响应**:

```json
{"status": "success", "message": "Toast已触发"}

2. 从文件执行 POP 脚本 pop_run

从设备内部存储读取一个 POP 脚本文件并执行。

参数:

参数名 类型 必填 说明
file string 是 脚本文件的绝对路径（例如 /sdcard/script.pop）

示例请求:

curl "http://192.168.1.100:58082/api/?command=pop_run&file=/sdcard/test.pop"

示例响应:

{
  "ret": true,
  "msg": "success",
  "results": [...]
}

3. 测试 Toast 命令

test_toast

快速测试 POP 的 show-toast 指令，使用默认方式显示一条消息。

参数:

参数名 类型 必填 说明
msg string 否 要显示的消息，默认 "Hello from POP"

示例请求:

curl "http://192.168.1.100:58082/api/?command=test_toast&msg=测试消息"

示例响应:

{
  "status": "success",
  "message": "Toast已触发"
}

该命令会调用 popEngine.executeScript 自动生成 ['show-toast','','','消息'] 数组并执行。

4. 执行任意 JavaScript 代码

js_eval / eval / jseval

在 WebView 中直接执行 JavaScript 代码，并返回执行结果。支持调用 PopAndroid 对象（如 PopAndroid.showToast）进行交互。

命令别名: js_eval、eval、jseval

参数:

参数名 类型 必填 说明
code string 是 要执行的 JavaScript 代码
script string 备选 与 code 等价

示例请求:

# 简单计算
curl "http://192.168.1.100:58082/api/?command=js_eval&code=1%2B2"

# 获取当前页面标题（如果 WebView 加载了页面）
curl "http://192.168.1.100:58082/api/?command=js_eval&code=document.title"

# 调用 Android Toast
curl "http://192.168.1.100:58082/api/?command=js_eval&code=PopAndroid.showToast('Hello%20from%20JS')"

示例响应:

{
  "result": 3
}

对于非 JSON 返回值，会自动包装为 {"result": 值}；如果返回的是 JSON 对象或数组，则原样返回。

注意事项

  1. POP 脚本语法：POP 脚本基于 JavaScript 语法，支持 op(context, opcode, ...) 调用预定义的操作码，也支持 ['opcode', 参数...] 数组形式。具体操作码可参考 pop_runtime2.js 中的 binderAddOpcode 定义。

  2. 内置操作码扩展：该服务额外注册了 show-toast 和 dtnsbot 操作码：

    • show-toast: 显示 Toast 消息，例：show-toast msg
    • dtnsbot: 调用原有控制命令，例：dtnsbot click_at_500,800

  3. URL 编码：当脚本中包含特殊字符（如空格、引号、换行）时，必须进行 URL 编码。建议使用 POST 方式传递长脚本。

  4. 执行超时：POP 脚本和 JS 代码默认执行超时时间为 30 秒，超时后会返回 {"error": "执行超时"}。

  5. 安全限制：

    • POP 引擎初始化时 safeFlag = false，禁用了 Node.js 的 vm 模块和文件操作，但基本运算和自定义操作码可用。
    • JavaScript 引擎运行在独立的 WebView 中，无法直接访问文件系统，但可以通过 PopAndroid 接口调用部分服务功能。

  6. 响应结构：pop_eval 返回的是 opbatch 执行结果，通常包含 ret, msg, results 字段；js_eval 返回的是 JS 代码的直接返回值。

扩展建议

  • 结合 dtnsbot 操作码，可以在 POP 脚本中无缝调用所有无障碍命令（如点击、滑动、打开应用等）。
  • 利用 js_eval 可动态计算表达式或操作 WebView 内加载的页面内容。
  • 两种执行方式互补：POP 语言适合编写结构化自动化流程，JS 适合快速调试或简单计算。

poplang示例（调用dtnsbot命令）

根据您的要求和 POP 语言的实际语法，dtnsbot 操作码支持直接传递参数字符串（无需用 set 定义变量）。以下是通过 pop_eval 调用 dtnsbot 的示例，均使用简洁的 dtnsbot 命令 参数 格式。

基本示例

# 点击坐标
dtnsbot click_at_500,800

# 返回主页
dtnsbot home

# 截图
dtnsbot screenshot

# 打开设置
dtnsbot open_settings

# 滑动屏幕（起点、终点、持续时间）
dtnsbot swipe_at_100,800,100,200,300

# 输入文本
dtnsbot input_你好世界

# 获取GPS位置
dtnsbot get_gps

使用变量和循环

# 定义循环变量
set i 0
set max 10
set flag true

# 循环点击不同坐标
pop.func.define click_loop
    set x 100
    set y 100
    + x i x
    + y i y
    set coord **500,800
    dtnsbot click_at coord
    + i 1 i
    < i max flag
pop.func.end

pop.do.while flag click_loop

结合条件判断与 OCR 识图

# 截图并识别文字
dtnsbot screenshot
set screenshot_ok true
pop.ifelse screenshot_ok do_ocr skip_ocr

pop.func.define do_ocr
    dtnsbot 识图机灵
pop.func.end

pop.func.define skip_ocr
    dtnsbot show-toast 未截图成功
pop.func.end

# 注意：识图机灵是异步命令，实际执行时可能需等待

17.2 获取webview日志

HTTP API 文档：获取 WebView 日志

基本信息

属性 值
命令 get_today_log / get_log
方法 GET 或 POST
路径 /api/
描述 获取当天 WebView 控制台日志文件的内容（用于调试 POP 或 JS 脚本）

参数

参数名 类型 必填 说明
command string 是 固定值 get_today_log 或 get_log
date string 否 指定日期，格式 YYYY-MM-DD（例如 2025-01-15）。不提供时返回当天日志。

请求示例

# 获取今天的日志
curl "http://192.168.1.100:58082/api/?command=get_today_log"

# 获取指定日期的日志（扩展支持）
curl "http://192.168.1.100:58082/api/?command=get_log&date=2025-01-14"

响应格式

成功响应（日志文件存在且可读）

{
  "status": "success",
  "date": "2025-01-15",
  "file_path": "/sdcard/dtnsbot/logs/2025-01-15.log",
  "file_size": 12345,
  "content": "[10:47:23.205] [LOG] oplines:[[\"set\",\"msg\",\"测试消息\"],[\"show-toast\",\"msg\"]] (:904)\n[10:47:23.205] [ERROR] SyntaxError: Unexpected token '测', \"测试消息\" is not valid JSON (:953)",
  "timestamp": 1705312345678
}
字段 类型 说明
status string 固定为 "success"
date string 日志日期
file_path string 日志文件的绝对路径
file_size number 文件大小（字节）
content string 完整日志内容
timestamp number 服务器响应时间戳（毫秒）

错误响应

1. 日志文件不存在
{
  "status": "error",
  "message": "日志文件不存在或不可读",
  "date": "2025-01-15",
  "expected_path": "/sdcard/dtnsbot/logs/2025-01-15.log",
  "hint": "请确保已执行过脚本产生了日志，且应用有读取权限"
}
2. 读取失败（权限问题）
{
  "status": "error",
  "message": "读取日志文件失败: java.io.FileNotFoundException: /sdcard/dtnsbot/logs/2025-01-15.log (Permission denied)",
  "date": "2025-01-15",
  "file_path": "/sdcard/dtnsbot/logs/2025-01-15.log"
}
3. 日期格式错误（如果手动指定了 date）
{
  "status": "error",
  "message": "日期格式错误，请使用 YYYY-MM-DD 格式"
}

注意事项

  1. 日志文件位置

    • 优先写入公共目录：/sdcard/dtnsbot/logs/
    • 若无存储权限，则回退到应用私有目录：/storage/emulated/0/Android/data/com.example.dtnsbot/files/../dtnsbot/logs/
    • 实际路径以响应中的 file_path 为准。

  2. 权限要求

    • 访问公共目录需要 READ_EXTERNAL_STORAGE 权限（Android 10 及以下）或 MANAGE_EXTERNAL_STORAGE（Android 11+）。若无权限，请引导用户到设置中授予「存储权限」。
    • 应用私有目录不需要额外权限。

  3. 日志轮转

    • 每天生成一个独立的日志文件，文件名格式为 YYYY-MM-DD.log。
    • 当日志写入时自动创建，跨日时关闭旧文件并创建新文件。

  4. 内容安全

    • 日志可能包含敏感信息（如脚本内容、屏幕坐标等），仅在可信网络环境下调用该接口。

扩展用法

配合 dtnsbot_poplang.html 工具，可以在 JavaScript 模式下快速查看日志：

// 在 JS 模式编辑器中执行
fetch('/api/?command=get_today_log')
  .then(res => res.json())
  .then(data => {
    if (data.status === 'success') {
      console.log(data.content);
    } else {
      console.error('获取日志失败:', data.message);
    }
  });

错误码说明

HTTP状态码 说明
200 成功
400 请求参数错误
404 文件/目录不存在
500 服务器内部错误

附录

Web界面访问

  • 控制面板: http://[设备IP]:58082/control
  • 配置管理: http://[设备IP]:58082/config
  • 截图功能: http://[设备IP]:58082/screenshot
  • UI信息: http://[设备IP]:58082/uiinfo
  • 语音API: http://[设备IP]:58082/speech
  • 使用帮助: http://[设备IP]:58082/help

注意事项

  1. 所有坐标参数请确保在屏幕分辨率范围内
  2. 截图功能需要 Android 7.0+（API 24+）
  3. 系统截图API需要 Android 11+（API 30+）
  4. 语音识别需要上传WAV格式音频
  5. 配置修改后立即生效，无需重启服务
  6. 异步任务可以通过 task_id 查询处理状态