> ## Documentation Index
> Fetch the complete documentation index at: https://web2md.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Bridge

> 让 AI Agent 通过你的 Chrome 扩展批量转换 Reddit 和任意网站

## 概览

Agent Bridge 让 AI Agent（Claude Code、Cursor、Cowork 等）远程控制 Web2MD Chrome 扩展批量转换 URL——尤其是 Reddit、JS 渲染页面和需要登录的页面，这些页面服务端 API 都拿不到。

AI Agent 不走 Web2MD API（Reddit 会拦截），而是通过 [Native Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging) 向你本地的 Chrome 扩展发指令。扩展用**你的真实浏览器会话**——带着你的 cookie 和登录状态——在后台标签页打开每个页面，提取内容、转成 Markdown 并返回结果。

<Note>
  Agent Bridge 需要 **PRO 套餐**，并在你的机器上安装 **native messaging host**。扩展需要在 Chrome 中处于启用状态。
</Note>

## 架构

```
AI Agent ←MCP/stdio→ MCP Server ←TCP:12315→ Native Host ←NM→ Chrome Extension → Any Website
```

| 组件              | 角色                                    |
| --------------- | ------------------------------------- |
| **AI Agent**    | Claude Code、Cursor、Cowork——调用 MCP 工具  |
| **MCP Server**  | 把 MCP 工具调用翻译成 TCP 消息                  |
| **Native Host** | 在 TCP 和 Chrome Native Messaging 之间做中继 |
| **Chrome 扩展**   | 打开标签页、提取 HTML、转成 Markdown             |

所有通信都是**本地的**——不会有任何数据离开你的机器。Native Host 只监听 `localhost:12315`。

## 安装配置

### 第一步：构建 MCP Server

```bash theme={null}
cd packages/mcp-server
pnpm build
```

### 第二步：安装 Native Messaging Host

```bash theme={null}
cd packages/mcp-server
./install.sh <your-extension-id>
```

<Tip>
  在 `chrome://extensions` 开启开发者模式后可以找到扩展 ID。找到 Web2MD，复制 ID 字符串（例如 `ijmgpkkfgpijifldbjafjiapehppcbcn`）。
</Tip>

<Warning>
  安装完成后必须**完全退出 Chrome（Mac 上按 Cmd+Q）再重新打开**。Chrome 只在启动时读取 Native Messaging 清单——仅仅重载扩展是不够的。
</Warning>

安装脚本会：

* 把 host 文件复制到 `~/.web2md/`（避开 macOS 对 `~/Desktop` 的 TCC 限制）
* 解析 `node` 的绝对路径（Chrome 启动时 PATH 极简）
* 把 NM 清单写入 Chrome 的 `NativeMessagingHosts` 目录

### 第三步：配置 MCP

<Tabs>
  <Tab title="Claude Code">
    添加到 `~/.claude/settings.json`：

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    添加到 `~/.cursor/mcp.json`：

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    添加到你的 Claude Desktop 配置：

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 第四步：验证

在 Chrome 打开 `chrome://extensions` → 点击 Web2MD 的 "Service Worker" 链接 → 查看 Console：

```
[Web2MD] Service worker started
[Web2MD] Connected to native host
[Web2MD] Native host TCP relay ready on port 12315
```

看到这三行，Agent Bridge 就跑通了。

## 可用工具

### agent\_convert

用 Chrome 扩展转换单个 URL。

| 参数    | 类型     | 说明       |
| ----- | ------ | -------- |
| `url` | string | 要转换的 URL |

**返回：** Markdown 内容，附带标题、来源 URL、字数和阅读时长。

**最适合：** Reddit 帖子、需要登录的页面、JS 渲染的站点。

### agent\_batch\_convert

批量转换最多 50 个 URL。URL 会依次处理——扩展在后台标签页打开一个页面，提取内容后关掉标签页，再处理下一个。

| 参数     | 类型        | 说明                   |
| ------ | --------- | -------------------- |
| `urls` | string\[] | 要转换的 URL 数组（最多 50 个） |

**返回：** 每个 URL 的结果完成即流式返回，最后附上汇总。

**最适合：** 调研类工作流——批量转换 Reddit 帖子、HN 讨论或竞品页面，交给 AI 分析。

<Info>
  所有成功的转换都会自动存进你的[控制台历史记录](https://web2md.org/dashboard/history)，并附带 AI 生成的摘要和标签。
</Info>

## 使用示例

<AccordionGroup>
  <Accordion title="转换 Reddit 帖子">
    **你：** Convert this Reddit thread to Markdown: [https://www.reddit.com/r/LangChain/comments/1siwh6q/](https://www.reddit.com/r/LangChain/comments/1siwh6q/)...

    **Agent：** *（调用 `agent_convert`）* 这是转换后的帖子，含 7 条讨论法律文档 RAG 精度的评论……
  </Accordion>

  <Accordion title="批量转换做调研">
    **你：** Batch convert these 5 Reddit URLs and summarize the key takeaways:

    * [https://reddit.com/r/MachineLearning/comments/](https://reddit.com/r/MachineLearning/comments/)...
    * [https://reddit.com/r/LocalLLaMA/comments/](https://reddit.com/r/LocalLLaMA/comments/)...
    * [https://reddit.com/r/LangChain/comments/](https://reddit.com/r/LangChain/comments/)...
    * [https://reddit.com/r/artificial/comments/](https://reddit.com/r/artificial/comments/)...
    * [https://reddit.com/r/ChatGPT/comments/](https://reddit.com/r/ChatGPT/comments/)...

    **Agent：** *（调用 `agent_batch_convert`）* 5/5 个 URL 全部转换成功。以下是核心结论……
  </Accordion>

  <Accordion title="转换需要登录的页面">
    **你：** Convert my company's internal wiki page at [https://wiki.internal.com/architecture](https://wiki.internal.com/architecture)

    **Agent：** *（调用 `agent_convert`）* 由于你在 Chrome 里已登录该站点，我成功提取了完整内容……
  </Accordion>
</AccordionGroup>

## 支持的站点

Agent Bridge 使用与扩展相同的 16 个站点专用提取器：

| 站点                | 方式             | 需要标签页？ |
| ----------------- | -------------- | :----: |
| Reddit            | JSON API       |    否   |
| Hacker News       | Algolia API    |    否   |
| YouTube           | Transcript API |    否   |
| arXiv             | HTML 抓取        |    否   |
| Twitter/X         | DOM 提取         |    是   |
| GitHub Issues/PRs | REST API       |    否   |
| Medium            | DOM 提取         |    是   |
| Substack          | DOM 提取         |    是   |
| Wikipedia         | DOM 提取         |    是   |
| Stack Overflow    | SE API         |    否   |
| 其他任意站点            | 完整页面 HTML      |    是   |

标记「否」的站点通过 API 调用转换——更快也更稳定，其余的走后台标签页。

## 故障排查

<AccordionGroup>
  <Accordion title="'Native host not installed' 或 'not found'">
    Chrome 还没加载 NM 清单。**完全退出 Chrome（Cmd+Q）再重新打开。** 仅仅重载扩展是不够的。
  </Accordion>

  <Accordion title="'Native host has exited' 立刻退出">
    Chrome 无法执行 host 脚本。常见原因：

    * 找不到 `node`——重新运行 `./install.sh`，它会使用 node 的绝对路径
    * host 在 TCC 受保护目录（`~/Desktop`、`~/Documents`）里——重新运行安装脚本把它移到 `~/.web2md/`
  </Accordion>

  <Accordion title="MCP 报 'Agent connection error'">
    Native Host 的 TCP 服务没在运行。确认：

    1. Chrome 已打开
    2. Web2MD 扩展已加载
    3. Service Worker 控制台显示 "TCP relay ready on port 12315"
  </Accordion>

  <Accordion title="'Failed to extract content from the page'">
    扩展未登录。在 Chrome 里打开 Web2MD 弹窗，登录你的 PRO 账户。
  </Accordion>

  <Accordion title="'Tab load timeout'">
    目标页面加载太慢，慢站点出现这种情况很正常。扩展每个标签页最多等 15 秒。Reddit 走 JSON API 提取器不需要标签页，所以 Reddit 上的超时通常意味着帖子 URL 无效（404）。
  </Accordion>

  <Accordion title="转换没出现在控制台历史记录里">
    历史保存需要扩展以 PRO 账户登录。保存是 fire-and-forget 的——如果 API 调用静默失败，转换就不会出现。检查你的认证 token 是否有效。
  </Accordion>
</AccordionGroup>

## 与 MCP Server 的区别

| 特性             | MCP Server（`convert_url`） | Agent Bridge（`agent_convert`） |
| -------------- | ------------------------- | ----------------------------- |
| 运行位置           | 服务端 API 调用                | 你本地的 Chrome 浏览器               |
| Reddit 支持      | ❌ 被 Reddit 拦截             | ✅ 使用真实浏览器会话                   |
| 需要登录的页面        | ❌ 无法访问                    | ✅ 使用你的 cookie                 |
| JS 渲染页面        | ❌ 不执行 JavaScript          | ✅ 完整 Chrome 渲染                |
| 速度             | 更快（无标签页开销）                | 较慢（要打开真实标签页）                  |
| 是否需要 Chrome 打开 | 否                         | 是                             |

**经验法则：** 公开页面用 `convert_url`；Reddit、需要认证的页面和重度依赖 JS 的站点用 `agent_convert` / `agent_batch_convert`。