@web-auto/webauto 0.1.1 → 0.1.3

package/docs/xiaohongshu-next-steps.md

@@ -1,228 +0,0 @@
-# 小红书 Workflow - 下一步任务清单
-
-## ✅ 已完成
-
-1. **容器库架构** - 完整实现了搜索页、详情页、评论区等所有容器定义
-2. **Workflow Block** - `XiaohongshuCrawlerBlock.ts` 实现了完整采集逻辑
-3. **Debug 脚本** - 创建了 `debug-xhs-status/search/detail.mjs` 三个阶段测试脚本
-4. **AGENTS.md 规则** - 新增"调试脚本必须保持浏览器会话不被破坏"规则
-
-## 📋 当前问题分析
-
-### 问题 1: 调试脚本频繁重启浏览器 ❌
-**现状**:
-- `scripts/xiaohongshu-test-comments.mjs` 中有 `startBrowserSession()` 逻辑
-- 每次运行都可能调用 `start-headful.mjs` 启动新会话
-- 破坏了现有 session 状态
-
-**需要修改**:
-- `xiaohongshu-test-comments.mjs`
-- 其他可能启动新session的测试脚本
-
-### 问题 2: 频繁导航到同一页面 ❌
-**现状**:
-- `debug-xhs-search.mjs` 中有 `ensureSearchPage()` 会直接跳转
-- 没有先检查当前URL是否已经在目标页面
-
-**需要修改**:
-- 在导航前先检查 `getCurrentUrl()`
-- 如果已在目标页，只刷新而不重新导航
-
-### 问题 3: 脚本不是 unattached 模式 ❌
-**现状**:
-- 测试脚本直接操作浏览器，可能改变会话状态
-- 没有明确的"只读"或"非侵入"模式
-
-**需要改进**:
-- 明确标记哪些操作是只读的（如 status 检查）
-- 哪些操作会改变状态（如 search、navigate）
-- 提供恢复机制（如记录初始 URL，测试后恢复）
-
-## 🎯 下一步任务（按优先级排序）
-
-### Task 1: 修改现有调试脚本为 unattached 模式 ⏳
-
-**目标**: 让调试脚本复用现有 session，不重启浏览器
-
-**子任务**:
-
-1. **修改 `debug-xhs-status.mjs`** ✅
-   - ✅ 已经符合要求：仅读取状态，不改变页面
-   - ✅ 使用现有 PROFILE，不启动新session
-   
-2. **修改 `debug-xhs-search.mjs`** ⏳
-   - [ ] `ensureSearchPage()` 改为先检查当前URL
-   - [ ] 如果已在搜索页，优先使用 `location.reload()` 而非重新导航
-   - [ ] 记录初始URL，测试完成后可选恢复
-   
-3. **修改 `debug-xhs-detail.mjs`** ⏳
-   - [ ] 检查当前是否已在搜索页
-   - [ ] 测试完成后关闭详情模态，恢复到搜索页
-   - [ ] 不强制导航，优先使用现有页面状态
-
-4. **修改 `xiaohongshu-test-comments.mjs`** ⏳
-   - [ ] 移除 `startBrowserSession()` 自动启动逻辑
-   - [ ] 改为检测session不存在时，提示用户手动启动
-   - [ ] 或者提供 `--ensure-session` flag，明确需要时才启动
-
-**修改原则**:
-```javascript
-// ❌ 旧方式 - 直接导航
-async function ensureSearchPage() {
-  await controllerAction('browser:execute', {
-    script: `window.location.href = 'https://www.xiaohongshu.com'`
-  });
-}
-
-// ✅ 新方式 - 检查后刷新或导航
-async function ensureSearchPage() {
-  const url = await getCurrentUrl();
-  if (url.includes('xiaohongshu.com/search_result')) {
-    console.log('   ✅ 已在搜索页，刷新...');
-    await controllerAction('browser:execute', {
-      script: 'location.reload()'
-    });
-  } else if (url.includes('xiaohongshu.com')) {
-    console.log('   ⚠️  在小红书其他页面，导航到搜索...');
-    await controllerAction('browser:execute', {
-      script: `window.location.href = 'https://www.xiaohongshu.com/search_result?...'`
-    });
-  } else {
-    console.log('   ❌ 不在小红书页面，请先手动导航');
-    process.exit(1);
-  }
-}
-```
-
-### Task 2: 创建 Session 检查脚本 ⏳
-
-**目标**: 提供统一的 session 状态检查工具
-
-**文件**: `scripts/check-xiaohongshu-session.mjs`
-
-**功能**:
-- 检查 `xiaohongshu_fresh` session 是否存在
-- 显示当前 URL
-- 显示登录状态
-- 显示 Cookie 过期时间
-- 给出启动建议（如果 session 不存在）
-
-**用法**:
-```bash
-node scripts/check-xiaohongshu-session.mjs
-```
-
-### Task 3: 更新测试脚本文档 ⏳
-
-**目标**: 明确测试流程和最佳实践
-
-**文件**: `docs/testing-xiaohongshu.md`
-
-**内容**:
-1. **Session 管理规范**
-   - 启动 session：`node scripts/start-headful.mjs --profile xiaohongshu_fresh --url https://www.xiaohongshu.com`
-   - 检查 session：`node scripts/check-xiaohongshu-session.mjs`
-   - Session 应保持运行，不要频繁重启
-
-2. **测试流程**
-   ```bash
-   # 1. 启动 session（仅首次或session丢失时）
-   node scripts/start-headful.mjs --profile xiaohongshu_fresh --url https://www.xiaohongshu.com
-   
-   # 2. 运行阶段测试（session 保持运行）
-   node scripts/debug-xhs-status.mjs    # Step 1: 状态诊断
-   node scripts/debug-xhs-search.mjs    # Step 2: 搜索验证
-   node scripts/debug-xhs-detail.mjs    # Step 3: 详情页交互
-   
-   # 3. 完整 workflow 测试
-   node scripts/run-xiaohongshu-workflow.ts --keyword "oppo小平板" --count 5
-   ```
-
-3. **调试技巧**
-   - 使用 Bus 订阅监听事件：`wscat -c ws://127.0.0.1:7701/bus`
-   - 查看容器匹配日志：检查 `container:match` 事件
-   - 截图调试：在脚本中增加 `takeScreenshot()` 调用
-
-### Task 4: 优化 XiaohongshuCrawlerBlock ⏳
-
-**目标**: 根据实际测试结果优化 Block 逻辑
-
-**待优化点**:
-1. **Context Destroyed 处理**
-   - [ ] 增加 retry 机制
-   - [ ] 优化 `waitForDetailContext()` 的轮询策略
-   
-2. **评论展开优化**
-   - [ ] 根据实际 DOM 调整滚动距离和次数
-   - [ ] 优化 `show_more_button` 的查找逻辑
-   
-3. **图片下载优化**
-   - [ ] 增加并发控制
-   - [ ] 优化重试策略
-   
-4. **性能优化**
-   - [ ] 减少不必要的等待时间
-   - [ ] 并行处理部分操作
-
-### Task 5: 小规模验证测试 ⏳
-
-**目标**: 运行完整 workflow，采集 5 条数据验证
-
-**步骤**:
-```bash
-# 1. 确保 session 运行
-node scripts/check-xiaohongshu-session.mjs
-
-# 2. 运行 workflow（小规模）
-node scripts/run-xiaohongshu-workflow.ts --keyword "手机膜" --count 5
-
-# 3. 检查输出
-ls -la ~/.webauto/download/xiaohongshu/手机膜/
-
-# 4. 验证数据完整性
-# - Markdown 格式正确
-# - 图片下载成功
-# - 评论数据完整
-```
-
-## 🔄 迭代计划
-
-### 第一轮：基础功能验证（本周）
-- [x] 创建调试脚本
-- [x] 补充 AGENTS.md 规则
-- [ ] 修改脚本为 unattached 模式
-- [ ] 运行 5 条数据测试
-
-### 第二轮：稳定性优化（下周）
-- [ ] 优化 Context Destroyed 问题
-- [ ] 优化评论展开逻辑
-- [ ] 增加错误恢复机制
-- [ ] 运行 50 条数据测试
-
-### 第三轮：性能优化（后续）
-- [ ] 并行采集优化
-- [ ] 图片下载优化
-- [ ] 增加增量采集支持
-- [ ] 运行 200+ 条数据测试
-
-## 📊 预期成果
-
-- ✅ 调试流程清晰，session 状态稳定
-- ✅ 容器匹配成功率 > 95%
-- ✅ 评论展开成功率 > 90%
-- ✅ 图片下载成功率 > 85%
-- ✅ 平均每条数据采集时间 < 30秒
-
-## 🚨 风险提示
-
-1. **反爬策略变化**：小红书可能随时调整 DOM 结构或增加反爬措施
-2. **评论加载时机**：动态加载的评论可能需要更长等待时间
-3. **图片防盗链**：图片 URL 可能短期有效，需要及时下载
-
-## 📝 相关文档
-
-- `container-library/xiaohongshu/README.md` - 容器定义
-- `modules/workflow/blocks/XiaohongshuCrawlerBlock.ts` - 采集逻辑
-- `task.md` - 任务追踪
-- `AGENTS.md` - 架构规则
-- `docs/xiaohongshu-workflow-summary.md` - 实施总结

package/docs/xiaohongshu-quickstart.md

@@ -1,73 +0,0 @@
-# 小红书采集快速开始（新架构）
-
-## 1. 安装与检查
-
-```bash
-npm install
-npm run build:services
-node scripts/xiaohongshu/install.mjs --check
-```
-
-## 2. 登录准备（必须）
-
-首次运行建议先在可视模式完成登录。
-
-```bash
-node scripts/xiaohongshu/phase1-boot.mjs --profile xiaohongshu-batch-1 --headless false
-```
-
-## 3. 执行全流程
-
-### 方式 A：编排入口（推荐）
-
-```bash
-node scripts/xiaohongshu/phase-orchestrate.mjs \
-  --mode phase1-phase2-unified \
-  --profile xiaohongshu-batch-1 \
-  --keyword "工作服定制" \
-  --target 50 \
-  --env debug \
-  --headless false
-```
-
-### 方式 B：仅运行 unified（autoscript）
-
-```bash
-node scripts/xiaohongshu/phase-unified-harvest.mjs \
-  --profile xiaohongshu-batch-1 \
-  --keyword "工作服定制" \
-  --max-notes 50 \
-  --do-comments true \
-  --do-likes true \
-  --like-keywords "真敬业" \
-  --headless false
-```
-
-## 4. 查看进度与状态
-
-```bash
-# 状态摘要
-node scripts/xiaohongshu/state.mjs show --keyword "工作服定制" --env debug
-
-# 状态 JSON
-node scripts/xiaohongshu/state.mjs show --keyword "工作服定制" --env debug --json
-```
-
-## 5. 输出目录
-
-```text
-~/.webauto/download/xiaohongshu/{env}/{keyword}/
-├── phase2-links.jsonl
-├── .collect-state.json
-├── run*.log / run-events*.jsonl
-└── {noteId}/
-    ├── README.md
-    ├── comments.md
-    └── images/
-```
-
-## 注意事项
-
-- 详情页必须通过页面点击进入，禁止 URL 直跳（避免 `xsec_token` 风险）。
-- 调试阶段建议 `--headless false`，便于观察容器匹配与动画时序。
-- 若需要仅采集链接，可单独运行 `phase2-collect.mjs`。

package/docs/xiaohongshu-workflow-summary.md

@@ -1,227 +0,0 @@
-# 小红书 Workflow 实施总结
-
-## ✅ 已完成工作
-
-### 1. 容器库架构
-根据 `container-library/xiaohongshu/README.md`，完整实现了以下容器：
-
-#### 根容器
-- `xiaohongshu_search`: 搜索结果页 (`.feeds-page`)
-- `xiaohongshu_detail`: 笔记详情页 (`.note-detail-mask`)
-- `xiaohongshu_login`: 登录页
-- `xiaohongshu_home`: 主页/推荐流
-
-#### 搜索页容器层次
-```
-xiaohongshu_search/
-├── login_anchor/          # 登录锚点
-├── search_bar/            # 搜索框
-└── search_result_list/    # 结果列表
-    └── search_result_item/  # 单个结果项
-```
-
-**search_result_item 核心能力**:
-- `extract`: 提取 title/link/detail_url/image/text/note_id/xsec_token
-- `navigate`: 直接读取 `a[href*='/explore/']` 并执行 `window.location.href`
-- `click`: 点击图片获取带 xtoken 的 URL
-
-#### 详情页容器层次
-```
-xiaohongshu_detail/
-├── login_anchor/
-└── modal_shell/           # 详情模态框 (.note-detail-mask)
-    ├── header/            # 作者信息
-    ├── content/           # 正文
-    ├── gallery/           # 图片区域
-    └── comment_section/   # 评论区域
-        ├── show_more_button/  # 展开更多回复
-        ├── comment_item/      # 评论项
-        ├── end_marker/        # "THE END" 标记
-        └── empty_state/       # 无评论状态
-```
-
-**comment_section 核心能力**:
-- `scroll`: 向下滚动加载更多评论
-- `find-child`: 查找并触发 `show_more_button` 的自动点击
-- 自动检测 `end_marker` 和 `empty_state` 判断评论加载完成
-
-### 2. Workflow Block 实现
-
-#### XiaohongshuCrawlerBlock
-完整实现的主采集 Block，位于 `modules/workflow/blocks/XiaohongshuCrawlerBlock.ts`:
-
-**核心功能**:
-1. **登录守护**: `ensureLoginState()` - 检测登录页并等待人工登录
-2. **搜索管理**: `runSearch()` + `ensureSearchPageContext()`
-3. **列表采集**: `collectSearchItems()` - 基于容器树提取搜索结果
-4. **详情导航**: `openDetailFromItem()` - 使用 `navigate` operation
-5. **评论展开**: `scrollComments()` - 自动滚动并触发展开按钮
-6. **数据提取**: `collectDetailData()` - 提取header/content/gallery/comments
-7. **图片下载**: `saveNoteData()` - 保存 Markdown + 图片
-8. **去重机制**: 基于已存在目录的 note_id 去重
-
-**数据流**:
-```
-搜索页 → match SEARCH_ROOT → find SEARCH_LIST → extract SEARCH_ITEM
-  ↓
-navigate → wait DETAIL_ROOT → find MODAL_SHELL
-  ↓
-extract HEADER/CONTENT/GALLERY → scroll COMMENT_SECTION → extract COMMENT_ITEM
-  ↓
-save Markdown + images → close modal → back to search
-```
-
-### 3. Debug 脚本（新增）
-
-创建了3个原子化调试脚本：
-
-#### scripts/debug-xhs-status.mjs
-- 获取当前 URL
-- 截图当前页面
-- 分析 DOM 摘要（`.note-item`、`#search-input`、登录锚点）
-- 高亮关键元素
-
-#### scripts/debug-xhs-search.mjs
-- 确保在小红书页面
-- 高亮搜索框
-- 随机选择关键字（oppo小平板/手机膜/雷军/小米/华为/鸿蒙）
-- 执行搜索并等待结果稳定
-
-#### scripts/debug-xhs-detail.mjs
-- 获取列表第一个笔记
-- 高亮并打开详情页
-- 检查详情页加载（Modal/Title/Comments）
-- 自动展开评论（滚动 + 点击展开按钮）
-- 统计评论数量和状态
-
-### 4. Workflow 定义
-`modules/workflow/definitions/xiaohongshu-collect-workflow.ts`:
-```typescript
-{
-  id: 'xiaohongshu-collect',
-  name: '小红书关键词采集',
-  steps: [
-    { blockName: 'StartBrowserService', ... },
-    { blockName: 'EnsureSession', ... },
-    { blockName: 'XiaohongshuCrawlerBlock', ... }
-  ]
-}
-```
-
-## 📋 调试计划（按 task.md）
-
-### Step 1: 状态诊断 ✅
-```bash
-node scripts/debug-xhs-status.mjs
-```
-验证：
-- 当前 URL
-- DOM 结构
-- 关键元素高亮
-
-### Step 2: 搜索验证 ⏳
-```bash
-node scripts/debug-xhs-search.mjs
-```
-验证：
-- 搜索框定位
-- 关键字轮换
-- 结果加载
-
-### Step 3: 详情页交互 ⏳
-```bash
-node scripts/debug-xhs-detail.mjs
-```
-验证：
-- 详情页打开
-- 评论展开
-- 数据完整性
-
-### Step 4: 完整 Workflow ⏳
-```bash
-# 方式1: 直接调用 Block
-node -e "import('./modules/workflow/blocks/XiaohongshuCrawlerBlock.ts').then(m => m.execute({ sessionId: 'xiaohongshu_fresh', keyword: 'oppo小平板', targetCount: 5 }))"
-
-# 方式2: 通过 Workflow Runner
-node scripts/run-xiaohongshu-workflow.ts
-```
-
-## 🔧 技术栈
-
-- **统一 API**: `http://127.0.0.1:7701` (HTTP/WS/Bus)
-- **Browser Service**: `http://127.0.0.1:7704` + `ws://127.0.0.1:8765`
-- **容器操作**: `/v1/container/<containerId>/execute`
-- **Controller 动作**: `/v1/controller/action`
-- **事件总线**: `ws://127.0.0.1:7701/bus` (订阅 `container:*`/`ui:*`)
-
-## 🚨 已知问题与对策
-
-### 1. Navigation Context Destroyed
-**问题**: 页面跳转时脚本执行被中断
-**对策**: 
-- `waitForDetailContext()` - 轮询等待详情容器出现
-- `ensureSearchPageContext()` - 确保回到搜索页后重新匹配
-
-### 2. 评论展开时机
-**问题**: 动态加载的评论需要滚动触发
-**对策**:
-- `scrollComments()` - 多轮滚动 + `find-child` 触发 `show_more_button`
-- 检测 `end_marker` 和 `empty_state` 判断结束
-
-### 3. 图片下载反爬
-**问题**: 小红书图片需要 UA + Cookie
-**对策**:
-- `fetchBrowserHeaders()` - 读取浏览器 UA 和 Cookie
-- 重试机制（最多3次）
-
-## 📁 输出结构
-
-```
-~/.webauto/download/xiaohongshu/{keyword}/
-  ├── {title}_{noteId}/
-  │   ├── content.md
-  │   └── images/
-  │       ├── 1.jpg
-  │       ├── 2.jpg
-  │       └── ...
-  └── ...
-```
-
-### Markdown 格式
-```markdown
-# 标题
-
-- **关键字**: oppo小平板
-- **作者**: xxx | [主页](link)
-- **Note ID**: 12345
-- **评论统计**: 10 条 / 结尾标记：是 / 空状态：否
-
-## 正文
-（正文内容）
-
-## 图片
-![](./images/1.jpg)
-![](./images/2.jpg)
-
-## 评论（10）
-### 1. 用户名 (userId)
-- 时间：2025-01-05
-
-评论内容...
-```
-
-## 🎯 下一步
-
-1. **运行 Debug 脚本**: 验证当前 Session 状态
-2. **调整容器定义**: 根据实际 DOM 微调选择器
-3. **测试完整流程**: 5条数据小规模测试
-4. **优化性能**: 减少等待时间、提高提取成功率
-5. **扩展 Block**: 支持更多操作（如批量导出、数据分析）
-
-## 📝 参考文档
-
-- `container-library/xiaohongshu/README.md` - 容器定义规范
-- `modules/workflow/blocks/XiaohongshuCrawlerBlock.ts` - 主采集逻辑
-- `task.md` - 任务追踪与调试计划
-- `AGENTS.md` - 架构设计原则
-

package/modules/container-registry/tests/container-registry.test.ts

@@ -1,16 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { ContainerRegistry } from '../src/index.js';
-
-test('getContainersForUrl returns known container', () => {
-  const registry = new ContainerRegistry();
-  const containers = registry.getContainersForUrl('https://weibo.com/');
-  assert.ok(containers.weibo_main_page, 'should include weibo_main_page');
-});
-
-test('listSites contains weibo entry', () => {
-  const registry = new ContainerRegistry();
-  const sites = registry.listSites();
-  const hasWeibo = sites.some((site) => site.key.includes('weibo'));
-  assert.ok(hasWeibo, 'should list weibo site');
-});

package/modules/logging/tests/logging.test.ts

@@ -1,38 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import os from 'node:os';
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { run as runCli } from '../src/cli.js';
-
-async function withTempLog(content: string, fn: (file: string) => Promise<void>) {
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'logging-test-'));
-  const file = path.join(dir, 'sample.log');
-  await fs.writeFile(file, content, 'utf-8');
-  try {
-    await fn(file);
-  } finally {
-    await fs.rm(dir, { recursive: true, force: true });
-  }
-}
-
-test('logging cli stream returns tail lines', async () => {
-  await withTempLog('line1\nline2\nline3\n', async (file) => {
-    const result = await runCli(['stream', '--file', file, '--lines', '2']);
-    assert.equal(result.success, true);
-    assert.deepEqual(result.data.lines, ['line2', 'line3']);
-  });
-});
-
-test('logging cli flush can truncate file', async () => {
-  await withTempLog('foo\nbar\n', async (file) => {
-    const flush = await runCli(['flush', '--file', file, '--truncate', 'false']);
-    assert.equal(flush.success, true);
-    assert.equal(flush.data.lines.length, 2);
-
-    const flushTruncate = await runCli(['flush', '--file', file]);
-    assert.equal(flushTruncate.success, true);
-    const stats = await fs.stat(file);
-    assert.equal(stats.size, 0);
-  });
-});

package/modules/operations/tests/operations.test.ts

@@ -1,22 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { run as runCli } from '../src/cli.js';
-
-test('operations cli list returns registered operations', async () => {
-  const result = await runCli(['list']);
-  assert.equal(result.success, true);
-  assert.ok(result.data.some((op: any) => op.id === 'highlight'));
-  assert.ok(result.data.some((op: any) => op.id === 'scroll'));
-});
-
-test('operations cli run works with mock page context', async () => {
-  const result = await runCli(['run', '--op', 'highlight', '--config', '{"selector":"#app"}']);
-  assert.equal(result.success, true);
-  assert.equal(result.data.mock, true);
-});
-
-// Skipped: robotjs has been removed from dependencies
-test.skip('operations cli run supports system mouse', async () => {
-  const result = await runCli(['run', '--op', 'system:mouse-move', '--config', '{"x":10,"y":20}']);
-  assert.equal(result.success, true);
-});