使用说明

灯光浏览器

一个轻量级的网络浏览器，专为人类（CLI/TUI）和 AI代理 （MCP）。将内容提取置于视觉保真度之上，使网络内容在带宽受限的环境中以及比像素更有效地处理文本的系统中都可以访问。

特性

三层发动机：cheerio（静态HTML）、jsdom（简单JS）、Playwright（全浏览器）
语义搜索：使用本地嵌入的AI驱动内容过滤
智能过滤：搜索时，只返回相关链接和图像
多路输出：Markdown、JSON、纯文本
MCP服务器：AI代理的完整模型上下文协议支持
交互式TUI：类似Vim的终端界面
单个二进制：不需要运行时依赖关系

安装

选项1：单线安装（推荐）

需要包子 -安装方式 curl -fsSL https://bun.sh/install | bash

# Run directly without installing (downloads on first use)
bunx github:danilop/light-browser https://example.com

# Always use latest version from GitHub (add #main)
bunx github:danilop/light-browser#main https://example.com

# Or install globally
bun add -g github:danilop/light-browser
light-browser https://example.com

选项2：下载二进制文件（无需Bun）

从以下网址下载适用于您平台的预构建二进制文件发布:

平台	二进制
macOS（苹果硅）	`light-browser-darwin-arm64`
macOS（英特尔）	`light-browser-darwin-x64`
Linux（ARM64）	`light-browser-linux-arm64`
Linux（x64）	`light-browser-linux-x64`
Windows（x64）	`light-browser-windows-x64.exe`

# macOS/Linux: Make executable and move to PATH
chmod +x light-browser-darwin-arm64
sudo mv light-browser-darwin-arm64 /usr/local/bin/light-browser

选项3：来源

git clone https://github.com/danilop/light-browser.git
cd light-browser
bun install
bun run src/index.ts https://example.com

快速开始

# Interactive: Opens TUI automatically when in terminal
light-browser https://example.com

# Pipe/Script: Output markdown to stdout
light-browser https://example.com --dump

# Semantic search - find content about pricing
light-browser https://example.com --dump --query "how much does it cost"

# JSON output for scripts
light-browser https://example.com --json

# MCP: Start server for AI agents
light-browser serve

对于人类

CLI使用情况

基本命令

# Fetch and display as markdown (default)
light-browser https://example.com

# Output as JSON
light-browser https://example.com --json

# Output as plain text
light-browser https://example.com --format text

# Quiet mode (no status messages)
light-browser https://example.com -q

# Verbose mode (timing details)
light-browser https://example.com -v

内容过滤

Light Browser提供强大的过滤功能，只提取您需要的内容：

# CSS selectors - extract specific elements
light-browser https://example.com -s "main" -s "article"

# Keywords - exact text matching
light-browser https://example.com -k "price" -k "shipping"

# Semantic search - AI-powered similarity matching
light-browser https://example.com --query "contact information"

智能链接和媒体过滤：使用时 -k （关键字）或 --query （语义搜索），仅返回出现在匹配内容中或与匹配内容相关的链接和图像。这大大降低了输出中的噪声。

# Example: On a news site, only get links related to "AI"
light-browser https://news.ycombinator.com --query "artificial intelligence"
# Returns: Only the matching headlines + their specific links

语义搜索

这 --query 选项使用本地AI嵌入（全MiniLM-L6-v2）来查找语义相关的内容：

# Find pricing info even if page doesn't use the word "price"
light-browser https://store.com --query "how much does it cost"
# Matches: "pricing", "$99", "fees", "subscription cost", etc.

# Find contact methods
light-browser https://company.com --query "ways to reach support"
# Matches: email addresses, phone numbers, contact forms, etc.

约23MB的型号在首次使用时会自动下载，并完全在本地运行。

选项：

--semantic-threshold <0-1>：最小相似性得分（默认值：0.3）
--semantic-top-k <n>：返回的最大结果数（默认值：10）

发动机等级

层级	发动机	转速	用例
1	cheerio	~50ms	静态HTML页面
2	jsdom	~150-300ms	使用简单JS的页面
3	编剧	~500-2000ms	复杂的SPA（React、Vue）

# Force a specific tier
light-browser https://react-app.com --tier 3

# Default is tier 1 (fastest)

代币预算

限制LLM消耗的输出大小：

# Limit to ~1000 tokens
light-browser https://example.com --max-tokens 1000

批处理

一次处理多个URL：

# Create URL list
cat > urls.txt << EOF
https://example.com
https://example.org
https://news.ycombinator.com
EOF

# Process all URLs
light-browser --batch urls.txt --batch-output results.json

# With parallel processing
light-browser --batch urls.txt --batch-concurrency 3 --batch-output results.csv

所有CLI选项

Usage: light-browser [options] [command] [url]

Options:
  -f, --format <format>         markdown, text, json (default: markdown)
  -t, --tier <tier>             Engine tier: 1, 2, or 3 (default: 1)
  --timeout <ms>                Request timeout (default: 30000)
  -s, --selector <selector...>  CSS selectors to extract
  -k, --keyword <keyword...>    Keywords for exact filtering
  --query <text>                Semantic search query
  --semantic-threshold <0-1>    Similarity threshold (default: 0.3)
  --semantic-top-k <n>          Max semantic results (default: 10)
  --max-tokens <n>              Token budget limit
  -q, --quiet                   Suppress status messages
  -v, --verbose                 Show timing details
  --dump                        Force non-interactive output (for scripts/pipes)
  --download-media              Process images/videos
  --image-size <WxH>            Max image dimensions (default: 640x480)
  --image-quality <n>           Image quality 1-100 (default: 80)
  --video-frames <n>            Video frames to extract (default: 5)
  --batch <file>                Process URLs from file
  --batch-output <file>         Write results to file
  --batch-concurrency <n>       Parallel requests (default: 1)
  --stealth                     Browser-like fingerprint
  --json                        Shorthand for --format json

Commands:
  serve                         Start MCP server

交互式浏览器（TUI）

当stdout是一个终端时，Light Browser默认打开一个交互式w3m/lynx风格的浏览器：

# Opens interactive browser automatically
light-browser https://example.com

# Force non-interactive output
light-browser https://example.com --dump
echo "https://example.com" | light-browser

键盘快捷键

关键	行动
`Tab`	下一个可聚焦元素（链接/输入/按钮）
`Shift+Tab`	上一个可聚焦元素
`Enter`	激活（点击链接、编辑字段、提交）
`j` / `↓`	向下滚动
`k` / `↑`	向上滚动
`d` / `PgDn`	向下翻页
`u` / `PgUp`	向上翻页
`g`	转到顶部
`G`	转到底部
`b`	回到历史
`f`	在历史中前进
`1-9`	按编号跟踪链接
`/`	在页面中搜索
`n` / `N`	下一个/上一个搜索结果
`:`	命令模式
`q`	退出

输入模式（表单字段）

当您在输入字段上按Enter键时：

键入您的文本
Enter -保存并退出输入模式
Escape -取消并退出
Tab -保存并移动到下一个字段

命令

:open <url> -导航到URL
:links -显示所有链接
:forms -显示所有表单
:back -回去吧
:forward -继续
:refresh -重新加载页面
:help -显示所有键盘快捷键
:quit -退出

人工智能代理（MCP）

Light Browser提供了一个 模型上下文协议（MCP）服务器 用于AI代理集成。

设置

需要包子 -安装方式 curl -fsSL https://bun.sh/install | bash

添加到MCP客户端配置中：

{
  "mcpServers": {
    "light-browser": {
      "command": "bunx",
      "args": ["github:danilop/light-browser#main", "serve"]
    }
  }
}

就是这样！无克隆，无需手动安装。首次使用时自动下载。这 #main 后缀确保您始终获得最新版本。

Alternative: Using compiled binary (no Bun needed)

下载自发布那么：

{
  "mcpServers": {
    "light-browser": {
      "command": "/usr/local/bin/light-browser",
      "args": ["serve"]
    }
  }
}

MCP工具

`browse` -高级提取（推荐）

获取网络内容的最简单方法：

{
  "name": "browse",
  "arguments": {
    "url": "https://example.com",
    "format": "markdown",
    "query": "find pricing information",
    "maxTokens": 5000
  }
}

参数：

url （必填）：要获取的URL
format: "markdown" | "text" | "json" （默认值：markdown）
query：语义搜索以过滤内容
keywords：精确匹配关键字数组
selectors：CSS选择器数组
maxTokens：限制输出大小
maxTier：最大发动机级别（1-3）
includeMedia：在响应中包含图像（默认值：false）

当 includeMedia: true:

图像被下载、调整大小（最大640×480）并转换为WebP
在响应中以base64编码数据返回

响应格式：

{
  "content": [
    { "type": "text", "text": "Page content with [img:1] references..." },
    { "type": "image", "data": "base64...", "mimeType": "image/webp" }
  ]
}

`navigate` -创建会话

对于多步骤交互：

{
  "name": "navigate",
  "arguments": { "url": "https://example.com" }
}
// Returns: { "sessionId": "session-abc123" }

`snapshot` -获取页面内容

{
  "name": "snapshot",
  "arguments": {
    "sessionId": "session-abc123",
    "format": "markdown",
    "query": "contact info"
  }
}

`get_links` / `get_forms`

{
  "name": "get_links",
  "arguments": {
    "sessionId": "session-abc123",
    "filter": "pricing"
  }
}

`fill_form` / `submit_form`

{
  "name": "fill_form",
  "arguments": {
    "sessionId": "session-abc123",
    "formId": "login-form",
    "fields": { "username": "user", "password": "pass" }
  }
}

{
  "name": "submit_form",
  "arguments": {
    "sessionId": "session-abc123",
    "formId": "login-form"
  }
}

`click_link`

{
  "name": "click_link",
  "arguments": {
    "sessionId": "session-abc123",
    "linkText": "Products"
  }
}

`session_list` / `session_close`

{ "name": "session_list", "arguments": {} }
{ "name": "session_close", "arguments": { "sessionId": "session-abc123" } }

示例工作流

简单提取

browse({ url: "https://store.com", query: "product prices" })

多步导航

1. navigate({ url: "https://store.com" })
   → { sessionId: "session-123" }

2. get_links({ sessionId: "session-123", filter: "products" })

3. click_link({ sessionId: "session-123", linkText: "Products" })

4. session_close({ sessionId: "session-123" })

表格提交

1. navigate({ url: "https://example.com/login" })

2. get_forms({ sessionId: "session-123" })

3. fill_form({
     sessionId: "session-123",
     formId: "login-form",
     fields: { username: "user", password: "pass" }
   })

4. submit_form({ sessionId: "session-123", formId: "login-form" })
   → Returns resulting page content

技术细节

媒体处理

随着 --download-media:

图像：调整为最大640×480，转换为WebP
视频：按间隔提取的帧（需要ffmpeg）
输出：Base64编码的MCP兼容内容

PDF支持

PDF会自动检测和提取：

light-browser https://example.com/document.pdf

文本提取

Light Browser从任何HTML结构中提取所有可见文本，而不管语义标记如何。这意味着它适用于：

用于布局的表格
嵌套的div和span
非语义HTML
任何网站，而不仅仅是那些使用正确HTML5语义的网站

发展

# Install dependencies
bun install

# Run tests (172 tests)
bun test

# Type check
bun run typecheck

# Lint & format
bun run lint
bun run format

# Build for current platform
bun run build

# Build for all platforms
bun run build:all

构建二进制文件

# Current platform
bun run build
# → dist/light-browser

# All platforms
bun run build:all
# → dist/light-browser-darwin-arm64
# → dist/light-browser-darwin-x64
# → dist/light-browser-linux-arm64
# → dist/light-browser-linux-x64
# → dist/light-browser-windows-x64.exe

释放

发布是通过GitHub Actions自动完成的。要创建新版本，请执行以下操作：

# 1. Update version in package.json
# 2. Commit the version bump
git add package.json
git commit -m "Bump version to X.Y.Z"

# 3. Create and push a version tag
git tag vX.Y.Z
git push origin main --tags

这将触发发布工作流，该工作流：

为所有平台（macOS、Linux、Windows）构建二进制文件
创建附带二进制文件的GitHub版本
自动从提交中生成发行说明

版本格式：使用语义版本控制（例如。， v0.2.0, v1.0.0-beta.1)

许可证

麻省理工学院