nstbrowser-ai-agent

nstbrowser-ai-agent

此技能适用于 Nstbrowser 工作流。

默认运行模式

使用一个已验证可用的 Nstbrowser 配置文件，并在每条浏览器命令中重复使用同一个 --profile <name-or-id>。

• 对 AI Agent 来说，这是最安全的默认做法。
• 只有任务确实需要隔离的多步工作流时，才使用 --session。
• 在同一个守护进程会话中，--profile twitter1 必须切换到 twitter1；不要假设上一个配置文件仍处于活动状态。
• 不要假设导航后或切换到其他会话后，诸如 @e1 的引用仍然有效。

前置条件

• 已安装并运行 Nstbrowser 桌面客户端
• 已通过 nstbrowser-ai-agent config set key YOUR_API_KEY 或 NST_API_KEY 配置 API 密钥
• NST 服务可通过 http://127.0.0.1:8848 访问，除非用户配置了其他主机/端口

首要检查

当环境可能尚未配置时，先运行以下命令：

nstbrowser-ai-agent nst status
nstbrowser-ai-agent profile list
nstbrowser-ai-agent --version

快速路径

除非用户明确要求更专业的操作，否则使用此路径：

nstbrowser-ai-agent nst status
nstbrowser-ai-agent profile list
nstbrowser-ai-agent verify --profile YOUR_PROFILE
nstbrowser-ai-agent --profile YOUR_PROFILE open https://example.com
nstbrowser-ai-agent --profile YOUR_PROFILE snapshot -i
nstbrowser-ai-agent --profile YOUR_PROFILE click @e1
nstbrowser-ai-agent --profile YOUR_PROFILE get url
nstbrowser-ai-agent --profile YOUR_PROFILE screenshot --annotate /tmp/page.png

将 YOUR_PROFILE 替换为 profile list 中的配置文件。

如果你还没有干净的配置文件：

nstbrowser-ai-agent profile create task-profile
nstbrowser-ai-agent --profile task-profile open https://example.com

NST 核心命令

配置

nstbrowser-ai-agent config set key YOUR_API_KEY
nstbrowser-ai-agent config show
nstbrowser-ai-agent config get key

诊断

仅使用以下形式：

nstbrowser-ai-agent nst status
nstbrowser-ai-agent profile list
nstbrowser-ai-agent verify YOUR_PROFILE
nstbrowser-ai-agent verify --profile YOUR_PROFILE
nstbrowser-ai-agent repair

配置文件管理

• profile list 需要快速查看易读的候选配置文件列表时使用。 重要参数：--verbose 返回完整的 NST 配置文件对象，而不是精简摘要。

• profile list-cursor --page-size <size> [--cursor <token>] [--direction next|prev] 配置文件较多且需要确定性分页时使用。 --page-size 限制每页条数。 --cursor 从先前返回的游标继续。 --direction 告知 NST 该游标对应下一页还是上一页。

• profile show <name-or-id> 需要查看某个配置文件的准确分组、代理、标签、平台或上次启动信息时使用。

• profile create <name> [--platform <Windows|macOS|Linux>] [--kernel <version>] [--group-id <id>] 需要为新任务创建一个干净的配置文件时使用。 --kernel 请求使用首选的内核里程碑版本；NST 可能会将其规范化为当前支持的版本。 可选代理参数： --proxy-host <host>、--proxy-port <port>、--proxy-type <http|https|socks5>、--proxy-username <user>、--proxy-password <pass>。

• profile proxy show <name-or-id> 代理行为看起来异常，需要检查已保存的代理配置和上次代理检查结果时使用。

• profile proxy update <name-or-id> --host <host> --port <port> [--type <type>] [--username <user>] [--password <pass>] 配置文件需要保留相同的 Cookie/历史记录，但切换到其他代理时使用。

• profile proxy reset <name-or-id> [name-or-id...] 配置文件需要恢复为本地/默认路由时使用。

• profile tags list、profile tags create、profile tags update、profile tags clear 需要为重复的 Agent 工作流整理配置文件时使用。 profile tags create 只需要标签名称；CLI 会自动填入默认标签颜色。

• profile groups list、profile groups change <group-id> <name-or-id> [name-or-id...] 需要查找有效的 NST 分组 ID 或将配置文件移入指定分组时使用。

浏览器管理

• browser list 当你需要查看当前正在运行的配置文件浏览器或临时浏览器时使用。

• browser start <name-or-id> [--headless] [--auto-close] 当你希望在首次 open 之前启动浏览器时使用。 --headless 请求以无头模式启动。 --auto-close 请求 NST 在浏览器所属进程退出时关闭该浏览器。

• browser pages <name-or-id> 当你需要查看某个运行中浏览器当前可调试的页面时使用。

• browser debugger <name-or-id> 当你需要调试器端口和浏览器级 WebSocket 端点时使用。

• browser cdp-url <name-or-id> 当你只需要浏览器级 CDP WebSocket URL 时使用。

• browser connect <name-or-id> 当你希望 NST 在需要时启动浏览器并立即返回连接信息时使用。

• browser start-once [--platform <platform>] [--kernel <kernel>] [--headless] [--auto-close] 仅用于不应保存在已保存配置文件中的一次性任务。

• browser cdp-url-once 当临时浏览器足以满足需求，且你只需要其 CDP URL 时使用。

• browser connect-once [--platform <platform>] [--kernel <kernel>] 当你希望一条命令同时创建临时浏览器并返回 CDP 连接信息时使用。

• browser stop <name-or-id> 和 browser stop-all 用于在任务完成后清理，或清除已过期的浏览器。

何时使用哪条 NST 命令

• 当环境本身可能出现故障时，先使用 nst status。
• 当你只需要配置文件名称以快速开始工作时，使用 profile list。
• 当工作区中的配置文件太多，无法一次列出时，使用 profile list-cursor。
• 当问题涉及某个特定配置文件的配置时，使用 profile show。
• 当配置文件可能已过期或不可信时，在正式工作前使用 verify。
• 当 verify 报告浏览器状态已过期或多次连接失败时，使用 repair。
• 当你希望明确控制浏览器启动时，使用 browser start。
• 当目标是执行任务而非管理时，直接在浏览器操作中使用 --profile <name-or-id>。

浏览器操作

所有浏览器操作都可以使用 --profile <name-or-id>。其值可以是配置文件名称或 UUID。

推荐工作流

优先使用此工作流，而非临时浏览器：

nstbrowser-ai-agent --profile YOUR_PROFILE open https://example.com
nstbrowser-ai-agent --profile YOUR_PROFILE snapshot -i
nstbrowser-ai-agent --profile YOUR_PROFILE click @e1
nstbrowser-ai-agent --profile YOUR_PROFILE get url
nstbrowser-ai-agent --profile YOUR_PROFILE screenshot --annotate /tmp/page.png
nstbrowser-ai-agent browser stop YOUR_PROFILE

会话工作流

仅当用户明确需要隔离环境或由守护进程支持的较长运行时才使用此工作流。每条相关命令都使用相同的 --session 和 --profile。

如果任务需要在同一个 --session 中切换到另一个 Nstbrowser 配置文件，请在切换命令中明确重复指定新的 --profile。

nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE open https://example.com
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE snapshot -i
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE click @e1
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE tab new https://iana.org
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE get url

临时浏览器工作流

仅当用户需要一次性浏览器且不需要持久化配置文件时，才使用 browser start-once：

nstbrowser-ai-agent browser start-once
nstbrowser-ai-agent open https://example.com
nstbrowser-ai-agent snapshot -i

close 只会停止现有浏览器；它不会启动或创建浏览器。使用 close --profile <name-or-id>，通过 Agent API 停止指定的 NST 配置文件浏览器。 如果会话上下文不可用，不带参数的 close 会停止唯一正在运行的 Agent 浏览器；如果有多个浏览器正在运行，则必须指定 --profile。

实用全局选项

--profile <name-or-id>   Use a specific Nstbrowser profile
--session <name>         Use an isolated daemon session
--session-name <name>    Auto-save and restore browser state
--json                   Machine-readable output
--headers <json>         Scoped HTTP headers for the opened origin
--proxy <server>         Override proxy for the launched browser session
--proxy-bypass <hosts>   Bypass proxy for specific hosts
--annotate               Add numbered labels to screenshot output
--full                   Full-page screenshot

推荐模式

1. 如果环境有任何不明确之处，请先运行 nst status 和 profile list。
2. 优先在 click 或 fill 之前使用 snapshot -i，以确保引用是最新的。
3. 除非有意使用专用的 --session，否则每条浏览器命令都重复指定相同的 --profile。
4. 仅在需要隔离工作流时使用 --session；此时整个运行过程中都要保持 --session 和 --profile 一致。
5. 如果 NST 报告浏览器状态已过期或存在多个卡住的实例，请在重试前使用 repair。
6. 如果现有配置文件的代理或网络设置有问题，优先使用干净的或新建的配置文件。

常见故障恢复

• Profile not found：运行 profile list，并使用准确的配置文件名称或 UUID。
• @e1 not working：重新运行 snapshot -i，因为导航后引用会发生变化。
• 引用取决于顺序：先生成引用，再在同一会话中使用。
• @e1 被视为 CSS：你可能更改了配置文件或会话上下文，或者忘记再次传入相同的 --profile。
• Browser not running：运行 browser start <name-or-id>，或重新运行 open。
• NST agent not responding：启动 Nstbrowser 桌面客户端，然后运行 nst status。
• Command appears stale：使用新的 --session 名称，或运行 browser stop <name-or-id> / browser stop-all。
• open https://example.com 打开的是 Chrome 错误页面：切换到干净的配置文件或新建一个，因为当前配置文件的代理可能已损坏。

注意事项

• browser start-once 会创建一个由 Nstbrowser 管理的临时浏览器。
• 由配置文件支持的会话会将 Cookie 和网站存储保存在 Nstbrowser 配置文件中。
• --profile 仅用于选择 Nstbrowser 配置文件。