cssprobe-cli

cssprobe-cli

运行时 CSS 探测工具——在实时浏览器中检查布局、滚动、颜色、背景、字体等。面向人类和 AI Agent 打造。

面向 AI Agent 的静态与运行时 CSS 诊断工具——搭配 cssgraph（CSS 知识图谱）即可全面了解情况。

---

为什么选择 cssprobe-cli？

当 AI Agent 需要调试 CSS——例如，为什么元素溢出、实际渲染的布局是什么、容器是否可滚动——它无法直接查看浏览器。它只能根据静态代码猜测，因此会漏掉溢出、滚动链和包含块劫持等仅在运行时出现的问题。

cssprobe-cli 让 Agent 拥有了双眼。 它会打开真实浏览器，通过注入的 JavaScript 收集计算样式和指标，使用置信度模型进行分析，并在一条命令中返回结构化发现。Agent 只需询问任意选择器相关的问题，就能获得 DOM 树、ASCII 布局图、溢出警告和滚动诊断，无需离开终端。

---

安装

面向人类

将此提示词复制并粘贴到你的 LLM Agent（Claude Code、Cursor、Codex 等）：

Install and configure cssprobe-cli by following the instructions here:
https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md

或者阅读安装指南，不过说真的，让 Agent 来做吧。人类很容易把配置输错。

面向 LLM Agent

获取安装指南并按其说明操作：

curl -s https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md

或者直接安装：

npm install -g cssprobe-cli
cssprobe-cli skill-install

---

工作原理

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "Is .sidebar overflowing?"                               │
│      calls: cssprobe-cli inspect .sidebar                 │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssprobe-cli daemon                       │
│                                                           │
│  collector (IIFE) → analyzer (pure) → renderer (md/json)  │
│                             │                             │
│                             ▼                             │
│               Playwright browser (Chromium)                │
│     getBoundingClientRect · getComputedStyle · DOM walk    │
└───────────────────────────────────────────────────────────┘

1. 会话 — open 会启动管理浏览器的守护进程。命令通过 Unix 套接字连接。
2. 收集器 — 以 IIFE 的形式注入页面。遍历 DOM，读取计算样式、声明值和元素指标。
3. 分析器 — 纯 Node.js 函数。按置信度级别（DEFINITE / INDEFINITE / UNVERIFIABLE）对发现进行分类。
4. 渲染器 — 输出 Markdown（默认）或 JSON。内容包括 ASCII 布局图、DOM 树和发现结果。

---

快速开始

1. 检查页面

# Open browser (non-blocking, starts daemon session)
cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout

# Inspect with CSS selector
cssprobe-cli inspect .container

# Show ASCII layout diagram
cssprobe-cli layout .container

# Show only issues/warnings
cssprobe-cli findings .container

# Close browser when done
cssprobe-cli close

2. 受登录保护的页面

# Open browser in headed mode
cssprobe-cli open https://mysite.com --headed

# User manually logs in...

# Save session state for future use
cssprobe-cli state-save --name mysite

# Reopen with saved state (no login needed)
cssprobe-cli open https://mysite.com --state state.json --headed

3. JSON 输出

cssprobe-cli inspect body --json
cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'

4. 用作 MCP 服务（AI 客户端）

cssprobe-cli 附带 MCP 服务（stdio），AI 客户端可将其作为原生工具调用——无需 shell：

cssprobe-cli mcp-install          # auto-detect and configure installed clients
cssprobe-cli mcp-install --target=claude,cursor,codex
cssprobe-cli mcp-install --local  # write project-scoped config

适用于任何 MCP 客户端的手动配置：

{
  "mcpServers": {
    "cssprobe-cli": { "command": "cssprobe-cli", "args": ["mcp"] }
  }
}

提供 10 个工具：cssprobe_open、cssprobe_inspect、cssprobe_tree、cssprobe_layout、 cssprobe_findings、cssprobe_eval、cssprobe_screenshot、cssprobe_inject_css、 cssprobe_close、cssprobe_status。使用 cssprobe-cli mcp-uninstall 移除。

---

命令

会话管理

命令	说明
open [url]	以会话模式打开浏览器（非阻塞）
open [url] --headed	显示浏览器窗口
open [url] --state <file>	使用已保存的 Cookie 和 localStorage 打开
open [url] --viewport 1280x720	自定义视口大小
open [url] --expect-url <regex>	如果最终 URL 不匹配该模式则失败
open [url] --fail-on-login	重定向到登录 URL 时快速失败
close	关闭浏览器会话
close --all	关闭所有工作区中的所有会话
status	显示会话状态（URL、标题、帧数）
frames	列出帧：索引、名称、URL、主帧标记
doctor	诊断浏览器安装与 Playwright 预期版本之间的问题

CSS 检查

命令	描述
inspect <selector>	完整的 CSS 诊断（计算值、声明值、检查结果）
inspect <selector> --layout	包含 ASCII 布局图
inspect <selector> --brief	精简输出：树形草图 + 仅显示警告和错误
inspect <selector> --json	结构化 JSON 输出
tree <selector>	DOM 树结构
layout <selector>	ASCII 布局图
findings <selector>	仅显示问题、警告和错误

检查命令接受 --frame <index|name|url-substring>，用于指定 iframe；默认使用主框架。

CSS 注入

命令	描述
inject-css <css>	向当前页面注入 CSS

浏览器

命令	描述
resize <width> <height>	调整浏览器视口大小
eval <expression>	执行 JavaScript（浏览器上下文）；DOM 节点会自动序列化；会等待 Promise；undefined 字段会变为 null
eval @file / eval -	从文件或标准输入读取表达式
playwright <call>	执行 Playwright API（Node.js 上下文）
screenshot	截取屏幕截图（保存到 ~/.cssprobe-cli/screenshots/，可通过 --out 覆盖路径）

交互

命令	描述
click <selector>	执行真实鼠标点击（自动滚动并等待可操作；适用于自定义 React 组件）
hover <selector>	执行真实鼠标悬停
type <selector> <text>	填入文本（替换现有值）；使用 --press Enter 提交；使用 --sequential 触发真实按键事件
wait-for <selector>	等待选择器状态（--state visible|hidden|attached|detached、--timeout ms）
wait-for --js "<predicate>"	等待 JS 谓词为真
wait-for --network-idle	等待页面网络空闲（页面级；不支持 --frame）
wait-for ... --frame <spec>	在 iframe 内等待（选择器/JS 模式）
sample "<expr>"	随时间采样表达式（--interval、--duration、--key、--frame）；返回时间线和摘要
wait-stable "<expr>"	等待表达式停止变化（--tolerance、--window、--timeout）
run <file>	运行多步流程脚本

click / hover 支持 --nth N（从 1 开始，默认为首个匹配项）、--force（跳过可操作性检查）和 --timeout ms。未指定 --nth 时，如果有多个匹配项，命令会失败（严格模式），以防点击错误目标。

状态

命令	描述
state-import <file>	从 Netscape 格式导入 Cookie
state-save	保存当前浏览器会话状态（Cookie + localStorage）
state-check	验证状态文件：Cookie 数量、过期时间、目标域名覆盖范围（--state、--url）

配置

命令	描述
config-show	显示当前配置
config-set <key> <value>	设置配置值
config-list	列出所有配置档
config-use <name>	切换活动配置档
config-new <name>	创建新配置档
config-path	显示配置文件路径

---

多步流程

交互命令可逐步驱动页面；run 可将一系列操作转换为可版本管理的脚本：

cssprobe-cli open https://example.com/editor
cssprobe-cli wait-for .editor-canvas
cssprobe-cli click ".layout-switch" --nth 1
cssprobe-cli type ".block-title input" "Hello" --press Enter
cssprobe-cli inspect .block-grid --json
cssprobe-cli close

对于可重复的流程，可编写脚本并通过一条命令运行。脚本在守护进程会话中运行（可完整访问 Playwright 的 page）：

// flow.js
export default async ({ page, context, frames, newPage, click, waitFor, type, inspect, screenshot, expect, log }) => {
  await page.goto('https://example.com/editor', { waitUntil: 'domcontentloaded' });
  await waitFor('.editor-canvas', { state: 'visible', timeout: 10000 });

  await click('.layout-switch', { nth: 1 });
  await waitFor({ js: "() => document.body.dataset.layout === 'two-col'" });

  await type('.block-title input', 'Hello', { press: 'Enter', sequential: true, clear: true });
  await waitFor({ networkIdle: true });

  const { findings } = await inspect('.block-grid', { format: 'json' });
  log('findings:', findings.length);
  await screenshot({ path: './after-layout-switch.png' });

  return { findings: findings.length };
};

cssprobe-cli run ./flow.js        # --timeout ms for the whole script (default 300000, 0 = unlimited)

脚本必须 default-export 一个接收 API 对象的异步函数：page、context、frames()、newPage()、click、hover、type、waitFor、inspect、screenshot、expect、log。waitFor 接受 { state, timeout, frame }。未捕获的页面错误会作为 pageErrors 收集到结果封套中。screenshot 的相对路径会相对于脚本所在目录解析；日志（log() 和 console.*）会被收集并随结果返回。若执行失败，命令会以 1 退出、打印收集到的日志，并保持会话运行。

脚本由本地守护进程以完整的 Node 权限执行——请仅运行可信脚本。

---

场景套件（回归测试）

通过 JSON 套件运行可重复的回归用例：每个用例都会打开一个全新的浏览器、执行步骤、对已保存的值进行断言，并写入产物及可选的 JUnit 报告。

cssprobe-cli scenario run suites/ticket-26571394.json \
  --state ~/.cssprobe-cli/states/preprod.json \
  --artifacts out/ticket-26571394 \
  --junit out/junit.xml

{
  "name": "ticket 26571394 preprod",
  "defaults": { "viewport": { "width": 1280, "height": 800 } },
  "cases": [
    {
      "name": "refresh keeps the hash section aligned",
      "url": "https://example.com/#listen-to-tcmi",
      "steps": [
        { "do": "sample", "expression": "({ hash: location.hash, top: Math.round(document.querySelector('#listen-to-tcmi')?.getBoundingClientRect().top ?? -1) })", "interval": 250, "duration": 12000, "key": "top", "tailFrom": 9500, "save": "timeline" },
        { "do": "assert", "label": "hash retained", "on": "timeline", "path": "summary.last.value.hash", "eq": "#listen-to-tcmi" },
        { "do": "assert", "label": "anchor stable", "on": "timeline", "path": "summary.tail.min", "min": 70 },
        { "do": "assert", "label": "anchor stable", "on": "timeline", "path": "summary.tail.max", "max": 90 }
      ]
    },
    {
      "name": "deployment fingerprint",
      "url": "https://example.com/",
      "steps": [
        { "do": "waitFor", "js": "() => !!window.DEBUG?.NavigatorStore", "timeout": 20000 },
        { "do": "assert", "globals": { "DEBUG.NavigatorStore.setHashRestoreProtected": "function" }, "absent": ["DEBUG.NavigatorStore.navigateToSectionId"] }
      ]
    }
  ]
}

步骤包括：goto、reload、wait、eval、sample、waitStable、click、waitFor、screenshot、assert。wait 接受固定的 ms；waitFor 支持通过 frame 对 iframe 中的选择器或 JS 执行等待。sample 和 eval 使用 save: "<name>" 保存值；断言可通过 on: "<name>" + path 读取这些值，也可检查实时 state（url、title、frames）、url、globals、absent。sample 支持 key、tailFrom、ignoreErrors；每次运行都会写入 summary.json、每个用例的 case.json、样本序列和失败截图。

Iframe 和预览页面。 页面可能包含隐藏的辅助 iframe（about:blank）；可使用 frames 选取实际的 iframe，并在等待不可见的 frame 元素时使用 state: "attached"。预览 frame 可能需要 6–8s 才能渲染完成，而分析请求会导致 networkIdle 一直处于忙碌状态——建议使用固定的 wait 步骤，然后在 frame 内执行 waitFor（frame: "i/preview"），而不是等待 networkIdle。

置信度模型

每项发现都带有一个置信度等级：

等级	含义
DEFINITE	基于计算值（来自 getComputedStyle 的事实）或可访问的声明值
INDEFINITE	声明值使用 %——会在运行时解析
UNVERIFIABLE	声明值缺失，或来自受阻的跨源样式表

报告标头显示：confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1

---

辅助工具：cssgraph

cssprobe-cli 是一个运行时 CSS 探测工具——它会打开真实浏览器并读取实际渲染的内容。对于有关源代码的静态问题——.btn-primary 定义在哪里、哪些样式会层叠覆盖它、哪些组件引用了它、编辑它会带来什么变化——请使用 cssgraph，这是一个本地 SQLite 知识图谱，收录样式表中的每个 className、属性、变量和 at 规则。这两种工具相辅相成：

	cssgraph（静态）	cssprobe-cli（运行时）
分析对象	源代码（CSS/SCSS/Less + JSX/TSX + 模板）	实时浏览器（计算样式 + DOM）
可回答的问题	类的定义位置、层叠关系、影响范围、未使用的 CSS	实际渲染布局、溢出、滚动、高度链
使用时机	浏览器分析之前／无需浏览器时	静态分析后，用于运行时验证
用法	cssgraph init + explore/rule/impact	open + inspect/layout/findings

样式问题的推荐工作流——先做静态分析，再进行运行时验证：

# 1. Static: find the definitions, cascade, and blast radius (cssgraph)
cssgraph explore .btn-primary
cssgraph cascade .btn-primary

# 2. Runtime: confirm what actually renders (cssprobe-cli)
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

安装：npm install -g cssgraph（需要 Node.js >= 22.5.0）。它提供 12 个 MCP 工具（cssgraph_explore、cssgraph_rule、cssgraph_impact、……）以及 CLI 命令。详见 npm / GitHub。

---

配置

# Set values
cssprobe-cli config-set browser chromium
cssprobe-cli config-set depth 8
cssprobe-cli config-set viewport 375x812

# Profile management
cssprobe-cli config-new staging
cssprobe-cli -p staging config-set browser firefox
cssprobe-cli config-use staging

优先级：CLI 标志 > 环境变量 > 配置文件

--browser       CSSPROBE_BROWSER
--depth         CSSPROBE_DEPTH
--headed        CSSPROBE_HEADED
--viewport      CSSPROBE_VIEWPORT
-p, --profile   CSSPROBE_PROFILE

配置文件：~/.cssprobe-clirc

---

支持的平台

平台	架构
macOS	x64, arm64
Linux	x64, arm64
Windows	x64, arm64

---

开发

npm install
npm run build       # tsc + esbuild collector + daemon entry + generate help.json
npm test            # Run unit tests (58 tests)
npx tsc --noEmit    # Type check only

如果 cssprobe-cli 对你有用

点个 ⭐ 星标能帮助其他开发者发现它，也能告诉我们继续推出新版本。

---

许可证

MIT