freundapps/NBSvision
GitHub: freundapps/NBSvision
将任意网页的 DOM 逆向为人类可读的 Unicode 结构化框图，帮助 AI 智能体和开发者在零 token 消耗下发现并定位 CSS 布局问题。
Stars: 1 | Forks: 0
# NBSvision — 看清你的 UI 究竟长什么样
[🇬🇧 English](README.md) | [🇷🇺 Русский](README.ru.md) | [🇩🇪 Deutsch](README.de.md)
## 🇬🇧 English {#english}
**“我的页面看起来没问题”** —— AI 智能体是这么说的。直到它运行了 NBSvision。
你设计了一个完美的布局。规格说明书标明了 36px 高度、8px 间距、居中的图标。你的 AI 智能体声称已经完成了。然后你运行了一条命令，看到了现实：按钮紧贴边缘、间距为 -1px、文本溢出、缺少 padding。所有这些都对智能体不可见。而所有这些在 NBS 中都瞬间可见。
**专为没有视觉能力的 AI 智能体打造。** NBSvision 是 LLM 的眼睛。你的智能体无法看懂屏幕截图——但它能读懂 NBS map。每一个像素都变成了结构化数据。无需视觉模型。适用于任何终端、任何控制台、任何 CI pipeline。人类可读，机器可解析，零 token。
**NBS**（Nested Box Schema）将你的 DOM 映射为人类可读的 Unicode 框图。每个元素都有自己嵌套的框，包含精确的 `W×H`、在父元素中的位置、边框、字体大小和显示模式。问题会用带编号的标记标出——你不需要去寻找 bug，它们会主动找上你。
**逆向工程任何网站。** 将 check-props 指向一个 URL，就能获得完整的 DOM 结构框图。使用 nbs-find 进行搜索。并据此生成页面。从神秘的 DOM 到干净的代码，全程无需消耗 LLM token。
### 为什么会有这个项目
你肯定有这种感觉：你让 LLM 构建一个页面，它声称“完成了”，但布局却是一团糟。你花了 30 分钟调试 CSS，又花了 20 分钟折腾 Playwright 选择器，而 LLM 在这个过程中烧掉了 5000 个 token。NBSvision 用一个 Python 脚本取代了这一切。零 LLM token。瞬间获取基本事实。
## 快速开始
### 安装
```
# 环境要求：Python 3.11+, pip, Playwright
git clone https://github.com/freundapps/NBSvision.git
cd NBSvision
pip install playwright && playwright install chromium
```
### 运行
```
# 映射任意网站
python scripts/check-props/check-props.py --url https://apple.com --map
# 搜索 JSON
python scripts/check-props/check-props.py --url https://apple.com --map --json --compact | python scripts/nbs-find/nbs-find.py --tag button
# 提取 design tokens
python scripts/check-props/check-props.py --url https://apple.com --tokens
```
### 真实世界示例
| 网站 | NBS Map | Token（精简版 NBS） |
|------|---------|:-----:|
| [Apple](examples/apple/map.nbs) | 482KB | ~120K |
| [Google](examples/google/map.nbs) | 56KB | ~14K |
| [TikTok](examples/tiktok/map.nbs) | 29KB | ~7K |
| [GitHub](examples/github/raw-map.nbs) | 63KB | ~16K |
*将完整的 NBS map 加载到 LLM 时的情况。
## 脚本
### Playwright
| 脚本 | 描述 | 依赖 |
|--------|------------|:---:|
| `check-props.py` | DOM → NBS map：`--map`, `--json`, `--compact`, `--tokens`, `--sweep` | Playwright |
### 生成器
| 脚本 | 描述 | 依赖 |
|--------|------------|:---:|
| `nbs-gen.py` | JSON → NBS schema (标准输入→标准输出) | — |
| `generate-page.py` | JSON 配置 → page.tsx + Body + Row + scss + API hook | — |
| `gen-playwright-test.py` | NBS JSON → Playwright 幂等性测试 | Playwright |
| `mk-tree.py` | ASCII 树状图 → 文件系统 | — |
| `nbs-slice.py` | 深层 NBS 树状图 → 概览 + 细节块 | — |
### 分析器
| 脚本 | 描述 | 依赖 |
|--------|------------|:---:|
| `nbs-find.py` | 搜索 NBS JSON：标签、文本、class、问题。**节省 99.6-99.9% token** | — |
| `nbs-to-compact.py` | NBS → 精简 DSL。为 LLM 阅读节省 70-90% token | — |
| `count-tokens.py` | 从 SQLite 会话数据库进行 token 使用分析 | — |
| `github-scout.py` | 无需 LLM token 的 GitHub 搜索 | — |
## AI Pipeline：零 Token 搜索
`nbs-find` 让 AI 智能体无需阅读即可搜索庞大的 JSON schema。搜索过程不消耗任何 LLM token——只消耗在微小的结果上。
### Token 节省情况
| 查询 | 完整 JSON (精简版) | nbs-find | 节省量 |
|-------|:-----:|:-----:|:-----:|
| 在 Apple 中查找 "iPhone" (75KB) | 18,750 | 67 | **99.6%** |
| 在 GitHub 中查找 footer (41KB) | 10,250 | 23 | **99.8%** |
| 在 Google 中查找所有 buttons | 5,500 | 3 | **99.9%** |
### 工作原理
```
# AI agent 提取页面 schema（紧凑——不浪费 tokens）
python check-props.py --url https://apple.com --map --json --compact > schema.json
# AI 询问 nbs-find 而不是读取 75KB JSON
python nbs-find.py --text "iPhone" schema.json # → 67 tokens
python nbs-find.py --tag button schema.json # → 3 tokens
python nbs-find.py --issue 1 schema.json # → only broken elements
python nbs-find.py --wider-than 500 --limit 5 schema.json # → top 5 widest
```
### 智能体间通信
所有 JSON 输出都支持 `--compact` 标志——移除缩进和空格。LLM 解析它们的方式完全相同，但消耗的 token 减少了 23%。
```
# 人类：可读
python check-props.py --url https://apple.com --json > human.json # 97KB
# Agent：紧凑
python check-props.py --url https://apple.com --json --compact > agent.json # 75KB, -23%
```
### 搜索标志
| 标志 | 查找目标 |
|------|-------|
| `--tag button` | 所有 `
标签：DOM解析, LLM辅助开发, UI测试, Web开发工具, 云资产清单, 反调试, 特征检测, 逆向工具, 逆向工程