# https://github.com/kunchenguid/chrome-devtools-axi 项目说明书

生成时间：2026-07-07 05:04:19 UTC

## 目录

- [总览与系统架构](#page-1)
- [CLI 命令参考与配置](#page-2)
- [会话、钩子与安装分发](#page-3)
- [已知问题、失败模式与跨平台兼容性](#page-4)

<a id='page-1'></a>

## 总览与系统架构

### 相关页面

相关主题：[CLI 命令参考与配置](#page-2), [会话、钩子与安装分发](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/bridge.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bridge.ts)
- [src/client.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/client.ts)
- [src/snapshot.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/snapshot.ts)
- [src/paths.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/paths.ts)
- [src/generation.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/generation.ts)
- [src/suggestions.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/suggestions.ts)
- [bin/chrome-devtools-axi.js](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/bin/chrome-devtools-axi.js)
</details>

# 总览与系统架构

`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**。

```mermaid
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_CHANNEL` | 选择 Chrome 发布通道（stable / beta / canary） | [src/bridge.ts:60-75]() |
| `setup hooks` 子命令 | 向 Claude Code 注入 SessionStart 钩子 | [src/client.ts:140-200]() |
| 子命令注册表 | 集中维护 `open` / `snapshot` / `eval` 等入口 | [src/client.ts:30-80]() |

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

---

<a id='page-2'></a>

## CLI 命令参考与配置

### 相关页面

相关主题：[总览与系统架构](#page-1), [会话、钩子与安装分发](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/cli.ts)
- [src/run.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/run.ts)
- [bin/chrome-devtools-axi.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/bin/chrome-devtools-axi.ts)
- [README.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/README.md)
- [package.json](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/package.json)
</details>

# 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（或类似）结构组织命令。常用命令如下：

| 命令 | 作用 | 备注 |
|------|------|------|
| `run` | 启动 MCP 服务器并连接已存在的 Chrome | 由 `src/run.ts` 实现 |
| `open <url>` | 在 Chrome 中打开 URL 或新建标签页 | `navigate_page` 失败时回退到 `new_page` |
| `snapshot` | 抓取当前页面的无障碍快照（pull 模型） | 当前唯一的状态读取手段之一 |
| `eval <expr>` | 在选中页面执行表达式并返回结果 | 同步执行 |
| `console` | 读取当前 console 缓冲区 | 不包含实时订阅 |
| `setup hooks` | 向 Claude Code 注入 SessionStart 钩子 | Windows 路径需转义，见下文 |

资料来源：[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

## 工作流程

```mermaid
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]()

---

<a id='page-3'></a>

## 会话、钩子与安装分发

### 相关页面

相关主题：[总览与系统架构](#page-1), [已知问题、失败模式与跨平台兼容性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/sessions.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/sessions.ts)
- [src/hooks.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/hooks.ts)
- [src/skill.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/skill.ts)
- [scripts/build-skill.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/scripts/build-skill.ts)
- [skills/chrome-devtools-axi/SKILL.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/skills/chrome-devtools-axi/SKILL.md)
- [bin/chrome-devtools-axi-bridge.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/bin/chrome-devtools-axi-bridge.ts)
</details>

# 会话、钩子与安装分发

`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 暴露的"提示词 + 工具元数据"包，由三段流程协作产出：

```mermaid
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 退出逻辑，正是这条隐式链路上最脆弱的接缝。

## 小结

| 模块 | 关注点 | 已知痛点 |
|------|--------|----------|
| sessions | 目标/页面状态、CDP 路由 | fallback 残留空白目标 |
| hooks | 钩子注入、bridge 拉起 | Windows 路径转义、跨平台 kill |
| skill | 提示词与元数据分发 | 安装幂等性、产物与源同步 |
| bridge | 进程级 Chrome/MCP 托管 | POSIX-only teardown |

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

---

<a id='page-4'></a>

## 已知问题、失败模式与跨平台兼容性

### 相关页面

相关主题：[总览与系统架构](#page-1), [会话、钩子与安装分发](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/bridge.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bridge.ts)
- [src/open.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/open.ts)
- [src/hooks.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/hooks.ts)
- [src/paths.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/paths.ts)
- [src/sessions.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/sessions.ts)
- [src/index.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/index.ts)
- [CHANGELOG.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/CHANGELOG.md)
- [README.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/README.md)
</details>

# 已知问题、失败模式与跨平台兼容性

本页汇总 chrome-devtools-axi 在社区反馈中暴露的已知问题、失败模式与跨平台兼容性缺陷，涵盖 API 语义边界、目标清理、Windows 平台行为差异等关键场景，并标注已修复版本。

## 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. 后续命令实际作用的页面并非用户预期，造成"静默操作错误页"的体验。

```mermaid
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]()  

## 缓解建议与版本对照

| 问题类别 | 现状 | 缓解方式 | 涉及版本 |
|---|---|---|---|
| Pull-based 无事件流 | 尚未实现订阅 API | 调用方降采样轮询 | 所有版本 |
| `open` 回退累积空白 tab | 未自动清理 | 调用 `close_page` 手动回收 | 所有版本 |
| Bridge 在 Windows 关闭孤儿 | POSIX-only | 手动终止 Chrome 与 MCP 进程 | 所有版本 |
| `setup hooks` 路径转义 | 已修复 | 升级至 v0.1.26+ | v0.1.26 |

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

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：kunchenguid/chrome-devtools-axi

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：open fallback leaves blank targets behind; the selected page drifts to a leftover blank tab after an SPA full-page redi…。

## 1. 配置坑 · 来源证据：open fallback leaves blank targets behind; the selected page drifts to a leftover blank tab after an SPA full-page redi…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：open fallback leaves blank targets behind; the selected page drifts to a leftover blank tab after an SPA full-page redirect
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/80 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://www.npmjs.com/package/chrome-devtools-axi | host_targets=mcp_host, claude

## 3. 配置坑 · 来源证据：Bridge teardown is POSIX-only: on Windows, stopping the bridge orphans chrome-devtools-mcp + Chrome, and the ps-based i…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bridge teardown is POSIX-only: on Windows, stopping the bridge orphans chrome-devtools-mcp + Chrome, and the ps-based identity check never passes
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/79 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://www.npmjs.com/package/chrome-devtools-axi | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://www.npmjs.com/package/chrome-devtools-axi | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://www.npmjs.com/package/chrome-devtools-axi | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：[fixed] `setup hooks` writes a non-bash-safe raw .js path on Windows → SessionStart hook fails with "command not found"

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[fixed] `setup hooks` writes a non-bash-safe raw .js path on Windows → SessionStart hook fails with "command not found"
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi | release_recency=unknown

<!-- canonical_name: kunchenguid/chrome-devtools-axi; human_manual_source: deepwiki_human_wiki -->