613 lines
29 KiB
Markdown
613 lines
29 KiB
Markdown
# 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 路径示例）
|
||
|
||
```ts
|
||
// 未来 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>>` 作为每会话的串行化锁：
|
||
|
||
```ts
|
||
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 |
|
||
|
||
**触发方式**：
|
||
|
||
```bash
|
||
# 命令级（最高优先级）
|
||
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 集成
|
||
|
||
```ts
|
||
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 指纹参数
|
||
|
||
```bash
|
||
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 代理参数
|
||
|
||
```bash
|
||
# 完整代理 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 路径解析
|
||
|
||
```ts
|
||
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 兼容 |
|