npm - @web-auto/webauto - Versions diffs - 0.1.1 → 0.1.3 - Mend

@web-auto/webauto 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (354) hide show

package/docs/arch/PORTS.md DELETED Viewed

@@ -1,40 +0,0 @@
-# 端口约定与环境变量
-## 统一端口（新架构）
-| 端口 | 服务 | 用途 | 实现文件 |
-|------|------|------|----------|
-| 7701 | Unified API | HTTP + WebSocket + Bus | services/unified-api/index.ts |
-| 7704 | Browser Service | 浏览器会话管理 | modules/camo-backend/src/index.ts |
-| 7790 | SearchGate | 搜索节流服务（每 key 60s 最多 2 次） | scripts/search-gate-server.mjs |
-## 环境变量
-### 浮窗相关
-- `WEBAUTO_FLOATING_WS_URL`：WebSocket 端点（默认：ws://127.0.0.1:7701/ws）
-- `WEBAUTO_FLOATING_BUS_PORT`：Bus 端口（默认：7701，连接到 /bus）
-- `WEBAUTO_FLOATING_HEADLESS`：浮窗是否无头（默认：0，显示窗口）
-### 启动参数
-- `--profile <name>`：Profile 名称（默认：xiaohongshu-batch-1）
-- `--url <url>`：目标 URL（默认：https://www.xiaohongshu.com）
-- `--headless`：无头模式（仅用于调试，无可见窗口）
-### 搜索节流
-- `WEBAUTO_SEARCH_GATE_PORT`：SearchGate 监听端口（默认：7790）；
-- `WEBAUTO_SEARCH_GATE_URL`：Workflow 侧调用 SearchGate `/permit` 的完整 URL（默认：`http://127.0.0.1:7790/permit`）。
-### 移除的端口
-以下端口已合并到 7701，不再使用：
-- 8970（Controller）
-- 8790（Bus Bridge）
-- 8765（独立 WebSocket）
-## 启动流程
-1. 清理 7701/7704 端口
-2. 启动 Unified API（7701）
-3. 启动 Browser Service（7704）
-4. 创建浏览器会话 + 注入 Cookie
-5. 启动浮窗（连接 7701/ws 和 7701/bus）
-6. 验证容器匹配（通过 7701/ws）

package/docs/arch/REGRESSION_CHECKLIST.md DELETED Viewed

@@ -1,121 +0,0 @@
-# 回归验证检查清单（Regression Checklist）
-> 定义“什么是验证完成”：每次代码改动后必须提供的证据条目，避免模糊的“测试通过”。
-## 适用场景
-- 所有 Phase 脚本改动（1-4）
-- 核心服务改动（Unified API/Browser Service/SearchGate）
-- Workflow/Block 改动（影响采集/评论/落盘）
-- UI/Desktop Console 改动（影响编排/参数生成）
----
-## 必需证据（每个改动）
-### 1. 服务健康检查
-```bash
-# Unified API
-curl -s http://127.0.0.1:7701/health | jq .
-# Browser Service
-curl -s http://127.0.0.1:7704/health | jq .
-# SearchGate（可选，仅搜索相关改动）
-curl -s http://127.0.0.1:7790/health | jq .
-```
-**要求**：每个服务返回 `ok: true`（或明确期望的错误码），并附上终端输出截图或复制文本。
----
-### 2. 脚本运行证据
-- **runId**：从 `[Logger] runId=...` 提取
-- **日志路径**：
-  - `~/.webauto/download/xiaohongshu/<env>/<keyword>/run.log`
-  - `~/.webauto/download/xiaohongshu/<env>/<keyword>/run-events.jsonl`
-- **命令**：完整执行的命令（例如：`node scripts/xiaohongshu/phase2-collect.mjs --keyword 深圳黄金 --target 20 --env debug`）
-- **输出摘要**：
-  - 最终状态（成功/失败）
-  - 关键指标（采集数量/耗时）
-  - 错误信息（如果有）
-**示例**：
-```bash
-node scripts/xiaohongshu/phase2-collect.mjs --profile xiaohongshu_batch-2 --keyword "深圳黄金" --target 20 --env debug
-# 输出:
-# [Logger] runId=20260203-114619-scoxyx
-# ✅ 20/20
-# ⏱️  总耗时: 8m56s
-# 📁 保存路径: /Users/fanzhang/.webauto/download/xiaohongshu/debug/深圳黄金/phase2-links.jsonl
-```
----
-### 3. 失败时的证据（如果脚本失败）
-- **WS DOM 快照**：使用 `ws://127.0.0.1:7701/ws` 执行 `browser:execute` 获取 `document.body.innerHTML` 或容器匹配状态
-- **高亮/锚点**：使用 `container:operation highlight` 在页面上高亮失败元素，并截图
-- **错误日志**：从 `run.log` 提取最后 20 行
-**示例命令**：
-```bash
-# 获取当前页 DOM 摘要（Unified API / WS）
-node scripts/xiaohongshu/tests/ws-dom-dump.mjs --profile <profile>
-# 高亮指定容器
-node scripts/container-op.mjs <profile> <containerId> highlight
-```
-**规则**：
-- 脚本失败时 **必须** 先跑 `ws-dom-dump.mjs` 留证再重试。
-- DOM 快照必须写入 bd 任务评论（避免只在聊天里）。
-- 禁止使用 Chrome MCP；只允许 Unified API/容器系统。
----
-### 4. 落盘验证（如果涉及写盘）
-- **文件存在性**：`ls -l ~/.webauto/download/xiaohongshu/<env>/<keyword>/`
-- **内容抽样**：`head -n 3 phase2-links.jsonl | jq .`
-- **去重验证**：两次运行后确认目录未重复创建
----
-## 模板：提交 bd 任务时必须包含的字段
-```markdown
-### 改动描述
-<一句话说明改了什么>
-### 服务健康
-- [ ] Unified API: （粘贴 curl 7701/health 输出）
-- [ ] Browser Service: （粘贴 curl 7704/health 输出）
-- [ ] SearchGate: （如适用）
-### 脚本运行
-- **命令**: <完整命令>
-- **runId**: <从日志提取>
-- **结果**: <成功/失败 + 关键指标>
-- **日志路径**: `~/.webauto/download/.../run.log`
-### 失败证据（如有）
-- **DOM 快照**: （粘贴 ws-dom-dump 输出）
-- **高亮截图**: （附图或说明高亮的 containerId）
-- **错误日志**: （run.log 最后 20 行）
-### 落盘验证（如涉及）
-- [ ] 文件路径: <ls -l 输出>
-- [ ] 内容抽样: <head -n 3 | jq . 输出>
-- [ ] 去重验证: <说明>
-```
----
-## 引用
-- 本文档在 `AGENTS.md` 中索引为“回归验证规范”
-- bd Epic `webauto-0r2` 的子任务 `webauto-jqm` 负责维护此清单

package/docs/arch/SEARCH_GATE.md DELETED Viewed

@@ -1,224 +0,0 @@
-# SearchGate 搜索节流器
-## 背景
-小红书（以及其他平台）对频繁搜索行为高度敏感，直接拼接 URL 或短时间内多次搜索会触发风控验证码。
-为确保：
-1. **所有搜索必须走"对话框搜索"流程**（模拟人工输入 + 回车）
-2. **不频繁搜索**（速率控制）
-引入 **SearchGate** 后台节流服务。
----
-## 核心原则（硬性规则）
-1. **所有平台的搜索 Block 必须先向 SearchGate 申请许可**（通过 `WaitSearchPermitBlock`）
-2. **只有拿到许可后才能执行搜索**（否则阻塞或等待）
-3. **禁止直跳搜索 URL**，所有搜索必须在页面内通过对话框触发
-4. **Phase1 启动后自动拉起 SearchGate**（常驻后台）
----
-## 架构
-```
-┌──────────────────┐
-│   Phase1 启动    │
-│ (session+login)  │
-└────────┬─────────┘
-         │
-         ├─ spawn detached
-         ├─ start-headful.mjs
-         └─ search-gate-server.mjs ──┐
-                                     │
-                                     ▼
-                            ┌────────────────┐
-                            │  SearchGate    │
-                            │  (HTTP 7790)   │
-                            │                │
-                            │ - POST /permit │
-                            │ - GET /status  │
-                            │ - GET /health  │
-                            └────────────────┘
-                                     ▲
-                                     │
-         ┌───────────────────────────┴──────────────────┐
-         │                                              │
-┌────────┴─────────┐                      ┌─────────────┴─────────┐
-│ WaitSearchPermit │                      │   GoToSearchBlock     │
-│     Block        │  ──(允许后执行)──→   │  (对话框搜索)         │
-└──────────────────┘                      └───────────────────────┘
-```
----
-## 接口
-### HTTP 端口：7790
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| `POST` | `/permit` | 申请搜索许可<br/>Body: `{ key, windowMs?, maxCount? }`<br/>Response: `{ ok, allowed, waitMs, countInWindow }` |
-| `GET` | `/health` | 健康检查 |
-| `GET` | `/stats` | 统计信息（队列/窗口） |
-| `POST` | `/shutdown` | 优雅退出 |
-### 速率策略
-- **默认限制**：同一 key（通常是 `profileId`）在 60s 内最多 2 次搜索
-- **超限行为**：返回 `allowed: false` + `waitMs`（需等待的毫秒数）
-- **窗口滑动**：每次许可授予后记录时间戳，自动清理过期记录
----
-## 启动方式
-### 方式1：独立启动（调试）
-```bash
-node scripts/search-gate-server.mjs
-```
-### 方式2：CLI（推荐）
-```bash
-# 启动
-node scripts/search-gate-cli.mjs start
-# 停止
-node scripts/search-gate-cli.mjs stop
-# 重启
-node scripts/search-gate-cli.mjs restart
-# 状态
-node scripts/search-gate-cli.mjs status
-```
-### 方式3：Phase1 自动启动（生产）
-```bash
-node scripts/xiaohongshu/tests/phase1-session-login-with-gate.mjs
-```
-登录成功后自动拉起 SearchGate（detached 模式）。
----
-## Workflow 集成
-### 1. 定义中添加 WaitSearchPermitBlock
-参考 `modules/workflow/definitions/xiaohongshu-collect-workflow-v2.ts`：
-```ts
-{
-  blockName: 'WaitSearchPermitBlock',
-  input: {
-    sessionId: '$sessionId'
-  }
-},
-{
-  blockName: 'GoToSearchBlock',
-  input: {
-    sessionId: '$sessionId',
-    keyword: '$keyword'
-  }
-}
-```
-### 2. 注册 Block
-参考 `scripts/run-xiaohongshu-workflow-v2.ts`：
-```ts
-import * as WaitSearchPermitBlock from '../modules/workflow/blocks/WaitSearchPermitBlock';
-executor.registerBlock('WaitSearchPermitBlock', { execute: WaitSearchPermitBlock.execute });
-```
-### 3. WaitSearchPermitBlock 内部逻辑
-- 向 `http://127.0.0.1:7790/permit` POST 请求
-- 如果 `allowed: true`，立即返回
-- 如果 `allowed: false`，等待 `waitMs` 后重试
-- 最多等待 `maxWaitMs`（默认 5 分钟）后失败
-### 4. GoToSearchBlock 内部已集成
-`modules/workflow/blocks/GoToSearchBlock.ts` 内部已包含对 SearchGate 的调用（位于 `execute` 函数开头），但推荐在 Workflow 定义中显式添加 `WaitSearchPermitBlock` 步骤，逻辑更清晰。
----
-## 测试
-### 1. 健康检查
-```bash
-curl http://127.0.0.1:7790/health
-```
-### 2. 申请许可
-```bash
-curl -X POST http://127.0.0.1:7790/permit \
-  -H "Content-Type: application/json" \
-  -d '{"key":"xiaohongshu_fresh"}'
-```
-### 3. 验证速率限制
-```bash
-node scripts/xiaohongshu/tests/test-search-gate.mjs
-```
-预期：
-- 前 2 次请求立即授权
-- 第 3 次请求被限流，需等待 ~60s
----
-## 日志
-SearchGate 会实时打印到终端：
-```
-[12:34:56] [GATE] listening on http://127.0.0.1:7790 (window: 60s, max: 2 searches per key)
-[12:35:00] [GATE] /permit: key=xiaohongshu_fresh allowed=true countInWindow=1/2
-[12:35:03] [GATE] /permit: key=xiaohongshu_fresh allowed=true countInWindow=2/2
-[12:35:06] [GATE] /permit: key=xiaohongshu_fresh allowed=false waitMs=54000
-```
----
-## 注意事项
-1. **不持久化**：SearchGate 重启后队列清空，已授权的请求需重新申请
-2. **单点服务**：所有平台共享一个 SearchGate（通过 `key` 隔离）
-3. **独立于浏览器**：不受浏览器启停影响，可常驻后台
-4. **Workflow 失败时**：如果 SearchGate 不可达，`WaitSearchPermitBlock` 会抛出异常，Workflow 失败
-5. **调试模式**：可设置 `WEBAUTO_SEARCH_GATE_URL=http://127.0.0.1:7790` 覆盖默认端口
----
-## 文件清单
-| 文件 | 说明 |
-|------|------|
-| `scripts/search-gate-server.mjs` | SearchGate HTTP 服务（主入口） |
-| `scripts/search-gate-cli.mjs` | CLI（start/stop/restart/status） |
-| `modules/workflow/blocks/WaitSearchPermitBlock.ts` | Workflow Block（申请许可） |
-| `scripts/xiaohongshu/tests/phase1-session-login-with-gate.mjs` | Phase1 + 自动启动 Gate |
-| `scripts/xiaohongshu/tests/test-search-gate.mjs` | 速率限制测试脚本 |
-| `modules/workflow/definitions/xiaohongshu-collect-workflow-v2.ts` | 包含 WaitSearchPermitBlock 的 Workflow 定义 |
-| `scripts/run-xiaohongshu-workflow-v2.ts` | Workflow Runner（已注册 WaitSearchPermitBlock） |
----
-## 参考
-- `AGENTS.md` § 新增规则（2025-01-06）：SearchGate 强制节流
-- `container-library/xiaohongshu/README.md`：小红书容器定义与登录锚点
-- `docs/arch/PORTS.md`：端口分配（7790 = SearchGate）

package/docs/arch/VIEWPORT_SAFETY.md DELETED Viewed

@@ -1,182 +0,0 @@
-# 视口安全行为准则（Viewport Safety Guidelines）
-## 背景
-小红书等平台通过 **视口行为检测** 识别自动化爬虫：
-- 真实用户不会点击离屏（off-screen）元素
-- 不会进行非自然的大跨度滚动
-- 不会操作 `display:none` 或 `visibility:hidden` 的元素
-本准则确保所有容器操作模拟真实用户可见行为。
----
-## 核心原则
-1. **可见即操作**：只操作当前视口内可见元素
-2. **先验证后操作**：每个操作前必须通过 Rect 验证
-3. **渐进式滚动**：滚动仅用于将元素带入视口
-4. **自然节奏**：操作间加入人类可感知的延迟
----
-## 技术规范
-### 1. 可见性验证
-**必须同时满足：**
-```js
-rect.y < window.innerHeight &&  // 元素顶部在视口内
-rect.width > 0 &&               // 有宽度
-rect.height > 0 &&              // 有高度
-getComputedStyle(element).display !== 'none' &&
-getComputedStyle(element).visibility !== 'hidden'
-```
-**验证流程：**
-1. 通过 `containers:match` 获取元素坐标
-2. 验证上述条件
-3. 如不满足，滚动到元素位置
-4. 重新验证（最多 3 次）
-### 2. 滚动约束
-**单次滚动：**
-- 最大距离：800px（用户单次手势范围）
-- 滚动后：必须重新验证可见性
-- 滚动间隔：≥500ms（避免连续滚动）
-**滚动方式：**
-```js
-// ✅ 正确：平滑滚动到元素
-element.scrollIntoView({ behavior: 'smooth', block: 'center' });
-// ❌ 错误：直接跳转到固定位置
-window.scrollTo(0, 3000);
-```
-### 3. 点击约束
-**点击前检查：**
-1. 元素在视口中心区域（避免边缘误触）
-2. 无其他元素遮挡（z-index 检查）
-3. 元素可交互（`pointer-events !== 'none'`）
-**点击方式：**
-```js
-// ✅ 正确：自然点击
-await element.click();
-// ❌ 错误：合成事件（除非必要）
-element.dispatchEvent(new MouseEvent('click', { bubbles: true }));
-```
-### 4. 输入约束
-**输入节奏：**
-- 每字符间隔：50-200ms（随机）
-- 先聚焦再输入：
-```js
-element.focus();
-await delay(Math.random() * 150 + 50); // 50-200ms
-```
-**事件触发：**
-```js
-element.value = text;
-element.dispatchEvent(new Event('input', { bubbles: true }));
-element.dispatchEvent(new Event('change', { bubbles: true }));
-```
----
-## 实现检查清单
-### Block 级别
-- [ ] 每个 Block 返回 `anchor.rect` 必须通过验证
-- [ ] 滚动操作后重新验证可见性
-- [ ] 点击前高亮 1-2 秒供视觉确认
-### 脚本级别
-- [ ] 无直接 `window.scrollTo(x, y)` 大跨度滚动
-- [ ] 无 `querySelector` 后直接操作离屏元素
-- [ ] 所有操作基于当前视口状态
-### 调试级别
-- [ ] 通过 `debug-container-tree-*.mjs` 验证可见性
-- [ ] 日志中记录离屏操作告警
-- [ ] Rect 验证失败时抛出可见性错误
----
-## 违规示例
-### ❌ 禁止做法
-```js
-// 直接操作可能不可见元素
-document.querySelector('.hidden-button').click();
-// 大跨度滚动后操作
-window.scrollTo(0, 3000);
-document.querySelector('.far-away-element').click();
-// 无可见性验证的操作
-element.click(); // 未检查 element 是否在视口内
-```
-### ✅ 正确做法
-```js
-// 先验证可见性
-const rect = await verifyAnchor(containerId);
-if (rect.y > window.innerHeight) {
-  await scrollToElement(containerId);
-  const newRect = await verifyAnchor(containerId);
-  if (!newRect) throw new Error('元素不可见');
-}
-// 高亮确认
-await highlight(containerId);
-await delay(1000);
-// 执行操作
-await click(containerId);
-```
----
-## 检测与监控
-### 开发阶段
-- 每个 Block 必须返回 `anchor.rect.verified: true`
-- 通过 `scripts/debug-container-tree-*.mjs` 验证可见性
-- 调试日志记录离屏操作尝试
-### 生产阶段
-- 监控日志中的可见性验证失败率
-- 设置告警阈值（如 >5% 失败率）
-- 定期审查新 Block 的 Rect 验证逻辑
----
-## 审查标准
-| 等级 | 标准 | 处理方式 |
-|------|------|----------|
-| **A级** | 所有操作基于可见元素 + Rect 验证闭环 | 符合发布标准 |
-| **B级** | 大部分操作可见，少量离屏但有合理滚动 | 需改进后发布 |
-| **C级** | 存在直接离屏操作 | **阻塞发布**，必须整改 |
----
-## 相关工具
-- `scripts/debug-container-tree-summary.mjs` - 快速验证可见性
-- `scripts/debug-container-tree-full.mjs` - 完整容器可见性检查
-- `modules/workflow/blocks/helpers/anchorVerify.ts` - Rect 验证辅助函数
-- `scripts/container-op.mjs` - 带可见性验证的容器操作
----
-**制定时间**：2025-01-06
-**适用范围**：所有小红书采集脚本与 Workflow Block
-**审查周期**：每次 Block 新增或修改时必须验证