oskill-proxy（oskill proxy 文档）

OSkillProxy — Android 组件调用代理

概述

OSkillProxy 是运行在 Android 设备上的代理服务。它提供本地 HTTP API，允许你以正确的 App 身份调用 Android 四大组件（Activity、Service、BroadcastReceiver、ContentProvider）。

使用前提：

• OSkillProxy App 已安装并且代理服务已启动
• Token 已配置（在 App 界面上查看）
• 通过 http://127.0.0.1:8726 访问（端口可能已修改，以实际配置为准）

工具列表

start_activity

启动一个 Android Activity。

• 支持显式 Intent（指定 package + class）和隐式 Intent（指定 action）
• 这是一个 fire-and-forget 操作，不返回 Activity 结果

start_service

启动一个 Android Service。

• 支持普通启动和前台服务启动

send_broadcast

发送一个 Android Broadcast。

• 支持普通广播和带权限限制的广播

query_provider

查询 ContentProvider 数据，返回结构化结果（列名 + 行数据）。

insert_provider

向 ContentProvider 插入数据，返回新记录的 URI。

update_provider

更新 ContentProvider 数据，返回受影响的行数。

delete_provider

删除 ContentProvider 数据，返回受影响的行数。

call_provider

调用 ContentProvider 的 call() 方法，返回 Bundle 结果。

调用方式

所有调用通过 HTTP POST 请求发起，使用 JSON 格式。

通用 HTTP 格式

curl -X POST http://127.0.0.1:8726/api/v1/component/<endpoint> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '<json_body>'

认证

每个请求（除 GET /api/v1/status 外）必须携带 Authorization header：

Authorization: Bearer <你的token>

通用响应格式

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {},
  "requestId": "abc12345"
}

各端点详细说明

POST /component/activity/start

启动一个 Activity。

请求参数:

package+class（显式）或 action（隐式）至少提供一种。

支持的 Flags:

• FLAG_ACTIVITY_NEW_TASK（自动添加）
• FLAG_ACTIVITY_CLEAR_TOP
• FLAG_ACTIVITY_SINGLE_TOP
• FLAG_ACTIVITY_CLEAR_TASK
• FLAG_ACTIVITY_NO_HISTORY
• FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS
• FLAG_ACTIVITY_NEW_DOCUMENT
• FLAG_ACTIVITY_MULTIPLE_TASK
• FLAG_INCLUDE_STOPPED_PACKAGES

POST /component/service/start

启动一个 Service。

请求参数: 同 Activity，额外字段：

POST /component/broadcast/send

发送一个 Broadcast。

请求参数: 同 Activity，额外字段：

POST /component/provider/query

查询 ContentProvider。

请求参数:

响应 data:

{
  "columns": ["_id", "title"],
  "rows": [[1, "Note 1"], [2, "Note 2"]],
  "count": 2
}

POST /component/provider/insert

向 ContentProvider 插入数据。

请求参数:

响应 data:

{
  "uri": "content://com.example.provider/notes/3"
}

POST /component/provider/update

更新 ContentProvider 数据。

请求参数:

响应 data:

{
  "affectedRows": 1
}

POST /component/provider/delete

删除 ContentProvider 数据。

请求参数:

响应 data:

{
  "affectedRows": 1
}

POST /component/provider/call

调用 ContentProvider 的 call() 方法。

请求参数:

响应 data: ContentProvider 返回的 Bundle 内容，序列化为 JSON 对象。

extras 类型说明

extras 字段支持两种格式：

格式 1：显式类型（推荐）

{
  "key": {"type": "string", "value": "hello"},
  "count": {"type": "int", "value": 42},
  "flag": {"type": "boolean", "value": true}
}

支持的类型：string, int, long, float, double, boolean, string_array, int_array, long_array

格式 2：自动推断

{
  "key": "hello",
  "count": 42,
  "flag": true
}

自动根据 JSON 值类型推断。

使用示例

示例 1：启动一个 Activity（显式 Intent）

场景：启动录音应用的透明 Activity 进行录音控制

curl -X POST http://127.0.0.1:8726/api/v1/component/activity/start \
  -H "Authorization: Bearer a3f8xxxxxxxxxxc9d2" \
  -H "Content-Type: application/json" \
  -d '{
    "package": "com.coloros.soundrecorder",
    "class": "oplus.multimedia.soundrecorder.slidebar.TransparentActivity",
    "action": "oplus.intent.action.START_RECORD_FROM_CUBE_BUTTON",
    "categories": ["android.intent.category.DEFAULT"]
  }'

示例 2：启动一个 Activity（隐式 Intent，带 extras）

curl -X POST http://127.0.0.1:8726/api/v1/component/activity/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "android.intent.action.SEND",
    "type": "text/plain",
    "extras": {
      "android.intent.extra.TEXT": {"type": "string", "value": "Hello from agent!"}
    }
  }'

示例 3：查询 ContentProvider

curl -X POST http://127.0.0.1:8726/api/v1/component/provider/query \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "content://com.example.provider/notes",
    "projection": ["_id", "title", "content"],
    "selection": "title LIKE ?",
    "selectionArgs": ["%meeting%"],
    "sortOrder": "created_at DESC"
  }'

示例 4：发送 Broadcast

curl -X POST http://127.0.0.1:8726/api/v1/component/broadcast/send \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "com.example.app.ACTION_REFRESH",
    "package": "com.example.app",
    "extras": {
      "force": {"type": "boolean", "value": true}
    }
  }'

示例 5：检查服务状态（无需 Token）

curl http://127.0.0.1:8726/api/v1/status

错误码

状态检查

GET /api/v1/status

无需认证，用于检查代理服务是否运行。

响应:

{
  "success": true,
  "code": 0,
  "data": {
    "running": true,
    "version": "1.0.0",
    "handlers": ["component"],
    "endpoints": [
      "/api/v1/component/activity/start",
      "/api/v1/component/service/start",
      "/api/v1/component/broadcast/send",
      "/api/v1/component/provider/query",
      "/api/v1/component/provider/insert",
      "/api/v1/component/provider/update",
      "/api/v1/component/provider/delete",
      "/api/v1/component/provider/call"
    ]
  }
}