onesvm-browser-server/docs/dev-handoff-20260902.md

type	status	created
runbook	active	2026-09-02

接手开发说明

读者：第一次改这个仓的工程师 / Agent。读完应能：找到权威文档、在本机跑通测试、知道改哪一层、知道什么不能做。 决策权威：plan-final-20260901.md。机制权威：design-arch-20260901.md。现网能力：mcp-usage-20260901.md §4。仓库地图：根 README.md。

0. 十分钟路径

1. 读根 README.md §1–§3（问题、分层、入选方案）。
2. 读本文 §1–§4（目录、事件、怎么改、怎么验）。
3. cd server && go test -race ./... 必须绿。
4. 再按任务读：路由 → internal/scheduler/routing.go；抓取 → stacks/trafilatura/app.py + internal/dock/；合规 → internal/policy/；MCP 契约 → internal/gateway/mcphandler.go。

不要从 .dsh/contracts/ 或 superseded 手稿当现行 acceptance。过程产物在 .dsh/artifacts/（gitignore）。

1. 进程与包

单二进制三角色，Swarm 里三个服务：

-role	职责	有状态
gateway	MCP /mcp、HTTP /v1/*、Auth、策略预检、入队	无。可多副本
scheduler	SQLite 队列、能力路由、Dock 适配器、模版层、Cookie 罐	有。replicas=1，钉节点
proxymanager	订阅、探活、选出口	replicas=1

适配器在 scheduler 进程内，引擎在旁边的容器（SearXNG / Trafilatura / Lightpanda / shell）。

要改	去哪	不要
工具参数 / 信封	internal/contract/、gateway/mcphandler.go	只改文档不改 schema
搜索 junk 过滤	scheduler/searx_parse.go isJunkSearchHit	在适配器里偷偷丢结果
精读 TLS/UA	stacks/trafilatura/app.py（真抓取）	只改 Go httpx 假装 Chrome
指纹模版	internal/fingerprint/	模版和 impersonate 错代
Cookie 罐	internal/session/ + store/session.go	把 Cookie 写进 MCP / jobs JSON
robots / SSRF	internal/policy/	fail-open 放行内网
出站代理	internal/proxymanager/	在适配器里自己拨代理
部署	stacks/browser-server.yml、scripts/deploy-mgr1.sh	在 Swarm 节点上 docker pull

JobEnvelope.Session 与 RawResult.SetCookies 是 json:"-"。打破这条 = Cookie 进审计/MCP，P0。

2. 事件表（本服务已填、热修只改碰到的行）

事件	怎么活	怎么死	多快死
search/read 请求	认证过 → 入队 ACK → 适配器出 RawResult → 模版层信封	策略 denied；上游 blocked/upstream/timeout	入站跟网关；出站 Trafilatura 15s；队列硬顶 120s
排队位	running+queued < 60 才接	超限 503，只拒新	消费者按 Retry-After
Cookie 罐	200 且非投毒则 Sanitize 后覆盖该域	403/验证页/换出口 → 整域删	TTL 2h，硬顶 6h，60s reap
指纹模版	节点 HOSTNAME 种子，8 套落库，内存只持 active	不因单次失败换脸	进程重启从库恢复同一张脸
渲染槽	Lightpanda 多槽；shell 默认 0 副本	shell 忙则互斥停接	空闲 10min 计数（本版不自动 scale）
密钥	X-Service-Token，库内 hash	缺省 fail-closed	吊销缓存 ≤10s

「用默认超时」不算已填。Go 出站禁止 http.DefaultClient。I/O 第一参必须是 ctx。

3. 改代码时的分层

消费者 → gateway（认证/配额/SSRF/robots）
       → scheduler 入队
       → 路由（region + 是否要渲染）
       → dock 适配器（只产 RawResult）
       → 模版层（体积守卫 / fit markdown / 安全扫描 / 信封）

新增第 6 个引擎：实现 init/health/execute/teardown/capabilities，注册路由标签，不要再写一套合规。对照 docs/overview-integration-20260901.md §2。

P0 指纹自洽：impersonate、UA、sec-ch-ua、platform 钉同一 Chrome 大版本（现网 136）。Go httpx 保持诚实 UA。

P1 罐硬顶：每域 20 颗、单条 4KiB、总 2MiB、64 域 LRU。登录态名（session-token / sid / __secure-*psid 等）直接拒收。

4. 验证

合入前：

make fmt && make vet
cd server && go test -race ./...
make wc          # 单文件 >600 行必须拆

改了 MCP 参数或信封：同步 docs/mcp-usage-20260901.md 与 mcphandler.go 的 schema，并补/改 golden。

改了 Trafilatura：必须重建 onesvm/trafilatura-http:dev，只更 Go 镜像是半接线（真抓取在 Python）。

现网复测：用 HTTP /v1/search /v1/read 即可（与 MCP 同一内核）。不要把消费方 key 写进脚本提交。

5. 部署（🟡，须用户确认）

目标是 primary mgr1 192.168.1.51，不是 dev-swarm。默认 scripts/deploy-mgr1.sh 是 dry-run。

已知坑（已踩过，不要再踩）：

1. 生产节点禁直连 Docker Hub；本机构建 amd64 → save|load → --resolve-image never。
2. 同 tag :dev 覆盖后必须 docker service update --force，否则还跑旧任务。
3. Lightpanda CDP 握手 Host 必须是 127.0.0.1:9222，Docker 服务名会被拒。
4. Trafilatura cgroup 现网是 192m（64m 会 OOM 137）。deploy-prod-preset 里仍写 64m，以 stack 为准。
5. 海外 search 出口键用 https://www.bing.com/，不要拿空 URL 去 /api/exit。
6. 单次适配器超时不要把整实例健康闩死；只有 /healthz 失败或 HTTP 5xx 才摘适配器。

回滚：docker stack rm browser-server（命名卷保留）。不要 git push --force。

6. 文档怎么维护

变了什么	更新哪
工具参数 / 错误码 / 现网能力	mcp-usage-20260901.md（消费方权威）
联调步骤 / 验收用例	integration-vlepontas-20260901.md
决策（档位、Bing-only、不做 L4）	plan-final；不要只改 overview
队列字段 / Dock 五方法	design-arch
选型理由	decision-candidates
接手路径 / 现网坑	本文

NFP：规范进组织 base/，本仓只写本服务事实。密钥只在 deploy.env / 组织 credentials.md，禁止写进 docs。

7. 不要做的事

• 为「让 Google 出结果」去伪装 Chrome + Go TLS，或给消费方换出口绕 robots。
• 把 Amazon 登录 Cookie / TOTP 账号池搬进本服务（DaaS 的实证：决定变量是出口 IP）。
• 未填事件表就加新中间件（Redis、第二套队列）。
• 未授权 commit / push；用户没说「确认执行」就 --apply 到 mgr1。
• 用 2026-09-01 bench 的站点三分表覆盖现网 §4（BBC/百科/Amazon 结论已漂移）。