consulting-report-search

Consulting and industry report search and QA skill that prioritizes iResearch free reports. Use for consulting report search, industry report QA, iResearch report lookup, and market research report search.

# Consulting Report Search

## Description

Search and question-answering skill for consulting reports, industry reports, and market research reports. By default, it prioritizes free iResearch reports, uses the iResearch list API for primary recall, then uses QuestMobile public reports as the secondary source. Results must always show iResearch first and QuestMobile second. The search workflow now supports deeper QuestMobile pagination and grouped output rendering, so mixed-source results can be shown as fixed source sections with iResearch first.

Within each source, the default ranking mode is now newest-first, then relevance. The default sort direction is descending, so newer reports appear before older ones. If needed, agents can switch to relevance-first with an explicit CLI flag, or override the direction explicitly. If the user query itself contains a year such as `2024`, `2025`, or `2026`, ranking should instead prioritize year signals in the report title first, then report relevance, then publication time, and all three dimensions should be treated in descending order.

## Activation Keywords

- 咨询报告搜索
- 行业报告问答
- 艾瑞报告
- 艾瑞咨询
- 市场研究报告
- iresearch report
- report search
- market research report

## Tools Used

- exec: Run the bundled script to fetch iResearch and QuestMobile search results and detail pages
- read: Load the skill reference file for source behavior, encoding notes, and parsing rules
- write: Save search results or answer drafts when needed
- browser or web search tools: Use browser-based or available web-search capability when both primary sources fail to return reports

## Installation

No extra third-party packages are required. The script uses only the Python standard library.

For iResearch specifically, the logical default `pageSize` is 100 items. However, the current live public endpoint can fail when asked for 100 items in a single backend call, so the bundled script transparently splits large iResearch fetches into multiple smaller requests while still preserving the user-facing default of 100.

### Prerequisites

- Network access to https://www.iresearch.com.cn/ and https://report.iresearch.cn/
- Network access to https://www.questmobile.com.cn/research/reports/
- Python 3.10+ to run the script

## Usage Patterns

### Search Reports

```bash
python collection/skills/consulting-report-search/scripts/iresearch_report_search.py \
  search "AI营销" --pages 8 --limit 20 --sort-by recency --sort-order desc --grouped --format markdown
```

Fetch multiple pages from the iResearch free report feed, then pull multiple QuestMobile pages from its public article-list API only as fallback coverage. The default search depth is now 8 pages of iResearch results with a logical page size of 100, so the script starts from a much larger newest-first window before falling back. If the initial iResearch window still does not produce enough relevant matches, the script now automatically expands the iResearch search deeper, up to 20 logical pages in total, before QuestMobile is allowed to fill remaining slots. Final ranking must still keep all iResearch matches ahead of QuestMobile matches, and grouped output should render iResearch as the first section and QuestMobile as the second section.

By default, results are sorted by publish time first and relevance second within each source. The default sort direction is `desc`. Use `--sort-by relevance` only when the user explicitly prefers stronger keyword matching over freshness.

If the query contains a year, override the normal within-source sort and use: title year, then relevance, then publication time. All three are descending. This helps queries like `2025 AI营销` or `2024 飞行汽车` prefer reports whose titles explicitly carry the requested year.

Markdown output also shows the active sort mode and any active `--since` filter at the top of the result block.

Every returned report should explicitly include a report link. This is a hard requirement. In structured output, use the `report_link` field. In Markdown output, show a `Report Link` line for each report. If a source item does not have a valid public report link, it should be dropped from list/search output instead of being returned as a bare title.

When both sources have matches, the mixed-source search now tries to fill the requested result window with as many relevant iResearch reports as possible first. If the initial newest window is not enough, it automatically keeps paging deeper into iResearch before QuestMobile is used. QuestMobile should only fill the remaining slots when iResearch alone still cannot satisfy the requested result count.

If the user explicitly wants only iResearch, use `--iresearch-only`. This is the preferred flag for pure iResearch report collection workflows; `--no-questmobile` remains available as a lower-level compatibility switch.

### Fetch Report Details

```bash
python collection/skills/consulting-report-search/scripts/iresearch_report_search.py \
  detail freport.4694 --pages 8 --include-images --format markdown
```

Read the report detail page and return the summary, catalog, chart catalog, online reader link, and image links from the reader page.

The detail workflow should now also return a conservative interpretation, evidence boundary note, and structured outline sections derived from the public introduction, meta description, and public catalog. The interpretation should read like a short answer-oriented summary instead of a raw evidence dump.

QuestMobile detail pages are also supported through full URLs or `qm.<id>` identifiers.

### Answer a Question Against One Report

```bash
python collection/skills/consulting-report-search/scripts/iresearch_report_search.py \
  answer freport.4794 "这份报告主要讲什么？" --pages 8 --include-images --format markdown
```

Use `answer` when the user is asking a concrete question about one report rather than requesting a raw detail dump.

The answer mode should:

- fetch the same public detail evidence as `detail`
- generate a conservative answer grounded in public summary, outline sections, and chart catalog
- return explicit evidence snippets
- keep the evidence boundary visible
- include report and online-reading links for manual verification

### Browse Recent Free Reports

```bash
python collection/skills/consulting-report-search/scripts/iresearch_report_search.py \
  list --pages 2 --page-size 100 --format markdown
```

Use this to inspect the recent free-report pool before deciding which reports to summarize or use for QA.

### Search Reports with Explicit Source Groups

```bash
python collection/skills/consulting-report-search/scripts/iresearch_report_search.py \
  search "AI应用层" --pages 8 --limit 12 --sort-by recency --sort-order desc --since 2025-01-01 --grouped --format json
```

Use grouped output when you need a stable source-layered rendering format. This keeps iResearch and QuestMobile separated instead of interleaving them in a single list.

Use `--since` when the user explicitly wants only recent reports, for example limiting the result window to 2025 and later.

The hidden `--last-id` cursor parameter is deprecated for normal use and should only be used for debugging historical iResearch cursor windows.

## Instructions for Agents

### Step 1: Classify the Request

First determine whether the user wants:

- Report search
- Topic filtering or comparison
- QA grounded in one or more reports
- Lead collection for relevant reports

If the request involves industry status, trends, market size, cases, figures, or charts, start with iResearch by default.

### Step 2: Search iResearch Free Reports First

Always use the bundled script first instead of jumping directly to broad web search:

```bash
python collection/skills/consulting-report-search/scripts/iresearch_report_search.py \
  search "<query>" --pages 8 --limit 20 --format json
```

Execution requirements:

- Fetch a deep newest-first iResearch window by default; the current default is 8 logical pages with pag