chore: import zh skill active-research
This commit is contained in:
wehub-skill-sync
@@ -0,0 +1,9 @@
|
||||
# WeHub 来源说明
|
||||
|
||||
- Skill 名称：`active-research`
|
||||
- 中文类目：自主深度研究
|
||||
- 上游仓库：`actionbook__actionbook`
|
||||
- 上游路径：`skills/active-research/SKILL.md`
|
||||
- 上游链接：https://github.com/actionbook/actionbook/blob/HEAD/skills/active-research/SKILL.md
|
||||
- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
|
||||
- 原作者、版权和许可证信息以上游仓库为准
|
||||
@@ -0,0 +1,794 @@
|
||||
---
|
||||
name: active-research
|
||||
description: 深度研究与分析工具。能够针对任何主题、领域、论文或技术生成全面的 HTML 报告。增强的高级浏览器自动化功能包括：SPA 处理、网络空闲等待、批量操作、隐身浏览和智能页面分析。当用户要求研究、分析、调查、深入探索或生成任何主题的报告时使用。
|
||||
exclude_tools: group:web
|
||||
triggers: research, deep-dive, investigate, analyze topic, deep research, generate report
|
||||
force_tool_turns: 10
|
||||
---
|
||||
|
||||
# Active Research
|
||||
|
||||
分析任何主题、领域或论文，并使用 **Actionbook Browser** 生成精美的 HTML 报告——支持 SPA 感知导航、网络空闲检测、批量操作和智能页面分析。
|
||||
|
||||
## 增强的浏览器能力
|
||||
|
||||
| 能力 | 描述 |
|
||||
|------------|-------------|
|
||||
| 页面加载等待 | `wait-idle`——监控 fetch/XHR 直至网络稳定 |
|
||||
| SPA 内容 | `wait-fn`——等待 JS 条件满足后再提取 |
|
||||
| 页面理解 | `snapshot --filter interactive --max-tokens N`——聚焦、节省预算 |
|
||||
| 弹窗拦截 | `--auto-dismiss-dialogs`——自动处理 alert/confirm/prompt |
|
||||
| 加载速度 | `--block-images`——跳过图片以加快文本提取 |
|
||||
| 页面稳定性 | `--no-animations`——冻结 CSS 过渡动画 |
|
||||
| 错误检测 | `console --level error`——检查页面问题 |
|
||||
| 多步骤表单 | `batch`——单次调用中执行多个操作 |
|
||||
| 元素调试 | `info <selector>`——检查可见性、位置、属性 |
|
||||
| 变更追踪 | `snapshot --diff`——仅查看变化内容 |
|
||||
| 反检测 | `--stealth` + `fingerprint rotate` 用于受保护站点 |
|
||||
| 认证管理 | `storage set`——注入 JWT/令牌以访问受限内容 |
|
||||
| 一次性抓取 | `browser fetch <url>`——导航+等待+提取+关闭，一条命令完成 |
|
||||
| 静态页面速度 | `--lite`——优先 HTTP，仅在需要时回退到浏览器 |
|
||||
| 反爬取 URL | `--rewrite-urls`——将 x.com 重写为 xcancel.com，reddit 重写为 old.reddit |
|
||||
| 等待调优 | `--wait-hint`——域名感知等待（fast/normal/slow/heavy） |
|
||||
| 日志关联 | `--session-tag`——为所有操作打标签以便调试 |
|
||||
|
||||
## 用法
|
||||
|
||||
```
|
||||
/active-research <topic>
|
||||
/active-research <topic> --output ./reports/my-report.json
|
||||
```
|
||||
|
||||
或者直接告诉 Claude：「Research XXX and generate a report」
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 是否必需 | 默认值 | 描述 |
|
||||
|-----------|----------|---------|-------------|
|
||||
| `topic` | 是 | - | 要研究的主题（任意文本） |
|
||||
| `--output` | 否 | `./output/<topic-slug>.json` | JSON 报告的输出路径 |
|
||||
|
||||
### 主题检测
|
||||
|
||||
| 模式 | 类型 | 策略 |
|
||||
|---------|------|----------|
|
||||
| `arxiv:XXXX.XXXXX` | 论文 | **arXiv Advanced Search** + ar5iv 深度阅读 |
|
||||
| `doi:10.XXX/...` | 论文 | 解析 DOI，然后通过 **arXiv Advanced Search** 查找相关工作 |
|
||||
| 学术关键词（paper, research, model, algorithm） | 学术主题 | **arXiv Advanced Search** + Google 搜索非学术来源 |
|
||||
| URL | 特定页面 | 获取并分析该页面 |
|
||||
| 通用文本 | 主题研究 | Google 搜索 + 必要时使用 arXiv Advanced Search |
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
|
||||
│ Claude │────▶│ Actionbook │────▶│ Web Pages │────▶│ Extract │
|
||||
│ Code │ │ Browser │ │ (multiple) │ │ Content │
|
||||
└──────────┘ └──────────────┘ └──────────────┘ └─────┬────┘
|
||||
│ │ wait-idle │ │ SPA / dynamic │ │
|
||||
│ │ batch ops │ │ protected │ │
|
||||
│ │ --stealth │ │ mobile-only │ │
|
||||
│ │ snapshot │ └───────────────┘ │
|
||||
│ └──────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
├─────────▶│ Actionbook │ │ arXiv Adv. │ │
|
||||
│ │ search/get │────▶│ Search Form │───────────▶│
|
||||
│ │ (selectors) │ │ (40+ fields) │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
┌──────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ Open in │◀────│ json-ui │◀────│ Write JSON │◀───────────┘
|
||||
│ Browser │ │ render │ │ Report │ Synthesize
|
||||
└──────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
## 必须使用 Actionbook CLI
|
||||
|
||||
**始终使用 `actionbook browser` 命令进行网页浏览。绝不使用任何其他方法访问网络：**
|
||||
|
||||
- **绝不**通过 bash 使用 `curl`、`wget`、`httpie` 或任何 HTTP CLI 工具
|
||||
- **绝不**通过 bash 使用 `python -c "import requests"` 或任何脚本语言的 HTTP 库
|
||||
- **绝不**使用 WebFetch 或 WebSearch 工具
|
||||
- **只使用** `actionbook browser` 和 `actionbook search`/`actionbook get` 命令
|
||||
|
||||
如果需要获取网页内容，**推荐**路径是：`actionbook browser fetch <url> --format text --json`（一次性完成）。
|
||||
对于交互式多步骤工作流，请使用：`actionbook browser open <url>` → `actionbook browser wait-idle` → `actionbook browser text`。
|
||||
|
||||
## 浏览器标志——研究默认值
|
||||
|
||||
**关键：在研究场景下打开浏览器时，始终使用这些标志。**
|
||||
|
||||
```bash
|
||||
# 推荐：一次性抓取（I1）——自动处理 open+wait+extract+close
|
||||
actionbook --block-images --rewrite-urls browser fetch "<url>" --format text --json
|
||||
|
||||
# 对于交互式多步骤工作流，使用显式 open：
|
||||
actionbook --block-images --auto-dismiss-dialogs --no-animations --rewrite-urls browser open "<url>"
|
||||
```
|
||||
|
||||
| 标志 | 原因 |
|
||||
|------|-----|
|
||||
| `--block-images` | 跳过图片下载——文本提取速度提升 2-5 倍 |
|
||||
| `--auto-dismiss-dialogs` | 防止 alert/confirm/prompt 阻塞自动化 |
|
||||
| `--no-animations` | 冻结 CSS 动画——快照稳定，无时序问题 |
|
||||
| `--rewrite-urls` | 将 x.com 重写为 xcancel.com，reddit 重写为 old.reddit 以避免反爬虫拦截 |
|
||||
| `--wait-hint <hint>` | 域名感知等待：`instant`、`fast`、`normal`、`slow`、`heavy` 或毫秒值 |
|
||||
| `--session-tag <tag>` | 为所有操作打标签以便日志关联和调试 |
|
||||
| `--lite`（仅 fetch） | 优先尝试 HTTP，对静态页面跳过浏览器（Wikipedia、文档、博客） |
|
||||
|
||||
对于有反爬虫保护的站点，添加 `--stealth`：
|
||||
```bash
|
||||
actionbook --block-images --auto-dismiss-dialogs --no-animations --stealth --rewrite-urls browser open "<url>"
|
||||
```
|
||||
|
||||
## 导航模式——始终遵循
|
||||
|
||||
**选项 A：一次性抓取（只读页面提取推荐方式）：**
|
||||
|
||||
```bash
|
||||
# 单条命令：导航 → 等待（域名感知）→ 提取 → 关闭
|
||||
actionbook --block-images --rewrite-urls browser fetch "<url>" --format text --json
|
||||
# 对于静态页面（Wikipedia、文档、博客），添加 --lite 完全跳过浏览器：
|
||||
actionbook --rewrite-urls browser fetch "<url>" --format text --lite --json
|
||||
# 无障碍树：
|
||||
actionbook --block-images --rewrite-urls browser fetch "<url>" --format snapshot --max-tokens 2000 --json
|
||||
```
|
||||
|
||||
**选项 B：交互式多步骤模式（用于表单、点击、多页面流程）：**
|
||||
|
||||
```bash
|
||||
# 步骤 1：导航
|
||||
actionbook browser open "<url>" # 或：goto, click a link
|
||||
|
||||
# 步骤 2：等待加载（v2 中为强制步骤）
|
||||
actionbook browser wait-idle # 等待 fetch/XHR 稳定
|
||||
|
||||
# 步骤 3：提取内容
|
||||
actionbook browser text [selector] # 提取文本
|
||||
# 或
|
||||
actionbook browser snapshot --filter interactive --max-tokens 500 # 理解页面结构
|
||||
```
|
||||
|
||||
**为什么 `wait-idle` 至关重要：**
|
||||
- SPA（React、Vue、Next.js）在初始 HTML 之后通过 fetch/XHR 加载内容
|
||||
- 如果不等待，`text` 返回空或不完整的内容
|
||||
- `wait-idle` 监控所有待处理的网络请求，等待网络静默持续 500ms
|
||||
|
||||
**对于在网络稳定后动态加载内容的页面：**
|
||||
```bash
|
||||
actionbook browser wait-idle
|
||||
actionbook browser wait-fn "document.querySelector('.results')" # 等待特定元素
|
||||
actionbook browser text ".results"
|
||||
```
|
||||
|
||||
## 完整工作流
|
||||
|
||||
> **提醒：** 本工作流中的每次网络访问都必须使用 `actionbook browser` 命令。
|
||||
> 使用 `curl`、`wget`、`python requests` 或任何其他 HTTP 工具**严格禁止**。
|
||||
> bash 工具应**仅**用于 `actionbook` CLI 命令和本地文件操作（json-ui render、`open`）。
|
||||
|
||||
### 步骤 1：规划搜索策略
|
||||
|
||||
根据主题，从不同角度生成 5-8 条搜索查询：
|
||||
- 核心定义 / 概述
|
||||
- 最新进展 / 新闻
|
||||
- 技术细节 / 实现
|
||||
- 比较 / 替代方案
|
||||
- 专家观点 / 分析
|
||||
- 使用场景 / 应用
|
||||
|
||||
**搜索顺序——始终先查询 Actionbook API，再进行搜索：**
|
||||
|
||||
| 步骤 | 操作 | 原因 |
|
||||
|------|--------|-----|
|
||||
| **步骤 2（第一步）** | **查询 Actionbook API** | 在浏览之前获取 arXiv、ar5iv 和其他已知站点的已验证选择器。 |
|
||||
| **步骤 3（第二步）** | **arXiv Advanced Search** | 使用 Actionbook 选择器进行多字段、过滤后的学术搜索。 |
|
||||
| **步骤 4（第三步）** | Google / Bing 搜索 | 用博客、新闻、代码、讨论、非学术来源进行补充。 |
|
||||
|
||||
### 步骤 2：查询 Actionbook API 获取选择器（始终优先执行此步骤）
|
||||
|
||||
**在浏览任何 URL 之前**，先查询 Actionbook 的索引选择器。
|
||||
|
||||
```bash
|
||||
# 按域名搜索已索引的操作
|
||||
actionbook search "<keywords>" -d "<domain>"
|
||||
|
||||
# 获取特定页面的详细选择器
|
||||
actionbook get "<domain>:/<path>:<area>"
|
||||
```
|
||||
|
||||
**对研究有用的预索引站点：**
|
||||
|
||||
| 站点 | area_id | 关键选择器 |
|
||||
|------|---------|---------------|
|
||||
| arXiv Advanced Search | `arxiv.org:/search/advanced:default` | **40+ 个选择器**：字段选择、词条输入、分类复选框、日期范围筛选 |
|
||||
| ar5iv 论文 | `ar5iv.labs.arxiv.org:/html/{paper_id}:default` | `h1.ltx_title_document`、`div.ltx_authors`、`div.ltx_abstract`、`section.ltx_section` |
|
||||
| Google Scholar | `scholar.google.com:/:default` | `#gs_hdr_tsi`（搜索）、`#gs_hdr_tsb`（提交） |
|
||||
| arXiv 首页 | `arxiv.org:/:default` | 在 240 万+ 篇文章中进行全局搜索 |
|
||||
|
||||
**对于你计划访问的任何 URL**，运行 `actionbook search "<keywords>" -d "<domain>"` 检查它是否已被索引。
|
||||
|
||||
### 步骤 3：arXiv 搜索（优先 URL 方式，表单作为后备）
|
||||
|
||||
**经验教训：通过浏览器自动化提交 arXiv 表单不可靠。应使用基于 URL 的搜索作为主要方法。**
|
||||
|
||||
**选项 A：基于 URL 的搜索（主要方式——最可靠）：**
|
||||
|
||||
```bash
|
||||
# 简单关键词搜索
|
||||
actionbook --block-images --auto-dismiss-dialogs --no-animations browser open "https://arxiv.org/search/?query=large+language+model+agent&searchtype=all"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text "#main-container"
|
||||
|
||||
# 带筛选条件的高级 URL 搜索
|
||||
# searchtype: all, title, author, abstract
|
||||
# start: 结果偏移量（0, 50, 100, ...）
|
||||
actionbook browser open "https://arxiv.org/search/?query=Rust+machine+learning&searchtype=all&start=0"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text "#main-container"
|
||||
```
|
||||
|
||||
**搜索策略：从宽泛开始，再逐步收窄：**
|
||||
1. 首次搜索：宽泛词条（例如 `"Rust" "machine learning"`）——目标是 50+ 条结果
|
||||
2. 如果结果太少（< 10 条）：进一步放宽范围，移除日期/分类筛选
|
||||
3. 如果结果太多（> 200 条）：添加更具体的词条，使用 `searchtype=title`
|
||||
4. 尝试 2-3 种不同的查询角度（例如框架名称、使用场景、基准测试）
|
||||
|
||||
**选项 B：通过 batch 进行表单交互（后备方案——当 URL 搜索不足时使用）：**
|
||||
|
||||
```bash
|
||||
# 使用研究标志打开 arXiv
|
||||
actionbook --block-images --auto-dismiss-dialogs --no-animations browser open "https://arxiv.org/search/advanced"
|
||||
actionbook browser wait-idle
|
||||
|
||||
# 使用 batch 处理表单——往返次数更少，更可靠
|
||||
cat <<'EOF' | actionbook browser batch --delay 150
|
||||
{
|
||||
"actions": [
|
||||
{"kind": "click", "selector": "#terms-0-field"},
|
||||
{"kind": "click", "selector": "option[value='title']"},
|
||||
{"kind": "type", "selector": "#terms-0-term", "text": "large language model agent"},
|
||||
{"kind": "click", "selector": "#classification-computer_science"},
|
||||
{"kind": "click", "selector": "#date-filter_by-3"},
|
||||
{"kind": "type", "selector": "#date-from_date", "text": "2025-01-01"},
|
||||
{"kind": "type", "selector": "#date-to_date", "text": "2026-02-23"},
|
||||
{"kind": "click", "selector": "button:has-text('Search'):nth(2)"}
|
||||
],
|
||||
"stopOnError": true
|
||||
}
|
||||
EOF
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text "#main-container"
|
||||
|
||||
# 如果批量表单提交失败（页面重新显示表单而非结果）：
|
||||
# → 立即回退到选项 A 的 URL 搜索
|
||||
# → 不要重试表单——这是在浪费时间
|
||||
```
|
||||
|
||||
**arXiv 搜索能力（来自索引选择器——用于选项 B）：**
|
||||
|
||||
| 能力 | 选择器 |
|
||||
|------------|----------|
|
||||
| 搜索字段（标题/作者/摘要） | `#terms-0-field` 选择 |
|
||||
| 搜索词条 | `#terms-0-term` 输入 |
|
||||
| 添加布尔词条 | `button "Add another term +"` |
|
||||
| 筛选：计算机科学 | `#classification-computer_science` |
|
||||
| 筛选：物理、数学等 | `#classification-physics`、`#classification-mathematics` |
|
||||
| 日期：过去 12 个月 | `#date-filter_by-1` 单选 |
|
||||
| 日期：特定年份 | `#date-filter_by-2` 单选 + `#date-year` |
|
||||
| 日期：自定义范围 | `#date-filter_by-3` 单选 + `#date-from_date` / `#date-to_date` |
|
||||
| 显示摘要 | `#abstracts-0` 单选 |
|
||||
|
||||
### 步骤 4：用 Google / Bing 搜索补充
|
||||
|
||||
```bash
|
||||
# 通过 Google 搜索（使用 wait-idle 等待 SPA 结果）
|
||||
actionbook browser open "https://www.google.com/search?q=<encoded_query>"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text "#search"
|
||||
|
||||
# 或通过 Bing 搜索
|
||||
actionbook browser open "https://www.bing.com/search?q=<encoded_query>"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text "#b_results"
|
||||
```
|
||||
|
||||
解析搜索结果以提取 URL。对于每个发现的 URL，查询 Actionbook API 检查是否已被索引。
|
||||
|
||||
**关键：URL 处理规则（来自生产环境经验）**
|
||||
|
||||
1. **绝不手动从搜索摘要中构造 URL。** 许多 Google 摘要 URL 被截断或重新格式化。应改为：
|
||||
- 使用 `actionbook browser snapshot --filter interactive` 查找实际链接元素
|
||||
- 直接点击链接：`actionbook browser click "a[href*='domain.com']"`
|
||||
- 或从 snapshot 引用中提取 href
|
||||
|
||||
2. **预计 20-30% 的 URL 会失效。** 实际中，约 20 个 URL 中有 5 个返回 404。按如下方式处理：
|
||||
```bash
|
||||
actionbook browser open "<url>"
|
||||
actionbook browser wait-idle
|
||||
# 检查页面是否为 404 或错误页面
|
||||
actionbook browser wait-fn "!document.title.includes('404') && !document.title.includes('Not Found')" --timeout 3000
|
||||
# 如果超时 → 页面失效，立即跳过。不要重试。
|
||||
```
|
||||
|
||||
3. **从 Google 摘要中抢救信息。** 如果 URL 已失效但 Google 摘要包含有用信息：
|
||||
- 你已经提取的摘要文本本身就是有效数据
|
||||
- 在报告中加以使用，并注明来源已不可用
|
||||
- 在替代站点（archive.org、缓存版本）上搜索相同内容
|
||||
|
||||
4. **使用 4 条以上多样化的搜索查询。** 不要依赖单一搜索角度：
|
||||
- 查询 1：核心主题概述（例如「Rust AI ecosystem 2026」）
|
||||
- 查询 2：特定框架/工具（例如「Candle vs Burn Rust ML framework」）
|
||||
- 查询 3：使用场景/基准测试（例如「Rust LLM inference performance benchmark」）
|
||||
- 查询 4：最新新闻/进展（例如「Rust machine learning latest 2026」）
|
||||
- 查询 5：社区/生态（例如「Rust AI agent framework comparison」）
|
||||
|
||||
### 步骤 5：深度阅读来源
|
||||
|
||||
**推荐：使用 `browser fetch` 进行一次性页面提取（处理等待 + 提取 + 清理）：**
|
||||
|
||||
```bash
|
||||
# 快速文本提取（最常见）
|
||||
actionbook --block-images --rewrite-urls browser fetch "<url>" --format text --json
|
||||
|
||||
# 静态页面（Wikipedia、文档、博客）——完全跳过浏览器
|
||||
actionbook --rewrite-urls browser fetch "<url>" --format text --lite --json
|
||||
|
||||
# 页面结构分析
|
||||
actionbook --block-images --rewrite-urls browser fetch "<url>" --format snapshot --max-tokens 2000 --json
|
||||
|
||||
# 带 token 预算的 LLM 上下文管理
|
||||
actionbook --block-images --rewrite-urls browser fetch "<url>" --format text --max-tokens 4000 --json
|
||||
```
|
||||
|
||||
**对于交互式工作流（表单、点击），回退到多步骤：**
|
||||
|
||||
```bash
|
||||
actionbook browser open "<url>"
|
||||
actionbook browser wait-idle # 强制：等待网络
|
||||
actionbook browser text # 整页文本（后备方案）
|
||||
actionbook browser text "<selector>" # 如已索引，使用 Actionbook 选择器
|
||||
```
|
||||
|
||||
**如果页面内容似乎不完整，进行调试：**
|
||||
|
||||
```bash
|
||||
# 检查可能阻止渲染的 JS 错误
|
||||
actionbook browser console --level error
|
||||
|
||||
# 检查特定元素是否存在
|
||||
actionbook browser wait-fn "document.querySelector('.content')" --timeout 5000
|
||||
|
||||
# 检查元素属性
|
||||
actionbook browser info ".content"
|
||||
```
|
||||
|
||||
**对于 arXiv 论文**，按以下顺序尝试来源：
|
||||
|
||||
```bash
|
||||
# 1. arXiv 摘要（最可靠）——使用 fetch
|
||||
actionbook --block-images browser fetch "https://arxiv.org/abs/<arxiv_id>" --format text --json
|
||||
|
||||
# 2. HuggingFace 论文页面
|
||||
actionbook --block-images browser fetch "https://huggingface.co/papers/<arxiv_id>" --format text --json
|
||||
|
||||
# 3. ar5iv HTML（结构化，但新论文上可能失败）——使用 --lite 获取静态 HTML
|
||||
actionbook browser fetch "https://ar5iv.org/html/<arxiv_id>" --format text --lite --json
|
||||
# 注意：如果内容太短，ar5iv 未渲染。回退。
|
||||
|
||||
# 4. GitHub 仓库（来自搜索结果）——使用 fetch
|
||||
actionbook --block-images browser fetch "<github_repo_url>" --format text --json
|
||||
```
|
||||
|
||||
**对于受保护站点（Cloudflare、反爬虫检测）——使用隐身模式交互：**
|
||||
|
||||
```bash
|
||||
actionbook --stealth --block-images --auto-dismiss-dialogs --rewrite-urls browser open "<protected_url>"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text
|
||||
```
|
||||
|
||||
**对于仅移动端内容：**
|
||||
|
||||
```bash
|
||||
actionbook browser emulate iphone-14
|
||||
actionbook browser open "<url>"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text
|
||||
```
|
||||
|
||||
**对于 Google Scholar**（被 Actionbook 索引）：
|
||||
|
||||
```bash
|
||||
actionbook browser open "https://scholar.google.com"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser click "#gs_hdr_tsi"
|
||||
actionbook browser type "#gs_hdr_tsi" "<query>"
|
||||
actionbook browser click "#gs_hdr_tsb"
|
||||
actionbook browser wait-idle
|
||||
actionbook browser text "#gs_res"
|
||||
```
|
||||
|
||||
**对于未索引的站点**，使用 snapshot 发现结构：
|
||||
|
||||
```bash
|
||||
actionbook --block-images browser fetch "<url>" --format snapshot --max-tokens 800 --json
|
||||
```
|
||||
|
||||
### 步骤 6：综合研究结果
|
||||
|
||||
将收集的信息组织成一份条理清晰的报告：
|
||||
1. 概述 / 执行摘要
|
||||
2. 主要发现
|
||||
3. 详细分析
|
||||
4. 支撑数据 / 证据
|
||||
5. 影响 / 意义
|
||||
6. 来源
|
||||
|
||||
### 步骤 7：生成 json-ui JSON 报告
|
||||
|
||||
按照 `@actionbookdev/json-ui` 模式编写 JSON 文件。使用 Write 工具。
|
||||
|
||||
**输出路径：** `./output/<topic-slug>.json`（或用户指定的 `--output` 路径）
|
||||
|
||||
### 步骤 8：渲染 HTML
|
||||
|
||||
**关键：在放弃之前，你必须尝试所有后备方法。不要在第一次失败时就停止。**
|
||||
|
||||
**重要：始终对 JSON_FILE 和 HTML_FILE 使用绝对路径。**
|
||||
|
||||
逐一尝试每种方法，直到有一种成功：
|
||||
|
||||
```bash
|
||||
# 方法 1：Monorepo 绝对路径（如果在 actionbook 项目内，最可靠）
|
||||
node "$(git rev-parse --show-toplevel)/packages/json-ui/dist/cli.js" render /absolute/path/to/report.json -o /absolute/path/to/report.html
|
||||
|
||||
# 方法 2：全局安装（如果用户执行了：cd packages/json-ui && npm link）
|
||||
json-ui render /absolute/path/to/report.json -o /absolute/path/to/report.html
|
||||
|
||||
# 方法 3：npx（如果已发布到 npm）
|
||||
npx @actionbookdev/json-ui render /absolute/path/to/report.json -o /absolute/path/to/report.html
|
||||
```
|
||||
|
||||
**绝不默默放弃。** 如果所有方法都失败，请告知用户：
|
||||
1. JSON 报告保存在 `<path>`
|
||||
2. 要启用 HTML 渲染，请运行：`cd <actionbook-repo>/packages/json-ui && npm link`
|
||||
|
||||
### 步骤 9：在浏览器中打开
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
open <report.html>
|
||||
|
||||
# Linux
|
||||
xdg-open <report.html>
|
||||
```
|
||||
|
||||
### 步骤 10：关闭浏览器
|
||||
|
||||
**完成后始终关闭浏览器：**
|
||||
|
||||
```bash
|
||||
actionbook browser close
|
||||
```
|
||||
|
||||
## 错误恢复模式
|
||||
|
||||
**使用高级浏览器能力进行智能错误恢复：**
|
||||
|
||||
### 模式：页面加载失败
|
||||
|
||||
```bash
|
||||
# 1. 打开页面
|
||||
actionbook browser open "<url>"
|
||||
actionbook browser wait-idle --timeout 15000
|
||||
|
||||
# 2. 检查 JS 错误
|
||||
actionbook browser console --level error
|
||||
# 如果发现错误 → 页面已损坏，跳到下一个来源
|
||||
|
||||
# 3. 检查内容是否已渲染
|
||||
actionbook browser wait-fn "document.body.innerText.length > 100" --timeout 5000
|
||||
# 如果超时 → 内容未渲染，尝试后备方案
|
||||
```
|
||||
|
||||
### 模式：未找到选择器
|
||||
|
||||
```bash
|
||||
# 1. 使用 snapshot 发现实际页面结构
|
||||
actionbook browser snapshot --filter interactive --max-tokens 800
|
||||
|
||||
# 2. 或检查特定区域
|
||||
actionbook browser info "<parent_selector>"
|
||||
# 返回：建议的选择器、可见性、标签信息
|
||||
|
||||
# 3. 调整选择器后重试
|
||||
```
|
||||
|
||||
### 模式：反爬虫检测
|
||||
|
||||
```bash
|
||||
# 1. 如果初始加载返回 CAPTCHA 或访问被拒：
|
||||
actionbook browser close
|
||||
|
||||
# 2. 使用隐身模式重新打开
|
||||
actionbook --stealth --no-animations --auto-dismiss-dialogs browser open "<url>"
|
||||
actionbook browser wait-idle
|
||||
|
||||
# 3. 如果仍然被拦截，轮换指纹
|
||||
actionbook browser fingerprint rotate --os windows
|
||||
actionbook browser open "<url>"
|
||||
actionbook browser wait-idle
|
||||
```
|
||||
|
||||
### 模式：SPA 内容未加载
|
||||
|
||||
```bash
|
||||
# 1. 等待网络
|
||||
actionbook browser wait-idle --idle-time 1000 --timeout 15000
|
||||
|
||||
# 2. 等待特定元素
|
||||
actionbook browser wait-fn "document.querySelector('.results')" --timeout 10000
|
||||
|
||||
# 3. 如果仍然为空，检查控制台
|
||||
actionbook browser console --level error
|
||||
|
||||
# 4. 尝试点击加载触发器
|
||||
actionbook browser snapshot --filter interactive --max-tokens 300
|
||||
# 查找「Load More」、「Show Results」等
|
||||
```
|
||||
|
||||
## 完整错误处理参考
|
||||
|
||||
| 错误 | 恢复策略 |
|
||||
|-------|-------------------|
|
||||
| 浏览器打开失败 | `actionbook browser status`，重试 + 检查 `console --level error` |
|
||||
| 页面加载超时 | `wait-idle --timeout 15000`，然后 `console --level error` 进行诊断 |
|
||||
| **URL 返回 404** | 使用 `wait-fn "!document.title.includes('404')"` 快速检测。**立即跳过，不要重试。** 使用 Google 摘要文本作为备份数据。 |
|
||||
| **arXiv 表单提交失败** | 回退到基于 URL 的搜索：`arxiv.org/search/?query=...&searchtype=all` |
|
||||
| ar5iv 内容截断 | 回退到 arXiv 摘要 + 使用 `wait-fn "document.body.innerText.length > 5000"` 验证 |
|
||||
| 选择器未找到 | 使用 `snapshot --filter interactive` 发现实际结构 |
|
||||
| 动态内容缺失 | `wait-idle` + `wait-fn` 等待特定条件 |
|
||||
| 弹窗警报拦截 | `--auto-dismiss-dialogs` 完全阻止此问题 |
|
||||
| 反爬虫检测 | `--stealth` + `fingerprint rotate` |
|
||||
| 媒体繁重的慢速页面 | `--block-images` 或 `--block-media` 获得 2-5 倍加速 |
|
||||
| CSS 动画干扰 | `--no-animations` 冻结所有过渡 |
|
||||
| json-ui render 崩溃 | 检查 MetricsGrid——`suffix`/`value` 必须是纯字符串 |
|
||||
| `npx json-ui` 404 | 尝试全部 3 种方法（monorepo、全局、npx） |
|
||||
| 无搜索结果 | 从宽泛开始（50+ 条结果），然后收窄。使用 4 种以上查询角度。 |
|
||||
|
||||
**重要：** 即使出现错误，也要在结束前始终运行 `actionbook browser close`。
|
||||
|
||||
## 功能使用检查清单
|
||||
|
||||
**在最终确定研究之前，验证你是否使用了以下能力：**
|
||||
|
||||
| 功能 | 何时使用 | 检查 |
|
||||
|---------|-------------|-------|
|
||||
| `browser fetch` | 只读页面提取（优先于 open+wait+text） | 用于大多数页面读取 |
|
||||
| `--lite` | 静态页面（Wikipedia、文档、博客）——完全跳过浏览器 | 对静态站点添加到 `fetch` |
|
||||
| `--rewrite-urls` | 始终使用（避免 x.com、reddit 的反爬虫） | 在初始浏览器启动时设置 |
|
||||
| `--wait-hint` | 域名感知等待调优（fast/slow/heavy） | 与 `fetch` 或手动流程配合使用 |
|
||||
| `--session-tag` | 需要日志关联的多步骤操作 | 为调试会话设置 |
|
||||
| `wait-idle` | 在每次触发导航的 `open`/`goto`/`click` 之后 | 必须在每个页面上使用 |
|
||||
| `--block-images` | 始终使用（研究不需要图片） | 在初始浏览器启动时设置 |
|
||||
| `--auto-dismiss-dialogs` | 始终使用（防止阻塞） | 在初始浏览器启动时设置 |
|
||||
| `--no-animations` | 始终使用（稳定的快照） | 在初始浏览器启动时设置 |
|
||||
| `wait-fn` | 当内容在网络稳定后异步加载时 | 用于 SPA、动态页面 |
|
||||
| `console --level error` | 当页面内容似乎不完整或损坏时 | 用于调试 |
|
||||
| `batch` | 当填写多步骤表单时（arXiv、Google Scholar） | 替代 5 条以上连续命令 |
|
||||
| `snapshot --filter interactive` | 当发现未知页面结构时 | 用于未索引的站点 |
|
||||
| `info <selector>` | 当 click/type 未按预期工作时 | 调试元素可见性 |
|
||||
| `--stealth` | 当站点返回 CAPTCHA 或访问被拒时 | 在重试时添加 |
|
||||
|
||||
**要避免的常见错误：**
|
||||
- 在 `browser fetch` 一条命令就能完成时，仍手动使用 `open → wait-idle → text → close`
|
||||
- 对静态页面（Wikipedia、文档、博客）不使用 `--lite`——浪费 5-10 秒在浏览器启动上
|
||||
- 不使用 `--rewrite-urls`——x.com 和 reddit.com 有激进的反爬虫机制会拦截抓取
|
||||
- 在交互模式下导航后忘记使用 `wait-idle`（内容显示为空）
|
||||
- 表单交互不使用 `batch`（慢、不可靠）
|
||||
- 重试失效 URL 而不是跳过它
|
||||
- 从搜索摘要中手动构造 URL 而不是点击链接
|
||||
- 只使用一个搜索查询角度（始终使用 4 条以上多样化的查询）
|
||||
- 在提取内容前不检查 404 页面
|
||||
|
||||
## json-ui 报告模板
|
||||
|
||||
**重要：始终包含 BrandHeader 和 BrandFooter。**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "Report",
|
||||
"props": { "theme": "auto" },
|
||||
"children": [
|
||||
{
|
||||
"type": "BrandHeader",
|
||||
"props": {
|
||||
"badge": "Deep Research Report",
|
||||
"poweredBy": "Actionbook"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "Section",
|
||||
"props": { "title": "Overview", "icon": "paper" },
|
||||
"children": [
|
||||
{
|
||||
"type": "Prose",
|
||||
"props": {
|
||||
"content": "Overview of the topic..."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Section",
|
||||
"props": { "title": "Key Findings", "icon": "star" },
|
||||
"children": [
|
||||
{
|
||||
"type": "ContributionList",
|
||||
"props": {
|
||||
"items": [
|
||||
{
|
||||
"badge": "Finding",
|
||||
"title": "...",
|
||||
"description": "..."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Section",
|
||||
"props": { "title": "Detailed Analysis", "icon": "bulb" },
|
||||
"children": [
|
||||
{
|
||||
"type": "Prose",
|
||||
"props": { "content": "..." }
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Section",
|
||||
"props": { "title": "Key Metrics", "icon": "chart" },
|
||||
"children": [
|
||||
{
|
||||
"type": "MetricsGrid",
|
||||
"props": { "metrics": [], "cols": 3 }
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Section",
|
||||
"props": { "title": "Sources", "icon": "link" },
|
||||
"children": [
|
||||
{
|
||||
"type": "LinkGroup",
|
||||
"props": { "links": [] }
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "BrandFooter",
|
||||
"props": {
|
||||
"timestamp": "YYYY-MM-DDTHH:MM:SSZ",
|
||||
"attribution": "Powered by Actionbook",
|
||||
"disclaimer": "This report was generated by AI using web sources. Verify critical information independently."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 论文报告模板（用于 arXiv 论文）
|
||||
|
||||
分析学术论文时，使用更丰富的模板，包含：
|
||||
- `PaperHeader`（标题、arxivId、日期、分类）
|
||||
- `AuthorList`（带所属机构的作者）
|
||||
- `Abstract`（带关键词高亮）
|
||||
- `ContributionList`（关键贡献）
|
||||
- `MethodOverview`（逐步方法说明）
|
||||
- `ResultsTable`（实验结果）
|
||||
- `Formula`（关键公式，LaTeX）
|
||||
- `Figure`（来自 ar5iv 的论文图表）
|
||||
|
||||
### 可用的 json-ui 组件
|
||||
|
||||
| 组件 | 用途 | 关键属性 |
|
||||
|-----------|---------|-----------|
|
||||
| `BrandHeader` | 报告头部 | `badge`、`poweredBy` |
|
||||
| `PaperHeader` | 论文元数据 | `title`、`arxivId`、`date`、`categories` |
|
||||
| `AuthorList` | 作者 | `authors: [{name, affiliation}]`、`maxVisible` |
|
||||
| `Section` | 主要章节 | `title`、`icon`（paper/star/bulb/chart/code/link/info/warning） |
|
||||
| `Prose` | 富文本 | `content`（支持 **粗体**、*斜体*、`代码`、列表） |
|
||||
| `Abstract` | 摘要文本 | `text`、`highlights: ["keyword"]` |
|
||||
| `ContributionList` | 编号发现 | `items: [{badge, title, description}]` |
|
||||
| `MethodOverview` | 逐步说明 | `steps: [{step, title, description}]` |
|
||||
| `MetricsGrid` | 关键统计 | `metrics: [{label, value, trend, suffix}]`、`cols` |
|
||||
| `ResultsTable` | 数据表格 | `columns`、`rows`、`highlights: [{row, col}]` |
|
||||
| `Table` | 通用表格 | `columns: [{key, label}]`、`rows`、`striped`、`compact` |
|
||||
| `Callout` | 信息/提示/警告 | `type`（info/tip/warning/important/note）、`title`、`content` |
|
||||
| `Highlight` | 引用块 | `type`（quote/important/warning/code）、`text`、`source` |
|
||||
| `KeyPoint` | 关键发现卡片 | `icon`、`title`、`description`、`variant` |
|
||||
| `CodeBlock` | 代码片段 | `code`、`language`、`title`、`showLineNumbers` |
|
||||
| `Formula` | LaTeX 公式 | `latex`、`block`、`label` |
|
||||
| `Figure` | 图片 | `images: [{src, alt, width}]`、`label`、`caption` |
|
||||
| `Image` | 单张图片 | `src`、`alt`、`caption`、`width` |
|
||||
| `DefinitionList` | 术语/定义 | `items: [{term, definition}]` |
|
||||
| `LinkGroup` | 来源链接 | `links: [{href, label, icon}]` |
|
||||
| `Grid` | 网格布局 | `cols`、children |
|
||||
| `Card` | 卡片容器 | `padding`（sm/md/lg）、`shadow` |
|
||||
| `TagList` | 标签 | `tags: [{label, color, href}]` |
|
||||
| `BrandFooter` | 页脚 | `timestamp`、`attribution`、`disclaimer` |
|
||||
|
||||
### json-ui 已知陷阱
|
||||
|
||||
| 陷阱 | 症状 | 修复 |
|
||||
|---------|---------|-----|
|
||||
| `MetricsGrid.suffix` 为对象 | `text.replace is not a function` | `suffix` 必须是**纯字符串** |
|
||||
| `MetricsGrid.value` 为数字 | 渲染错误 | `value` 必须是**字符串**（例如 `"58.5"` 而非 `58.5`） |
|
||||
| 缺少 `BrandHeader`/`BrandFooter` | 报告显示异常 | 始终包含两者 |
|
||||
| `Table` 行值为对象 | 单元格显示 `[object Object]` | 行单元格值必须是**纯字符串** |
|
||||
| 过长的 Prose 内容 | 渲染被截断 | 拆分为多个 Prose 块或使用子章节 |
|
||||
|
||||
### 文本字段
|
||||
|
||||
所有文本字段应使用**纯英文字符串**。
|
||||
|
||||
```json
|
||||
{ "title": "Key Findings" }
|
||||
```
|
||||
|
||||
**注意：** `MetricsGrid` 属性 `value` 和 `suffix`，以及 `Table` 行单元格值必须始终是纯字符串。
|
||||
|
||||
## 学术论文支持
|
||||
|
||||
### arXiv 论文
|
||||
|
||||
**ar5iv.org HTML**（优先用于阅读，但对 3 个月内的新论文通常不完整）：
|
||||
|
||||
| 元素 | 选择器 | 可靠性 | 后备方案 |
|
||||
|---------|----------|-------------|----------|
|
||||
| 标题 | `h1.ltx_title_document` | 高 | `div.ltx_abstract` |
|
||||
| 作者 | `div.ltx_authors` | 高 | — |
|
||||
| 摘要 | `div.ltx_abstract` | 高 | — |
|
||||
| 全文 | `article` | 中 | 当章节选择器失败时使用 |
|
||||
| 章节 | `section.ltx_section` | **新论文上可靠性低** | `article` |
|
||||
| 图表 | `figure.ltx_figure` | 中 | — |
|
||||
| 表格 | `table.ltx_tabular` | 中 | — |
|
||||
|
||||
**推荐方法：** 使用 `wait-idle` + `wait-fn` 验证 ar5iv 内容已加载：
|
||||
|
||||
```bash
|
||||
actionbook browser open "https://ar5iv.org/html/<arxiv_id>"
|
||||
actionbook browser wait-idle --timeout 15000
|
||||
actionbook browser wait-fn "document.body.innerText.length > 5000" --timeout 10000
|
||||
# 如果 wait-fn 超时 → 内容未渲染，回退到其他来源
|
||||
```
|
||||
|
||||
### 推荐来源优先级
|
||||
|
||||
| 优先级 | 来源 | 获取内容 | 可靠性 |
|
||||
|----------|--------|-------------|-------------|
|
||||
| 1 | `arxiv.org/abs/<id>` | 摘要、元数据、提交历史 | 非常高 |
|
||||
| 2 | `huggingface.co/papers/<id>` | 摘要、社区、相关模型 | 非常高 |
|
||||
| 3 | GitHub 仓库 | README、代码、模型库 | 高 |
|
||||
| 4 | HuggingFace 模型卡片 | 训练方法、基准测试 | 高 |
|
||||
| 5 | `ar5iv.org/html/<id>` | 完整论文 HTML | 中 |
|
||||
| 6 | Google Scholar / Semantic Scholar | 引用、相关工作 | 中 |
|
||||
|
||||
### 其他学术来源
|
||||
|
||||
- Google Scholar（`scholar.google.com`）——已被 Actionbook 索引
|
||||
- Semantic Scholar（`semanticscholar.org`）
|
||||
- Papers With Code（`paperswithcode.com`）
|
||||
- 会议论文集网站
|
||||
|
||||
## 质量指南
|
||||
|
||||
1. **广度**：从至少 3-5 个不同的来源进行研究
|
||||
2. **深度**：阅读全文，而不仅仅是摘要
|
||||
3. **准确性**：跨来源交叉验证事实
|
||||
4. **结构**：为每种内容类型使用适当的 json-ui 组件
|
||||
5. **归属**：始终在报告中包含来源链接
|
||||
6. **时效性**：在相关性相同的情况下，优先使用较新的来源
|
||||
Reference in New Issue
Block a user