research-assistant 0.1.0

package/src/research_assistant/providers/base.py

@@ -0,0 +1,93 @@
+"""Provider 统一接口（ADR-0011 插件化解耦的核心）。
+
+每个 provider 声明：
+    type        —— config 中的 type 键（如 "exa"）
+    command     —— 主命令名（如 "exa"）
+    aliases     —— 命令别名（如 ["x"]）
+    capabilities() —— 返回 Capability 列表（子命令 → async 处理函数 + 参数声明）
+
+加/删/换 provider = 1 文件 + 1 条 config，不改 CLI 入口/路由/横切/其他 provider。
+能力差异用 capabilities{} 声明式表达，CLI 按声明动态生成命令（不强制统一方法签名）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..config import Config
+
+
+@dataclass
+class ArgSpec:
+    """单个 CLI 参数声明（透传到 argparse.add_argument）。
+
+    kind="positional" 时 name_or_flags 给单个位置参数名（如 ["query"]）；
+    kind="optional" 时给 flag（如 ["--num-results"]）。
+    """
+
+    name_or_flags: list[str]
+    help: str = ""
+    default: Any = None
+    required: bool = False
+    type: Callable[[str], Any] | None = None
+    choices: list[str] | None = None
+    nargs: str | int | None = None
+    action: str | None = None
+    dest: str | None = None
+    metavar: str | None = None
+    kind: str = "optional"
+
+    def add_to(self, parser: Any) -> None:
+        kwargs: dict[str, Any] = {"help": self.help}
+        if self.kind == "optional":
+            if self.default is not None:
+                kwargs["default"] = self.default
+            if self.required:
+                kwargs["required"] = True
+        if self.type is not None:
+            kwargs["type"] = self.type
+        if self.choices is not None:
+            kwargs["choices"] = self.choices
+        if self.nargs is not None:
+            kwargs["nargs"] = self.nargs
+        if self.action is not None:
+            kwargs["action"] = self.action
+        if self.dest is not None:
+            kwargs["dest"] = self.dest
+        if self.metavar is not None:
+            kwargs["metavar"] = self.metavar
+        parser.add_argument(*self.name_or_flags, **kwargs)
+
+
+@dataclass
+class Capability:
+    """一个子命令（如 exa search）：参数声明 + async 处理函数。
+
+    handler 签名：async (provider_instance, argparse.Namespace) -> dict
+    返回 dict 直接作为 JSON 输出（对齐 api-contract.md §3）。
+    """
+
+    name: str
+    help: str = ""
+    args: list[ArgSpec] = field(default_factory=list)
+    handler: Callable[..., Any] | None = None  # async callable
+
+
+class Provider:
+    """所有 provider 的基类。子类设置类属性 + 实现 capabilities() 与各 handler。"""
+
+    type: str = ""
+    command: str = ""
+    aliases: list[str] = []
+    help: str = ""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    def capabilities(self) -> list[Capability]:
+        raise NotImplementedError
+
+    def client_kwargs(self) -> dict[str, Any]:
+        """子类可覆盖：构造 httpx 客户端时的额外 header/base_url。"""
+        return {}

package/src/research_assistant/providers/browser.py

@@ -0,0 +1,91 @@
+"""browser provider：本地浏览器作为一个"平台"（与 exa/tavily/firecrawl 同级，走 registry 自动发现）。
+
+不是 HTTP API（无 key/base_url），直接驱动本地浏览器：
+  - browser fetch：headed DrissionPage + CF auto-detect 抓取（跳过普通 API，直接浏览器入口）。
+  - browser search：headless DrissionPage 抓搜索引擎结果页（必应国内/国际、Google），页数表翻页。
+与 fetch 命令的浏览器层共用 fetch_with_browser（去 headless 后统一 headed+CF auto-detect）。
+config 无需 [[provider]] type=browser，运行参数从 config.browser 读（channel 等）；永远可用。
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from ..errors import ArgsError
+from ..fetch import fetch_with_browser, write_snapshot
+from ..fetch.search_engine import search_engine
+from .base import ArgSpec, Capability, Provider
+from .registry import register
+
+
+@register
+class BrowserProvider(Provider):
+    type = "browser"
+    command = "browser"
+    aliases = ["br"]
+    help = "Local browser platform: headed fetch with CF auto-detect, or headless search-engine search."
+
+    def capabilities(self) -> list[Capability]:
+        return [
+            Capability(
+                name="fetch",
+                help="Headed browser fetch with CF auto-detect (skips normal API).",
+                args=[
+                    ArgSpec(["urls"], kind="positional", nargs="+", metavar="URL", help="URL(s) to fetch."),
+                    ArgSpec(["--no-login"], action="store_true", help="Do not inject login cookies (default injects)."),
+                    ArgSpec(["--concurrency"], type=int, default=4, help="Browser concurrency (default 4)."),
+                    ArgSpec(["--write"], metavar="PATH", help="Write markdown to this path (single URL only)."),
+                ],
+                handler=self.fetch,
+            ),
+            Capability(
+                name="search",
+                help="Headless search-engine search (default bing-intl; bing-cn|bing-intl|google).",
+                args=[
+                    ArgSpec(["query"], kind="positional", metavar="QUERY", help="Search query."),
+                    ArgSpec(
+                        ["--engine"],
+                        choices=["bing-cn", "bing-intl", "google"],
+                        default="bing-intl",
+                        help="Search engine (default bing-intl; intl avoids CN-sensitive-word filtering).",
+                    ),
+                    ArgSpec(["--limit"], type=int, default=10, help="Min results to collect (default 10)."),
+                    ArgSpec(["--max-pages"], type=int, default=10, help="Max pages to paginate (default 10)."),
+                ],
+                handler=self.search,
+            ),
+        ]
+
+    async def fetch(self, args_ns: argparse.Namespace) -> dict[str, Any]:
+        urls = list(args_ns.urls)
+        if args_ns.write and len(urls) > 1:
+            raise ArgsError("browser fetch: --write 仅支持单个 URL")
+        use_login = not getattr(args_ns, "no_login", False)
+        raw = await fetch_with_browser(
+            self.config, urls, login=use_login, concurrency=args_ns.concurrency
+        )
+        results: list[dict[str, Any]] = []
+        for url in urls:
+            md = raw.get(url)
+            if md:
+                md_path = write_snapshot(url, "browser", md, args_ns.write)
+                results.append(
+                    {"url": url, "method": "browser", "status": "success", "md_path": md_path}
+                )
+            else:
+                results.append(
+                    {
+                        "url": url,
+                        "method": "browser",
+                        "status": "failed",
+                        "md_path": None,
+                        "error": "浏览器抓取失败（CF 未通过/无浏览器/内容过短）",
+                    }
+                )
+        return {"results": results}
+
+    async def search(self, args_ns: argparse.Namespace) -> dict[str, Any]:
+        return await search_engine(
+            self.config, args_ns.query, args_ns.engine, args_ns.limit, args_ns.max_pages
+        )

package/src/research_assistant/providers/context7.py

@@ -0,0 +1,171 @@
+"""Context7 provider（自写 HTTP，ADR-0010；Context7 无 Python SDK 本就需自写）。
+
+公共 REST API（实测确认，context7.com）：
+    GET https://context7.com/api/v1/search?libraryName=<name>&query=<question>
+        鉴权 Authorization: Bearer <key>
+        resp: {results[]{id"/org/repo", title, description, totalSnippets, trustScore, ...}}
+    GET https://context7.com/api/v1/<libraryId>?topic=<query>&tokens=<n>&format=markdown
+        注：libraryId 在路径里（catch-all 路由），需去掉前导 /
+        resp: text/markdown，块间以 '--------------------------------' 分隔，每块含 'Source: <url>'
+
+对齐 api-contract.md §2.1/§3：
+    ctx7 library → {results[]{id, name, description}}
+    ctx7 docs    → {id, contents[]{text, source_url?}}
+"""
+
+from __future__ import annotations
+
+import httpx
+import re
+from typing import Any
+
+from ..config import ProviderConfig
+from ..errors import ArgsError, ProviderError
+from .. import http as http_mod
+from ..proxy import resolve_proxy
+from .base import ArgSpec, Capability, Provider
+from .registry import register
+
+DEFAULT_BASE_URL = "https://context7.com"
+_SEPARATOR = re.compile(r"\n-{10,}\n")
+
+
+@register
+class Context7Provider(Provider):
+    type = "context7"
+    command = "ctx7"
+    aliases = ["c7"]
+    help = "Context7 library resolution and up-to-date docs retrieval."
+
+    def capabilities(self) -> list[Capability]:
+        return [
+            Capability(
+                name="library",
+                help="Resolve a library ID by name.",
+                args=[
+                    ArgSpec(["name"], kind="positional", help="Library name (e.g. 'Next.js')."),
+                    ArgSpec(["query"], kind="positional", nargs="?", help="Your question (for relevance ranking)."),
+                ],
+                handler=self.library,
+            ),
+            Capability(
+                name="docs",
+                help="Fetch up-to-date docs for a library ID (must start with '/').",
+                args=[
+                    ArgSpec(["library_id"], kind="positional", metavar="LIBRARY_ID", help="Library ID, e.g. /facebook/react."),
+                    ArgSpec(["query"], kind="positional", help="Topic / question."),
+                    ArgSpec(["--tokens"], type=int, default=5000, help="Max tokens to return (default 5000)."),
+                ],
+                handler=self.docs,
+            ),
+        ]
+
+    def _cfg(self) -> ProviderConfig:
+        cfg = self.config.require_provider("context7")
+        if not cfg.api_key:
+            raise ArgsError("context7: 缺少 api_key", provider="context7")
+        if not cfg.base_url:
+            cfg.base_url = DEFAULT_BASE_URL
+        return cfg
+
+    async def library(self, args: Any) -> dict[str, Any]:
+        cfg = self._cfg()
+        params: dict[str, str] = {"libraryName": args.name}
+        if args.query:
+            params["query"] = args.query
+        else:
+            params["query"] = args.name
+        async with http_mod.make_client(
+            proxy_url=resolve_proxy(self.config.proxy.url),
+            timeout=cfg.timeout,
+            headers={"Authorization": f"Bearer {cfg.api_key}"},
+        ) as client:
+            data = await http_mod.request_json(
+                client, "GET", f"{cfg.base_url}/api/v1/search", provider="context7", params=params
+            )
+        results = []
+        for r in data.get("results", []) or []:
+            results.append(
+                {
+                    "id": r.get("id"),
+                    "name": r.get("title"),
+                    "description": r.get("description"),
+                }
+            )
+        return {"results": results}
+
+    async def docs(self, args: Any) -> dict[str, Any]:
+        cfg = self._cfg()
+        lib_id = args.library_id
+        if not lib_id.startswith("/"):
+            raise ArgsError(
+                "context7 docs: libraryId 必须以 '/' 开头（如 /facebook/react）", provider="context7"
+            )
+        params = {"topic": args.query, "tokens": str(args.tokens), "format": "markdown"}
+        async with http_mod.make_client(
+            proxy_url=resolve_proxy(self.config.proxy.url),
+            timeout=cfg.timeout,
+            headers={"Authorization": f"Bearer {cfg.api_key}"},
+        ) as client:
+            text, final_id = await _fetch_docs(client, cfg.base_url, lib_id, params)
+        contents = _parse_docs_text(text)
+        return {"id": final_id, "contents": contents}
+
+
+async def _fetch_docs(
+    client: httpx.AsyncClient, base_url: str, lib_id: str, params: dict[str, str], _depth: int = 0
+) -> tuple[str, str]:
+    """取 docs 文本；Context7 对旧 id 会 404 重定向，自动跟随（最多 3 次）。"""
+    if _depth > 3:
+        raise ProviderError("context7: libraryId 重定向次数过多", provider="context7")
+    path_id = lib_id.lstrip("/")
+    try:
+        resp = await client.request("GET", f"{base_url}/api/v1/{path_id}", params=params)
+    except Exception as e:
+        from ..errors import wrap_provider_http_error
+
+        raise wrap_provider_http_error("context7", e) from e
+    if resp.status_code == 404:
+        # 解析重定向提示："Library X has been redirected to this library: /new/id."
+        import re
+
+        m = re.search(r"redirected to this library:\s*(/[^\s.]+)", resp.text)
+        if m:
+            new_id = m.group(1)
+            return await _fetch_docs(client, base_url, new_id, params, _depth + 1)
+    if resp.status_code >= 400:
+        raise http_mod.handle_http_error(
+            "context7",
+            httpx.HTTPStatusError(f"context7 HTTP {resp.status_code}", request=resp.request, response=resp),
+        )
+    return resp.text, lib_id
+
+
+def _parse_docs_text(text: str) -> list[dict[str, Any]]:
+    """把 Context7 markdown 文本拆成 contents[]{text, source_url?}。
+
+    块间以一行短横线分隔；每块若含 'Source: <url>' 行，抽出为 source_url。
+    """
+    if not text or not text.strip():
+        return []
+    blocks = _SEPARATOR.split(text)
+    out: list[dict[str, Any]] = []
+    for block in blocks:
+        block = block.strip()
+        if not block:
+            continue
+        source_url = None
+        lines = block.splitlines()
+        # 找 Source: 行
+        clean_lines: list[str] = []
+        for line in lines:
+            m = re.match(r"\s*Source:\s*(\S+)", line)
+            if m and source_url is None:
+                source_url = m.group(1)
+                continue  # 去掉 Source 行本身
+            clean_lines.append(line)
+        item: dict[str, Any] = {"text": "\n".join(clean_lines).strip()}
+        if source_url:
+            item["source_url"] = source_url
+        out.append(item)
+    return out