research-assistant 0.1.0

package/src/research_assistant/assets/skills/research-assistant/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: research-assistant
+description: Search the open web, fetch official library docs, pull page content past logins or anti-bot challenges, and locate passages in long documents. This skill is a set of concurrent CLI tools that gather candidate sources and pages; it does not synthesize answers. It covers web search for sources, library/framework/SDK/CLI/cloud docs lookup, fetching pages behind Cloudflare or a login, and locating where a topic sits in a long document.
+---
+
+# research-assistant
+
+`research-assistant` is a set of concurrent CLI atomic tools for gathering external
+information: web search providers, official library docs, cross-tool page fetch, and
+anchor-based locate for long local documents. It is **middleware**. It collects sources and
+pages; you read them and synthesize your own answer.
+
+## Output boundary
+
+These tools gather sources and pages. They do not synthesize answers, do not rank which source
+to trust when sources disagree, and do not decide correctness. You read what they return and
+draw your own conclusions.
+
+## How to read this skill
+
+The Capability map and the Commands list describe what each tool is good at and when to use
+it. Treat those as guidance for picking a tool, not as a fixed routing order. The tier numbers
+(Tier 1/2/3) express a preference for the faster, cheaper tool first, not a hard rule: if you
+already know a page needs a browser, go straight to `fetch`. Anything in a command's inline
+comment is a strength hint, not a contract.
+
+## Primary tools: fetch, search, ask
+
+Three commands do the heavy lifting and need no configuration to start. Reach for them first.
+
+### `fetch <url>...`: cross-tool page fetch with automatic escalation
+
+`fetch` tries the cheap path first and climbs only on failure: the normal APIs (tavily extract,
+firecrawl scrape), then a headed real browser with Cloudflare auto-detect. Login cookies are
+injected through the bundled extension bridge, so logged-in pages work without re-entering
+credentials. It works out of the box: with zero provider config the normal APIs simply fail and
+the browser fallback still returns the page.
+
+### `search "<query>"`: aggregated multi-source search, browser included by default
+
+`search` fans the query across the configured search APIs (exa, tavily) and the browser search
+engine, then merges and de-duplicates the candidates. One source failing does not block the
+others. The browser source is always in the default set, so `search` works with zero provider
+config: with nothing configured it still runs the headless browser search engine and returns
+candidates. Pass `--providers exa,tavily` to restrict to the fast APIs only.
+
+### When to reach for browser search
+
+Reach for `browser search`, or the browser source inside `search`, when the APIs come back empty
+or shallow. It is slower than the APIs, but it runs against the user's real Edge/Chromium and
+searches the way a person does, so sites that hide behind strong anti-bot become reachable, and
+those sites usually hide because their content is worth protecting. It carries the user's login
+cookies and search history, so the results track their habits and the search engine's
+personalization model. When exa and tavily give you nothing useful on a niche or protected topic,
+fall back to browser search before you give up. It runs headless, so it does not steal focus from
+the user's daily browser.
+
+### `ask "<question>"`: natural-language answer from a web-enabled LLM
+
+`ask` sends your question to the configured `openai_compat` LLM (pick a model with built-in web
+search) and returns its markdown answer plus an extracted citations list. Use it for a direct
+answer to a small question. Treat the prose as a lead, not a fact: for anything that matters,
+`fetch` the cited page and read it yourself.
+
+## Capability map (pick by what the task needs; no hardcoded routing)
+
+Four independent domains. Each tool has a distinct strength; choose per task, not by a fixed
+order. Tool selection is YOUR decision.
+
+### A. Web search and page fetch, tiered by anti-bot strength
+
+When you need the open web, prefer the **lowest tier that can do the job**. API tools are
+fastest because they skip browser rendering, and they cost the least. Escalate only when a
+tier genuinely cannot return the content.
+
+| Tier | Tool | Strength | Use when |
+|------|------|----------|----------|
+| 1. API | `exa`, `tavily` | Structured search APIs; clean JSON, no rendering. `tavily extract` returns ready markdown, `tavily map`/`crawl` cover a whole site; `exa` adds `similar`, `contents`, `answer`, and async `research`. Fast and cheap. | Simple or public pages; search with snippets; fast fetch of a known URL; site map or crawl. |
+| 2. Firecrawl | `firecrawl` | Residential or home-bandwidth infrastructure; `scrape` and `search` are **keyless**, the other endpoints (`map`, `crawl`, `extract`, `interact`, `agent`, `monitor`, `parse`) need a key. More likely than Tier 1 to succeed on lightly protected pages, and the only tier with site-wide crawl and structured extraction. | A page refuses raw HTTP but shows no hard Cloudflare challenge. Batch scrape many URLs, crawl a whole site, or extract structured data with a schema. |
+| 3. Browser | `fetch`, `browser` | Drives the user's real Edge/Chromium, same engine as the daily browser so login cookies stay valid. `fetch` auto-escalates: normal API, then a headed browser with Cloudflare auto-detect (no challenge means solve returns instantly). `browser` is the direct browser platform when you already know you want the browser: `browser fetch` (headed + CF auto-detect, skips the API) and `browser search` (headless search engine: Bing CN/intl, Google). | Everything above failed; or the page is behind Cloudflare, needs JS, or needs login cookies; or you want a browser search engine directly. |
+
+Notes:
+- Escalation is **automatic inside `fetch`**: normal API, then a headed browser with CF
+  auto-detect (no CF challenge means solve returns instantly). You usually just call `fetch`
+  and let it climb.
+- `browser` is the direct browser platform, used when you already know the page needs a
+  browser: `browser fetch` skips the API and goes straight to the headed browser with CF
+  auto-detect; `browser search` runs a headless search engine (default Bing international,
+  since CN Bing filters some sensitive terms).
+- `fetch` and `browser fetch` inject login cookies through the bundled MV3 extension bridge,
+  so logged-in pages work without re-entering credentials.
+- The Cloudflare bypass runs on DrissionPage against the user's real browser. If that runtime
+  dependency is missing, `fetch` and `browser fetch` report a clear install hint (exit code 5,
+  antibot) instead of silently failing.
+
+### B. Official docs, Context7 (`ctx7`), an independent domain
+
+`ctx7 library "<name>" "<question>"` resolves a library id. `ctx7 docs /org/repo
+"<question>"` returns up-to-date official docs as markdown. It hits the authoritative source
+directly, so it is fast and accurate.
+
+**For any library, framework, SDK, CLI, or cloud-service question, prefer `ctx7` over web
+search.** Do not grep the open web for API syntax, config keys, or version-migration notes
+that Context7 can serve from the source.
+
+### C. Ask a web-enabled LLM (`ask`), natural-language Q&A, LOW trust on the answer
+
+`ask "<question>"` sends your natural-language question to the configured `openai_compat`
+LLM (model must have built-in web search). It returns the model's markdown answer with
+inline source links, plus an extracted citations list. Use it for a direct answer to a small
+question; this differs from `search`, which aggregates the exa/tavily search APIs and returns
+only URLs.
+
+Why low trust on the answer: the LLM is great for **breadth** and for fuzzy or niche
+questions, but its synthesized prose is unreliable. Expect context pollution, hallucinated
+URLs, and stale facts. Treat the answer as a lead; for any actual fact, `fetch` the cited
+page and read it yourself.
+
+### D. Long local documents, `locate`
+
+`locate <md_path> "<query>"` does anchor-based relevance scanning: it chunks the document,
+scores chunks with a small model, then matches code strings back to exact line numbers. Use
+it to **pre-screen which parts of a long page or doc matter** before reading, so you avoid
+blind full reads of 10k-line files.
+
+## Core principle: consume sources, do not inherit synthesis
+
+Every search and locate tool returns **candidate sources or locations**, not a conclusion to
+trust verbatim. Read the fetched sources yourself and synthesize your own answer. Never
+fabricate a source you did not fetch.
+
+## Use high concurrency; this is the point of the toolkit
+
+These tools are cheap and independent. Fire many in parallel; do not serialize.
+
+- **One question, many sources at once.** In a single turn, issue `exa search`, `tavily
+  search`, `ctx7 docs`, and `ask` together (parallel tool calls); merge and de-duplicate
+  the candidate URLs, then `fetch` the best ones. This is far faster than search, read,
+  search, read.
+- **Batch fetch.** `fetch url1 url2 url3` fetches all concurrently (one browser, many pages,
+  `--concurrency N`). `firecrawl scrape u1 u2 u3` batches too. Never loop one URL at a time
+  when a batch call exists.
+- **Many pages, one locate.** Run `locate` once on the whole document to pin the relevant
+  sections, then read only those.
+
+Reserve serial work for genuine dependencies (you need URL X's content to formulate the next
+query). Otherwise, fan out.
+
+## Commands (JSON on stdout by default; `--output markdown` for readable markdown)
+
+Pick a tool by what the task needs. Each command's comment states its strength and when to
+use it. Async endpoints (crawl, extract, research, agent) block until done or `--poll-timeout`,
+and accept `--async-submit` to return the job id immediately instead of waiting.
+
+### A. Web search and page fetch, escalate only when the lower tier fails
+
+```sh
+# Tier 1: structured search APIs. Clean JSON, fastest, cheapest. Start here for simple or public pages.
+research-assistant exa search "<query>" [--num-results N] [--type auto|keyword|neural|fast] [--text] [--highlights] [--category CAT] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--include-domains D ...] [--exclude-domains D ...]
+research-assistant exa similar <url> [--num-results N]              # pages semantically similar to a URL
+research-assistant exa contents <id>... [--text] [--highlights]     # fetch body for Exa IDs or URLs
+research-assistant exa answer "<question>" [--text]                 # LLM answer grounded in Exa results
+research-assistant exa research "<instructions>" [--model exa-research|exa-research-pro] [--output-schema JSON | --infer-schema] [--poll-timeout N] [--async-submit]   # async in-depth research
+
+research-assistant tavily search "<query>" [--depth ultra-fast|fast|basic|advanced] [--max-results N] [--topic general|news|finance] [--time-range day|week|month|year] [--include-answer basic|true|advanced] [--country C] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--chunks-per-source N] [--include-raw-content markdown|text] [--include-images] [--include-domains D ...] [--exclude-domains D ...] [--auto-parameters]
+research-assistant tavily extract <url>... [--extract-depth basic|advanced] [--format markdown|text]   # ready markdown, no rendering
+research-assistant tavily map <url> [--max-depth N] [--max-breadth N] [--limit N] [--select-paths REGEX ...] [--instructions TEXT] [--timeout N]   # list a site's reachable URLs
+research-assistant tavily crawl <url> [--max-depth N] [--limit N] [--instructions TEXT] [--extract-depth basic|advanced] [--no-external] [--timeout N]   # recursive crawl, markdown per page
+
+# Tier 2: Firecrawl. Residential bandwidth. scrape and search are keyless; the rest need a key.
+research-assistant firecrawl scrape <url>... [--format markdown|html] [--only-main-content] [--wait-for MS]   # batch markdown, keyless
+research-assistant firecrawl search "<query>" [--limit N] [--sources web|news] [--scrape]                      # keyless; --scrape returns full markdown per result
+research-assistant firecrawl map <url> [--limit N] [--include-subdomains]                                      # needs key
+research-assistant firecrawl crawl <url> [--limit N] [--max-depth N] [--include-paths REGEX ...] [--allow-subdomains] [--prompt TEXT] [--poll-timeout N] [--async-submit]   # async recursive crawl
+research-assistant firecrawl extract <url>... [--prompt TEXT | --schema JSON] [--enable-web-search] [--agent] [--poll-timeout N] [--async-submit]   # LLM structured extraction, async
+research-assistant firecrawl interact "<prompt>" [--scrape-id ID | --url URL] [--code TEXT --language node|python|bash] [--timeout S] [--stop]   # live browser session bound to a scrape
+research-assistant firecrawl agent "<prompt>" [--model spark-1-mini|spark-1-pro] [--urls U ...] [--schema JSON] [--max-credits N] [--strict] [--poll-timeout N] [--async-submit]   # autonomous extraction
+research-assistant firecrawl monitor                                                                       # list active crawl jobs
+research-assistant firecrawl parse <file> [--format markdown|html|json ...] [--pdf-mode fast|auto|ocr] [--max-pages N]   # parse a local document
+
+# Tier 3: real browser. fetch auto-escalates (normal API, then headed browser with CF auto-detect).
+research-assistant fetch <url> [<url>...] [--concurrency N] [--login|--no-login] [--no-browser] [--output PATH]
+
+# browser platform: direct browser, no API attempt. fetch = headed + CF auto-detect; search = headless engine.
+research-assistant browser fetch <url>... [--no-login] [--concurrency N] [--write PATH]   # skip the API, straight to the headed browser (--write, not global --output)
+research-assistant browser search "<query>" [--engine bing-cn|bing-intl|google] [--limit N] [--max-pages N]   # headless search engine (default bing-intl)
+
+# Aggregate the search sources in one call (default: configured exa,tavily + browser; browser is
+# always in the default set and works with zero config). Keywords, not an LLM.
+research-assistant search "<query>" [--providers exa,tavily,firecrawl,browser] [--limit N]
+```
+
+### B. Official docs, Context7 (authoritative; prefer over web search for library/SDK/CLI/cloud)
+
+```sh
+research-assistant ctx7 library "<name>" "<question>"       # resolve a library id
+research-assistant ctx7 docs /org/repo "<question>"         # up-to-date official docs
+```
+
+### C. Ask a web-enabled LLM in natural language (`ask`)
+
+`ask` sends your question to the configured `openai_compat` provider (config `[providers.openai_compat]`: base_url, api_key, model). Pick a model with built-in web search; the CLI sends a plain chat request and the model searches on its own, returning a markdown answer with inline source links. The command returns that markdown plus an extracted citations list. Use it for a direct answer to a small question; to gather URLs from the search APIs instead, use `search`.
+
+```sh
+research-assistant ask "<natural-language question>" [--system TEXT]
+```
+
+### D. Long-doc locating, pre-screen which parts of a 10k-line file matter before reading
+
+```sh
+research-assistant locate <md_path> "<query>" [--top N] [--scope lines|paragraph] [--context N] [--concurrency N]
+```
+
+### Setup and management
+
+```sh
+research-assistant setup [--non-interactive | --config-inline TOML] [--provider TYPE[,k=v,...]] ... [--proxy URL] [--browser-channel msedge|chrome] [--daemon-port N] [--install-skills claude,codex,...]   # configure providers/proxy/browser; --install-skills writes the skill+agent files
+research-assistant doctor [--show-config] [--target <name>]              # connectivity diagnostics; --show-config prints config (masked), --target checks one provider or builtin
+research-assistant skills status [--targets claude,codex,...] [--skills-root PATH]   # managed skill/agent freshness
+research-assistant skills update [--targets claude,codex,...] [--skills-root PATH]   # refresh managed files
+```
+
+### Global flags (allowed anywhere on the command line)
+
+```sh
+research-assistant [--config PATH] [--output json|markdown] [--proxy URL|none] [--verbose] [--version] <command> ...
+```
+
+Every command also takes `-h`/`--help`: `research-assistant --help` lists all commands; `research-assistant <command> [--subcommand] --help` shows that command's arguments.
+
+## Research workflow (you decide the steps)
+
+1. Fan out search and docs (`exa` + `tavily` + `ctx7` + `ask`) to get candidate sources.
+2. `fetch` the most promising URLs in one batch to get clean local markdown.
+3. For long pages, `locate` to pin relevant passages before reading.
+4. Synthesize YOUR answer from what you actually fetched; cite URLs.
+
+For large, multi-source investigations, delegate to the `researcher` sub-agent. It runs this
+workflow in an isolated context, writes a full report to `tmp-doc/`, and returns only a
+summary, keeping the main context clean.
+
+## Output and errors
+
+Output defaults to JSON on stdout (parseable). Pass `--output markdown` for human or AI
+readable markdown. Errors always surface as
+`{"error":{"code","message","provider?","details?"}}` on stdout, plus a one-line
+`error: ...` on stderr, with exit codes:
+`0` ok, `1` internal, `2` args, `3` config, `4` network, `5` antibot.

package/src/research_assistant/cli.py

@@ -0,0 +1,155 @@
+"""CLI 入口：全局 flag 预解析 + 动态命令路由 + 统一分发/错误处理。
+
+命令树（api-contract.md §2）：
+    research-assistant [全局flags] <tool|cmd> <subcommand> [args] [flags]
+
+  provider 命令（从 registry 动态生成，ADR-0011）：
+    ctx7/exa/tavily/firecrawl + openai_compat 的各自子命令
+  research-assistant 增值命令：fetch / locate / search
+  管理命令：setup / skills / doctor
+
+全局 flags 可出现在任意位置（预解析抽离）：
+    --config <path>  --output json|markdown  --proxy <url>  --verbose  --version
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from typing import Any, Sequence
+
+from . import __version__
+from .config import load as load_config
+from .errors import ArgsError, ResearchAssistantError
+from .output import emit, emit_error, emit_json
+from .providers import all_provider_classes
+from . import proxy as proxy_mod
+
+
+# ---------------------------------------------------------------------------
+# 命令分发 handler 契约：async(args_ns, config) -> dict
+# ---------------------------------------------------------------------------
+
+
+def _wrap_provider_handler(bound_handler: Any) -> Any:
+    """把 provider 的 bound handler(self 已绑定) 适配成 (args_ns, config) 契约。"""
+
+    async def runner(args_ns: argparse.Namespace, config: Any) -> Any:
+        return await bound_handler(args_ns)
+
+    return runner
+
+
+def _build_parser(config: Any) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="research-assistant",
+        description="搜索调研子 Agent + 可并发的搜索/爬取/定位 CLI 原子工具。",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subs = parser.add_subparsers(dest="command", required=True, metavar="<command>")
+
+    # ---- provider 命令（动态，从 registry 生成）----
+    for ptype, pclass in sorted(all_provider_classes().items()):
+        provider = pclass(config)
+        cap_list = provider.capabilities()
+        if not cap_list:
+            continue
+        names = [provider.command] + list(provider.aliases or [])
+        names = [n for n in names if n]
+        if not names:
+            continue
+        p_parser = subs.add_parser(
+            names[0],
+            aliases=names[1:],
+            help=pclass.help,
+            description=pclass.help,
+        )
+        p_sub = p_parser.add_subparsers(dest="subcommand", required=True, metavar="<subcommand>")
+        for cap in cap_list:
+            c_parser = p_sub.add_parser(cap.name, help=cap.help, description=cap.help)
+            for arg in cap.args:
+                arg.add_to(c_parser)
+            c_parser.set_defaults(_handler=_wrap_provider_handler(cap.handler))
+
+    # ---- 原生命令 ----
+    from .commands import ask as ask_cmd
+    from .commands import fetch as fetch_cmd
+    from .commands import locate as locate_cmd
+    from .commands import search as search_cmd
+    from .commands import setup as setup_cmd
+    from .commands import skills as skills_cmd
+    from .commands import doctor as doctor_cmd
+
+    for cmd in (fetch_cmd, locate_cmd, search_cmd, ask_cmd, setup_cmd, skills_cmd, doctor_cmd):
+        cmd.register(subs)
+
+    return parser
+
+
+def _parse_globals(argv: Sequence[str]) -> tuple[argparse.Namespace, list[str]]:
+    """预解析全局 flags（允许出现在命令任意位置），返回 (globals_ns, remaining_argv)。"""
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("--config", default=None, dest="config_path")
+    pre.add_argument("--output", default="json", choices=["json", "markdown"])
+    pre.add_argument("--proxy", default=None, help="Proxy URL override (横切); 'none' = force direct, no proxy.")
+    pre.add_argument("--verbose", action="store_true")
+    pre.add_argument("--version", action="store_true")
+    ns, remaining = pre.parse_known_args(list(argv))
+    return ns, remaining
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    g_ns, remaining = _parse_globals(argv)
+
+    if g_ns.version:
+        print(f"research-assistant {__version__}")
+        return 0
+
+    # 代理横切覆盖（CLI --proxy 优先级最高，ADR-0007）
+    proxy_mod.set_override(g_ns.proxy)
+
+    # 加载配置（文件不存在=首次使用，返回空 Config）
+    try:
+        config = load_config(g_ns.config_path)
+    except ResearchAssistantError as e:
+        emit_json(e.to_json())
+        emit_error(e.message)
+        return e.exit_code()
+
+    # 构建并解析子命令树
+    parser = _build_parser(config)
+    try:
+        args_ns = parser.parse_args(remaining)
+    except SystemExit as e:  # argparse 解析失败/--help 已退出
+        code = e.code if isinstance(e.code, int) else 2
+        return code
+
+    handler = getattr(args_ns, "_handler", None)
+    if handler is None:  # 只有顶层命令没有 sub（理论上 required=True 已挡）
+        parser.print_help(sys.stderr)
+        return 2
+
+    try:
+        result = asyncio.run(handler(args_ns, config))
+    except ResearchAssistantError as e:
+        emit_json(e.to_json())
+        emit_error(e.message)
+        return e.exit_code()
+    except KeyboardInterrupt:
+        emit_error("已中断")
+        return 1
+    except Exception as e:  # 兜底：未预期异常 → INTERNAL
+        err = ResearchAssistantError(f"内部错误: {e}", details={"type": type(e).__name__})
+        emit_json(err.to_json())
+        emit_error(err.message)
+        return err.exit_code()
+
+    emit(result, g_ns.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/research_assistant/commands/__init__.py

@@ -0,0 +1,7 @@
+"""commands 包：research-assistant 原生命令（fetch/locate/search/setup/skills/doctor）。
+
+每个模块暴露：
+    NAME / ALIASES / HELP
+    register(subparsers) —— 向 CLI 注册子命令与参数，set_defaults(_handler=run)
+    async run(args_ns, config) -> dict
+"""

package/src/research_assistant/commands/ask.py

@@ -0,0 +1,54 @@
+"""ask 命令：自然语言问一个自带 web 搜索的 LLM，拿它的 markdown 回答 + 抽出的信源。
+
+    research-assistant ask "<natural-language question>"
+
+和 search（聚合 exa/tavily 搜索 API）的区别：ask 走 openai_compat（你配的、model 自带
+web 搜索的 LLM）。你发自然语言意图，LLM 理解后自己搜、自己组织答案；返回 LLM 的
+markdown 回答（引用链接嵌在正文里）+ 抽出的 citations 列表。适合主 agent 遇到小问题、
+不想自己调一堆工具、直接发自然语言拿结果的轻量场景。
+
+model 必须自带 web 搜索（如 grok 类）：CLI 只发普通 chat 请求，搜索由 model 自身能力
+完成；若 model 不会搜，content 里不会有真实信源、citations 为空。
+
+响应：{content(str, markdown), citations[]{url, title?, snippet?}}
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from ..config import Config
+from ..providers import openai_compat
+
+NAME = "ask"
+ALIASES: list[str] = []
+HELP = "Ask a web-enabled LLM in natural language; returns its markdown answer plus sources."
+
+_ASK_SYSTEM_PROMPT = (
+    "You are a web research assistant. Search the web to answer the user's question. "
+    "Answer in clear markdown and cite sources inline as links. "
+    "Prefer official documentation and reputable sites."
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    p.add_argument("query", help="Natural-language question.")
+    p.add_argument("--system", help="Override the system prompt.")
+    p.set_defaults(_handler=run)
+
+
+async def run(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": args.system or _ASK_SYSTEM_PROMPT},
+        {"role": "user", "content": args.query},
+    ]
+    response = await openai_compat.chat_completion(config, messages, temperature=0.0)
+    msg = openai_compat.extract_message(response)
+    content = openai_compat.strip_think(msg.get("content") or "")
+    citations = openai_compat.extract_citations(response, msg)
+    out: dict[str, Any] = {"content": content}
+    if citations:
+        out["citations"] = citations
+    return out

package/src/research_assistant/commands/doctor.py

@@ -0,0 +1,201 @@
+"""doctor 命令：连通性诊断（api-contract §2.3 / 场景 E）。
+
+    research-assistant doctor [--show-config] [--target <name>]
+
+对每个已配置 provider 做最小请求；locate 模型 ping；浏览器+cookie daemon 探测。
+--show-config 展示配置（密钥遮蔽）。退出码 0=诊断完成（可达性体现在 report）。
+响应：{checks[]{target, reachable, latency_ms, error?}, config_complete, config?}
+"""
+
+from __future__ import annotations
+
+import argparse
+import time
+from typing import Any
+
+from .. import providers as providers_pkg
+from ..config import Config, mask_secret
+from ..errors import ResearchAssistantError
+from ..providers import openai_compat
+
+NAME = "doctor"
+ALIASES: list[str] = ["diag"]
+HELP = "Run connectivity diagnostics across configured providers."
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    p.add_argument("--show-config", action="store_true", help="Show config (secrets masked).")
+    p.add_argument("--target", help="Only check a single provider/builtin target.")
+    p.set_defaults(_handler=run)
+
+
+async def run(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    checks: list[dict[str, Any]] = []
+    configured_types = {p.type for p in config.providers}
+
+    targets: list[str] = []
+    if args.target:
+        targets = [args.target]
+    else:
+        # 已配置的 provider + 浏览器；firecrawl 免 key 层永远可用，始终检查
+        configured = set(configured_types)
+        targets = [t for t in ("openai_compat", "locate", "exa", "tavily", "context7") if t in configured]
+        targets.append("firecrawl")
+        targets.append("browser")
+
+    for target in targets:
+        checks.append(await _check(target, config))
+
+    config_complete = _config_complete(config)
+    result: dict[str, Any] = {"checks": checks, "config_complete": config_complete}
+    if args.show_config:
+        result["config"] = _masked_config(config)
+    return result
+
+
+def _config_complete(config: Config) -> bool:
+    """配置是否足以做完整调研。
+
+    搜索源：firecrawl 免 key 层永远可用，故搜索能力始终具备（exa/tavily/context7 是增强）。
+    LLM：openai_compat（驱动 search）或 locate（驱动 locate）至少一个就绪才算完整。
+    """
+    pc = config.provider("openai_compat")
+    has_llm = bool(pc and pc.api_key and pc.base_url and pc.model)
+    lc = config.provider("locate")
+    has_locate = bool(lc and lc.api_key and lc.base_url and lc.model)
+    return has_llm or has_locate
+
+
+async def _check(target: str, config: Config) -> dict[str, Any]:
+    start = time.perf_counter()
+    try:
+        if target == "browser":
+            ok, msg = await _check_browser(config)
+        elif target == "openai_compat":
+            await openai_compat.chat_completion(
+                config, [{"role": "user", "content": "ping"}], provider_type="openai_compat"
+            )
+            ok, msg = True, "ok"
+        elif target == "locate":
+            await openai_compat.chat_completion(
+                config, [{"role": "user", "content": "ping"}], provider_type="locate"
+            )
+            ok, msg = True, "ok"
+        else:
+            ok, msg = await _check_provider(target, config)
+    except ResearchAssistantError as e:
+        ok, msg = False, e.message
+    except Exception as e:  # noqa: BLE001
+        ok, msg = False, f"{type(e).__name__}: {e}"
+    latency_ms = round((time.perf_counter() - start) * 1000, 1)
+    item: dict[str, Any] = {"target": target, "reachable": ok, "latency_ms": latency_ms}
+    if not ok:
+        item["error"] = msg
+    return item
+
+
+async def _check_provider(ptype: str, config: Config) -> tuple[bool, str]:
+    """用 provider 的最小能力做存活探测（复用插件实例与真实代码路径）。"""
+    classes = providers_pkg.all_provider_classes()
+    pclass = classes.get(ptype)
+    if pclass is None:
+        return False, f"provider '{ptype}' 未注册"
+    provider = pclass(config)
+    caps = provider.capabilities()
+    # 选一个轻量能力：search / library / map
+    preferred = next((c for c in caps if c.name in ("search", "library", "map")), None)
+    if preferred is None:
+        return False, f"{ptype}: 无可用探测能力"
+    ns = _minimal_namespace(preferred.name)
+    await preferred.handler(ns)
+    return True, "ok"
+
+
+def _minimal_namespace(cap_name: str) -> argparse.Namespace:
+    """构造各 provider 最小查询所需的 args（带全部默认值，避免 AttributeError）。"""
+    base = {
+        "query": "test",
+        "name": "test",
+        "library_id": "/facebook/react",
+        "num_results": 1,
+        "max_results": 1,
+        "limit": 1,
+        "type": "auto",
+        "depth": "basic",
+        "topic": "general",
+        "text": False,
+        "highlights": False,
+        "include_domains": None,
+        "exclude_domains": None,
+        "category": None,
+        "start_date": None,
+        "time_range": None,
+        "include_answer": None,
+        "scrape": False,
+        "sources": None,
+        "include_subdomains": False,
+        "only_main_content": False,
+        "wait_for": None,
+        "extract_depth": "basic",
+        "format": "markdown",
+        "tokens": 200,
+        "ids": [],
+        "url": "https://example.com",
+        "urls": ["https://example.com"],
+    }
+    return argparse.Namespace(**base)
+
+
+async def _check_browser(config: Config) -> tuple[bool, str]:
+    """探测本地浏览器（Playwright channel）与 cookie daemon。"""
+    # cookie daemon 状态（HTTP /status）
+    daemon_msg = await _check_daemon(config)
+    # 浏览器可启动性（仅探测 channel 可执行是否存在，不真启动以省时）
+    from ..fetch import browser_probe
+
+    browser_msg = browser_probe(config.browser.channel)
+    ok = "可用" in browser_msg
+    msg = f"browser={browser_msg}; daemon={daemon_msg}"
+    return ok, msg
+
+
+async def _check_daemon(config: Config) -> str:
+    import aiohttp
+
+    url = f"http://127.0.0.1:{config.browser.daemon_port}/status"
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, timeout=aiohttp.ClientTimeout(total=3)) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return f"在线(扩展已连={data.get('extConnected', False)})"
+                return f"HTTP {resp.status}"
+    except Exception:
+        return "离线（未启动或扩展未装；fetch 时会按需拉起）"
+
+
+def _masked_config(config: Config) -> dict[str, Any]:
+    return {
+        "config_path": config.path,
+        "schema_version": config.schema_version,
+        "providers": [
+            {
+                "type": p.type,
+                "base_url": p.base_url,
+                "api_key": mask_secret(p.api_key),
+                "model": p.model,
+                "timeout": p.timeout,
+                **({"concurrency": p.concurrency} if p.type == "locate" else {}),
+            }
+            for p in config.providers
+        ],
+        "proxy": {"url": config.proxy.url or "(空=自动检测)"},
+        "browser": {
+            "channel": config.browser.channel,
+            "extension_status": config.browser.extension_status,
+            "daemon_port": config.browser.daemon_port,
+            "profile_strategy": config.browser.profile_strategy,
+            "max_browser_instances": config.browser.max_browser_instances,
+        },
+    }