AI导哈

浏览器自动化工具

AgentChrome是一个基于Chrome DevTools Protocol的CLI工具，专为AI代理设计，提供浏览器自动化功能，支持JSON输出和程序化错误处理。

  • by Nunley-Media-Group
  • Rust
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 Nunley-Media-Group/chrome-cli

使用说明

AgentChrome

赋予你的AI代理浏览器超能力。

AgentChrome是一个通过Chrome DevTools协议实现浏览器自动化的原生CLI工具，专为Codex等AI编码代理设计。每个命令都输出结构化的JSON，使用可访问性树UID进行元素定位，并返回键入的退出代码进行编程错误处理。没有Node.js，没有Python，没有MCP服务器——你的代理从shell调用的只是一个快速的Rust二进制文件。

食品法典整合

1.安装AgentChrome （参见 安装 更多选项）

cargo install agentchrome

2.将AgentChrome指南添加到食品法典委员会

agentchrome skill install --tool codex

这将AgentChrome Codex技能写入 $CODEX_HOME/skills/agentchrome/SKILL.md，或 ~/.codex/skills/agentchrome/SKILL.md 当 CODEX_HOME 未设置。AgentChrome通过以下方式进行自我记录 agentchrome --help, agentchrome capabilities，以及 agentchrome examples，因此Codex可以直接从安装的二进制文件中发现当前的CLI界面。

对于项目本地指导，您还可以添加AGENTS模板：

curl -fsSL https://raw.githubusercontent.com/Nunley-Media-Group/AgentChrome/main/examples/AGENTS.md.example > AGENTS.md

3.要求Codex使用浏览器

“检查localhost:3000上的登录表单是否正常工作”

在幕后，Codex将运行以下命令：

agentchrome connect --launch --headless
agentchrome navigate http://localhost:3000/login --wait-until networkidle
agentchrome page snapshot
agentchrome form fill-many '[{"uid": "s2", "value": "test@example.com"}, {"uid": "s3", "value": "password123"}]'
agentchrome interact click s4 --include-snapshot
agentchrome console read --errors-only

查看完整 食品法典整合指南 用于工作流、效率提示和错误处理模式。

对于AgentChrome内置技能安装程序支持的代理工具，请使用 agentchrome skill install 编写特定于工具的指导文件，以及 agentchrome skill update 升级AgentChrome后。支持的目标包括Claude Code、Windsurf、Aider、Continue.dev、GitHub Copilot、Cursor、Gemini CLI和Codex；Codex用户可以明确地将其作为目标 agentchrome skill install --tool codex.

特性

专为AI代理构建

  • 默认JSON输出 --每个命令都返回结构化、可解析的输出
  • 带有UID的可访问性树快照 — page snapshot 分配稳定的UID（例如。， s1, s5)互动元素，实现可靠瞄准
  • 结构化退出代码 --0（成功）、1（一般错误）、2（连接错误）、3（目标错误）、4（超时）、5（协议错误）用于程序错误处理
  • 自文档化CLI — agentchrome capabilities 输出每个命令、标志和参数的机器可读JSON清单
  • --include-snapshot 关于互动 --在与点击或填写表单相同的响应中获取更新的可访问性树，将往返次数减半
Full Browser Control
  • 选项卡管理 --列出、创建、关闭和激活浏览器选项卡
  • URL导航 --导航到URL、后退/前进、使用等待策略重新加载
  • 页面检查 --可访问性树、文本提取、元素搜索
  • 截图 --全页、视口、元素或区域捕获
  • JavaScript执行 --在页面上下文中运行脚本，返回JSON格式的结果
  • 用户交互 --单击、悬停、拖动、键入、按键、滚动、基于坐标的拖动和分解鼠标动作
  • 填表 --填写输入、选择选项、上传文件、批量填写 fill-many，ARIA组合框支持
  • Iframe/帧定位 --列表框架，目标特定的iframe --frame 在所有命令上，都支持跨源OOPIF
  • 媒体控制 --使用CSS选择器或批量定位列出、播放、暂停、查找音频/视频元素
  • 页面分析 --通过iframe检测、框架识别、覆盖/阻止检测和点击调试命中测试进行结构发现
  • DOM事件自检 --通过CDP检查任何元素上的事件侦听器
  • Cookie管理 --列出、设置、删除和清除浏览器Cookie
  • 网络监控 --实时列出、检查和跟踪请求
  • 控制台捕获 --使用类型筛选读取和跟踪控制台消息
  • 设备仿真 --移动设备、网络/CPU限制、地理位置、配色方案
  • 性能跟踪 --记录痕迹、分析见解、衡量核心网络生命
  • 灯塔审计 --运行审核，通过过滤返回结构化类别分数
  • 对话框处理 --接受、取消或响应警报/确认/提示对话框

比较

AgentChrome如何为AI代理提供浏览器访问权限：

AgentChrome 木偶师/编剧 Chrome DevTools MCP
AI代理集成 CLI——适用于运行shell命令的任何代理 需要JavaScript包装器 MCP协议（需要特定的客户端）
运行时 没有Node.js--原生Rust二进制 Node.js Node.js
安装 单个二进制， cargo install npm install npx
接口 CLI/shell脚本 JavaScript API MCP协议
启动时间 <50ms ~500ms+ 变化
二进制大小 <10 MB ~100 MB+（含存款） 各不相同
壳牌管道 头等舱(` jq, grep`)

建筑

Agent → CLI (clap) → Command Dispatch → CDP Client (WebSocket) → Chrome (DevTools Protocol)

AgentChrome使用 Chrome 开发者工具协议 （CDP）通过WebSocket。跑 agentchrome connect --launch --headless 启动会话——后续命令会自动重用连接。原生Rust二进制文件，启动时间<50ms，磁盘空间<10MB。

安装

货物安装

cargo install agentchrome

预构建二进制文件

从以下网址下载适用于您平台的最新版本 GitHub发布.

Quick install via curl (macOS / Linux) 
# macOS (Apple Silicon)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-aarch64-apple-darwin.tar.gz \
  | tar xz && mv agentchrome-*/agentchrome /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-x86_64-apple-darwin.tar.gz \
  | tar xz && mv agentchrome-*/agentchrome /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-x86_64-unknown-linux-gnu.tar.gz \
  | tar xz && mv agentchrome-*/agentchrome /usr/local/bin/

# Linux (ARM64)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-aarch64-unknown-linux-gnu.tar.gz \
  | tar xz && mv agentchrome-*/agentchrome /usr/local/bin/
Build from source 
git clone https://github.com/Nunley-Media-Group/AgentChrome.git
cd AgentChrome
cargo build --release
# Binary is at target/release/agentchrome

支持的平台

平台 目标 存档
macOS（苹果硅） aarch64-apple-darwin .tar.gz
macOS（英特尔） x86_64-apple-darwin .tar.gz
Linux（x86_64） x86_64-unknown-linux-gnu .tar.gz
Linux（ARM64） aarch64-unknown-linux-gnu .tar.gz
Windows（x86_64） x86_64-pc-windows-msvc .zip

CLI快速入门

对于shell脚本和手动使用：

1.安装AgentChrome （参见 安装 以上）

2.在启用远程调试的情况下启动Chrome：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Or launch headless Chrome directly via AgentChrome:
agentchrome connect --launch --headless

3.连接到Chrome浏览器：

agentchrome connect

4.导航到URL：

agentchrome navigate https://example.com

5.检查页面：

agentchrome page snapshot

命令参考

命令 描述
connect 连接或启动Chrome实例
tabs 选项卡管理（列表、创建、关闭、激活）
navigate URL导航和历史记录
page 页面检查（屏幕截图、文本、可访问性树、查找、分析、点击测试、框架、工作人员）
dom DOM检查、操作和事件侦听器自检
js 页面上下文中的JavaScript执行
console 控制台消息读取和监控
network 网络请求监控和拦截
interact 鼠标、键盘、滚动和基于坐标的拖动交互
form 表单输入、提交和ARIA组合框支持
emulate 设备和网络仿真
perf 性能跟踪和指标
cookie 浏览器cookie管理（列表、设置、删除、清除）
dialog 浏览器对话框处理（警报、确认、提示、卸载前）
media 媒体元素控制（列表、播放、暂停、搜索）
audit 对当前页面（Lighthouse）运行审核
diagnose 自动化前挑战扫描（iframe、覆盖、媒体门、框架、模式）
skill 代理工具技能安装与管理
config 配置文件管理（show、init、path）
completions 生成shell完成脚本
examples 显示命令的使用示例
capabilities 输出所有CLI功能的机器可读清单
man 显示AgentColor命令的手册页

跑 agentchrome <command> --help 为了详细使用， agentchrome examples <command> 作为实例，或 agentchrome capabilities 以获取完整的机器可读命令清单。

会话弹性

长时间运行的自动化会话在没有人工干预的情况下，能够经受住短暂的WebSocket掉线和空闲超时。

自动重新连接。 当命令被存储时 ws_url 不再可访问，但Chrome仍在记录的端口上运行，AgentChrome透明地重新发现当前浏览器级别的WebSocket URL，重写会话文件（保留 pid, port，以及 active_tab_id)，并在同一调用中重试该命令。诊断仅限于stderr；stdout保持纯JSON。

活下去。 当命令使CDP会话保持打开状态的时间长于保持活动间隔（默认值 30000 ms），AgentChrome发送WebSocket Ping帧以防止空闲超时断开连接。10秒内缺少Pong会触发现有的重新连接路径。

配置优先级： --keepalive-interval <ms> 旗帜> AGENTCHROME_KEEPALIVE_INTERVAL 谁是 > [keepalive] interval_ms 在 config.toml >内置默认值（30000毫秒）。

# Run a long command with a 60-second keep-alive
agentchrome --keepalive-interval 60000 console follow

# Disable keep-alive (--no-keepalive or interval 0)
agentchrome --no-keepalive page snapshot --json

针对连接丢失错误编写脚本。 当自动重新连接无法恢复会话时，CLI会在stderr上发出结构化JSON错误，错误为 kind 鉴别器和a recoverable 布尔值：

条件 kind recoverable 建议补救措施
Chrome进程消失了 "chrome_terminated" false agentchrome connect --launch
探测失败，但Chrome可能仍然有效 "transient" true agentchrome connect

脚本可以在这些字段上分支，以决定是重新启动Chrome还是只是重新发现连接。

用法示例

Page inspection 
# Get the accessibility tree with element UIDs
agentchrome page snapshot

# Extract visible text content
agentchrome page text

# Find elements by text or role
agentchrome page find "Submit" --role button
Form filling 
# Snapshot to discover form field UIDs
agentchrome page snapshot

# Fill multiple fields at once (returns updated snapshot)
agentchrome form fill-many --include-snapshot \
  '[{"uid": "s5", "value": "hello@example.com"}, {"uid": "s8", "value": "MyPassword123"}]'

# Or fill fields individually
agentchrome form fill s5 "hello@example.com"

# Click the submit button
agentchrome interact click s10
Screenshots 
# Viewport screenshot
agentchrome page screenshot --file screenshot.png

# Full-page screenshot
agentchrome page screenshot --full-page --file full-page.png
JavaScript execution 
# Run a JavaScript expression and get the result
agentchrome js exec "document.title"

# Run JavaScript from a file
agentchrome js exec --file script.js
Network monitoring 
# List recent network requests
agentchrome network list

# Filter requests by URL pattern
agentchrome network list --filter "api"

# Get details for a specific request
agentchrome network get <request-id>
Pre-automation diagnostics 
# Scan a new URL for automation challenges before you begin
agentchrome diagnose https://example.com/course

# Diagnose the already-loaded page in place (no navigation)
agentchrome diagnose --current

# Extract strategy suggestions for each matched pattern
agentchrome diagnose --current | jq -r '.patterns[].suggestion'

# Check if the page is straightforward to automate
agentchrome diagnose --current | jq '.summary.straightforward'
Interaction strategy guides 
# List all scenario-based interaction strategy guides
agentchrome examples strategies

# Show the full guide for iframe automation
agentchrome examples strategies iframes

# Get all strategy guides as JSON (for AI agent discovery)
agentchrome examples strategies --json

# Get the full SCORM/LMS strategy as JSON
agentchrome examples strategies scorm --json

可用策略： iframes, overlays, scorm, drag-and-drop, shadow-dom, spa-navigation-waits, react-controlled-inputs, debugging-failed-interactions, authentication-cookie-reuse, multi-tab-workflows.

相关项目

  • Chrome DevTools MCP服务器 --如果您需要基于MCP的浏览器控制而不是CLI工具，请使用CDP支持的MCP服务器。

贡献

看 贡献.md 针对项目特定的问题、规范、指导、实施和验证期望。

所有捐款必须遵循 NMG-SDLC 工作流程无偏差。NMG-SDLC是一个BDD规范驱动的开发工具包，它强制执行结构化的交付生命周期：问题创建、规范编写、实施、验证和PR创建。不接受绕过SDLC流程的捐款。

先决条件

  • 锈 1.93.0或更高版本（通过固定 rust-toolchain.toml)
  • Chrome或Chromium（用于集成测试）
  • 食品法典委员会 NMG-SDLC插件 安装

构建与测试

git clone https://github.com/Nunley-Media-Group/AgentChrome.git
cd AgentChrome

# Build
cargo build

# Run tests
cargo test

# Lint
cargo clippy -- -D warnings
cargo fmt --check

# Generate man pages
cargo xtask man

代码风格

此项目使用严格的Clippy配置(all = "deny", pedantic = "warn")以及2024年版的rustfmt。合并前必须解决所有警告。

许可证

根据以下任一许可 MIT许可证 或 Apache许可证，版本2.0 由您选择。

相关 MCP