byted-acep-api

Files (21)

• LICENSE
• SKILL.md
• pyproject.toml
• __init__.py · scripts/core/
• apps.py · scripts/core/
• cli_common.py · scripts/core/
• dcs.py · scripts/core/
• display_layouts.py · scripts/core/
• generic.py · scripts/core/
• hosts.py · scripts/core/
• images.py · scripts/core/
• instance_controls.py · scripts/core/
• instance_properties.py · scripts/core/
• instances.py · scripts/core/
• network.py · scripts/core/
• products.py · scripts/core/
• resources.py · scripts/core/
• tags.py · scripts/core/
• tasks.py · scripts/core/
• vephone_client.py · scripts/core/
• vephone_cli.py · scripts/

SKILL.md (first lines)

# 火山云手机 Skill

当用户要求查看或操作已配置测试业务下的火山云手机资源时，使用这个 skill。

## 运行约束

- 不要静态配置 DC。应根据用户请求或当前资源可用性选择 DC。
- 先通过 `list-products` 查业务 ID，再在每条命令里显式传入 `product_id`。
- 创建和订购资源时必须显式选择业务资源类型：云盘存储使用 `100`，本地存储使用 `200`。
- 更新实例镜像或规格时，优先先关机；涉及强制更新时，提醒用户确认可能带来的影响。
- 后付费实例资源组只支持复购。在订购后付费资源前，先确认该业务已经在火山云手机控制台下过单，并且能查到 `OrderId`。
- 截图优先使用直连方式 `get-presigned-edge-url --api-type TakeScreenshot`。
- `batch-screen-shot` 作为回退方式使用；当业务已配置截图存储且用户明确需要该链路时再用。
- 除非用户明确要求，否则不要输出签名 URL。
- 查询已安装应用时优先使用 `get-pod-app-list`；仅在确有需要时才回退到 Android `pm list packages`。
- 除非用户明确要求，否则不要输出 access key、secret key、Authorization header 或完整签名 URL。
- 创建、删除、开关机、重启、重置、安装/卸载、文件传输、应用启动/关闭，以及 Android 命令执行都属于有状态变更操作。除非用户明确要求执行该操作，否则先确认。

## 命令入口

以下示例默认在当前 skill 包目录下执行：

```bash
python3 scripts/vephone_cli.py <command> [args]
```

这个 skill 已内置 `scripts/vephone_cli.py` 和 `scripts/core/`，可以直接运行，不依赖仓库根目录下的实现。

命令以显式 flags 的形式暴露常用参数。除 `list-products` 等少数查询命令外，大多数业务命令都把 `product_id` 作为第一个位置参数；查看某个命令支持哪些过滤条件时，直接用 `python3 scripts/vephone_cli.py <command> -h`。如果认证配置不在默认位置，可以用 `--config /path/to/config.json` 指定配置文件路径；这个全局参数放在子命令前后都可以。

如果现有命令还没有覆盖到目标 OpenAPI Action，可以使用通用命令：

```bash
python3 scripts/vephone_cli.py action-call ListOperableProduct --json-body --param Count=10 --param CloudphoneProductType=5
python3 scripts/vephone_cli.py action-call GetProductResource --product-id <product_id>
python3 scripts/vephone_cli.py action-call SetProxy --json-body --params-json '{"ProductId":"<product_id>","PodIdList":["pod-1"],"ProxyStatus":1,"ProxyConfig":{"version":"v2","type":"socks5","address":"203.0.113.52","port":"12345"}}'
```

`action-call` 的 `--param` 使用 `Key=Value` 形式，`Value` 会优先按 JSON 解析，失败时按字符串处理，所以可以直接传 `true`、`123`、`[1,2]`、`{"k":"v"}`。注意在常见 shell 中如果不对 `Key=Value` 做引用/转义，形如 `--param Foo={"k":"v"}` 的双引号可能会被 shell 吞掉，导致程序实际收到 `Foo={k:v}` 并触发 JSON 解析失败；当 `Value` 含双引号、空格或复杂 JSON 时，请用单引号包裹整个 `Key=Value`（如 `--param 'Foo={"k":"v"}'` / `--param 'PodIdList=["pod-1"]'`），或优先使用 `--params-json`（如 `--params-json '{"Foo":{"k":"v"}}'`）。若希望强制按字符串传入 `true`/`123` 等，请使用 JSON 字符串形式：`--param Name='"123"'`。需要批量传参时用 `--params-json`；如果同时传了同名键，`--param` 会覆盖 `--params-json`。默认按 query string 调用，带 `--json-body` 时改为 JSON body。

## 实例管理

只读操作：

```bash
python3 scripts/vephone_cli.py list-products --count 10
python3 scripts/vephone_cli.py list-pods <product_id> --max-results 10
python3 scripts/vephone_cli.py list-pods <product_id> --configuration-code-list <code1,code2> --dc-list <dc1,dc2> --online-list 1,2 --next-token <token>
python3 scripts/vephone_cli.py detail-pod <product_id> <pod_id>
python3 scripts/vephone_cli.py get-pod-metric <product_id> <pod_id>
python3 scripts/vephone_cli.py get-pod-property <product_id> <pod_id>
```

有状态变更操作：

```bash
python3 scripts/vephone_cli.py create-pod <product_id> --name <name> --template-id <template_id> --configuration-code <code> --dc-id <dc> --resource-type 200 --image-id <image_id> --display-layout-id <layout_id> --phone-template-id <template_id>
python3 scripts/vephone_cli.py update-pod <product_id> <pod_id> --image-id <image_id> --display-layout-id <layout_id> --configuration-code <code>
python3 scripts/vephone_cli.py update-pod <product_id> <pod_id> --image-id <image_id> --force
python3 scripts/vephone_cli.py delete-pod <product_id> <pod_id>
python3 scripts/vephone_cli.py power-on-pod <product_id> <pod_id>
python3 scripts/vephone_cli.py power-off-pod <product_id> <pod_id>
python3 scripts/vephone_cli.py reboot-pod <product_id> <pod_id>
python3 scripts/vephone_cli.py reset-pod <product_id> <pod_id>
python3 scripts/vephone_cli.py create-pod-one-step <product_id> --configuration-code <code> --dc <dc> --app-list <app_id:version_id,...>
python3 scripts/vephone_cli.py update-pod-property <product_id> --pod-id <pod_id> --pod-settings '[{"SettingsName":"locale_language","SettingsType":"global","SettingsValue":"zh-CN","SettingsValueType":"string"}]'
python3 scripts/vephone_cli.py update-pod-resource-apply-num <product_id> --resource-set-id <resource_set_id> --apply-num <num>
python3 scripts/vephone_cli.py backup-pod <product_id> --pod-id-list <pod_id1,pod_id2>
python3 scripts/vephone_cli.py restore-pod <product_id> --pod-id-list <pod_id1,pod_id2>
python3 scripts/vephone_cli.py pod-mute <product_id> --pod-id <pod_id> --mute true --display-list <display1,display2>
python3 scripts/vephone_cli.py pod-adb <product_id> --pod-id <pod_id> --enable true
python3 scripts/vephone_cli.py pod-stop <product_id> --pod-id <pod_id>
python3 scripts/vephone_cli.py pod-data-delete <product_id> --pod-id <pod_id> --file-path-list </sdcard,/data/data> --package-list <pkg1,pkg2>
python3 scripts/vephone_cli.py set-proxy <product_id> --pod-id-list <pod_id1,pod_id2> --proxy-status 1 --proxy-config '{"version":"v2","type":"socks5","address":"203.0.113.52","port":"12345"}'
python3 scripts/vephone_cli.py get-proxy <product_id> --pod-id-list <pod_id1,pod_id2>
python3 scripts/vephone_cli.py backup-data <product_id> --pod-id-list <pod_id1,pod_id2> --backup-all false --include-path-list </data/app,/data/data> --exclude-path-list </data/anr>
python3 scripts/vephone_cli.py restore-data <product_id> --backup-data-id <backup_data_id> --pod-id-list <pod_id1,pod_id2>
python3 scripts/vephone_cli.py list-backup-data <product_id> --status completed --max-results 20
python3 scripts/vephone_cli.py delete-backup-data <product_id> --backup-data-id-list <backup_data_id1,backup_data_id2>
```

`list-pods` 支持通过 `--max-results` 和 `--next-token` 分页。`create-pod` 可以用 `--image-id` 指定初始镜像。`delete-pod`、`reset-pod`、`update-pod --force` 这类操作有明显影响，执行前先确认。像 `--app-list`、`--pod-settings`、`--specify-host-list`、`--proxy-config` 这类结构化参数，直接看对应命令的 `-h` 获取格式说明。

## 资源、DC、主机与镜像查询

```bash
python3 scripts/vephone_cli.py list-dcs <product_id>
python3 scripts/vephone_cli.py get-dc-bandwidth-daily-peak <product_id> <dc_id_list>
python3 scripts/vephone_cli.py list-pod-resources <product_id>
python3 scripts/vephone_cli.py get-product-resource <product_id>
python3 scripts/vephone_cli.py list-products --count 10
python3 scripts/vephone_cli.py list-configurations <product_id>
python3 scripts/vephone_cli.py list-instance-configuration-specs <product_id>
python3 scripts/vephone_cli.py list-phone-templates <product_id>
python3 scripts/vephone_cli.py get-phone-template <product_id> <phone_template_id>
python3 scripts/vephone_cli.py list-hosts <product_id>
python3 scripts/vephone_cli.py detail-host <product_id> <host_id>
python3 scripts/vephone_cli.py update-host <product_id> <host_id1,host_id2> --configuration-code <pod_config_code>
python3 scripts/vephone_cli.py reboot-host <product_id> <host_id1,host_id2> --force
python3 scripts/vephone_cli.py reset-host <product_id> <host_id1,host_id2> --force
python3 scripts/vephone_cli.py list-image-resources <product_id>
python3 scripts/vephone_cli.py list-aosp-images <product_id> --is-public --max-results 20
python3 scripts/vephone_cli.py list-aosp-images <product_id> --max-results 20
python3 scripts/vephone_cli.py get-image-preheating <product_id> <image_id>
```

`list-image-resources` 用于查看当前业务正在使用的镜像资源。`list-aosp-images --is-public` 查询公共镜像；省略 `--is-public` 则查询自定义镜像。

创建实例前，先看 `list-pod-resources`，选择有可用余量的 `(ConfigurationCode, Dc)` 组合，并带上匹配的 `--resource-type`。

资源订购操作属于有状态变更，并且可能产生费用。后付费实例资源组只适用于已有下单历史的业务，执行前先确认。

本地存储主机订购时，明确传目标 pod 规格、主机类型、机房、数量和资源类型：

```bash
python3 scripts/vephone_cli.py subscribe-resource-auto \
  <product_id> \
  --configuration-code <pod_config_code> \
  --server-type-code <host_server_type_code> \

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples