# Contract: onesvm-browser-server 联网搜索服务架构选型与实测评定

> 状态: done
> 创建: 2026-09-01（Asia/Shanghai）
> run_id: run-20260901-browser-arch
> CASA Contract Gate — 仅 `approved` / `in_progress` 后进入 Execute

## deliverable_type

docs + spike（架构方案文档 + 开源方案实测评定；本轮**不**写生产业务代码）

## complexity

core_framework（最终方案须经 Architecture Review 通过才可 done）

## model_family

architect（最终方案）；实测/调研步骤 hard/simple 见 Plan 步骤表

## model_override

（空）

## 档位

commander（用户明确「作为开发架构与开发指挥官」）

## 背景

新仓 onesvm-browser-server 要构建「支持可扩容、集成多浏览器自构建方案、高并发排队」的联网搜索服务，服务对象为 Vlepontas（60 会话级）与 EAI 等内部 toB 智能体。用户给出 6 项任务：统一出口 / 集群与排队 / 拓展坞协议+整合器 / ProxyManager 合规代理 / 开源方案筛选实测 / 最终方案 review。用户已确认四项关键决策：① 部署目标 dev-swarm 内网集群；② 已有代理订阅（容灾后续补充，明文仅存 `.dsh/artifacts/proxy-subscriptions.local.md`，gitignore）；③ 出口 MCP Server 为主 + HTTP API 兜底；④ 本机 Docker 全量实测。

## scope

### in_scope

```
.dsh/contracts/**
.dsh/artifacts/**
.dsh/casa-runtime/**
docs/**
research/**
bench/**
```

### out_of_scope

```
生产/primary 环境任何变更（本轮仅设计+本机实测）
其它业务仓（vlepontas / EAI 等）
onesvm-dev-md/base/credentials.md（只读不改）
git commit / push（除非用户明确要求）
代理订阅明文（禁止写入任何 in-scope 的可提交文件；仅 .dsh/artifacts/*.local.md）
生产级源码实现（src/** 本轮不建，方案通过后另开 Contract）
```

## acceptance

- [ ] 最终方案文档 `docs/` 覆盖用户任务 1–6 全部要点，含 mermaid 拓扑
- [ ] 实测报告覆盖**国内外各 ≥2 套**候选方案，每套含：数据质量样本、延迟、内存占用、成功率、反爬表现；搜索需求模板 ≥5 套（国内搜索 / 国内正文提取 / 国外搜索·代理 / 国外 JS 渲染页 / 60 会话 burst 压测）
- [ ] 集群规格设计落在 dev-swarm 现实约束（3 节点 × ~6.5GB RAM）内，且**本项目全栈（网关+排队+ProxyManager+无头 worker 集群）总内存 ≤1GB，按需求从低水位渐进递增至 1GB 上限**；给出无 Redis 排队机制与横向扩展公式（含 1GB 内的渐进扩容档位表）
- [ ] ProxyManager 设计含：订阅解析容灾、健康检查轮换、出口端合规拦截（违反中国法律的数据获取直接拦截）+ MCP 文档消费侧规则（双向保险）
- [ ] 出口形态 = MCP Server 为主 + HTTP API 兜底；HTTP 侧采用组织 urlapi 惯例（独立端口 + `/search-api` 类前缀），认证头遵循 service-secret-protocol（静态 key 走 `X-Service-Token`/`X-API-Key`，禁 Bearer）
- [ ] 有头浏览器仅抽象插拔预留，不建具体设施
- [ ] 所有实测数据来自本机 Docker 真实运行，禁止纸面编造（每条数据可追溯至 `bench/` 产物）
- [ ] Verify + 独立 Reverify 双过；Architecture Review PASS

## constraints

- 能不加 Redis 就不加（用户硬性偏好，排队机制须给无 Redis 方案）
- **本项目集群总内存硬上限 1GB，且按需求渐进递增（起步低水位 → 逐步增至 1GB）**：内存成为选型的决定性指标，实测必须精确记录每方案 idle/单会话/60 burst 三档内存；超轻量内核（Lightpanda/Bouncy/chrome-headless-shell/PinchTab 类）优先级上调，重型方案（Camoufox 等）须论证单实例内存或降为预留档
- **若 bench 数据显示 1GB 无法维持 Vlepontas 60 会话级 + EAI 并发负载**，最终方案必须附「扩容提议」：给出维持该负载所需的具体规格（内存总量/节点分布/各组件副本数）与预期性能（并发能力/延迟/吞吐），每项数字由 bench 实测数据换算支撑，供用户决策
- 轻量化/无头优先；有头仅预留插拔
- 候选方案最终评定：国内外各 ≥2，总数控制在 4–6 套，稳定质量好优先
- 本机 Mac Docker 实测须控制资源（同时运行候选容器 ≤3，实测完即停）
- 时间/时区一律 Asia/Shanghai
- 源文件行数硬上限 600（本轮主要为文档与 bench 脚本）
- 实测执行类委派 `subagent_cursor`（brief 写 `Required model: grok-4.6?effort=high`；复杂实测 `xhigh`）

## artifact_io

| stage | 读取 (kinds/paths) | 写入 (kinds/paths) |
|-------|--------------------|--------------------|
| S1 research | web + 用户附表 | `.dsh/artifacts/run-20260901-browser-arch/research/*.md` |
| S2 select | S1 产物 + 附表 | `.dsh/artifacts/run-20260901-browser-arch/select.md` + `bench/plan.md` |
| S3a proxy-probe | `.dsh/artifacts/proxy-subscriptions.local.md` | `.dsh/artifacts/run-20260901-browser-arch/proxy-probe.md` |
| S3b/S3c bench | S2 选定方案 + 代理 | `bench/**` + `.dsh/artifacts/run-20260901-browser-arch/bench/*.md,*.json` |
| S4 arch-design | KB + S1 | `docs/design-arch-*.md` |
| S5 final-plan | 全部前置产物 | `docs/plan-final-*.md` |
| S6 verify/reverify | S5 文档 + 全部产物 | `.dsh/artifacts/run-20260901-browser-arch/review*.md` |
| S7 arch_review | S5 + norms | `.dsh/artifacts/run-20260901-browser-arch/arch-review.md` |

## stage_dag

```
[S1] ∥ [S3a] → [S2] → [S3b ∥ S3c] → [S5]
[S4（依赖 S1，与 S2/S3 并行）] ↗
[S5] → [S6 verify+reverify] → [S7 arch_review] → done
```

## revisions

| 日期 | 变更摘要 | 作废 artifact |
|------|----------|---------------|
| 2026-09-01 | 初版；用户四问已确认（dev-swarm / 代理订阅已有 / MCP+HTTP / 本机全量实测） | — |
| 2026-09-01 | 用户补充硬约束：本项目集群总内存 ≤1GB 且按需求渐进递增；内存升为选型决定性指标 | — |
| 2026-09-01 | 用户补充：若 1GB 不够维持 Vlepontas+EAI 负载，须给出扩容提议（规格+预期性能，bench 数据支撑） | — |
| 2026-09-01 | S6 ITERATE：Verify PASS + Reverify FAIL（P1×2/P2×4/P3×2）→ 主会话修订 plan-final 与 design-arch（记账口径/入队路径/420×/mihomo 标注/节点布局/扩容换算/端口取代/MCP 表述），送双重复查 | reverify.md 初版结论 FAIL，待复审 |

## notes

- 组织 KB 入口：`onesvm-dev-md/base/development-standards.md`、`deployment-rules.md`、`infrastructure-inventory.md`；经验 `experience/projects/vlepontas.md`（既有 WSG/Tavily 先例，本服务为其自构建替代/升级）、`dev-swarm.md`
- dev-swarm 事实：3 manager（.61/.62/.63，VM107/108/109），6656MB RAM/节点，overlay 10.60.0.0/16，Engine 29.5.3；镜像传输走 docker save/load + `--resolve-image never`
- 已有 central-proxy（.53:7890，订阅 :8080/sub/onesvm.yaml）可作 ProxyManager 参考/复用点
- 风险：① 代理订阅节点质量未知（S3a 先探活）；② 本机 Mac 资源有限，全量实测分批；③ 部分候选（Camoufox/Lightpanda）平台兼容性需实测验证
- 回滚：本轮仅文档与本机容器，`docker compose down` + 删文档即可