md-browse：用 AI 的视角浏览网页

想象一下，当你把一个网页丢给 AI 读取时，大模型看到的往往是一团混乱的 HTML 标签、广告脚本、CSS 样式，真正有用的内容被埋在层层噪声之下。md-browse（Markdown Browser）就是为了解决这个问题而生的——它是一个以 Markdown 为核心的浏览器，让任何网页都能以 AI 最容易理解的干净格式呈现。

背景故事：为什么 AI 看网页总是不准

大语言模型处理网页内容的能力取决于输入的质量。当 AI 读取一个满是 div 嵌套和 script 标签的网页时，它需要消耗额外的"脑细胞"来过滤噪声、还原语义。传统爬虫方案虽然也能提取正文，但转换逻辑参差不齐——有的把代码块弄乱，有的丢失了表格格式，有的图片链接变成了占位符。

md-browse 的作者来自 needle-tools，一个长期专注于开发者工具的团队。他们在开发 needle-engine 的过程中，深感 AI 辅助编程工具需要稳定可靠的网页内容读取能力，于是决定从浏览器层面解决这个问题：与其在爬虫层做各种 hack，不如让浏览器本身就输出 Markdown。

核心原理：双通道内容获取

md-browse 采用了优先级递进的内容获取策略，这是理解它工作原理的关键：

第一通道：原生 Markdown（Accept Header 优先）

当用户输入 URL 时，md-browse 会在 HTTP 请求中加入 Accept: text/markdown 头部，优先请求服务器原生的 Markdown 内容。越来越多的现代网站（如 Vercel 文档）开始支持这种 content negotiation 方式，服务器检测到该头部后会直接返回 .md 格式的内容，绕过 HTML 渲染步骤。

第二通道：Turndown HTML→Markdown 智能转换

如果服务器不支持 Markdown 格式，md-browse 会退回到传统的 HTML 获取模式，然后通过 Turndown 库将 HTML 转换为干净的 Markdown。转换过程经过大量调优（见 src/shared/turndown.ts）：

• 语义感知提取：优先从 <main> 或 <article> 标签提取主要内容，过滤导航栏、页脚、广告位
• GFM 兼容：使用 turndown-plugin-gfm 支持 GitHub Flavored Markdown 特性（表格、任务列表、删除线）
• 智能链接处理：从 aria-label → img[alt] → title → href 的备选顺序提取链接文本，解决大量页面空链接 <a href="..."></a> 的文本缺失问题
• 协议修正：自动修复 //example.com 这类协议相对 URL 为 https://example.com
• Sitemap 解析：内置 XML Sitemap 解析器，将站点地图转换为可导航的 Markdown 列表

# Sitemap - engine.needle.tools

Found 5 URLs:
- [https://engine.needle.tools/samples/] — lastmod: 2024-12-05
- [https://engine.needle.tools/docs/] — lastmod: 2024-11-20
...

图1：md-browse 应用图标

架构拆解：Electrobun + Svelte 的桌面端方案

md-browse 基于 Electrobun 框架构建，这是一个相对小众但值得关注的新兴桌面应用框架——它用 Bun 替代 Node.js 作为后端运行时，结合 WebView 实现轻量级跨平台应用。

进程模型

应用分为两个进程层：

1. Bun 主进程（src/bun/index.ts）：处理所有 HTTP 通信、内容转换、标签页状态管理。代码约 500 行，纯 TypeScript，逻辑清晰。它管理 Tab[] 数组（包含历史记录 history[] 和当前位置 historyIndex），支持后退/前进导航。

2. Svelte UI 进程（src/toolbar-svelte/）：编译后的单页面视图，包含标签栏、地址栏、导航按钮、视图切换开关。UI 层完全由 Svelte 5 的响应式系统驱动，通过 RPC 与 Bun 进程通信。

RPC 通信设计

Bun 与 Toolbar 之间定义了完整的 RPC Schema（见 src/shared/types.ts）：

• Toolbar → Bun：导航操作（navigate、goBack、goForward）、标签管理（createTab、closeTab）、设置更新
• Bun → Toolbar：导航状态变化（navigationStateChanged）、标签更新（tabsChanged）、日志消息（log）

这种设计将网络层、转换层与 UI 层完全解耦，Bun 进程可以独立测试，UI 可以热更新而不影响后端逻辑。

功能细节：双视图与标签页

md-browse 提供了两种互补的内容查看模式：

• Markdown 视图：显示原始转换后的 Markdown 文本，适合 AI 工具直接复制使用。代码块保持格式，链接显示为 [文本](url) 形式
• Preview 视图：渲染后的 HTML 预览，适合人类阅读确认内容是否正确

用户可以在任意时刻切换视图，无需重新请求页面——Bun 进程同时保存了原始 HTML（rawHtml 字段）和转换后的 Markdown，切换视图只是切换渲染方式。

多标签页支持是另一个实用特性：用户可以同时打开多个网页，每个标签独立维护历史记录（history[] + historyIndex），支持真正的后退/前进导航。

测试体系：转换质量有保障

md-browse 配备了完整的单元测试和对比测试：

• turndown.test.ts：验证链接文本提取、空链接处理、多行文本规范化等核心转换逻辑
• turndown-comparison.test.ts：对真实网站（needle.engine）进行转换对比测试，确保端到端质量

测试用例覆盖了 AI 工具最常遇到的坑：aria-label 链接、图片 alt 文本链接、无文本空链接、多行 HTML 文本合并等场景。

争议与局限

Electrobun 的生态风险：Electrobun 是一个相对小众的框架，虽然有 Bun 生态加持，但相比 Electron 缺乏成熟的插件生态和社区积累。如果 Electrobun 停止维护，迁移成本可能较高。

macOS 构建强依赖：虽然配置了 build:stable:win 和 build:stable:linux 脚本，但 macOS 版本构建需要 macOS 环境（MACOSX_DEPLOYMENT_TARGET=14.0），Linux 桌面构建需要额外处理图标路径问题。跨平台 CI/CD 存在一定门槛。

非 Web 服务：md-browse 是桌面端应用，不提供 Headless 模式或 HTTP API。如果需要在服务器端批量处理网页转换，需要另找方案（如 Puppeteer + Turndown 服务端部署）。

行业意义：重新定义 AI 的"读网页"体验

md-browse 代表了一个新兴类别：AI-Native 浏览器。它不追求替代 Chrome/Firefox，而是专为 AI 工具设计的内容管道。随着 AI 编程助手（Copilot、Claude Code）、AI 搜索（RAG 管道、知识库构建）的大规模应用，对高质量网页内容提取工具的需求正在快速增长。

GitHub 253 颗星、22 个 fork 的数据表明，这个方向正在引起开发者社区的关注。作为一个 MIT 协议的开源项目，md-browse 为构建 AI 内容管道的开发者提供了可直接参考的技术实现——尤其是 Turndown 转换规则的调优经验，对于任何需要网页→结构化文本场景都有借鉴价值。