@web-auto/webauto 0.1.1 → 0.1.3

package/docs/arch/XIAOHONGSHU_OFFLINE_MOCK_DESIGN.md

@@ -1,267 +0,0 @@
-# 小红书采集持久化节点与离线仿真测试设计
-
-> 目标：在不依赖线上页面和 URL 跳转的前提下，完整验证「详情提取 + 评论采集 + 持久化写盘」链路，为后续量产采集提供稳定闭环。
-
-## 1. 持久化节点：PersistXhsNoteBlock
-
-### 1.1 职责
-
-- 单一职责：将当前 Note 的结构化内容（详情 + 评论）写入本地目录结构；
-- 不做 DOM 访问、不做容器操作，只处理纯数据与文件系统；
-- 所有落盘路径统一落在 `~/.webauto/download/xiaohongshu/{env}/`。
-
-### 1.2 输入
-
-由上游 Workflow 上下文提供（通常来自 ExtractDetailBlock / CollectCommentsBlock）：
-
-- `sessionId: string`
-- `env: string`：环境标记，例如 `debug` / `prod`
-- `platform?: string`：默认 `'xiaohongshu'`
-- `keyword: string`
-- `noteId: string`
-- `detailUrl?: string`：当前详情页 URL（带 xsec token，只用于展示，不参与导航）
-- `detail: { ... }`：
-  - 至少包含：`title`, `contentText`, `gallery: { images: string[] }`
-  - 具体字段沿用 ExtractDetailBlock 的输出结构
-- `commentsResult: { ... }`：
-  - 至少包含：
-    - `comments: Array<{ user_name?, user_id?, timestamp?, text? }>`
-    - `totalFromHeader?: number`
-    - `reachedEnd?: boolean`
-    - `emptyState?: boolean`
-
-### 1.3 输出
-
-```ts
-interface PersistXhsNoteOutput {
-  success: boolean;
-  error?: string;
-  outputDir?: string;     // 实际写盘的帖子目录
-  contentPath?: string;   // content.md 路径
-  imagesDir?: string;     // images 目录路径
-}
-```
-
-### 1.4 目录结构
-
-- 根目录：`~/.webauto/download/xiaohongshu/{env}/`
-- 关键字目录：`{root}/{sanitize(keyword)}/`
-- 单条 Note 目录：`{root}/{sanitize(keyword)}/{noteId}/`
-  - `content.md`：帖子+评论 Markdown
-  - `images/`：图片文件
-
-`sanitize(keyword)`：沿用现有实现，替换 `\/:*?"<>|` 等字符为 `_`，并 trim。
-
-### 1.5 写盘逻辑
-
-1. **目录创建**
-   - 依次确保 `root/keywordDir/postDir/imagesDir` 存在；
-   - 使用 Node ESM FS API：`fs.promises.mkdir(dir, { recursive: true })`。
-
-2. **图片下载**
-   - 来源：`detail.gallery.images: string[]`；
-   - 预处理：
-     - 去除空值，两端 trim；
-     - `//` 开头补 `https:`；
-     - 仅保留 `http/https` 协议；
-   - 下载策略：
-     - 使用 `fetch(url)` 获取响应，`arrayBuffer()` → `Buffer`；
-     - 文件名：`images/{index}.jpg`（`01.jpg`、`02.jpg`...，保留顺序即可）；
-     - 对单张失败情况：跳过该 URL，打印告警但不使整个 Block 失败；
-   - 返回：
-     - 本地相对路径列表，例如：`['images/01.jpg', 'images/02.jpg', ...]`。
-
-3. **content.md 结构**
-
-示例结构（与现有 `collect-100-workflow-v2.mjs` 一致，但文件名统一为 `content.md`）：
-
-```markdown
-# {title || '无标题'}
-
-- Note ID: {noteId}
-- 关键词: {keyword}
-- 链接: {detailUrl}
-- 作者: {author}
-- 评论统计: 抓取={comments.length}, header={totalFromHeader|未知}（reachedEnd={是/否}, empty={是/否}）
-
-## 正文
-
-{contentText 或占位 "（无正文）"}
-
-## 图片
-
-![](images/01.jpg)
-![](images/02.jpg)
-...
-
-## 评论
-
-- **用户名**(user_id) [时间]：评论文本
-...
-```
-
-字段选择策略：
-
-- `title`：优先 detail.header/content 中的标题字段，其次回退到列表 item 的标题；
-- `author`：从 detail.header 中的 `author/user_name/nickname` 选取；
-- `contentText`：从 detail.content 中组合正文文本字段；
-- `评论统计`：使用 `commentsResult.comments/totalFromHeader/reachedEnd/emptyState` 填充。
-
-评论渲染规则：
-
-- 遍历 `commentsResult.comments`：
-  - `user = user_name || username || '未知用户'`
-  - `uid = user_id || ''`
-  - `ts = timestamp || ''`
-  - `text = text || ''`
-  - 生成：`- **{user}**({uid}) [ts]：{text}`
-- 当 `comments.length === 0` 时写入：`（无评论）`。
-
----
-
-## 2. 在线数据 → 本地 fixture JSON
-
-> 一次在线采集，多次离线复用。
-
-### 2.1 录制位置
-
-- 在真实阶段（在线运行）中，在以下 Block 后增加 debug 输出（仅在 `DEBUG` 或特定环境下打开）：
-  - `ExtractDetailBlock` 完成后；
-  - `CollectCommentsBlock` 完成后。
-- 将两者输出聚合成一份结构体：
-
-```ts
-interface XhsNoteFixture {
-  noteId: string;
-  keyword: string;
-  detailUrl: string;
-  detail: any;          // ExtractDetailBlock 完整输出
-  commentsResult: any;  // CollectCommentsBlock 完整输出
-  capturedAt: string;   // ISO 时间
-}
-```
-
-### 2.2 落盘路径
-
-- 路径统一放在用户目录，不进仓库：
-  - `~/.webauto/fixtures/xiaohongshu/{noteId}.json`
-- 由一个小的工具函数或 Block 内部调试逻辑写入：
-  - 非强制步骤，只在调试/回放模式下写，避免常态任务产生太多 fixture。
-
-### 2.3 用途
-
-- PersistXhsNoteBlock 的单元/集成测试直接以 fixture 为输入，不依赖浏览器或 DOM；
-- 也作为生成离线 HTML 仿真页的原始数据源。
-
----
-
-## 3. fixture JSON → 仿真 HTML 详情页
-
-> 目标：构造一个“结构类似小红书详情页”的本地 HTML，使容器系统与 Block 可以在本地跑完整链路。
-
-### 3.1 生成脚本
-
-- 新增脚本：`scripts/xiaohongshu/tests/generate-detail-mock-page.mjs`
-- 输入：
-  - `--noteId <id>`：从 `~/.webauto/fixtures/xiaohongshu/{noteId}.json` 读数据；
-  - `--output <path>`（可选）：默认写到 `~/.webauto/fixtures/xiaohongshu/detail-{noteId}.html`。
-- 输出：
-  - 一份完整 HTML，模拟线上详情页的布局和 class 结构。
-
-### 3.2 DOM 结构设计（按容器对齐）
-
-仿真 DOM 需对齐以下容器 ID/selector：
-
-- 详情容器：
-  - `xiaohongshu_detail.modal_shell` / `xiaohongshu_detail`：最外层模态框容器；
-  - `xiaohongshu_detail.header`：标题、作者信息区域；
-  - `xiaohongshu_detail.content`：正文文本区域；
-  - `xiaohongshu_detail.gallery`：图片区域。
-- 评论容器：
-  - `xiaohongshu_detail.comment_section`：评论区根容器；
-  - `xiaohongshu_detail.comment_section.comment_item`：单条评论节点；
-  - `xiaohongshu_detail.comment_section.show_more_button`：展开更多按钮；
-  - `xiaohongshu_detail.comment_section.end_marker`：末尾 marker（可选）。
-
-布局要点：
-
-- 使用与容器 JSON 中 selector 对齐的 class / DOM 层级；
-- 每条评论生成一段 `.comment-item`，内部包含：
-  - 用户名元素（如 `.user-name`）；
-  - 用户链接/ID（放在 `data-user-id` 或 `<a href="/user">` 中）；
-  - 时间元素；
-  - 文本元素。
-
-### 3.3 “展开更多评论”仿真
-
-- 插入若干 `.show-more` 按钮与折叠块：
-  - 初始部分评论（例如前 N 条）直接可见；
-  - 后续评论包在一个 `div` 里，`style="display:none"`；
-  - 在其前插入一个 `.show-more` 元素。
-- 在页面底部插入一段简单的 inline JS：
-
-```js
-document.addEventListener('click', (e) => {
-  const btn = e.target.closest('.show-more');
-  if (!btn) return;
-  const block = btn.nextElementSibling;
-  if (block) {
-    block.style.display = 'block';
-    btn.remove();
-  }
-});
-```
-
-- 目的：让 `WarmupCommentsBlock` + `CollectCommentsBlock` 在本地也能通过容器 click 自动展开评论，行为上与线上一致。
-
-### 3.4 图片区域仿真
-
-- 使用 fixture 中的 `detail.gallery.images`：
-  - 在 gallery 容器下生成 `<img>` 列表，class 对齐容器定义，例如：
-    - `.note-img img`、`.note-scroller img` 等；
-  - `src` 直接使用线上 URL（下载由 PersistXhsNoteBlock 负责）。
-
----
-
-## 4. 基于仿真页的测试策略
-
-### 4.1 PersistXhsNoteBlock 单块测试
-
-1. 使用 fixture JSON 作为直接输入，不依赖 HTML/浏览器；
-2. 调用 `PersistXhsNoteBlock.execute()`；
-3. 断言：
-   - 目录结构：`~/.webauto/download/xiaohongshu/{env}/{keyword}/{noteId}/` 存在；
-   - `content.md` 内容完整（标题、元信息、正文、图片引用、评论）；
-   - `images/` 下图片数量与 `gallery.images` 数量基本一致（允许部分下载失败但有告警）。
-
-### 4.2 单 Note Workflow 离线 E2E
-
-1. 启动 Browser Service，但导航到本地生成的仿真 HTML：
-   - 例如：`http://127.0.0.1:port/xhs-mock/detail-{noteId}.html`；
-   - URL 不包含任何线上域名，也不构造 xsec-less 链接。
-2. 通过 `runWorkflowById('xiaohongshu-note-collect', { sessionId, keyword, env, noteId, detailUrl: mockUrl })` 执行：
-   - 内部仍然使用容器系统进行 anchor 定位、滚动、展开评论；
-   - CollectCommentsBlock 与 ExtractDetailBlock 均在本地仿真 DOM 上运行。
-3. 验证：
-   - WorkflowExecutionResult 中各步骤 success；
-   - 持久化结果与 fixture 内容一致（评论条数、标题、正文等）。
-
-### 4.3 整链路集成（可选）
-
-- 在 debug 模式下，将搜索阶段替换为「直接跳本地仿真详情页」的简化 Workflow，用于验证：
-  - 顶层 Workflow + CallWorkflowBlock 串联；
-  - note-collect 节点可被反复调用且写盘正确；
-  - 不再依赖真实搜索页和线上滚动。
-
----
-
-## 5. 对现有代码的影响范围（规划）
-
-1. 新增 Block：`PersistXhsNoteBlock`（仅依赖 Node FS 与 fetch，不依赖容器或浏览器上下文）；
-2. 新增脚本：`scripts/xiaohongshu/tests/generate-detail-mock-page.mjs`；
-3. 适度修改：
-   - 在在线调试脚本 / Workflow 中增加 fixture 录制逻辑（可由 DEBUG 开关控制）；
-   - 在 `xiaohongshu-note-collect` Workflow 定义中插入 `PersistXhsNoteBlock`。
-
-通过本设计，我们可以在本地稳定重放“小红书详情+评论”的复杂场景，用真实数据驱动的仿真 DOM 来验证容器、Block 与持久化逻辑，而不再依赖线上页面与 URL 导航，从而显著降低调试成本与风控风险。 
-

package/docs/xiaohongshu-container-driven-summary.md

@@ -1,221 +0,0 @@
-# 小红书容器驱动化改造总结
-
-> 日期：2025-01-06
-> 状态：✅ 完成
-> 目标：将小红书采集链路完全切换到容器驱动模式
-
-## ✅ 完成清单
-
-### 1. 登录锚点模型定义 ✅
-
-**文件**：`container-library/xiaohongshu/README.md`
-
-**约定**：
-- **已登录标识**：`*.login_anchor`（匹配任意页面下的登录锚点容器）
-- **未登录标识**：`xiaohongshu_login.login_guard`（登录页核心控件）
-- **不确定状态**：两类容器都不匹配
-
-**容器选择器**：
-- `*.login_anchor`：`a.link-wrapper[title="我"]`
-- `xiaohongshu_login.login_guard`：登录页核心控件
-
-### 2. Launcher 登录检测改造 ✅
-
-**文件**：`launcher/core/launcher.mjs`
-
-**改造内容**：
-- 移除硬编码 DOM 查询
-- 改为调用 `containers:match` 获取容器树
-- 递归查找 `*.login_anchor` 和 `xiaohongshu_login.login_guard`
-- 不再直接读取 `__INITIAL_STATE__` 等全局变量
-
-**关键代码**：
-```typescript
-function findContainer(tree, pattern) {
-  if (pattern.test(tree.id || tree.defId)) return tree;
-  // 递归查找...
-}
-
-const loginAnchor = findContainer(tree, /\.login_anchor$/);
-const loginGuard = findContainer(tree, /xiaohongshu_login\.login_guard$/);
-```
-
-### 3. Workflow Block 实现 ✅
-
-**文件**：`modules/workflow/blocks/EnsureLoginBlock.ts`
-
-**功能**：
-- 通过 `containers:match` API 查找容器
-- 匹配到 `*.login_anchor` → 返回 `isLoggedIn: true`
-- 匹配到 `login_guard` → 等待人工登录
-- 超时保护（默认 2 分钟）
-
-**接口**：
-```typescript
-interface EnsureLoginInput {
-  sessionId: string;
-  serviceUrl?: string;
-  maxWaitMs?: number;
-  checkIntervalMs?: number;
-}
-
-interface EnsureLoginOutput {
-  isLoggedIn: boolean;
-  loginMethod: 'container_match' | 'manual_wait' | 'timeout';
-  matchedContainer?: string;
-  waitTimeMs?: number;
-  error?: string;
-}
-```
-
-### 4. 调试脚本改造 ✅
-
-**文件**：
-- `scripts/xiaohongshu/tests/status-v2.mjs` - 状态检查
-- `scripts/xiaohongshu/tests/phase1-session-login.mjs` - 登录守护
-- `scripts/debug-xhs-search.mjs` - Unattached 搜索验证
-- `scripts/debug-xhs-detail.mjs` - Unattached 详情页交互
-
-**改造要点**：
-- 移除硬编码 DOM 逻辑（如 `if (url.includes('xiaohongshu'))`）
-- 完全基于容器 ID 匹配
-- 优先使用刷新而非重新导航
-- 测试后恢复初始状态
-
-### 5. 文档完善 ✅
-
-**文件**：
-- `container-library/xiaohongshu/README.md` - 登录锚点约定
-- `AGENTS.md` - 调试脚本 Unattached 模式规则
-- `task.md` - 完整任务追踪
-
-## 📊 容器驱动化对比
-
-### ❌ 旧方式（硬编码 DOM）
-
-```javascript
-// 禁止这样写
-if (url.includes('xiaohongshu.com')) {
-  const avatar = await page.$('a[title="我"]');
-  if (avatar) return true;
-}
-```
-
-**问题**：
-- DOM 选择器易失效
-- 平台特定逻辑分散
-- 难以测试和维护
-- 违反分层原则
-
-### ✅ 新方式（容器驱动）
-
-```typescript
-// 推荐：基于容器 ID
-const result = await controllerAction('containers:match', { profile, url });
-const loginAnchor = findContainer(tree, /\.login_anchor$/);
-if (loginAnchor) {
-  return { isLoggedIn: true };
-}
-```
-
-**优势**：
-- 平台无关（同一套代码支持微博/抖音等）
-- 选择器集中在容器定义
-- 易于测试和验证
-- 符合分层架构
-
-## 🔄 数据流
-
-### 登录检测流程
-
-```
-1. Launcher / Workflow
-   ↓
-2. 调用 containers:match
-   ↓
-3. 获取容器树
-   ↓
-4. 递归查找 *.login_anchor
-   ↓
-5a. 匹配到 → 已登录
-   ↓
-5b. 未匹配到，查找 xiaohongshu_login.login_guard
-   ↓
-6a. 匹配到 → 未登录，等待人工
-   ↓
-6b. 未匹配到 → 不确定状态
-```
-
-### Workflow 执行流程
-
-```
-1. EnsureSessionBlock
-   ↓
-2. EnsureLoginBlock（容器驱动）
-   ↓
-3. GoToSearchBlock（容器驱动）
-   ↓
-4. PickNoteBlock（容器驱动）
-   ↓
-5. OpenDetailBlock（容器驱动）
-   ↓
-6. ExpandCommentsBlock（容器驱动）
-```
-
-## 📝 关键文件清单
-
-| 文件 | 状态 | 说明 |
-|------|------|------|
-| `container-library/xiaohongshu/README.md` | ✅ | 登录锚点约定文档 |
-| `launcher/core/launcher.mjs` | ✅ | 容器驱动登录检测 |
-| `modules/workflow/blocks/EnsureLoginBlock.ts` | ✅ | 通用登录 Block |
-| `scripts/xiaohongshu/tests/status-v2.mjs` | ✅ | 容器驱动状态检查 |
-| `scripts/xiaohongshu/tests/phase1-session-login.mjs` | ✅ | 容器驱动登录守护 |
-| `scripts/debug-xhs-search.mjs` | ✅ | Unattached 搜索验证 |
-| `scripts/debug-xhs-detail.mjs` | ✅ | Unattached 详情页交互 |
-| `AGENTS.md` | ✅ | Unattached 模式规则 |
-| `task.md` | ✅ | 完整任务追踪 |
-
-## 🎯 验证测试
-
-### 测试命令
-
-```bash
-# 1. 检查会话状态（容器驱动）
-node scripts/xiaohongshu/tests/status-v2.mjs
-
-# 2. 一键启动（容器驱动登录检测）
-node scripts/start-headful.mjs --profile xiaohongshu_fresh --url https://www.xiaohongshu.com
-
-# 3. 搜索验证（Unattached 模式）
-node scripts/debug-xhs-search.mjs
-
-# 4. 详情页测试（Unattached 模式）
-node scripts/debug-xhs-detail.mjs
-```
-
-### 预期结果
-
-- 所有脚本不再硬编码 DOM 逻辑
-- 登录状态完全基于容器匹配
-- 调试脚本复用现有 session
-- Workflow 可以直接复用 EnsureLoginBlock
-
-## 🚀 下一步
-
-1. 运行测试脚本验证容器驱动化
-2. 创建第一个基于容器驱动的完整 Workflow
-3. 运行小规模采集测试（5 条数据）
-4. 优化 XiaohongshuCrawlerBlock 使用新架构
-
-## 📚 参考文档
-
-- `container-library/xiaohongshu/README.md` - 容器定义 + 登录锚点约定
-- `task.md` - 当前任务追踪
-- `AGENTS.md` - 架构规则
-- `docs/xiaohongshu-next-steps.md` - 详细任务清单
-
----
-
-**完成时间**：2025-01-06 09:30
-**改造成果**：小红书链路 100% 容器驱动化

package/docs/xiaohongshu-full-collect-runbook.md

@@ -1,134 +0,0 @@
-# 小红书全流程采集执行文档（Phase1-4）
-
-> 目标：确保“列表未达目标也继续执行 Phase3/4 评论采集”，即使列表滚动异常也不中断后续流程。
-
-## 一、前置检查
-
-### 1. 服务状态
-
-```bash
-curl http://127.0.0.1:7701/health
-curl http://127.0.0.1:7704/health
-```
-
-### 2. 会话状态
-
-```bash
-node scripts/xiaohongshu/tests/status-v2.mjs
-```
-
-必须确认：
-- session: `xiaohongshu_fresh` 已存在
-- 登录锚点 `*.login_anchor` 命中
-- 当前页面处于小红书正常页面
-
-### 3. SearchGate
-
-如果需要搜索（Phase2 会触发）：
-
-```bash
-node scripts/search-gate-server.mjs
-```
-
-## 二、全流程启动
-
-### 1. 启动完整采集
-
-```bash
-node scripts/xiaohongshu/tests/phase1-4-full-collect.mjs --keyword "雷军" --count 200
-```
-
-输出目录（强制标准）：
-```
-~/.webauto/download/xiaohongshu/{env}/{keyword}/{noteId}/
-```
-
-默认 env=`download`（可通过参数调整）。
-
-### 2. 运行阶段说明
-
-| 阶段 | 功能 | 退出条件 |
-|------|------|-----------|
-| Phase1 | 确认服务/会话/登录 | 成功即进入 Phase2 |
-| Phase2(ListOnly) | 搜索列表采集 + 获取 safe-detail-urls | **列表滚动异常不影响后续阶段** |
-| Phase3 | 基于 safe-detail-urls 打开详情 | safe-detail-urls 为空则跳过 |
-| Phase4 | 采集评论并落盘 | 逐条完成，增量写 comments.md |
-
-### 3. 关键要求（必须遵守）
-
-- **不允许 URL 直跳**：必须从搜索页点击进入详情
-- **SearchGate 节流**：搜索必须先申请许可
-- **容器锚点**：禁止硬编码 DOM
-- **滚动必须在视口内**：禁止 off-screen 操作
-- **内容文件名必须是 `content.md`**（不是 README.md）
-
-## 三、Phase2 滚动异常处理（修复后行为）
-
-### 目标
-
-- **只在检测到 END 标记时认为真正到底**
-- **若滚动失败：仍继续尝试滚动**
-- **即使 Phase2 未达标，也继续执行 Phase3/4**
-
-### 异常退出逻辑（修复后）
-
-- 连续 3 轮滚动失败（每轮 3 次重试） → 标记 Phase2 异常退出
-- **但不会中断流程**：Phase3/4 继续执行已采集的 safe-detail-urls
-
-## 四、产出目录结构
-
-```
-~/.webauto/download/xiaohongshu/{env}/{keyword}/{noteId}/
-├── content.md
-├── images/
-│   ├── 1.jpg
-│   └── ...
-└── comments.md   # Phase4 追加生成
-```
-
-其他文件：
-- `.collect-state.json`：断点状态
-- `safe-detail-urls.jsonl`：带 xsec_token 的详情链接索引
-- `run.log / run-events.jsonl`：流程日志
-
-## 五、恢复采集
-
-如中断，可直接重跑，脚本会续传：
-
-```bash
-node scripts/xiaohongshu/tests/phase1-4-full-collect.mjs --keyword "雷军" --count 200
-```
-
-## 六、排查常见问题
-
-### 1. Phase2 停止但未到 END
-
-修复后不会直接停止，只会进入“滚动失败重试”。
-若仍退出：
-- 检查 END 标记是否存在
-- 检查容器结构是否变化
-- 检查 SearchGate 状态
-
-### 2. 没有 comments.md
-
-说明 Phase4 未完成或评论为空：
-- 检查日志 `Phase4` 关键字
-- 检查是否遇到风控
-
-### 3. 输出路径不对
-
-必须是：
-```
-~/.webauto/download/xiaohongshu/{env}/{keyword}/{noteId}/
-```
-
-## 七、日志定位
-
-```bash
-# 最新 run log
-ls -lt ~/.webauto/download/xiaohongshu/{env}/{keyword}/run*.log | head -1
-
-# 查看关键错误
-rg "ERROR|WARN|风控|phase2_scroll_failure" ~/.webauto/download/xiaohongshu/{env}/{keyword}/run*.log
-```
-