GPU_GUARD_MONOREPO/docs/superpowers/specs/2026-05-04-netabrowser-cli-s1-design.md

netabrowser-cli S1 基础设施层 设计文档

Neta 子项目 netabrowser-cli 第一个迭代：浏览器后端 daemon service + CLI 包装 + skill 元数据。 不含任何业务 service（业务 service 留给 S2/S3）。

元数据	值
子项目	netabrowser-cli S1（基础设施层）
创建日期	2026-05-04
估期	~10-12 天
状态	设计完成，待 user 复核 → writing-plans
关联	geo S1 联调暂停（Task 22）；netabrowser-cli 完成后 geo PlainChromiumProvider 改调 BrowserDaemonService

---

1. 目标

为 Neta 平台提供反风控 + 拟人化的浏览器自动化基础设施，统一服务以下三类调用方：

1. NetaClaw Agent：通过 netabrowser-cli skill（命令行调用，AI token 友好）
2. 后端业务 service（如未来的 XiaohongshuLoginService）：通过 @Inject BrowserDaemonService 直接调
3. 未来的电商自动化模块：同 #2

S1 完成后，AI Agent 可以用 cli 命令探索任意网页（小红书/淘宝/抖音/拼多多），后续 S2/S3 把固化的 SOP 封装为业务 service。

2. 关键决策（brainstorming 阶段已确认）

决策点	决策
skill 范围	三个 skill 并存：playwright-cli + patchwright-cli + netabrowser-cli。前两个保留不动
拟人化粒度	完整拟人化：贝塞尔轨迹 + 滚动 + 视觉停顿 + 字符间随机间隔 + 偶尔错字回退
拟人化触发	默认拟人化：一个命令 = 人类行为；提供 --no-humanize 用于测试
daemon 进程	嵌入 backend（Midway @Provide @Singleton），单进程；崩溃隔离的代价不值
实施风格	Service-First：BrowserDaemonService 为核心；CLI 是 thin client 调 backend HTTP；后端业务直接 @Inject service
chromium 打包	内嵌完整打包（Inno Setup [Files]），安装包 ~400MB
拟人化实现	ghost-cursor 开源库 + 自加套：用 ghost-cursor 的贝塞尔轨迹，自己加随机延迟/滚动/停顿/错字模拟
平台补丁	S1 只做通用 CLI，小红书/抖音/淘宝特定补丁 → S2
S1 范围	仅基础设施（daemon service + cli + skill），无业务 service
数据库	local + prod 都用 neta_test（用户已确认）

3. 已有架构契合度

Neta 在 2026-04-25 后已有完整 windows-runtime 体系：

已有机制	netabrowser-cli S1 复用方式
pkg/yao-pkg 打包 backend.exe	netabrowser-cli 单独 pkg 打包成 netabrowser-cli.exe
Inno Setup 安装器	增加 [Files] 段把 chromium/win64/* 拷到安装目录
.NET 托盘	不动
comm/config-loader.ts	不改；netabrowser-cli 通过 backend HTTP 间接读 config
comm/data-dir.ts	不改；daemon 内拼子路径 <dataDir>/browser-profiles/、<dataDir>/states/
comm/runtime-info.ts	不改；netabrowser-cli 读 runtime-info.json 拿端口 + secret
/app/base/runtime/status /stop	不动；新增 /admin/browser-daemon/* 平行路径
bundled skills 自动入安装包	netabrowser-cli skill 沿用

意思：S1 完全在现有 windows-runtime 框架内增量构建，不重写打包/托盘/安装器。

---

4. 架构与目录

4.1 三层职责

┌──────────────────────────────────────────────────────────────┐
│ 调用方层（S1 范围外）                                          │
│ NetaClaw Agent  ←─── netabrowser-cli skill（探索期 token 省）│
│ Geo / 电商业务  ←─── @Inject BrowserDaemonService（固化期）  │
└──────────────────────────────────────────────────────────────┘
                              ↓ ↓
┌──────────────────────────────────────────────────────────────┐
│ S1 范围                                                        │
│                                                                │
│ packages/netabrowser-cli/         CLI 包装 + Chromium 二进制 │
│ packages/backend/...browser-daemon/  Daemon Service + HTTP   │
│ packages/backend/skills/netabrowser-cli/  Skill 元数据       │
└──────────────────────────────────────────────────────────────┘

4.2 后端模块目录

packages/backend/src/modules/netaclaw/browser-daemon/
├── service/
│   ├── daemon.service.ts          # ★ BrowserDaemonService（核心，单例）
│   ├── humanizer.service.ts       # 拟人化操作包装（ghost-cursor + 自加套）
│   └── fingerprint.service.ts     # neta-chromium 指纹参数管理
├── controller/admin/
│   ├── session.ts                 # /open /close /list 会话管理
│   ├── interaction.ts             # /click /fill /type /scroll /hover 拟人化交互
│   ├── navigation.ts              # /goto /back /forward /reload
│   ├── state.ts                   # /cookie-list /cookie-set /state-save /state-load
│   └── inspect.ts                 # /snapshot /screenshot /eval /run-code
├── runtime/
│   ├── chromium-launcher.ts       # 启动 neta-chromium 子进程（路径解析、proxy、fingerprint args）
│   ├── session-registry.ts        # Map<sessionName, BrowserContext> 内存表
│   └── cleanup.ts                 # backend 退出时优雅关闭所有 context
└── config.ts

4.3 netabrowser-cli 包目录

packages/netabrowser-cli/
├── package.json                   # bin: netabrowser-cli → dist/bin/main.js
├── src/
│   ├── bin/
│   │   └── main.ts                # CLI 入口（commander 解析）
│   ├── commands/
│   │   ├── open.ts                # netabrowser-cli open <url> --session=xx --proxy=xx --fingerprint=xx
│   │   ├── close.ts
│   │   ├── click.ts / fill.ts / type.ts / scroll.ts / hover.ts / press.ts
│   │   ├── cookie.ts              # cookie-list / cookie-set / cookie-clear
│   │   ├── state.ts               # state-save / state-load
│   │   ├── navigate.ts            # goto / back / forward / reload
│   │   ├── snapshot.ts / screenshot.ts / eval.ts / run-code.ts
│   │   └── list.ts                # netabrowser-cli list（列出所有 session）
│   ├── client/
│   │   ├── http-client.ts         # 调 backend HTTP API
│   │   └── runtime-info.ts        # 解析 backend runtime info 拿端口和 secret
│   └── output/
│       └── formatter.ts           # --raw / 默认格式化输出
├── vendor/                        # patchright 补丁源码——仅作"未来改造参考"，运行时不依赖
│   ├── patchright/                # Kaliiiiiiiiii-Vinyzu/patchright（driver patches 源码，已 vendor）
│   └── patchright-nodejs/         # Kaliiiiiiiiii-Vinyzu/patchright-nodejs（client patches 源码，已 vendor）
│                                  # 运行时直接 npm install patchright（编译产物）；
│                                  # 当未来要改 patch（如加小红书反检测）才需要本地跑 vendor 里的 patches 流程
├── chromium/
│   └── win64/                     # neta-chromium 二进制 397MB（已就位，gitignore）
├── tests/
└── README.md

4.4 Skill 目录

packages/backend/skills/netabrowser-cli/
├── SKILL.md                       # 给 NetaClaw Agent 看的命令清单
└── references/
    ├── humanization.md            # 拟人化能力说明
    ├── fingerprint.md             # 指纹参数说明
    ├── proxy.md                   # 代理配置说明
    └── examples/                  # 典型场景示例

---

5. 核心数据流

5.1 启动会话（探索期 AI 路径）

NetaClaw Agent 决定打开淘宝
   ↓
exec("netabrowser-cli open https://www.taobao.com \
        --session=geo-1 \
        --proxy=http://e50b26:7ecdccfd@210.51.27.112:10000 \
        --fingerprint-seed=42 \
        --profile-dir=geo-1 \
        --headed")
   ↓
netabrowser-cli/src/bin/main.ts
   → 解析参数
   → 读 runtime-info.json 拿 backend 端口 + secret
   → POST http://127.0.0.1:8003/admin/browser-daemon/open
        Headers: x-neta-control-secret: <secret>
        Body: {sessionName, url, proxy, fingerprintSeed, profileDir, headed}
   ↓
backend → AdminBrowserDaemonSessionController
   → @Inject BrowserDaemonService
   → daemonService.open({...})
   ↓
BrowserDaemonService.open():
   1. 校验 sessionName 不重复（查 session-registry）
   2. 拼 launch args：
      - executablePath = <安装目录>/chromium/win64/chrome.exe
      - args = ['--fingerprint=42', '--fingerprint-platform=Windows', ...]
      - userDataDir = <dataDir>/browser-profiles/<profileDir>
      - proxy = {server, username, password}
   3. patchright chromium.launchPersistentContext() 启动
   4. 把 BrowserContext 存入 session-registry
   5. 返回 {sessionName, pageCount, url}
   ↓
HTTP 200 → cli 输出格式化结果给 AI

5.2 拟人化点击

AI: netabrowser-cli click e15 --session=geo-1
   ↓
cli → POST /admin/browser-daemon/click {sessionName, ref}
   ↓
daemonService.click(sessionName, ref):
   const ctx = registry.get(sessionName);
   const page = ctx.pages()[0];
   const locator = page.locator(`[data-ai-ref="${ref}"]`);

   await humanizer.click(page, locator);
        ↓
        Humanizer.click:
          1. 计算目标元素 box 中心
          2. ghost-cursor 生成贝塞尔轨迹（鼠标当前位置 → 目标）
          3. 沿轨迹移动，每段 5-15ms；10% 概率轨迹中段微停顿 50-200ms
          4. 到达目标后停顿 100-300ms（人类视觉确认）
          5. mousedown → 50-150ms → mouseup
          6. 20% 概率 click 后 micro-scroll 2-10px
   ↓
返回 {clicked: true, snapshotRef: 'e16'}

5.3 抓 Cookie + 持久登录态（固化期 service 路径示例）

// 未来 S3 的 XiaohongshuLoginService（不在 S1 范围）
@Provide()
class XiaohongshuLoginService {
  @Inject() browserDaemon: BrowserDaemonService;
  @Inject() encryptService: GeoEncryptService;

  async loginAndCapture(account: GeoAccountEntity) {
    const session = `geo-${account.id}`;
    await this.browserDaemon.open({
      sessionName: session,
      url: 'https://www.xiaohongshu.com',
      proxy: this.toProxyConfig(account.proxy),
      fingerprintSeed: account.fingerprintSeed,
      profileDir: `geo-${account.id}`,
      headed: true,
    });

    await this.browserDaemon.click(session, '登录按钮 selector');
    await this.browserDaemon.waitForUrl(session, /\/explore\//, 60_000);

    const cookies = await this.browserDaemon.getCookies(session, 'xiaohongshu.com');
    await this.browserDaemon.saveState(session, `<dataDir>/states/geo-${account.id}.json`);

    account.cookies = this.encryptService.encrypt(JSON.stringify(cookies));
    account.loginStatus = 'logged_in';
    await this.accountRepo.save(account);

    await this.browserDaemon.close(session);
  }
}

关键点：S3 业务 service 通过 @Inject 直接调 BrowserDaemonService，不走 HTTP，不走 cli。性能 = 直接 patchright API 调用。

5.3.1 service ↔ HTTP 路径等价性约束（强制）

CLI 路径与业务 @Inject 路径必须严格等价：调用同一个 BrowserDaemonService 方法，得到同样的副作用。

强制规则：

1. controller/admin/*.ts 必须是 service 方法的 thin wrapper，不允许加任何业务逻辑（参数转换、auth 检查、日志记录都不行）
2. controller 只做 4 件事：① 解析 HTTP body → DTO；② 校验 auth（见 §5.5）；③ 调 this.daemonService.xxx(dto)；④ 序列化返回值
3. 业务逻辑（重试、降级、补偿、校验）必须在 service 层实现
4. 测试加 contract test：每个 HTTP endpoint 跟同名 service 方法行为一一对照（mock service，verify HTTP 调用 1:1 转发）

5.4 Backend 重启时的会话恢复

backend 启动 → BrowserDaemonService @Init:
   1. 扫描 <dataDir>/states/*.json
   2. 不主动 launch（避免启动阻塞），仅记录 known sessions
   3. 当 cli/business 第一次 open(sessionName='geo-1')，发现该 sessionName 有持久化 state，自动 loadState

backend 关闭 → BrowserDaemonService @Destroy:
   1. 遍历 session-registry
   2. 每个 context 先 saveState 到 dataDir
   3. context.close() 优雅关闭
   4. 超时 5s 强制 kill

重启后状态语义（重要）：

• ✅ 可恢复：sessionName、cookie、localStorage（通过 storageState 文件）
• ❌ 不可恢复：snapshot ref（如 e15）、page handles、in-memory selectors

→ AI Agent 在 backend 重启后必须重新调 snapshot 命令获取新 ref。spec/skill 文档明确说明此约束。

5.5 HTTP API 鉴权模型

威胁模型：netabrowser-cli daemon API 能驱动浏览器登录用户社媒账号、抓 cookie，权限极高。本机其他进程也可能调用 → 必须鉴权。

方案（与 Neta 现有 /app/base/runtime/* 一致）：

层	措施
网络层	controller 中间件强制 req.ip === '127.0.0.1' 或 ::1，非 loopback 直接 403
凭据层	复用 runtime-info.json 中的 controlSecret（已有机制）。每次 HTTP 请求 header x-neta-control-secret: <secret> 必填，不匹配 401
CLI 端	netabrowser-cli 启动时自动读 <dataDir>/runtime-info.json 获取 secret，每次请求自动附 header
service 层	@Inject 调用方（业务代码）天然在 backend 进程内，不需要 secret

实现锚点：参考 packages/backend/src/modules/base/middleware/runtime-control.middleware.ts（runtime-info secret 现有中间件，按需复用或新建一个 browser-daemon-auth.middleware.ts）。

5.6 并发与会话锁

问题：cli 和 service 可能同时调 open(sessionName='geo-1')，两个请求都看到 sessionName 不存在 → 都启动 chrome → registry 第二次 set 覆盖第一次 → 第一个 chrome 进程残留。

方案：BrowserDaemonService 内部维护 Map<sessionName, Promise<void>> 作为每会话的串行化锁：

private locks = new Map<string, Promise<void>>();

async withLock<T>(sessionName: string, fn: () => Promise<T>): Promise<T> {
  const prev = this.locks.get(sessionName) ?? Promise.resolve();
  let release!: () => void;
  const next = new Promise<void>(r => (release = r));
  this.locks.set(sessionName, prev.then(() => next));
  try {
    await prev;
    return await fn();
  } finally {
    release();
    if (this.locks.get(sessionName) === next) this.locks.delete(sessionName);
  }
}

async open(opts) {
  return this.withLock(opts.sessionName, async () => {
    // 安全地 check-then-launch
  });
}

所有 service 方法（open/close/click/fill/cookie-list/...）都在该锁内执行，保证同 sessionName 操作严格串行。

5.7 内存与会话调度策略

问题：100 个 chrome × 200-400MB ≈ 20-40GB RAM，普通 16GB 机器扛不住。

策略：

维度	决策
软上限	默认同时活跃 session 数上限 = min(物理内存GB / 0.5, 50)。可通过 config.yaml 的 browserDaemon.maxActiveSessions 覆写
空闲回收	session 超过 60min 无命令 → 自动 saveState 后 close（释放 chrome 进程内存）；下次 open 同 sessionName 自动 loadState 重启
触达上限	新 open 请求 → 先 LRU 回收最久未使用的 idle session；如全部 active 中无 idle 可回收 → 返回 503 + 重试建议
优先级	DTO 加 priority?: 'low' | 'normal' | 'high' 字段，high 优先级抢占 low 优先级的 session 位
拒绝策略	默认是 fail-fast（503）；DTO 可选 --queue=true 让请求排队等位（最长 30s）
指标	service 暴露 getStats()：activeCount/idleCount/totalRamMB/queueLength，供监控面板和决策使用

实现锚点：runtime/session-scheduler.ts 实现 LRU + 软上限 + 队列。

5.5 错误处理

场景	处理
sessionName 已存在	返回 409 Conflict + 现有 session 信息
找不到 chrome.exe	抛 ChromiumNotInstalled，提示重新安装
chrome 启动失败	抛 LaunchFailed，附带 chromium stderr 最后 50 行
元素 ref 找不到	抛 RefNotFound，附带最近 snapshot 相邻元素
拟人化轨迹超时（10s）	降级直接 click，记 warn
backend 崩溃	所有 context 跟着崩；持久化 state 仍在；下次启动重新 launch

---

6. 拟人化与指纹细节

6.1 拟人化能力清单（默认开启）

操作	行为
click	ghost-cursor 贝塞尔轨迹 → 停顿 100-300ms → mousedown(50-150ms) → mouseup
type	字符间随机间隔 80-250ms；5% 概率模拟错字 → backspace → 重输
fill	先 click focus，再走 type 流程
press	按下后 30-100ms 抬起
hover	贝塞尔轨迹移到目标，停留 200-800ms
scroll	wheel events 而非 jump-to-position；多次 30-80px，间隔 50-150ms
goto	页面 load 后随机停留 1-3s
idle（隐式）	每命令完成后 50-200ms 默认延迟

6.2 拟人化的三档可调

问题：完整拟人化每命令 +2-5s。100 账号 × 30 操作 = 4 小时纯延迟，批量场景会卡死。

方案：三档 --humanize-mode：

档位	行为	单命令开销	适用
full（默认）	贝塞尔轨迹 + 视觉停顿 + 字符间隔 + 错字回退 + micro-scroll	2-5s	养号、敏感操作、AI 探索
fast	保留延迟（200-500ms）但去掉鼠标轨迹、错字、micro-scroll	0.3-0.7s	批量发布、批量评论、批量数据采集
off	完全关闭，立即执行	<100ms	测试、CI

触发方式：

# 命令级（最高优先级）
netabrowser-cli click e15 --humanize-mode=fast

# 会话级（open 时设默认值）
netabrowser-cli open <url> --session=xx --humanize-mode=fast

# 全局环境变量
NETA_BROWSER_HUMANIZE_MODE=fast netabrowser-cli click e15

# 兼容老开关
netabrowser-cli click e15 --no-humanize    # 等价于 --humanize-mode=off

实现要点：humanizer 接受 mode: 'full' | 'fast' | 'off'，每个动作内部按 mode 分支选择行为。

6.3 ghost-cursor 集成

import { createCursor } from 'ghost-cursor';

class Humanizer {
  async click(page: Page, locator: Locator) {
    const box = await locator.boundingBox();
    if (!box) throw new Error('Element not visible');

    const cursor = createCursor(page as any, undefined, true);
    await cursor.moveTo({ x: box.x + box.width/2, y: box.y + box.height/2 }, {
      randomizeMoveDelay: true,
      moveDelay: random(50, 150),
    });
    await sleep(random(100, 300));
    await page.mouse.down();
    await sleep(random(50, 150));
    await page.mouse.up();
    if (Math.random() < 0.2) {
      await page.mouse.wheel(0, random(2, 10));
    }
  }
}

6.4 neta-chromium 指纹参数

netabrowser-cli open <url> \
  --session=geo-1 \
  --fingerprint-seed=42                  # 单一 seed 自动派生所有维度（推荐）

# 或细粒度控制：
  --fingerprint-platform=Windows \
  --fingerprint-platform-version=10.0.0 \
  --fingerprint-brand=Chrome \
  --fingerprint-brand-version=144 \
  --fingerprint-hardware-concurrency=8 \
  --fingerprint-language=zh-CN \
  --fingerprint-timezone=Asia/Shanghai

底层翻译为 chrome.exe 命令行参数（已通过 chrome 144.0.7559.132 验证：seed=11111 与 seed=22222 产生不同 canvas/webgl 指纹）。

6.5 代理参数

# 完整代理 URL（最常用）
netabrowser-cli open <url> --session=xx \
  --proxy=http://e50b26:7ecdccfd@210.51.27.112:10000

# 拆分参数
  --proxy-server=http://210.51.27.112:10000 \
  --proxy-username=e50b26 \
  --proxy-password=7ecdccfd

底层用 patchright launchPersistentContext({proxy: {...}})，已验证出口 IP 真实变成代理 IP。

6.6 会话生命周期

状态	触发	行为
created	open 调用	内存 context + 持久 profileDir + session-registry 记录
active	同上	等待命令
closed	close 调用 / backend 退出	saveState → context.close() → 从 registry 删除
idle-timeout	60min 无命令	自动 saveState 到磁盘，关闭 context；下次 open 同 sessionName 自动 loadState

--no-idle-timeout 关闭自动空闲回收（养号常驻场景）。

---

7. 集成 + 打包

7.1 与 Neta 现有代码集成清单

组件	改动
pnpm-workspace.yaml	加 packages/netabrowser-cli
packages/backend/package.json	加 patchright（npm 包，编译产物，不依赖 vendor 的 patches 源码）+ ghost-cursor 依赖
packages/backend/src/modules/netaclaw/	新增 browser-daemon 子目录
packages/backend/src/comm/data-dir.ts	不改；daemon 内拼子路径
packages/backend/src/comm/runtime-info.ts	不改
packages/backend/installer/setup.iss	增加 [Files]：chromium/win64/*
packages/backend/scripts/build-windows-installer.js	增加复制 chromium 二进制
packages/backend/scripts/pkg-build.js	不改；netabrowser-cli 单独 pkg 打包
packages/backend/skills/netabrowser-cli/	新增 skill 目录

7.2 chromium 路径解析

function resolveChromiumPath(): string {
  if (process.env.NETA_CHROMIUM_PATH) return process.env.NETA_CHROMIUM_PATH;
  if (isPkg()) {
    return path.join(path.dirname(process.execPath), 'chromium', 'win64', 'chrome.exe');
  }
  return path.resolve(__dirname, '../../../../../../netabrowser-cli/chromium/win64/chrome.exe');
}

7.3 安装包目录结构（prod 模式）

C:\Program Files\Neta\
├── backend.exe
├── Neta.Tray.exe
├── netabrowser-cli.exe            ★ 新增
├── config.yaml
├── chromium\
│   └── win64\                     ★ 新增 397MB
│       ├── chrome.exe / chrome.dll / ...
├── data\
│   ├── browser-profiles\          # 每会话独立 profile
│   ├── states\                    # 持久化登录态
│   ├── logs\
│   └── runtime-info.json
└── skills\
    ├── netabrowser-cli\           ★ 新增
    ├── playwright-cli\
    └── patchwright-cli\

---

8. 测试策略

层	方法
Humanizer 单元	mock page，验证 ghost-cursor 调用 + 延迟范围 + 错字回退
BrowserDaemonService 单元	mock patchright，验证 session 注册/launch args 拼装/清理
chromium-launcher 单元	验证路径解析（dev/pkg/env 三种）
Controller 集成	jest + supertest，跑 open → click → cookie → close（mock page）
CLI bin 单元	mock HTTP，验证参数解析、output formatter
真机冒烟	手工启动 backend，cli 调 open https://httpbin.org/ip --proxy=...，验证出口 IP；访问 https://abrahamjuliot.github.io/creepjs/ 看 trust score

---

9. 验收标准

1. ✅ pnpm dev 启动 backend，<dataDir>/runtime-info.json 写入
2. ✅ netabrowser-cli list 返回空 []
3. ✅ netabrowser-cli open https://httpbin.org/ip --session=test --proxy=http://e50b26:7ecdccfd@210.51.27.112:10000 返回 200，出口 IP 210.51.27.112
4. ✅ netabrowser-cli open https://creepjs.com --session=test --fingerprint-seed=42 --headed 启动有头浏览器，creepjs trust score ≥ 70%
5. ✅ netabrowser-cli click <ref> --session=test 触发拟人化轨迹（mock 验证 + 真机肉眼） 5b. ✅ --humanize-mode=fast 单命令延迟 < 1s；--humanize-mode=off 单命令延迟 < 200ms 5c. ✅ HTTP API 不带 x-neta-control-secret header → 401；非 loopback → 403 5d. ✅ 同 sessionName 并发 open 两次，第二次返回 409 Conflict（锁机制有效） 5e. ✅ 软上限触达后，新 open 返回 503（含 retryAfter 字段）；--queue=true 时排队等位
6. ✅ netabrowser-cli cookie-list --session=test --domain=httpbin.org 返回 cookie JSON
7. ✅ netabrowser-cli state-save --session=test --output=/tmp/state.json 写文件，state-load 能恢复
8. ✅ netabrowser-cli close --session=test 关闭，list 不再显示
9. ✅ backend 重启后，已 saveState 的 session 通过 open --session=同名 自动 loadState 恢复
10. ✅ Inno Setup 打包后的安装包安装到全新 Windows，启动后能跑通 1-9
11. ✅ Skill 元数据完整（SKILL.md 命令清单 + references/），NetaClaw Agent 能识别

---

10. 范围红线（不在 S1）

• ❌ 平台特定补丁（小红书/抖音/淘宝特殊反风控）→ S2
• ❌ 业务 service（XiaohongshuLoginService 等）→ S2/S3
• ❌ geo BrowserAutomationService 迁移 → S2 单独 spec
• ❌ macOS / Linux 支持（chromium 只打包 win64）→ 后续
• ❌ 多 chrome 实例分布式调度 → 后续
• ❌ skill SKILL.md 国内平台示例（仅留通用例子）→ S2
• ❌ 替换/删除现有 playwright-cli / patchwright-cli skill → 不动

---

11. 风险与依赖

风险	缓解
上游 patchright 修复 bug 但 npm 包发布慢	通常上游 release 后 npm publish 间隔几天可接受；急用时启用 vendor 的 patches 本地构建
国内场景出现 patchright 默认未覆盖的反检测	vendor 的 patches 源码是改造起点，那时下载 playwright 源码本地跑 patches 流程，发布到 monorepo 内部 npm 仓
ghost-cursor 不兼容 patchright	已知 ghost-cursor 接受 puppeteer-style page，patchright 兼容；冒烟阶段实测
安装包 400MB 用户嫌大	安装界面提示"含浏览器内核 ~300MB"；后续可选"在线安装版"
chrome.exe 进程残留	daemon @Destroy 优雅关闭 + 启动时扫 chromium/win64/chrome.exe 进程清理
100 账号同时启动 OOM	session-registry 设上限（如 50），超过自动 idle-timeout 回收最久未用的
AI 误调拟人化命令导致超慢	拟人化每命令 +2-5s（full）；提供 --humanize-mode=fast/off 三档兜底；SKILL.md 明确说明性能特征与档位选择
chromium 144.0.7559.132 不是真 fingerprint-chromium	已验证：seed=11111 与 seed=22222 产生不同 canvas/webgl，确认是真 fingerprint-chromium
AI ref 协议（e15）依赖 playwright-cli 内部状态，patchright 无现成实现	plan 阶段 spike #1：选定方案（自实现 ref 协议 / 改用 selector / vendor playwright-cli ref 代码）
ghost-cursor 是为 puppeteer/playwright 设计，patchright 改了 mouse. 实现，可能不兼容*	plan 阶段 spike #2：跑一个 demo 在 patchright + neta-chromium 上用 ghost-cursor click，验证轨迹和反检测都生效

---

12. 工作流

完成本 spec 后：

1. user 复核本文档
2. 调用 superpowers:writing-plans 生成 docs/superpowers/plans/2026-05-04-netabrowser-cli-s1-plan.md
3. plan 第一阶段必须包含两个 spike（在写实现代码前完成）：
   • Spike #1：AI ref 协议——验证一种方案：① 自实现（snapshot 时 inject data-ai-ref 到 DOM + 内存 ref→selector 表）；② 改用 selector 字符串作为命令参数；③ vendor playwright-cli 的 ref 协议代码进 netabrowser-cli。spike 产出：选定一种 + demo 跑通 click(e15) 整套流程
   • Spike #2：ghost-cursor on patchright + neta-chromium——demo：用 patchright launchPersistentContext 启动 neta-chromium → 用 ghost-cursor 在页面上轨迹移动鼠标 click 一个按钮 → 验证 ① 鼠标确实走贝塞尔轨迹 ② 在 brotector/creepjs 上仍过反检测
4. user 复核 plan
5. superpowers:subagent-driven-development 实施
6. superpowers:verification-before-completion 逐条核对验收标准
7. superpowers:requesting-code-review
8. 完成后回头继续 geo S1 联调（Task 22）：geo PlainChromiumProvider 改调 BrowserDaemonService

---

13. 变更日志

日期	变更
2026-05-04	初稿（brainstorming 完成后产出）
2026-05-04	架构 review v2 修复 7 项必修：①patchright 改用 npm 包+vendor 仅参考 ②HTTP API auth 模型（loopback+secret） ③service↔HTTP 等价性约束 ④sessionName 串行化锁 ⑤内存调度策略（LRU+软上限+优先级） ⑥拟人化三档（full/fast/off） ⑦backend 重启后 ref 必须重 snapshot；plan 阶段加两个 spike：AI ref 协议 + ghost-cursor 兼容