CLI 使用指南

更新于 2026-08-19

本文只说明 PerfKitty CLI 的构建产物、命令、参数、输出和使用流程。MCP 与 Skills 不在本文展开。

1. CLI 是什么

PerfKitty CLI 是 PerfKitty 的本地命令行执行入口，面向脚本、CI、批处理和 AI Agent 调用。

CLI 的职责：

检查本地环境。
发现 Android / iOS 设备。
读取设备详情。
列出目标设备上的应用包。
启动和停止本地采集会话。
保存 perfkitty-session-v2 JSON 或 xlsx 本地结果。
上传 Saved Session。
查询和分享云端 reports。
输出结构化结果，方便脚本和 Agent 解析。

当前 CLI 命令族：

doctor
config show / config set
auth status / auth login / auth login-authing / auth logout
devices list / devices info
packages list
capability probe
session start / session stop / session status / session screenshot / session save
upload session
reports list / reports get / reports share

2. 基本调用格式

.\PerfKitty.CLI.exe <command> [options]

示例：

.\PerfKitty.CLI.exe doctor

所有命令默认输出 JSON。全局参数：

参数	说明
`--output <table\|json\|jsonl\|markdown>`	控制输出格式
`--verbose`	输出更详细的错误信息
`--config <path>`	指定 CLI 配置文件路径

--config 会决定同级 CLI 数据目录。认证文件、最近会话状态、停止信号和缓存结果都会放在该配置文件同级目录下；不传 --config 时默认使用 %LOCALAPPDATA%\PerfKitty\Cli。

成功响应统一形态：

{
  "ok": true,
  "command": "devices list",
  "data": {}
}

失败响应统一形态：

{
  "ok": false,
  "command": "session start",
  "error": {
    "code": "COMMAND_FAILED",
    "message": "..."
  }
}

3. 命令总览

当前 CLI 支持以下命令：

命令	作用	当前状态
`doctor`	检查本地环境、配置和认证状态	不需要登录
`config show` / `config set`	查看或修改 CLI 配置	不需要登录
`auth status`	查看认证状态	不需要预先登录，但会连接已保存的 server
`auth login` / `auth login-authing` / `auth logout`	登录或退出登录	不需要预先登录
`devices list`	列出连接设备	需要登录
`devices info`	读取设备详情	需要登录
`packages list`	列出设备应用包	需要登录
`capability probe`	探测设备和应用采集能力	需要登录
`session start`	启动采集会话	需要登录
`session stop`	停止活动会话	需要登录
`session status`	查看最近一次 CLI 会话状态	需要登录
`session screenshot`	查看最近一次会话截图	需要登录
`session save`	将最近一次会话缓存导出为正式结果	需要登录
`export session`	`session save` 的别名	需要登录
`upload session`	上传本地 session 文件到服务端	需要登录和服务端 API
`reports list` / `reports get` / `reports share`	查询和分享服务端报告	需要登录和服务端 API

登录失败或保存的登录态无法连接服务端时，CLI 不允许访问设备、读取应用、启动采样、停止采样或导出已有采样数据。

4. `doctor`

4.1 作用

doctor 用于检查 CLI 当前运行环境是否具备基本采集条件。

它会检查：

ADB 是否可调用。
Android 设备数量。
iOS helper 状态。
Server 配置状态。
Auth 状态。
阻塞问题列表。

4.2 命令

.\PerfKitty.CLI.exe doctor

4.3 参数

当前无必填参数。

4.4 输出示例

{
  "ok": true,
  "command": "doctor",
  "data": {
    "adb": {
      "status": "ok",
      "deviceCount": 1
    },
    "iosHelper": {
      "status": "unavailable",
      "note": "No CLI iOS helper transport is configured in this build."
    },
    "server": {
      "status": "not_configured"
    },
    "auth": {
      "status": "not_authenticated"
    },
    "issues": []
  }
}

4.5 字段说明

字段	说明
`adb.status`	ADB 检查结果，`ok` 表示可用
`adb.deviceCount`	当前发现的 Android 设备数量
`iosHelper.status`	iOS helper 状态；未配置 helper transport 时为 `unavailable`
`server.status`	服务端配置状态，取决于 `config set server.url`
`auth.status`	认证状态，取决于 `auth login` 或 `auth login-authing`
`issues`	环境问题列表；空数组表示没有发现阻塞问题

4.6 什么时候用

建议每次采集前先跑：

.\PerfKitty.CLI.exe doctor

如果 issues 非空，先解决环境问题再采集。

5. `auth status`

5.1 作用

auth status 用于查看 CLI 当前认证状态。

CLI 会尝试从本地加密认证文件恢复登录态；如果 refresh token 有效，会刷新并返回当前用户信息。

5.2 命令

.\PerfKitty.CLI.exe auth status

5.3 参数

当前无参数。

5.4 输出示例

{
  "ok": true,
  "command": "auth status",
  "data": {
    "isAuthenticated": false,
    "serverApiBaseUrl": null,
    "user": null,
    "accessTokenExpiresAt": null,
    "refreshTokenExpiresAt": null
  }
}

5.5 字段说明

字段	说明
`isAuthenticated`	是否已登录
`serverApiBaseUrl`	当前服务端地址
`user`	当前用户信息
`accessTokenExpiresAt`	access token 过期时间
`refreshTokenExpiresAt`	refresh token 过期时间

5.6 相关命令

账号密码登录：

.\PerfKitty.CLI.exe auth login --server-url http://127.0.0.1:5267 --identifier <email-or-phone> --password <password>

Authing 托管登录：

.\PerfKitty.CLI.exe auth login-authing --server-url http://127.0.0.1:5267 --open
.\PerfKitty.CLI.exe auth login-authing --server-url http://127.0.0.1:5267 --code <callback-code>

退出登录：

.\PerfKitty.CLI.exe auth logout

登录状态会使用 DPAPI 加密后保存到 CLI 数据目录。

6. `devices list`

6.1 作用

devices list 用于列出当前连接的设备。

该命令需要有效登录态。登录失败、登录态过期或保存的 server 地址不可达时，命令会在访问 ADB / helper 前失败。

Android 设备来自 ADB：

adb devices

iOS 设备当前依赖 helper transport；未配置 transport 时 doctor 会显示 iosHelper.status=unavailable。

6.2 命令

.\PerfKitty.CLI.exe devices list

6.3 参数

当前无参数。

6.4 输出示例

{
  "ok": true,
  "command": "devices list",
  "data": [
    {
      "id": "FLCH10001A202406",
      "displayName": "FIH EA211005",
      "platform": 0,
      "connectionKind": 0,
      "serial": "FLCH10001A202406",
      "legacyConnectionKind": 0
    }
  ]
}

6.5 字段说明

字段	说明
`id`	设备 id，Android 下等同 ADB serial
`displayName`	设备显示名
`platform`	平台枚举，`0` 表示 Android，`1` 表示 iOS
`connectionKind`	连接类型枚举
`serial`	兼容旧字段，等同 `id`
`legacyConnectionKind`	兼容旧连接类型字段

6.6 什么时候用

采集前必须先知道设备 id：

.\PerfKitty.CLI.exe devices list

后续命令中的 --device 参数就填这里返回的 id。

7. `devices info`

7.1 作用

devices info 用于读取单台设备的硬件和系统信息。

Android 下会通过 ADB 读取系统属性、CPU/GPU/内存等信息。

7.2 命令

.\PerfKitty.CLI.exe devices info --device FLCH10001A202406 --platform android

7.3 参数

参数	必填	说明
`--device <id>`	是	设备 id，来自 `devices list`
`--platform <android\|ios>`	否	设备平台，默认 `android`

7.4 输出字段

输出为 ConnectedDeviceDetails，主要包含：

字段	说明
`cpuArch`	CPU 架构
`cpuCoreNum`	CPU 核心数
`cpuInfo`	CPU 型号信息
`cpuMaxFreq`	CPU 最大频率
`deviceBrand`	设备品牌
`deviceName`	设备名称
`deviceSystem`	系统版本
`gpuInfo`	GPU 信息
`openGl`	OpenGL 信息
`ram`	内存信息
`resolution`	分辨率
`serialNumber`	序列号
`vulkan`	Vulkan 信息
`metal`	iOS Metal 信息，Android 下一般为 `-`

7.5 什么时候用

建议在以下场景使用：

采集前确认设备型号。
报告里需要写设备信息。
排查不同设备性能差异。

8. `packages list`

8.1 作用

packages list 用于列出指定设备上的应用包。

Android 下会合并：

第三方已安装包。
正在运行的进程包。
当前前台包。

返回结果会优先排序：

前台应用。
正在运行的应用。
其他包名。

8.2 命令

.\PerfKitty.CLI.exe packages list --device FLCH10001A202406 --platform android

8.3 参数

参数	必填	说明
`--device <id>`	是	设备 id，来自 `devices list`
`--platform <android\|ios>`	否	设备平台，默认 `android`

8.4 输出示例

{
  "ok": true,
  "command": "packages list",
  "data": [
    {
      "packageName": "com.smashrealm.cn",
      "isRunning": true,
      "isForeground": true,
      "displayName": null,
      "iconPngBytes": null,
      "version": null,
      "versionCode": null
    }
  ]
}

8.5 字段说明

字段	说明
`packageName`	Android package name 或 iOS bundle id
`isRunning`	是否正在运行
`isForeground`	是否为当前前台应用
`displayName`	应用显示名，当前 Android CLI 路径可能为空
`iconPngBytes`	应用图标，当前 Android CLI 路径可能为空
`version`	应用版本，当前 Android CLI 路径可能为空
`versionCode`	应用版本码，当前 Android CLI 路径可能为空

8.6 什么时候用

当用户不知道包名时，先执行：

.\PerfKitty.CLI.exe packages list --device <device-id> --platform android

通常取 isForeground: true 的包作为采集目标。

9. `session start`

9.1 作用

session start 用于启动一次本地性能采集会话。

当前 Android 采集会：

部署 Android agent。
建立 ADB / socket 通道。
读取 capability。
启动目标包采样。
接收 sample。
如果指定 --duration，到时自动停止。
如果指定 --save-to，结束后导出正式 session 文件。
如果指定 --upload，导出后上传 Saved Session。

9.2 命令

.\PerfKitty.CLI.exe session start --device FLCH10001A202406 --platform android --package com.smashrealm.cn --duration 10

采集 Android SubProcess 时，传入完整进程名：

.\PerfKitty.CLI.exe session start --device 861c33da --platform android --package com.ss.android.ugc.aweme --process com.ss.android.ugc.aweme:minigame1 --duration 30

9.3 参数

参数	必填	说明
`--device <id>`	是	设备 id，来自 `devices list`
`--platform <android\|ios>`	否	设备平台，默认 `android`
`--package <name>`	是	目标应用包名
`--process <name>`	否	Android 目标进程完整名称，用于采集 SubProcess，例如 `com.ss.android.ugc.aweme:minigame1`
`--duration <seconds>`	否	采集秒数；大于 0 时自动停止
`--scene <name>`	否	本次采集场景名，会进入导出文件和上传报告
`--sampling <default\|cpu,memory,fps,gpu,network,disk,thermal>`	否	采样项选择，多个值用逗号分隔
`--continuous-screenshots`	否	采集期间开启连续截图
`--save-to <path>`	否	采样结束后导出正式 session 文件
`--format <json\|excel>`	否	导出格式；也可由 `.json` / `.xlsx` 扩展名推断
`--upload`	否	采样结束后上传 Saved Session；需要已登录
`--adb-path <path>`	否	指定 ADB 可执行文件
`--repository-root <path>`	否	开发调试兜底参数；发布产物正常不需要传

9.4 输出示例

{
  "ok": true,
  "command": "session start",
  "data": {
    "state": "Stopped",
    "hasActiveSession": false,
    "sampleCount": 8,
    "capability": {
      "device_id": "FLCH10001A202406",
      "android_version": "11",
      "abi": "arm64-v8a",
      "gpu_backend": "mali",
      "gpu_model": "mt6833",
      "memory_provider": "Debug.MemoryInfo",
      "fps_provider": "surfaceflinger",
      "timestamp_unix_ms": 1663604607240,
      "status": "ok"
    },
    "error": null
  }
}

9.5 字段说明

字段	说明
`state`	会话结束后的状态；自动停止成功时为 `Stopped`
`hasActiveSession`	是否仍有活动会话
`sampleCount`	本次进程内采到的 sample 数
`capability`	采集链路能力快照
`error`	错误信息；成功时为 `null`

9.6 capability 字段说明

字段	说明
`device_id`	设备 id
`android_version`	Android 版本
`abi`	设备 ABI
`gpu_backend`	GPU 采集后端，例如 `mali`、`kgsl`
`gpu_model`	GPU 型号
`memory_provider`	内存采集来源
`fps_provider`	FPS 采集来源
`status`	capability 状态，`ok` 表示可用

9.7 完整 session 导出

按设计文档，采样结束后的正式结果不应该只落在 JSONL 里。

正式结果可通过两种方式导出：

session start --save-to <path>
session save --path <path>

格式	用途
`perfkitty-session-v2` JSON	PerfKitty 的结构化会话结果，后续上传、离线加载和 MCP 分析应优先使用
`xlsx`	面向人工查看、表格分析和 PerfDog 对齐

示例：

.\PerfKitty.CLI.exe session start --device <id> --platform android --package <package> --duration 30 --save-to F:\Temp\run.perfkitty.json
.\PerfKitty.CLI.exe session save --path F:\Temp\run.xlsx --format excel

9.8 原始样本日志

CLI 会在发布目录生成 JSONL 原始流日志：

.\perfkitty-cli-session.jsonl

每一行是一个 sample JSON。常见字段包括：

字段	说明
`session_id`	会话 id
`device_id`	设备 id
`app_pid`	目标应用 pid
`fps`	FPS
`frame_time_ms`	帧时间
`cpu_process_percent`	App CPU 使用率
`cpu_total_percent`	整机 CPU 使用率
`gpu_backend`	GPU 后端
`gpu_usage_percent`	GPU 使用率
`memory_pss_kb`	PSS 内存
`gpu_counters`	原始 GPU counter 字典
`gpu_semantic_counters`	语义化 GPU 指标
`timestamp_unix_ms`	时间戳
`relative_ms`	相对会话开始时间
`frame_times_ms_x10`	帧时间列表，单位为 0.1 ms

JSONL 的定位是原始明细和调试追踪。它保留逐条 sample 原始数据，适合排查采集链路，但不是最终报告文件。

9.9 成功判断

一次采集可以认为成功，需要同时满足：

ok 为 true。
error 为 null。
capability.status 为 ok。
sampleCount 大于 0。
JSONL 原始日志文件存在并有内容。

9.10 长会话行为

不传 --duration 时，session start 会以前台采集方式运行，直到按 Ctrl+C 才停止。脚本和 CI 推荐使用短采集：

.\PerfKitty.CLI.exe session start --device <id> --platform android --package <package> --duration 10

也可以在另一个终端用同一份 --config 发停止请求：

.\PerfKitty.CLI.exe --config F:\Temp\perfkitty-cli.json session stop

10. `session stop`

10.1 作用

session stop 用于停止当前活动采集会话。

10.2 命令

.\PerfKitty.CLI.exe session stop

10.3 行为说明

session start 在无 --duration 时会以前台方式持续采集，并在当前 CLI 配置目录写入：

sessions.json：最近一次会话状态，包含设备、包名、进程号、状态和最近缓存路径。
control\stop-<pid>.signal：session stop 写入的停止信号文件。
cache\last-session.perfkitty.json：采样结束后的最近一次正式 session 缓存。

session stop 会读取 sessions.json，如果最近一次会话仍由 CLI 前台采集进程持有，就写入停止信号，并等待该进程优雅停止。停止完成后，session start 进程会保存 perfkitty-session-v2 缓存；随后可用 session save 导出 JSON 或 Excel。

如果最近一次进程已经不存在，session stop 不会伪造一次成功采样，只会返回当前状态。

10.4 输出示例

{
  "ok": true,
  "command": "session stop",
  "data": {
    "stopped": true,
    "requested": true,
    "activeSession": {
      "state": "Stopped",
      "lastPackagePath": "C:\\Users\\...\\cache\\last-session.perfkitty.json"
    },
    "note": "Stop was requested through the CLI control signal."
  }
}

11. 推荐使用流程

11.1 第一次确认环境

Client\build-portable.bat
.\PerfKitty.CLI.exe doctor

11.2 找设备

先确认已经登录到当前服务端：

.\PerfKitty.CLI.exe auth status

如果未登录或 server 地址不对，先登录：

.\PerfKitty.CLI.exe auth login --server-url http://127.0.0.1:5267 --identifier <email-or-phone> --password <password>

.\PerfKitty.CLI.exe devices list

记下输出里的 id。

11.3 找包名

.\PerfKitty.CLI.exe packages list --device <device-id> --platform android

优先选择：

{
  "isForeground": true
}

的包。

11.4 采集 10 秒

.\PerfKitty.CLI.exe session start --device <device-id> --platform android --package <package-name> --duration 10

11.5 保存正式结果

.\PerfKitty.CLI.exe session save --path F:\Temp\run.perfkitty.json
.\PerfKitty.CLI.exe session save --path F:\Temp\run.xlsx --format excel

11.6 查看原始样本

JSONL 是原始证据，不是最终报告：

Get-Content .\perfkitty-cli-session.jsonl -Head 3

11.7 上传报告

.\PerfKitty.CLI.exe upload session --file F:\Temp\run.perfkitty.json --platform android

12. 实测示例

12.1 设备

FLCH10001A202406 / FIH EA211005

12.2 前台包

com.smashrealm.cn

12.3 采集命令

.\PerfKitty.CLI.exe session start --device FLCH10001A202406 --platform android --package com.smashrealm.cn --duration 10

12.4 采集结果摘要

sampleCount: 8
gpu_backend: mali
gpu_model: mt6833
memory_provider: Debug.MemoryInfo
fps_provider: surfaceflinger
status: ok

本次样本汇总：

有效 FPS 样本: 7
平均 FPS: 30.13
FPS 范围: 30.12 - 30.15
平均帧时间: 33.19 ms
App CPU 平均: 18.94%
Total CPU 平均: 36.47%
GPU Usage 平均: 99.17%
PSS 平均内存: 646.55 MB

13. 完整命令速查

命令	作用
`doctor`	检查 ADB、设备、server 配置、认证状态和 CLI 数据目录
`config show`	显示 CLI 配置、配置文件路径和状态文件路径
`config set server.url <value>`	设置服务端 API 地址
`config set android.sdk-root <value>`	记录 Android SDK 路径
`config set ios.runtime-backend <value>`	记录 iOS runtime backend
`config set default-output-format <value>`	设置默认输出格式
`auth status`	恢复并显示当前登录态
`auth login`	使用账号密码登录，参数为 `--server-url`、`--identifier`、`--password`
`auth login-authing`	使用 Authing 托管登录，支持 `--open` 和 `--code`
`auth logout`	清除本地登录态并通知服务端登出
`devices list`	枚举 Android / iOS 设备
`devices info --device <id>`	查询设备详情
`packages list --device <id>`	查询设备上的应用包和前台状态
`capability probe --device <id> --package <pkg>`	通过短握手采集 capability 和 GPU semantic catalog；Android SubProcess 可传 `--process`
`session start`	启动采集，支持 Android `--process`、`--duration`、`--scene`、`--sampling`、`--continuous-screenshots`、`--save-to`、`--upload`
`session stop`	读取最近 session 上下文并报告停止语义
`session status`	查看最近 session cache
`session screenshot`	查看最近 session cache 中的最后一帧截图
`session save --path <file>`	将最近 session cache 导出为 `json` 或 `excel`
`export session --path <file>`	`session save` 的别名
`upload session --file <path>`	上传本地 `perfkitty-session-v2` JSON 或 `xlsx`
`reports list`	查询云端 Saved Session 列表，支持 `--search`、`--project`、`--platform`、`--package`、分页参数
`reports get --id <guid>`	获取指定报告详情
`reports share --id <guid>`	创建或更新单报告分享，支持 `--expires-in-days`、`--password`

14. 排障

14.1 `doctor` 中 `deviceCount` 为 0

检查：

adb devices

可能原因：

设备未连接。
USB 调试未打开。
设备授权弹窗未确认。
ADB 不在 PATH 中。
SDK 路径未配置。

可用 --adb-path 指定 ADB：

.\PerfKitty.CLI.exe devices list --adb-path C:\Android\platform-tools\adb.exe

14.2 `packages list` 没有目标包

检查：

目标 App 是否已安装。
目标 App 是否是第三方包。
目标 App 是否已经启动。
是否选错了设备 id。

可以先把目标 App 切到前台，再执行：

.\PerfKitty.CLI.exe packages list --device <device-id> --platform android

14.3 `session start` 返回 `COMMAND_FAILED`

重点检查：

--device 是否正确。
--package 是否正确。
设备是否允许安装/启动 agent。
发布目录是否包含 android/console/build/libs/perfkitty-console.jar。
发布目录是否包含 android-native/perfkitty-mali-counter 或 android-native/perfkitty-kgsl-counter。

14.4 `sampleCount` 为 0

可能原因：

采集时间太短。
目标包没有运行。
agent 启动后未能产生 sample。
FPS/GPU provider 在设备上不可用。

建议：

.\PerfKitty.CLI.exe session start --device <device-id> --platform android --package <package-name> --duration 30

14.5 FPS 为 0

可能原因：

刚启动时处于 warmup。
SurfaceFlinger layer 尚未匹配到目标应用。
目标应用无有效画面刷新。

建议采集更久，并查看后续 sample 中的 fps.diagnostic.* 字段。

15. 给脚本和 Agent 的建议

脚本调用建议顺序：

doctor
devices list
packages list
session start --duration --save-to
upload session
reports list 或 reports get

判断失败时，优先读取：

顶层 ok
顶层 error.message
data.error
capability.status
JSONL 中 sampling.diagnostic.*
JSONL 中 fps.diagnostic.*
JSONL 中 mali.diagnostic.* 或其他 GPU backend diagnostic 字段

1. CLI 是什么

2. 基本调用格式

3. 命令总览

4. doctor

4.1 作用

4.2 命令

4.3 参数

4.4 输出示例

4.5 字段说明

4.6 什么时候用

5. auth status

5.1 作用

5.2 命令

5.3 参数

5.4 输出示例

5.5 字段说明

5.6 相关命令

6. devices list

6.1 作用

6.2 命令

6.3 参数

6.4 输出示例

6.5 字段说明

6.6 什么时候用

7. devices info

7.1 作用

7.2 命令

7.3 参数

7.4 输出字段

7.5 什么时候用

8. packages list

8.1 作用

8.2 命令

8.3 参数

8.4 输出示例

8.5 字段说明

8.6 什么时候用

9. session start

9.1 作用

9.2 命令

9.3 参数

9.4 输出示例

9.5 字段说明

9.6 capability 字段说明

9.7 完整 session 导出

9.8 原始样本日志

9.9 成功判断

9.10 长会话行为

10. session stop

10.1 作用

10.2 命令

10.3 行为说明

10.4 输出示例

11. 推荐使用流程

11.1 第一次确认环境

11.2 找设备

11.3 找包名

11.4 采集 10 秒

11.5 保存正式结果

11.6 查看原始样本

11.7 上传报告

12. 实测示例

12.1 设备

12.2 前台包

12.3 采集命令

12.4 采集结果摘要

13. 完整命令速查

14. 排障

14.1 doctor 中 deviceCount 为 0

14.2 packages list 没有目标包

14.3 session start 返回 COMMAND_FAILED

14.4 sampleCount 为 0

14.5 FPS 为 0

15. 给脚本和 Agent 的建议

4. `doctor`

5. `auth status`

6. `devices list`

7. `devices info`

8. `packages list`

9. `session start`

10. `session stop`

14.1 `doctor` 中 `deviceCount` 为 0

14.2 `packages list` 没有目标包

14.3 `session start` 返回 `COMMAND_FAILED`

14.4 `sampleCount` 为 0