#程序化 API

agent-lynx 可以通过两种方式接入自动化脚本：

• CLI 子进程：从 Shell、Python、Node.js 等语言调用命令，解析 JSON 输出，再进行筛选、判断或保存结果。
• Connector API：在 JavaScript 或 TypeScript 中通过 agent-lynx/connector 连接应用，发送 CDP、App 请求或订阅事件。

以下示例都需要先按快速开始连接应用，并用 list-clients、list-sessions 获取目标页面的 ID。将它们设为环境变量：

export CLIENT_ID='<client-id>'
export SESSION_ID='<session-id>'

#通过子进程调用 CLI

安装 CLI 并确保脚本能从 PATH 找到 agent-lynx：

npm install -g agent-lynx

将 --json 放在命令前，请求机器可读输出。下面三种写法完成相同的任务：读取页面元素树，在后台 VM 中执行表达式获取全局属性的字段名，最后将两份结果保存为 page-report.json。

set -euo pipefail
target=(--client "$CLIENT_ID" --session "$SESSION_ID")

document=$(agent-lynx --json cdp --method DOM.getDocument \
  '{"depth":-1}' "${target[@]}")
props=$(agent-lynx --json evaluate \
  'Object.keys(lynx.__globalProps || {})' "${target[@]}")

jq -n --argjson document "$document" --argjson props "$props" '
  if $props.exceptionDetails then error($props.exceptionDetails | tostring)
  else {document: $document, globalPropKeys: $props.result.value}
  end
' > page-report.json

import json
import os
import subprocess
from pathlib import Path

def run(*args):
    result = subprocess.run(
        ["agent-lynx", "--json", *args,
         "--client", os.environ["CLIENT_ID"],
         "--session", os.environ["SESSION_ID"]],
        check=True, stdout=subprocess.PIPE, text=True,
    )
    return json.loads(result.stdout)

document = run("cdp", "--method", "DOM.getDocument", '{"depth":-1}')
props = run("evaluate", "Object.keys(lynx.__globalProps || {})")
if props.get("exceptionDetails"):
    raise RuntimeError(props["exceptionDetails"])
report = {"document": document, "globalPropKeys": props["result"]["value"]}
Path("page-report.json").write_text(json.dumps(report, indent=2), encoding="utf-8")

import { execFileSync } from 'node:child_process';
import { writeFileSync } from 'node:fs';

function run(...args) {
  return JSON.parse(execFileSync('agent-lynx', [
    '--json', ...args,
    '--client', process.env.CLIENT_ID,
    '--session', process.env.SESSION_ID,
  ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], maxBuffer: 16 * 1024 * 1024 }));
}

const document = run('cdp', '--method', 'DOM.getDocument', '{"depth":-1}');
const props = run('evaluate', 'Object.keys(lynx.__globalProps || {})');
if (props.exceptionDetails) throw new Error(JSON.stringify(props.exceptionDetails));
writeFileSync('page-report.json', JSON.stringify({
  document, globalPropKeys: props.result.value,
}, null, 2));

脚本检查进程退出状态，只解析 stdout；stderr 保留为诊断信息。Python 和 Node.js 使用参数数组传递命令，表达式和 JSON 参数不需要再做 Shell 转义。

JSON 结构由具体命令决定：cdp、evaluate 本身就输出 JSON；evaluate 的值位于 result.value，VM 执行异常通过 exceptionDetails 返回。snapshot --json 等命令则返回包含 ok、data 或 error 的结果。get-console --watch --json 是逐行 JSON 事件流，应逐行解析。更多选项见 CLI 参考。

#使用 Connector API

Connector API 适合在 JavaScript 或 TypeScript 脚本中复用连接、组合协议请求。先在项目中安装 agent-lynx：

npm install agent-lynx

下面通过 Connector 完成与 CLI 示例相同的页面检查，并保存为 page-report.json。使用前面设置的 CLIENT_ID 和 SESSION_ID，将脚本保存为 inspect-page.mjs，运行 node inspect-page.mjs：

import { writeFileSync } from 'node:fs';
import { createDefaultConnector, evaluateExpression } from 'agent-lynx/connector';

const connector = createDefaultConnector();
const clientId = process.env.CLIENT_ID;
const sessionId = Number(process.env.SESSION_ID);
if (!clientId || !Number.isInteger(sessionId)) {
  throw new Error('Set CLIENT_ID and SESSION_ID to the target page IDs.');
}

const document = await connector.sendCDPMessage(
  clientId, sessionId, 'DOM.getDocument', { depth: -1 },
);
const props = await evaluateExpression(
  connector, clientId, sessionId, 'Object.keys(lynx.__globalProps || {})',
);
if (props.exceptionDetails) throw new Error(JSON.stringify(props.exceptionDetails));

writeFileSync('page-report.json', JSON.stringify({
  document, globalPropKeys: props.result.value,
}, null, 2));

createDefaultConnector() 与 CLI 共享本地 daemon 管理的应用连接。sendCDPMessage 对选中的页面执行协议请求；evaluateExpression 默认在后台 VM 中执行，并准备页面对应的 lynx 上下文。结果直接返回为 JavaScript 对象，无需解析进程输出。

除了页面检查，还可以用 sendAppMessage 调用宿主能力，或用 sendCDPStream 组合输入事件、订阅运行时消息。更多用法见 lynx-community/skills 中的程序化使用介绍、Connector 详细示例和点击与双击示例。