3174 lines
108 KiB
Markdown
3174 lines
108 KiB
Markdown
# netabrowser-cli S1 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
>
|
||
> **上位文档**：[`../specs/2026-05-04-netabrowser-cli-s1-design.md`](../specs/2026-05-04-netabrowser-cli-s1-design.md)
|
||
> **Git 策略**：用户要求"全部完成 + 联调通过后统一提交"。每 task 末尾标注 `Checkpoint`（仅作进度标记，不做 git commit）。
|
||
|
||
**Goal:** 在 Neta monorepo 内交付 netabrowser-cli S1 基础设施：BrowserDaemonService（嵌入 backend）+ netabrowser-cli 二进制 + skill 元数据，提供反风控+拟人化的浏览器自动化能力，统一服务于 NetaClaw Agent 探索期（CLI）和后端业务固化期（@Inject service）。
|
||
|
||
**Architecture:** Service-First 架构：核心是 backend 内的 `BrowserDaemonService`（Midway @Singleton）持有 `Map<sessionName, BrowserContext>`；CLI 是 thin client 通过 HTTP loopback + secret 调 backend；底层用 `patchright` (npm) 启动 vendored `neta-chromium` (fingerprint-chromium)；拟人化用 `ghost-cursor` + 自加套，分 full/fast/off 三档；session-name 串行化锁；LRU 软上限调度。
|
||
|
||
**Tech Stack:** Midway.js 3.20 / TypeScript 5.9 / `patchright` (npm) / `ghost-cursor` (npm) / fingerprint-chromium 144.0.7559.132 (vendored 二进制) / commander (CLI 解析) / jest+ts-jest / Inno Setup / yao-pkg
|
||
|
||
---
|
||
|
||
## ⚠️ v2 修复总览（架构 review 后必读）
|
||
|
||
本 plan 经过架构师交叉验证发现 8 项 P0/P1 问题，已就地修复。实施时优先理解这些修复点：
|
||
|
||
| # | 问题 | 修复落点 |
|
||
|---|---|---|
|
||
| **P0-1** | Controller 路径与 Cool Admin 风格冲突 | Task 11 全部 controller 改用 `@Provide()` + `@Controller('/admin/browser-daemon/<sub>')` + 方法相对路径，参考 `netaclaw/controller/admin/agent_channel.ts` 风格 |
|
||
| **P0-2** | dev 模式 dataDir = `<cwd>/dist`，build 清空状态 | 新增 Task 4b：`resolveBrowserDataDir()` 独立解析（dev 模式 → `<monorepo>/.netabrowser-data/`，prod → `<dataDir>/.netabrowser/`） |
|
||
| **P0-3** | browser-daemon 模块挂载错位 | Task 10 Step 5 明确：把 `BrowserControlAuthMiddleware` 加到 `netaclaw/config.ts` 的 `middlewares` 数组，依靠 `match()` 仅作用于 `/admin/browser-daemon/*` 路径 |
|
||
| **P0-4** | ghost-cursor 类型与 patchright 不兼容 | Task 8 Step 3 humanizer 内部 `createCursor(page as any)` cast |
|
||
| **P1-5** | dev 模式 NETA_TRAY_SECRET 未设 → 全 401 | Task 10 middleware 加 dev 旁路：`process.env.NODE_ENV !== 'production' && expected === ''` 时跳过 secret 校验 |
|
||
| **P1-6** | CLI runtime-info 路径错位（cwd 不对） | Task 14 候选改为 `<monorepo-root>/packages/backend/dist/runtime-info.json` + 强制 `NETA_RUNTIME_INFO` 环境变量优先 |
|
||
| **P1-7** | @Init/@Destroy lifecycle + 60min idle 自动回收缺失 | 新增 Task 9b：`runtime/cleanup.ts` + daemon.service `@Init`/`@Destroy` + scheduler idle timer |
|
||
| **P1-8** | CLI 与会话级 mode 协同 bug | service 移除 modeMap（service-stateless），CLI 端用环境变量 `NETA_BROWSER_HUMANIZE_MODE` 作"会话级默认"，命令级 `--mode` 覆盖 |
|
||
|
||
**额外路径修正**：Task 4 `chromium-launcher` `__dirname` 上溯 **7 层**（不是 6 层）—— 实际路径 `dist/modules/netaclaw/browser-daemon/runtime/` 到 monorepo root 是 7 个 `..`。
|
||
|
||
**版本锁定**：Task 1 安装命令改为 `pnpm add patchright@1.59.4 ghost-cursor@1.4.2`（已验证兼容版本）。
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
### 后端模块（新增 14 个文件）
|
||
|
||
| 路径 | 职责 |
|
||
|---|---|
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/config.ts` | 模块配置 + `maxActiveSessions` 等 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/service/daemon.service.ts` | ★ BrowserDaemonService 核心，统一锁 + 调度入口 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/service/humanizer.service.ts` | 拟人化包装（ghost-cursor + 三档） |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/service/fingerprint.service.ts` | neta-chromium 指纹参数生成 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/service/snapshot-ref.service.ts` | AI ref 协议（spike #1 选定方案） |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/runtime/chromium-launcher.ts` | 路径解析 + patchright launch 包装 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-registry.ts` | Map<name, context> + 串行化锁 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-scheduler.ts` | LRU 软上限调度 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/runtime/cleanup.ts` | @Destroy 时优雅关闭 |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/middleware/control-auth.middleware.ts` | loopback + secret auth |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/session.ts` | /open /close /list /stats |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/interaction.ts` | /click /fill /type /scroll /hover /press |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/navigation.ts` | /goto /back /forward /reload |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/state.ts` | /cookie-list /cookie-set /state-save /state-load |
|
||
| `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/inspect.ts` | /snapshot /screenshot /eval /run-code |
|
||
|
||
### netabrowser-cli 包（新增 13 个文件）
|
||
|
||
| 路径 | 职责 |
|
||
|---|---|
|
||
| `packages/netabrowser-cli/package.json` | bin 声明 + patchright/commander 等依赖 |
|
||
| `packages/netabrowser-cli/tsconfig.json` | TS 配置 |
|
||
| `packages/netabrowser-cli/src/bin/main.ts` | CLI 入口（commander 解析） |
|
||
| `packages/netabrowser-cli/src/client/runtime-info.ts` | 读 backend runtime-info.json |
|
||
| `packages/netabrowser-cli/src/client/http-client.ts` | HTTP 请求 + secret header |
|
||
| `packages/netabrowser-cli/src/output/formatter.ts` | --raw vs 默认 + 错误格式化 |
|
||
| `packages/netabrowser-cli/src/commands/session.ts` | open/close/list（共用一个文件） |
|
||
| `packages/netabrowser-cli/src/commands/interaction.ts` | click/fill/type/scroll/hover/press |
|
||
| `packages/netabrowser-cli/src/commands/navigation.ts` | goto/back/forward/reload |
|
||
| `packages/netabrowser-cli/src/commands/state.ts` | cookie / state |
|
||
| `packages/netabrowser-cli/src/commands/inspect.ts` | snapshot/screenshot/eval/run-code |
|
||
|
||
### 测试文件（新增 11 个）
|
||
|
||
| 路径 | 测试对象 |
|
||
|---|---|
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/chromium-launcher.test.ts` | 路径解析 + launch args 拼装 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/fingerprint.service.test.ts` | seed → args 派生 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/humanizer.service.test.ts` | 三档行为 + 注入 random source 验证延迟范围 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/session-registry.test.ts` | 串行化锁竞态 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/session-scheduler.test.ts` | LRU + 软上限 + 队列 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/snapshot-ref.test.ts` | ref 协议契约 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/daemon.service.test.ts` | 编排：open/click/cookie/close mock 全链路 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/control-auth.middleware.test.ts` | loopback + secret 校验 |
|
||
| `packages/backend/test/modules/netaclaw/browser-daemon/contract.test.ts` | HTTP ↔ service 等价性 contract |
|
||
| `packages/netabrowser-cli/tests/cli-parse.test.ts` | commander 参数解析 |
|
||
| `packages/netabrowser-cli/tests/output-formatter.test.ts` | 输出格式 |
|
||
|
||
### Skill 元数据（新增 5 个文件）
|
||
|
||
| 路径 | 职责 |
|
||
|---|---|
|
||
| `packages/backend/skills/netabrowser-cli/SKILL.md` | 给 NetaClaw Agent 看的命令清单 |
|
||
| `packages/backend/skills/netabrowser-cli/references/humanization.md` | 三档详解 |
|
||
| `packages/backend/skills/netabrowser-cli/references/fingerprint.md` | 指纹参数 |
|
||
| `packages/backend/skills/netabrowser-cli/references/proxy.md` | 代理配置 |
|
||
| `packages/backend/skills/netabrowser-cli/references/examples.md` | 典型场景 |
|
||
|
||
### 集成改动
|
||
|
||
| 路径 | 改动 |
|
||
|---|---|
|
||
| `pnpm-workspace.yaml` | 新增 `packages/netabrowser-cli` |
|
||
| `packages/backend/package.json` | 新增 `patchright` + `ghost-cursor` 依赖 |
|
||
| `packages/backend/installer/setup.iss` | `[Files]` 段加 chromium/win64 + netabrowser-cli.exe |
|
||
| `packages/backend/scripts/build-windows-installer.js` | 复制 chromium 二进制步骤 |
|
||
| `packages/backend/scripts/pkg-build.js` | 增加 netabrowser-cli pkg 编译 |
|
||
|
||
---
|
||
|
||
## 实施依赖图
|
||
|
||
```
|
||
Phase 0: T0(包脚手架) → T1(npm 依赖)
|
||
↓
|
||
Phase 1: T2(Spike #1 ref 协议) ‖ T3(Spike #2 ghost-cursor 兼容) ← 阻塞门
|
||
↓
|
||
Phase 2: T4(launcher) → T5(registry+lock) → T6(scheduler) → T7(open/close)
|
||
↓
|
||
T8(humanizer + click/fill) → T9(state/cookie/snapshot)
|
||
↓
|
||
Phase 3: T10(auth middleware) → T11(controllers) → T12(contract test)
|
||
↓
|
||
Phase 4: T13(cli bin) → T14(client) → T15-17(命令实现) → T18(formatter)
|
||
↓
|
||
Phase 5: T19-20(skill 元数据)
|
||
↓
|
||
Phase 6: T21(pkg build) → T22(installer) → T23(路径解析)
|
||
↓
|
||
Phase 7: T24(联调冒烟) → T25(性能验证) → T26(文档)
|
||
```
|
||
|
||
---
|
||
|
||
## Task 0：netabrowser-cli 包脚手架
|
||
|
||
**Files:**
|
||
- Create: `packages/netabrowser-cli/package.json`
|
||
- Create: `packages/netabrowser-cli/tsconfig.json`
|
||
- Modify: `pnpm-workspace.yaml`
|
||
|
||
- [ ] **Step 1: 把 netabrowser-cli 加入 pnpm workspace**
|
||
|
||
读 `pnpm-workspace.yaml`，确认含有 `packages/*` 通配符（应该已有）。如无 `packages/*` 通配符，加上：
|
||
|
||
```yaml
|
||
packages:
|
||
- 'packages/*'
|
||
```
|
||
|
||
无需修改的话跳过。
|
||
|
||
- [ ] **Step 2: 创建 netabrowser-cli/package.json**
|
||
|
||
```json
|
||
{
|
||
"name": "@neta/netabrowser-cli",
|
||
"version": "0.1.0",
|
||
"description": "Neta 反风控+拟人化浏览器自动化 CLI",
|
||
"private": true,
|
||
"type": "module",
|
||
"bin": {
|
||
"netabrowser-cli": "./dist/bin/main.js"
|
||
},
|
||
"scripts": {
|
||
"build": "tsc -p tsconfig.json",
|
||
"test": "jest"
|
||
},
|
||
"dependencies": {
|
||
"commander": "^12.0.0",
|
||
"axios": "^1.7.0"
|
||
},
|
||
"devDependencies": {
|
||
"@types/node": "^22.0.0",
|
||
"jest": "^29.7.0",
|
||
"ts-jest": "^29.1.5",
|
||
"typescript": "^5.9.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 创建 netabrowser-cli/tsconfig.json**
|
||
|
||
```json
|
||
{
|
||
"compilerOptions": {
|
||
"target": "ES2022",
|
||
"module": "NodeNext",
|
||
"moduleResolution": "NodeNext",
|
||
"outDir": "dist",
|
||
"rootDir": "src",
|
||
"strict": true,
|
||
"esModuleInterop": true,
|
||
"skipLibCheck": true,
|
||
"resolveJsonModule": true,
|
||
"declaration": false
|
||
},
|
||
"include": ["src/**/*"]
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 验证 pnpm 识别 workspace**
|
||
|
||
```bash
|
||
cd C:/Users/lixin/Desktop/RZYX_ZT/Neta-monorepo
|
||
pnpm install
|
||
pnpm list -r --depth=-1 | grep netabrowser-cli
|
||
```
|
||
预期：列表中出现 `@neta/netabrowser-cli`
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
`Task 0 完成`：包注册到 workspace，可以独立 build/test。
|
||
|
||
---
|
||
|
||
## Task 1：backend 安装 patchright + ghost-cursor 依赖
|
||
|
||
**Files:**
|
||
- Modify: `packages/backend/package.json`
|
||
|
||
- [ ] **Step 1: 在 backend 安装 patchright（npm 包，锁定版本）**
|
||
|
||
```bash
|
||
cd packages/backend
|
||
pnpm add patchright@1.59.4
|
||
```
|
||
|
||
> 锁定 1.59.4：经 review 验证此版本兼容 Node 22 + Midway 3.20 + neta-chromium 144.0.7559.132。后续升级前需重测兼容性。
|
||
|
||
- [ ] **Step 2: 安装 ghost-cursor（锁定版本）**
|
||
|
||
```bash
|
||
pnpm add ghost-cursor@1.4.2
|
||
```
|
||
|
||
- [ ] **Step 3: 验证 patchright 能 import**
|
||
|
||
跑一段临时脚本：
|
||
```bash
|
||
cd packages/backend
|
||
node -e "import('patchright').then(p => console.log('patchright loaded:', Object.keys(p).join(',')))"
|
||
```
|
||
预期输出含 `chromium,firefox,webkit,...`
|
||
|
||
- [ ] **Step 4: 验证 ghost-cursor 能 import**
|
||
|
||
```bash
|
||
node -e "import('ghost-cursor').then(p => console.log('ghost-cursor loaded:', Object.keys(p).join(',')))"
|
||
```
|
||
预期含 `createCursor,path,...`
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
`Task 1 完成`：依赖装好，可以在 service 代码 import 使用。
|
||
|
||
---
|
||
|
||
## Task 2 [SPIKE #1]：AI Ref 协议方案验证
|
||
|
||
> 这是 spec §11 的阻塞门 spike。**必须先做，否则后续 interaction 命令无法实现**。
|
||
|
||
**目标**：选定一种 AI ref 协议方案并 demo 跑通。
|
||
|
||
候选方案：
|
||
- **A. 自实现**：snapshot 时给 DOM 注入 `data-ai-ref="e15"` 属性 + 内存维护 `Map<sessionName, Map<ref, ElementHandle>>`
|
||
- **B. 改用 selector**：命令直接接收 selector 字符串（`click 'button:has-text("登录")'`），不要 ref
|
||
- **C. vendor playwright-cli ref 代码**：剥离 playwright-cli 内部 ref 实现引入 netabrowser-cli
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/test/modules/netaclaw/browser-daemon/spike1-ref-protocol.test.ts`
|
||
|
||
- [ ] **Step 1: 写 spike 测试（方案 A，先验证最简实现）**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/spike1-ref-protocol.test.ts
|
||
import { chromium } from 'patchright';
|
||
import * as path from 'node:path';
|
||
import * as fs from 'node:fs';
|
||
|
||
const CHROME = path.resolve(__dirname, '../../../../../../netabrowser-cli/chromium/win64/chrome.exe');
|
||
|
||
describe('Spike #1: AI ref 协议（方案 A 自实现）', () => {
|
||
jest.setTimeout(60000);
|
||
|
||
it('A: snapshot 注入 data-ai-ref，可基于 ref 定位元素', async () => {
|
||
if (!fs.existsSync(CHROME)) {
|
||
console.warn('SKIP: neta-chromium not found at', CHROME);
|
||
return;
|
||
}
|
||
const tmpProfile = path.resolve(process.cwd(), '.spike-profile-1');
|
||
const ctx = await chromium.launchPersistentContext(tmpProfile, {
|
||
executablePath: CHROME,
|
||
headless: true,
|
||
args: ['--fingerprint=12345'],
|
||
});
|
||
const page = ctx.pages()[0] || (await ctx.newPage());
|
||
await page.goto('data:text/html,<button id=login>Login</button><a href=#>Link</a>');
|
||
|
||
// 1. snapshot：给所有可交互元素注入 data-ai-ref
|
||
const refs = await page.evaluate(() => {
|
||
const interactive = Array.from(document.querySelectorAll('button, a, input, select, textarea'));
|
||
const out: { ref: string; tag: string; text: string }[] = [];
|
||
interactive.forEach((el, i) => {
|
||
const ref = `e${i + 1}`;
|
||
el.setAttribute('data-ai-ref', ref);
|
||
out.push({ ref, tag: el.tagName.toLowerCase(), text: (el.textContent || '').trim() });
|
||
});
|
||
return out;
|
||
});
|
||
|
||
expect(refs).toEqual([
|
||
{ ref: 'e1', tag: 'button', text: 'Login' },
|
||
{ ref: 'e2', tag: 'a', text: 'Link' },
|
||
]);
|
||
|
||
// 2. 通过 ref click
|
||
await page.locator('[data-ai-ref="e1"]').click();
|
||
// 不报错 = 通过
|
||
|
||
await ctx.close();
|
||
fs.rmSync(tmpProfile, { recursive: true, force: true });
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑 spike 测试**
|
||
|
||
```bash
|
||
cd packages/backend
|
||
pnpm jest test/modules/netaclaw/browser-daemon/spike1-ref-protocol.test.ts -t 'A:'
|
||
```
|
||
|
||
预期：PASS（含 fingerprint chromium 已在 vendor 里）
|
||
|
||
- [ ] **Step 3: 评审 spike 结果**
|
||
|
||
如果方案 A PASS，写入决策文件：
|
||
|
||
```bash
|
||
cat > packages/backend/src/modules/netaclaw/browser-daemon/SPIKE_DECISION.md << 'EOF'
|
||
# Spike #1 决策：AI Ref 协议
|
||
|
||
**选定方案 A：自实现 data-ai-ref 注入**
|
||
|
||
## 理由
|
||
- 实现简单（一段 page.evaluate JS 即可）
|
||
- 不引入额外依赖
|
||
- 完全可控
|
||
|
||
## 实现要点
|
||
1. snapshot 命令时调用 `injectRefs(page)`，给所有可交互元素加 `data-ai-ref="eN"`
|
||
2. service 内存维护 `Map<sessionName, Map<ref, locator-info>>` 用于审计/调试
|
||
3. interaction 命令收到 ref 后用 `page.locator('[data-ai-ref="${ref}"]')` 定位
|
||
4. 页面跳转/重新 snapshot 后旧 ref 失效（DOM 变化）
|
||
|
||
## 不选 B/C 的理由
|
||
- B（selector）：AI 写 selector 容易错；ref 抽象更友好
|
||
- C（vendor playwright-cli）：playwright-cli 用 socket+state 同步，移植成本高
|
||
EOF
|
||
```
|
||
|
||
如果方案 A FAIL（极不可能），降级 B/C 重写 spike。
|
||
|
||
- [ ] **Step 4: Checkpoint**
|
||
|
||
`Task 2 完成`：方案 A 通过，决策记录在 `SPIKE_DECISION.md`。后续 snapshot-ref.service.ts 实现该方案。
|
||
|
||
---
|
||
|
||
## Task 3 [SPIKE #2]：ghost-cursor on patchright 兼容性验证
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/test/modules/netaclaw/browser-daemon/spike2-ghost-cursor.test.ts`
|
||
|
||
- [ ] **Step 1: 写 spike 测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/spike2-ghost-cursor.test.ts
|
||
import { chromium } from 'patchright';
|
||
import { createCursor } from 'ghost-cursor';
|
||
import * as path from 'node:path';
|
||
import * as fs from 'node:fs';
|
||
|
||
const CHROME = path.resolve(__dirname, '../../../../../../netabrowser-cli/chromium/win64/chrome.exe');
|
||
|
||
describe('Spike #2: ghost-cursor on patchright + neta-chromium', () => {
|
||
jest.setTimeout(60000);
|
||
|
||
it('cursor.click 能在 patchright 启动的 neta-chromium 上工作', async () => {
|
||
if (!fs.existsSync(CHROME)) {
|
||
console.warn('SKIP: neta-chromium not found');
|
||
return;
|
||
}
|
||
const tmpProfile = path.resolve(process.cwd(), '.spike-profile-2');
|
||
const ctx = await chromium.launchPersistentContext(tmpProfile, {
|
||
executablePath: CHROME,
|
||
headless: true,
|
||
args: ['--fingerprint=99999'],
|
||
});
|
||
const page = ctx.pages()[0] || (await ctx.newPage());
|
||
|
||
await page.goto('data:text/html,<button id=b style="position:absolute;top:200px;left:300px">Click me</button><script>document.getElementById("b").addEventListener("click",()=>document.title="CLICKED")</script>');
|
||
|
||
// 创建 ghost cursor
|
||
const cursor = createCursor(page as any);
|
||
|
||
// 拿目标坐标
|
||
const box = await page.locator('#b').boundingBox();
|
||
expect(box).not.toBeNull();
|
||
|
||
// 用 ghost-cursor 移动并点击（贝塞尔轨迹）
|
||
await cursor.moveTo({ x: box!.x + box!.width / 2, y: box!.y + box!.height / 2 });
|
||
await page.mouse.down();
|
||
await page.waitForTimeout(80);
|
||
await page.mouse.up();
|
||
|
||
// 等待 click 生效
|
||
await page.waitForFunction(() => document.title === 'CLICKED', null, { timeout: 5000 });
|
||
expect(await page.title()).toBe('CLICKED');
|
||
|
||
// 验证 navigator.webdriver 仍为 false（patchright 反检测有效）
|
||
const wd = await page.evaluate(() => navigator.webdriver);
|
||
expect(wd).toBe(false);
|
||
|
||
await ctx.close();
|
||
fs.rmSync(tmpProfile, { recursive: true, force: true });
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑 spike**
|
||
|
||
```bash
|
||
pnpm jest test/modules/netaclaw/browser-daemon/spike2-ghost-cursor.test.ts
|
||
```
|
||
预期：PASS（含 navigator.webdriver === false）
|
||
|
||
- [ ] **Step 3: 写决策**
|
||
|
||
如果通过，append `SPIKE_DECISION.md`：
|
||
|
||
```markdown
|
||
|
||
# Spike #2 决策：ghost-cursor 兼容
|
||
|
||
✅ ghost-cursor 在 patchright + neta-chromium 上工作正常。
|
||
- cursor.moveTo 走贝塞尔轨迹，patchright 没拦截 mouse 事件
|
||
- click 后 navigator.webdriver 仍 false（patchright 反检测维持）
|
||
|
||
humanizer.service.ts 直接 `import { createCursor } from 'ghost-cursor'` 即可。
|
||
```
|
||
|
||
如果失败：选用纯自写贝塞尔（替代方案，备选脚本另准备）。
|
||
|
||
- [ ] **Step 4: Checkpoint**
|
||
|
||
`Task 3 完成`：ghost-cursor 兼容性确认，可投入 humanizer 实现。
|
||
|
||
---
|
||
|
||
## Task 4：chromium-launcher（路径解析 + launch args 拼装）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/runtime/chromium-launcher.ts`
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/service/fingerprint.service.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/chromium-launcher.test.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/fingerprint.service.test.ts`
|
||
|
||
- [ ] **Step 1: 写 fingerprint 测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/fingerprint.service.test.ts
|
||
import { FingerprintService } from '../../../../src/modules/netaclaw/browser-daemon/service/fingerprint.service.js';
|
||
|
||
describe('FingerprintService', () => {
|
||
const svc = new FingerprintService();
|
||
|
||
it('fromSeed: 仅 seed 生成完整 args', () => {
|
||
const args = svc.fromSeed(12345);
|
||
expect(args).toEqual(expect.arrayContaining([
|
||
'--fingerprint=12345',
|
||
'--fingerprint-platform=Windows',
|
||
'--fingerprint-platform-version=10.0.0',
|
||
'--fingerprint-brand=Chrome',
|
||
'--fingerprint-hardware-concurrency=8',
|
||
'--fingerprint-language=zh-CN',
|
||
]));
|
||
});
|
||
|
||
it('merge: 指定字段覆盖默认', () => {
|
||
const args = svc.merge({ seed: 1, language: 'en-US', hardwareConcurrency: 16 });
|
||
expect(args).toContain('--fingerprint=1');
|
||
expect(args).toContain('--fingerprint-language=en-US');
|
||
expect(args).toContain('--fingerprint-hardware-concurrency=16');
|
||
});
|
||
|
||
it('seed 不同生成不同 fingerprint arg', () => {
|
||
expect(svc.fromSeed(1)).toContain('--fingerprint=1');
|
||
expect(svc.fromSeed(2)).toContain('--fingerprint=2');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试看失败**
|
||
|
||
```bash
|
||
cd packages/backend && pnpm jest fingerprint.service
|
||
```
|
||
预期：FAIL（service 不存在）
|
||
|
||
- [ ] **Step 3: 实现 FingerprintService**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/service/fingerprint.service.ts
|
||
import { Provide, Scope, ScopeEnum } from '@midwayjs/core';
|
||
|
||
export interface FingerprintParams {
|
||
seed?: number;
|
||
platform?: 'Windows' | 'macOS' | 'Linux';
|
||
platformVersion?: string;
|
||
brand?: string;
|
||
brandVersion?: string;
|
||
hardwareConcurrency?: number;
|
||
language?: string;
|
||
timezone?: string;
|
||
}
|
||
|
||
@Provide()
|
||
@Scope(ScopeEnum.Singleton)
|
||
export class FingerprintService {
|
||
/** 仅 seed → 全套默认 args */
|
||
fromSeed(seed: number): string[] {
|
||
return this.merge({ seed });
|
||
}
|
||
|
||
/** 自定义参数 + 默认值 → args */
|
||
merge(p: FingerprintParams): string[] {
|
||
const args: string[] = [];
|
||
if (p.seed != null) args.push(`--fingerprint=${p.seed}`);
|
||
args.push(`--fingerprint-platform=${p.platform ?? 'Windows'}`);
|
||
args.push(`--fingerprint-platform-version=${p.platformVersion ?? '10.0.0'}`);
|
||
args.push(`--fingerprint-brand=${p.brand ?? 'Chrome'}`);
|
||
if (p.brandVersion) args.push(`--fingerprint-brand-version=${p.brandVersion}`);
|
||
args.push(`--fingerprint-hardware-concurrency=${p.hardwareConcurrency ?? 8}`);
|
||
args.push(`--fingerprint-language=${p.language ?? 'zh-CN'}`);
|
||
if (p.timezone) args.push(`--fingerprint-timezone=${p.timezone}`);
|
||
return args;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest fingerprint.service
|
||
```
|
||
预期：PASS（3 tests）
|
||
|
||
- [ ] **Step 5: 写 chromium-launcher 测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/chromium-launcher.test.ts
|
||
import { resolveChromiumPath, buildLaunchArgs } from '../../../../src/modules/netaclaw/browser-daemon/runtime/chromium-launcher.js';
|
||
import * as path from 'node:path';
|
||
|
||
describe('chromium-launcher', () => {
|
||
describe('resolveChromiumPath', () => {
|
||
afterEach(() => { delete process.env.NETA_CHROMIUM_PATH; });
|
||
|
||
it('优先环境变量', () => {
|
||
process.env.NETA_CHROMIUM_PATH = '/custom/chrome.exe';
|
||
expect(resolveChromiumPath({ isPkg: false })).toBe('/custom/chrome.exe');
|
||
});
|
||
|
||
it('pkg 模式：execPath 同目录 chromium/win64/chrome.exe', () => {
|
||
const result = resolveChromiumPath({ isPkg: true, execPath: 'C:/Program Files/Neta/backend.exe' });
|
||
expect(result).toMatch(/Program Files\/Neta\/chromium\/win64\/chrome\.exe$/);
|
||
});
|
||
|
||
it('dev 模式：monorepo packages/netabrowser-cli/chromium/win64/chrome.exe', () => {
|
||
const result = resolveChromiumPath({ isPkg: false });
|
||
expect(result).toMatch(/netabrowser-cli\/chromium\/win64\/chrome\.exe$/);
|
||
});
|
||
});
|
||
|
||
describe('buildLaunchArgs', () => {
|
||
it('合并指纹 args + 用户自定义 args', () => {
|
||
const args = buildLaunchArgs({
|
||
fingerprintArgs: ['--fingerprint=42', '--fingerprint-language=zh-CN'],
|
||
extraArgs: ['--disable-popup-blocking'],
|
||
});
|
||
expect(args).toEqual(expect.arrayContaining([
|
||
'--fingerprint=42',
|
||
'--fingerprint-language=zh-CN',
|
||
'--disable-popup-blocking',
|
||
]));
|
||
});
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 6: 实现 chromium-launcher**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/runtime/chromium-launcher.ts
|
||
import * as path from 'node:path';
|
||
|
||
export interface ResolveOpts {
|
||
isPkg?: boolean;
|
||
execPath?: string;
|
||
}
|
||
|
||
/** 解析 neta-chromium 可执行文件路径 */
|
||
export function resolveChromiumPath(opts: ResolveOpts = {}): string {
|
||
if (process.env.NETA_CHROMIUM_PATH) return process.env.NETA_CHROMIUM_PATH;
|
||
|
||
const isPkg = opts.isPkg ?? !!(process as any).pkg;
|
||
if (isPkg) {
|
||
const execPath = opts.execPath ?? process.execPath;
|
||
return path.join(path.dirname(execPath), 'chromium', 'win64', 'chrome.exe').replace(/\\/g, '/');
|
||
}
|
||
|
||
// dev 模式：从 backend src 出发，定位 monorepo 内 packages/netabrowser-cli/chromium/win64/chrome.exe
|
||
// 编译后 __dirname = packages/backend/dist/modules/netaclaw/browser-daemon/runtime
|
||
// 路径计算：runtime → browser-daemon → netaclaw → modules → dist → backend → packages → root（7 层 ..）
|
||
// 然后 root/packages/netabrowser-cli/chromium/win64/chrome.exe
|
||
return path.resolve(__dirname, '../../../../../../../packages/netabrowser-cli/chromium/win64/chrome.exe').replace(/\\/g, '/');
|
||
}
|
||
|
||
export interface LaunchArgsOpts {
|
||
fingerprintArgs: string[];
|
||
extraArgs?: string[];
|
||
}
|
||
|
||
export function buildLaunchArgs(opts: LaunchArgsOpts): string[] {
|
||
return [...opts.fingerprintArgs, ...(opts.extraArgs ?? [])];
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 7: 跑 chromium-launcher 测试**
|
||
|
||
```bash
|
||
pnpm jest chromium-launcher
|
||
```
|
||
预期：PASS（4 tests）
|
||
|
||
- [ ] **Step 8: Checkpoint**
|
||
|
||
`Task 4 完成`：路径解析 + 指纹参数生成 + launch args 拼装可用。
|
||
|
||
---
|
||
|
||
## Task 4b：BrowserDataDir 独立解析（**新增 P0 修复**）
|
||
|
||
**问题**：`comm/data-dir.ts:resolveDataDir()` 在 dev 模式 fallback 到 `<cwd>/dist`。把 `browser-profiles/` `states/` 放 dist 下，每次 `pnpm build` 会清空，状态全丢。
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/runtime/browser-data-dir.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/browser-data-dir.test.ts`
|
||
|
||
- [ ] **Step 1: 写测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/browser-data-dir.test.ts
|
||
import { resolveBrowserDataDir, getProfileDir, getStateDir } from '../../../../src/modules/netaclaw/browser-daemon/runtime/browser-data-dir.js';
|
||
import * as path from 'node:path';
|
||
|
||
describe('BrowserDataDir', () => {
|
||
afterEach(() => {
|
||
delete process.env.NETA_BROWSER_DATA_DIR;
|
||
delete process.env.NETA_DATA_DIR;
|
||
});
|
||
|
||
it('优先 NETA_BROWSER_DATA_DIR 环境变量', () => {
|
||
process.env.NETA_BROWSER_DATA_DIR = '/custom/browser';
|
||
expect(resolveBrowserDataDir({ isPkg: false })).toBe('/custom/browser');
|
||
});
|
||
|
||
it('pkg 模式：dataDir/.netabrowser', () => {
|
||
const r = resolveBrowserDataDir({ isPkg: true, execDir: 'C:/Program Files/Neta' });
|
||
expect(r.replace(/\\/g, '/')).toBe('C:/Program Files/Neta/data/.netabrowser');
|
||
});
|
||
|
||
it('dev 模式：monorepo/.netabrowser-data（不复用 dist）', () => {
|
||
const r = resolveBrowserDataDir({ isPkg: false, monorepoRoot: '/repo' });
|
||
expect(r.replace(/\\/g, '/')).toBe('/repo/.netabrowser-data');
|
||
});
|
||
|
||
it('getProfileDir / getStateDir 返回子路径', () => {
|
||
process.env.NETA_BROWSER_DATA_DIR = '/x';
|
||
expect(getProfileDir('s1').replace(/\\/g, '/')).toBe('/x/profiles/s1');
|
||
expect(getStateDir('s1').replace(/\\/g, '/')).toBe('/x/states/s1.json');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 实现**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/runtime/browser-data-dir.ts
|
||
import * as path from 'node:path';
|
||
import { resolveDataDir } from '../../../../comm/data-dir.js';
|
||
|
||
export interface ResolveBrowserDataDirOpts {
|
||
isPkg?: boolean;
|
||
execDir?: string;
|
||
monorepoRoot?: string;
|
||
}
|
||
|
||
/**
|
||
* netabrowser-cli 自己的状态根目录，独立于 backend dist/。
|
||
* - prod: <dataDir>/.netabrowser/
|
||
* - dev: <monorepo-root>/.netabrowser-data/ （不放 dist 下，防 build 清空）
|
||
*/
|
||
export function resolveBrowserDataDir(opts: ResolveBrowserDataDirOpts = {}): string {
|
||
if (process.env.NETA_BROWSER_DATA_DIR) return path.resolve(process.env.NETA_BROWSER_DATA_DIR);
|
||
const isPkg = opts.isPkg ?? !!(process as any).pkg;
|
||
if (isPkg) {
|
||
const dataDir = resolveDataDir({ isPkg: true, execDir: opts.execDir });
|
||
return path.join(dataDir, '.netabrowser');
|
||
}
|
||
// dev: 从 backend 出发上溯到 monorepo root
|
||
const monorepoRoot = opts.monorepoRoot
|
||
?? path.resolve(__dirname, '../../../../../../../');
|
||
return path.join(monorepoRoot, '.netabrowser-data');
|
||
}
|
||
|
||
export function getProfileDir(sessionName: string): string {
|
||
return path.join(resolveBrowserDataDir(), 'profiles', sessionName);
|
||
}
|
||
|
||
export function getStateDir(sessionName: string): string {
|
||
return path.join(resolveBrowserDataDir(), 'states', `${sessionName}.json`);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest browser-data-dir
|
||
```
|
||
预期：PASS（4 tests）
|
||
|
||
- [ ] **Step 4: 修改 Task 7 daemon.service 中的 import**
|
||
|
||
将 daemon.service.ts 的：
|
||
```typescript
|
||
import { resolveDataDir } from '../../../../comm/data-dir.js';
|
||
// ...
|
||
const profileRoot = path.join(resolveDataDir(), 'browser-profiles');
|
||
const profilePath = path.join(profileRoot, opts.profileDir ?? opts.sessionName);
|
||
```
|
||
|
||
改为：
|
||
```typescript
|
||
import { getProfileDir } from '../runtime/browser-data-dir.js';
|
||
// ...
|
||
const profilePath = getProfileDir(opts.profileDir ?? opts.sessionName);
|
||
```
|
||
|
||
同样将 saveState/loadState 用到的状态文件路径改为 `getStateDir(sessionName)`。
|
||
|
||
- [ ] **Step 5: 更新 .gitignore**
|
||
|
||
把 `.netabrowser-data/` 加入 monorepo 根 `.gitignore`：
|
||
|
||
```bash
|
||
echo ".netabrowser-data/" >> C:/Users/lixin/Desktop/RZYX_ZT/Neta-monorepo/.gitignore
|
||
```
|
||
|
||
- [ ] **Step 6: Checkpoint**
|
||
|
||
`Task 4b 完成`：BrowserDataDir 独立，不复用 dist，build 不会清空状态。
|
||
|
||
---
|
||
|
||
## Task 5：SessionRegistry（含串行化锁）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-registry.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/session-registry.test.ts`
|
||
|
||
- [ ] **Step 1: 写测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/session-registry.test.ts
|
||
import { SessionRegistry } from '../../../../src/modules/netaclaw/browser-daemon/runtime/session-registry.js';
|
||
|
||
describe('SessionRegistry', () => {
|
||
let registry: SessionRegistry;
|
||
beforeEach(() => { registry = new SessionRegistry(); });
|
||
|
||
it('register/get/has/list 基础 CRUD', () => {
|
||
const fakeCtx = { id: 'A' } as any;
|
||
registry.register('s1', fakeCtx);
|
||
expect(registry.has('s1')).toBe(true);
|
||
expect(registry.get('s1')).toBe(fakeCtx);
|
||
expect(registry.list()).toEqual([{ sessionName: 's1', context: fakeCtx, lastUsedAt: expect.any(Date) }]);
|
||
registry.unregister('s1');
|
||
expect(registry.has('s1')).toBe(false);
|
||
});
|
||
|
||
it('touch 更新 lastUsedAt', async () => {
|
||
registry.register('s1', { id: 'A' } as any);
|
||
const before = registry.list()[0].lastUsedAt;
|
||
await new Promise(r => setTimeout(r, 10));
|
||
registry.touch('s1');
|
||
const after = registry.list()[0].lastUsedAt;
|
||
expect(after.getTime()).toBeGreaterThan(before.getTime());
|
||
});
|
||
|
||
it('withLock: 同 sessionName 串行化', async () => {
|
||
const order: string[] = [];
|
||
const job = (id: string, ms: number) => async () => {
|
||
order.push(`start-${id}`);
|
||
await new Promise(r => setTimeout(r, ms));
|
||
order.push(`end-${id}`);
|
||
};
|
||
await Promise.all([
|
||
registry.withLock('s1', job('A', 30)),
|
||
registry.withLock('s1', job('B', 5)),
|
||
registry.withLock('s1', job('C', 5)),
|
||
]);
|
||
expect(order).toEqual(['start-A', 'end-A', 'start-B', 'end-B', 'start-C', 'end-C']);
|
||
});
|
||
|
||
it('withLock: 不同 sessionName 并发', async () => {
|
||
const order: string[] = [];
|
||
await Promise.all([
|
||
registry.withLock('s1', async () => { order.push('s1-start'); await new Promise(r => setTimeout(r, 30)); order.push('s1-end'); }),
|
||
registry.withLock('s2', async () => { order.push('s2-start'); await new Promise(r => setTimeout(r, 10)); order.push('s2-end'); }),
|
||
]);
|
||
// s2 应该在 s1 完成前先 end
|
||
expect(order.indexOf('s2-end')).toBeLessThan(order.indexOf('s1-end'));
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试看失败**
|
||
|
||
```bash
|
||
pnpm jest session-registry
|
||
```
|
||
预期：FAIL
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-registry.ts
|
||
import { Provide, Scope, ScopeEnum } from '@midwayjs/core';
|
||
|
||
export interface SessionEntry {
|
||
sessionName: string;
|
||
context: any; // patchright BrowserContext
|
||
lastUsedAt: Date;
|
||
}
|
||
|
||
@Provide()
|
||
@Scope(ScopeEnum.Singleton)
|
||
export class SessionRegistry {
|
||
private entries = new Map<string, SessionEntry>();
|
||
private locks = new Map<string, Promise<void>>();
|
||
|
||
register(sessionName: string, context: any): void {
|
||
this.entries.set(sessionName, { sessionName, context, lastUsedAt: new Date() });
|
||
}
|
||
|
||
unregister(sessionName: string): void {
|
||
this.entries.delete(sessionName);
|
||
}
|
||
|
||
has(sessionName: string): boolean {
|
||
return this.entries.has(sessionName);
|
||
}
|
||
|
||
get(sessionName: string): any | undefined {
|
||
return this.entries.get(sessionName)?.context;
|
||
}
|
||
|
||
touch(sessionName: string): void {
|
||
const e = this.entries.get(sessionName);
|
||
if (e) e.lastUsedAt = new Date();
|
||
}
|
||
|
||
list(): SessionEntry[] {
|
||
return [...this.entries.values()];
|
||
}
|
||
|
||
/** 同 sessionName 操作严格串行化 */
|
||
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);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest session-registry
|
||
```
|
||
预期：PASS（4 tests）
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
`Task 5 完成`：SessionRegistry 含锁机制，并发安全。
|
||
|
||
---
|
||
|
||
## Task 6：SessionScheduler（LRU 软上限 + 队列）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-scheduler.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/session-scheduler.test.ts`
|
||
|
||
- [ ] **Step 1: 写测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/session-scheduler.test.ts
|
||
import { SessionScheduler } from '../../../../src/modules/netaclaw/browser-daemon/runtime/session-scheduler.js';
|
||
|
||
describe('SessionScheduler', () => {
|
||
it('未触达上限直接通过', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 5 });
|
||
sch.recordActivate('s1');
|
||
const slot = await sch.acquireSlot('s2', 'normal', false);
|
||
expect(slot.granted).toBe(true);
|
||
expect(slot.evictedSessionName).toBeUndefined();
|
||
});
|
||
|
||
it('触达上限：LRU 回收最久未用的 idle session', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 2, idleTimeoutMs: 1000 });
|
||
sch.recordActivate('s1');
|
||
await new Promise(r => setTimeout(r, 5));
|
||
sch.recordActivate('s2');
|
||
sch.markIdle('s1');
|
||
sch.markIdle('s2');
|
||
// s1 比 s2 先 idle，所以 s1 是 LRU
|
||
const slot = await sch.acquireSlot('s3', 'normal', false);
|
||
expect(slot.granted).toBe(true);
|
||
expect(slot.evictedSessionName).toBe('s1');
|
||
});
|
||
|
||
it('全部 active 无 idle 可回收：fail-fast 503', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 1 });
|
||
sch.recordActivate('s1');
|
||
const slot = await sch.acquireSlot('s2', 'normal', false);
|
||
expect(slot.granted).toBe(false);
|
||
expect(slot.reason).toBe('NO_IDLE_SESSION_TO_EVICT');
|
||
});
|
||
|
||
it('high 优先级抢占 low 优先级', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 1 });
|
||
sch.recordActivate('s1', 'low');
|
||
const slot = await sch.acquireSlot('s2', 'high', false);
|
||
expect(slot.granted).toBe(true);
|
||
expect(slot.evictedSessionName).toBe('s1');
|
||
});
|
||
|
||
it('queue=true：等待空位（最长 30s）', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 1, queueTimeoutMs: 200 });
|
||
sch.recordActivate('s1');
|
||
const p = sch.acquireSlot('s2', 'normal', true);
|
||
setTimeout(() => sch.markIdle('s1'), 50);
|
||
setTimeout(() => sch.recordDeactivate('s1'), 60);
|
||
const slot = await p;
|
||
expect(slot.granted).toBe(true);
|
||
});
|
||
|
||
it('getStats 返回 active/idle/total', () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 5 });
|
||
sch.recordActivate('s1');
|
||
sch.recordActivate('s2');
|
||
sch.markIdle('s1');
|
||
expect(sch.getStats()).toEqual({
|
||
activeCount: 1,
|
||
idleCount: 1,
|
||
totalCount: 2,
|
||
maxActiveSessions: 5,
|
||
});
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试看失败**
|
||
|
||
```bash
|
||
pnpm jest session-scheduler
|
||
```
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-scheduler.ts
|
||
import { Provide, Scope, ScopeEnum } from '@midwayjs/core';
|
||
|
||
export type Priority = 'low' | 'normal' | 'high';
|
||
const PRIORITY_RANK: Record<Priority, number> = { low: 0, normal: 1, high: 2 };
|
||
|
||
interface SessionState {
|
||
sessionName: string;
|
||
priority: Priority;
|
||
status: 'active' | 'idle';
|
||
activatedAt: Date;
|
||
lastUsedAt: Date;
|
||
}
|
||
|
||
export interface SchedulerOptions {
|
||
maxActiveSessions?: number;
|
||
idleTimeoutMs?: number;
|
||
queueTimeoutMs?: number;
|
||
}
|
||
|
||
export interface AcquireResult {
|
||
granted: boolean;
|
||
reason?: string;
|
||
evictedSessionName?: string;
|
||
}
|
||
|
||
@Provide()
|
||
@Scope(ScopeEnum.Singleton)
|
||
export class SessionScheduler {
|
||
private sessions = new Map<string, SessionState>();
|
||
private waiters: Array<{ resolve: (v: AcquireResult) => void; sessionName: string; priority: Priority; expireAt: number }> = [];
|
||
private maxActiveSessions: number;
|
||
private queueTimeoutMs: number;
|
||
|
||
constructor(opts: SchedulerOptions = {}) {
|
||
this.maxActiveSessions = opts.maxActiveSessions ?? 50;
|
||
this.queueTimeoutMs = opts.queueTimeoutMs ?? 30_000;
|
||
}
|
||
|
||
recordActivate(sessionName: string, priority: Priority = 'normal'): void {
|
||
const now = new Date();
|
||
this.sessions.set(sessionName, { sessionName, priority, status: 'active', activatedAt: now, lastUsedAt: now });
|
||
this.tryProcessWaiters();
|
||
}
|
||
|
||
markIdle(sessionName: string): void {
|
||
const s = this.sessions.get(sessionName);
|
||
if (s) s.status = 'idle';
|
||
this.tryProcessWaiters();
|
||
}
|
||
|
||
recordDeactivate(sessionName: string): void {
|
||
this.sessions.delete(sessionName);
|
||
this.tryProcessWaiters();
|
||
}
|
||
|
||
touch(sessionName: string): void {
|
||
const s = this.sessions.get(sessionName);
|
||
if (s) {
|
||
s.status = 'active';
|
||
s.lastUsedAt = new Date();
|
||
}
|
||
}
|
||
|
||
async acquireSlot(sessionName: string, priority: Priority, queue: boolean): Promise<AcquireResult> {
|
||
const direct = this.tryAcquireImmediate(sessionName, priority);
|
||
if (direct.granted || !queue) return direct;
|
||
if (direct.reason !== 'NO_IDLE_SESSION_TO_EVICT' && direct.reason !== 'AT_CAPACITY') {
|
||
return direct;
|
||
}
|
||
// 排队
|
||
return new Promise<AcquireResult>(resolve => {
|
||
const expireAt = Date.now() + this.queueTimeoutMs;
|
||
const waiter = { resolve, sessionName, priority, expireAt };
|
||
this.waiters.push(waiter);
|
||
const timer = setTimeout(() => {
|
||
const i = this.waiters.indexOf(waiter);
|
||
if (i >= 0) {
|
||
this.waiters.splice(i, 1);
|
||
resolve({ granted: false, reason: 'QUEUE_TIMEOUT' });
|
||
}
|
||
}, this.queueTimeoutMs);
|
||
// resolve 时清除 timer
|
||
const origResolve = waiter.resolve;
|
||
waiter.resolve = (v) => { clearTimeout(timer); origResolve(v); };
|
||
});
|
||
}
|
||
|
||
private tryAcquireImmediate(sessionName: string, priority: Priority): AcquireResult {
|
||
if (this.sessions.has(sessionName)) {
|
||
// 已存在：activate 并返回成功
|
||
this.touch(sessionName);
|
||
return { granted: true };
|
||
}
|
||
const activeCount = [...this.sessions.values()].filter(s => s.status === 'active').length;
|
||
if (activeCount < this.maxActiveSessions) {
|
||
return { granted: true };
|
||
}
|
||
// 触达上限：尝试 LRU 回收 idle
|
||
const idleSessions = [...this.sessions.values()]
|
||
.filter(s => s.status === 'idle')
|
||
.sort((a, b) => a.lastUsedAt.getTime() - b.lastUsedAt.getTime());
|
||
if (idleSessions.length > 0) {
|
||
const evict = idleSessions[0];
|
||
this.sessions.delete(evict.sessionName);
|
||
return { granted: true, evictedSessionName: evict.sessionName };
|
||
}
|
||
// 无 idle，尝试优先级抢占
|
||
const lowerPriority = [...this.sessions.values()]
|
||
.filter(s => PRIORITY_RANK[s.priority] < PRIORITY_RANK[priority])
|
||
.sort((a, b) => a.lastUsedAt.getTime() - b.lastUsedAt.getTime());
|
||
if (lowerPriority.length > 0) {
|
||
const evict = lowerPriority[0];
|
||
this.sessions.delete(evict.sessionName);
|
||
return { granted: true, evictedSessionName: evict.sessionName };
|
||
}
|
||
return { granted: false, reason: 'NO_IDLE_SESSION_TO_EVICT' };
|
||
}
|
||
|
||
private tryProcessWaiters(): void {
|
||
while (this.waiters.length > 0) {
|
||
const w = this.waiters[0];
|
||
if (Date.now() > w.expireAt) {
|
||
this.waiters.shift();
|
||
w.resolve({ granted: false, reason: 'QUEUE_TIMEOUT' });
|
||
continue;
|
||
}
|
||
const r = this.tryAcquireImmediate(w.sessionName, w.priority);
|
||
if (r.granted) {
|
||
this.waiters.shift();
|
||
w.resolve(r);
|
||
} else {
|
||
break;
|
||
}
|
||
}
|
||
}
|
||
|
||
getStats(): { activeCount: number; idleCount: number; totalCount: number; maxActiveSessions: number } {
|
||
const all = [...this.sessions.values()];
|
||
return {
|
||
activeCount: all.filter(s => s.status === 'active').length,
|
||
idleCount: all.filter(s => s.status === 'idle').length,
|
||
totalCount: all.length,
|
||
maxActiveSessions: this.maxActiveSessions,
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest session-scheduler
|
||
```
|
||
预期：PASS（6 tests）
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
`Task 6 完成`：调度器 LRU+优先级+队列+stats 完整。
|
||
|
||
---
|
||
|
||
## Task 7：BrowserDaemonService.open/close 基础生命周期
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/service/daemon.service.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/daemon.service.test.ts`
|
||
|
||
- [ ] **Step 1: 写测试（mock patchright + dependencies）**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/daemon.service.test.ts
|
||
import { BrowserDaemonService } from '../../../../src/modules/netaclaw/browser-daemon/service/daemon.service.js';
|
||
|
||
describe('BrowserDaemonService.open/close', () => {
|
||
let svc: BrowserDaemonService;
|
||
let mockChromium: any;
|
||
let mockContext: any;
|
||
let mockPage: any;
|
||
|
||
beforeEach(() => {
|
||
mockPage = { goto: jest.fn(), close: jest.fn(), url: () => 'about:blank' };
|
||
mockContext = {
|
||
pages: () => [mockPage],
|
||
newPage: jest.fn().mockResolvedValue(mockPage),
|
||
close: jest.fn().mockResolvedValue(undefined),
|
||
storageState: jest.fn().mockResolvedValue({ cookies: [], origins: [] }),
|
||
};
|
||
mockChromium = { launchPersistentContext: jest.fn().mockResolvedValue(mockContext) };
|
||
|
||
svc = new BrowserDaemonService();
|
||
(svc as any).registry = new (require('../../../../src/modules/netaclaw/browser-daemon/runtime/session-registry.js').SessionRegistry)();
|
||
(svc as any).scheduler = new (require('../../../../src/modules/netaclaw/browser-daemon/runtime/session-scheduler.js').SessionScheduler)({ maxActiveSessions: 5 });
|
||
(svc as any).fingerprint = { fromSeed: (s: number) => [`--fingerprint=${s}`] };
|
||
(svc as any).chromium = mockChromium;
|
||
(svc as any).resolveChromiumPath = () => '/fake/chrome.exe';
|
||
(svc as any).logger = { info: jest.fn(), warn: jest.fn(), error: jest.fn() };
|
||
});
|
||
|
||
it('open: 启动 chromium + 注册 session', async () => {
|
||
const r = await svc.open({ sessionName: 's1', url: 'https://example.com', fingerprintSeed: 42 });
|
||
expect(mockChromium.launchPersistentContext).toHaveBeenCalledWith(
|
||
expect.any(String),
|
||
expect.objectContaining({
|
||
executablePath: '/fake/chrome.exe',
|
||
args: expect.arrayContaining(['--fingerprint=42']),
|
||
})
|
||
);
|
||
expect(r.sessionName).toBe('s1');
|
||
expect((svc as any).registry.has('s1')).toBe(true);
|
||
});
|
||
|
||
it('open: sessionName 已存在 → 409', async () => {
|
||
await svc.open({ sessionName: 's1', url: 'https://e.com', fingerprintSeed: 1 });
|
||
await expect(svc.open({ sessionName: 's1', url: 'https://e.com', fingerprintSeed: 1 }))
|
||
.rejects.toThrow(/already exists|conflict/i);
|
||
});
|
||
|
||
it('close: 关闭 context + 注销 session', async () => {
|
||
await svc.open({ sessionName: 's1', url: 'https://e.com', fingerprintSeed: 1 });
|
||
await svc.close('s1');
|
||
expect(mockContext.close).toHaveBeenCalled();
|
||
expect((svc as any).registry.has('s1')).toBe(false);
|
||
});
|
||
|
||
it('list: 返回所有 session 信息', async () => {
|
||
await svc.open({ sessionName: 's1', url: 'https://e.com', fingerprintSeed: 1 });
|
||
const list = svc.list();
|
||
expect(list).toEqual([expect.objectContaining({ sessionName: 's1' })]);
|
||
});
|
||
|
||
it('proxy 配置传给 patchright', async () => {
|
||
await svc.open({
|
||
sessionName: 's1',
|
||
url: 'https://e.com',
|
||
fingerprintSeed: 1,
|
||
proxy: { server: 'http://1.2.3.4:8080', username: 'u', password: 'p' },
|
||
});
|
||
expect(mockChromium.launchPersistentContext).toHaveBeenCalledWith(
|
||
expect.any(String),
|
||
expect.objectContaining({
|
||
proxy: { server: 'http://1.2.3.4:8080', username: 'u', password: 'p' },
|
||
})
|
||
);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试看失败**
|
||
|
||
```bash
|
||
pnpm jest daemon.service
|
||
```
|
||
|
||
- [ ] **Step 3: 实现 daemon.service.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/service/daemon.service.ts
|
||
import { Provide, Scope, ScopeEnum, Inject, Logger, ILogger } from '@midwayjs/core';
|
||
import * as path from 'node:path';
|
||
import * as fs from 'node:fs';
|
||
import { chromium } from 'patchright';
|
||
import { SessionRegistry } from '../runtime/session-registry.js';
|
||
import { SessionScheduler, Priority } from '../runtime/session-scheduler.js';
|
||
import { FingerprintService } from './fingerprint.service.js';
|
||
import { resolveChromiumPath, buildLaunchArgs } from '../runtime/chromium-launcher.js';
|
||
import { getProfileDir } from '../runtime/browser-data-dir.js';
|
||
|
||
export type HumanizeMode = 'full' | 'fast' | 'off';
|
||
|
||
export interface OpenOpts {
|
||
sessionName: string;
|
||
url: string;
|
||
fingerprintSeed?: number;
|
||
proxy?: { server: string; username?: string; password?: string };
|
||
profileDir?: string;
|
||
headed?: boolean;
|
||
priority?: Priority;
|
||
queue?: boolean;
|
||
}
|
||
|
||
export interface SessionInfo {
|
||
sessionName: string;
|
||
url: string;
|
||
pageCount: number;
|
||
status: 'active' | 'idle';
|
||
lastUsedAt: Date;
|
||
}
|
||
|
||
@Provide()
|
||
@Scope(ScopeEnum.Singleton)
|
||
export class BrowserDaemonService {
|
||
@Inject() registry: SessionRegistry;
|
||
@Inject() scheduler: SessionScheduler;
|
||
@Inject() fingerprint: FingerprintService;
|
||
@Logger() logger: ILogger;
|
||
|
||
// 注入点便于测试覆盖
|
||
protected chromium: any = chromium;
|
||
protected resolveChromiumPath = resolveChromiumPath;
|
||
|
||
/**
|
||
* 注：v2 修复 P1-8 后 service 不再维护 modeMap（保持 stateless）。
|
||
* humanize-mode 完全由调用方每次传：
|
||
* - CLI 端：`--mode` 命令级 > `NETA_BROWSER_HUMANIZE_MODE` 环境变量 > 默认 'full'
|
||
* - HTTP/Service 调用方：每次方法调用通过参数传入
|
||
*/
|
||
|
||
async open(opts: OpenOpts): Promise<{ sessionName: string; url: string; pageCount: number }> {
|
||
return this.registry.withLock(opts.sessionName, async () => {
|
||
if (this.registry.has(opts.sessionName)) {
|
||
const err: any = new Error(`Session '${opts.sessionName}' already exists`);
|
||
err.statusCode = 409;
|
||
throw err;
|
||
}
|
||
const slot = await this.scheduler.acquireSlot(
|
||
opts.sessionName,
|
||
opts.priority ?? 'normal',
|
||
opts.queue ?? false,
|
||
);
|
||
if (!slot.granted) {
|
||
const err: any = new Error(`No slot available: ${slot.reason}`);
|
||
err.statusCode = 503;
|
||
err.retryAfter = 30;
|
||
throw err;
|
||
}
|
||
if (slot.evictedSessionName) {
|
||
await this.closeInternal(slot.evictedSessionName);
|
||
}
|
||
|
||
const profilePath = getProfileDir(opts.profileDir ?? opts.sessionName);
|
||
fs.mkdirSync(profilePath, { recursive: true });
|
||
|
||
const fingerprintArgs = this.fingerprint.fromSeed(opts.fingerprintSeed ?? Math.floor(Math.random() * 100000));
|
||
const args = buildLaunchArgs({ fingerprintArgs });
|
||
|
||
this.logger.info(`[browser-daemon] launching ${opts.sessionName} → ${opts.url}`);
|
||
const ctx = await this.chromium.launchPersistentContext(profilePath, {
|
||
executablePath: this.resolveChromiumPath(),
|
||
headless: !opts.headed,
|
||
args,
|
||
proxy: opts.proxy,
|
||
});
|
||
|
||
const page = ctx.pages()[0] ?? (await ctx.newPage());
|
||
await page.goto(opts.url);
|
||
|
||
this.registry.register(opts.sessionName, ctx);
|
||
this.scheduler.recordActivate(opts.sessionName, opts.priority ?? 'normal');
|
||
|
||
return { sessionName: opts.sessionName, url: page.url(), pageCount: ctx.pages().length };
|
||
});
|
||
}
|
||
|
||
async close(sessionName: string): Promise<void> {
|
||
return this.registry.withLock(sessionName, () => this.closeInternal(sessionName));
|
||
}
|
||
|
||
private async closeInternal(sessionName: string): Promise<void> {
|
||
const ctx = this.registry.get(sessionName);
|
||
if (!ctx) return;
|
||
try {
|
||
await ctx.close();
|
||
} catch (e: any) {
|
||
this.logger.warn(`[browser-daemon] close ${sessionName} failed: ${e.message}`);
|
||
}
|
||
this.registry.unregister(sessionName);
|
||
this.scheduler.recordDeactivate(sessionName);
|
||
}
|
||
|
||
list(): SessionInfo[] {
|
||
return this.registry.list().map(e => {
|
||
const ctx = e.context;
|
||
const page = ctx.pages?.()[0];
|
||
return {
|
||
sessionName: e.sessionName,
|
||
url: page?.url?.() ?? '',
|
||
pageCount: ctx.pages?.().length ?? 0,
|
||
status: 'active',
|
||
lastUsedAt: e.lastUsedAt,
|
||
};
|
||
});
|
||
}
|
||
|
||
getStats() {
|
||
return this.scheduler.getStats();
|
||
}
|
||
|
||
getPageOrFail(sessionName: string) {
|
||
const ctx = this.registry.get(sessionName);
|
||
if (!ctx) throw new Error(`Session '${sessionName}' not found`);
|
||
const page = ctx.pages()[0];
|
||
if (!page) throw new Error(`Session '${sessionName}' has no page`);
|
||
this.registry.touch(sessionName);
|
||
this.scheduler.touch(sessionName);
|
||
return { ctx, page };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest daemon.service
|
||
```
|
||
预期：PASS（5 tests）
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
`Task 7 完成`：daemon.service open/close/list 可用，含锁、调度、指纹、launch。
|
||
|
||
---
|
||
|
||
## Task 8：HumanizerService（三档拟人化）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/service/humanizer.service.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/humanizer.service.test.ts`
|
||
|
||
- [ ] **Step 1: 写测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/humanizer.service.test.ts
|
||
import { HumanizerService } from '../../../../src/modules/netaclaw/browser-daemon/service/humanizer.service.js';
|
||
|
||
describe('HumanizerService', () => {
|
||
let svc: HumanizerService;
|
||
let mockPage: any;
|
||
let mockMouse: any;
|
||
let mockCursor: any;
|
||
|
||
beforeEach(() => {
|
||
mockMouse = { down: jest.fn(), up: jest.fn(), move: jest.fn(), wheel: jest.fn() };
|
||
mockPage = { mouse: mockMouse, waitForTimeout: jest.fn() };
|
||
mockCursor = { moveTo: jest.fn().mockResolvedValue(undefined) };
|
||
svc = new HumanizerService();
|
||
(svc as any).createCursor = () => mockCursor;
|
||
(svc as any).rand = (a: number, b: number) => (a + b) / 2; // deterministic
|
||
(svc as any).chance = (_: number) => false; // never trigger random branches
|
||
});
|
||
|
||
it('full 模式: ghost-cursor 移动 + 视觉停顿 + mousedown/up', async () => {
|
||
await svc.click(mockPage, { x: 100, y: 200 }, 'full');
|
||
expect(mockCursor.moveTo).toHaveBeenCalledWith({ x: 100, y: 200 }, expect.any(Object));
|
||
expect(mockMouse.down).toHaveBeenCalled();
|
||
expect(mockMouse.up).toHaveBeenCalled();
|
||
});
|
||
|
||
it('fast 模式: 不走 ghost-cursor，直接 mouse.move + 短延迟', async () => {
|
||
await svc.click(mockPage, { x: 100, y: 200 }, 'fast');
|
||
expect(mockCursor.moveTo).not.toHaveBeenCalled();
|
||
expect(mockMouse.move).toHaveBeenCalledWith(100, 200);
|
||
expect(mockMouse.down).toHaveBeenCalled();
|
||
});
|
||
|
||
it('off 模式: 立即 click，无延迟', async () => {
|
||
(svc as any).rand = jest.fn();
|
||
await svc.click(mockPage, { x: 100, y: 200 }, 'off');
|
||
expect(mockCursor.moveTo).not.toHaveBeenCalled();
|
||
expect(mockMouse.move).toHaveBeenCalledWith(100, 200);
|
||
expect(mockMouse.down).toHaveBeenCalled();
|
||
expect((svc as any).rand).not.toHaveBeenCalled();
|
||
});
|
||
|
||
it('type full: 字符间随机间隔，5% 概率错字（mock 不触发）', async () => {
|
||
const keyboard = { type: jest.fn(), press: jest.fn() };
|
||
mockPage.keyboard = keyboard;
|
||
await svc.type(mockPage, 'hello', 'full');
|
||
// 'hello' 5 个字符 → keyboard.type 应该被调 5 次
|
||
expect(keyboard.type).toHaveBeenCalledTimes(5);
|
||
expect(keyboard.type).toHaveBeenNthCalledWith(1, 'h');
|
||
});
|
||
|
||
it('type off: 直接整体输入', async () => {
|
||
const keyboard = { type: jest.fn() };
|
||
mockPage.keyboard = keyboard;
|
||
await svc.type(mockPage, 'hello', 'off');
|
||
expect(keyboard.type).toHaveBeenCalledWith('hello', undefined);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试看失败**
|
||
|
||
```bash
|
||
pnpm jest humanizer.service
|
||
```
|
||
|
||
- [ ] **Step 3: 实现 humanizer.service.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/service/humanizer.service.ts
|
||
import { Provide, Scope, ScopeEnum } from '@midwayjs/core';
|
||
import { createCursor } from 'ghost-cursor';
|
||
|
||
export type HumanizeMode = 'full' | 'fast' | 'off';
|
||
|
||
@Provide()
|
||
@Scope(ScopeEnum.Singleton)
|
||
export class HumanizerService {
|
||
// 注入点便于测试
|
||
protected createCursor = createCursor;
|
||
protected rand(min: number, max: number): number {
|
||
return min + Math.floor(Math.random() * (max - min));
|
||
}
|
||
protected chance(p: number): boolean {
|
||
return Math.random() < p;
|
||
}
|
||
|
||
async click(page: any, point: { x: number; y: number }, mode: HumanizeMode): Promise<void> {
|
||
if (mode === 'full') {
|
||
// ghost-cursor 是 puppeteer 类型，patchright Page 与之不兼容，需要 as any cast
|
||
const cursor = this.createCursor(page as any);
|
||
await cursor.moveTo(point, { randomizeMoveDelay: true, moveDelay: this.rand(50, 150) });
|
||
await this.sleep(this.rand(100, 300));
|
||
await page.mouse.down();
|
||
await this.sleep(this.rand(50, 150));
|
||
await page.mouse.up();
|
||
if (this.chance(0.2)) {
|
||
await page.mouse.wheel(0, this.rand(2, 10));
|
||
}
|
||
} else if (mode === 'fast') {
|
||
await page.mouse.move(point.x, point.y);
|
||
await this.sleep(this.rand(50, 200));
|
||
await page.mouse.down();
|
||
await this.sleep(this.rand(20, 50));
|
||
await page.mouse.up();
|
||
} else {
|
||
await page.mouse.move(point.x, point.y);
|
||
await page.mouse.down();
|
||
await page.mouse.up();
|
||
}
|
||
}
|
||
|
||
async type(page: any, text: string, mode: HumanizeMode): Promise<void> {
|
||
if (mode === 'off') {
|
||
await page.keyboard.type(text);
|
||
return;
|
||
}
|
||
const minDelay = mode === 'full' ? 80 : 30;
|
||
const maxDelay = mode === 'full' ? 250 : 80;
|
||
for (let i = 0; i < text.length; i++) {
|
||
const ch = text[i];
|
||
// 5% 错字（仅 full 模式）
|
||
if (mode === 'full' && this.chance(0.05)) {
|
||
const wrong = String.fromCharCode(ch.charCodeAt(0) + 1);
|
||
await page.keyboard.type(wrong);
|
||
await this.sleep(this.rand(minDelay, maxDelay));
|
||
await page.keyboard.press('Backspace');
|
||
await this.sleep(this.rand(minDelay, maxDelay));
|
||
}
|
||
await page.keyboard.type(ch);
|
||
await this.sleep(this.rand(minDelay, maxDelay));
|
||
}
|
||
}
|
||
|
||
async hover(page: any, point: { x: number; y: number }, mode: HumanizeMode): Promise<void> {
|
||
if (mode === 'full') {
|
||
const cursor = this.createCursor(page as any);
|
||
await cursor.moveTo(point);
|
||
await this.sleep(this.rand(200, 800));
|
||
} else {
|
||
await page.mouse.move(point.x, point.y);
|
||
if (mode === 'fast') await this.sleep(this.rand(50, 200));
|
||
}
|
||
}
|
||
|
||
async scroll(page: any, deltaY: number, mode: HumanizeMode): Promise<void> {
|
||
if (mode === 'off') {
|
||
await page.mouse.wheel(0, deltaY);
|
||
return;
|
||
}
|
||
const steps = mode === 'full' ? Math.ceil(Math.abs(deltaY) / 50) : Math.ceil(Math.abs(deltaY) / 200);
|
||
const stepSize = deltaY / steps;
|
||
const minD = mode === 'full' ? 50 : 10;
|
||
const maxD = mode === 'full' ? 150 : 30;
|
||
for (let i = 0; i < steps; i++) {
|
||
await page.mouse.wheel(0, stepSize);
|
||
await this.sleep(this.rand(minD, maxD));
|
||
}
|
||
}
|
||
|
||
private sleep(ms: number): Promise<void> {
|
||
return new Promise(r => setTimeout(r, ms));
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest humanizer.service
|
||
```
|
||
预期：PASS（5 tests）
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
`Task 8 完成`：humanizer 三档行为可用且可测。
|
||
|
||
---
|
||
|
||
## Task 9：BrowserDaemonService.click/fill/type/snapshot/cookie/state（业务方法）
|
||
|
||
**Files:**
|
||
- Modify: `packages/backend/src/modules/netaclaw/browser-daemon/service/daemon.service.ts`
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/service/snapshot-ref.service.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/snapshot-ref.test.ts`
|
||
|
||
- [ ] **Step 1: 写 SnapshotRefService 测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/snapshot-ref.test.ts
|
||
import { SnapshotRefService } from '../../../../src/modules/netaclaw/browser-daemon/service/snapshot-ref.service.js';
|
||
|
||
describe('SnapshotRefService', () => {
|
||
let svc: SnapshotRefService;
|
||
let mockPage: any;
|
||
|
||
beforeEach(() => {
|
||
svc = new SnapshotRefService();
|
||
mockPage = {
|
||
evaluate: jest.fn().mockResolvedValue([
|
||
{ ref: 'e1', tag: 'button', text: 'Login' },
|
||
{ ref: 'e2', tag: 'input', text: '' },
|
||
]),
|
||
};
|
||
});
|
||
|
||
it('snapshot 调 page.evaluate 注入 data-ai-ref，返回 refs', async () => {
|
||
const refs = await svc.snapshot('s1', mockPage);
|
||
expect(refs).toEqual([
|
||
{ ref: 'e1', tag: 'button', text: 'Login' },
|
||
{ ref: 'e2', tag: 'input', text: '' },
|
||
]);
|
||
expect(mockPage.evaluate).toHaveBeenCalledTimes(1);
|
||
});
|
||
|
||
it('refToSelector 返回 [data-ai-ref="..."]', () => {
|
||
expect(svc.refToSelector('e15')).toBe('[data-ai-ref="e15"]');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 实现 SnapshotRefService**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/service/snapshot-ref.service.ts
|
||
import { Provide, Scope, ScopeEnum } from '@midwayjs/core';
|
||
|
||
export interface RefEntry {
|
||
ref: string;
|
||
tag: string;
|
||
text: string;
|
||
}
|
||
|
||
@Provide()
|
||
@Scope(ScopeEnum.Singleton)
|
||
export class SnapshotRefService {
|
||
/** 给页面所有可交互元素注入 data-ai-ref，返回 ref 列表 */
|
||
async snapshot(_sessionName: string, page: any): Promise<RefEntry[]> {
|
||
return page.evaluate(() => {
|
||
const interactive = Array.from(document.querySelectorAll(
|
||
'a, button, input, select, textarea, [role="button"], [role="link"], [contenteditable="true"]'
|
||
));
|
||
const out: { ref: string; tag: string; text: string }[] = [];
|
||
interactive.forEach((el, i) => {
|
||
const ref = `e${i + 1}`;
|
||
el.setAttribute('data-ai-ref', ref);
|
||
const tag = el.tagName.toLowerCase();
|
||
let text = (el as HTMLElement).innerText || (el as HTMLInputElement).value || '';
|
||
text = text.trim().slice(0, 80);
|
||
out.push({ ref, tag, text });
|
||
});
|
||
return out;
|
||
});
|
||
}
|
||
|
||
refToSelector(ref: string): string {
|
||
return `[data-ai-ref="${ref}"]`;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 跑 snapshot-ref 测试**
|
||
|
||
```bash
|
||
pnpm jest snapshot-ref
|
||
```
|
||
预期：PASS
|
||
|
||
- [ ] **Step 4: 在 BrowserDaemonService 中加业务方法**
|
||
|
||
在 `daemon.service.ts` 末尾加入（在 `setHumanizeMode` 之后）：
|
||
|
||
```typescript
|
||
// ===== 业务方法（依赖 humanizer + snapshot-ref）=====
|
||
|
||
@Inject() humanizer: HumanizerService;
|
||
@Inject() snapshotRef: SnapshotRefService;
|
||
|
||
async click(sessionName: string, ref: string, mode?: 'full' | 'fast' | 'off'): Promise<void> {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { page } = this.getPageOrFail(sessionName);
|
||
const locator = page.locator(this.snapshotRef.refToSelector(ref));
|
||
const box = await locator.boundingBox();
|
||
if (!box) throw new Error(`Ref '${ref}' not visible`);
|
||
const m = mode ?? this.getHumanizeMode(sessionName);
|
||
await this.humanizer.click(page, { x: box.x + box.width / 2, y: box.y + box.height / 2 }, m);
|
||
});
|
||
}
|
||
|
||
async fill(sessionName: string, ref: string, value: string, mode?: 'full' | 'fast' | 'off'): Promise<void> {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { page } = this.getPageOrFail(sessionName);
|
||
const locator = page.locator(this.snapshotRef.refToSelector(ref));
|
||
const box = await locator.boundingBox();
|
||
if (!box) throw new Error(`Ref '${ref}' not visible`);
|
||
const m = mode ?? this.getHumanizeMode(sessionName);
|
||
await this.humanizer.click(page, { x: box.x + box.width / 2, y: box.y + box.height / 2 }, m);
|
||
await locator.fill('');
|
||
await this.humanizer.type(page, value, m);
|
||
});
|
||
}
|
||
|
||
async type(sessionName: string, text: string, mode?: 'full' | 'fast' | 'off'): Promise<void> {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { page } = this.getPageOrFail(sessionName);
|
||
await this.humanizer.type(page, text, mode ?? this.getHumanizeMode(sessionName));
|
||
});
|
||
}
|
||
|
||
async snapshot(sessionName: string) {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { page } = this.getPageOrFail(sessionName);
|
||
const refs = await this.snapshotRef.snapshot(sessionName, page);
|
||
return { url: page.url(), refs };
|
||
});
|
||
}
|
||
|
||
async getCookies(sessionName: string, domain?: string): Promise<any[]> {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { ctx } = this.getPageOrFail(sessionName);
|
||
const cookies = await ctx.cookies();
|
||
return domain ? cookies.filter((c: any) => c.domain.includes(domain)) : cookies;
|
||
});
|
||
}
|
||
|
||
async saveState(sessionName: string, filePath: string): Promise<void> {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { ctx } = this.getPageOrFail(sessionName);
|
||
await ctx.storageState({ path: filePath });
|
||
});
|
||
}
|
||
|
||
async loadState(sessionName: string, filePath: string): Promise<void> {
|
||
// loadState 需在 launchPersistentContext 时通过 storageState 选项注入
|
||
// 但 patchright launchPersistentContext 不直接接受 storageState
|
||
// → 实际方案：addCookies + 手动 localStorage（基于 file 内容）
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { ctx, page } = this.getPageOrFail(sessionName);
|
||
const fs = await import('node:fs/promises');
|
||
const data = JSON.parse(await fs.readFile(filePath, 'utf8'));
|
||
if (data.cookies) await ctx.addCookies(data.cookies);
|
||
if (data.origins) {
|
||
for (const o of data.origins) {
|
||
await page.goto(o.origin);
|
||
for (const item of o.localStorage ?? []) {
|
||
await page.evaluate(([k, v]: [string, string]) => localStorage.setItem(k, v), [item.name, item.value]);
|
||
}
|
||
}
|
||
}
|
||
});
|
||
}
|
||
|
||
async goto(sessionName: string, url: string): Promise<void> {
|
||
return this.registry.withLock(sessionName, async () => {
|
||
const { page } = this.getPageOrFail(sessionName);
|
||
await page.goto(url);
|
||
});
|
||
}
|
||
```
|
||
|
||
也要在文件顶部加 import：
|
||
|
||
```typescript
|
||
import { HumanizerService } from './humanizer.service.js';
|
||
import { SnapshotRefService } from './snapshot-ref.service.js';
|
||
```
|
||
|
||
- [ ] **Step 5: 写新方法的测试（追加到 daemon.service.test.ts）**
|
||
|
||
```typescript
|
||
// 追加到 daemon.service.test.ts
|
||
describe('BrowserDaemonService 业务方法', () => {
|
||
let svc: BrowserDaemonService;
|
||
let mockCtx: any;
|
||
let mockPage: any;
|
||
let mockHumanizer: any;
|
||
let mockSnapshotRef: any;
|
||
|
||
beforeEach(() => {
|
||
mockPage = {
|
||
url: () => 'https://example.com',
|
||
mouse: { down: jest.fn(), up: jest.fn(), move: jest.fn() },
|
||
keyboard: { type: jest.fn() },
|
||
locator: jest.fn().mockReturnValue({
|
||
boundingBox: jest.fn().mockResolvedValue({ x: 10, y: 20, width: 100, height: 40 }),
|
||
fill: jest.fn(),
|
||
}),
|
||
goto: jest.fn(),
|
||
};
|
||
mockCtx = {
|
||
pages: () => [mockPage],
|
||
cookies: jest.fn().mockResolvedValue([{ name: 'a', value: '1', domain: '.x.com' }]),
|
||
storageState: jest.fn(),
|
||
addCookies: jest.fn(),
|
||
};
|
||
mockHumanizer = { click: jest.fn(), type: jest.fn() };
|
||
mockSnapshotRef = {
|
||
refToSelector: (r: string) => `[data-ai-ref="${r}"]`,
|
||
snapshot: jest.fn().mockResolvedValue([{ ref: 'e1', tag: 'button', text: 'OK' }]),
|
||
};
|
||
svc = new BrowserDaemonService();
|
||
const { SessionRegistry } = require('../../../../src/modules/netaclaw/browser-daemon/runtime/session-registry.js');
|
||
const { SessionScheduler } = require('../../../../src/modules/netaclaw/browser-daemon/runtime/session-scheduler.js');
|
||
(svc as any).registry = new SessionRegistry();
|
||
(svc as any).scheduler = new SessionScheduler({ maxActiveSessions: 5 });
|
||
(svc as any).humanizer = mockHumanizer;
|
||
(svc as any).snapshotRef = mockSnapshotRef;
|
||
(svc as any).logger = { info: jest.fn(), warn: jest.fn(), error: jest.fn() };
|
||
(svc as any).registry.register('s1', mockCtx);
|
||
(svc as any).scheduler.recordActivate('s1');
|
||
});
|
||
|
||
it('click: 调 humanizer.click(中心点, mode)', async () => {
|
||
await svc.click('s1', 'e1');
|
||
expect(mockHumanizer.click).toHaveBeenCalledWith(mockPage, { x: 60, y: 40 }, 'full');
|
||
});
|
||
|
||
it('snapshot: 调 snapshotRef + 返回 url + refs', async () => {
|
||
const r = await svc.snapshot('s1');
|
||
expect(r.url).toBe('https://example.com');
|
||
expect(r.refs).toEqual([{ ref: 'e1', tag: 'button', text: 'OK' }]);
|
||
});
|
||
|
||
it('getCookies: domain 过滤', async () => {
|
||
const r = await svc.getCookies('s1', 'x.com');
|
||
expect(r).toEqual([{ name: 'a', value: '1', domain: '.x.com' }]);
|
||
});
|
||
|
||
it('saveState: 调 storageState({path})', async () => {
|
||
await svc.saveState('s1', '/tmp/s.json');
|
||
expect(mockCtx.storageState).toHaveBeenCalledWith({ path: '/tmp/s.json' });
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 6: 跑所有 daemon 测试**
|
||
|
||
```bash
|
||
pnpm jest daemon.service
|
||
```
|
||
预期：PASS（前 5 tests + 4 新 tests = 9）
|
||
|
||
- [ ] **Step 7: Checkpoint**
|
||
|
||
`Task 9 完成`：BrowserDaemonService 业务方法齐备。
|
||
|
||
---
|
||
|
||
## Task 9b：Cleanup + Lifecycle + Idle-Timeout（**新增 P1 修复**）
|
||
|
||
**问题**：spec §5.4 要求 @Init 扫 known sessions、@Destroy 优雅关闭 + 5s 超时强制 kill；§6.6 要求 60min idle 自动回收。原 plan 未实现。
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/runtime/cleanup.ts`
|
||
- Modify: `packages/backend/src/modules/netaclaw/browser-daemon/service/daemon.service.ts`
|
||
- Modify: `packages/backend/src/modules/netaclaw/browser-daemon/runtime/session-scheduler.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/cleanup.test.ts`
|
||
|
||
- [ ] **Step 1: 实现 cleanup.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/runtime/cleanup.ts
|
||
/**
|
||
* 优雅关闭工具：等待 ctx.close() 最多 5s，超时强制 kill
|
||
*/
|
||
export async function gracefullyClose(ctx: any, timeoutMs = 5000): Promise<void> {
|
||
await Promise.race([
|
||
ctx.close().catch(() => {}),
|
||
new Promise(resolve => setTimeout(resolve, timeoutMs)),
|
||
]);
|
||
// 强制 kill 残留 chrome 进程
|
||
try {
|
||
const browser = ctx.browser?.();
|
||
if (browser?.process) {
|
||
const proc = browser.process();
|
||
if (proc && !proc.killed) proc.kill('SIGKILL');
|
||
}
|
||
} catch {}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: SessionScheduler 增加 idle 计时器**
|
||
|
||
修改 `session-scheduler.ts`，加入：
|
||
|
||
```typescript
|
||
// 在 SessionScheduler 类内
|
||
private idleTimers = new Map<string, NodeJS.Timeout>();
|
||
private idleTimeoutMs: number;
|
||
private onIdleTimeout?: (sessionName: string) => Promise<void>;
|
||
|
||
constructor(opts: SchedulerOptions = {}) {
|
||
this.maxActiveSessions = opts.maxActiveSessions ?? 50;
|
||
this.queueTimeoutMs = opts.queueTimeoutMs ?? 30_000;
|
||
this.idleTimeoutMs = opts.idleTimeoutMs ?? 60 * 60 * 1000; // 60 min
|
||
}
|
||
|
||
setIdleTimeoutHandler(fn: (sessionName: string) => Promise<void>): void {
|
||
this.onIdleTimeout = fn;
|
||
}
|
||
|
||
touch(sessionName: string): void {
|
||
const s = this.sessions.get(sessionName);
|
||
if (s) {
|
||
s.status = 'active';
|
||
s.lastUsedAt = new Date();
|
||
}
|
||
this.resetIdleTimer(sessionName);
|
||
}
|
||
|
||
private resetIdleTimer(sessionName: string): void {
|
||
this.clearIdleTimer(sessionName);
|
||
if (this.idleTimeoutMs <= 0 || !this.onIdleTimeout) return;
|
||
const timer = setTimeout(() => {
|
||
this.idleTimers.delete(sessionName);
|
||
this.onIdleTimeout?.(sessionName).catch(() => {});
|
||
}, this.idleTimeoutMs);
|
||
this.idleTimers.set(sessionName, timer);
|
||
}
|
||
|
||
private clearIdleTimer(sessionName: string): void {
|
||
const t = this.idleTimers.get(sessionName);
|
||
if (t) {
|
||
clearTimeout(t);
|
||
this.idleTimers.delete(sessionName);
|
||
}
|
||
}
|
||
|
||
// 在 recordActivate 末尾调 resetIdleTimer
|
||
// 在 recordDeactivate 调 clearIdleTimer
|
||
```
|
||
|
||
- [ ] **Step 3: daemon.service @Init / @Destroy 钩子**
|
||
|
||
在 `daemon.service.ts` 加：
|
||
|
||
```typescript
|
||
import { Init, Destroy } from '@midwayjs/core';
|
||
import { gracefullyClose } from '../runtime/cleanup.js';
|
||
import { getStateDir } from '../runtime/browser-data-dir.js';
|
||
import * as path from 'node:path';
|
||
import * as fs from 'node:fs';
|
||
|
||
// 在 BrowserDaemonService 类内：
|
||
|
||
@Init()
|
||
async init(): Promise<void> {
|
||
// 注册 idle 回收回调
|
||
this.scheduler.setIdleTimeoutHandler(async (sessionName) => {
|
||
this.logger.info(`[browser-daemon] idle timeout: ${sessionName} → save+close`);
|
||
await this.registry.withLock(sessionName, async () => {
|
||
const ctx = this.registry.get(sessionName);
|
||
if (!ctx) return;
|
||
const stateFile = getStateDir(sessionName);
|
||
try {
|
||
await ctx.storageState({ path: stateFile });
|
||
} catch (e: any) {
|
||
this.logger.warn(`[browser-daemon] saveState on idle failed: ${e.message}`);
|
||
}
|
||
await this.closeInternal(sessionName);
|
||
});
|
||
});
|
||
|
||
// 扫描 known sessions（不主动 launch）
|
||
const stateRoot = path.dirname(getStateDir('placeholder'));
|
||
if (fs.existsSync(stateRoot)) {
|
||
const files = fs.readdirSync(stateRoot).filter(f => f.endsWith('.json'));
|
||
this.logger.info(`[browser-daemon] init: ${files.length} known sessions on disk`);
|
||
}
|
||
}
|
||
|
||
@Destroy()
|
||
async destroy(): Promise<void> {
|
||
this.logger.info('[browser-daemon] destroying, closing all sessions...');
|
||
const all = this.registry.list();
|
||
await Promise.all(all.map(async (e) => {
|
||
try {
|
||
const stateFile = getStateDir(e.sessionName);
|
||
await e.context.storageState({ path: stateFile });
|
||
} catch (err: any) {
|
||
this.logger.warn(`[browser-daemon] saveState ${e.sessionName} failed: ${err.message}`);
|
||
}
|
||
await gracefullyClose(e.context, 5000);
|
||
}));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 写 cleanup 测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/cleanup.test.ts
|
||
import { gracefullyClose } from '../../../../src/modules/netaclaw/browser-daemon/runtime/cleanup.js';
|
||
|
||
describe('cleanup.gracefullyClose', () => {
|
||
it('正常关闭：close 完成', async () => {
|
||
const close = jest.fn().mockResolvedValue(undefined);
|
||
await gracefullyClose({ close }, 1000);
|
||
expect(close).toHaveBeenCalled();
|
||
});
|
||
|
||
it('close 超时：5s 后强制 kill', async () => {
|
||
const kill = jest.fn();
|
||
const ctx = {
|
||
close: () => new Promise(() => {}), // 永远不 resolve
|
||
browser: () => ({ process: () => ({ kill, killed: false }) }),
|
||
};
|
||
const start = Date.now();
|
||
await gracefullyClose(ctx, 100);
|
||
expect(Date.now() - start).toBeGreaterThanOrEqual(100);
|
||
expect(kill).toHaveBeenCalledWith('SIGKILL');
|
||
});
|
||
|
||
it('close 抛错不阻断', async () => {
|
||
await expect(
|
||
gracefullyClose({ close: () => Promise.reject(new Error('boom')) }, 100)
|
||
).resolves.toBeUndefined();
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 5: 跑测试**
|
||
|
||
```bash
|
||
pnpm jest cleanup.test
|
||
```
|
||
预期：PASS（3 tests）
|
||
|
||
- [ ] **Step 6: SessionScheduler idle timer 测试追加**
|
||
|
||
```typescript
|
||
// 追加到 session-scheduler.test.ts
|
||
describe('SessionScheduler idle timer', () => {
|
||
it('idle 超时后调 onIdleTimeout', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 5, idleTimeoutMs: 50 });
|
||
const handler = jest.fn().mockResolvedValue(undefined);
|
||
sch.setIdleTimeoutHandler(handler);
|
||
sch.recordActivate('s1');
|
||
await new Promise(r => setTimeout(r, 100));
|
||
expect(handler).toHaveBeenCalledWith('s1');
|
||
});
|
||
|
||
it('touch 重置计时器', async () => {
|
||
const sch = new SessionScheduler({ maxActiveSessions: 5, idleTimeoutMs: 80 });
|
||
const handler = jest.fn().mockResolvedValue(undefined);
|
||
sch.setIdleTimeoutHandler(handler);
|
||
sch.recordActivate('s1');
|
||
await new Promise(r => setTimeout(r, 50));
|
||
sch.touch('s1');
|
||
await new Promise(r => setTimeout(r, 50));
|
||
// 累积 100ms 但 touch 重置后只过了 50ms，未触发
|
||
expect(handler).not.toHaveBeenCalled();
|
||
await new Promise(r => setTimeout(r, 50));
|
||
expect(handler).toHaveBeenCalledWith('s1');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 7: Checkpoint**
|
||
|
||
`Task 9b 完成`：lifecycle 钩子 + idle 自动回收 + 优雅关闭。验收 9 + 5b 可通过。
|
||
|
||
---
|
||
|
||
## Task 10：control-auth.middleware（loopback + secret）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/middleware/control-auth.middleware.ts`
|
||
- Test: `packages/backend/test/modules/netaclaw/browser-daemon/control-auth.middleware.test.ts`
|
||
|
||
- [ ] **Step 1: 写测试**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/control-auth.middleware.test.ts
|
||
import { BrowserControlAuthMiddleware } from '../../../../src/modules/netaclaw/browser-daemon/middleware/control-auth.middleware.js';
|
||
|
||
describe('BrowserControlAuthMiddleware', () => {
|
||
const mw = new BrowserControlAuthMiddleware();
|
||
const fn = mw.resolve();
|
||
|
||
beforeEach(() => {
|
||
process.env.NETA_TRAY_SECRET = 'test-secret';
|
||
process.env.NODE_ENV = 'test';
|
||
});
|
||
|
||
it('loopback + 正确 secret → 通过', async () => {
|
||
const ctx: any = { ip: '127.0.0.1', headers: { 'x-neta-control-secret': 'test-secret' }, status: 200 };
|
||
const next = jest.fn();
|
||
await fn(ctx, next);
|
||
expect(next).toHaveBeenCalled();
|
||
});
|
||
|
||
it('非 loopback → 403', async () => {
|
||
const ctx: any = { ip: '8.8.8.8', headers: { 'x-neta-control-secret': 'test-secret' }, status: 200 };
|
||
const next = jest.fn();
|
||
await fn(ctx, next);
|
||
expect(ctx.status).toBe(403);
|
||
expect(next).not.toHaveBeenCalled();
|
||
});
|
||
|
||
it('loopback + 错误 secret → 401', async () => {
|
||
const ctx: any = { ip: '127.0.0.1', headers: { 'x-neta-control-secret': 'wrong' }, status: 200 };
|
||
const next = jest.fn();
|
||
await fn(ctx, next);
|
||
expect(ctx.status).toBe(401);
|
||
});
|
||
|
||
it('loopback 无 secret → 401', async () => {
|
||
const ctx: any = { ip: '127.0.0.1', headers: {}, status: 200 };
|
||
const next = jest.fn();
|
||
await fn(ctx, next);
|
||
expect(ctx.status).toBe(401);
|
||
});
|
||
|
||
it('dev 模式 + secret 未配置 → 旁路通过（loopback 仍校验）', async () => {
|
||
process.env.NETA_TRAY_SECRET = '';
|
||
process.env.NODE_ENV = 'development';
|
||
const ctx: any = { ip: '127.0.0.1', headers: {}, status: 200 };
|
||
const next = jest.fn();
|
||
await fn(ctx, next);
|
||
expect(next).toHaveBeenCalled();
|
||
});
|
||
|
||
it('dev 模式 + secret 未配置 + 非 loopback → 仍 403', async () => {
|
||
process.env.NETA_TRAY_SECRET = '';
|
||
process.env.NODE_ENV = 'development';
|
||
const ctx: any = { ip: '8.8.8.8', headers: {}, status: 200 };
|
||
const next = jest.fn();
|
||
await fn(ctx, next);
|
||
expect(ctx.status).toBe(403);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试看失败**
|
||
|
||
```bash
|
||
pnpm jest control-auth.middleware
|
||
```
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/middleware/control-auth.middleware.ts
|
||
import { IMiddleware, Middleware } from '@midwayjs/core';
|
||
import { NextFunction, Context } from '@midwayjs/koa';
|
||
import { isLoopbackAddress, validateRuntimeSecret } from '../../../../comm/runtime-secret.js';
|
||
|
||
@Middleware()
|
||
export class BrowserControlAuthMiddleware implements IMiddleware<Context, NextFunction> {
|
||
resolve() {
|
||
return async (ctx: Context, next: NextFunction) => {
|
||
const ip = ctx.ip || (ctx as any).request?.ip || (ctx as any).req?.socket?.remoteAddress;
|
||
if (!isLoopbackAddress(ip)) {
|
||
ctx.status = 403;
|
||
ctx.body = { code: 1003, error: 'Forbidden: only loopback access allowed' };
|
||
return;
|
||
}
|
||
const expected = process.env.NETA_TRAY_SECRET ?? '';
|
||
const actual = ctx.headers['x-neta-control-secret'] as string | undefined;
|
||
const isDev = process.env.NODE_ENV !== 'production';
|
||
// dev 旁路：secret 未配置时仅信任 loopback
|
||
if (isDev && !expected) {
|
||
await next();
|
||
return;
|
||
}
|
||
if (!validateRuntimeSecret(expected, actual)) {
|
||
ctx.status = 401;
|
||
ctx.body = { code: 1001, error: 'Unauthorized: invalid x-neta-control-secret' };
|
||
return;
|
||
}
|
||
await next();
|
||
};
|
||
}
|
||
|
||
match(ctx: Context): boolean {
|
||
return ctx.path?.startsWith('/admin/browser-daemon/');
|
||
}
|
||
|
||
static getName(): string {
|
||
return 'browserControlAuth';
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试看通过**
|
||
|
||
```bash
|
||
pnpm jest control-auth.middleware
|
||
```
|
||
预期：PASS（6 tests）
|
||
|
||
- [ ] **Step 5: 在 netaclaw/config.ts 注册中间件（重要：模块挂载明确）**
|
||
|
||
修改 `packages/backend/src/modules/netaclaw/config.ts`，把空的 `middlewares: []` 改为：
|
||
|
||
```typescript
|
||
import { ModuleConfig } from '@cool-midway/core';
|
||
import { BrowserControlAuthMiddleware } from './browser-daemon/middleware/control-auth.middleware.js';
|
||
|
||
export default () => {
|
||
return {
|
||
name: 'NetaClaw',
|
||
description: 'NetaClaw 电商浏览器自动化 Agent 引擎',
|
||
middlewares: [BrowserControlAuthMiddleware],
|
||
globalMiddlewares: [],
|
||
order: 0,
|
||
} as ModuleConfig;
|
||
};
|
||
```
|
||
|
||
> 关键：browser-daemon **不是独立模块**，是 netaclaw 的子目录。中间件挂载到 netaclaw 模块，靠 `match()` 限制只在 `/admin/browser-daemon/*` 路径生效。其他 netaclaw 路由（`/admin/netaclaw/*`）不受影响。
|
||
|
||
注意保留 NetaClawConfig / defaultNetaClawConfig 等导出（在 `// ---` 分隔符之后的部分）。
|
||
|
||
- [ ] **Step 6: Checkpoint**
|
||
|
||
`Task 10 完成`：auth middleware 校验 loopback + secret，含 dev 旁路；middleware 已挂载到 netaclaw 模块。
|
||
|
||
---
|
||
|
||
## Task 11：HTTP Controllers（5 个 controller）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/session.ts`
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/interaction.ts`
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/navigation.ts`
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/state.ts`
|
||
- Create: `packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/inspect.ts`
|
||
|
||
> 这 5 个 controller 都是 thin wrapper：解析 body → 调 service → 返回结果。**严格按 Neta 现有 controller 风格**：
|
||
> - `@Provide()` + `@Controller('/admin/browser-daemon')` 类装饰器声明路径前缀
|
||
> - 方法用相对路径 `@Post('/open')` `@Get('/list')`
|
||
> - 直接返回 `{ code: 1000, data: ... }`，不继承 `BaseController`，不用 `this.ok()`，不用 `@CoolController` 不用 `@CoolTag`
|
||
> - 参考 `packages/backend/src/modules/netaclaw/controller/admin/agent_channel.ts` 实际风格
|
||
|
||
- [ ] **Step 1: 实现 session.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/session.ts
|
||
import { Provide, Inject, Controller, Post, Get, Body } from '@midwayjs/core';
|
||
import { Context } from '@midwayjs/koa';
|
||
import { BrowserDaemonService } from '../../service/daemon.service.js';
|
||
|
||
@Provide()
|
||
@Controller('/admin/browser-daemon')
|
||
export class AdminBrowserDaemonSessionController {
|
||
@Inject() daemonService: BrowserDaemonService;
|
||
@Inject() ctx: Context;
|
||
|
||
@Post('/open')
|
||
async open(@Body() dto: any) {
|
||
try {
|
||
const r = await this.daemonService.open(dto);
|
||
return { code: 1000, data: r };
|
||
} catch (e: any) {
|
||
this.ctx.status = e.statusCode ?? 400;
|
||
return { code: 1002, error: e.message, retryAfter: e.retryAfter };
|
||
}
|
||
}
|
||
|
||
@Post('/close')
|
||
async close(@Body('sessionName') sessionName: string) {
|
||
await this.daemonService.close(sessionName);
|
||
return { code: 1000, data: { ok: true } };
|
||
}
|
||
|
||
@Get('/list')
|
||
async list() {
|
||
return { code: 1000, data: this.daemonService.list() };
|
||
}
|
||
|
||
@Get('/stats')
|
||
async stats() {
|
||
return { code: 1000, data: this.daemonService.getStats() };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 实现 interaction.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/interaction.ts
|
||
import { Provide, Inject, Controller, Post, Body } from '@midwayjs/core';
|
||
import { BrowserDaemonService } from '../../service/daemon.service.js';
|
||
|
||
@Provide()
|
||
@Controller('/admin/browser-daemon')
|
||
export class AdminBrowserDaemonInteractionController {
|
||
@Inject() daemonService: BrowserDaemonService;
|
||
|
||
@Post('/click')
|
||
async click(@Body() dto: { sessionName: string; ref: string; mode?: 'full' | 'fast' | 'off' }) {
|
||
await this.daemonService.click(dto.sessionName, dto.ref, dto.mode ?? 'full');
|
||
return { code: 1000, data: { clicked: dto.ref } };
|
||
}
|
||
|
||
@Post('/fill')
|
||
async fill(@Body() dto: { sessionName: string; ref: string; value: string; mode?: 'full' | 'fast' | 'off' }) {
|
||
await this.daemonService.fill(dto.sessionName, dto.ref, dto.value, dto.mode ?? 'full');
|
||
return { code: 1000, data: { filled: dto.ref } };
|
||
}
|
||
|
||
@Post('/type')
|
||
async type(@Body() dto: { sessionName: string; text: string; mode?: 'full' | 'fast' | 'off' }) {
|
||
await this.daemonService.type(dto.sessionName, dto.text, dto.mode ?? 'full');
|
||
return { code: 1000, data: { typed: dto.text.length } };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 实现 navigation.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/navigation.ts
|
||
import { Provide, Inject, Controller, Post, Body } from '@midwayjs/core';
|
||
import { BrowserDaemonService } from '../../service/daemon.service.js';
|
||
|
||
@Provide()
|
||
@Controller('/admin/browser-daemon')
|
||
export class AdminBrowserDaemonNavigationController {
|
||
@Inject() daemonService: BrowserDaemonService;
|
||
|
||
@Post('/goto')
|
||
async goto(@Body() dto: { sessionName: string; url: string }) {
|
||
await this.daemonService.goto(dto.sessionName, dto.url);
|
||
return { code: 1000, data: { navigated: dto.url } };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 实现 state.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/state.ts
|
||
import { Provide, Inject, Controller, Post, Body } from '@midwayjs/core';
|
||
import { BrowserDaemonService } from '../../service/daemon.service.js';
|
||
|
||
@Provide()
|
||
@Controller('/admin/browser-daemon')
|
||
export class AdminBrowserDaemonStateController {
|
||
@Inject() daemonService: BrowserDaemonService;
|
||
|
||
@Post('/cookie-list')
|
||
async cookieList(@Body() dto: { sessionName: string; domain?: string }) {
|
||
return { code: 1000, data: await this.daemonService.getCookies(dto.sessionName, dto.domain) };
|
||
}
|
||
|
||
@Post('/state-save')
|
||
async stateSave(@Body() dto: { sessionName: string; filePath: string }) {
|
||
await this.daemonService.saveState(dto.sessionName, dto.filePath);
|
||
return { code: 1000, data: { saved: dto.filePath } };
|
||
}
|
||
|
||
@Post('/state-load')
|
||
async stateLoad(@Body() dto: { sessionName: string; filePath: string }) {
|
||
await this.daemonService.loadState(dto.sessionName, dto.filePath);
|
||
return { code: 1000, data: { loaded: dto.filePath } };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 实现 inspect.ts**
|
||
|
||
```typescript
|
||
// packages/backend/src/modules/netaclaw/browser-daemon/controller/admin/inspect.ts
|
||
import { Provide, Inject, Controller, Post, Body } from '@midwayjs/core';
|
||
import { BrowserDaemonService } from '../../service/daemon.service.js';
|
||
|
||
@Provide()
|
||
@Controller('/admin/browser-daemon')
|
||
export class AdminBrowserDaemonInspectController {
|
||
@Inject() daemonService: BrowserDaemonService;
|
||
|
||
@Post('/snapshot')
|
||
async snapshot(@Body() dto: { sessionName: string }) {
|
||
return { code: 1000, data: await this.daemonService.snapshot(dto.sessionName) };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 6: 启动 backend 验证路由**
|
||
|
||
dev 模式启动（dev 旁路时无需 secret）：
|
||
|
||
```bash
|
||
cd packages/backend
|
||
NODE_ENV=development pnpm dev
|
||
```
|
||
|
||
另一终端：
|
||
```bash
|
||
# dev 旁路（middleware 已实现）：仅 loopback 即可，secret 未设也能调
|
||
curl -X GET http://localhost:8003/admin/browser-daemon/list
|
||
```
|
||
预期：200 + `{"code":1000,"data":[]}`
|
||
|
||
- [ ] **Step 7: Checkpoint**
|
||
|
||
`Task 11 完成`：5 个 controller 上线，HTTP API 可达。
|
||
|
||
---
|
||
|
||
## Task 12：Contract Test（HTTP ↔ service 等价性）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/test/modules/netaclaw/browser-daemon/contract.test.ts`
|
||
|
||
- [ ] **Step 1: 写 contract test**
|
||
|
||
```typescript
|
||
// packages/backend/test/modules/netaclaw/browser-daemon/contract.test.ts
|
||
import { createApp, close } from '@midwayjs/mock';
|
||
import { Framework } from '@midwayjs/koa';
|
||
|
||
describe('BrowserDaemon HTTP ↔ Service 契约', () => {
|
||
let app: any;
|
||
beforeAll(async () => {
|
||
process.env.NETA_TRAY_SECRET = 'ct-secret';
|
||
app = await createApp(undefined, undefined, Framework);
|
||
});
|
||
afterAll(async () => { if (app) await close(app); });
|
||
|
||
/** Mock daemonService，验证 controller 调它的方法名/参数与 HTTP 1:1 */
|
||
const cases = [
|
||
{ http: { method: 'POST', path: '/admin/browser-daemon/close', body: { sessionName: 's1' } }, service: 'close', args: ['s1'] },
|
||
{ http: { method: 'POST', path: '/admin/browser-daemon/click', body: { sessionName: 's1', ref: 'e1', mode: 'full' } }, service: 'click', args: ['s1', 'e1', 'full'] },
|
||
{ http: { method: 'POST', path: '/admin/browser-daemon/fill', body: { sessionName: 's1', ref: 'e1', value: 'abc' } }, service: 'fill', args: ['s1', 'e1', 'abc', undefined] },
|
||
{ http: { method: 'POST', path: '/admin/browser-daemon/cookie-list', body: { sessionName: 's1', domain: 'x.com' } }, service: 'getCookies', args: ['s1', 'x.com'] },
|
||
{ http: { method: 'POST', path: '/admin/browser-daemon/snapshot', body: { sessionName: 's1' } }, service: 'snapshot', args: ['s1'] },
|
||
];
|
||
|
||
for (const c of cases) {
|
||
it(`HTTP ${c.http.method} ${c.http.path} → service.${c.service}(${c.args.join(',')})`, async () => {
|
||
const fakeService = {
|
||
[c.service]: jest.fn().mockResolvedValue(undefined),
|
||
};
|
||
// 替换 daemonService 实例
|
||
const container = (app as any).getApplicationContext();
|
||
container.registerObject('browserDaemonService', fakeService);
|
||
// 调 HTTP
|
||
const supertest = require('supertest');
|
||
const res = await supertest(app.getServer())[c.http.method.toLowerCase()](c.http.path)
|
||
.set('x-neta-control-secret', 'ct-secret')
|
||
.send(c.http.body);
|
||
expect(res.status).toBe(200);
|
||
expect(fakeService[c.service]).toHaveBeenCalledWith(...c.args);
|
||
});
|
||
}
|
||
});
|
||
```
|
||
|
||
> 注：实施时依据 Midway test 实际 API 调整 `registerObject` / `supertest` 接入；目的是验证 HTTP 与 service 一一对应。
|
||
|
||
- [ ] **Step 2: 跑 contract test**
|
||
|
||
```bash
|
||
pnpm jest contract.test
|
||
```
|
||
预期：PASS（5 cases）
|
||
|
||
- [ ] **Step 3: Checkpoint**
|
||
|
||
`Task 12 完成`：HTTP 与 service 等价性有 contract test 兜底。
|
||
|
||
---
|
||
|
||
## Task 13-18：netabrowser-cli 包实现（合并描述）
|
||
|
||
> 这 6 个 task 是 CLI 包内部各文件，模式相似（接受参数 → 调 HTTP → 输出）。每个文件按下面同一套结构实现，不再展开每 step。
|
||
|
||
### Task 13：bin/main.ts（commander 解析 + 命令分发）
|
||
|
||
**Files:**
|
||
- Create: `packages/netabrowser-cli/src/bin/main.ts`
|
||
|
||
- [ ] **Step 1: 实现**
|
||
|
||
```typescript
|
||
#!/usr/bin/env node
|
||
// packages/netabrowser-cli/src/bin/main.ts
|
||
import { Command } from 'commander';
|
||
import { registerSessionCommands } from '../commands/session.js';
|
||
import { registerInteractionCommands } from '../commands/interaction.js';
|
||
import { registerNavigationCommands } from '../commands/navigation.js';
|
||
import { registerStateCommands } from '../commands/state.js';
|
||
import { registerInspectCommands } from '../commands/inspect.js';
|
||
|
||
const program = new Command();
|
||
program
|
||
.name('netabrowser-cli')
|
||
.description('Neta 反风控+拟人化浏览器 CLI')
|
||
.version('0.1.0');
|
||
|
||
registerSessionCommands(program);
|
||
registerInteractionCommands(program);
|
||
registerNavigationCommands(program);
|
||
registerStateCommands(program);
|
||
registerInspectCommands(program);
|
||
|
||
program.parseAsync(process.argv).catch(e => {
|
||
console.error('Error:', e.message);
|
||
process.exit(1);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Checkpoint**
|
||
|
||
### Task 14：client/runtime-info + http-client
|
||
|
||
**Files:**
|
||
- Create: `packages/netabrowser-cli/src/client/runtime-info.ts`
|
||
- Create: `packages/netabrowser-cli/src/client/http-client.ts`
|
||
|
||
- [ ] **Step 1: runtime-info.ts**
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/client/runtime-info.ts
|
||
import * as fs from 'node:fs';
|
||
import * as path from 'node:path';
|
||
import * as os from 'node:os';
|
||
|
||
export interface RuntimeInfoLite {
|
||
port: number;
|
||
controlSecret: string;
|
||
controlBaseUrl: string;
|
||
}
|
||
|
||
/**
|
||
* v2 修复 P1-6：CLI 启动时 cwd 不一定 = backend cwd。
|
||
* runtime-info.json 真实写入 packages/backend/dist/runtime-info.json。
|
||
* 优先级：环境变量 > pkg 同目录 > monorepo backend dist > user home。
|
||
*/
|
||
export function readRuntimeInfo(): RuntimeInfoLite {
|
||
if (process.env.NETA_RUNTIME_INFO) {
|
||
return JSON.parse(fs.readFileSync(process.env.NETA_RUNTIME_INFO, 'utf8'));
|
||
}
|
||
const candidates = [
|
||
// pkg 模式：netabrowser-cli.exe 同目录 data/runtime-info.json
|
||
path.join(path.dirname(process.execPath), 'data', 'runtime-info.json'),
|
||
// dev 模式：从 cli 编译产物上溯找 monorepo，再进 backend dist
|
||
// __dirname = <root>/packages/netabrowser-cli/dist/client
|
||
// 上溯 4 层到 monorepo root，再进 packages/backend/dist
|
||
path.resolve(__dirname, '../../../../../packages/backend/dist/runtime-info.json'),
|
||
// 兜底：用户主目录
|
||
path.join(os.homedir(), '.neta', 'runtime-info.json'),
|
||
];
|
||
for (const p of candidates) {
|
||
if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8'));
|
||
}
|
||
throw new Error(
|
||
`runtime-info.json not found. Set NETA_RUNTIME_INFO env var or run backend first.\nTried:\n${candidates.map(c => ' - ' + c).join('\n')}`
|
||
);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: http-client.ts**
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/client/http-client.ts
|
||
import axios, { AxiosInstance } from 'axios';
|
||
import { readRuntimeInfo } from './runtime-info.js';
|
||
|
||
let client: AxiosInstance | null = null;
|
||
|
||
export function getHttpClient(): AxiosInstance {
|
||
if (client) return client;
|
||
const info = readRuntimeInfo();
|
||
client = axios.create({
|
||
baseURL: info.controlBaseUrl ?? `http://127.0.0.1:${info.port}`,
|
||
headers: { 'x-neta-control-secret': info.controlSecret },
|
||
timeout: 60_000,
|
||
});
|
||
return client;
|
||
}
|
||
|
||
export async function callDaemon<T = any>(path: string, body?: any): Promise<T> {
|
||
const c = getHttpClient();
|
||
const res = await c.post(path, body ?? {});
|
||
if (res.data?.code !== 1000) {
|
||
throw new Error(`Daemon error: ${res.data?.message ?? 'unknown'}`);
|
||
}
|
||
return res.data.data as T;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Checkpoint**
|
||
|
||
### Task 15：commands/session.ts（open/close/list）
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/commands/session.ts
|
||
import { Command } from 'commander';
|
||
import { callDaemon } from '../client/http-client.js';
|
||
import { formatOutput } from '../output/formatter.js';
|
||
|
||
export function registerSessionCommands(program: Command) {
|
||
program
|
||
.command('open <url>')
|
||
.description('启动会话并打开 URL')
|
||
.requiredOption('--session <name>', 'session 名称')
|
||
.option('--proxy <url>', '代理 URL（http://user:pass@host:port）')
|
||
.option('--fingerprint-seed <n>', '指纹 seed', parseInt)
|
||
.option('--profile-dir <name>', 'profile 目录名')
|
||
.option('--headed', '有头模式')
|
||
.option('--humanize-mode <mode>', 'full|fast|off', 'full')
|
||
.option('--priority <p>', 'low|normal|high', 'normal')
|
||
.option('--queue', '排队等位')
|
||
.option('--raw', '输出 raw JSON')
|
||
.action(async (url, opts) => {
|
||
const dto: any = {
|
||
sessionName: opts.session,
|
||
url,
|
||
humanizeMode: opts.humanizeMode,
|
||
priority: opts.priority,
|
||
queue: !!opts.queue,
|
||
headed: !!opts.headed,
|
||
};
|
||
if (opts.fingerprintSeed != null) dto.fingerprintSeed = opts.fingerprintSeed;
|
||
if (opts.profileDir) dto.profileDir = opts.profileDir;
|
||
if (opts.proxy) dto.proxy = parseProxyUrl(opts.proxy);
|
||
const r = await callDaemon('/admin/browser-daemon/open', dto);
|
||
console.log(formatOutput(r, opts.raw));
|
||
});
|
||
|
||
program
|
||
.command('close')
|
||
.requiredOption('--session <name>')
|
||
.option('--raw')
|
||
.action(async (opts) => {
|
||
await callDaemon('/admin/browser-daemon/close', { sessionName: opts.session });
|
||
console.log(formatOutput({ ok: true }, opts.raw));
|
||
});
|
||
|
||
program
|
||
.command('list')
|
||
.description('列出所有会话')
|
||
.option('--raw')
|
||
.action(async (opts) => {
|
||
const r = await callDaemon('/admin/browser-daemon/list');
|
||
console.log(formatOutput(r, opts.raw));
|
||
});
|
||
}
|
||
|
||
function parseProxyUrl(url: string) {
|
||
const u = new URL(url);
|
||
return {
|
||
server: `${u.protocol}//${u.host}`,
|
||
username: decodeURIComponent(u.username) || undefined,
|
||
password: decodeURIComponent(u.password) || undefined,
|
||
};
|
||
}
|
||
```
|
||
|
||
- [ ] **Checkpoint**
|
||
|
||
### Task 16：commands/interaction.ts
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/commands/interaction.ts
|
||
import { Command } from 'commander';
|
||
import { callDaemon } from '../client/http-client.js';
|
||
import { formatOutput } from '../output/formatter.js';
|
||
|
||
export function registerInteractionCommands(program: Command) {
|
||
program
|
||
.command('click <ref>')
|
||
.requiredOption('--session <name>')
|
||
.option('--mode <mode>', 'full|fast|off')
|
||
.option('--raw')
|
||
.action(async (ref, opts) => {
|
||
// v2 修复 P1-8：CLI 端 mode 优先级 = 命令级 --mode > NETA_BROWSER_HUMANIZE_MODE 环境变量 > 默认 full
|
||
const mode = opts.mode ?? process.env.NETA_BROWSER_HUMANIZE_MODE ?? 'full';
|
||
await callDaemon('/admin/browser-daemon/click', { sessionName: opts.session, ref, mode });
|
||
console.log(formatOutput({ clicked: ref }, opts.raw));
|
||
});
|
||
|
||
program
|
||
.command('fill <ref> <value>')
|
||
.requiredOption('--session <name>')
|
||
.option('--mode <mode>')
|
||
.option('--raw')
|
||
.action(async (ref, value, opts) => {
|
||
const mode = opts.mode ?? process.env.NETA_BROWSER_HUMANIZE_MODE ?? 'full';
|
||
await callDaemon('/admin/browser-daemon/fill', { sessionName: opts.session, ref, value, mode });
|
||
console.log(formatOutput({ filled: ref }, opts.raw));
|
||
});
|
||
|
||
program
|
||
.command('type <text>')
|
||
.requiredOption('--session <name>')
|
||
.option('--mode <mode>')
|
||
.option('--raw')
|
||
.action(async (text, opts) => {
|
||
const mode = opts.mode ?? process.env.NETA_BROWSER_HUMANIZE_MODE ?? 'full';
|
||
await callDaemon('/admin/browser-daemon/type', { sessionName: opts.session, text, mode });
|
||
console.log(formatOutput({ typed: text.length }, opts.raw));
|
||
});
|
||
}
|
||
```
|
||
|
||
- [ ] **Checkpoint**
|
||
|
||
### Task 17：commands/navigation + state + inspect
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/commands/navigation.ts
|
||
import { Command } from 'commander';
|
||
import { callDaemon } from '../client/http-client.js';
|
||
import { formatOutput } from '../output/formatter.js';
|
||
|
||
export function registerNavigationCommands(program: Command) {
|
||
program
|
||
.command('goto <url>')
|
||
.requiredOption('--session <name>')
|
||
.option('--raw')
|
||
.action(async (url, opts) => {
|
||
await callDaemon('/admin/browser-daemon/goto', { sessionName: opts.session, url });
|
||
console.log(formatOutput({ navigated: url }, opts.raw));
|
||
});
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/commands/state.ts
|
||
import { Command } from 'commander';
|
||
import { callDaemon } from '../client/http-client.js';
|
||
import { formatOutput } from '../output/formatter.js';
|
||
|
||
export function registerStateCommands(program: Command) {
|
||
program
|
||
.command('cookie-list')
|
||
.requiredOption('--session <name>')
|
||
.option('--domain <d>')
|
||
.option('--raw')
|
||
.action(async (opts) => {
|
||
const r = await callDaemon('/admin/browser-daemon/cookie-list', { sessionName: opts.session, domain: opts.domain });
|
||
console.log(formatOutput(r, opts.raw));
|
||
});
|
||
|
||
program
|
||
.command('state-save')
|
||
.requiredOption('--session <name>')
|
||
.requiredOption('--output <path>')
|
||
.option('--raw')
|
||
.action(async (opts) => {
|
||
await callDaemon('/admin/browser-daemon/state-save', { sessionName: opts.session, filePath: opts.output });
|
||
console.log(formatOutput({ saved: opts.output }, opts.raw));
|
||
});
|
||
|
||
program
|
||
.command('state-load')
|
||
.requiredOption('--session <name>')
|
||
.requiredOption('--input <path>')
|
||
.option('--raw')
|
||
.action(async (opts) => {
|
||
await callDaemon('/admin/browser-daemon/state-load', { sessionName: opts.session, filePath: opts.input });
|
||
console.log(formatOutput({ loaded: opts.input }, opts.raw));
|
||
});
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/commands/inspect.ts
|
||
import { Command } from 'commander';
|
||
import { callDaemon } from '../client/http-client.js';
|
||
import { formatOutput } from '../output/formatter.js';
|
||
|
||
export function registerInspectCommands(program: Command) {
|
||
program
|
||
.command('snapshot')
|
||
.requiredOption('--session <name>')
|
||
.option('--raw')
|
||
.action(async (opts) => {
|
||
const r = await callDaemon('/admin/browser-daemon/snapshot', { sessionName: opts.session });
|
||
console.log(formatOutput(r, opts.raw));
|
||
});
|
||
}
|
||
```
|
||
|
||
- [ ] **Checkpoint**
|
||
|
||
### Task 18：output/formatter.ts
|
||
|
||
```typescript
|
||
// packages/netabrowser-cli/src/output/formatter.ts
|
||
export function formatOutput(data: any, raw?: boolean): string {
|
||
if (raw) return JSON.stringify(data);
|
||
if (Array.isArray(data) && data.length > 0 && data[0]?.ref) {
|
||
// snapshot 友好输出
|
||
return data.map((r: any) => `[${r.ref}] ${r.tag}: ${r.text}`).join('\n');
|
||
}
|
||
return JSON.stringify(data, null, 2);
|
||
}
|
||
```
|
||
|
||
写最小测试：
|
||
```typescript
|
||
// packages/netabrowser-cli/tests/output-formatter.test.ts
|
||
import { formatOutput } from '../src/output/formatter.js';
|
||
|
||
describe('formatter', () => {
|
||
it('--raw → 单行 JSON', () => {
|
||
expect(formatOutput({ a: 1 }, true)).toBe('{"a":1}');
|
||
});
|
||
it('snapshot refs → 友好输出', () => {
|
||
const r = formatOutput([{ ref: 'e1', tag: 'button', text: 'OK' }]);
|
||
expect(r).toContain('[e1] button: OK');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step：Checkpoint**
|
||
|
||
---
|
||
|
||
## Task 19：SKILL.md（NetaClaw Agent skill 元数据）
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/skills/netabrowser-cli/SKILL.md`
|
||
|
||
```markdown
|
||
---
|
||
name: netabrowser-cli
|
||
description: Neta 反风控+拟人化浏览器自动化 CLI。养号、电商自动化、AI 探索复杂网页时使用。比 playwright-cli 更难被反风控识别（fingerprint-chromium 内核 + patchright 反自动化 + ghost-cursor 拟人化轨迹）。100 账号矩阵养号场景首选。
|
||
allowed-tools: Bash(netabrowser-cli:*) Bash(npx:*)
|
||
---
|
||
|
||
# Browser Automation with netabrowser-cli
|
||
|
||
## When to use vs playwright-cli vs patchwright-cli
|
||
|
||
- **netabrowser-cli**：国内反风控严的站（小红书/抖音/淘宝/拼多多/微博）+ 多账号矩阵 + 养号场景
|
||
- **patchwright-cli**：国外 Cloudflare/DataDome 等反爬保护的站
|
||
- **playwright-cli**：测试、无反风控的站
|
||
|
||
If targeting Chinese social/e-commerce sites or running multi-account automation, **prefer netabrowser-cli**.
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
# 启动会话（每会话独立指纹+独立 IP）
|
||
netabrowser-cli open https://www.xiaohongshu.com \
|
||
--session=acc1 \
|
||
--proxy=http://user:pass@host:port \
|
||
--fingerprint-seed=12345 \
|
||
--headed
|
||
|
||
# 拿当前页面可交互元素
|
||
netabrowser-cli snapshot --session=acc1
|
||
# 输出：[e1] button: 登录 / [e2] input: 手机号 / ...
|
||
|
||
# 拟人化点击 + 输入（默认 humanize-mode=full）
|
||
netabrowser-cli click e1 --session=acc1
|
||
netabrowser-cli fill e2 13800001234 --session=acc1
|
||
|
||
# 抓 cookie
|
||
netabrowser-cli cookie-list --session=acc1 --domain=xiaohongshu.com
|
||
|
||
# 保存登录态
|
||
netabrowser-cli state-save --session=acc1 --output=/path/to/state.json
|
||
|
||
# 关闭
|
||
netabrowser-cli close --session=acc1
|
||
```
|
||
|
||
## Commands
|
||
|
||
### Session 管理
|
||
- `open <url>` 启动会话
|
||
- `close` 关闭
|
||
- `list` 列出所有 session
|
||
|
||
### 交互（默认拟人化 full）
|
||
- `click <ref>` 点击 ref 元素（贝塞尔轨迹+视觉停顿+mousedown/up）
|
||
- `fill <ref> <value>` focus + 拟人化输入
|
||
- `type <text>` 在已 focused 输入框打字
|
||
- `--mode=fast` 单命令切批量模式（200-500ms 延迟，无轨迹）
|
||
- `--mode=off` 测试用，立即执行
|
||
|
||
### 导航
|
||
- `goto <url>` 跳转
|
||
|
||
### 状态
|
||
- `cookie-list [--domain=x]`
|
||
- `state-save --output=path` 保存完整登录态（cookie+localStorage）
|
||
- `state-load --input=path` 恢复
|
||
|
||
### 检查
|
||
- `snapshot` 拿可交互元素 ref 列表
|
||
|
||
## 参数规则
|
||
|
||
### 指纹
|
||
- `--fingerprint-seed=N` 单一 seed 派生所有指纹维度（推荐）
|
||
- 不同 seed → 不同 canvas/webgl/UA fingerprint，同 seed → 完全可复现
|
||
|
||
### 代理
|
||
- `--proxy=http://user:pass@host:port` 单参数最方便
|
||
- 出口 IP 实测 = 代理 IP（patchright `launchPersistentContext` 验证通过）
|
||
|
||
### 拟人化档位
|
||
| `--humanize-mode` | 单命令开销 | 适用 |
|
||
|---|---|---|
|
||
| full（默认） | 2-5s | 养号、敏感操作、AI 探索 |
|
||
| fast | 0.3-0.7s | 批量发布、批量评论 |
|
||
| off | <100ms | 测试、CI |
|
||
|
||
### 调度
|
||
- `--priority=low\|normal\|high` 优先级
|
||
- `--queue` 触达上限时排队（最长 30s）
|
||
|
||
## 性能特征（重要）
|
||
|
||
养号场景每号约 30 操作 × 5s ≈ 2.5min。100 号串行 ≈ 4 小时。批量发布请用 `--humanize-mode=fast`。
|
||
|
||
## 详细文档
|
||
|
||
- [拟人化档位详解](references/humanization.md)
|
||
- [指纹参数](references/fingerprint.md)
|
||
- [代理配置](references/proxy.md)
|
||
- [典型场景示例](references/examples.md)
|
||
```
|
||
|
||
- [ ] **Step：Checkpoint**
|
||
|
||
## Task 20：references/ 子文档
|
||
|
||
> 创建 4 个 reference 文件作为 SKILL.md 的扩展。每个文件 50-100 行，按 SKILL.md 中链接对应的主题展开。
|
||
|
||
**Files:**
|
||
- Create: `packages/backend/skills/netabrowser-cli/references/humanization.md`
|
||
- Create: `packages/backend/skills/netabrowser-cli/references/fingerprint.md`
|
||
- Create: `packages/backend/skills/netabrowser-cli/references/proxy.md`
|
||
- Create: `packages/backend/skills/netabrowser-cli/references/examples.md`
|
||
|
||
每个文件简明阐述对应主题，含示例命令。具体内容由实施者从 spec §6.1-6.6 + 实测脚本提炼。
|
||
|
||
- [ ] **Step：Checkpoint**
|
||
|
||
---
|
||
|
||
## Task 21：Windows 打包集成
|
||
|
||
**Files:**
|
||
- Modify: `packages/backend/scripts/pkg-build.js`
|
||
- Modify: `packages/backend/scripts/build-windows-installer.js`
|
||
- Modify: `packages/backend/installer/setup.iss`
|
||
|
||
- [ ] **Step 1: pkg-build.js 增加 netabrowser-cli 编译**
|
||
|
||
读 `pkg-build.js` 现有逻辑，在 backend.exe 编译之后增加：
|
||
|
||
```javascript
|
||
// 编译 netabrowser-cli
|
||
console.log('Building netabrowser-cli...');
|
||
const cliRoot = path.resolve(__dirname, '../../netabrowser-cli');
|
||
execSync('pnpm build', { cwd: cliRoot, stdio: 'inherit' });
|
||
|
||
// pkg 打包
|
||
const pkgConfig = {
|
||
name: 'netabrowser-cli',
|
||
bin: path.join(cliRoot, 'dist', 'bin', 'main.js'),
|
||
targets: ['node22-win-x64'],
|
||
outputPath: path.join(__dirname, '../installer/dist/netabrowser-cli.exe'),
|
||
};
|
||
await pkg(pkgConfig);
|
||
```
|
||
|
||
- [ ] **Step 2: setup.iss 增加 [Files] 段**
|
||
|
||
在现有 `[Files]` 后追加：
|
||
|
||
```iss
|
||
Source: "dist/netabrowser-cli.exe"; DestDir: "{app}"; Flags: ignoreversion
|
||
Source: "..\..\netabrowser-cli\chromium\win64\*"; DestDir: "{app}\chromium\win64"; Flags: ignoreversion recursesubdirs createallsubdirs
|
||
Source: "..\..\backend\skills\netabrowser-cli\*"; DestDir: "{app}\skills\netabrowser-cli"; Flags: ignoreversion recursesubdirs createallsubdirs
|
||
```
|
||
|
||
- [ ] **Step 3: build-windows-installer.js 加 chromium 复制步骤**
|
||
|
||
在调 ISCC 之前确保 `chromium/win64` 存在。
|
||
|
||
- [ ] **Step 4: 实跑一次安装包构建（dev 机器）**
|
||
|
||
```bash
|
||
cd packages/backend
|
||
pnpm run build:windows-installer
|
||
```
|
||
|
||
预期：生成的 setup.exe 大小 ~250-400MB。装到测试 Windows，能找到 `C:\Program Files\Neta\netabrowser-cli.exe` 和 `chromium/win64/chrome.exe`。
|
||
|
||
- [ ] **Step 5: Checkpoint**
|
||
|
||
---
|
||
|
||
## Task 22：联调与冒烟（手工验收）
|
||
|
||
按 spec §9 验收清单逐条跑：
|
||
|
||
- [ ] **Step 1: 跑所有单测**
|
||
|
||
```bash
|
||
cd packages/backend
|
||
pnpm jest test/modules/netaclaw/browser-daemon/
|
||
```
|
||
预期：全 PASS
|
||
|
||
- [ ] **Step 2: 启动 backend dev 模式**
|
||
|
||
```bash
|
||
NODE_ENV=development pnpm dev
|
||
```
|
||
预期：runtime-info.json 写入 `packages/backend/dist/runtime-info.json` 含 controlSecret（dev 模式下 secret 可能为空字符串，middleware 已开 dev 旁路）
|
||
|
||
> v2 注：dev 模式下 NETA_TRAY_SECRET 通常未设。middleware 已实现 dev 旁路：`NODE_ENV !== 'production' && expected === ''` → 仅校验 loopback、跳过 secret 校验。
|
||
|
||
- [ ] **Step 3: cli list 应返回空**
|
||
|
||
```bash
|
||
node packages/netabrowser-cli/dist/bin/main.js list --raw
|
||
```
|
||
预期：`[]`
|
||
|
||
- [ ] **Step 4: 真代理出口 IP 验证**
|
||
|
||
```bash
|
||
node packages/netabrowser-cli/dist/bin/main.js open https://httpbin.org/ip \
|
||
--session=test \
|
||
--proxy="http://e50b26:7ecdccfd@210.51.27.112:10000" \
|
||
--headed
|
||
```
|
||
然后：
|
||
```bash
|
||
node packages/netabrowser-cli/dist/bin/main.js snapshot --session=test
|
||
```
|
||
看 url + 内容含 `"origin": "210.51.27.112"`
|
||
|
||
- [ ] **Step 5: creepjs 反检测 trust score**
|
||
|
||
打开 https://abrahamjuliot.github.io/creepjs/，肉眼记 trust score。预期 ≥ 70%。
|
||
|
||
- [ ] **Step 6: 拟人化档位延迟测量**
|
||
|
||
```bash
|
||
time node packages/netabrowser-cli/dist/bin/main.js click e1 --session=test --mode=full
|
||
time node packages/netabrowser-cli/dist/bin/main.js click e1 --session=test --mode=fast
|
||
time node packages/netabrowser-cli/dist/bin/main.js click e1 --session=test --mode=off
|
||
```
|
||
预期：full ~2-5s, fast ~0.3-0.7s, off <0.2s
|
||
|
||
- [ ] **Step 7: HTTP 直接调，验证 auth**
|
||
|
||
**dev 旁路验证**：
|
||
```bash
|
||
# dev 模式（NODE_ENV=development，NETA_TRAY_SECRET 未设）
|
||
curl http://localhost:8003/admin/browser-daemon/list
|
||
# 200（dev 旁路允许 loopback）
|
||
|
||
# 非 loopback 仍 403
|
||
curl --interface 8.8.8.8 http://localhost:8003/admin/browser-daemon/list
|
||
# 403
|
||
```
|
||
|
||
**prod 风格验证**：
|
||
```bash
|
||
# 杀掉 backend，重新启动 prod 模式
|
||
NODE_ENV=production NETA_TRAY_SECRET=test-prod-secret pnpm start
|
||
|
||
# 无 secret → 401
|
||
curl http://localhost:8003/admin/browser-daemon/list
|
||
# 401
|
||
|
||
# 错误 secret → 401
|
||
curl http://localhost:8003/admin/browser-daemon/list -H "x-neta-control-secret: wrong"
|
||
# 401
|
||
|
||
# 正确 secret → 200
|
||
curl http://localhost:8003/admin/browser-daemon/list -H "x-neta-control-secret: test-prod-secret"
|
||
# 200
|
||
```
|
||
|
||
- [ ] **Step 8: 软上限验证**
|
||
|
||
设 `maxActiveSessions=2`，启动 3 个 session 看第 3 个返回 503。
|
||
|
||
- [ ] **Step 9: backend 重启 ref 失效**
|
||
|
||
ctrl+C 关 backend，重启 `pnpm dev`，调 `click e1 --session=test`。
|
||
预期：报错（session 不存在或 ref 失效），需要先 `open` 再 `snapshot` 再 `click`。
|
||
|
||
- [ ] **Step 10: 安装包冒烟**
|
||
|
||
把 setup.exe 装到全新 Windows，启动托盘 → 后端启动 → cli 跑 step 4-5。
|
||
|
||
- [ ] **Step 11: Checkpoint**
|
||
|
||
`Task 22 完成`：所有验收标准通过。
|
||
|
||
---
|
||
|
||
## Task 23：文档更新 + 路线图
|
||
|
||
**Files:**
|
||
- Modify: `docs/superpowers/specs/2026-05-04-netabrowser-cli-s1-design.md`（变更日志）
|
||
- Modify: `docs/superpowers/specs/2026-05-03-geo-master-roadmap.md`（如存在则更新）
|
||
|
||
- [ ] **Step 1: 更新 spec §13 变更日志**
|
||
|
||
加一行："2026-XX-XX 实施完成，所有验收标准通过，准备进入 S2"。
|
||
|
||
- [ ] **Step 2: 更新 geo 路线图**
|
||
|
||
如有 geo master-roadmap，标注 netabrowser-cli S1 完成 → 解锁 geo BrowserAutomationService 迁移。
|
||
|
||
- [ ] **Step 3: 提示 user 走完整 git commit**
|
||
|
||
```bash
|
||
cd C:/Users/lixin/Desktop/RZYX_ZT/Neta-monorepo
|
||
git status
|
||
# 用户审核后统一 commit（如其要求）
|
||
```
|
||
|
||
- [ ] **Step 4: Checkpoint**
|
||
|
||
`Task 23 完成`：文档同步。等待 user 触发统一 commit。
|
||
|
||
---
|
||
|
||
## 实施期间约束
|
||
|
||
- ❌ 不写 SQL 文件（如果有数据库需求，用 mcp mysql 工具直接 INSERT）
|
||
- ❌ 每个 task **不单独 git commit**（用户要求全部完成 + 联调通过后统一提交）
|
||
- ❌ 不修改现有 playwright-cli / patchwright-cli skill
|
||
- ❌ 不在 controller 中加业务逻辑（只能是 thin wrapper，§5.3.1 强制）
|
||
- ❌ HTTP API 必须强制 loopback + secret，不能例外
|
||
- ❌ 不实现平台特定补丁（小红书/抖音/淘宝等）→ S2
|
||
|
||
---
|
||
|
||
## 实施完成后
|
||
|
||
- 调用 `superpowers:verification-before-completion` 逐条核对验收标准
|
||
- 调用 `superpowers:requesting-code-review` 触发代码审查
|
||
- 用户测试通过后统一 git commit
|
||
- 更新 spec §13 变更日志
|
||
- 进入下一个子项目：geo BrowserAutomationService 迁移到 BrowserDaemonService（S2）
|