Deep Research

Analyze any topic, domain, or paper and generate a beautiful HTML report using Actionbook browser automation and json-ui rendering.

Usage

/deep-research:analyze <topic>
/deep-research:analyze <topic> --lang zh
/deep-research:analyze <topic> --output ./reports/my-report.json

Or simply tell Claude: "帮我深度研究 XXX 并生成报告" / "Research XXX and generate a report"

Parameters

topic

--lang

both

en

zh

both

--output

./output/<topic-slug>.json

Topic Detection

arxiv:XXXX.XXXXX

doi:10.XXX/...

Architecture

┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│  Claude   │────▶│  Actionbook  │────▶│  Web Pages   │────▶│ Extract  │
│  Code     │     │  Browser CLI │     │  (multiple)  │     │ Content  │
└──────────┘     └──────────────┘     └──────────────┘     └─────┬────┘
      │                                                           │
      │          ┌──────────────┐     ┌──────────────┐           │
      ├─────────▶│  Actionbook  │     │ arXiv Adv.   │           │
      │          │  search/get  │────▶│ Search Form  │──────────▶│
      │          │  (selectors) │     │ (40+ fields) │           │
      │          └──────────────┘     └──────────────┘           │
      │                                                           │
      │    Actionbook indexes arXiv form selectors,               │
      │    enabling field-specific, filtered academic              │
      │    searches that WebFetch/WebSearch CANNOT do.             │
      │                                                           │
┌──────────┐     ┌──────────────┐     ┌──────────────┐           │
│  Open in │◀────│   json-ui    │◀────│  Write JSON  │◀──────────┘
│  Browser │     │   render     │     │  Report      │  Synthesize
└──────────┘     └──────────────┘     └──────────────┘

Why Actionbook, Not WebFetch/WebSearch?

#terms-0-field

actionbook get

This is the core value of Actionbook for research: it turns web forms into structured, programmable interfaces for AI agents.

MUST USE Actionbook CLI

Always use

actionbook browser

actionbook browser open <url>          # Navigate to page
actionbook browser snapshot            # Get accessibility tree
actionbook browser text [selector]     # Extract text content
actionbook browser screenshot [path]   # Capture visual
actionbook browser click <selector>    # Click element
actionbook browser close               # Close browser (ALWAYS do this at end)

Complete Workflow

Step 1: Plan Search Strategy

Based on the topic, generate 5-8 search queries from different angles:

• Core definition / overview
• Latest developments / news
• Technical details / implementation
• Comparisons / alternatives
• Expert opinions / analysis
• Use cases / applications

Search order — ALWAYS query Actionbook API first, then search:

IMPORTANT: Always query Actionbook API first (Step 2) to get selectors, then use them in arXiv Advanced Search (Step 3). This is what makes Actionbook-powered research fundamentally different from WebFetch/WebSearch — the agent knows the exact selectors for every form field before it even opens the browser.

Step 2: Query Actionbook API for Selectors (ALWAYS DO THIS FIRST)

BEFORE browsing any URL, query Actionbook's indexed selectors. This gives you verified CSS/XPath selectors instead of guessing.

# Search for indexed actions by domain
actionbook search "<keywords>" -d "<domain>"

# Get detailed selectors for a specific page
actionbook get "<domain>:/<path>:<area>"

Pre-indexed sites useful for research:

arxiv.org:/search/advanced:default

ar5iv.labs.arxiv.org:/html/{paper_id}:default

h1.ltx_title_document

div.ltx_authors

div.ltx_abstract

section.ltx_section

scholar.google.com:/:default

#gs_hdr_tsi

#gs_hdr_tsb

arxiv.org:/:default

For any URL you plan to visit, run

actionbook search "<keywords>" -d "<domain>"

actionbook browser snapshot

Example: Get arXiv Advanced Search selectors before searching:

# Query Actionbook for arXiv form selectors
actionbook get "arxiv.org:/search/advanced:default"
# Returns 40+ selectors: #terms-0-field, #terms-0-term, #classification-computer_science, etc.

Step 3: arXiv Advanced Search (Using Actionbook Selectors)

Key differentiator: WebFetch/WebSearch can only do simple keyword searches. Actionbook has indexed the entire arXiv Advanced Search form with 40+ verified selectors (queried in Step 2), enabling multi-field, multi-criteria academic searches — just like a human researcher would use the form.

Using the selectors obtained from Step 2, the Agent can:

#terms-0-field

button "Add another term +"

#classification-computer_science

#date-filter_by-3

#date-from_date

#date-to_date

#date-filter_by-2

#date-year

#classification-include_cross_list-0/1

#size

#abstracts-0/1

Example: Search for recent CS papers by a specific author:

# Open arXiv Advanced Search
actionbook browser open "https://arxiv.org/search/advanced"

# 1. Set search field to "Author" and type author name
actionbook browser click "#terms-0-field"
actionbook browser click "option[value='author']"
actionbook browser type "#terms-0-term" "Yann LeCun"

# 2. Filter to Computer Science only
actionbook browser click "#classification-computer_science"

# 3. Restrict to past 12 months
actionbook browser click "#date-filter_by-1"

# 4. Show abstracts in results
actionbook browser click "#abstracts-0"

# 5. Submit search
actionbook browser click "button:has-text('Search'):nth(2)"

# 6. Extract results
actionbook browser text "#main-container"

Example: Search by title keywords in a date range:

actionbook browser open "https://arxiv.org/search/advanced"

# Search in "Title" field
actionbook browser click "#terms-0-field"
actionbook browser click "option[value='title']"
actionbook browser type "#terms-0-term" "large language model agent"

# Date range: 2025-01 to 2026-02
actionbook browser click "#date-filter_by-3"
actionbook browser type "#date-from_date" "2025-01-01"
actionbook browser type "#date-to_date" "2026-02-09"

# Submit and extract
actionbook browser click "button:has-text('Search'):nth(2)"
actionbook browser text "#main-container"

Step 4: Supplement with Google / Bing Search

After arXiv, use Google/Bing to find non-academic sources (blogs, news, docs, code, discussions):

# Search via Google
actionbook browser open "https://www.google.com/search?q=<encoded_query>"
actionbook browser text "#search"

# Or search via Bing
actionbook browser open "https://www.bing.com/search?q=<encoded_query>"
actionbook browser text "#b_results"

Parse the search results to extract URLs and snippets. Collect the top 5-10 most relevant URLs. For each discovered URL, query Actionbook API (Step 2 pattern) to check if the site is indexed before visiting.

Step 5: Deep Read Sources

For each relevant URL, first query Actionbook API (same as Step 2) to check if the site is indexed, then use verified selectors:

actionbook browser open "<url>"
actionbook browser text                # Full page text (fallback)
actionbook browser text "<selector>"   # Use Actionbook selector if indexed

For arXiv papers, try sources in this order (newer papers often fail on ar5iv):

# 1. Try ar5iv first (best structured selectors from Actionbook)
actionbook browser open "https://ar5iv.org/html/<arxiv_id>"
actionbook browser text "h1.ltx_title_document"  # Title
actionbook browser text "div.ltx_authors"         # Authors
actionbook browser text "div.ltx_abstract"        # Abstract
# NOTE: section.ltx_section often fails on newer papers — use "article" as fallback

# 2. If ar5iv content is truncated (<5KB), fall back to arxiv abstract + other sources
actionbook browser open "https://arxiv.org/abs/<arxiv_id>"
actionbook browser text "main"

# 3. Supplement with HuggingFace model cards and GitHub READMEs for full details
actionbook browser open "https://huggingface.co/papers/<arxiv_id>"
actionbook browser text "main"

Key lesson: Don't rely solely on ar5iv. Always cross-reference 3-4 sources for completeness.

For Google Scholar (indexed by Actionbook):

actionbook browser open "https://scholar.google.com"
# Type into search: use selector #gs_hdr_tsi
actionbook browser click "#gs_hdr_tsi"
# ... type query, click #gs_hdr_tsb to search

For unindexed sites, use snapshot to discover page structure:

actionbook browser open "<url>"
actionbook browser snapshot            # Get accessibility tree to find selectors
actionbook browser text "<discovered_selector>"

Step 6: Synthesize Findings

Organize collected information into a coherent report:

1. Overview / Executive Summary
2. Key Findings
3. Detailed Analysis
4. Supporting Data / Evidence
5. Implications / Significance
6. Sources

Step 7: Generate json-ui JSON Report

Write a JSON file following the

@actionbookdev/json-ui

Output path:

./output/<topic-slug>.json

--output

Step 8: Render HTML

CRITICAL: You MUST try ALL fallback methods before giving up. Do NOT stop at the first failure.

IMPORTANT: Always use ABSOLUTE paths for JSON_FILE and HTML_FILE. Relative paths break when git rev-parse returns an absolute repo root.

Try each method one by one until one succeeds:

# Method 1: npx (recommended — works anywhere if npm is available)
npx @actionbookdev/json-ui render /absolute/path/to/report.json -o /absolute/path/to/report.html

# Method 2: Global install (if user ran: npm install -g @actionbookdev/json-ui)
json-ui render /absolute/path/to/report.json -o /absolute/path/to/report.html

# Method 3: Monorepo local path (fallback if inside actionbook project)
node "$(git rev-parse --show-toplevel)/packages/json-ui/dist/cli.js" render /absolute/path/to/report.json -o /absolute/path/to/report.html

NEVER give up silently. If all methods fail, tell the user:

1. The JSON report is saved at

   <path>

2. To install the renderer, run:

   npm install -g @actionbookdev/json-ui

Step 9: Open in Browser

# macOS
open <report.html>

# Linux
xdg-open <report.html>

Step 10: Close Browser

Always close the browser when done:

actionbook browser close

json-ui Report Template

IMPORTANT: Always include BrandHeader and BrandFooter.

{
  "type": "Report",
  "props": { "theme": "auto" },
  "children": [
    {
      "type": "BrandHeader",
      "props": {
        "badge": { "en": "Deep Research Report", "zh": "深度研究报告" },
        "poweredBy": "Actionbook"
      }
    },
    {
      "type": "Section",
      "props": { "title": { "en": "Overview", "zh": "概述" }, "icon": "paper" },
      "children": [
        {
          "type": "Prose",
          "props": {
            "content": { "en": "English overview...", "zh": "中文概述..." }
          }
        }
      ]
    },
    {
      "type": "Section",
      "props": { "title": { "en": "Key Findings", "zh": "核心发现" }, "icon": "star" },
      "children": [
        {
          "type": "ContributionList",
          "props": {
            "items": [
              {
                "badge": { "en": "Finding", "zh": "发现" },
                "title": { "en": "...", "zh": "..." },
                "description": { "en": "...", "zh": "..." }
              }
            ]
          }
        }
      ]
    },
    {
      "type": "Section",
      "props": { "title": { "en": "Detailed Analysis", "zh": "详细分析" }, "icon": "bulb" },
      "children": [
        {
          "type": "Prose",
          "props": { "content": { "en": "...", "zh": "..." } }
        }
      ]
    },
    {
      "type": "Section",
      "props": { "title": { "en": "Key Metrics", "zh": "关键指标" }, "icon": "chart" },
      "children": [
        {
          "type": "MetricsGrid",
          "props": { "metrics": [], "cols": 3 }
        }
      ]
    },
    {
      "type": "Section",
      "props": { "title": { "en": "Sources", "zh": "信息来源" }, "icon": "link" },
      "children": [
        {
          "type": "LinkGroup",
          "props": { "links": [] }
        }
      ]
    },
    {
      "type": "BrandFooter",
      "props": {
        "timestamp": "YYYY-MM-DDTHH:MM:SSZ",
        "attribution": "Powered by Actionbook",
        "disclaimer": {
          "en": "This report was generated by AI using web sources. Verify critical information independently.",
          "zh": "本报告由 AI 基于网络来源生成，请独立验证关键信息。"
        }
      }
    }
  ]
}

Paper Report Template (for arXiv papers)

When analyzing academic papers, use a richer template with:

• PaperHeader

  (title, arxivId, date, categories)

• AuthorList

  (authors with affiliations)

• Abstract

  (with keyword highlights)

• ContributionList

  (key contributions)

• MethodOverview

  (step-by-step method)

• ResultsTable

  (experimental results)

• Formula

  (key equations, LaTeX)

• Figure

  (paper figures from ar5iv)

Available json-ui Components

BrandHeader

badge

poweredBy

PaperHeader

title

arxivId

date

categories

AuthorList

authors: [{name, affiliation}]

maxVisible

Section

title

icon

Prose

content

code

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

title

content

Highlight

type

text

source

KeyPoint

icon

title

description

variant

CodeBlock

code

language

title

showLineNumbers

Formula

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

Card

padding

shadow

TagList

tags: [{label, color, href}]

BrandFooter

timestamp

attribution

disclaimer

json-ui Known Pitfalls

MetricsGrid.suffix

text.replace is not a function

suffix

{ "en": ..., "zh": ... }

MetricsGrid.value

value

"58.5"

58.5

BrandHeader

BrandFooter

Table

[object Object]

label

"Runtimes / 运行时"

{ "en": "Runtimes", "zh": "运行时" }

i18n Support

All text fields support bilingual output unless noted above:

{ "en": "English text", "zh": "中文文本" }

For

--lang en

--lang zh

--lang both

Exceptions:

• MetricsGrid

  props

  value

  and

  suffix

  must always be plain strings.

• Table

  row cell values must be plain strings (column

  label

  supports i18n, but row data does not). For bilingual, use

  "English / 中文"

  format.

Academic Paper Support

arXiv Papers

ar5iv.org HTML (preferred for reading, but often incomplete for papers < 3 months old):

h1.ltx_title_document

div.ltx_abstract

div.ltx_authors

div.ltx_abstract

article

section.ltx_section

article

h2.ltx_title_section

article

figure.ltx_figure

table.ltx_tabular

.ltx_bibliography

Note: For papers submitted within the last ~3 months, ar5iv often renders incomplete content. Always check

actionbook browser text 2>&1 | wc -c

arXiv API (for metadata via actionbook browser):

actionbook browser open "http://export.arxiv.org/api/query?id_list={arxiv_id}"
actionbook browser text

Recommended Source Priority for Papers

Based on testing, use this priority order for maximum coverage:

arxiv.org/abs/<id>

huggingface.co/papers/<id>

ar5iv.org/html/<id>

Key insight: Don't rely on a single source. The combination of arxiv abstract + HuggingFace + GitHub typically gives 90%+ of what you need, even when ar5iv fails.

Other Academic Sources

Use

actionbook browser

• Google Scholar (

  scholar.google.com

  ) — Actionbook indexed, use

  #gs_hdr_tsi

  for search
• Semantic Scholar (

  semanticscholar.org

  )
• Papers With Code (

  paperswithcode.com

  )
• Conference proceedings sites

Error Handling

actionbook browser status

section.ltx_section

actionbook browser text "article"

"main"

actionbook browser snapshot

actionbook search

actionbook browser snapshot

text.replace

suffix

value

npx @actionbookdev/json-ui

npm install -g @actionbookdev/json-ui

json-ui render

npm install -g @actionbookdev/json-ui

IMPORTANT: Always run

actionbook browser close

Quality Guidelines

1. Breadth: Research from at least 3-5 diverse sources
2. Depth: Read full articles, not just snippets
3. Accuracy: Cross-reference facts across sources
4. Structure: Use appropriate json-ui components for each content type
5. Attribution: Always include source links in the report
6. Freshness: Prefer recent sources when relevance is equal

Chinese Content Quality Guidelines (中文内容质量规范)

CRITICAL: Chinese text must be written as native Chinese, NOT translated from English.

The

zh

Common Problems to Avoid

Writing Rules

1. 先写中文，再对照英文查漏：不要从英文逐句翻译。先理解内容本质，用中文重新组织表达。
2. 主动语态优先：中文天然偏好主动句。"X 被 Y 采用" → "Y 采纳了 X" 或 "Y 已在用 X"。
3. 短句 > 长句：中文读者偏好短句。超过 40 字的句子应拆分。
4. 术语处理原则：
   • 有公认中文译名的术语用中文：服务器 → 服务器、容器 → 容器、沙箱 → 沙箱
   • 无公认译名的术语保留英文：Component Model、WASI、SIMD、Cold Start
   • 首次出现时中英对照：「组件模型（Component Model）」，之后可只用中文
   • 不要硬造中文译名（如"非干扰分析"，应写"Noninterference 分析"或解释性表述）
5. 数据和事实保持一致：中英文的数字、日期、引用来源必须完全一致。
6. 语气自然：可以用"说白了"、"换句话说"、"简单来说"等口语化连接词，避免全篇书面腔。
7. 标点规范：用中文标点（，。；：「」）而非英文标点。引号优先用「」。

Table & Short Text Rules (表格与短文本规则)

Table 行中的

"English / 中文"

规则：中文部分必须是独立的中文表述，不是英文的逐词翻译。

表格中文短文本的核心原则：

1. 保留英文术语：Bump allocator、MPMC、ECS 这些没有公认中文译名的概念，直接保留英文。别硬翻。
2. 口语化 > 书面化：短文本读者扫一眼就过，要像说话一样自然。"主打性能" 比 "性能优化的" 好。
3. 别逐词翻译：先理解英文描述的意思，然后用中文重新说一遍。"Full-featured datetime" → "功能齐全的时间日期库"，不是 "全功能日期时间"。
4. 可以省略冗余修饰：英文 "A generic serialization/deserialization framework" → 中文只需 "序列化框架"。
5. 数量控制在 10 字以内：表格中文描述尽量控制在 10 个汉字以内，简短精准。

Bilingual Tone Reference