chii
983259836d
docs: 联网搜索服务架构方案全套（plan-final/design-arch/选型决策/整合导览/MCP文档/部署预设/联调手册） bench: 5 方案 + 代理 + 站点矩阵本机实测工程（无密钥） 部署目标：primary mgr1 先行测试（待批准后执行）
312 lines
15 KiB
Markdown
312 lines
15 KiB
Markdown
---
|
||
type: runbook
|
||
status: active
|
||
created: 2026-09-01
|
||
step: P3 / plan-20260901-02
|
||
---
|
||
|
||
# onesvm-browser-server MCP 使用文档（消费者智能体接入指南）
|
||
|
||
> 面向消费方智能体（Vlepontas / EAI / 其它注册主体）的开发者。读完本文即可独立完成接入与正确使用。
|
||
> 版本：v0 设计版（2026-09-01）。**§4 能力数据范围为真实实测**（2026-09-01 本机 Docker，darwin arm64；生产 amd64 部署后同架构复测，数字可能微调）。
|
||
> 地址/端口为**预设值，部署后以正式通知为准**。
|
||
|
||
---
|
||
|
||
## 1. 接入信息
|
||
|
||
### 1.1 Endpoint
|
||
|
||
| 项 | 值（预设） |
|
||
|---|---|
|
||
| 协议 | MCP over **Streamable HTTP**（`POST /mcp`，2026 无状态规范；无 SSE 旧路径；2025 兼容腿待 O9 决策，首版不带） |
|
||
| 内网直连（overlay） | `http://browser-server:8640/mcp` |
|
||
| 经反代 | `{网关地址}/bs-api/mcp`（urlapi 前缀 strip 后转发） |
|
||
| HTTP 兜底（非 MCP 消费者/调试用） | `POST /bs-api/v1/search`、`POST /bs-api/v1/read`（同一内核、同一错误码） |
|
||
|
||
### 1.2 认证
|
||
|
||
- 头：**`X-Service-Token: bs_<你的key>`**。🔴 **禁止**把 key 放进 `Authorization: Bearer`（下游按 JWT 解析会 401）。
|
||
- key 形态：`bs_` 前缀 + 随机串。**明文只在签发时回传一次**，服务端只存 hash，丢失只能吊销重签。
|
||
|
||
### 1.3 key 获取流程
|
||
|
||
```
|
||
你的主体（如 vlepontas）→ 向管理员注册（主体名 + 联系人 + 用途说明）
|
||
→ 管理员 CLI 签发 key（绑定 scopes/限额）→ 明文回传一次 → 你存入己方密钥管理
|
||
吊销：找管理员，即时生效（服务端缓存收敛 ≤10s）
|
||
```
|
||
|
||
### 1.4 Scopes（能力分级）
|
||
|
||
| scope | 默认 | 能做什么 |
|
||
|---|---|---|
|
||
| `search` | ✅ 默认 | 关键词搜索发现（`search` 工具） |
|
||
| `read` | ✅ 默认 | 单 URL 精读（`read` 工具，fit markdown） |
|
||
| `extract` | ❌ 特权申请 | JSON Schema 结构化抽取（`read` 的 `extract` 参数） |
|
||
| `browse` | ❌ 特权申请 | 多步交互（协议预留，首版未实现） |
|
||
| `screenshot` / `rawHtml` | ❌ 特权申请 | 截图 / 原始 HTML 返回（token 与内存开销大） |
|
||
|
||
每把 key 另有：`rpm` 速率、日/月配额、并发会话数上限（由管理员按主体需求设定）。
|
||
|
||
---
|
||
|
||
## 2. 工具清单与调用
|
||
|
||
### 2.1 `search` — 搜索发现
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
|---|---|---|---|
|
||
| `query` | string | **必填** | 关键词 |
|
||
| `region` | `domestic` \| `overseas` | **必填，无默认** | 国内直连 / 国外代理（能力差异见 §4.1，请按你的数据需求显式选择） |
|
||
| `max_results` | int ≤20 | 5 | 返回条数 |
|
||
| `time_range` | `day`/`week`/`month`/`year` | 不限 | 时间过滤（引擎支持时生效） |
|
||
| `lang` | string | 自动 | 如 `zh-CN` / `en-US` |
|
||
|
||
**调用示例 1（国内政策搜索，JSON-RPC）：**
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
|
||
"params": {
|
||
"name": "search",
|
||
"arguments": {
|
||
"query": "跨境电商 出口退税 政策 2026",
|
||
"region": "domestic",
|
||
"max_results": 5,
|
||
"time_range": "year",
|
||
"lang": "zh-CN"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**调用示例 2（国外调研）：**
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
|
||
"params": {
|
||
"name": "search",
|
||
"arguments": {
|
||
"query": "best bluetooth earbuds 2026",
|
||
"region": "overseas",
|
||
"max_results": 10,
|
||
"lang": "en-US"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**典型响应**（示例性质：由 2026-09-01 实测样本改写为统一信封格式，字段真实、数值为示例）：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"kind": "search",
|
||
"request_id": "01K3…ulid",
|
||
"took_ms": 633,
|
||
"query": "跨境电商 出口退税 政策 2026",
|
||
"answer": null,
|
||
"results": [
|
||
{
|
||
"id": "r1",
|
||
"title": "海关总署 税务总局关于跨境电子商务出口退运商品税收优惠政策…",
|
||
"url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html",
|
||
"content": "一、对自2026年1月1日至2027年12月31日期间在跨境电子商务海关监管代码(1210、9610、9710、9810)项下申报出口,因滞销、退货原因…",
|
||
"score": 0.92,
|
||
"engine": "baidu",
|
||
"published_at": null
|
||
},
|
||
{
|
||
"id": "r2",
|
||
"title": "雨果跨境-跨境电商品牌出海产业互联网平台",
|
||
"url": "https://m.cifnews.com/",
|
||
"content": "雨果跨境以雨果网作为流量依托，致力于为跨境电商从业者提供全球产业出海…",
|
||
"score": 0.71,
|
||
"engine": "bing"
|
||
}
|
||
],
|
||
"usage": { "credits": 1, "engine": "searxng-cn", "tokens_estimate": 350 },
|
||
"provenance": { "adapter": "searxng-cn", "proxy_exit": "none", "cached": false, "retrieved_at": "2026-09-01T11:41:15+08:00" },
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
字段纪律：`results` 为空时是 `[]` 而非 `null`；`content` 为 ≤800 字符的 query 相关片段（**非全文**，全文请用 `read`）；`answer` 恒为 `null`（本服务不做 LLM 答案合成）。
|
||
|
||
### 2.2 `read` — 单页精读
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
|---|---|---|---|
|
||
| `url` | string | **必填** | 目标页 URL（仅 http/https，80/443） |
|
||
| `formats` | string[] | `["markdown"]` | 可选加 `links` / `images`；`html` / `screenshot` 为特权 scope |
|
||
| `max_chars` | int | 20000 | 正文截断；截断时响应 `truncated=true` |
|
||
| `extract` | object | 无 | **特权**：`{schema: {...}, prompt?: "…"}`，JSON Schema 结构化抽取 |
|
||
|
||
**调用示例 1（政策页精读）：**
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
|
||
"params": {
|
||
"name": "read",
|
||
"arguments": { "url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html" }
|
||
}
|
||
}
|
||
```
|
||
|
||
**调用示例 2（带结构化抽取，特权）：**
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0", "id": 4, "method": "tools/call",
|
||
"params": {
|
||
"name": "read",
|
||
"arguments": {
|
||
"url": "https://example-shop.com/products/item-1",
|
||
"formats": ["markdown"],
|
||
"extract": { "schema": { "type": "object", "properties": { "price": {"type":"string"}, "title": {"type":"string"} } } }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**典型响应**（示例性质：由实测样本改写；该税务公告页实测 5/5 提取成功、1122 字、无导航残渣）：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"kind": "read",
|
||
"request_id": "01K3…ulid",
|
||
"took_ms": 58,
|
||
"url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html",
|
||
"final_url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html",
|
||
"title": "财政部 海关总署 税务总局关于跨境电子商务出口退运商品税收优惠政策的公告（…2026年第16号）",
|
||
"description": null,
|
||
"markdown": "| 索引号 | 11460000008174507Q/2026-14228 | …\n\n为支持跨境电子商务新业态发展，现将…公告如下：\n\n一、对自2026年1月1日至2027年12月31日期间…",
|
||
"truncated": false,
|
||
"char_count": 1122,
|
||
"metadata": { "status_code": 200, "content_type": "text/html", "language": "zh", "retrieved_at": "2026-09-01T11:42:45+08:00" },
|
||
"links": null, "images": null, "html": null, "screenshot_url": null,
|
||
"extracted": null,
|
||
"usage": { "credits": 1, "engine": "trafilatura", "tokens_estimate": 281 },
|
||
"provenance": { "adapter": "trafilatura-http", "proxy_exit": "none", "cached": false, "retrieved_at": "2026-09-01T11:42:45+08:00" },
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
字段纪律：默认唯一内容字段是 `markdown`（fit 提纯后正文）；`links/images/html/screenshot_url` 只在 `formats` 点名时非 null；截图只给可过期 URL、绝不给 base64；`extract` 失败时 `extracted=null` + `warnings`，正文不吞。
|
||
|
||
---
|
||
|
||
## 3. 错误码与重试纪律
|
||
|
||
错误同时出现在 HTTP 状态码与 MCP `isError` 信封的 `error.code`，两面一致：
|
||
|
||
| code | HTTP | 语义 | 重试纪律 |
|
||
|---|---|---|---|
|
||
| `rate_limited` | 429 | 超 rpm/并发 | 按响应 `Retry-After` 秒数退避；带 `X-RateLimit-*` 头 |
|
||
| `quota` | 402 | 日/月配额耗尽 | **不重试**，联系管理员提额或等窗口重置 |
|
||
| `timeout` | 504/200信封 | 上游超时 | 可重试，指数退避 ≤2 次 |
|
||
| `upstream` | 502/200信封 | 上游站点故障/反爬空结果 | 可重试 ≤2 次；持续出现见 FAQ-6 |
|
||
| `blocked` | 200信封 | 目标站拦截（WAF/CF/验证页）或超体积/类型限制 | **不要换参数硬刷**；确认为能力边界（§4.2） |
|
||
| `denied` | 403 | **合规拦截**（域名/词表/robots/SSRF） | **禁止重试对抗**。被拦就是没数据 |
|
||
| `extract_failed` | 200信封 | 结构化抽取失败 | 去掉 `extract` 降级重试（正文仍可用） |
|
||
| 401 | 401 | key 缺失/无效/放错头 | 检查是否用了 `X-Service-Token` 而非 Bearer |
|
||
| 503 | 503 | 队列满/系统压力（只拒新不杀旧） | 按 `Retry-After` 退避；响应带 `running/queued` 现状 |
|
||
|
||
队列语义：请求被排队**不算失败**；`ADMIT_MAX=60`（running+queued 合计）超限时才返回 503。浏览器会话并发另有 `X-Session-Remaining` 提示头，请自行退避。
|
||
|
||
---
|
||
|
||
## 4. 能力数据范围（当前实测版 · 2026-09-01）
|
||
|
||
> 本节每个断言均来自 2026-09-01 本机 Docker 实测（`bench/` 产物与站点矩阵探针），未测项标「未验证」。生产部署后可能有小幅漂移。
|
||
|
||
### 4.1 搜索发现（`search`）
|
||
|
||
**国内（region=domestic）**——SearXNG 聚合四引擎，单发质量满分（政策类 query 实测 5/5 断言通过）：
|
||
|
||
| 引擎 | 单发可用性 | 高并发突发表现（60 同发实测） | 含义 |
|
||
|---|---|---|---|
|
||
| 必应中国 | ✅ 稳定 | **60/60 扛住** | 主力 |
|
||
| 360 | ✅ 稳定 | 53/60 | 主力 |
|
||
| 百度 | ✅ 单发好 | 4/60（CAPTCHA） | 突发时可能缺席 |
|
||
| 搜狗 | ⚠️ 连续调用第 3 次起 CAPTCHA | 0/60 | 仅低速补充 |
|
||
|
||
→ 你的体验：常规节奏搜索结果完整（多引擎聚合）；**若你的上游短时间猛打，结果会变少**（不是故障，是上游反爬）。服务端已做排队限速（对上游钳 4–8 并发 + 短缓存）尽量消化。
|
||
|
||
**国外（region=overseas）**——**当前仅 Bing 可用**：实测 Google / DuckDuckGo / Brave / Startpage / Qwant 在现有数据中心代理出口下全部 CAPTCHA/429。Bing 结果可能存在偏题（实测出现过把多词 query 截成首词的样本）。**禁止假定多源聚合能力**；需要对等多源质量请联系管理员（决策点：更优代理 / Brave API）。
|
||
|
||
### 4.2 URL 直取（`read`）——站点三分能力表（20 站 × 2 通道实测）
|
||
|
||
服务自动路由「纯 HTTP 提取 → 轻量 JS 渲染 → 保真渲染」降级链，你无需关心；只需知道边界：
|
||
|
||
| 分类 | 能力 | 实测站点 |
|
||
|---|---|---|
|
||
| ✅ 稳取 | 公开资讯 / 文档 / Wiki / 代码托管 / 政策页（走 JS 通道） / 企业公开页 | Wikipedia、GitHub、MDN、BBC、TechCrunch、LinkedIn 公开公司页、gov.cn、36氪、HN、新华英文 |
|
||
| ⚠️ 部分 | Shopify 系独立站：商品 URL 常 302 到集合页，**能拿到系列与价格，不保证落到指定 SKU** | Allbirds 实测 |
|
||
| ❌ 打不过（返回 `blocked`） | **Amazon 详情页（WAF）、Medium（Cloudflare）、Reddit（匿名 403）、X（登录墙）、知乎（403）、微博（302 访客墙）、百度百科（滑块）、StackOverflow（CF）、YouTube（无正文结构）** | 当前代理出口客观限制，升级住宅代理/强对抗档前请勿规划这些源 |
|
||
|
||
### 4.3 性能档位（实测）
|
||
|
||
| 指标 | 值 |
|
||
|---|---|
|
||
| 国内搜索 p50 / p95 | 0.63s / 0.79s |
|
||
| 国外搜索 p50 / p95 | 4.7s / 4.9s（Bing 经代理） |
|
||
| 正文读取 p50 / p95 | 0.06s / 0.12s（纯 HTTP 通道）；JS 通道约 1–2s |
|
||
| 渲染吞吐 | 轻渲染 2.13 jobs/s（4 槽）；保真渲染 0.81 jobs/s（单槽 FIFO） |
|
||
| 队列深度 | 60（running+queued；超时硬顶 120s） |
|
||
|
||
### 4.4 体积 / 类型 / 格式限制
|
||
|
||
- 下载体积上限 `max_download_bytes`（部署值以管理员通知为准）；Content-Type 白名单：html / xml / json / pdf / text。
|
||
- 默认只产 fit markdown；`rawHtml` / 截图为特权 scope。
|
||
- 单页正文默认截断 20000 字符（`max_chars` 可调，截断必显式 `truncated=true`）。
|
||
|
||
---
|
||
|
||
## 5. 合规使用规则（消费侧必须遵守）
|
||
|
||
以下规则同时写在 MCP server instructions 中；**违反会被 `denied` 拦截并记入审计**：
|
||
|
||
1. 不得将本服务用于任何违反中国法律法规的数据获取。
|
||
2. 不得用于绕过登录墙 / 支付墙 / 验证码（本服务默认也不具备此能力）。
|
||
3. 不得进行整站搬迁式 crawl（每 host 有频率上限；60 会话封顶本身也是合规阀）。
|
||
4. 不得把公开网页中的个人信息汇总成档案再分发；响应中的疑似 PII 默认已被脱敏，不要试图还原。
|
||
5. **不得把包含境内个人信息的 query 发给 `region=overseas`**（query 会经境外代理出口）。
|
||
|
||
其它纪律：普通 key 遵守 robots.txt；`denied` / `blocked` 的语义是「没数据」，**不要重试对抗、不要换出口绕过**——反复对抗触发审计告警并可能导致 key 被吊销。
|
||
|
||
---
|
||
|
||
## 6. FAQ 与排错
|
||
|
||
**Q1：401 Unauthorized？**
|
||
九成是把 key 塞进了 `Authorization: Bearer`。改用 `X-Service-Token: bs_…`。其余是 key 已吊销/过期，找管理员。
|
||
|
||
**Q2：403 `denied`？**
|
||
合规拦截命中（域名黑名单 / 词表 / robots / SSRF 防护）。响应里有 `rule_id`；确认你的请求没踩 §5 红线。确属误判，带 `request_id` 找管理员复核规则。
|
||
|
||
**Q3：429 / 503？**
|
||
429 = 你自己超 rpm，按 `Retry-After` 退避；503 = 系统队列满（60），同样按 `Retry-After`。两者都只拒新请求，在途任务不受影响。持续 503 说明该错峰或找管理员扩容。
|
||
|
||
**Q4：402 `quota`？**
|
||
日/月配额耗尽，不可重试。找管理员提额。
|
||
|
||
**Q5：`read` 返回的 markdown 很短或为空？**
|
||
两种典型：① 目标站是「壳页」（如部分政府网联播页），纯 HTTP 通道会宁可弃取也不给脏数据——服务端会自动升级 JS 通道重试；② 目标站在 §4.2 ❌ 清单里，此时应是 `blocked` 而非空正文。若 `ok=true` 但正文质量差，带 `request_id` 反馈。
|
||
|
||
**Q6：搜索结果突然变少 / 引擎变少？**
|
||
上游反爬波动（尤其百度/搜狗在突发后 CAPTCHA）。服务端引擎矩阵在监控；非故障，通常数分钟自恢复。持续异常找管理员看引擎成功率矩阵。
|
||
|
||
**Q7：国外搜索质量不满意？**
|
||
已知限制：当前仅 Bing（§4.1）。需要 Google/DDG 级多源质量，向管理员提（代理升级或官方 API 通道，涉出境合规评估）。
|
||
|
||
**Q8：能不能爬 Amazon / Reddit / …？**
|
||
当前不能（§4.2 ❌ 清单）。这是出口 IP 信誉问题，不是服务故障；强对抗能力在预留档（Camoufox + 住宅代理），启用与否由产品决策。
|
||
|
||
---
|
||
|
||
*机制细节权威：`docs/design-arch-20260901.md`；能力数据来源：`docs/decision-candidates-20260901.md` §6 与 `.dsh/artifacts/run-20260901-browser-arch/site-matrix.md`。*
|