CitationAgent

# 年份遍历模式：绕过 Google Scholar 每次只返回 ~1000 篇的硬限制
# 解析 .gs_hist_g_a[data-year][data-count] 柱状图
async def _scrape_by_year(self, base_url: str):
    # 先获取年份直方图
    histogram = await self._fetch_year_histogram(base_url)
    # {2018: 43, 2019: 127, 2020: 289, ...}

    for year, count in histogram.items():
        # 对每个年份单独构造 URL 并抓取
        year_url = base_url + f"&as_ylo={year}&as_yhi={year}"
        papers = await self._scrape_url(year_url)
        yield papers
        await self._write_jsonl_page(papers)

# 20 个优先国家代码（学术流量大，被封概率低）
PREFERRED_GEO_COUNTRIES = [
    'us', 'uk', 'de', 'fr', 'ca', 'au', 'jp',
    'kr', 'sg', 'nl', 'se', 'ch', 'at', 'dk',
    'fi', 'no', 'nz', 'ie', 'be', 'it',
]

async def _detect_dc_inconsistency(self, page_html: str) -> bool:
    # 短页面检测：正常页面应有 10 篇论文
    papers_found = self.parser.count_results(page_html)
    return papers_found < 2

async def _rotate_geo(self, attempt: int) -> str:
    if attempt < 20:
        return self.PREFERRED_GEO_COUNTRIES[attempt % 20]
    else:
        return random.choice(self.ALL_GEO_COUNTRIES)

class AuthorSearcher:
    async def search_all(self, papers: list, parallel_workers: int = 5):
        sem = asyncio.Semaphore(parallel_workers)

        async def _bounded_search(paper):
            async with sem:
                # 先检查缓存
                cached = self.cache.get(paper['url'])
                if cached and cached.is_complete():
                    return cached
                # 执行多步 LLM 搜索
                return await self._search_single(paper)

        tasks = [_bounded_search(p) for p in papers]
        return await asyncio.gather(*tasks)

    async def _llm_web_search(self, prompt: str) -> str:
        # extra_body 启用 Web Search（OpenAI-compatible 扩展）
        resp = await self.client.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
            extra_body={"web_search_options": {}}
        )
        return resp.choices[0].message.content

# 对目标论文标题加锁，防止并发时重复查找同一目标
self._title_locks: dict[str, asyncio.Lock] = {}

async def _get_lock(self, title: str) -> asyncio.Lock:
    if title not in self._title_locks:
        self._title_locks[title] = asyncio.Lock()
    return self._title_locks[title]

# 三种抓取范围
# "all"            → 所有引用论文
# "renowned_only"  → 仅重要学者的论文
# "specified_only" → 用户指定的论文列表