tomevault-io ZAFrida HTTP 控制
当用户需要通过脚本/自动化方式操控 ZAFrida 而不依赖 UI 点击时，使用此技能。
前置条件
- ZAFrida 插件已安装，且 ToolWindow 至少打开过一次。
- 本地 API 可达（默认地址：
http://127.0.0.1:17839/zafrida/api/v1）。 - 如需自定义地址，设置环境变量
ZAFRIDA_API_BASE即可。
接口概览
共 26 个接口，分为以下几组：
状态与健康
| 命令 | 方法 | 说明 |
|---|---|---|
health |
GET | 服务健康检查（端口、就绪状态） |
state |
GET | 完整状态汇总（项目/设备/脚本/会话/日志大小），不含日志内容 |
项目管理
| 命令 | 方法 | 参数 | 说明 |
|---|---|---|---|
project-current |
GET | — | 当前活跃项目及项目列表 |
project-select |
POST | --name |
切换活跃项目 |
project-create |
POST | --name --platform |
新建项目（android/ios） |
设备与进程
| 命令 | 方法 | 参数 | 说明 |
|---|---|---|---|
devices |
GET | — | 列出所有已连接设备（调用 frida-ls-devices） |
processes |
GET | [--scope] |
列出当前设备的进程/应用（running/apps/installed） |
device-select |
POST | --id 或 --host |
选择设备（二选一） |
mode-set |
POST | --mode [--host --port] |
设置连接模式（usb/remote/gadget） |
target-set |
POST | --target |
设置目标应用包名 |
脚本与参数
| 命令 | 方法 | 参数 | 说明 |
|---|---|---|---|
run-script-set |
POST | --path |
设置 Run 脚本路径 |
attach-script-set |
POST | --path |
设置 Attach 脚本路径 |
extra-set |
POST | --value |
设置额外命令行参数 |
会话控制
| 命令 | 方法 | 说明 |
|---|---|---|
run |
POST | 启动 Run 会话 |
stop |
POST | 停止 Run 会话 |
attach |
POST | 启动 Attach 会话 |
stop-attach |
POST | 停止 Attach 会话 |
日志读取
| 命令 | 方法 | 参数 | 说明 |
|---|---|---|---|
run-log-path |
GET | — | 获取 Run 日志路径、文件大小 |
run-log-content |
GET | [--path] [--max-bytes] |
读取 Run 日志内容（可截断） |
run-log-lines |
GET | [--path] [--start] [--count] |
按行读取 Run 日志（最多 2000 行/次） |
attach-log-path |
GET | — | 获取 Attach 日志路径、文件大小 |
attach-log-content |
GET | [--path] [--max-bytes] |
读取 Attach 日志内容（可截断） |
attach-log-lines |
GET | [--path] [--start] [--count] |
按行读取 Attach 日志（最多 2000 行/次） |
ADB 操作
| 命令 | 方法 | 参数 | 说明 |
|---|---|---|---|
adb-force-stop |
POST | [--target] |
强制停止应用（默认使用当前 target） |
adb-open-app |
POST | [--target] |
启动应用（默认使用当前 target） |
控制台与诊断
| 命令 | 方法 | 参数 | 说明 |
|---|---|---|---|
console-clear |
POST | [--type] |
清空控制台（run/attach，默认 run） |
diagnostics |
GET | — | 运行环境诊断（Python/Frida/ADB 共 6 项检查） |
命令行调用
使用内置脚本 zafrida_skill_cli.py（全局路径 ~/.claude/tools/zafrida_skill_cli.py）：
# 状态与健康
python3 ~/.claude/tools/zafrida_skill_cli.py health
python3 ~/.claude/tools/zafrida_skill_cli.py state
# 项目
python3 ~/.claude/tools/zafrida_skill_cli.py project-current
python3 ~/.claude/tools/zafrida_skill_cli.py project-select --name demo
python3 ~/.claude/tools/zafrida_skill_cli.py project-create --name app1 --platform android
# 设备枚举与选择
python3 ~/.claude/tools/zafrida_skill_cli.py devices
python3 ~/.claude/tools/zafrida_skill_cli.py device-select --id usb
python3 ~/.claude/tools/zafrida_skill_cli.py mode-set --mode remote --host 127.0.0.1 --port 14725
# 进程/应用列表
python3 ~/.claude/tools/zafrida_skill_cli.py processes
python3 ~/.claude/tools/zafrida_skill_cli.py processes --scope apps
python3 ~/.claude/tools/zafrida_skill_cli.py processes --scope installed
# 脚本与参数
python3 ~/.claude/tools/zafrida_skill_cli.py target-set --target com.demo.app
python3 ~/.claude/tools/zafrida_skill_cli.py run-script-set --path /abs/path/run.js
python3 ~/.claude/tools/zafrida_skill_cli.py attach-script-set --path /abs/path/attach.js
python3 ~/.claude/tools/zafrida_skill_cli.py extra-set --value "--realm=emulated"
# 会话控制
python3 ~/.claude/tools/zafrida_skill_cli.py run
python3 ~/.claude/tools/zafrida_skill_cli.py stop
python3 ~/.claude/tools/zafrida_skill_cli.py attach
python3 ~/.claude/tools/zafrida_skill_cli.py stop-attach
# 日志（路径 + 大小）
python3 ~/.claude/tools/zafrida_skill_cli.py run-log-path
python3 ~/.claude/tools/zafrida_skill_cli.py attach-log-path
# 日志（内容，可限制字节数）
python3 ~/.claude/tools/zafrida_skill_cli.py run-log-content --max-bytes 200000
python3 ~/.claude/tools/zafrida_skill_cli.py attach-log-content --max-bytes 200000
# 日志（按行读取，适合大文件分页）
python3 ~/.claude/tools/zafrida_skill_cli.py run-log-lines --start 1 --count 100
python3 ~/.claude/tools/zafrida_skill_cli.py attach-log-lines --start 1000 --count 200
# ADB 操作
python3 ~/.claude/tools/zafrida_skill_cli.py adb-force-stop
python3 ~/.claude/tools/zafrida_skill_cli.py adb-force-stop --target com.demo.app
python3 ~/.claude/tools/zafrida_skill_cli.py adb-open-app
python3 ~/.claude/tools/zafrida_skill_cli.py adb-open-app --target com.demo.app
# 控制台与诊断
python3 ~/.claude/tools/zafrida_skill_cli.py console-clear
python3 ~/.claude/tools/zafrida_skill_cli.py console-clear --type attach
python3 ~/.claude/tools/zafrida_skill_cli.py diagnostics
推荐工作流
- 先调用
state获取完整上下文（项目、设备、脚本路径、会话状态、日志文件大小）。 - 如有问题，调用
diagnostics自检环境（Python/Frida/ADB 可用性）。 - 调用
devices查看可用设备，按需device-select选择。 - 调用
processes --scope apps查看设备上的应用，确认目标。 - 按需配置必要字段（
project-select、mode-set、脚本、目标、额外参数）。 - 需要时先
adb-force-stop停止旧进程，再adb-open-app启动应用。 - 触发
run或attach。 - 根据日志文件大小选择读取策略：
- 小日志（< 200KB）：直接用
run-log-content读取全部内容。 - 中等日志：用
run-log-lines --start N --count M按行分页读取。 - 大日志（> 1MB）：用返回的
path配合large-text-viewer进行高效行提取和搜索（参见/use-text-viewer全局技能）。
- 小日志（< 200KB）：直接用
- 需要重新开始时，用
console-clear清空控制台。
响应格式
所有接口返回统一 JSON 结构：
// 成功
{"ok": true, "status": 200, "data": { ... }}
// 失败
{"ok": false, "status": 400, "message": "错误描述"}
注意事项
- 汇总接口
state不包含日志内容，仅返回路径和文件大小（避免大体积响应）。 run-log-path/attach-log-path返回fileSize（字节数）和sizeHuman（可读格式如 "14.1 MB"）。run-log-content的content字段为纯日志内容，截断信息通过truncated/fileSize/maxBytes元数据传递（不会注入标记文本）。run-log-lines的lines为字符串数组，响应包含startLine/endLine/linesRead/hasMore元数据。- 单次按行读取上限 2000 行；超过此限制请分多次请求或使用
large-text-viewer。
Source: yilongmd/zafrida-ui — distributed by TomeVault.