onesvm-browser-server/.dsh/contracts/plan-20260901-03.md

Commander Plan: 控制面 Go 实现（contract-20260901-browser-impl）

状态: done 创建: 2026-09-01（Asia/Shanghai）· 收口: 2026-09-02 plan_id: plan-20260901-03 run_id: run-20260901-browser-impl contract: contract-20260901-browser-impl.md 验收链: W1→W2∥W3∥W4→W5 → ITER-1（冒烟三根因）→ ITER-2（冷启动窗口）→ V1 verify PASS-with-issues → ITER-3（P1 配额结算+三接线）→ V2 reverify PASS → V3 arch-review PASS-with-debt → ITER-4（D-1/D-2 必修债就地修复）。产物：.dsh/artifacts/run-20260901-browser-impl/{impl-receipt-w1..w5, verify.md, reverify.md, arch-review.md, wc.txt, smoke/smoke-run.log, fail-*.md}。

目标

单二进制三角色（gateway/scheduler/proxymanager）+ 五 Dock 适配器 + SQLite 队列 + stack 与部署产物，达到「部署 mgr1 测试」就绪态（详见 Contract §5 A1–A6）。

背景与约束

• 权威设计：docs/design-arch + plan-final + mcp-usage（契约面）+ deploy-prod-preset（端口/资源/灰度）
• 组织纪律：600 行/文件上限、密钥 fail-closed、urlapi、东八区、镜像 save/load
• 模型：Worker 用 impl-glm-5.3-flash（ZCode 实现型 subagent，含 Bash/文件全工具）；验收用独立 Explore（只读）+ 主会话复核

模块化拆解（防上帝文件）

server/
  go.mod                      # module onesvm.com/onesvm/browser-server
  cmd/browser-server/main.go  # role 分流入口（gateway|scheduler|proxymanager）
  internal/contract/          # 信封/Job/RawResult/DockAdapter 接口/错误码（A1）
  internal/store/             # SQLite open+migrations+repos（A1）
  internal/auth/              # key 校验/签发（A1+A2 admin）
  internal/policy/            # SSRF/域名规则/robots（A1）
  internal/safetyscan/        # 词表/PII redact/注入包裹（A1）
  internal/httpx/             # 共享 client + Size/Type guard（A1）
  internal/gateway/           # HTTP handler + MCP JSON-RPC + enqueue 转发（A2）
  internal/scheduler/         # 队列/派发/reaper/路由/模版层/pressure（A3）
  internal/dock/              # 五适配器：searxng.go trafilatura.go cdp.go（lightpanda+shell 共用）cdp_client.go（A3/D8）
  internal/proxymanager/      # 订阅/探活/P2C/路由 API（A4）
  internal/config/            # env 解析（fail-closed 辅助）
stacks/browser-server.yml
scripts/deploy-mgr1.sh  scripts/smoke-local.sh

步骤表

step_id	goal	worker	scope (write)	acceptance	depends_on	status
W1	骨架门：go.mod+目录+contract/store/config 全量实现+auth/policy/safetyscan/httpx 全量+单测	impl-glm-5.3-flash	server/ 全部（本步建立骨架与公共包）	A1 全项 + A6.1/6.2 + go test 全绿	—	todo
W2	gateway：MCP handler + HTTP v1 + admin key 面 + enqueue 转发 + 缓存	impl-glm-5.3-flash	server/internal/gateway/ server/cmd/	A2 全项 + A6 golden 信封测试	W1	todo
W3	scheduler：队列/派发/reaper/路由/模版层/pressure + dock 五适配器	impl-glm-5.3-flash	server/internal/scheduler/ server/internal/dock/	A3 全项 + A6.1/6.2	W1	todo
W4	proxymanager：订阅解析/探活/P2C/路由 API	impl-glm-5.3-flash	server/internal/proxymanager/	A4 全项	W1	todo
W5	stack/Dockerfile/Makefile/脚本 + 本机冒烟 + amd64 构建	impl-glm-5.3-flash	stacks/ scripts/ server/Dockerfile Makefile	A5 全项 + A6.4/6.5	W2,W3,W4	todo
V1	独立验收 verify（只读）：跑 A6 全部门槛，产 verify.md / fail-*.md	Explore（readonly）	写 .dsh/artifacts/run-20260901-browser-impl/verify.md	A6 六项逐一核对 + T1–T7 复核	W5	todo
V2	reverify（builder 修复后复核，只读）+ 行数检查落 wc.txt	Explore（readonly）	写 reverify.md wc.txt	修复项复验 + 全绿	V1（若有 fail）	todo
V3	架构审查（core_framework 强制）：解耦/行数/契约对齐/门闩矩阵	主会话指挥（read-only 审查，独立 reviewer subagent）	写 arch-review.md	无 P0/P1	V2	todo

并行策略

W1 先行（串行）；W2 ∥ W3 ∥ W4 并行派发；W5 收口；V1→V2→V3 验收链。

风险

• modernc.org/sqlite 拉取需网络（Go proxy 镜像）；失败则降级 CGO-free 备选或升级用户
• 冒烟依赖本机 Docker 与缓存镜像（searxng/trafilatura 已缓存）；境外引擎冒烟可能空结果——用 stub 断言形状即可
• 五适配器 + 三角色工程量集中在一个 Worker 会话可能超长 → W1 公共包先行落稳，W2–W4 各自独立目录，边界清晰可各自验收
• headless-shell Swarm 按需拉起依赖 socket 权限——冒烟仅验证「不可用时降级」路径，Swarm 拉起留部署轮实机验证