research-assistant 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 research-assistant contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-ZH.md

@@ -0,0 +1,115 @@
+# research-assistant
+
+面向 AI agent 的并发 search / fetch / locate CLI 工具集。一次调用扇出到多个 provider 并行采集
+候选信源和页面，然后由你自己阅读、得出答案。
+
+阅读：[English](README.md)
+
+> **中间件，不是神谕。** 它采集信源，不替你下结论。每次 search 返回候选 URL，每次 fetch 返回
+> 页面正文；综合判断是你的事。
+
+## 为什么需要
+
+agent 常常耗费大量往返和上下文去做"一次并发工具集本来一次调用就能搞定"的事：跨引擎搜索、抓取
+Cloudflare 后的页面、取官方文档、在长文件里定位段落。`research-assistant` 把这些采集工作收进
+一个 CLI，并提供一个 `researcher` 子 agent 处理大型调研，保持主上下文干净。
+
+## 特性
+
+- **多源聚合搜索** — 一次 `search` 扇出到 `exa`、`tavily`、`firecrawl` 和无头浏览器引擎
+  （必应 / 谷歌），合并去重。**零配置可用**：浏览器源不需要 API key，永远在默认集合里。
+- **Cloudflare / 反爬绕过** — `fetch` 驱动你**真实的** Edge/Chromium（有头，Cloudflare 检测不到
+  headless），点击穿过 Turnstile。自动升级：先走便宜的 API，失败才上真实浏览器。
+- **一个浏览器，多个 tab** — 抓 N 个 URL 只开一个浏览器进程 + N 个 tab，不是 N 个浏览器。搜索
+  按首页结果数智能推断、并发翻页；跨进程实例上限防止浏览器失控。
+- **登录 cookie 桥接** — 内置 MV3 扩展把日常浏览器的登录 cookie 注入 fetch，登录页无需重输凭据。
+- **官方文档直取** — `ctx7 docs` 经 Context7 返回最新的库 / SDK / CLI / 云文档，比搜开放网页更快
+  更准。
+- **web-LLM `ask` + 长文档 `locate`** — `ask` 用自带网页搜索的 LLM 回答自然语言问题并附引用；
+  `locate` 在阅读前锁定 10k 行文件里哪些段落重要。
+- **插件式 provider** — 加一个 provider = 一个模块 + 一条配置；注册表自动发现，出现在 `--help`。
+  无需改路由或 CLI。
+- **可脚本化** — stdout 默认 JSON（`--output markdown` 给人看）；语义退出码（`0` 成功 · `1` 内部
+  · `2` 参数 · `3` 配置 · `4` 网络 · `5` 反爬）。可作为 skill 装进 Claude Code、Codex 等。
+
+## 快速开始
+
+```sh
+uv venv .venv
+uv pip install -e . --python .venv/Scripts/python.exe
+research-assistant setup                 # 配置 provider + 安装 skill/agent（可选）
+research-assistant search "python asyncio" --limit 10
+research-assistant fetch https://example.com
+```
+
+没有 provider key？`search` 和 `fetch` 仍能用：浏览器源和 Firecrawl 的免 key 层不需要。
+
+## 命令
+
+```sh
+# 搜索
+research-assistant search "<q>" [--providers exa,tavily,firecrawl,browser]   # 聚合
+research-assistant browser search "<q>" [--engine bing-cn|bing-intl|google]  # 直连浏览器引擎
+research-assistant exa|tavily search "<q>"                                   # 结构化 API
+
+# 抓取
+research-assistant fetch <url> [<url>...]      # API，然后真实浏览器 + CF 绕过（自动）
+research-assistant browser fetch <url>...      # 直奔真实浏览器
+research-assistant firecrawl scrape <url>...   # 免 key markdown
+
+# 文档 & 问答
+research-assistant ctx7 docs /org/repo "<q>"   # 官方文档（Context7）
+research-assistant ask "<question>"            # web-LLM 回答 + 引用
+
+# 长文档
+research-assistant locate <md_path> "<q>"      # 锚点式相关性扫描
+
+# 管理
+research-assistant setup                       # 配置 + 安装 skill/agent
+research-assistant doctor [--show-config]      # 连通性诊断
+research-assistant skills status               # 受管 skill/agent 新鲜度
+```
+
+完整列表见 `research-assistant --help`；每条命令也支持 `-h`。
+
+## 配置
+
+配置在 `~/.research-assistant/config.toml`（环境变量 `RA_<TYPE>_<FIELD>` 覆盖）：
+
+```toml
+schema_version = 1
+
+[[provider]]
+type     = "exa"
+api_key  = "..."
+base_url = "https://api.exa.ai"
+
+[[provider]]
+type     = "openai_compat"          # 驱动 `ask`
+base_url = "https://api.example.com/v1"
+api_key  = "..."
+model    = "grok-..."
+
+[proxy]
+url = ""                            # 空 = 自动检测系统代理
+
+[browser]
+channel               = "msedge"    # msedge | chrome
+max_browser_instances = 3           # 并发浏览器进程上限（跨 CLI）
+```
+
+未配置的 provider 直接跳过。`firecrawl scrape` / `search` 和浏览器源是免 key 的，所以空配置下
+`search` 和 `fetch` 也能跑。
+
+## 工作原理
+
+每条命令是对 provider 插件的一个薄 async 包装。`search` 扇出到各 provider 合并；`fetch` 先走便宜
+的 API，失败升级到真实浏览器 + Cloudflare 绕过；`locate` 把文档切块、用小模型打分。输出默认 JSON
+供主 agent 解析，另有 markdown 模式给人看。
+
+大型调研可分派 `researcher` 子 agent：它在隔离上下文里跑完整的 search → fetch → locate 流程，把报告
+写到磁盘，只返回摘要，重活阅读不污染主上下文。
+
+## 许可
+
+MIT

package/README.md

@@ -0,0 +1,124 @@
+# research-assistant
+
+Concurrent search / fetch / locate CLI tools for AI agents. Fan out across many providers in
+parallel, gather candidate sources and pages, then read them yourself to form the answer.
+
+Read this in: [中文](README-ZH.md)
+
+> **Middleware, not an oracle.** It collects sources. It does not write your conclusion. Every
+> search returns candidate URLs, every fetch returns the page body; synthesis is your job.
+
+## Why
+
+Agents burn turns and context doing what one concurrent tool-set can do in a single call: search
+across engines, fetch pages past Cloudflare, pull official docs, locate passages in long files.
+`research-assistant` does all of that gathering in one CLI, and ships a `researcher` sub-agent
+for large investigations that keeps the host context clean.
+
+## Features
+
+- **Aggregated multi-source search** — one `search` call fans out across `exa`, `tavily`,
+  `firecrawl`, and a headless browser engine (Bing/Google), then merges and de-duplicates.
+  **Zero-config works**: the browser source needs no API key and is always in the default set.
+- **Cloudflare & anti-bot bypass** — `fetch` drives your **real** Edge/Chromium (headed, so
+  Cloudflare does not flag it) and clicks through Turnstile. It auto-escalates: cheap API first,
+  real browser only when the API fails.
+- **One browser, many tabs** — fetching N URLs opens one browser process with N tabs, not N
+  browsers. Search paginates concurrently with smart page-count inference; a cross-process
+  instance cap prevents runaway browsers.
+- **Login cookies bridged** — a bundled MV3 extension pipes your daily browser's login cookies
+  into fetch, so logged-in pages work without re-entering credentials.
+- **Official docs from the source** — `ctx7 docs` returns up-to-date library / SDK / CLI / cloud
+  docs via Context7, faster and more accurate than grepping the open web.
+- **Web-LLM `ask` and long-doc `locate`** — `ask` gets a natural-language answer with citations
+  from a web-enabled LLM; `locate` pins which sections of a 10k-line file matter before you read.
+- **Plugin providers** — adding a provider is one module plus one config entry; the registry
+  auto-discovers it and it appears in `--help`. No router or CLI changes.
+- **Scriptable** — JSON on stdout by default (`--output markdown` for humans); semantic exit
+  codes (`0` ok · `1` internal · `2` args · `3` config · `4` network · `5` antibot). Installs as
+  a skill into Claude Code, Codex, and friends.
+
+## Quick start
+
+```sh
+uv venv .venv
+uv pip install -e . --python .venv/Scripts/python.exe
+research-assistant setup                 # configure providers + install skill/agent (optional)
+research-assistant search "python asyncio" --limit 10
+research-assistant fetch https://example.com
+```
+
+No provider keys? `search` and `fetch` still work: the browser source and Firecrawl's keyless
+tier need none.
+
+## Commands
+
+```sh
+# Search
+research-assistant search "<q>" [--providers exa,tavily,firecrawl,browser]   # aggregated
+research-assistant browser search "<q>" [--engine bing-cn|bing-intl|google]  # direct browser engine
+research-assistant exa|tavily search "<q>"                                   # structured APIs
+
+# Fetch
+research-assistant fetch <url> [<url>...]      # API, then real browser + CF bypass (auto)
+research-assistant browser fetch <url>...      # straight to the real browser
+research-assistant firecrawl scrape <url>...   # keyless markdown
+
+# Docs & Q&A
+research-assistant ctx7 docs /org/repo "<q>"   # official docs via Context7
+research-assistant ask "<question>"            # web-LLM answer + citations
+
+# Long docs
+research-assistant locate <md_path> "<q>"      # anchor-based relevance scan
+
+# Management
+research-assistant setup                       # configure + install skill/agent
+research-assistant doctor [--show-config]      # connectivity diagnostics
+research-assistant skills status               # managed skill/agent freshness
+```
+
+Run `research-assistant --help` for the full list; every command also takes `-h`.
+
+## Configuration
+
+Config lives at `~/.research-assistant/config.toml` (env overrides via `RA_<TYPE>_<FIELD>`):
+
+```toml
+schema_version = 1
+
+[[provider]]
+type     = "exa"
+api_key  = "..."
+base_url = "https://api.exa.ai"
+
+[[provider]]
+type     = "openai_compat"          # drives `ask`
+base_url = "https://api.example.com/v1"
+api_key  = "..."
+model    = "grok-..."
+
+[proxy]
+url = ""                            # empty = auto-detect system proxy
+
+[browser]
+channel               = "msedge"    # msedge | chrome
+max_browser_instances = 3           # concurrent browser-process cap (cross-CLI)
+```
+
+Unconfigured providers are simply skipped. `firecrawl scrape` / `search` and the browser source
+are keyless, so `search` and `fetch` work with an empty config.
+
+## How it works
+
+Each command is a thin async wrapper over a provider plugin. `search` fans out across providers
+and merges; `fetch` tries the cheap API then escalates to a real browser with Cloudflare bypass;
+`locate` chunks a document and scores chunks with a small model. Output is JSON by default so the
+host agent can parse it, with a markdown mode for humans.
+
+For large investigations, dispatch the `researcher` sub-agent: it runs the full
+search → fetch → locate workflow in isolation, writes a report to disk, and returns only a
+summary, so the heavy reading never pollutes the host context.
+
+## License
+
+MIT

package/npm/bin/research-assistant.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// bin shim：找到 venv python 并转发到 `python -m research_assistant.cli <args>`。
+// venv 缺失时自动修复（跑一次 postinstall）。
+const { spawn, spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const callerCwd = process.env.INIT_CWD || process.cwd();
+const venvDir = path.join(packageRoot, ".research-assistant-python");
+const pythonPath =
+  process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+
+function reinstallHint() {
+  console.error("修复：重装 npm 包");
+  console.error("  npm install -g research-assistant");
+}
+
+if (!fs.existsSync(pythonPath)) {
+  const postinstall = path.join(packageRoot, "npm", "scripts", "postinstall.js");
+  console.error("research-assistant Python 运行时缺失，尝试自动修复...");
+  const repaired = spawnSync(process.execPath, [postinstall], {
+    cwd: packageRoot,
+    stdio: "inherit",
+    windowsHide: true,
+    env: { ...process.env, PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" },
+  });
+  if (repaired.error) {
+    console.error(`运行时修复失败：${repaired.error.message}`);
+    reinstallHint();
+    process.exit(5);
+  }
+  if (repaired.status !== 0 || !fs.existsSync(pythonPath)) {
+    console.error("research-assistant 找不到 Python 运行时。");
+    console.error(`期望位置：${pythonPath}`);
+    reinstallHint();
+    process.exit(repaired.status || 5);
+  }
+}
+
+const child = spawn(
+  pythonPath,
+  ["-m", "research_assistant.cli", ...process.argv.slice(2)],
+  {
+    cwd: callerCwd,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      RESEARCH_ASSISTANT_PACKAGE_ROOT: packageRoot,
+      PYTHONIOENCODING: process.env.PYTHONIOENCODING || "utf-8",
+      PYTHONUTF8: process.env.PYTHONUTF8 || "1",
+    },
+    windowsHide: true,
+  }
+);
+
+child.on("error", (error) => {
+  console.error(`启动 research-assistant 失败：${error.message}`);
+  process.exit(5);
+});
+
+child.on("close", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 5);
+});

package/npm/scripts/postinstall.js

@@ -0,0 +1,112 @@
+// postinstall: 建 venv + 安装 Python 包（ADR-0003：uv 优先，回退 python -m venv + pip）。
+// PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 —— 用本地浏览器 channel，不下载 Chromium。
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const venvDir = path.join(packageRoot, ".research-assistant-python");
+
+function run(command, args, options = {}) {
+  const env = {
+    ...process.env,
+    PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1",
+    ...(options.env || {}),
+  };
+  const result = spawnSync(command, args, {
+    cwd: packageRoot,
+    stdio: options.stdio || "inherit",
+    encoding: "utf8",
+    env,
+    windowsHide: true,
+  });
+  if (result.error) {
+    return { ok: false, error: result.error };
+  }
+  return { ok: result.status === 0, status: result.status, stdout: result.stdout || "" };
+}
+
+function venvPython() {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+}
+
+function hasCommand(cmd) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const r = run(finder, [cmd], { stdio: "pipe" });
+  return r.ok;
+}
+
+function pythonCandidates() {
+  if (process.platform === "win32") {
+    return [
+      { command: "py", args: ["-3"] },
+      { command: "python", args: [] },
+      { command: "python3", args: [] },
+    ];
+  }
+  return [
+    { command: "python3", args: [] },
+    { command: "python", args: [] },
+  ];
+}
+
+function findPython() {
+  const probe = ["-c", "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)"];
+  for (const c of pythonCandidates()) {
+    const r = run(c.command, [...c.args, ...probe], { stdio: "pipe" });
+    if (r.ok) return c;
+  }
+  return null;
+}
+
+// ---- 主流程 ----
+let useUv = hasCommand("uv");
+
+// 1) 建 venv
+if (!fs.existsSync(venvPython())) {
+  console.log("Creating research-assistant Python runtime...");
+  if (useUv) {
+    const created = run("uv", ["venv", venvDir, "--python", "3.10"]);
+    if (!created.ok) {
+      console.error("uv venv 创建失败，回退到 python -m venv");
+      useUv = false;
+    }
+  }
+  if (!fs.existsSync(venvPython())) {
+    const py = findPython();
+    if (!py) {
+      console.error("research-assistant 需要 Python 3.10+。请安装 Python 后重试：");
+      console.error("  npm install -g research-assistant");
+      process.exit(1);
+    }
+    // python -m venv 自带 pip；uv venv 不带（uv 自己管包），故回退时重建带 pip 的 venv
+    const created = run(py.command, [...py.args, "-m", "venv", "--clear", venvDir]);
+    if (!created.ok) {
+      console.error("无法创建 Python 虚拟环境。");
+      process.exit(created.status || 1);
+    }
+    useUv = false;
+  }
+}
+
+// 2) 安装包（uv venv 用 uv pip；python venv 用 pip）
+console.log("Installing research-assistant Python package" + (useUv ? " (via uv)" : "") + "...");
+let installOk = false;
+if (useUv) {
+  const r = run("uv", ["pip", "install", "--python", venvPython(), packageRoot]);
+  installOk = r.ok;
+}
+if (!installOk) {
+  // 非 uv 路径（python -m venv 自带 pip）
+  const r = run(venvPython(), [
+    "-m", "pip", "install", "--disable-pip-version-check", packageRoot,
+  ]);
+  if (!r.ok) {
+    console.error("安装 research-assistant Python 包失败。");
+    process.exit(r.status || 1);
+  }
+}
+
+console.log("research-assistant ready.");

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "research-assistant",
+  "version": "0.1.0",
+  "description": "Search/research sub-agent + concurrent search/fetch/locate CLI atomic tools for AI agents (Exa, Tavily, Firecrawl, Context7, OpenAI-compatible).",
+  "license": "MIT",
+  "homepage": "https://github.com/arsonist-g/research-assistant-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arsonist-g/research-assistant-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/arsonist-g/research-assistant-cli/issues"
+  },
+  "bin": {
+    "research-assistant": "npm/bin/research-assistant.js"
+  },
+  "files": [
+    "npm/",
+    "src/research_assistant/**/*.py",
+    "src/research_assistant/assets/researcher_persona.md",
+    "src/research_assistant/assets/skills/research-assistant/SKILL.md",
+    "src/research_assistant/loginstate/extension/**",
+    "pyproject.toml",
+    "README.md",
+    "README-ZH.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node npm/scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "research-assistant"
+version = "0.1.0"
+description = "Search/research sub-agent + a set of concurrent search/fetch/locate CLI atomic tools for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "research-assistant" }]
+keywords = ["search", "research", "cli", "agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    # HTTP 客户端（各 provider 自写 HTTP，ADR-0010）
+    "httpx>=0.27",
+    # DrissionPage：CF 绕过兜底路径。直驱用户 Edge（不经自动化运行时，无注入痕迹）+
+    # DOM.getDocument(pierce) 穿透 closed shadow root 点 Turnstile checkbox（playwright 的
+    # performSearch 只穿透 UA shadow DOM，看不到 closed shadow root 里的 checkbox）。同步 API，
+    # browser.py 用 asyncio.to_thread 桥接到 async。
+    "DrissionPage>=4.1",
+    # pywin32：Windows 下隐藏 CF 兜底浏览器窗口（page.set.hide → Win32 ShowWindow SW_HIDE）。
+    # 窗口仍在（真 headed 渲染，CF 检测不到 headless），但不占视野。仅 Windows 需要。
+    "pywin32; sys_platform == 'win32'",
+    # HTML → markdown（浏览器回退路径用，ADR-0006 D6）
+    "trafilatura>=1.12",
+    # TOML 写入（setup 持久化配置，D3）
+    "tomli_w>=1.0",
+    # cookie daemon：单 aiohttp 进程同时承载 WS（扩展连）+ HTTP（fetch/doctor 调），ADR-0006
+    "aiohttp>=3.9",
+    # Python 3.10 没有 tomllib，需 tomli 读 TOML；3.11+ 内置 tomllib（环境标记自动按版本装）
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+# 测试依赖（开发期）。CI/贡献者：`uv pip install -e ".[dev]"` 安装。
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+research-assistant = "research_assistant.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/arsonist-g/research-assistant"
+
+[tool.hatch.build]
+# 中文审查版（SKILL-ZH.md / researcher_persona-ZH.md）仅供人工审阅：
+# 不进 git、不进发行包。installer 固定读 SKILL.md / researcher_persona.md，本就不会安装。
+exclude = [
+    "src/research_assistant/assets/skills/research-assistant/SKILL-ZH.md",
+    "src/research_assistant/assets/researcher_persona-ZH.md",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/research_assistant"]
+# assets/（SKILL.md、researcher 人设）与 loginstate/extension/（MV3 扩展）在包目录下，
+# 随 packages 递归包含，无需 force-include。
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "live_cf: 真实 Cloudflare 绕过实机测试（启动浏览器、访问外部站点，慢且依赖网络；默认跳过，手动 `pytest -m live_cf` 运行）",
+    "live_browser: browser 平台 live 测试（启动浏览器、访问外部站点；默认跳过，手动 `pytest -m live_browser` 运行）",
+]
+# 默认排除实机测试，保持快速基线干净；命令行 `-m live_cf` / `-m live_browser` 会覆盖此项
+addopts = "-m 'not live_cf and not live_browser'"

package/src/research_assistant/__init__.py

@@ -0,0 +1,7 @@
+"""research-assistant: 搜索调研子 Agent + 一组可并发的搜索/爬取/定位 CLI 原子工具。
+
+单进程 Python CLI，集成各搜索/文档工具（自写 HTTP，ADR-0010）+ fetch（浏览器爬取增强）
++ locate（锚点速览）+ setup/skills/doctor，通过 npm 包分发。
+"""
+
+__version__ = "0.1.0"

package/src/research_assistant/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m research_assistant` 调用 CLI。"""
+
+from research_assistant.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/research_assistant/assets/researcher_persona.md

@@ -0,0 +1,94 @@
+# researcher
+
+You are a **research sub-agent**. A host agent delegates a question to you that needs external
+information. You run in an **isolated context**: the host sees only what you return, so your
+job is to do the heavy reading here and hand back a trustworthy, source-grounded answer.
+
+**All external-information gathering MUST go through the `research-assistant` skill.** It is
+your toolkit and operating manual: the full tool map (`fetch` with automatic Cloudflare-bypass
+escalation; `search` aggregating the search APIs and the headless browser engine; Context7
+official docs; the `ask` web-LLM; `locate` for long docs), the concurrency strategy, and every
+command with its strength and "use when". Pick tools per the skill's guidance. Do not improvise
+sources or guess at tool behavior.
+
+## 0. Why you exist, and the one rule that matters most
+
+The host delegates to you precisely because gathering and reading sources is **token-expensive
+and context-polluting**. Doing that work in the host's context would crowd out the actual
+task. That is why you run isolated.
+
+The corollary is the most important rule in this document:
+
+> **Do not over-economize on tokens.** You are isolated; reading thoroughly here costs the
+> host nothing. The failure mode to avoid is *skimming and guessing*: reading only a snippet,
+> inferring the rest, and returning a plausible-sounding but unverified answer. Reading the
+> full relevant source is always cheaper than being wrong. When in doubt between "read more"
+> and "move on", read more.
+
+## 1. Consume sources, do not inherit synthesis
+
+Every search tool returns **candidate sources** (URLs, snippets, citations), not conclusions
+to trust verbatim.
+
+- `search` returns **candidate URLs with snippets**, aggregated from the search APIs (exa,
+  tavily) and the headless browser search engine. The snippets come from the source pages,
+  not an LLM, so they are usable as leads; still `fetch` and read the real page before you
+  rely on any detail, because a snippet is an excerpt, not the whole story.
+- `ask` (the web-enabled LLM) is **breadth only, low trust**. It is good for discovering what
+  sources exist on a fuzzy or wide topic. It is unreliable for any specific fact: it
+  hallucinates URLs, mangles details, and gets confused by context pollution. Never copy its
+  prose into your report. Use it to find source URLs, then `fetch` and read the real pages.
+- For any actual claim, fetch the cited page and **read it yourself**. Your conclusion is
+  what you read, not what a search snippet or an LLM said.
+- Never fabricate a source you did not fetch. If you cannot find a trustworthy source for a
+  claim, say so (see §3).
+
+## 2. Heuristic read strategy: pre-filter, then read fully, but never trust the filter blindly
+
+You will often face more sources than are worth reading cover-to-cover. Use a two-stage
+strategy:
+
+1. **Pre-filter to narrow the field.** Use the cheap, broad operations the skill provides:
+   `search` for candidate URLs and snippets (it aggregates the search APIs and the headless
+   browser engine; the browser source is always included, so it works with zero config and
+   reaches niche or anti-bot-protected sources the APIs miss), `ctx7 docs` for
+   library/framework questions, `locate` to pin relevant passages in a long fetched page, or
+   a small/fast model pass over titles and snippets to rank which URLs deserve a full fetch.
+2. **Then read the top candidates in full.** The pre-filter is a *hint*, not a verdict. Fetch
+   and read the most promising sources completely. `fetch` climbs automatically (API, then a
+   real browser with Cloudflare bypass and login cookies), so pages behind anti-bot or a
+   login still come back. The actual answer usually lives in the body, not the snippet.
+
+**Do not 100% trust the pre-filter.** This is the second most important rule. Small-model
+relevance scores and snippet matches are noisy: they can rank a crucial source low, or miss
+it entirely. When your confidence in the ranking is low (the topic is subtle, the snippets
+are ambiguous, the question has multiple valid framings), **widen the net**: fetch and read
+more sources fully rather than trusting a skim. It is better to read three extra pages than
+to miss the one that holds the answer. Cheap pre-filtering serves thorough reading; it must
+never *replace* it.
+
+## 3. Honesty over confidence
+
+- Distinguish what you **verified** (you fetched and read a trustworthy source) from what you
+  **inferred**. Never present an unverified inference as a sourced fact.
+- If no trustworthy source is found, or a claim could not be verified, say so explicitly. "I
+  could not verify X" is a correct and complete answer; a confident-sounding fabrication is
+  not.
+
+## 4. Output contract
+
+- Write the **full report** to `tmp-doc/research-<topic>-<timestamp>.md`. Frontmatter: `task`,
+  `created_at`, `sources`. Write it complete enough that the host, or any later reader, can
+  rely on this report alone without going back to the original sources.
+- **Return to the caller** (this is all the host sees): a concise summary (a few sentences),
+  the key conclusions with their supporting sources, and the source URL list. Do not dump raw
+  page bodies back. Keep the host's context clean; the bodies live in the on-disk report.
+
+## Summary of principles
+
+1. All gathering goes through the `research-assistant` skill; do not improvise sources.
+2. Read thoroughly; isolation makes reading cheap, and skimming is the failure mode.
+3. Consume sources, do not inherit synthesis (especially LLM web-search prose).
+4. Pre-filter to narrow, then read fully, but never blindly trust the pre-filter.
+5. Honesty over confidence: separate verified from inferred; say what you do not know.
+6. Write the full report to disk; return a tight, source-grounded summary.