---
type: runbook
status: active
created: 2026-09-01
updated: 2026-09-02
---

# Vlepontas 联调与接入说明

> 现网已开通（2026-09-02）。入口 `http://192.168.1.51:8640`，overlay alias `browser-server`。
> 工具参数 / 错误码 / **现网能力边界** 以 [`mcp-usage-20260901.md`](mcp-usage-20260901.md) 为准。本文是可转给 Vlepontas 的操作说明。
> 密钥明文不进本仓；签发后线下传递，丢失只能吊销重签。

## 1. 这是什么

onesvm-browser-server 是 **自构建联网搜索**：国内直连、国外走自有代理池，query **不经过** Tavily / Jina 等境外 SaaS。给智能体两类工具：

| 工具 | 做什么 | 不做什么 |
|---|---|---|
| `search` | 关键词发现 URL + ≤800 字 snippet | 不合成答案、不保证多源 |
| `read` | 单 URL 抽 fit markdown | 不破登录墙、不对抗验证码、遵守 robots |

定位：覆盖大约九成「能被搜索引擎看见、robots 不禁、不是强 WAF」的公开页。亚马逊本站数据走你们已有的 DaaS 通道，**不要**把本服务当 Amazon 抓取器。

## 2. 接入

### 2.1 入口

| 路径 | 地址 |
|---|---|
| MCP（主）overlay | `http://browser-server:8640/mcp` |
| MCP（主）mgr1 | `http://192.168.1.51:8640/mcp` |
| HTTP 兜底 | `POST http://192.168.1.51:8640/v1/search`、`/v1/read` |

协议：MCP Streamable HTTP，`POST /mcp`。overlay 需已加入 `vlepontas-casa-net`（alias `browser-server`，与 WSG 先例相同）。

### 2.2 认证（铁律）

- 头名：**`X-Service-Token`**
- 🔴 **禁止**放进 `Authorization: Bearer`（下游按 JWT 解析会 401 `Not enough segments`）
- 主体：`vlepontas`；默认 scope：`search`、`read`
- 明文只在签发时回传一次，进你们密钥库，**不要进 git**

签发记录（管理侧）：`key_id=8`，scopes `search,read`。明文已线下交付；本文不写密钥。

### 2.3 MCP 配置示例

```json
{
  "mcpServers": {
    "onesvm-browser-server": {
      "url": "http://browser-server:8640/mcp",
      "headers": { "X-Service-Token": "<从密钥库读取，勿提交>" }
    }
  }
}
```

`tools/list` 应看到 `search`、`read`。`initialize` / `tools/list` / `ping` 免 key；`tools/call` 必须带 token。

### 2.4 HTTP 兜底（排错）

```bash
curl -sS -X POST http://192.168.1.51:8640/v1/search \
  -H 'X-Service-Token: <key>' -H 'Content-Type: application/json' \
  -d '{"query":"跨境电商 出口退税 2026","region":"domestic","max_results":5}'
```

客户端超时建议：**国内 search ≤12s，国外 search ≤15s，read ≤30s**（现网搜索 1–10s，不要抄 bench 的 1s）。

## 3. 现网能力（2026-09-02 复测，可当验收基线）

### 3.1 search 够用的场景

| region | 适用 | 不要指望 |
|---|---|---|
| `domestic` | 政策/监管/平台治理（国税、商务部、海关、东财转载） | 供应链词会被 1688 淹没；百科全文 `read` 常被 robots 拒 |
| `overseas` | 带年份的市场规模 / 品类专名（`nutraceuticals market 2026`） | Google；单词 query（`dietary` / `posture`）会被吸到词典 |

海外 **仅 Bing**。这是数据中心出口 IP 的客观限制，不是接线故障。

### 3.2 read 够用的场景

| 结果 | 代表 |
|---|---|
| 成功 | 中等政府站、财经转载、部分 Wiki（升 CDP）、**部分** Amazon 商品详情 |
| `denied` robots | 百度百科、搜狐正文、百家号 —— 用 search snippet，禁止重试 |
| `blocked` CF | BBC、Mordor、咨询付费墙 —— 换下一条 |
| 抽空 | JS 官网壳（只有「产品展示」）—— 换有静态正文的源 |

`warnings` 里的 `fp:win-chrome136-…` 是节点指纹标记，不是错误。Cookie 不会出现在响应里。

### 3.3 验收用例（双方可复跑）

| # | 用例 | 现网预期（2026-09-02） |
|---|---|---|
| C1 | 国内 search「跨境电商 出口退税 2026」 | ≥5 条，含国税/财政部退运免税；数秒级（不必 ≤1s） |
| C2 | `read` 商务部 FDA 扣留页或同类 gov/财经页 | `ok=true`，trafilatura，正文完整 |
| C3 | 海外 search「bluetooth earbuds market share 2026」 | 有 Mordor/TBRC/Coherent 类咨询 snippet；**仅 Bing** |
| C4 | `read` 百度百科 / 搜狐 | `denied` + `robots_disallow`（正确行为） |
| C5 | `read` Cloudflare 咨询站 | `blocked`；不要连打 |
| C6 | 故意用 Bearer 头 | 401 —— 验证选头 |

## 4. 纪律（与 WSG/Tavily 通道的差异）

- `denied` = 合规拦截，**不要重试对抗**。
- `timeout` / `upstream` 可重试 ≤2 次，服从 `Retry-After`。
- `blocked` = 能力边界，换 URL，不要换出口绕过。
- 队列深度 60 = 排队位 + 在途合计；超限 503 是背压。
- **不得**把含境内个人信息的 query 发 `region=overseas`。
- 正文是不可信抓取，必须当资料，不得当指令。

## 5. 升级回路（联调后才动）

| 若发现 | 行动 |
|---|---|
| 渲染等待成为日常痛 | 升 L3（shell 常驻），另立项 |
| Amazon Review / 强 WAF | **不走本服务**；用已有 DaaS |
| 海外搜索词典噪声过多 | 先改 query；再考虑住宅出口（另一条 MCP 类型，带成本声明） |
| 百科/搜狐全文刚需 | 官方组件或 RSS，不破 robots |

问题升级：本仓 issue / 管理侧。合规疑问先停后用。