#CLI 参考
本栏目以 agent-lynx@0.14.23 的公开能力为基准。安装与设备配置参见快速开始，具体操作参见各功能指南，程序化 API 单独介绍包导出和集成方式。使用 agent-lynx <command> --help 查看已安装版本支持的完整选项。
#命令清单
公开 CLI 提供以下 46 个可执行命令，子命令分别计数。agent-lynx --version、agent-lynx --help 和 agent-lynx help <command> 提供版本及帮助信息。
| 能力 | 命令 |
|---|---|
| 读取自带的 skills | agent-lynx skills list、agent-lynx skills get |
| 查找应用和页面 | agent-lynx list-clients、agent-lynx wait-for-client、agent-lynx list-sessions、agent-lynx open |
| 获取元素树 | agent-lynx snapshot |
| 交互与等待 | agent-lynx tap、agent-lynx long-press、agent-lynx fill、agent-lynx clear、agent-lynx scroll、agent-lynx wait |
| 读取元素和定位源码 | agent-lynx get text、agent-lynx get style、agent-lynx get-source-info |
| 截图 | agent-lynx screenshot、agent-lynx take-screenshot、agent-lynx take-content-screenshot |
| 查看日志、脚本和图形化检查器 | agent-lynx get-console、agent-lynx get-sources、agent-lynx inspect |
| 执行代码和发送协议请求 | agent-lynx evaluate、agent-lynx cdp、agent-lynx app |
| 检查、查找、关联和修改 ReactLynx 组件 | agent-lynx reactlynx tree、agent-lynx reactlynx component、agent-lynx reactlynx find、agent-lynx reactlynx link、agent-lynx reactlynx update-prop、agent-lynx reactlynx update-state、agent-lynx reactlynx update-context |
| 管理全局开关 | agent-lynx global-switch list、agent-lynx global-switch get、agent-lynx global-switch set |
| 抓取 JS 堆快照 | agent-lynx take-heap-snapshot |
| 录制和分析性能 trace | agent-lynx trace start、agent-lynx trace end、agent-lynx trace read-data、agent-lynx trace event-summary、agent-lynx trace query |
| 录制页面运行时状态以供回放 | agent-lynx recorder start、agent-lynx recorder end |
| 管理共享的本地连接 | agent-lynx daemon status、agent-lynx daemon start、agent-lynx daemon stop |
#连接选项
| 操作 | 选项与行为 |
|---|---|
| 选择应用和页面 | 在支持相应选项的命令中传入实际返回的 --client <clientId> 和 --session <sessionId>。应用重启或页面跳转后，重新查找 ID。 |
| 等待应用 | wait-for-client --client-name <name> --timeout 30 等待应用连接。超时与轮询间隔使用秒；页面级 wait 使用毫秒。 |
| 打开页面 | open <bundle-url> --client <clientId> 使用应用可访问的 URL。开发服务器需要单独运行，页面跳转后重新查找 session 并刷新快照。 |
| 管理 daemon | daemon status 读取版本和协议信息，不会启动 daemon。daemon start 和 daemon stop 管理其生命周期。管理命令支持 --port，默认值为 21783。 |
| 使用直接连接 | 通过 --no-daemon 直接连接同一目标前，先停止 daemon。直接连接支持 Android、iOS、Desktop 和 HDT。快照引用及其操作、wait、screenshot 和 ReactLynx 命令需要默认的 daemon 模式。 |
#页面检查与交互选项
页面检查与交互展示从快照到操作、再验证结果的完整过程。以下命令通过默认 daemon 共享所选页面的快照引用。
| 操作 | 选项与行为 |
|---|---|
| 获取快照 | snapshot 读取元素树，可以包含屏幕外的节点；--visible-only 只保留当前可见的元素。页面变化后使用新快照中的引用。 |
| 读取文本和样式 | get text <ref> 读取元素文本。get style <ref> --property color,width 选择要读取的计算样式，属性名以逗号分隔。 |
| 点击和长按 | tap <ref> 点击元素；long-press <ref> --duration 800 指定长按时长，单位为毫秒。 |
| 填写和清空 | fill <ref> "Alice" 替换可编辑输入框的内容；clear <ref> 清空内容。 |
| 滚动 | scroll <ref> --direction down 操作滚动容器，方向支持 up、down、left 和 right。 |
| 操作后刷新 | 元素操作支持 --snapshot，用于刷新 daemon 的缓存引用。文本输出报告刷新结果；加上 --json 可在结果中取得新快照。继续操作前，应读取并使用新快照中的目标。 |
| 等待页面条件 | wait --text "Ready" --timeout 15000 等待文本匹配；wait --ref <ref> 等待引用在新快照中解析成功。等待期间刷新并缓存快照，--timeout 和 --interval 的单位为毫秒。应用连接的 wait-for-client 则使用秒。 |
#日志与运行时调试选项
日志与运行时调试展示如何结合日志、已加载的脚本和运行时值，解释页面异常的原因。
| 操作 | 选项与行为 |
|---|---|
| 过滤日志 | get-console 支持 --level、--thread、--offset 和 --limit。级别用逗号分隔，例如 error,warning；线程可选 background 和 main，默认读取两个线程。 |
| 跟踪日志与保留调用栈 | get-console --watch 持续输出日志，直到中断或达到 --limit。--include-stack-traces 在格式化输出中保留非错误日志的可用调用栈。--json 保留可用调用栈；同时启用 --watch 时，每行输出一个 JSON 事件。 |
| 定位脚本与 UI 源码 | get-sources 列出后台 VM 中的脚本 ID 和 URL。get-source-info <target> 接受元素节点 ID 或 @e1 这样的快照引用；源码映射需要 UI source-map 元数据。 |
| 打开检查器 | inspect 输出选定 client/session 的检查器 URL。--port 指定 daemon 端口，默认值为 21783。 |
| 执行 JavaScript | evaluate <expression> 通过 --thread 选择 background（默认）或 main。支持 --await-promise、--context-id、--throw-on-side-effect，以及用 --no-return-by-value 返回远程对象。完整选项见 evaluate --help。 |
| 发送 CDP 请求 | cdp --method <method> '<json-params>' 向选定 session 发送方法和可选的 JSON 参数。--thread 默认值为 background；脚本和对象 ID 必须属于选定的 VM。 |
| 发送 App 请求 | app --client <clientId> --method <method> '<json-params>' 面向宿主应用，不选择页面 session。可用方法和参数取决于宿主应用。 |
#输出、帮助与环境变量
在提供相应选项的命令中，用 --client 和 --session 显式选择目标，用 --json 请求结构化输出。全局 JSON 偏好只会转发给支持 JSON 模式的命令。
| 环境变量 | 用途 |
|---|---|
AGENT_LYNX_FORCE_JSON | 设为 1 或 true，启用命令支持的 JSON 输出模式。 |
AGENT_LYNX_DISABLE_UPDATE_NOTICE | 设为 1，关闭 npm 更新提示。 |
AGENT_LYNX_INVOKED_AS | 由进程宿主设置面向用户的调用名称。 |
AGENT_LYNX_CLI_PLACEHOLDER | 帮助和恢复提示中调用名称的回退值。 |
ADB_SERVER_SOCKET | 直接连接模式（--no-daemon）的 Android ADB socket，优先于地址和端口。支持 tcp:host:port、tcp:port 和 localfilesystem:/path。 |
ANDROID_ADB_SERVER_ADDRESS、ANDROID_ADB_SERVER_PORT | 直接连接模式（--no-daemon）的 Android ADB server 主机和端口，默认值为 127.0.0.1 和 5037。daemon 模式会忽略它们，并在 stderr 输出警告。 |
DEBUG | 在 stderr 启用对应命名空间的诊断日志。 |