@blxzer/cursor-trellis 0.1.3 → 0.2.1

package/vendor/smart-search/src/smart_search/service.py

@@ -1,2865 +0,0 @@
-import asyncio
-import hashlib
-import json
-import re
-import time
-from pathlib import Path
-from typing import Any
-from urllib.parse import urlparse
-
-import httpx
-
-from .config import config
-from .logger import log_info
-from .providers.context7 import Context7Provider
-from .providers.exa import ExaSearchProvider
-from .providers.jina import JinaReaderProvider
-from .providers.openai_compatible import OpenAICompatibleSearchProvider, get_local_time_info
-from .providers.zhipu import ZhipuWebSearchProvider
-from .sources import merge_sources, new_session_id, split_answer_and_sources
-from .utils import search_prompt
-
-
-_AVAILABLE_MODELS_CACHE: dict[tuple[str, str], list[str]] = {}
-_AVAILABLE_MODELS_LOCK = asyncio.Lock()
-SOURCE_PROVENANCE_WARNING = (
-    "extra_sources are retrieved in parallel and are not automatically used to verify generated content; "
-    "use fetch on key URLs for claim-level evidence."
-)
-MINIMUM_PROFILE_ERROR = (
-    "最低配置不满足：必须至少配置 main_search、docs_search、web_fetch 三类能力各一个 provider。"
-)
-OPENAI_COMPATIBLE_DIAGNOSE_COMMAND = "smart-search diagnose openai-compatible --format markdown"
-DOCS_INTENT_ASCII_KEYWORDS = {
-    "api",
-    "sdk",
-    "library",
-    "framework",
-    "docs",
-    "documentation",
-    "reference",
-    "guide",
-    "tutorial",
-    "quickstart",
-    "example",
-    "examples",
-    "usage",
-    "manual",
-    "changelog",
-    "release notes",
-    "migration",
-    "react",
-    "next.js",
-    "vue",
-    "python",
-    "prisma",
-    "langchain",
-    "openai",
-    "context7",
-}
-DOCS_INTENT_TEXT_KEYWORDS = {
-    "接口",
-    "文档",
-    "库",
-    "框架",
-    "函数",
-    "参数",
-    "配置",
-    "教程",
-    "指南",
-    "示例",
-    "用法",
-    "快速开始",
-    "迁移",
-    "变更日志",
-    "版本说明",
-}
-DOCS_INTENT_KEYWORDS = DOCS_INTENT_ASCII_KEYWORDS | DOCS_INTENT_TEXT_KEYWORDS
-ZH_CURRENT_KEYWORDS = {
-    "今天",
-    "最新",
-    "国内",
-    "中国",
-    "政策",
-    "新闻",
-    "实时",
-    "刚刚",
-    "本周",
-    "本月",
-    "战报",
-    "比分",
-    "赛程",
-    "赛果",
-    "季后赛",
-    "比赛",
-    "nba",
-    "足球",
-    "篮球",
-}
-FETCH_INTENT_KEYWORDS = {"http://", "https://"}
-DEEP_ALLOWED_TOOLS = {
-    "search",
-    "exa-search",
-    "exa-similar",
-    "context7-library",
-    "context7-docs",
-    "fetch",
-    "map",
-}
-DEEP_TRIGGER_KEYWORDS = {
-    "深度搜索",
-    "深度调研",
-    "深入搜索",
-    "deep search",
-    "deep research",
-    "核验",
-    "验证",
-    "交叉验证",
-    "选型",
-    "对比",
-    "评测",
-}
-DEEP_HIGH_COMPLEXITY_KEYWORDS = {
-    "对比",
-    "选型",
-    "核验",
-    "验证",
-    "为什么",
-    "架构",
-    "方案",
-    "趋势",
-    "优缺点",
-    "风险",
-    "区别",
-    "怎么选",
-    "compare",
-    "comparison",
-    "evaluate",
-    "architecture",
-    "tradeoff",
-    "trade-off",
-    "risk",
-}
-DEEP_RECENT_KEYWORDS = {
-    "最近",
-    "最新",
-    "当前",
-    "现在",
-    "今天",
-    "实时",
-    "刚刚",
-    "本周",
-    "本月",
-    "recent",
-    "latest",
-    "current",
-    "today",
-}
-DEEP_CURRENT_KEYWORDS = {"今天", "实时", "刚刚", "当前", "现在", "today", "current", "live", "realtime"}
-DEEP_CHINA_KEYWORDS = {"中国", "国内", "中文", "政策", "监管", "公告", "A股", "港股"}
-DEEP_EXA_DISCOVERY_KEYWORDS = {
-    "官方",
-    "官网",
-    "论文",
-    "paper",
-    "papers",
-    "research paper",
-    "产品页",
-    "product page",
-    "可信站点",
-    "trusted",
-    "known domain",
-    "known domains",
-    "site:",
-    "白皮书",
-    "standard",
-    "standards",
-}
-RESEARCH_ROUTE_POLICY_VERSION = "research-router-v2-bilingual-no-zhipu"
-RESEARCH_JS_HEAVY_KEYWORDS = {
-    "js-heavy",
-    "javascript",
-    "dynamic",
-    "动态页面",
-    "浏览器渲染",
-    "登录页",
-    "cloudflare",
-    "screenshot",
-    "ocr",
-    "扫描",
-}
-RESEARCH_PDF_KEYWORDS = {"pdf", "arxiv", "论文", "paper", ".pdf"}
-RESEARCH_PROFILE_ORDER = {
-    "main_search": ["openai-compatible"],
-    "web_search": ["tavily", "firecrawl"],
-    "docs_search": ["context7", "exa"],
-    "web_fetch": ["tavily", "jina", "firecrawl"],
-    "site_map": ["tavily"],
-    "synthesis": ["main-search"],
-}
-PROVIDER_PROFILES: dict[str, dict[str, Any]] = {
-    "openai-compatible": {
-        "capability": "main_search",
-        "strengths": ["broad synthesis", "relay compatibility"],
-        "exclusions": ["xAI server tools"],
-        "fallback_group": "main_search",
-        "minimum_profile_role": "main_search",
-        "quality_filters": ["source extraction required for high-risk claims"],
-        "route_reasons": ["relay-compatible primary synthesis"],
-    },
-    "context7": {
-        "capability": "docs_search",
-        "strengths": ["library docs", "API docs", "framework docs", "versioned snippets"],
-        "exclusions": ["general news", "generic web facts"],
-        "fallback_group": "docs_search",
-        "minimum_profile_role": "docs_search",
-        "quality_filters": ["library id required", "content required before citation"],
-        "route_reasons": ["docs/API evidence", "framework reference"],
-    },
-    "exa": {
-        "capability": "docs_search",
-        "strengths": ["official domains", "papers", "product pages", "trusted low-noise discovery", "similar pages"],
-        "exclusions": ["default second hop for every high-risk claim"],
-        "fallback_group": "docs_search",
-        "minimum_profile_role": "docs_search",
-        "quality_filters": ["URL required", "fetch before proof citation"],
-        "route_reasons": ["official low-noise discovery", "paper/product discovery"],
-    },
-    "zhipu": {
-        "capability": "web_search",
-        "deprecated": True,
-        "strengths": ["legacy Chinese/current web-search command compatibility"],
-        "exclusions": ["web_fetch", "chat model selection"],
-        "fallback_group": "web_search",
-        "minimum_profile_role": "",
-        "quality_filters": ["URL required", "fetch before proof citation"],
-        "route_reasons": ["deprecated; not used by default routing"],
-    },
-    "tavily": {
-        "capability": "web_search",
-        "capabilities": ["web_search", "web_fetch", "site_map"],
-        "strengths": ["broad source discovery", "site map", "URL extract"],
-        "exclusions": ["docs semantic replacement"],
-        "fallback_group": "web_search/web_fetch/site_map",
-        "minimum_profile_role": "web_fetch",
-        "quality_filters": ["non-empty normalized result", "non-empty extracted content"],
-        "route_reasons": ["broad source discovery", "site map", "URL fetch"],
-    },
-    "jina": {
-        "capability": "web_fetch",
-        "strengths": ["known public URL", "PDF", "arXiv", "clean markdown", "ReaderLM-v2 with key"],
-        "exclusions": ["general search provider", "anonymous standard minimum profile"],
-        "fallback_group": "web_fetch",
-        "minimum_profile_role": "web_fetch_with_key",
-        "quality_filters": ["non-empty markdown", "challenge page rejection", "ReaderLM-v2 requires key"],
-        "route_reasons": ["known URL extraction", "PDF/arXiv extraction"],
-    },
-    "firecrawl": {
-        "capability": "web_fetch",
-        "capabilities": ["web_search", "web_fetch"],
-        "strengths": ["robust scrape fallback", "JS-heavy pages", "dynamic pages", "OCR/PDF/structured extraction"],
-        "exclusions": ["docs semantic replacement"],
-        "fallback_group": "web_search/web_fetch",
-        "minimum_profile_role": "web_fetch",
-        "quality_filters": ["non-empty normalized result", "non-empty extracted content"],
-        "route_reasons": ["JS-heavy fetch", "dynamic/browser-like extraction", "robust fetch fallback"],
-    },
-    "main-search": {
-        "capability": "synthesis",
-        "strengths": ["evidence-only final synthesis"],
-        "exclusions": ["live source discovery during research synthesis"],
-        "fallback_group": "synthesis",
-        "minimum_profile_role": "",
-        "quality_filters": ["fetched evidence only", "no provider calls during synthesis"],
-        "route_reasons": ["evidence-only synthesis"],
-    },
-}
-MAIN_SEARCH_FALLBACK_CHAIN = ["openai-compatible"]
-MAIN_SEARCH_PROVIDER_ALIASES = {
-    "openai-compatible": {"openai-compatible", "openai", "chat-completions", "primary"},
-}
-
-
-def _elapsed_ms(start: float) -> float:
-    return round((time.time() - start) * 1000, 2)
-
-
-def _normalize_domain_filter(value: str | list[str] | tuple[str, ...] | None) -> list[str] | None:
-    if not value:
-        return None
-
-    raw_parts = [value] if isinstance(value, str) else [str(item) for item in value if item]
-    domains: list[str] = []
-    for part in raw_parts:
-        domains.extend(item.strip() for item in re.split(r"[\s,]+", part) if item.strip())
-    return domains or None
-
-
-def _empty_search_result(
-    start: float,
-    session_id: str,
-    query: str,
-    error_type: str,
-    error: str,
-    primary_api_mode: str = "",
-    extra: dict[str, Any] | None = None,
-) -> dict[str, Any]:
-    data: dict[str, Any] = {
-        "ok": False,
-        "error_type": error_type,
-        "error": error,
-        "session_id": session_id,
-        "query": query,
-        "primary_api_mode": primary_api_mode,
-        "content": "",
-        "sources": [],
-        "sources_count": 0,
-        "primary_sources": [],
-        "primary_sources_count": 0,
-        "extra_sources": [],
-        "extra_sources_count": 0,
-        "source_warning": "",
-        "routing_decision": {},
-        "providers_used": [],
-        "provider_attempts": [],
-        "fallback_used": False,
-        "validation_level": "",
-        "elapsed_ms": _elapsed_ms(start),
-    }
-    if extra:
-        data.update(extra)
-    return data
-
-
-def _attempt(
-    capability: str,
-    provider: str,
-    status: str,
-    start: float,
-    result_count: int = 0,
-    error_type: str = "",
-    error: str = "",
-) -> dict[str, Any]:
-    return {
-        "capability": capability,
-        "provider": provider,
-        "status": status,
-        "error_type": error_type,
-        "error": error,
-        "elapsed_ms": _elapsed_ms(start),
-        "result_count": result_count,
-    }
-
-
-def _normalize_source_results(results: list[dict] | None, provider: str) -> list[dict]:
-    normalized: list[dict] = []
-    for item in results or []:
-        url = (item.get("url") or item.get("link") or "").strip()
-        if not url:
-            continue
-        out = {"url": url, "provider": item.get("provider") or provider}
-        title = (item.get("title") or "").strip()
-        if title:
-            out["title"] = title
-        desc = (item.get("description") or item.get("content") or item.get("snippet") or "").strip()
-        if desc:
-            out["description"] = desc
-        published = item.get("published_date") or item.get("publishedDate") or item.get("publish_date")
-        if published:
-            out["published_date"] = published
-        source = item.get("source") or item.get("media")
-        if source:
-            out["source"] = source
-        normalized.append(out)
-    return normalized
-
-
-def _provider_names_from_attempts(attempts: list[dict]) -> list[str]:
-    names: list[str] = []
-    for attempt in attempts:
-        provider = attempt.get("provider")
-        if attempt.get("status") == "ok" and provider and provider not in names:
-            names.append(provider)
-    return names
-
-
-def _fallback_used(attempts: list[dict]) -> bool:
-    by_capability: dict[str, list[dict]] = {}
-    for attempt in attempts:
-        capability = attempt.get("capability", "")
-        if attempt.get("status") in {"ok", "empty", "error"}:
-            by_capability.setdefault(capability, []).append(attempt)
-    for capability_attempts in by_capability.values():
-        previous_failed = False
-        previous_provider = ""
-        for attempt in capability_attempts:
-            provider = attempt.get("provider", "")
-            status = attempt.get("status")
-            if previous_failed:
-                return True
-            if previous_provider and provider and provider != previous_provider:
-                return True
-            previous_failed = status in {"empty", "error"}
-            previous_provider = provider or previous_provider
-    return False
-
-
-def provider_profiles() -> dict[str, dict[str, Any]]:
-    return {provider: dict(profile) for provider, profile in PROVIDER_PROFILES.items()}
-
-
-def _provider_supports_capability(provider: str, capability: str) -> bool:
-    profile = PROVIDER_PROFILES.get(provider, {})
-    capabilities = set(profile.get("capabilities") or [profile.get("capability", "")])
-    return capability in capabilities
-
-
-def _provider_configured(provider: str) -> bool:
-    if provider == "openai-compatible":
-        return bool(config.openai_compatible_api_url and config.openai_compatible_api_key)
-    if provider == "context7":
-        return bool(config.context7_api_key)
-    if provider == "exa":
-        return bool(config.exa_api_key)
-    if provider == "zhipu":
-        return bool(config.zhipu_api_key)
-    if provider == "tavily":
-        return bool(config.tavily_api_key)
-    if provider == "jina":
-        return bool(config.jina_api_key)
-    if provider == "firecrawl":
-        return bool(config.firecrawl_api_key)
-    if provider == "main-search":
-        return bool(config.openai_compatible_api_url and config.openai_compatible_api_key)
-    return False
-
-
-def _configured_for_capability(capability: str, capability_status: dict[str, Any] | None = None) -> list[str]:
-    if capability_status is not None:
-        configured = set(capability_status.get(capability, {}).get("configured") or [])
-        return [
-            provider
-            for provider in RESEARCH_PROFILE_ORDER.get(capability, [])
-            if provider in configured and _provider_supports_capability(provider, capability)
-        ]
-    return [provider for provider in RESEARCH_PROFILE_ORDER.get(capability, []) if _provider_configured(provider)]
-
-
-def _bilingual_search_queries(query: str) -> list[dict[str, str]]:
-    question = query.strip()
-    return [
-        {
-            "locale": "zh",
-            "label": "Chinese-language sources",
-            "query": f"中文搜索，优先检索中文来源，并回答原问题：{question}",
-        },
-        {
-            "locale": "en",
-            "label": "English-language sources",
-            "query": f"Search English-language sources and answer the original question: {question}",
-        },
-    ]
-
-
-def _safe_provider_overrides() -> tuple[list[str], list[str], list[str]]:
-    known = set(PROVIDER_PROFILES)
-    preferred = [provider for provider in config.research_preferred_providers if provider in known]
-    disabled = [provider for provider in config.research_disabled_providers if provider in known]
-    invalid = [
-        provider
-        for provider in config.research_preferred_providers + config.research_disabled_providers
-        if provider not in known
-    ]
-    return preferred, disabled, invalid
-
-
-def _apply_research_overrides(capability: str, providers: list[str]) -> list[str]:
-    preferred, disabled, _ = _safe_provider_overrides()
-    allowed = [
-        provider
-        for provider in providers
-        if provider not in disabled and _provider_supports_capability(provider, capability)
-    ]
-    ordered = [
-        provider
-        for provider in preferred
-        if provider in allowed and _provider_supports_capability(provider, capability)
-    ]
-    ordered.extend(provider for provider in allowed if provider not in ordered)
-    return ordered
-
-
-def _research_fetch_order(query: str, url: str = "", capability_status: dict[str, Any] | None = None) -> list[str]:
-    providers = _configured_for_capability("web_fetch", capability_status)
-    target = f"{query} {url}".lower()
-    if _contains_any(target, RESEARCH_JS_HEAVY_KEYWORDS):
-        preferred = ["firecrawl", "tavily", "jina"]
-    elif _contains_any(target, RESEARCH_PDF_KEYWORDS) or url.lower().endswith(".pdf"):
-        preferred = ["jina", "tavily", "firecrawl"]
-    elif url or _extract_urls(query):
-        preferred = ["jina", "tavily", "firecrawl"]
-    else:
-        preferred = providers
-    ordered = [provider for provider in preferred if provider in providers]
-    ordered.extend(provider for provider in providers if provider not in ordered)
-    return _apply_research_overrides("web_fetch", ordered)
-
-
-def _research_route_signals(question: str, plan: dict[str, Any]) -> dict[str, Any]:
-    intent = plan.get("intent_signals") or {}
-    text = question.lower()
-    return {
-        "docs_api_intent": bool(intent.get("docs_api_intent")) or _is_docs_intent(question),
-        "official_low_noise_intent": _contains_any(question, DEEP_EXA_DISCOVERY_KEYWORDS),
-        "current_or_locale_intent": intent.get("recency_requirement") in {"recent", "current"}
-        or intent.get("locale_domain_scope") == "china"
-        or _is_zh_current_intent(question),
-        "known_url": bool(intent.get("known_url")) or bool(_extract_urls(question)),
-        "pdf_or_arxiv_intent": _contains_any(question, RESEARCH_PDF_KEYWORDS),
-        "js_heavy_intent": _contains_any(question, RESEARCH_JS_HEAVY_KEYWORDS),
-        "claim_risk": intent.get("claim_risk", "medium"),
-        "cross_validation_need": intent.get("cross_validation_need", "normal"),
-        "raw_query": text,
-    }
-
-
-def _research_capability_routes(
-    question: str,
-    plan: dict[str, Any],
-    fallback: str,
-    capability_status: dict[str, Any] | None = None,
-) -> dict[str, Any]:
-    signals = _research_route_signals(question, plan)
-    _, _, invalid_overrides = _safe_provider_overrides()
-    routes: dict[str, Any] = {
-        "signals": signals,
-        "fallback_mode": fallback,
-        "route_policy_version": RESEARCH_ROUTE_POLICY_VERSION,
-        "invalid_provider_overrides": invalid_overrides,
-        "capabilities": {},
-    }
-
-    web_search = _configured_for_capability("web_search", capability_status)
-    ordered = [provider for provider in ["tavily", "firecrawl"] if provider in web_search]
-    routes["capabilities"]["web_search"] = {
-        "providers": _apply_research_overrides("web_search", ordered),
-        "reason": (
-            "bilingual current/locale evidence"
-            if signals["current_or_locale_intent"]
-            else "bilingual broad source discovery"
-        ),
-    }
-
-    docs = _configured_for_capability("docs_search", capability_status)
-    docs_order = [provider for provider in ["context7", "exa"] if provider in docs]
-    if signals["official_low_noise_intent"] and not signals["docs_api_intent"]:
-        docs_order = [provider for provider in ["exa", "context7"] if provider in docs]
-    routes["capabilities"]["docs_search"] = {
-        "providers": _apply_research_overrides("docs_search", docs_order),
-        "reason": "docs/API evidence" if signals["docs_api_intent"] else "official low-noise discovery",
-    }
-
-    fetch_order = _research_fetch_order(question, capability_status=capability_status)
-    routes["capabilities"]["web_fetch"] = {
-        "providers": fetch_order,
-        "reason": "JS-heavy fetch" if signals["js_heavy_intent"] else ("known URL/PDF extraction" if signals["known_url"] or signals["pdf_or_arxiv_intent"] else "evidence extraction"),
-    }
-
-    return routes
-
-
-def _research_evidence_item(
-    *,
-    url: str,
-    provider: str,
-    title: str = "",
-    content: str = "",
-    source_type: str = "fetched_page",
-    subquestion_id: str = "",
-) -> dict[str, Any]:
-    digest = hashlib.sha1(f"{url}\n{provider}\n{title}".encode("utf-8")).hexdigest()[:12]
-    return {
-        "id": f"e{digest}",
-        "url": url,
-        "title": title or url,
-        "provider": provider,
-        "source_type": source_type,
-        "subquestion_id": subquestion_id,
-        "content": content,
-        "content_len": len(content or ""),
-        "verified": bool(content and content.strip()),
-    }
-
-
-def _citation_items(evidence_items: list[dict[str, Any]]) -> list[dict[str, str]]:
-    citations: list[dict[str, str]] = []
-    seen: set[str] = set()
-    for item in evidence_items:
-        url = item.get("url", "")
-        if not url or url in seen:
-            continue
-        seen.add(url)
-        citations.append({
-            "url": url,
-            "title": item.get("title") or url,
-            "provider": item.get("provider") or "",
-        })
-    return citations
-
-
-def _evidence_only_synthesis(question: str, evidence_items: list[dict[str, Any]], gaps: list[dict[str, Any]]) -> str:
-    if not evidence_items:
-        return (
-            f"未能为 `{question}` 获取可引用的页面正文证据。"
-            "本次 research 已停止在降级状态，未对缺证据的结论做断言。"
-        )
-    lines = [f"Research result for: {question}", ""]
-    lines.append("Evidence-backed findings:")
-    for index, item in enumerate(evidence_items, 1):
-        content = re.sub(r"\s+", " ", (item.get("content") or "").strip())
-        excerpt = content[:360]
-        lines.append(f"{index}. {item.get('title') or item.get('url')} ({item.get('provider')})")
-        if excerpt:
-            lines.append(f"   Evidence excerpt: {excerpt}")
-        lines.append(f"   Source: {item.get('url')}")
-    if gaps:
-        lines.extend(["", "Unverified gaps:"])
-        for gap in gaps:
-            lines.append(f"- {gap.get('subquestion_id', '')}: {gap.get('reason', '')}")
-    return "\n".join(lines).strip()
-
-
-def _select_candidate_urls(sources: list[dict[str, Any]], limit: int = 5) -> list[dict[str, Any]]:
-    selected: list[dict[str, Any]] = []
-    seen: set[str] = set()
-    for source in sources:
-        url = (source.get("url") or "").strip()
-        if not url or url.startswith("context7:") or url in seen:
-            continue
-        seen.add(url)
-        selected.append(source)
-        if len(selected) >= limit:
-            break
-    return selected
-
-
-def _artifact_path(evidence_root: str, name: str) -> Path:
-    return Path(evidence_root) / name
-
-
-def _write_research_artifact(evidence_root: str, name: str, data: Any) -> None:
-    root = Path(evidence_root)
-    root.mkdir(parents=True, exist_ok=True)
-    path = _artifact_path(evidence_root, name)
-    if isinstance(data, str):
-        path.write_text(data, encoding="utf-8")
-    else:
-        path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
-
-
-def _is_docs_intent(query: str) -> bool:
-    q = query.lower()
-    if any(keyword in q for keyword in DOCS_INTENT_TEXT_KEYWORDS):
-        return True
-    for keyword in DOCS_INTENT_ASCII_KEYWORDS:
-        pattern = re.escape(keyword).replace(r"\ ", r"\s+")
-        if re.search(rf"(?<![a-z0-9_]){pattern}(?![a-z0-9_])", q):
-            return True
-    return False
-
-
-def _is_zh_current_intent(query: str) -> bool:
-    q = query.lower()
-    return any(keyword in q for keyword in ZH_CURRENT_KEYWORDS)
-
-
-def _is_fetch_intent(query: str) -> bool:
-    q = query.lower()
-    return any(keyword in q for keyword in FETCH_INTENT_KEYWORDS)
-
-
-def _contains_any(query: str, keywords: set[str]) -> bool:
-    q = query.lower()
-    return any(keyword.lower() in q for keyword in keywords)
-
-
-def _extract_urls(query: str) -> list[str]:
-    urls = []
-    for match in re.findall(r"https?://[^\s<>\]\)\"']+", query):
-        cleaned = match.rstrip(".,;，。；)")
-        if cleaned:
-            urls.append(cleaned)
-    return urls
-
-
-def _slugify_query(query: str) -> str:
-    slug = re.sub(r"https?://", "", query.lower())
-    slug = re.sub(r"[^a-z0-9\u4e00-\u9fff]+", "-", slug, flags=re.IGNORECASE)
-    slug = slug.strip("-")
-    return slug[:48] or "deep-research"
-
-
-def _default_evidence_dir(query: str) -> str:
-    timestamp = time.strftime("%Y%m%d-%H%M")
-    return str(config.evidence_dir / f"{timestamp}-{_slugify_query(query)}")
-
-
-def _quote_arg(value: str) -> str:
-    escaped = value.replace("`", "``").replace("$", "`$").replace('"', '`"')
-    return f'"{escaped}"'
-
-
-def _path_join(base: str, filename: str) -> str:
-    return str(Path(base) / filename)
-
-
-def _deep_step(
-    step_id: str,
-    subquestion_id: str,
-    tool: str,
-    purpose: str,
-    command: str,
-    output_path: str,
-) -> dict[str, str]:
-    return {
-        "id": step_id,
-        "subquestion_id": subquestion_id,
-        "tool": tool,
-        "purpose": purpose,
-        "command": command,
-        "output_path": output_path,
-    }
-
-
-def _deep_capability(capability: str, tools: list[str], reason: str) -> dict[str, Any]:
-    return {"capability": capability, "tools": tools, "reason": reason}
-
-
-def _deep_subquestion(sub_id: str, question: str, reason: str, required_capabilities: list[str]) -> dict[str, Any]:
-    return {
-        "id": sub_id,
-        "question": question,
-        "reason": reason,
-        "required_capabilities": required_capabilities,
-    }
-
-
-def _deep_budget(value: str) -> str:
-    budget = (value or "standard").strip().lower()
-    return budget if budget in {"quick", "standard", "deep"} else "standard"
-
-
-def _is_deep_complex(query: str, budget: str) -> bool:
-    q = re.sub(r"https?://[^\s<>\]\)\"']+", "", query)
-    object_separators = len(re.findall(r"[/、,，]| 和 | 与 | vs | VS | versus ", q))
-    return budget == "deep" or _contains_any(query, DEEP_HIGH_COMPLEXITY_KEYWORDS) or object_separators >= 2
-
-
-def build_deep_research_plan(query: str, budget: str = "standard", evidence_dir: str = "") -> dict[str, Any]:
-    start = time.time()
-    question = query.strip()
-    budget = _deep_budget(budget)
-    evidence_root = evidence_dir.strip() or _default_evidence_dir(question)
-    urls = _extract_urls(question)
-    known_url = bool(urls)
-    docs_intent = _is_docs_intent(question)
-    zh_current_intent = _is_zh_current_intent(question)
-    recency_requirement = "none"
-    if _contains_any(question, DEEP_CURRENT_KEYWORDS) or zh_current_intent:
-        recency_requirement = "current"
-    elif _contains_any(question, {"行情", "价格", "走势", "币圈", "股票", "市场"}) and _contains_any(question, DEEP_RECENT_KEYWORDS):
-        recency_requirement = "current"
-    elif _contains_any(question, DEEP_RECENT_KEYWORDS):
-        recency_requirement = "recent"
-    locale_domain_scope = "china" if _contains_any(question, DEEP_CHINA_KEYWORDS) else "global"
-    if known_url:
-        locale_domain_scope = "known_domains"
-    claim_risk = "high" if recency_requirement in {"recent", "current"} or _contains_any(question, {"核验", "验证", "真假", "价格", "行情", "财经", "医疗", "政策", "监管", "risk"}) else "medium"
-    cross_validation_need = "high" if claim_risk == "high" or _contains_any(question, {"对比", "选型", "核验", "验证", "compare", "versus"}) else "normal"
-    authority_need = "high" if docs_intent or claim_risk == "high" or _contains_any(question, {"官方", "文档", "论文", "标准", "政策", "监管", "official"}) else "normal"
-    complex_query = _is_deep_complex(question, budget)
-    difficulty = "high" if complex_query else "standard"
-
-    intent_signals = {
-        "recency_requirement": recency_requirement,
-        "docs_api_intent": docs_intent,
-        "locale_domain_scope": locale_domain_scope,
-        "known_url": known_url,
-        "source_authority_need": authority_need,
-        "claim_risk": claim_risk,
-        "cross_validation_need": cross_validation_need,
-        "breadth_depth_budget": budget,
-    }
-
-    decomposition: list[dict[str, Any]] = []
-    capability_plan: list[dict[str, Any]] = []
-    steps: list[dict[str, str]] = []
-
-    def add_step(sub_id: str, tool: str, purpose: str, command: str, filename: str) -> None:
-        step_id = f"s{len(steps) + 1}"
-        steps.append(_deep_step(step_id, sub_id, tool, purpose, command, _path_join(evidence_root, filename)))
-
-    def next_filename(suffix: str) -> str:
-        return f"{len(steps) + 1:02d}-{suffix}"
-
-    def command_search(q: str, extra_sources: int = 2, filename: str = "") -> str:
-        output_name = filename or next_filename("search.json")
-        return f"smart-search search {_quote_arg(q)} --validation balanced --extra-sources {extra_sources} --format json --output {_quote_arg(_path_join(evidence_root, output_name))}"
-
-    def command_exa(q: str) -> str:
-        return f"smart-search exa-search {_quote_arg(q)} --num-results 5 --format json --output {_quote_arg(_path_join(evidence_root, next_filename('exa.json')))}"
-
-    def command_fetch(target: str = "<key-url>") -> str:
-        return f"smart-search fetch {_quote_arg(target)} --format markdown --output {_quote_arg(_path_join(evidence_root, next_filename('fetch.md')))}"
-
-    def add_bilingual_search_steps(sub_id: str, purpose: str, extra_sources: int) -> None:
-        for variant in _bilingual_search_queries(question):
-            filename = next_filename(f"search-{variant['locale']}.json")
-            add_step(
-                sub_id,
-                "search",
-                f"{purpose}: {variant['label']}",
-                command_search(variant["query"], extra_sources, filename),
-                filename,
-            )
-
-    def has_capability(name: str) -> bool:
-        return any(item.get("capability") == name for item in capability_plan)
-
-    if known_url:
-        url = urls[0]
-        parsed = urlparse(url)
-        host = parsed.netloc or "provided URL"
-        decomposition.append(
-            _deep_subquestion(
-                "sq1",
-                f"这个已知来源页面本身说了什么？{url}",
-                "用户已经给出 URL，Deep Research 必须先抓正文再扩展。",
-                ["page_evidence"],
-            )
-        )
-        decomposition.append(
-            _deep_subquestion(
-                "sq2",
-                f"围绕 {host} 还需要哪些相邻来源或交叉来源？",
-                "已知好 URL 适合用相似页面和广泛发现扩展证据。",
-                ["adjacent_source_discovery", "broad_discovery"],
-            )
-        )
-        capability_plan.extend(
-            [
-                _deep_capability("page_evidence", ["fetch"], "Fetch the user-provided URL before making claims."),
-                _deep_capability("adjacent_source_discovery", ["exa-similar"], "Find pages adjacent to the known source."),
-                _deep_capability("broad_discovery", ["search"], "Broaden the context if the fetched page leaves gaps."),
-            ]
-        )
-        add_step("sq1", "fetch", "fetch user supplied URL first", f"smart-search fetch {_quote_arg(url)} --format markdown --output {_quote_arg(_path_join(evidence_root, '01-fetch.md'))}", "01-fetch.md")
-        add_step("sq2", "exa-similar", "find adjacent sources from the provided URL", f"smart-search exa-similar {_quote_arg(url)} --num-results 5 --format json --output {_quote_arg(_path_join(evidence_root, '02-similar.json'))}", "02-similar.json")
-        add_bilingual_search_steps("sq2", "broad discovery for missing context", 1)
-    else:
-        decomposition.append(
-            _deep_subquestion(
-                "sq1",
-                f"{question} 的整体问题轮廓和候选来源是什么？",
-                "先做 broad discovery，避免一开始把问题拆错。",
-                ["broad_discovery"],
-            )
-        )
-        capability_plan.append(_deep_capability("broad_discovery", ["search"], "Find the initial answer shape and candidate sources."))
-        add_bilingual_search_steps("sq1", "bilingual broad discovery and routing metadata", 1 if budget == "quick" else 3)
-
-        if docs_intent:
-            decomposition.append(
-                _deep_subquestion(
-                    "sq2",
-                    f"{question} 的官方文档、API 或 SDK 证据在哪里？",
-                    "docs/API intent should resolve the library docs first, with Exa only as official-domain discovery.",
-                    ["docs_source_discovery", "page_evidence"],
-                )
-            )
-            capability_plan.append(
-                _deep_capability(
-                    "docs_source_discovery",
-                    ["context7-library", "context7-docs"],
-                    "Resolve official library/API documentation first; use Exa only for official-domain or supplemental discovery.",
-                )
-            )
-            library_hint = " ".join(re.findall(r"[A-Za-z][A-Za-z0-9_.-]*", question)[:2]) or "<library-name>"
-            add_step(
-                "sq2",
-                "context7-library",
-                "resolve library id for docs/API intent",
-                f"smart-search context7-library {_quote_arg(library_hint)} {_quote_arg(question)} --format json --output {_quote_arg(_path_join(evidence_root, next_filename('context7-library.json')))}",
-                next_filename("context7-library.json"),
-            )
-            add_step(
-                "sq2",
-                "context7-docs",
-                "retrieve docs after selecting the best library_id",
-                f"smart-search context7-docs {_quote_arg('<library_id>')} {_quote_arg(question)} --format json --output {_quote_arg(_path_join(evidence_root, next_filename('context7-docs.json')))}",
-                next_filename("context7-docs.json"),
-            )
-            if _contains_any(question, DEEP_EXA_DISCOVERY_KEYWORDS):
-                capability_plan.append(
-                    _deep_capability(
-                        "official_domain_discovery",
-                        ["exa-search"],
-                        "Use Exa for official-domain or low-noise supplemental docs discovery.",
-                    )
-                )
-                add_step("sq2", "exa-search", "official-domain docs source discovery", command_exa(f"{question} official docs"), next_filename("exa.json"))
-
-        if recency_requirement != "none" or locale_domain_scope == "china":
-            sub_id = f"sq{len(decomposition) + 1}"
-            decomposition.append(
-                _deep_subquestion(
-                    sub_id,
-                    f"{question} 的最新或中文/国内来源如何交叉验证？",
-                    "Current or China-scoped prompts use bilingual search instead of Zhipu reinforcement.",
-                    ["current_or_locale_source_discovery"],
-                )
-            )
-            capability_plan.append(
-                _deep_capability("current_or_locale_source_discovery", ["search"], "Use Chinese and English broad search for current or locale-sensitive evidence.")
-            )
-
-        if complex_query:
-            while len(decomposition) < (2 if budget != "deep" else 4):
-                sub_id = f"sq{len(decomposition) + 1}"
-                if len(decomposition) == 1:
-                    sub_question = f"{question} 里有哪些主要选项、说法或路线需要分别验证？"
-                    reason = "Complex prompts need explicit comparison targets before final synthesis."
-                    caps = ["cross_validation"]
-                elif len(decomposition) == 2:
-                    sub_question = f"{question} 的成本、风险、限制和适用边界是什么？"
-                    reason = "High-difficulty research needs downside and boundary checks."
-                    caps = ["low_noise_source_discovery", "page_evidence"]
-                else:
-                    sub_question = f"基于已抓取证据，{question} 应该如何形成可执行结论？"
-                    reason = "A deep budget should reserve one synthesis-oriented gap check subquestion."
-                    caps = ["gap_check"]
-                decomposition.append(_deep_subquestion(sub_id, sub_question, reason, caps))
-            if not has_capability("cross_validation"):
-                capability_plan.append(
-                    _deep_capability("cross_validation", ["search"], "Compare independent sources before final claims; supplemental tools depend on intent.")
-                )
-            if budget == "deep" and _contains_any(question, DEEP_EXA_DISCOVERY_KEYWORDS):
-                add_step("sq3", "exa-search", "low-noise evidence for tradeoffs and risks", command_exa(f"{question} risks limitations comparison"), next_filename("exa.json"))
-
-        if cross_validation_need == "high":
-            if not has_capability("cross_validation"):
-                capability_plan.append(
-                    _deep_capability("cross_validation", ["search"], "Compare independent sources before final claims; supplemental tools depend on intent.")
-                )
-            target_subquestion = decomposition[-1]["id"] if decomposition else "sq1"
-            cross_validation_tools = next((item["tools"] for item in capability_plan if item.get("capability") == "cross_validation"), [])
-            if recency_requirement != "none" or locale_domain_scope == "china" or zh_current_intent:
-                if "search" not in cross_validation_tools:
-                    cross_validation_tools.append("search")
-                if not any(
-                    step["tool"] == "search" and "English-language sources" in step.get("purpose", "")
-                    for step in steps
-                ):
-                    add_bilingual_search_steps(target_subquestion, "current or locale-specific cross-source discovery", 2)
-            elif docs_intent:
-                if "context7-library" not in cross_validation_tools:
-                    cross_validation_tools.extend(["context7-library", "context7-docs"])
-            elif _contains_any(question, DEEP_EXA_DISCOVERY_KEYWORDS):
-                if "exa-search" not in cross_validation_tools:
-                    cross_validation_tools.append("exa-search")
-                if not any(step["tool"] == "exa-search" for step in steps):
-                    add_step(target_subquestion, "exa-search", "official-domain or low-noise cross-source discovery", command_exa(question), next_filename("exa.json"))
-
-        capability_plan.append(_deep_capability("page_evidence", ["fetch"], "Fetch key URLs before claim-level conclusions."))
-        add_step("sq1" if len(decomposition) == 1 else decomposition[-1]["id"], "fetch", "fetch key URLs before final claims", command_fetch(), next_filename("fetch.md"))
-
-    for item in capability_plan:
-        item["tools"] = [tool for tool in item["tools"] if tool in DEEP_ALLOWED_TOOLS]
-    steps = [step for step in steps if step["tool"] in DEEP_ALLOWED_TOOLS]
-    if budget == "quick" and len(decomposition) > 2:
-        decomposition = decomposition[:2]
-    if budget == "quick" and len(steps) > 4:
-        limited_steps = steps[:4]
-        if not any(step["tool"] == "fetch" for step in limited_steps):
-            first_fetch = next((step for step in steps if step["tool"] == "fetch"), None)
-            if first_fetch:
-                first_fetch = dict(first_fetch)
-                fetch_path = _path_join(evidence_root, "04-fetch.md")
-                first_fetch["command"] = f"smart-search fetch {_quote_arg('<key-url>')} --format markdown --output {_quote_arg(fetch_path)}"
-                first_fetch["output_path"] = fetch_path
-                limited_steps = steps[:3] + [first_fetch]
-        steps = limited_steps[:4]
-    if budget == "quick":
-        valid_subquestion_ids = {item["id"] for item in decomposition}
-        fallback_subquestion_id = decomposition[-1]["id"] if decomposition else "sq1"
-        for index, step in enumerate(steps, start=1):
-            step["id"] = f"s{index}"
-            if step.get("subquestion_id") not in valid_subquestion_ids:
-                step["subquestion_id"] = fallback_subquestion_id
-
-    return {
-        "ok": True,
-        "mode": "deep_research",
-        "query_mode": "research",
-        "question": question,
-        "trigger_source": "explicit_cli",
-        "difficulty": difficulty,
-        "intent_signals": intent_signals,
-        "decomposition": decomposition,
-        "capability_plan": capability_plan,
-        "evidence_policy": "fetch_before_claim",
-        "preflight": {
-            "tool": "doctor",
-            "command": "smart-search doctor --format json",
-            "when": "configuration or provider availability is uncertain",
-            "executed_during_planning": False,
-        },
-        "steps": steps,
-        "gap_check": {
-            "required": True,
-            "rule": "fetch missing evidence for key claims or downgrade unsupported claims to unverified candidates",
-            "unsupported_claim_action": "downgrade_to_unverified_candidate",
-        },
-        "final_answer_policy": "cite fetched evidence, list unverified candidates, and include key commands",
-        "usage_boundary": {
-            "search": "smart-search search runs live fast/broad search immediately.",
-            "research": "smart-search research builds this plan internally, then runs the staged discover/fetch/synthesis workflow.",
-            "execution": "research executes the listed steps with existing CLI commands, then performs gap_check.",
-        },
-        "allowed_tools": sorted(DEEP_ALLOWED_TOOLS),
-        "evidence_dir": evidence_root,
-        "elapsed_ms": _elapsed_ms(start),
-    }
-
-
-async def research(
-    query: str,
-    budget: str = "deep",
-    evidence_dir: str = "",
-    fallback: str = "auto",
-) -> dict[str, Any]:
-    start = time.time()
-    question = query.strip()
-    fallback_mode = (fallback or "auto").strip().lower()
-    if fallback_mode not in {"auto", "off"}:
-        return {
-            "ok": False,
-            "error_type": "parameter_error",
-            "error": f"Invalid fallback mode: {fallback_mode}",
-            "question": question,
-            "mode": "deep_research_execution",
-            "route_policy_version": RESEARCH_ROUTE_POLICY_VERSION,
-            "elapsed_ms": _elapsed_ms(start),
-        }
-
-    minimum = validate_minimum_profile()
-    if not minimum.get("ok"):
-        return {
-            "ok": False,
-            "error_type": minimum.get("error_type", "config_error"),
-            "error": minimum.get("error", MINIMUM_PROFILE_ERROR),
-            "question": question,
-            "mode": "deep_research_execution",
-            "minimum_profile_ok": False,
-            "capability_status": minimum.get("capability_status", {}),
-            "final_answer": "",
-            "citations": [],
-            "evidence_items": [],
-            "gap_check": {
-                "status": "failed",
-                "gaps": [{"subquestion_id": "", "reason": "minimum profile is missing required capabilities"}],
-            },
-            "provider_attempts": [],
-            "fallback_used": False,
-            "degraded": True,
-            "route_policy_version": RESEARCH_ROUTE_POLICY_VERSION,
-            "evidence_dir": evidence_dir,
-            "elapsed_ms": _elapsed_ms(start),
-        }
-
-    plan = build_deep_research_plan(question, budget=_deep_budget(budget or "deep"), evidence_dir=evidence_dir)
-    evidence_root = plan.get("evidence_dir") or _default_evidence_dir(question)
-    routes = _research_capability_routes(question, plan, fallback_mode)
-    provider_attempts: list[dict[str, Any]] = []
-    discovery_sources: list[dict[str, Any]] = []
-    evidence_items: list[dict[str, Any]] = []
-    stage_results: list[dict[str, Any]] = []
-    gaps: list[dict[str, Any]] = []
-
-    _write_research_artifact(evidence_root, "00-plan.json", plan)
-
-    urls = _extract_urls(question)
-    fetch_order = routes["capabilities"]["web_fetch"]["providers"]
-    if urls:
-        for index, url in enumerate(urls, 1):
-            fetch_result, attempts = await _run_web_fetch_fallback(url, fallback=fallback_mode, preferred_order=fetch_order)
-            provider_attempts.extend(attempts)
-            stage_results.append({"stage": "known_url_fetch", "url": url, "ok": bool(fetch_result), "provider_attempts": attempts})
-            if fetch_result:
-                item = _research_evidence_item(
-                    url=fetch_result["url"],
-                    provider=fetch_result["provider"],
-                    title=fetch_result["url"],
-                    content=fetch_result["content"],
-                    subquestion_id="sq1",
-                )
-                evidence_items.append(item)
-                _write_research_artifact(evidence_root, f"{index:02d}-fetch-{fetch_result['provider']}.md", fetch_result["content"])
-            else:
-                gaps.append({"subquestion_id": "sq1", "reason": f"failed to fetch known URL: {url}", "url": url})
-
-    signals = routes["signals"]
-    if signals["docs_api_intent"]:
-        docs_providers = routes["capabilities"]["docs_search"]["providers"]
-        selected_docs_providers = docs_providers[:1] if fallback_mode == "off" else docs_providers
-        if not selected_docs_providers:
-            gaps.append({"subquestion_id": "sq2", "reason": "no configured docs_search provider for docs/API evidence"})
-        for provider in selected_docs_providers:
-            step_start = time.time()
-            if provider == "context7":
-                data = await context7_library(question, question)
-                if data.get("ok") and data.get("results"):
-                    provider_attempts.append(_attempt("docs_search", "context7", "ok", step_start, result_count=len(data.get("results") or [])))
-                    stage_results.append({"stage": "docs_discovery", "provider": "context7", "ok": True, "result_count": len(data.get("results") or [])})
-                    library_id = (data.get("results") or [{}])[0].get("id", "")
-                    if library_id:
-                        docs_start = time.time()
-                        docs_data = await context7_docs(library_id, question)
-                        if docs_data.get("ok") and docs_data.get("content"):
-                            provider_attempts.append(_attempt("docs_search", "context7", "ok", docs_start, result_count=1))
-                            item = _research_evidence_item(
-                                url=f"context7:{library_id}",
-                                provider="context7",
-                                title=library_id,
-                                content=docs_data.get("content", ""),
-                                source_type="docs",
-                                subquestion_id="sq2",
-                            )
-                            evidence_items.append(item)
-                            _write_research_artifact(evidence_root, "docs-context7.md", docs_data.get("content", ""))
-                            break
-                        docs_status = "error" if docs_data.get("error_type") else "empty"
-                        provider_attempts.append(_attempt("docs_search", "context7", docs_status, docs_start, error_type=docs_data.get("error_type", ""), error=docs_data.get("error", "")))
-                    if fallback_mode == "off":
-                        break
-                    continue
-                status = "error" if data.get("error_type") in {"auth_error", "timeout", "network_error", "runtime_error"} else "empty"
-                provider_attempts.append(_attempt("docs_search", "context7", status, step_start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-            elif provider == "exa":
-                data = await exa_search(question, num_results=5, include_highlights=True)
-                if data.get("ok"):
-                    sources = _normalize_source_results(data.get("results"), "exa")
-                    if sources:
-                        provider_attempts.append(_attempt("docs_search", "exa", "ok", step_start, result_count=len(sources)))
-                        discovery_sources.extend(sources)
-                        stage_results.append({"stage": "docs_discovery", "provider": "exa", "ok": True, "result_count": len(sources)})
-                        break
-                provider_attempts.append(_attempt("docs_search", "exa", "error" if data.get("error_type") else "empty", step_start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-
-    should_run_web_discovery = (
-        signals["current_or_locale_intent"]
-        or signals["cross_validation_need"] == "high"
-        or (not evidence_items and not discovery_sources)
-    ) and not (urls and fallback_mode == "off")
-    if should_run_web_discovery:
-        web_provider_order = routes["capabilities"]["web_search"]["providers"]
-        if web_provider_order:
-            web_sources, attempts = await _run_bilingual_web_search(
-                question,
-                count=5,
-                providers=",".join(web_provider_order),
-                fallback=fallback_mode,
-            )
-            provider_attempts.extend(attempts)
-            discovery_sources.extend(web_sources)
-            stage_results.append({"stage": "web_discovery", "ok": bool(web_sources), "result_count": len(web_sources), "provider_attempts": attempts})
-        else:
-            gaps.append({"subquestion_id": "", "reason": "no configured web_search provider for discovery"})
-
-    exa_in_selected_docs_route = "exa" in routes["capabilities"]["docs_search"]["providers"]
-    if (
-        fallback_mode != "off"
-        and signals["official_low_noise_intent"]
-        and exa_in_selected_docs_route
-        and not any(source.get("provider") == "exa" for source in discovery_sources)
-    ):
-        exa_start = time.time()
-        data = await exa_search(question, num_results=5, include_highlights=True)
-        if data.get("ok"):
-            sources = _normalize_source_results(data.get("results"), "exa")
-            if sources:
-                provider_attempts.append(_attempt("docs_search", "exa", "ok", exa_start, result_count=len(sources)))
-                discovery_sources.extend(sources)
-        else:
-            provider_attempts.append(_attempt("docs_search", "exa", "error", exa_start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-
-    candidates = _select_candidate_urls(discovery_sources, limit=6)
-    fetched_urls = {item.get("url") for item in evidence_items}
-    no_new_evidence = True
-    for index, candidate in enumerate(candidates, 1):
-        url = candidate.get("url", "")
-        if not url or url in fetched_urls:
-            continue
-        order = _research_fetch_order(question, url)
-        fetch_result, attempts = await _run_web_fetch_fallback(url, fallback=fallback_mode, preferred_order=order)
-        provider_attempts.extend(attempts)
-        stage_results.append({"stage": "candidate_fetch", "url": url, "ok": bool(fetch_result), "provider_attempts": attempts})
-        if fetch_result:
-            no_new_evidence = False
-            fetched_urls.add(url)
-            content = fetch_result.get("content", "")
-            item = _research_evidence_item(
-                url=fetch_result["url"],
-                provider=fetch_result["provider"],
-                title=candidate.get("title") or fetch_result["url"],
-                content=content,
-                subquestion_id=candidate.get("subquestion_id", ""),
-            )
-            evidence_items.append(item)
-            _write_research_artifact(evidence_root, f"fetch-{index:02d}-{fetch_result['provider']}.md", content)
-        elif fallback_mode == "off":
-            gaps.append({"subquestion_id": "", "reason": f"fetch failed with fallback off: {url}", "url": url})
-
-    if not evidence_items:
-        gaps.append({"subquestion_id": "", "reason": "no fetched/read evidence items were produced"})
-    elif no_new_evidence and not urls and candidates:
-        gaps.append({"subquestion_id": "", "reason": "discovery produced candidates but no new fetch evidence converged"})
-
-    covered = bool(evidence_items)
-    gap_status = "closed" if covered and not gaps else ("degraded" if evidence_items else "failed")
-    citations = _citation_items(evidence_items)
-    final_answer = _evidence_only_synthesis(question, evidence_items, gaps)
-    result = {
-        "ok": bool(evidence_items),
-        "error_type": "" if evidence_items else "evidence_error",
-        "error": "" if evidence_items else "research could not obtain fetched evidence",
-        "mode": "deep_research_execution",
-        "query_mode": "research",
-        "question": question,
-        "budget": _deep_budget(budget or "deep"),
-        "research_plan": plan,
-        "routing_decision": routes,
-        "stage_results": stage_results,
-        "discovery_sources": discovery_sources,
-        "final_answer": final_answer,
-        "content": final_answer,
-        "citations": citations,
-        "evidence_items": evidence_items,
-        "gap_check": {
-            "status": gap_status,
-            "gaps": gaps,
-            "stop_reason": "evidence_converged" if gap_status == "closed" else ("degraded_with_gaps" if evidence_items else "provider_exhausted"),
-        },
-        "provider_attempts": provider_attempts,
-        "providers_used": _provider_names_from_attempts(provider_attempts),
-        "fallback_used": _fallback_used(provider_attempts),
-        "degraded": bool(gaps),
-        "route_policy_version": RESEARCH_ROUTE_POLICY_VERSION,
-        "evidence_dir": evidence_root,
-        "minimum_profile_ok": minimum.get("ok", False),
-        "capability_status": minimum.get("capability_status", {}),
-        "elapsed_ms": _elapsed_ms(start),
-    }
-    _write_research_artifact(evidence_root, "summary.json", result)
-    return result
-
-
-def get_capability_status() -> dict[str, Any]:
-    main_configured = _configured_main_search_provider_ids()
-    status = {
-        "main_search": {
-            "configured": main_configured,
-            "fallback_chain": MAIN_SEARCH_FALLBACK_CHAIN,
-            "ok": bool(main_configured),
-        },
-        "web_search": {
-            "configured": [
-                name
-                for name, enabled in [
-                    ("tavily", bool(config.tavily_api_key)),
-                    ("firecrawl", bool(config.firecrawl_api_key)),
-                ]
-                if enabled
-            ],
-            "fallback_chain": ["tavily", "firecrawl"],
-            "deprecated_configured": ["zhipu"] if config.zhipu_api_key else [],
-        },
-        "docs_search": {
-            "configured": [
-                name
-                for name, enabled in [
-                    ("context7", bool(config.context7_api_key)),
-                    ("exa", bool(config.exa_api_key)),
-                ]
-                if enabled
-            ],
-            "fallback_chain": ["context7", "exa"],
-        },
-        "web_fetch": {
-            "configured": [
-                name
-                for name, enabled in [
-                    ("tavily", bool(config.tavily_api_key)),
-                    ("jina", bool(config.jina_api_key)),
-                    ("firecrawl", bool(config.firecrawl_api_key)),
-                ]
-                if enabled
-            ],
-            "fallback_chain": ["tavily", "jina", "firecrawl"],
-        },
-    }
-    for capability in ("web_search", "docs_search", "web_fetch"):
-        status[capability]["ok"] = bool(status[capability]["configured"])
-    return status
-
-
-def _minimum_profile_result(profile: str, capability_status: dict[str, Any]) -> dict[str, Any]:
-    required = [] if profile == "off" else ["main_search", "docs_search", "web_fetch"]
-    missing = [capability for capability in required if not capability_status.get(capability, {}).get("ok")]
-    return {
-        "ok": not missing,
-        "error_type": "config_error" if missing else "",
-        "error": f"{MINIMUM_PROFILE_ERROR} 缺失能力: {', '.join(missing)}" if missing else "",
-        "profile": profile,
-        "required": required,
-        "missing": missing,
-        "capability_status": capability_status,
-    }
-
-
-def validate_minimum_profile() -> dict[str, Any]:
-    try:
-        profile = config.minimum_profile
-    except ValueError as e:
-        return {"ok": False, "error_type": "parameter_error", "error": str(e), "missing": []}
-    return _minimum_profile_result(profile, get_capability_status())
-
-
-def _parse_provider_filter(providers: str = "auto") -> set[str] | None:
-    if not providers or providers.strip().lower() == "auto":
-        return None
-    return {item.strip().lower() for item in providers.split(",") if item.strip()}
-
-
-def _provider_allowed(provider_id: str, provider_filter: set[str] | None) -> bool:
-    if provider_filter is None:
-        return True
-    aliases = MAIN_SEARCH_PROVIDER_ALIASES.get(provider_id, {provider_id})
-    return bool(provider_filter.intersection(aliases))
-
-
-def _configured_main_search_provider_ids() -> list[str]:
-    configured: set[str] = set()
-
-    if config.openai_compatible_api_url and config.openai_compatible_api_key:
-        configured.add("openai-compatible")
-
-    return [provider for provider in MAIN_SEARCH_FALLBACK_CHAIN if provider in configured]
-
-
-def _main_search_provider_configs(model_override: str = "", providers: str = "auto") -> list[dict[str, Any]]:
-    provider_filter = _parse_provider_filter(providers)
-    by_provider: dict[str, dict[str, Any]] = {}
-
-    if config.openai_compatible_api_url and config.openai_compatible_api_key:
-        by_provider["openai-compatible"] = {
-            "provider": "openai-compatible",
-            "mode": "chat-completions",
-            "api_url": config.openai_compatible_api_url,
-            "api_key": config.openai_compatible_api_key,
-            "model": model_override or config.openai_compatible_model,
-            "stream": config.openai_compatible_stream,
-            "tools": [],
-            "source": "OPENAI_COMPATIBLE_*",
-        }
-
-    return [
-        by_provider[provider]
-        for provider in MAIN_SEARCH_FALLBACK_CHAIN
-        if provider in by_provider and _provider_allowed(provider, provider_filter)
-    ]
-
-
-def _main_search_providers(provider_configs: list[dict[str, Any]], fallback: str) -> list[Any]:
-    selected = provider_configs if fallback != "off" else provider_configs[:1]
-    providers: list[Any] = []
-    for provider_config in selected:
-        providers.append(
-            OpenAICompatibleSearchProvider(
-                provider_config["api_url"],
-                provider_config["api_key"],
-                provider_config["model"],
-                provider_config.get("stream", False),
-            )
-        )
-    return providers
-
-
-async def fetch_available_models(api_url: str, api_key: str) -> list[str]:
-    models_url = f"{api_url.rstrip('/')}/models"
-    async with httpx.AsyncClient(timeout=10.0) as client:
-        response = await client.get(
-            models_url,
-            headers={
-                "Authorization": f"Bearer {api_key}",
-                "Content-Type": "application/json",
-            },
-        )
-        response.raise_for_status()
-        data = response.json()
-
-    models: list[str] = []
-    for item in (data or {}).get("data", []) or []:
-        if isinstance(item, dict) and isinstance(item.get("id"), str):
-            models.append(item["id"])
-    return models
-
-
-async def get_available_models_cached(api_url: str, api_key: str) -> list[str]:
-    key = (api_url, api_key)
-    async with _AVAILABLE_MODELS_LOCK:
-        if key in _AVAILABLE_MODELS_CACHE:
-            return _AVAILABLE_MODELS_CACHE[key]
-
-    try:
-        models = await fetch_available_models(api_url, api_key)
-    except Exception:
-        models = []
-
-    async with _AVAILABLE_MODELS_LOCK:
-        _AVAILABLE_MODELS_CACHE[key] = models
-    return models
-
-
-def extra_results_to_sources(
-    tavily_results: list[dict] | None,
-    firecrawl_results: list[dict] | None,
-) -> list[dict]:
-    sources: list[dict] = []
-    seen: set[str] = set()
-
-    if firecrawl_results:
-        for r in firecrawl_results:
-            url = (r.get("url") or "").strip()
-            if not url or url in seen:
-                continue
-            seen.add(url)
-            item: dict = {"url": url, "provider": "firecrawl"}
-            title = (r.get("title") or "").strip()
-            if title:
-                item["title"] = title
-            desc = (r.get("description") or "").strip()
-            if desc:
-                item["description"] = desc
-            sources.append(item)
-
-    if tavily_results:
-        for r in tavily_results:
-            url = (r.get("url") or "").strip()
-            if not url or url in seen:
-                continue
-            seen.add(url)
-            item = {"url": url, "provider": "tavily"}
-            title = (r.get("title") or "").strip()
-            if title:
-                item["title"] = title
-            content = (r.get("content") or "").strip()
-            if content:
-                item["description"] = content
-            sources.append(item)
-
-    return sources
-
-
-async def _run_web_fetch_fallback(
-    url: str,
-    fallback: str = "auto",
-    preferred_order: list[str] | None = None,
-) -> tuple[dict[str, Any] | None, list[dict]]:
-    attempts: list[dict] = []
-    providers = []
-    if config.tavily_api_key:
-        providers.append("tavily")
-    if config.jina_api_key:
-        providers.append("jina")
-    if config.firecrawl_api_key:
-        providers.append("firecrawl")
-    if preferred_order:
-        allowed = {provider for provider in providers}
-        ordered = [provider for provider in preferred_order if provider in allowed]
-        ordered.extend(provider for provider in providers if provider not in ordered)
-        providers = ordered
-    if fallback == "off":
-        providers = providers[:1]
-
-    for provider in providers:
-        start = time.time()
-        try:
-            if provider == "tavily":
-                content = await call_tavily_extract(url)
-            elif provider == "jina":
-                data = await jina_fetch(url)
-                content = data.get("content") if data.get("ok") else None
-                if not data.get("ok"):
-                    status = "error" if data.get("error_type") in {"auth_error", "config_error", "parameter_error", "quality_error", "rate_limited", "timeout", "network_error", "runtime_error"} else "empty"
-                    attempts.append(_attempt("web_fetch", provider, status, start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-                    continue
-            else:
-                content = await call_firecrawl_scrape(url)
-            if content and content.strip():
-                attempts.append(_attempt("web_fetch", provider, "ok", start, result_count=1))
-                return {
-                    "ok": True,
-                    "url": url,
-                    "provider": provider,
-                    "content": content,
-                }, attempts
-            attempts.append(_attempt("web_fetch", provider, "empty", start))
-        except Exception as e:
-            attempts.append(_attempt("web_fetch", provider, "error", start, error_type="runtime_error", error=str(e)))
-    return None, attempts
-
-
-async def _run_web_search_fallback(
-    query: str,
-    count: int = 5,
-    providers: str = "auto",
-    fallback: str = "auto",
-) -> tuple[list[dict], list[dict]]:
-    provider_filter = _parse_provider_filter(providers)
-    attempts: list[dict] = []
-    configured: list[str] = []
-    if config.tavily_api_key:
-        configured.append("tavily")
-    if config.firecrawl_api_key:
-        configured.append("firecrawl")
-    if provider_filter is not None and "zhipu" in provider_filter and config.zhipu_api_key:
-        configured.append("zhipu")
-    if provider_filter is not None:
-        configured = [p for p in configured if p in provider_filter]
-    if fallback == "off":
-        configured = configured[:1]
-
-    for provider in configured:
-        start = time.time()
-        try:
-            if provider == "zhipu":
-                data = await zhipu_search(query, count=count)
-                if data.get("ok"):
-                    sources = _normalize_source_results(data.get("results"), "zhipu")
-                    if sources:
-                        attempts.append(_attempt("web_search", provider, "ok", start, result_count=len(sources)))
-                        return sources, attempts
-                status = "error" if data.get("error_type") in {"rate_limited", "auth_error", "timeout", "network_error", "runtime_error"} else "empty"
-                attempts.append(_attempt("web_search", provider, status, start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-            elif provider == "tavily":
-                results = await call_tavily_search(query, count)
-                sources = _normalize_source_results(results, "tavily")
-                if sources:
-                    attempts.append(_attempt("web_search", provider, "ok", start, result_count=len(sources)))
-                    return sources, attempts
-                attempts.append(_attempt("web_search", provider, "empty", start))
-            elif provider == "firecrawl":
-                results = await call_firecrawl_search(query, count)
-                sources = _normalize_source_results(results, "firecrawl")
-                if sources:
-                    attempts.append(_attempt("web_search", provider, "ok", start, result_count=len(sources)))
-                    return sources, attempts
-                attempts.append(_attempt("web_search", provider, "empty", start))
-        except Exception as e:
-            attempts.append(_attempt("web_search", provider, "error", start, error_type="runtime_error", error=str(e)))
-    return [], attempts
-
-
-async def _run_bilingual_web_search(
-    query: str,
-    count: int = 5,
-    providers: str = "auto",
-    fallback: str = "auto",
-) -> tuple[list[dict], list[dict]]:
-    all_sources: list[dict] = []
-    all_attempts: list[dict] = []
-    for variant in _bilingual_search_queries(query):
-        sources, attempts = await _run_web_search_fallback(
-            variant["query"],
-            count=count,
-            providers=providers,
-            fallback=fallback,
-        )
-        for source in sources:
-            source.setdefault("query_locale", variant["locale"])
-        all_sources = merge_sources(all_sources, sources)
-        all_attempts.extend(attempts)
-    return all_sources, all_attempts
-
-
-async def _run_docs_search_fallback(
-    query: str,
-    providers: str = "auto",
-    fallback: str = "auto",
-) -> tuple[list[dict], list[dict]]:
-    provider_filter = _parse_provider_filter(providers)
-    attempts: list[dict] = []
-    configured: list[str] = []
-    if config.context7_api_key:
-        configured.append("context7")
-    if config.exa_api_key:
-        configured.append("exa")
-    if provider_filter is not None:
-        configured = [p for p in configured if p in provider_filter]
-    if fallback == "off":
-        configured = configured[:1]
-
-    for provider in configured:
-        start = time.time()
-        try:
-            if provider == "exa":
-                data = await exa_search(query, num_results=5, include_highlights=True)
-                if data.get("ok"):
-                    sources = _normalize_source_results(data.get("results"), "exa")
-                    if sources:
-                        attempts.append(_attempt("docs_search", provider, "ok", start, result_count=len(sources)))
-                        return sources, attempts
-                status = "error" if data.get("error_type") in {"auth_error", "parameter_error", "rate_limited", "timeout", "network_error", "runtime_error"} else "empty"
-                attempts.append(_attempt("docs_search", provider, status, start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-            elif provider == "context7":
-                data = await context7_library(query, query)
-                if data.get("ok"):
-                    sources = [
-                        {
-                            "url": f"context7:{item.get('id')}",
-                            "title": item.get("title") or item.get("id") or "Context7",
-                            "description": item.get("description") or "",
-                            "provider": "context7",
-                        }
-                        for item in data.get("results", [])
-                        if item.get("id")
-                    ]
-                    if sources:
-                        attempts.append(_attempt("docs_search", provider, "ok", start, result_count=len(sources)))
-                        return sources, attempts
-                status = "error" if data.get("error_type") in {"auth_error", "timeout", "network_error", "runtime_error"} else "empty"
-                attempts.append(_attempt("docs_search", provider, status, start, error_type=data.get("error_type", ""), error=data.get("error", "")))
-        except Exception as e:
-            attempts.append(_attempt("docs_search", provider, "error", start, error_type="runtime_error", error=str(e)))
-    return [], attempts
-
-
-async def call_tavily_extract(url: str) -> str | None:
-    api_key = config.tavily_api_key
-    if not api_key:
-        return None
-    endpoint = f"{config.tavily_api_url.rstrip('/')}/extract"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    body = {"urls": [url], "format": "markdown"}
-    try:
-        async with httpx.AsyncClient(timeout=60.0) as client:
-            response = await client.post(endpoint, headers=headers, json=body)
-            response.raise_for_status()
-            data = response.json()
-            if data.get("results") and len(data["results"]) > 0:
-                content = data["results"][0].get("raw_content", "")
-                return content if content and content.strip() else None
-            return None
-    except Exception:
-        return None
-
-
-async def call_tavily_search(query: str, max_results: int = 6) -> list[dict] | None:
-    api_key = config.tavily_api_key
-    if not api_key:
-        return None
-    endpoint = f"{config.tavily_api_url.rstrip('/')}/search"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    body = {
-        "query": query,
-        "max_results": max_results,
-        "search_depth": "advanced",
-        "include_raw_content": False,
-        "include_answer": False,
-    }
-    try:
-        async with httpx.AsyncClient(timeout=90.0) as client:
-            response = await client.post(endpoint, headers=headers, json=body)
-            response.raise_for_status()
-            data = response.json()
-            results = data.get("results", [])
-            return [
-                {
-                    "title": r.get("title", ""),
-                    "url": r.get("url", ""),
-                    "content": r.get("content", ""),
-                    "score": r.get("score", 0),
-                }
-                for r in results
-            ] if results else None
-    except Exception:
-        return None
-
-
-async def call_firecrawl_search(query: str, limit: int = 14) -> list[dict] | None:
-    api_key = config.firecrawl_api_key
-    if not api_key:
-        return None
-    endpoint = f"{config.firecrawl_api_url.rstrip('/')}/search"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    body = {"query": query, "limit": limit}
-    try:
-        async with httpx.AsyncClient(timeout=90.0) as client:
-            response = await client.post(endpoint, headers=headers, json=body)
-            response.raise_for_status()
-            data = response.json()
-            results = data.get("data", {}).get("web", [])
-            return [
-                {
-                    "title": r.get("title", ""),
-                    "url": r.get("url", ""),
-                    "description": r.get("description", ""),
-                }
-                for r in results
-            ] if results else None
-    except Exception:
-        return None
-
-
-async def call_firecrawl_scrape(url: str, ctx=None) -> str | None:
-    api_key = config.firecrawl_api_key
-    if not api_key:
-        return None
-    endpoint = f"{config.firecrawl_api_url.rstrip('/')}/scrape"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    for attempt in range(config.retry_max_attempts):
-        body = {
-            "url": url,
-            "formats": ["markdown"],
-            "timeout": 60000,
-            "waitFor": (attempt + 1) * 1500,
-        }
-        try:
-            async with httpx.AsyncClient(timeout=90.0) as client:
-                response = await client.post(endpoint, headers=headers, json=body)
-                response.raise_for_status()
-                data = response.json()
-                markdown = data.get("data", {}).get("markdown", "")
-                if markdown and markdown.strip():
-                    return markdown
-                await log_info(ctx, f"Firecrawl: markdown为空, 重试 {attempt + 1}/{config.retry_max_attempts}", config.debug_enabled)
-        except Exception as e:
-            await log_info(ctx, f"Firecrawl error: {e}", config.debug_enabled)
-            return None
-    return None
-
-
-async def call_jina_reader(url: str) -> dict[str, Any]:
-    raw = await JinaReaderProvider(
-        config.jina_reader_api_url,
-        config.jina_api_key,
-        config.jina_respond_with,
-        config.jina_timeout,
-    ).fetch(url)
-    return await _decode_provider_json(raw, provider="jina")
-
-
-async def call_tavily_map(
-    url: str,
-    instructions: str = "",
-    max_depth: int = 1,
-    max_breadth: int = 20,
-    limit: int = 50,
-    timeout: int = 150,
-) -> dict[str, Any]:
-    api_key = config.tavily_api_key
-    if not api_key:
-        return {
-            "ok": False,
-            "error_type": "config_error",
-            "error": "TAVILY_API_KEY 未配置。请运行 `smart-search setup`，或使用 `smart-search config set TAVILY_API_KEY <key>`。",
-        }
-
-    endpoint = f"{config.tavily_api_url.rstrip('/')}/map"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    body = {"url": url, "max_depth": max_depth, "max_breadth": max_breadth, "limit": limit, "timeout": timeout}
-    if instructions:
-        body["instructions"] = instructions
-    try:
-        async with httpx.AsyncClient(timeout=float(timeout + 10)) as client:
-            response = await client.post(endpoint, headers=headers, json=body)
-            response.raise_for_status()
-            data = response.json()
-            return {
-                "ok": True,
-                "base_url": data.get("base_url", ""),
-                "results": data.get("results", []),
-                "response_time": data.get("response_time", 0),
-            }
-    except httpx.TimeoutException:
-        return {"ok": False, "error_type": "network_error", "error": f"映射超时: 请求超过{timeout}秒"}
-    except httpx.HTTPStatusError as e:
-        return {"ok": False, "error_type": "network_error", "error": f"HTTP错误: {e.response.status_code} - {e.response.text[:200]}"}
-    except Exception as e:
-        return {"ok": False, "error_type": "network_error", "error": f"映射错误: {str(e)}"}
-
-
-async def search(
-    query: str,
-    platform: str = "",
-    model: str = "",
-    extra_sources: int = 0,
-    validation: str = "",
-    fallback: str = "",
-    providers: str = "auto",
-    stream: bool | None = None,
-) -> dict[str, Any]:
-    start = time.time()
-    session_id = new_session_id()
-    try:
-        validation_level = (validation or config.validation_level).strip().lower()
-        fallback_mode = (fallback or config.fallback_mode).strip().lower()
-        if validation_level not in config._ALLOWED_VALIDATION_LEVELS:
-            raise ValueError(f"Invalid validation level: {validation_level}")
-        if fallback_mode not in config._ALLOWED_FALLBACK_MODES:
-            raise ValueError(f"Invalid fallback mode: {fallback_mode}")
-    except ValueError as e:
-        return _empty_search_result(start, session_id, query, "parameter_error", str(e))
-
-    minimum = validate_minimum_profile()
-    if not minimum.get("ok"):
-        return _empty_search_result(
-            start,
-            session_id,
-            query,
-            minimum.get("error_type", "config_error"),
-            minimum.get("error", MINIMUM_PROFILE_ERROR),
-            extra={
-                "capability_status": minimum.get("capability_status", {}),
-                "minimum_profile_ok": False,
-                "validation_level": validation_level,
-            },
-        )
-
-    try:
-        main_provider_configs = _main_search_provider_configs(model_override=model, providers=providers)
-    except ValueError as e:
-        return _empty_search_result(start, session_id, query, "parameter_error", str(e), extra={"validation_level": validation_level})
-
-    if not main_provider_configs:
-        return _empty_search_result(
-            start,
-            session_id,
-            query,
-            "config_error",
-            "No configured main_search provider matches --providers.",
-            extra={
-                "validation_level": validation_level,
-                "capability_status": minimum.get("capability_status", {}),
-                "minimum_profile_ok": minimum.get("ok", False),
-            },
-        )
-
-    primary_api_mode = main_provider_configs[0]["mode"]
-    if stream is not None:
-        for provider_config in main_provider_configs:
-            if provider_config["provider"] == "openai-compatible":
-                provider_config["stream"] = stream
-
-    has_tavily = bool(config.tavily_api_key)
-    has_firecrawl = bool(config.firecrawl_api_key)
-    tavily_count = 0
-    firecrawl_count = 0
-    if extra_sources > 0:
-        if has_tavily and has_firecrawl:
-            tavily_count = max(1, round(extra_sources * 0.6))
-            firecrawl_count = extra_sources - tavily_count
-        elif has_tavily:
-            tavily_count = extra_sources
-        elif has_firecrawl:
-            firecrawl_count = extra_sources
-
-    docs_intent = _is_docs_intent(query)
-    zh_current_intent = _is_zh_current_intent(query)
-    bilingual_web_search = True
-    web_current_intent = zh_current_intent
-    fetch_urls = _extract_urls(query)
-    fetch_intent = bool(fetch_urls) or _is_fetch_intent(query)
-    supplemental_paths: list[str] = []
-    if docs_intent:
-        supplemental_paths.append("docs_search")
-    if bilingual_web_search:
-        supplemental_paths.append("web_search")
-    if fetch_intent:
-        supplemental_paths.append("web_fetch")
-    selected_main_provider_configs = main_provider_configs if fallback_mode != "off" else main_provider_configs[:1]
-    routing_decision = {
-        "docs_intent": docs_intent,
-        "zh_current_intent": zh_current_intent,
-        "web_current_intent": web_current_intent,
-        "bilingual_web_search": bilingual_web_search,
-        "bilingual_query_locales": [item["locale"] for item in _bilingual_search_queries(query)],
-        "fetch_intent": fetch_intent,
-        "supplemental_paths": supplemental_paths,
-        "validation_level": validation_level,
-        "fallback_mode": fallback_mode,
-        "providers": providers,
-        "main_search_chain": [item["provider"] for item in selected_main_provider_configs],
-        "openai_compatible_stream": next((bool(item.get("stream")) for item in selected_main_provider_configs if item["provider"] == "openai-compatible"), False),
-    }
-
-    provider_attempts: list[dict] = []
-    main_providers = _main_search_providers(main_provider_configs, fallback_mode)
-    primary_start = time.time()
-    primary_result = None
-    successful_main_config: dict[str, Any] | None = None
-    last_primary_error: dict[str, Any] | None = None
-    for provider_config, search_provider in zip(selected_main_provider_configs, main_providers):
-        primary_start = time.time()
-        try:
-            candidate_result = await search_provider.search(query, platform)
-            if candidate_result:
-                primary_result = candidate_result
-                successful_main_config = provider_config
-                provider_attempts.append(_attempt("main_search", search_provider.get_provider_name(), "ok", primary_start, result_count=1))
-                break
-            last_primary_error = _primary_search_error_result(
-                start,
-                session_id,
-                query,
-                provider_config["mode"],
-                "network_error",
-                f"{search_provider.get_provider_name()} 返回空结果",
-            )
-            provider_attempts.append(_attempt("main_search", search_provider.get_provider_name(), "empty", primary_start))
-        except Exception as e:
-            error_result = _primary_search_exception_result(start, session_id, query, provider_config["mode"], search_provider.get_provider_name(), e)
-            last_primary_error = error_result
-            provider_attempts.append(
-                _attempt(
-                    "main_search",
-                    search_provider.get_provider_name(),
-                    "error",
-                    primary_start,
-                    error_type=error_result["error_type"],
-                    error=error_result["error"],
-                )
-            )
-    if primary_result is None:
-        result = last_primary_error or _primary_search_error_result(start, session_id, query, primary_api_mode, "network_error", "搜索失败或无结果")
-        result["provider_attempts"] = provider_attempts
-        result["providers_used"] = _provider_names_from_attempts(provider_attempts)
-        result["fallback_used"] = _fallback_used(provider_attempts)
-        result["routing_decision"] = routing_decision
-        result["validation_level"] = validation_level
-        result["minimum_profile_ok"] = minimum.get("ok", False)
-        result["capability_status"] = minimum.get("capability_status", {})
-        return result
-
-    successful_main_config = successful_main_config or selected_main_provider_configs[0]
-    primary_api_mode = successful_main_config["mode"]
-    effective_model = successful_main_config["model"]
-
-    coros: list[Any] = []
-    if tavily_count:
-        coros.append(call_tavily_search(query, tavily_count))
-    if firecrawl_count:
-        coros.append(call_firecrawl_search(query, firecrawl_count))
-
-    gathered = await asyncio.gather(*coros, return_exceptions=True)
-    primary_result = primary_result or ""
-    tavily_results: list[dict] | None = None
-    firecrawl_results: list[dict] | None = None
-    idx = 0
-    if tavily_count:
-        tavily_results = None if isinstance(gathered[idx], BaseException) else gathered[idx]
-        idx += 1
-    if firecrawl_count:
-        firecrawl_results = None if isinstance(gathered[idx], BaseException) else gathered[idx]
-
-    answer, primary_sources = split_answer_and_sources(primary_result)
-    extra_source_items = extra_results_to_sources(tavily_results, firecrawl_results)
-    for item_provider, results in (("tavily", tavily_results), ("firecrawl", firecrawl_results)):
-        if results:
-            provider_attempts.append(_attempt("web_search", item_provider, "ok", start, result_count=len(results)))
-
-    supplemental_sources: list[dict] = []
-    if validation_level in {"balanced", "strict"}:
-        if docs_intent:
-            docs_sources, docs_attempts = await _run_docs_search_fallback(query, providers=providers, fallback=fallback_mode)
-            provider_attempts.extend(docs_attempts)
-            supplemental_sources.extend(docs_sources)
-        if bilingual_web_search:
-            web_sources, web_attempts = await _run_bilingual_web_search(query, count=max(1, extra_sources or 3), providers=providers, fallback=fallback_mode)
-            provider_attempts.extend(web_attempts)
-            supplemental_sources.extend(web_sources)
-        if fetch_intent:
-            fetch_url = fetch_urls[0] if fetch_urls else query.strip()
-            fetch_result, fetch_attempts = await _run_web_fetch_fallback(fetch_url, fallback=fallback_mode)
-            provider_attempts.extend(fetch_attempts)
-            if fetch_result:
-                supplemental_sources.append({"url": fetch_result["url"], "provider": fetch_result["provider"], "description": fetch_result["content"][:300]})
-
-    extra_source_items = merge_sources(extra_source_items, supplemental_sources)
-    sources = merge_sources(primary_sources, extra_source_items)
-    ok = bool(answer or sources)
-    if validation_level == "strict" and not sources:
-        ok = False
-    return {
-        "ok": ok,
-        "error_type": "" if ok else ("evidence_error" if validation_level == "strict" else "network_error"),
-        "error": "" if ok else ("strict 模式证据不足" if validation_level == "strict" else "搜索失败或无结果"),
-        "session_id": session_id,
-        "query": query,
-        "platform": platform,
-        "model": effective_model,
-        "primary_api_mode": primary_api_mode,
-        "content": answer,
-        "sources": sources,
-        "sources_count": len(sources),
-        "primary_sources": primary_sources,
-        "primary_sources_count": len(primary_sources),
-        "extra_sources": extra_source_items,
-        "extra_sources_count": len(extra_source_items),
-        "source_warning": SOURCE_PROVENANCE_WARNING if extra_source_items else "",
-        "routing_decision": routing_decision,
-        "providers_used": _provider_names_from_attempts(provider_attempts),
-        "provider_attempts": provider_attempts,
-        "fallback_used": _fallback_used(provider_attempts),
-        "validation_level": validation_level,
-        "minimum_profile_ok": minimum.get("ok", False),
-        "capability_status": minimum.get("capability_status", {}),
-        "elapsed_ms": _elapsed_ms(start),
-    }
-
-
-def _primary_search_exception_result(
-    start: float,
-    session_id: str,
-    query: str,
-    primary_api_mode: str,
-    provider_name: str,
-    exc: BaseException,
-) -> dict[str, Any]:
-    if isinstance(exc, httpx.TimeoutException):
-        return _primary_search_error_result(
-            start,
-            session_id,
-            query,
-            primary_api_mode,
-            "network_error",
-            f"{provider_name} 请求超时: {str(exc)}",
-        )
-    if isinstance(exc, httpx.HTTPStatusError):
-        body = exc.response.text[:300] if exc.response is not None else str(exc)
-        status = exc.response.status_code if exc.response is not None else "unknown"
-        return _primary_search_error_result(
-            start,
-            session_id,
-            query,
-            primary_api_mode,
-            "network_error",
-            f"{provider_name} HTTP {status}: {body}",
-        )
-    if isinstance(exc, httpx.RequestError):
-        return _primary_search_error_result(
-            start,
-            session_id,
-            query,
-            primary_api_mode,
-            "network_error",
-            f"{provider_name} 网络错误: {str(exc)}",
-        )
-    return _primary_search_error_result(
-        start,
-        session_id,
-        query,
-        primary_api_mode,
-        "runtime_error",
-        f"{provider_name} 运行错误: {str(exc)}",
-    )
-
-
-def _primary_search_error_result(
-    start: float,
-    session_id: str,
-    query: str,
-    primary_api_mode: str,
-    error_type: str,
-    error: str,
-) -> dict[str, Any]:
-    return {
-        "ok": False,
-        "error_type": error_type,
-        "error": error,
-        "session_id": session_id,
-        "query": query,
-        "primary_api_mode": primary_api_mode,
-        "content": "",
-        "sources": [],
-        "sources_count": 0,
-        "primary_sources": [],
-        "primary_sources_count": 0,
-        "extra_sources": [],
-        "extra_sources_count": 0,
-        "source_warning": "",
-        "elapsed_ms": _elapsed_ms(start),
-    }
-
-
-async def fetch(url: str) -> dict[str, Any]:
-    start = time.time()
-    fetch_result, attempts = await _run_web_fetch_fallback(url)
-    if fetch_result:
-        return {
-            **fetch_result,
-            "provider_attempts": attempts,
-            "fallback_used": _fallback_used(attempts),
-            "elapsed_ms": _elapsed_ms(start),
-        }
-
-    if not (config.tavily_api_key or config.jina_api_key or config.firecrawl_api_key):
-        error = "TAVILY_API_KEY、JINA_API_KEY 和 FIRECRAWL_API_KEY 均未配置"
-        error_type = "config_error"
-    else:
-        error = "所有提取服务均未能获取内容"
-        error_type = "network_error"
-    return {
-        "ok": False,
-        "url": url,
-        "provider": "",
-        "content": "",
-        "error_type": error_type,
-        "error": error,
-        "provider_attempts": attempts,
-        "fallback_used": _fallback_used(attempts),
-        "elapsed_ms": _elapsed_ms(start),
-    }
-
-
-async def map_site(
-    url: str,
-    instructions: str = "",
-    max_depth: int = 1,
-    max_breadth: int = 20,
-    limit: int = 50,
-    timeout: int = 150,
-) -> dict[str, Any]:
-    start = time.time()
-    result = await call_tavily_map(url, instructions, max_depth, max_breadth, limit, timeout)
-    result.setdefault("url", url)
-    result.setdefault("elapsed_ms", _elapsed_ms(start))
-    return result
-
-
-async def exa_search(
-    query: str,
-    num_results: int = 5,
-    search_type: str = "neural",
-    include_text: bool = False,
-    include_highlights: bool = False,
-    start_published_date: str = "",
-    include_domains: str | list[str] | tuple[str, ...] = "",
-    exclude_domains: str | list[str] | tuple[str, ...] = "",
-    category: str = "",
-) -> dict[str, Any]:
-    api_key = config.exa_api_key
-    if not api_key:
-        return {
-            "ok": False,
-            "error_type": "config_error",
-            "error": "EXA_API_KEY 未配置。请运行 `smart-search setup`，或使用 `smart-search config set EXA_API_KEY <key>`。",
-        }
-
-    provider = ExaSearchProvider(config.exa_base_url, api_key, config.exa_timeout)
-    include_domain_list = _normalize_domain_filter(include_domains)
-    exclude_domain_list = _normalize_domain_filter(exclude_domains)
-
-    raw = await provider.search(
-        query=query,
-        num_results=num_results,
-        search_type=search_type,
-        include_text=include_text,
-        include_highlights=include_highlights,
-        start_published_date=start_published_date or None,
-        include_domains=include_domain_list,
-        exclude_domains=exclude_domain_list,
-        category=category or None,
-    )
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError:
-        return {"ok": False, "error_type": "parse_error", "error": raw}
-    if not data.get("ok", False):
-        data.setdefault("error_type", "network_error")
-    return data
-
-
-async def _decode_provider_json(raw: str, provider: str = "jina") -> dict[str, Any]:
-    try:
-        return json.loads(raw)
-    except json.JSONDecodeError:
-        return {"ok": False, "provider": provider, "error_type": "parse_error", "error": raw}
-
-
-async def jina_fetch(url: str) -> dict[str, Any]:
-    return await call_jina_reader(url)
-
-
-async def exa_find_similar(url: str, num_results: int = 5) -> dict[str, Any]:
-    api_key = config.exa_api_key
-    if not api_key:
-        return {
-            "ok": False,
-            "error_type": "config_error",
-            "error": "EXA_API_KEY 未配置。请运行 `smart-search setup`，或使用 `smart-search config set EXA_API_KEY <key>`。",
-        }
-
-    provider = ExaSearchProvider(config.exa_base_url, api_key, config.exa_timeout)
-    raw = await provider.find_similar(url=url, num_results=num_results)
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError:
-        return {"ok": False, "error_type": "parse_error", "error": raw}
-    if not data.get("ok", False):
-        data.setdefault("error_type", "network_error")
-    return data
-
-
-async def zhipu_search(
-    query: str,
-    count: int = 10,
-    search_engine: str = "",
-    search_recency_filter: str = "noLimit",
-    search_domain_filter: str = "",
-    content_size: str = "medium",
-) -> dict[str, Any]:
-    api_key = config.zhipu_api_key
-    if not api_key:
-        return {
-            "ok": False,
-            "error_type": "config_error",
-            "error": "ZHIPU_API_KEY 未配置。请运行 `smart-search setup`，或使用 `smart-search config set ZHIPU_API_KEY <key>`。",
-        }
-    provider = ZhipuWebSearchProvider(
-        config.zhipu_api_url,
-        api_key,
-        search_engine or config.zhipu_search_engine,
-        config.zhipu_timeout,
-    )
-    raw = await provider.search(
-        query=query,
-        count=count,
-        search_engine=search_engine or None,
-        search_recency_filter=search_recency_filter,
-        search_domain_filter=search_domain_filter,
-        content_size=content_size,
-    )
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError:
-        return {"ok": False, "error_type": "parse_error", "error": raw}
-    if not data.get("ok", False):
-        data.setdefault("error_type", "network_error")
-    return data
-
-
-async def context7_library(name: str, query: str = "") -> dict[str, Any]:
-    api_key = config.context7_api_key
-    if not api_key:
-        return {
-            "ok": False,
-            "error_type": "config_error",
-            "error": "CONTEXT7_API_KEY 未配置。请运行 `smart-search setup`，或使用 `smart-search config set CONTEXT7_API_KEY <key>`。",
-        }
-    provider = Context7Provider(config.context7_base_url, api_key, config.context7_timeout)
-    raw = await provider.library(name, query)
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError:
-        return {"ok": False, "error_type": "parse_error", "error": raw}
-    if not data.get("ok", False):
-        data.setdefault("error_type", "network_error")
-    return data
-
-
-async def context7_docs(library_id: str, query: str) -> dict[str, Any]:
-    api_key = config.context7_api_key
-    if not api_key:
-        return {
-            "ok": False,
-            "error_type": "config_error",
-            "error": "CONTEXT7_API_KEY 未配置。请运行 `smart-search setup`，或使用 `smart-search config set CONTEXT7_API_KEY <key>`。",
-        }
-    provider = Context7Provider(config.context7_base_url, api_key, config.context7_timeout)
-    raw = await provider.docs(library_id, query)
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError:
-        return {"ok": False, "error_type": "parse_error", "error": raw}
-    if not data.get("ok", False):
-        data.setdefault("error_type", "network_error")
-    return data
-
-
-async def _test_primary_chat_completion(api_url: str, api_key: str, model: str) -> dict[str, Any]:
-    chat_url = f"{api_url.rstrip('/')}/chat/completions"
-    start = time.time()
-    async with httpx.AsyncClient(timeout=20.0) as client:
-        response = await client.post(
-            chat_url,
-            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
-            json={
-                "model": model,
-                "messages": [{"role": "user", "content": "Reply with exactly: ok"}],
-                "stream": False,
-                "max_tokens": 8,
-            },
-        )
-        response_time = _elapsed_ms(start)
-        content_type = response.headers.get("content-type", "")
-        if response.status_code != 200:
-            return {
-                "status": "warning",
-                "message": f"HTTP {response.status_code}: {response.text[:100]}",
-                "response_time_ms": response_time,
-                "http_status": response.status_code,
-                "content_type": content_type,
-                "has_content": bool(response.text.strip()),
-            }
-        return {
-            "status": "ok",
-            "message": f"聊天接口可用 (HTTP {response.status_code})",
-            "response_time_ms": response_time,
-            "http_status": response.status_code,
-            "content_type": content_type,
-            "has_content": bool(response.text.strip()),
-        }
-
-
-def _diagnose_check_result(
-    *,
-    name: str,
-    status: str,
-    message: str,
-    start: float,
-    http_status: int | None = None,
-    content_type: str = "",
-    has_content: bool = False,
-    stream: bool | None = None,
-) -> dict[str, Any]:
-    result: dict[str, Any] = {
-        "name": name,
-        "status": status,
-        "message": message,
-        "response_time_ms": _elapsed_ms(start),
-        "has_content": has_content,
-    }
-    if http_status is not None:
-        result["http_status"] = http_status
-    if content_type:
-        result["content_type"] = content_type
-    if stream is not None:
-        result["stream"] = stream
-    return result
-
-
-def _openai_compatible_diagnosis(quick: dict[str, Any], no_stream: dict[str, Any], stream: dict[str, Any]) -> tuple[bool, str, str]:
-    quick_ok = quick.get("status") == "ok"
-    no_stream_ok = no_stream.get("status") == "ok"
-    stream_ok = stream.get("status") == "ok"
-    search_timeout = no_stream.get("status") == "timeout" or stream.get("status") == "timeout"
-
-    if no_stream_ok and stream_ok:
-        return (
-            True,
-            "OpenAI-compatible 主链路正常。",
-            "真实 search 形态的 stream=false 和 stream=true 都能返回。若用户仍卡住，更可能是调用方、PATH、超时设置或上游偶发波动。",
-        )
-    if stream_ok and not no_stream_ok:
-        return (
-            False,
-            "非流式请求不稳定，流式请求可用。",
-            "建议设置 `OPENAI_COMPATIBLE_STREAM=true`，或临时使用 `smart-search search ... --stream`。",
-        )
-    if no_stream_ok and not stream_ok:
-        return (
-            False,
-            "流式请求不稳定，非流式请求可用。",
-            "建议设置 `OPENAI_COMPATIBLE_STREAM=false`，或临时使用 `smart-search search ... --no-stream`。",
-        )
-    if quick_ok and search_timeout:
-        return (
-            False,
-            "小请求能通，但真实 search 形态超时。",
-            "这通常是上游模型或中转站在处理 smart-search 的完整 prompt 时卡住；建议换模型/中转，或把本诊断报告贴给维护者。",
-        )
-    if quick_ok:
-        return (
-            False,
-            "小请求能通，但真实 search 形态失败。",
-            "这更像上游模型/中转站对 smart-search 请求形态不兼容；建议换模型/中转，或把本诊断报告贴给维护者。",
-        )
-    return (
-        False,
-        "OpenAI-compatible 基础请求不可用。",
-        "请先检查 API URL、API key、模型名和网络；修好后再运行本诊断命令。",
-    )
-
-
-async def _probe_openai_compatible_search_shape(
-    api_url: str,
-    api_key: str,
-    model: str,
-    *,
-    stream: bool,
-    timeout_seconds: float,
-) -> dict[str, Any]:
-    name = "真实 search 请求 (stream=true)" if stream else "真实 search 请求 (stream=false)"
-    start = time.time()
-    payload = {
-        "model": model,
-        "messages": [
-            {"role": "system", "content": search_prompt},
-            {"role": "user", "content": get_local_time_info() + "\nping"},
-        ],
-        "stream": stream,
-    }
-    headers = {
-        "Authorization": f"Bearer {api_key}",
-        "Content-Type": "application/json",
-        "Accept": "application/json, text/event-stream",
-        "User-Agent": "smart-search/diagnose",
-    }
-    timeout = httpx.Timeout(connect=6.0, read=timeout_seconds, write=10.0, pool=None)
-    try:
-        async with httpx.AsyncClient(timeout=timeout, follow_redirects=True, verify=config.ssl_verify_enabled) as client:
-            if stream:
-                async with client.stream(
-                    "POST",
-                    f"{api_url.rstrip('/')}/chat/completions",
-                    headers=headers,
-                    json=payload,
-                ) as response:
-                    content_type = response.headers.get("content-type", "")
-                    response.raise_for_status()
-                    has_content = False
-                    async for line in response.aiter_lines():
-                        stripped = line.strip()
-                        if not stripped:
-                            continue
-                        if not stripped.startswith("data:"):
-                            continue
-                        if stripped in ("data: [DONE]", "data:[DONE]"):
-                            continue
-                        try:
-                            data = json.loads(stripped[5:].lstrip())
-                        except json.JSONDecodeError:
-                            continue
-                        choices = data.get("choices", []) if isinstance(data, dict) else []
-                        if not choices:
-                            continue
-                        delta = choices[0].get("delta", {})
-                        if isinstance(delta, dict) and str(delta.get("content") or "").strip():
-                            has_content = True
-                            break
-                        message = choices[0].get("message", {})
-                        if isinstance(message, dict) and str(message.get("content") or "").strip():
-                            has_content = True
-                            break
-                    status = "ok" if has_content else "empty"
-                    message = f"HTTP {response.status_code}; {'收到流式内容' if has_content else '未收到内容'}"
-                    return _diagnose_check_result(
-                        name=name,
-                        status=status,
-                        message=message,
-                        start=start,
-                        http_status=response.status_code,
-                        content_type=content_type,
-                        has_content=has_content,
-                        stream=stream,
-                    )
-
-            response = await client.post(
-                f"{api_url.rstrip('/')}/chat/completions",
-                headers=headers,
-                json=payload,
-            )
-            content_type = response.headers.get("content-type", "")
-            response.raise_for_status()
-            content = await OpenAICompatibleSearchProvider(api_url, api_key, model, stream=False)._parse_completion_response(response)
-            has_content = bool(content.strip())
-            status = "ok" if has_content else "empty"
-            message = f"HTTP {response.status_code}; {'收到内容' if has_content else '返回为空'}"
-            return _diagnose_check_result(
-                name=name,
-                status=status,
-                message=message,
-                start=start,
-                http_status=response.status_code,
-                content_type=content_type,
-                has_content=has_content,
-                stream=stream,
-            )
-    except httpx.TimeoutException as e:
-        return _diagnose_check_result(name=name, status="timeout", message=f"请求超时: {e}", start=start, stream=stream)
-    except httpx.HTTPStatusError as e:
-        body = e.response.text[:200] if e.response is not None else str(e)
-        status_code = e.response.status_code if e.response is not None else None
-        content_type = e.response.headers.get("content-type", "") if e.response is not None else ""
-        return _diagnose_check_result(
-            name=name,
-            status="warning",
-            message=f"HTTP {status_code}: {body}",
-            start=start,
-            http_status=status_code,
-            content_type=content_type,
-            stream=stream,
-        )
-    except httpx.RequestError as e:
-        return _diagnose_check_result(name=name, status="error", message=f"网络错误: {e}", start=start, stream=stream)
-    except Exception as e:
-        return _diagnose_check_result(name=name, status="error", message=f"运行错误: {e}", start=start, stream=stream)
-
-
-async def diagnose_openai_compatible(timeout_seconds: float = 30.0) -> dict[str, Any]:
-    start = time.time()
-    api_url = config.openai_compatible_api_url
-    api_key = config.openai_compatible_api_key
-    model = config.openai_compatible_model
-    info = config.config_path_info()
-    result: dict[str, Any] = {
-        "ok": False,
-        "provider": "openai-compatible",
-        "api_url": api_url or "未配置",
-        "api_key": config._mask_api_key(api_key) if api_key else "未配置",
-        "model": model,
-        "configured_stream": config.openai_compatible_stream,
-        "timeout_seconds": timeout_seconds,
-        "config_file": info.get("config_file", ""),
-        "config_dir_source": info.get("config_dir_source", ""),
-        "checks": [],
-        "next_command": OPENAI_COMPATIBLE_DIAGNOSE_COMMAND,
-    }
-    missing = []
-    if not api_url:
-        missing.append("OPENAI_COMPATIBLE_API_URL")
-    if not api_key:
-        missing.append("OPENAI_COMPATIBLE_API_KEY")
-    if missing:
-        result.update(
-            {
-                "error_type": "config_error",
-                "error": "缺少 OpenAI-compatible 配置: " + ", ".join(missing),
-                "summary": "OpenAI-compatible 配置不完整。",
-                "recommendation": "请先运行 `smart-search setup`，或用 `smart-search config set` 填好缺失项。",
-                "missing": missing,
-                "elapsed_ms": _elapsed_ms(start),
-            }
-        )
-        return result
-
-    try:
-        quick = await _test_primary_chat_completion(api_url, api_key, model)
-    except httpx.TimeoutException as e:
-        quick = {"status": "timeout", "message": f"轻量 chat 请求超时: {e}"}
-    except httpx.RequestError as e:
-        quick = {"status": "error", "message": f"轻量 chat 网络错误: {e}"}
-    except Exception as e:
-        quick = {"status": "error", "message": f"轻量 chat 运行错误: {e}"}
-    quick_check = {
-        "name": "轻量 chat 请求",
-        "status": quick.get("status", "error"),
-        "message": quick.get("message", ""),
-        "response_time_ms": quick.get("response_time_ms"),
-        "http_status": quick.get("http_status"),
-        "content_type": quick.get("content_type", ""),
-        "has_content": bool(quick.get("has_content", quick.get("status") == "ok")),
-    }
-    result["checks"].append(quick_check)
-    no_stream = await _probe_openai_compatible_search_shape(api_url, api_key, model, stream=False, timeout_seconds=timeout_seconds)
-    result["checks"].append(no_stream)
-    stream = await _probe_openai_compatible_search_shape(api_url, api_key, model, stream=True, timeout_seconds=timeout_seconds)
-    result["checks"].append(stream)
-
-    ok, summary, recommendation = _openai_compatible_diagnosis(quick_check, no_stream, stream)
-    result.update(
-        {
-            "ok": ok,
-            "error_type": "" if ok else "network_error",
-            "error": "" if ok else summary,
-            "summary": summary,
-            "recommendation": recommendation,
-            "elapsed_ms": _elapsed_ms(start),
-        }
-    )
-    return result
-
-
-async def _test_primary_connection(api_url: str, api_key: str, model: str) -> dict[str, Any]:
-    chat_test = await _test_primary_chat_completion(api_url, api_key, model)
-
-    models_url = f"{api_url.rstrip('/')}/models"
-    start = time.time()
-    try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            response = await client.get(
-                models_url,
-                headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
-            )
-            response_time = _elapsed_ms(start)
-            if response.status_code != 200:
-                models_test = {"status": "warning", "message": f"HTTP {response.status_code}: {response.text[:100]}", "response_time_ms": response_time}
-            else:
-                models_test = {"status": "ok", "message": f"成功获取模型列表 (HTTP {response.status_code})", "response_time_ms": response_time}
-                try:
-                    models_data = response.json()
-                    model_names = [m["id"] for m in models_data.get("data", []) if isinstance(m, dict) and "id" in m]
-                    models_test["message"] += f"，共 {len(model_names)} 个模型"
-                    if model_names:
-                        models_test["available_models"] = model_names
-                except Exception:
-                    pass
-    except httpx.HTTPError as e:
-        models_test = {"status": "warning", "message": f"模型列表接口请求失败: {e}", "response_time_ms": _elapsed_ms(start)}
-
-    if chat_test.get("status") != "ok":
-        models_state = "可用" if models_test.get("status") == "ok" else "不可用"
-        return {
-            "status": "warning",
-            "message": f"聊天接口不可用: {chat_test.get('message', '')}；模型列表接口{models_state}: {models_test['message']}",
-            "response_time_ms": chat_test.get("response_time_ms", models_test.get("response_time_ms")),
-            "models_endpoint_test": models_test,
-            "chat_completion_test": chat_test,
-        }
-
-    if models_test.get("status") != "ok":
-        return {
-            "status": "ok",
-            "message": f"{chat_test['message']}；模型列表接口不可用: {models_test['message']}",
-            "response_time_ms": chat_test.get("response_time_ms"),
-            "models_endpoint_test": models_test,
-            "chat_completion_test": chat_test,
-        }
-
-    result: dict[str, Any] = {
-        "status": "ok",
-        "message": f"{chat_test['message']}；{models_test['message']}",
-        "response_time_ms": chat_test.get("response_time_ms"),
-        "models_endpoint_test": models_test,
-        "chat_completion_test": chat_test,
-    }
-    if "available_models" in models_test:
-        result["available_models"] = models_test["available_models"]
-    return result
-
-
-async def _test_main_provider_connection(provider_config: dict[str, Any]) -> dict[str, Any]:
-    return await _test_primary_connection(provider_config["api_url"], provider_config["api_key"], provider_config["model"])
-
-
-async def _safe_test_main_provider_connection(provider_config: dict[str, Any]) -> dict[str, Any]:
-    try:
-        return await _test_main_provider_connection(provider_config)
-    except httpx.TimeoutException:
-        return {"status": "timeout", "message": f"{provider_config['provider']} 请求超时，请检查网络连接或 API URL"}
-    except httpx.RequestError as e:
-        return {"status": "error", "message": f"{provider_config['provider']} 网络错误: {str(e)}"}
-    except Exception as e:
-        return {"status": "error", "message": f"{provider_config['provider']} 未知错误: {str(e)}"}
-
-
-async def _test_exa_connection() -> dict[str, Any]:
-    exa_key = config.exa_api_key
-    if not exa_key:
-        return {"status": "not_configured", "message": "EXA_API_KEY 未设置，Exa 搜索功能不可用"}
-    start = time.time()
-    async with httpx.AsyncClient(timeout=10.0) as client:
-        resp = await client.post(
-            f"{config.exa_base_url.rstrip('/')}/search",
-            headers={"x-api-key": exa_key, "content-type": "application/json"},
-            json={"query": "test", "numResults": 1, "type": "keyword"},
-        )
-        response_time = _elapsed_ms(start)
-        if resp.status_code == 200:
-            return {"status": "ok", "message": "Exa API 可用 (HTTP 200)", "response_time_ms": response_time}
-        return {"status": "warning", "message": f"HTTP {resp.status_code}: {resp.text[:100]}", "response_time_ms": response_time}
-
-
-async def _test_tavily_connection() -> dict[str, Any]:
-    tavily_key = config.tavily_api_key
-    if not tavily_key:
-        return {"status": "not_configured", "message": "TAVILY_API_KEY 未设置，Tavily 功能不可用"}
-    start = time.time()
-    timeout = httpx.Timeout(connect=6.0, read=config.tavily_timeout, write=10.0, pool=None)
-    async with httpx.AsyncClient(timeout=timeout, follow_redirects=True, verify=config.ssl_verify_enabled) as client:
-        resp = await client.post(
-            f"{config.tavily_api_url.rstrip('/')}/search",
-            headers={"Authorization": f"Bearer {tavily_key}", "Content-Type": "application/json"},
-            json={"query": "test", "max_results": 1, "search_depth": "basic"},
-        )
-        response_time = _elapsed_ms(start)
-        if resp.status_code == 200:
-            return {"status": "ok", "message": "Tavily API 可用 (HTTP 200)", "response_time_ms": response_time}
-        return {"status": "warning", "message": f"HTTP {resp.status_code}: {resp.text[:100]}", "response_time_ms": response_time}
-
-
-async def _test_jina_connection() -> dict[str, Any]:
-    if config.jina_respond_with and not config.jina_api_key:
-        return {"status": "config_error", "message": "JINA_RESPOND_WITH requires JINA_API_KEY"}
-    if not config.jina_api_key:
-        return {"status": "not_configured", "message": "JINA_API_KEY 未设置，Jina 不满足 standard web_fetch；匿名 Reader 只能作为显式实验使用"}
-    start = time.time()
-    data = await jina_fetch("https://example.com")
-    response_time = _elapsed_ms(start)
-    if data.get("ok"):
-        return {"status": "ok", "message": "Jina Reader 可用", "response_time_ms": response_time}
-    error_type = data.get("error_type", "")
-    status = error_type if error_type in {"auth_error", "config_error", "parameter_error", "rate_limited", "timeout"} else "warning"
-    return {"status": status, "message": data.get("error", "Jina Reader 不可用"), "response_time_ms": response_time}
-
-
-async def _test_zhipu_connection() -> dict[str, Any]:
-    if not config.zhipu_api_key:
-        return {"status": "not_configured", "message": "ZHIPU_API_KEY 未设置，智谱搜索功能不可用"}
-    result = await zhipu_search("test", count=1)
-    if result.get("ok"):
-        return {"status": "ok", "message": "智谱 Web Search 可用", "response_time_ms": result.get("elapsed_ms", 0)}
-    return {"status": "warning", "message": result.get("error", "智谱 Web Search 不可用"), "response_time_ms": result.get("elapsed_ms", 0)}
-
-
-async def _test_context7_connection() -> dict[str, Any]:
-    if not config.context7_api_key:
-        return {"status": "not_configured", "message": "CONTEXT7_API_KEY 未设置，Context7 功能不可用"}
-    result = await context7_library("react", "hooks")
-    if result.get("ok"):
-        return {"status": "ok", "message": "Context7 API 可用", "response_time_ms": result.get("elapsed_ms", 0)}
-    return {"status": "warning", "message": result.get("error", "Context7 API 不可用"), "response_time_ms": result.get("elapsed_ms", 0)}
-
-
-async def doctor() -> dict[str, Any]:
-    info = config.get_config_info()
-
-    main_provider_configs: list[dict[str, Any]] = []
-    try:
-        main_provider_configs = _main_search_provider_configs()
-        info["main_search_connection_tests"] = {}
-        for provider_config in main_provider_configs:
-            info["main_search_connection_tests"][provider_config["provider"]] = await _safe_test_main_provider_connection(provider_config)
-        if main_provider_configs:
-            first_provider = main_provider_configs[0]
-            info["primary_api_mode"] = first_provider["mode"]
-            info["primary_connection_test"] = info["main_search_connection_tests"][first_provider["provider"]]
-        else:
-            info["primary_connection_test"] = {"status": "config_error", "message": MINIMUM_PROFILE_ERROR}
-    except ValueError as e:
-        info["main_search_connection_tests"] = {}
-        info["primary_connection_test"] = {"status": "config_error", "message": str(e)}
-    except Exception as e:
-        info["main_search_connection_tests"] = {}
-        info["primary_connection_test"] = {"status": "error", "message": f"未知错误: {str(e)}"}
-
-    try:
-        info["exa_connection_test"] = await _test_exa_connection()
-    except httpx.TimeoutException:
-        info["exa_connection_test"] = {"status": "timeout", "message": "Exa API 请求超时"}
-    except Exception as e:
-        info["exa_connection_test"] = {"status": "error", "message": str(e)}
-
-    try:
-        info["tavily_connection_test"] = await _test_tavily_connection()
-    except httpx.TimeoutException:
-        info["tavily_connection_test"] = {"status": "timeout", "message": "Tavily API 请求超时"}
-    except Exception as e:
-        info["tavily_connection_test"] = {"status": "error", "message": str(e)}
-
-    try:
-        info["jina_connection_test"] = await _test_jina_connection()
-    except httpx.TimeoutException:
-        info["jina_connection_test"] = {"status": "timeout", "message": "Jina Reader 请求超时"}
-    except Exception as e:
-        info["jina_connection_test"] = {"status": "error", "message": str(e)}
-
-    if config.firecrawl_api_key:
-        info["firecrawl_connection_test"] = {"status": "configured", "message": "FIRECRAWL_API_KEY 已设置"}
-    else:
-        info["firecrawl_connection_test"] = {"status": "not_configured", "message": "FIRECRAWL_API_KEY 未设置，Firecrawl 功能不可用"}
-
-    try:
-        info["zhipu_connection_test"] = await _test_zhipu_connection()
-    except httpx.TimeoutException:
-        info["zhipu_connection_test"] = {"status": "timeout", "message": "智谱 API 请求超时"}
-    except Exception as e:
-        info["zhipu_connection_test"] = {"status": "error", "message": str(e)}
-
-    try:
-        info["context7_connection_test"] = await _test_context7_connection()
-    except httpx.TimeoutException:
-        info["context7_connection_test"] = {"status": "timeout", "message": "Context7 API 请求超时"}
-    except Exception as e:
-        info["context7_connection_test"] = {"status": "error", "message": str(e)}
-
-    minimum = validate_minimum_profile()
-    info["capability_status"] = minimum.get("capability_status", get_capability_status())
-    info["minimum_profile_ok"] = minimum.get("ok", False)
-    info["minimum_profile_missing"] = minimum.get("missing", [])
-    main_connection_tests = info.get("main_search_connection_tests") or {}
-    main_search_statuses = [item.get("status") for item in main_connection_tests.values() if isinstance(item, dict)]
-    primary_test = info.get("primary_connection_test", {})
-    primary_status = primary_test.get("status")
-    main_search_ok = any(status == "ok" for status in main_search_statuses) if main_connection_tests else primary_status == "ok"
-    info["ok"] = main_search_ok and minimum.get("ok", False)
-    if info["ok"]:
-        info["error_type"] = ""
-        info["error"] = ""
-    elif info.get("config_parameter_errors"):
-        info["error"] = "; ".join(info["config_parameter_errors"])
-        info["error_type"] = "parameter_error"
-    elif not minimum.get("ok", False):
-        info["error"] = minimum.get("error", MINIMUM_PROFILE_ERROR)
-        info["error_type"] = minimum.get("error_type", "config_error")
-    else:
-        info["error"] = primary_test.get("message", "Primary connection check failed")
-        if primary_status == "config_error":
-            info["error_type"] = "config_error"
-        elif primary_status in {"timeout", "error", "warning"}:
-            info["error_type"] = "network_error"
-        else:
-            info["error_type"] = "runtime_error"
-    return info
-
-
-def config_path() -> dict[str, Any]:
-    return config.config_path_info()
-
-
-def config_list(show_secrets: bool = False) -> dict[str, Any]:
-    return {
-        "ok": True,
-        "config_file": str(config.config_file),
-        "values": config.get_saved_config(masked=not show_secrets),
-    }
-
-
-def config_set(key: str, value: str) -> dict[str, Any]:
-    try:
-        config.set_config_value(key, value)
-    except ValueError as e:
-        return {"ok": False, "error_type": "parameter_error", "error": str(e), "config_file": str(config.config_file)}
-    saved = config.get_saved_config(masked=True)
-    return {
-        "ok": True,
-        "config_file": str(config.config_file),
-        "key": key.strip().upper(),
-        "value": saved.get(key.strip().upper(), ""),
-    }
-
-
-def config_unset(key: str) -> dict[str, Any]:
-    try:
-        config.unset_config_value(key)
-    except ValueError as e:
-        return {"ok": False, "error_type": "parameter_error", "error": str(e), "config_file": str(config.config_file), "key": key.strip().upper()}
-    return {"ok": True, "config_file": str(config.config_file), "key": key.strip().upper()}
-
-
-def write_output(path: str | Path, content: str) -> None:
-    target = Path(path)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(content, encoding="utf-8")