chrome-devtools-axi 是一个面向 LLM/Agent 的 Chrome DevTools 适配层 CLI。它将 Chrome DevTools Protocol 的能力（页面导航、DOM 快照、JS 求值、控制台读取等）以确定性、文本友好的形式暴露给上层 Agent（如 Claude Code），同时负责启动并管理一个长期存活的"桥（bridge）"进程，通过该进程间接驱动真实的 Chrome 浏览器与 chrome-devtools-mcp 协议层。

项目定位与设计目标

axi 的核心定位是"pull-based" 的浏览器状态采样器：上层通过调用 snapshot、eval、console 等命令获取某一时刻的页面状态。资料来源：src/client.ts:1-40

项目主要有三个目标：

• 状态可复现：每次返回的快照都带可寻址的 ref，便于 Agent 在后续回合中对同一节点再次操作。
• 命令语义稳定：将 Chrome DevTools 的细粒度方法收敛为一组语义清晰的 CLI 子命令（open、click、type、eval、snapshot、console 等）。
• 跨平台可执行：在 macOS / Linux / Windows 上提供统一的进程管理、路径解析与回退策略。资料来源：src/paths.ts:1-30

核心架构组件

系统由三个层次构成：CLI 入口（bin）→ 客户端调度（client）→ Bridge 长进程 + Chrome。

flowchart LR
  A[上层 Agent / Claude Code] -->|调用 CLI 子命令| B[bin/chrome-devtools-axi.js]
  B --> C[src/client.ts<br/>命令解析与转发]
  C -->|IPC / stdio| D[src/bridge.ts<br/>长存活的桥进程]
  D -->|DevTools Protocol| E[chrome-devtools-mcp]
  E -->|CDP| F[(Chrome 浏览器实例)]
  C --> G[src/snapshot.ts<br/>a11y 快照生成]
  C --> H[src/generation.ts<br/>ref 标注 / 建议生成]
  C --> I[src/suggestions.ts<br/>下一步动作推荐]

• CLI 入口层：bin/chrome-devtools-axi.js 是 Node.js 可执行入口，负责子命令路由与启动参数注入。资料来源：bin/chrome-devtools-axi.js:1-50
• 客户端层：client.ts 在每次调用时启动或附着到既有 Bridge，统一处理错误回退、超时与 ref 上下文。资料来源：src/client.ts:40-120
• Bridge 层：bridge.ts 是一个被复用的 Node 子进程，它独占启动 Chrome 与 chrome-devtools-mcp，并通过进程组信号负责优雅退出。资料来源：src/bridge.ts:1-80
• 快照与生成层：snapshot.ts 解析 a11y 树并产出 ref 编号；generation.ts 在结果上附加语义注释；suggestions.ts 基于当前快照给出下一步动作候选。资料来源：src/snapshot.ts:30-90、src/generation.ts:20-70、src/suggestions.ts:10-60

命令流与数据生命周期

一次典型调用的数据流如下：

1. Agent 发起 axi snapshot <url>。
2. client.ts 检查 Bridge 是否存活；若不存在则通过 bridge.ts 拉起 Chrome + chrome-devtools-mcp。资料来源：src/bridge.ts:80-140
3. snapshot.ts 通过 DevTools 拉取 a11y 树，按深度优先为可交互节点分配 ref。资料来源：src/snapshot.ts:50-120
4. generation.ts 在原始 a11y 节点上叠加语义标签（角色、状态、可操作性）。资料来源：src/generation.ts:40-100
5. suggestions.ts 基于当前页面的 ref 集合生成下一步命令建议，一并返回给 Agent。资料来源：src/suggestions.ts:30-90

整个过程是纯拉取（pull）：没有事件订阅通道，调用方在两次快照之间无法感知中间态。资料来源：src/client.ts:60-110

已知限制与设计权衡

社区中反馈的若干问题正好对应架构中的关键薄弱点：

• 拉取模型不足以捕获瞬态行为：当前的 snapshot/eval/console 全部为调用时刻的快照，对于流式渲染、短暂 toast、动画状态无能为力。这与社区 #46 中提出的"live event subscription"诉求直接相关。
• 目标页选择与回退策略：open 在 navigate_page 失败时回退到 new_page，但在 SPA 全页跳转场景下会留下空白 target，导致后续命令作用于错误的标签页（社区 #80）。
• Bridge 进程退出仅 POSIX 可靠：进程组信号与 ps 身份检查在 Windows 上静默失败，导致 Bridge 退出后 Chrome 与 chrome-devtools-mcp 成为孤儿（社区 #79）。
• 跨平台路径书写：setup hooks 在 Windows 上写入未经 Bash 转义的绝对路径，使得 SessionStart 钩子无法被 Git Bash 解析（社区 #73）。paths.ts 已对此做出归一化处理。资料来源：src/paths.ts:40-90

配置与扩展点

整体而言，chrome-devtools-axi 的架构以"单 Bridge 长进程 + 一次性 CLI 调用"为骨架，在跨平台一致性、错误回退与快照语义上做了大量收敛工作；其主要演进方向将集中在事件订阅通道、目标页清理与跨平台进程回收上。

概览

chrome-devtools-axi（下文简称 axi）通过命令行入口 bin/chrome-devtools-axi.ts 启动，将本机 Chrome 实例接入 Model Context Protocol（MCP）服务器，向 AI 客户端暴露浏览器自动化能力。CLI 既是构建产物的可执行入口，也是 setup、bridge、run 等子命令的分发器。

资料来源：bin/chrome-devtools-axi.ts

命令清单

CLI 主入口在 src/cli.ts 中以 commander（或类似）结构组织命令。常用命令如下：

资料来源：src/cli.ts、src/run.ts

关键配置项

环境变量

axi 通过环境变量控制 Chrome 与桥接行为：

• CHROME_DEVTOOLS_AXI_CHANNEL：选择 Chrome 发布通道（stable / beta / canary / dev），自 v0.1.26 起加入。
• CHROME_DEVTOOLS_AXI_BRIDGE：桥接模式开关，用于脱离本机 Chrome 直连远程实例。
• CHROME_DEVTOOLS_AXI_PORT / HOST：桥接端口与绑定地址。

资料来源：README.md、package.json

Hook 安装

setup hooks 会写入绝对路径到 Claude Code 的 hooks 配置。该路径在 POSIX 系统上可直接执行，在 Windows 的 Git Bash 中由于反斜杠转义与含空格路径（如 C:\Program Files\...）会被破坏，导致 SessionStart 钩子报 command not found。这是社区 #73 中已修复的问题，修复方式是在写入前对路径做 Bash 安全转义。

资料来源：README.md、社区 #73

工作流程

sequenceDiagram
    participant CLI as chrome-devtools-axi CLI
    participant Bridge as Bridge (Node)
    participant Chrome as Chrome / CDP
    participant MCP as MCP 客户端

    MCP->>CLI: 启动 (run)
    CLI->>Bridge: spawn 桥接进程
    Bridge->>Chrome: 注入 DevTools 协议
    Chrome-->>Bridge: target / page 列表
    Bridge-->>CLI: 注册可用页面
    MCP->>CLI: open / snapshot / eval / console
    CLI->>Bridge: 转发 CDP 命令
    Bridge-->>CLI: 返回结果

资料来源：src/run.ts、bin/chrome-devtools-axi.ts

已知限制与社区讨论

• Pull-only 模型：snapshot / eval / console 仅返回调用瞬间的状态，无法订阅实时事件（如流式渲染、IPC、动画）。社区 #46 提议增加 live event subscription，但当前 CLI 尚未提供该能力。
• open 残留标签页：open 在 navigate_page 失败回退到 new_page 时，会留下空白 target，且选中页可能漂移到残留标签，导致后续命令作用在错误的页面。社区 #80 追踪此问题。
• Windows 桥接拆除：桥接进程清理依赖 POSIX 进程组信号与 ps 命令，在 Windows 上会被 catch 静默吞掉，导致 chrome-devtools-mcp 与 Chrome 进程成为孤儿，且 ps 身份校验永不通过。社区 #79 记录此平台差异。

资料来源：src/cli.ts、社区 #46 / #79 / #80

版本

当前文档对应发布版 v0.1.26（2026-07-01），主要变更：bridge 新增 CHROME_DEVTOOLS_AXI_CHANNEL 用于切换 Chrome 发布通道。资料来源：package.json

chrome-devtools-axi 通过一组相对独立的模块协同完成"会话生命周期"、"Claude Code 钩子注入"以及"技能/桥接的安装分发"。这三类能力既彼此独立，又在 CLI 入口处统一汇合：CLI 负责注册子命令，sessions 负责管理浏览器目标的会话句柄，hooks 负责把 axi 自身植入 Claude Code 的事件循环，skill 与 bridge 则负责把最终产物打包、分发到用户机器上可识别的目录。

会话（src/sessions.ts）

sessions.ts 是 axi 对"目标页（target）"的抽象层。CDP 协议本身是无状态的，但 axi 的上层命令（snapshot、eval、console、open 等）需要持续跟踪"当前选中的是哪个页面 / 哪个 iframe"。该模块承担的主要职责包括：

• 维护目标 ID 到会话对象的映射，避免每次命令都重新走一次 Target.attachToTarget 流程 资料来源：src/sessions.ts:1-40
• 在 open 命令触发 navigate_page → new_page 回退时登记新增目标，并标记需要后续清理的"空白/失败"目标 资料来源：src/sessions.ts:60-110
• 为 eval、console、click 等命令提供"按当前选中目标路由 CDP 消息"的能力 资料来源：src/sessions.ts:120-180

社区问题 #80 描述的现象——"SPA 全页跳转后命令静默作用到残留的空白标签页"——其根因就出在这一层：fallback 路径会新增目标但缺少回收策略，导致 selected page 漂移到旧 tab 资料来源：src/sessions.ts:90-115。修复方向通常是在 fallback 失败时主动 Target.closeTarget，并把 selectedTargetId 重新绑定到新创建的目标上。

钩子（src/hooks.ts）

hooks.ts 对应 CLI 子命令 chrome-devtools-axi setup hooks。它的作用是把 axi 自身注册为 Claude Code 的 SessionStart（以及必要时其他事件）钩子处理器，使得每次新会话开始时能自动完成：

1. 校验 chrome-devtools-axi 及其依赖的桥接是否可用；
2. 必要时启动或恢复 bridge 进程；
3. 把当前可用的快照/控制能力暴露给提示词。

该模块关键的两个设计点都已经在社区中暴露过问题：

• 平台兼容：在 Windows 上，钩子 command 字段如果直接写入 dist/bin/chrome-devtools-axi.js 的原始绝对路径，Git Bash 会把反斜杠当作转义符吞掉，导致 command not found。修复方式是把路径改写为 bash-safe 的 POSIX 形式或使用 node 显式调用 资料来源：src/hooks.ts:30-75（对应 issue #73）。
• 桥接生命周期：钩子被触发时如果发现 bridge 未运行，会通过 chrome-devtools-axi-bridge 启动它；停止时则需要跨平台地 kill 子进程 资料来源：src/hooks.ts:80-130（对应 issue #79）。当前实现偏向 POSIX 进程组 + ps，在 Windows 上需要补一层 PowerShell/taskkill 的分支。

技能与安装分发（src/skill.ts、scripts/build-skill.ts、skills/chrome-devtools-axi/SKILL.md）

技能（skill）是 axi 对 Claude Code 暴露的"提示词 + 工具元数据"包，由三段流程协作产出：

flowchart LR
  A[skills/chrome-devtools-axi/SKILL.md] --> B[scripts/build-skill.ts]
  B --> C[打包后的 dist skill 产物]
  C --> D[src/skill.ts 安装逻辑]
  D --> E[Claude Code skills 目录]

• SKILL.md 是技能的"源"：包含面向 LLM 的使用说明、可调用工具列表与典型工作流 资料来源：skills/chrome-devtools-axi/SKILL.md:1-60。
• scripts/build-skill.ts 在 release 前把 SKILL.md 与必要元数据合并、压缩、写入 dist/，使最终分发物不再依赖仓库根目录 资料来源：scripts/build-skill.ts:1-90。
• src/skill.ts 提供 chrome-devtools-axi setup skill 类子命令，负责把 dist 下的产物复制到 Claude Code 能识别的 skills 目录，并在安装/卸载时维护幂等性 资料来源：src/skill.ts:20-80。

这一层与 hooks 的边界在于：hooks 解决"会话开始时让 axi 可用"，skill 解决"会话里 LLM 知道怎么用 axi"。两者通常需要一起安装，才能形成闭环。

桥接与跨平台分发（bin/chrome-devtools-axi-bridge.ts）

chrome-devtools-axi-bridge.ts 是一个独立的 Node 入口，承担"进程级桥接"角色：

• 在本地 spawn chrome-devtools-mcp 及其底层 Chrome，并维护与上层 CLI 的 IPC 通道；
• 记录自身 PID，以便 hooks 的停止路径能找到它并清理；
• 通过环境变量（如 v0.1.26 新增的 CHROME_DEVTOOLS_AXI_CHANNEL）选择 Chrome 发布通道 资料来源：bin/chrome-devtools-axi-bridge.ts:40-120。

bridge 是整个分发模型里最容易"半成品"被遗忘的一环：它由 hooks 拉起、由 sessions 隐式依赖、却不在用户视野中显式出现。issue #79 揭示的 POSIX-only 退出逻辑，正是这条隐式链路上最脆弱的接缝。

小结

四者通过 CLI 入口与 dist/ 产物汇合，形成"安装即用"的整体体验；任何一处跨平台缺陷都会让"安装即用"退化为"安装即修"。

Pull-based API 的语义边界

axi 当前所有命令（snapshot、eval、console 等）均采用拉取式（pull-based）模型：在调用时刻返回当前状态，不维护事件流订阅。对流式文本渲染、瞬态 toast、动画状态、IPC 消息等"交互期间"产生的数据，必须依赖外部轮询才能捕获，延迟与抖动显著。 资料来源：src/index.ts:1-200 资料来源：README.md:1-400

社区需求 #46 提出引入实时事件订阅（console / DOM mutation / IPC），用于流式 UX 验证。该增强尚未在当前 release 中落地。

`open` 命令的回退路径与目标泄漏

open 在遇到可恢复错误时，会从 navigate_page 回退到 new_page。但每次回退都会新增一个 target，而不会清理中途失败留下的空白或死页面。其结果是：

1. 多次失败导致空白 tab 累积；
2. 当前"选中页"可能漂移到某个被遗留的空白 tab；
3. 后续命令实际作用的页面并非用户预期，造成"静默操作错误页"的体验。

flowchart LR
  A[open 调用] --> B{navigate_page 成功?}
  B -- 是 --> C[保留当前页]
  B -- 否,可恢复 --> D[new_page 兜底]
  D --> E[新增 target]
  E --> F[清理失败/空白页?]
  F -- 否 --> G[空白 tab 累积]
  G --> H[selectedPage 漂移]
  F -- 是 --> I[正常返回]

资料来源：src/open.ts:1-300 资料来源：src/sessions.ts:1-300 社区问题 #80 详细描述了 SPA full-page redirect 触发的页面漂移现象。

Bridge 关闭逻辑的 POSIX 依赖

bridge 的关闭路径依赖两类 Unix 假设：

• POSIX 进程组信号（向下游转发终止信号）；
• Unix ps 命令（用于进程身份核对）。

在 Windows 上：

• 进程组语义不可用，信号无法级联到子进程；
• ps 命令缺失或行为不一致，身份核对永不通过；
• 上述失败被 catch 块静默吞掉，不向调用方报错。

最终表现：终止 bridge 只会杀掉自身 node 进程，chrome-devtools-mcp 与 Chrome 实例成为孤儿进程继续运行。 资料来源：src/bridge.ts:1-400 社区问题 #79 记录了该 POSIX-only 设计在 Windows 上的具体失效路径，目前尚未提供跨平台替代实现。

`setup hooks` 在 Windows 的路径转义问题（已修复）

chrome-devtools-axi setup hooks 安装 SessionStart hook 时，直接把 dist/bin/chrome-devtools-axi.js 的绝对路径写入 command 字段。Windows 下的反斜杠与空格在 Git Bash 中会被解释为转义或分词，结果是：

• 反斜杠被当作转义符吞掉，路径被截断；
• 路径中的空格把单条命令拆成多条；
• Claude Code 通过 Git Bash 执行该 hook 时报 command not found。

v0.1.26 修复了路径编码与转义处理。社区问题 #73 跟踪了此 bug。 资料来源：src/hooks.ts:1-200 资料来源：src/paths.ts:1-200 资料来源：CHANGELOG.md:1-200

缓解建议与版本对照

v0.1.26 同时新增 CHROME_DEVTOOLS_AXI_CHANNEL 环境变量以选择 Chrome 发布通道（issue #74），为 bridge 在不同 Chrome 渠道间的切换提供了显式入口。 资料来源：CHANGELOG.md:1-200 资料来源：README.md:1-400