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

# Vlepontas 联调使用说明（草稿 · 部署批准后生效）

> 状态说明：mgr1 测试期已部署（2026-09-02）。入口 `http://192.168.1.51:8640`，overlay alias `browser-server`。
> 详细工具参数/错误码/能力范围见《MCP 使用文档》`docs/mcp-usage-20260901.md`，本文是联调操作手册。

## 1. 联调目标

验证 Vlepontas 真实业务流在本服务上的表现，回答三个问题：① 数据能力够不够（覆盖/质量）；② 性能体感是否达标（延迟/排队）；③ 是否需要升级数据能力（L4 强对抗档/官方 API）或性能（L3 1.5GB）。

## 2. 接入步骤

### 2.1 注册与拿 key

1. Vlepontas 侧提供：主体标识 `vlepontas`、联系人、预期负载（峰值会话数、搜索/读取/渲染比例）。
2. 管理侧签发：`X-Service-Token: bs_vlep_…`（明文只回传一次，线下传递）；默认 scope `search,read`；如需 `extract`（JSON schema 抽取）单独申请并审计。
3. 配额预设：rpm=120、daily=50k、concurrent_sessions=60（对齐 60 会话级上限；联调期可放宽观察）。

### 2.2 MCP 接入（主路径）

Vlepontas casa-worker 走 overlay（按 WSG 先例附加 `vlepontas-casa-net`）：

```json
{
  "mcpServers": {
    "onesvm-browser-server": {
      "url": "http://browser-server:8640/mcp",
      "headers": { "X-Service-Token": "bs_vlep_…" }
    }
  }
}
```

工具两个：`search`（发现 URL，`region: domestic|overseas` 自选）与 `read`（URL 精读，默认 fit markdown）。

### 2.3 HTTP 兜底（排错/非 MCP 链路）

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

### 2.4 纪律（与现有 WSG/Tavily 通道的差异）

- 错误码语义：`denied`=合规拦截（不要重试对抗）；`timeout/upstream` 可重试（≤2 次，服从 `Retry-After`）；429/503 带 `running/queued` 现状，自行退避。
- 队列深度 60 = 排队位 + 在途合计；超限收 503 是背压不是故障。
- 渲染（JS 页）是稀缺槽位：先 `read` 默认通道，空正文再升级；不要对 `blocked` 站点（Amazon/Medium/Reddit/X/知乎/微博/百度百科/SO/YouTube）反复打。

## 3. 联调验收用例（双方共同执行，预期值来自 2026-09-01 实测）

| # | 用例 | 预期 |
|---|---|---|
| C1 | 国内搜索「跨境电商 出口退税 政策 2026」region=domestic | ≥5 条政策域结果，p50 ≤1s |
| C2 | `read` 该政策页（gov.cn 系） | 壳页 HTTP 通道可能抽空 → 升级 JS 通道得全文（实测 9577 字/约1s） |
| C3 | 国外搜索「best bluetooth earbuds 2026」region=overseas | 有结果但**仅 Bing 源**（D2 已定）；p50 ≤5s |
| C4 | `read` 一个 Shopify 独立站商品页 | 可能被 302 到集合页：系列/价格可见，指定 SKU 不保证——记录业务影响 |
| C5 | 60 会话 burst 混合负载（40 搜索+15 读+5 渲染） | 无 5xx 风暴；搜索/读全过；渲染排队（p95 等待可测） |
| C6 | 访问一个 deny 名单域（联调时指定） | `error.code=denied` + 审计记录，验证合规拦截 |

## 4. 观察指标与反馈回路

联调期 Vlepontas 侧记录：各工具感知延迟、空结果率、denied 命中、渲染等待体感。管理侧提供 `/pressure` 指标快照（队列深度/渲染槽占用/内存比/代理池存活）。

**升级决策回路**（联调结论 → 行动）：

| 若联调发现 | 行动 |
|---|---|
| 渲染等待 p95 超标 / shell 冷启动被感知 | 升 L3 1.5GB（shell 常驻 + 渲染免互斥） |
| Amazon 详情页/Review | **非刚需**（2026-09-01 用户确认：Vlepontas 有既有消费方案覆盖亚马逊数据，本服务不规划 Amazon 方向；L4 档仅理论预留） |
| 舆情（Reddit/X/知乎/微博）成刚需 | Reddit 商用 API（~$0.24/千次）/ RSSHub+Cookie 边车（知乎/订阅流）；X 维持 C 档（无免费读档） |
| 国外搜索质量不满（Bing-only 偏题） | 采购优质/住宅代理出口，或 Brave Search API（出境须法务） |
| 知乎/百科类中文知识需求 | 千帆百科组件（约 0.01–0.036 元/次）/ RSSHub 适配器 |

（依据：`.dsh/artifacts/run-20260901-browser-arch/research/06-blocked-sites.md` 分级路线图。）

## 5. 时间窗与联系

- 联调窗口：上线后一周（建议每日同步 15min）。
- 问题升级：本仓 issue / 管理侧负责人；合规疑问先停后用，走法务。