cssgraph

---

为什么选择 cssgraph？

当 AI Agent 需要理解 CSS 时——.btn-primary 定义在哪里、有哪些属性、哪些选择器会层叠覆盖它、哪些 JSX 组件引用了它——它只能用缓慢的方式查找样式：逐个文件地使用 grep、glob 和 Read，手动还原层叠关系。

**cssgraph 一次调用，就能为 Agent 提供所需的精准样式上下文。**它是一个预构建的知识图谱，涵盖样式表中的每个 className、CSS 属性、变量和 at 规则——Agent 无需遍历文件，只需提出一个问题，就能完整获取属性、覆盖规则、优先级、调用方和文件级影响。

---

安装

面向使用者

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

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

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

面向大模型 Agent

获取安装指南并按其步骤操作：

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

---

快速开始

1. 初始化

npm i -g cssgraph
cd your-project
cssgraph init --workers 8

为所有样式文件（CSS、SCSS、Less、Sass）、JSX/TSX className 引用、 CSS-in-JS、CSS Modules 以及视图模板（ERB/Haml/HTML）建立索引，以启用所有 MCP 工具。

传入 --workers <n> 可控制并行解析线程数（默认为 CPU 核心数 - 1）。

需要 Node.js >= 22.5.0（用于 node:sqlite）。

2. 配置 Agent

cssgraph mcp-install

自动检测并配置 opencode、Claude Code、Cursor、Codex CLI、Gemini CLI、 Hermes Agent、Antigravity IDE 和 Kiro。写入 MCP 服务配置、指令 区块，以及一个 Agent Skill（SKILL.md + references/pitfalls.md），教会 Agent 何时使用 13 个 cssgraph 工具中的每一个、如何将它们串联成 工作流，以及需要避免哪些陷阱。

也可以手动将其添加到任何 MCP Agent：

{
  "mcpServers": {
    "cssgraph": {
      "type": "stdio",
      "command": "cssgraph",
      "args": ["serve", "--mcp"]
    }
  }
}

3. 无需再同步

默认启用自动同步。MCP 服务会监视你的项目，并在每次文件变更时更新图谱——无论是 Agent 编辑代码，还是你添加、修改或删除 CSS 文件。索引永远不会过时。

---

工作原理

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "What code files use .btn-primary?"                      │
│      calls cssgraph_rule — one tool call                  │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssgraph MCP Server                       │
│                                                           │
│ rule · O(1) exact selector lookup · loose/strict impact   │
│ explore · properties + overrides + specificity + callers  │
│                             │                             │
│                             ▼                             │
│               SQLite knowledge graph                      │
│     classNames · properties · variables · at-rules        │
│            edges · FTS5 full-text search                  │
└───────────────────────────────────────────────────────────┘

1. 提取 — PostCSS 将 CSS/SCSS/Less/Sass 解析为 AST。还会从 .jsx/.tsx/.erb/.haml 文件中提取 CSS-in-JS（styled.div）、JSX className 引用和模板 class 属性。
2. 存储 — 所有内容都存入本地 SQLite 数据库（.cssgraph/cssgraph.db），并使用 FTS5 全文搜索。采用 WAL 模式和批量提交来提升写入性能。批量加载期间会暂缓 FTS 触发器和唯一索引，以提高速度。
3. 图谱 — 边用于连接相关节点：contains（选择器→属性）、nests（父级→子级选择器）、overrides（高特异性选择器覆盖低特异性选择器）、imports（文件→导入的文件）、references（JSX/视图文件→className、属性→CSS 变量）。
4. 优先使用 Git 扫描 — 使用 git ls-files 即时发现文件。非 Git 项目则回退到文件系统遍历。
5. 并行解析 — 文件分批通过 Promise.all 分发到工作线程。文件会并发解析；结果按文件顺序写入，以确保正确性。
6. 自动同步 — 使用原生操作系统文件事件，经过防抖处理后增量同步。

---

CLI 参考

cssgraph init [path] [-w, --workers <n>]  # Initialize + build graph
cssgraph index [path] [-w, --workers <n>]  # Rebuild from scratch
cssgraph query <className>                 # Search for className selectors
cssgraph explore <query...>                # Full style context for a className
cssgraph details <selector>                # O(1) exact selector → file:line lookup
cssgraph rule <selector> [--strict]        # Selector impact: exact + loose/strict files
cssgraph impact-selector <selector>       # Code files affected by a selector
cssgraph impact <className>                # Blast radius of changing a className
cssgraph unused                            # Find unreferenced class selectors
cssgraph cascade <className>               # Visualize cascade path
cssgraph diagnose <className> [chain...]   # Static anchor diagnosis (height/scroll)
cssgraph property <query...>               # Search by CSS property value
cssgraph files [path]                      # Project style file tree
cssgraph status [path]                     # Index statistics
cssgraph sync [path]                       # Incremental update
cssgraph serve --mcp                       # Start MCP server
cssgraph mcp-install                       # Auto-wire to your AI agent (alias: install)
cssgraph skill-install                     # Install/update SKILL.md only (no MCP config changes)
cssgraph skill-uninstall                   # Remove SKILL.md only (no MCP config changes)
cssgraph mcp-uninstall                     # Remove from your AI agent (alias: uninstall)
cssgraph version                           # Print installed version

JSX 和视图文件扫描（默认）

cssgraph 始终会扫描：

• JSX/TSX/JS/TS/ES6 — className 引用、CSS-in-JS、CSS Modules
• 视图模板 — .erb、.haml、.html 文件中的 class="..." 属性和 Haml .classname 简写

这使 cssgraph_impact、cssgraph_callers 和 cssgraph_rule 能够追踪引用每个 className 的组件文件和模板文件。

项目	文件总数	首次索引	节点	边
小型	~50	~15s	~16K	~50K
生产级单体仓库	~11K	~3-5m	~780K	~22M

---

MCP 工具

工具	用途
cssgraph_explore	主要：获取 className 的完整样式上下文——属性、覆盖关系、特异性、调用方
cssgraph_search	按名称搜索 className 选择器
cssgraph_callers	查找引用 className 的 JSX 组件
cssgraph_impact	评估更改 className 的影响范围
cssgraph_rule	评估完整 CSS 选择器的影响范围（精确匹配 + 宽松/严格的文件影响）
cssgraph_impact_selector	查找受 CSS 选择器影响的代码文件（JS/TS/JSX/TSX）
cssgraph_details	O(1) 精确查询选择器（无边，轻量）
cssgraph_unused	查找没有传入引用的 class 选择器
cssgraph_cascade	可视化 className 的层叠路径
cssgraph_diagnose	针对滚动/高度问题进行静态锚点诊断——沿祖先链将高度声明分类为 DEFINITE / INDEFINITE / UNVERIFIABLE
cssgraph_property	按 CSS 属性值搜索选择器
cssgraph_files	已索引的样式文件树
cssgraph_status	索引健康检查

---

配套工具：cssprobe-cli

cssgraph 是一款静态分析工具——它会读取源代码，并回答某个类定义在哪里、哪些样式层叠覆盖了它，以及某项更改会影响什么。对于运行时问题——页面在浏览器中实际渲染的效果（溢出、滚动链、计算高度链、包含块劫持）——请使用 cssprobe-cli，它会打开真实浏览器并读取计算样式和 DOM 指标。这两款工具相辅相成：

	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)
npm i -g cssprobe-cli
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

安装：npm install -g cssprobe-cli（需要 Node.js >= 22.5.0）。请参阅 npm / GitHub。

---

支持的语言

语言	扩展名	提取方式
CSS	.css	PostCSS 标准
SCSS	.scss	postcss-scss 插件
Less	.less	postcss-less 插件
Sass（缩进语法）	.sass	编译 → PostCSS
PostCSS 自定义语法	.pcss	PostCSS 标准
JSX / TSX	.jsx .tsx	className + CSS-in-JS
JavaScript / TypeScript	.js .ts .es6	className + CSS Modules
ERB（Rails）	.erb	提取 class="..."
Haml（Rails）	.haml	提取 .classname + {:class =>}
HTML	.html	提取 class="..."
CSS Modules	.module.css .module.scss .module.less	动态导入解析
Tailwind	tailwind.config.js + CSS @theme	v3 JS 配置 + v4 CSS 配置

---

生产规模

项目	文件总数	首次索引	节点	边
小型	~50	~15s	~16K	~50K
生产级单体仓库	~11K	~3-5m	~780K	~22M

---

项目配置

默认无需配置。可在项目根目录添加 .cssgraph.json：

{
  "exclude": ["static/vendor/", "**/legacy/**"],
  "extensions": {
    ".pcss": "css"
  }
}

内置默认排除项（始终生效）：**/*.test.*、**/*.stories.*、**/*.spec.*、**/*.min.*、**/__tests__/**、**/__snapshots__/**、**/__mocks__/**、**/generated/**、**/spec/**、**/vendor/**。

---

支持的平台

平台	架构	安装方式
macOS	x64、arm64	npm
Linux	x64、arm64	npm
Windows	x64、arm64	npm

---

如果 cssgraph 对你有用

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

---

许可证

MIT