research-assistant 0.1.0

package/src/research_assistant/loginstate/daemon.py

@@ -0,0 +1,145 @@
+"""cookie daemon（Python 移植自 cdt bridge/daemon.mjs，ADR-0006）。
+
+单 aiohttp 进程同时承载：
+    WS   ws://127.0.0.1:<port>/ws   扩展主动连，保持长连接，响应 getCookies
+    HTTP http://127.0.0.1:<port>/status|/cookies   fetch/doctor 按需调
+保活：每 25s 向扩展 ping（< service worker 30s 不活动阈值）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sys
+from typing import Any
+
+from aiohttp import web, WSMsgType
+
+log = logging.getLogger("research_assistant.loginstate.daemon")
+
+PING_INTERVAL = 25.0  # 秒
+
+
+class CookieDaemon:
+    def __init__(self, port: int) -> None:
+        self.port = port
+        self._ext_ws: web.WebSocketResponse | None = None
+        self._last_cookies: list[dict[str, Any]] | None = None
+        self._last_cookie_at: float = 0.0
+        self._pending: asyncio.Future | None = None
+        self._lock = asyncio.Lock()
+
+    # ---- WebSocket（扩展连这里）----
+    async def ws_handler(self, request: web.Request) -> web.WebSocketResponse:
+        ws = web.WebSocketResponse()
+        await ws.prepare(request)
+        self._ext_ws = ws
+        log.info("扩展已连接")
+        async for msg in ws:
+            if msg.type == WSMsgType.TEXT:
+                try:
+                    m = json.loads(msg.data)
+                except json.JSONDecodeError:
+                    continue
+                await self._on_ext_message(m)
+            elif msg.type == WSMsgType.ERROR:
+                log.warning("扩展 WS 错误: %s", ws.exception())
+        self._ext_ws = None
+        log.info("扩展断开，等待重连")
+        return ws
+
+    async def _on_ext_message(self, m: dict[str, Any]) -> None:
+        t = m.get("type")
+        if t == "cookies":
+            self._last_cookies = m.get("data") or []
+            self._last_cookie_at = asyncio.get_event_loop().time()
+            if self._pending and not self._pending.done():
+                self._pending.set_result(self._last_cookies)
+                self._pending = None
+        elif t == "hello":
+            log.info("收到扩展 hello")
+        elif t == "pong":
+            pass
+        elif t == "error":
+            log.warning("扩展报错: %s", m.get("message"))
+            if self._pending and not self._pending.done():
+                self._pending.set_exception(RuntimeError(m.get("message", "扩展错误")))
+                self._pending = None
+
+    async def _ping_loop(self) -> None:
+        while True:
+            await asyncio.sleep(PING_INTERVAL)
+            if self._ext_ws is not None and not self._ext_ws.closed:
+                try:
+                    await self._ext_ws.send_str(json.dumps({"type": "ping"}))
+                except Exception:
+                    pass
+
+    # ---- HTTP（fetch/doctor 调）----
+    async def status_handler(self, request: web.Request) -> web.Response:
+        return web.json_response(
+            {
+                "extConnected": self._ext_ws is not None and not self._ext_ws.closed,
+                "cachedCookieCount": len(self._last_cookies) if self._last_cookies else 0,
+                "lastCookieAt": self._last_cookie_at or None,
+            }
+        )
+
+    async def cookies_handler(self, request: web.Request) -> web.Response:
+        try:
+            cookies = await self._fetch_cookies(timeout=10.0)
+            return web.json_response({"count": len(cookies), "data": cookies})
+        except Exception as e:
+            return web.json_response({"error": str(e)}, status=503)
+
+    async def _fetch_cookies(self, timeout: float = 10.0) -> list[dict[str, Any]]:
+        if self._ext_ws is None or self._ext_ws.closed:
+            raise RuntimeError("扩展未连接（请确认日常浏览器已加载 research-assistant 扩展且 daemon 在线）")
+        async with self._lock:
+            if self._pending is not None:
+                raise RuntimeError("已有进行中的 cookie 请求")
+            loop = asyncio.get_event_loop()
+            self._pending = loop.create_future()
+            await self._ext_ws.send_str(json.dumps({"type": "getCookies"}))
+            try:
+                return await asyncio.wait_for(self._pending, timeout=timeout)
+            except asyncio.TimeoutError:
+                if not self._pending.done():
+                    self._pending.set_exception(RuntimeError("扩展响应超时"))
+                self._pending = None
+                raise
+
+    def build_app(self) -> web.Application:
+        app = web.Application()
+        app.router.add_get("/ws", self.ws_handler)
+        app.router.add_get("/status", self.status_handler)
+        app.router.add_get("/cookies", self.cookies_handler)
+        # ping 循环用 aiohttp 规范的 async startup/cleanup 生命周期管理
+        app.on_startup.append(self._start_ping)
+        app.on_cleanup.append(self._stop_ping)
+        return app
+
+    async def _start_ping(self, app: web.Application) -> None:
+        self._ping_task = asyncio.create_task(self._ping_loop())
+
+    async def _stop_ping(self, app: web.Application) -> None:
+        task = getattr(self, "_ping_task", None)
+        if task:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+
+def run(port: int) -> None:
+    """启动 daemon（前台运行；由 daemonctl.ensure_daemon 以子进程拉起）。"""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [daemon] %(message)s",
+        stream=sys.stderr,
+    )
+    daemon = CookieDaemon(port=port)
+    web.run_app(daemon.build_app(), host="127.0.0.1", port=port, print=lambda *a: None)

package/src/research_assistant/loginstate/daemon_cli.py

@@ -0,0 +1,21 @@
+"""cookie daemon 的模块入口：python -m research_assistant.loginstate.daemon_cli <port>"""
+
+from __future__ import annotations
+
+import sys
+
+from .daemon import run
+
+
+def main() -> None:
+    port = 17890
+    if len(sys.argv) > 1:
+        try:
+            port = int(sys.argv[1])
+        except ValueError:
+            pass
+    run(port)
+
+
+if __name__ == "__main__":
+    main()

package/src/research_assistant/loginstate/daemonctl.py

@@ -0,0 +1,116 @@
+"""登录态层：cookie daemon 控制 + cookie 获取（ADR-0006）。
+
+- ensure_daemon(config): 若 daemon 未运行则以子进程拉起（与 fetch 同生命周期足够；这里是按需拉起）。
+- daemon_status(config): GET /status。
+- get_cookies(config): GET /cookies（若 daemon 未运行会自动拉起；扩展未连则抛错）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from typing import Any
+
+import aiohttp
+
+from .. import config as config_mod
+from . import daemon as daemon_mod
+
+
+def _base_url(config: Any) -> str:
+    port = config.browser.daemon_port
+    return f"http://127.0.0.1:{port}"
+
+
+async def _http_get(config: Any, path: str, timeout: float = 3.0) -> dict[str, Any] | None:
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(f"{_base_url(config)}{path}", timeout=aiohttp.ClientTimeout(total=timeout)) as resp:
+                if resp.status == 200:
+                    return await resp.json()
+                return None
+    except Exception:
+        return None
+
+
+async def daemon_status(config: Any) -> dict[str, Any] | None:
+    return await _http_get(config, "/status")
+
+
+async def ensure_daemon(config: Any) -> bool:
+    """确保 daemon 在线；若离线则后台拉起子进程。返回最终是否在线。"""
+    status = await daemon_status(config)
+    if status is not None:
+        return True
+    _spawn_daemon(config)
+    # 等待启动
+    for _ in range(20):
+        await asyncio.sleep(0.3)
+        if await daemon_status(config) is not None:
+            return True
+    return False
+
+
+def _spawn_daemon(config: Any) -> None:
+    """以 detached 子进程启动 daemon（out/err 落 .logs/）。"""
+    logs_dir = config_mod.logs_dir()
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    log_file = logs_dir / "daemon.log"
+    port = str(config.browser.daemon_port)
+    # sys.executable + 模块入口
+    import subprocess
+
+    with log_file.open("a", encoding="utf-8") as f:
+        creationflags = 0
+        if sys.platform.startswith("win"):
+            creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) | getattr(subprocess, "DETACHED_PROCESS", 0)
+        subprocess.Popen(
+            [sys.executable, "-m", "research_assistant.loginstate.daemon_cli", port],
+            stdout=f,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+            close_fds=True,
+            creationflags=creationflags,
+        )
+
+
+async def get_cookies(config: Any, *, ensure: bool = True, timeout: float = 12.0) -> list[dict[str, Any]]:
+    """从 daemon 取明文 cookie 列表（扩展推送的）。"""
+    if ensure:
+        if not await ensure_daemon(config):
+            raise RuntimeError("cookie daemon 无法启动")
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                f"{_base_url(config)}/cookies", timeout=aiohttp.ClientTimeout(total=timeout)
+            ) as resp:
+                if resp.status != 200:
+                    body = await resp.text()
+                    raise RuntimeError(f"daemon /cookies 返回 {resp.status}: {body}")
+                data = await resp.json()
+                return data.get("data") or []
+    except aiohttp.ClientConnectorError as e:
+        raise RuntimeError(f"cookie daemon 不可达（{e}）") from e
+
+
+def to_playwright_cookies(cookies: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """把 chrome.cookies Cookie → Playwright add_cookies 格式。"""
+    same_map = {"strict": "Strict", "lax": "Lax", "no_restriction": "None", "none": "None", "unspecified": "Lax"}
+    out: list[dict[str, Any]] = []
+    for c in cookies:
+        item: dict[str, Any] = {
+            "name": c.get("name", ""),
+            "value": c.get("value", ""),
+            "domain": c.get("domain", ""),
+            "path": c.get("path") or "/",
+            "httpOnly": bool(c.get("httpOnly")),
+            "secure": bool(c.get("secure")),
+        }
+        if c.get("expirationDate"):
+            item["expires"] = float(c["expirationDate"])
+        ss = c.get("sameSite")
+        if ss and same_map.get(str(ss).lower()):
+            item["sameSite"] = same_map[str(ss).lower()]
+        out.append(item)
+    return out

package/src/research_assistant/loginstate/extension/background.js

@@ -0,0 +1,167 @@
+// Research Assistant Bridge — background service worker (MV3)
+// 架构(搬自 cdt)：扩展主动连本地 daemon 保持持久长连接，被动响应 daemon 的 getCookies/ping。
+// 保活：daemon 25s ping → onmessage 重置 30s 不活动计时器；chrome.alarms 30s 兜底重连。
+// 去噪：重连指数退避(1→60s 封顶)，只在状态变化时记日志。
+// 端口：从 chrome.storage.local 读 ra_port（默认 17890），可在 popup 改。
+
+const DEFAULT_PORT = 17890;
+const ALARM = "ra-keepalive";
+const MAX_LOGS = 30;
+
+const state = {
+  status: "disconnected", // disconnected|connecting|connected
+  port: DEFAULT_PORT,
+  cookieCount: 0,
+  served: 0,
+  lastEvent: null,
+  logs: [],
+};
+
+let wsRef = null;
+let backoff = 1000; // 重连退避 ms
+
+function wsUrl() {
+  return `ws://127.0.0.1:${state.port}/ws`;
+}
+
+function persist() {
+  try {
+    chrome.storage.session.set({ state }).catch(() => {});
+  } catch {}
+}
+
+function log(text) {
+  const time = new Date().toLocaleTimeString();
+  state.logs.push(`${time} ${text}`);
+  if (state.logs.length > MAX_LOGS) state.logs.shift();
+  state.lastEvent = { time, text };
+  console.log("[ra-bridge]", text);
+  persist();
+}
+
+function setStatus(s) {
+  if (state.status !== s) {
+    state.status = s;
+    log("状态 → " + s);
+  }
+  persist();
+}
+
+async function loadPort() {
+  try {
+    const v = await chrome.storage.local.get("ra_port");
+    state.port = Number(v.ra_port) || DEFAULT_PORT;
+  } catch {
+    state.port = DEFAULT_PORT;
+  }
+}
+
+chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+  if (msg?.type === "getStatus") {
+    sendResponse({ ...state });
+    return false;
+  }
+  if (msg?.type === "setPort") {
+    const p = Number(msg.port);
+    if (p > 0 && p < 65536) {
+      chrome.storage.local.set({ ra_port: p });
+      state.port = p;
+      log("端口改为 " + p);
+      backoff = 1000;
+      if (wsRef) {
+        try { wsRef.close(); } catch {}
+      } else {
+        connect();
+      }
+      sendResponse({ ok: true, port: p });
+    } else {
+      sendResponse({ ok: false });
+    }
+    return false;
+  }
+  if (msg?.type === "reset") {
+    backoff = 1000;
+    log("手动重连");
+    if (!wsRef) connect();
+    sendResponse({ ok: true });
+    return false;
+  }
+  return false;
+});
+
+function connect() {
+  if (wsRef) return;
+  setStatus("connecting");
+  let ws;
+  try {
+    ws = new WebSocket(wsUrl());
+    wsRef = ws;
+  } catch (e) {
+    log("WebSocket 构造失败: " + (e?.message || e));
+    scheduleReconnect();
+    return;
+  }
+
+  ws.onopen = () => {
+    backoff = 1000;
+    setStatus("connected");
+    ws.send(JSON.stringify({ type: "hello" }));
+  };
+
+  ws.onmessage = async (event) => {
+    let m;
+    try {
+      m = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (m.type === "ping") {
+      ws.send(JSON.stringify({ type: "pong" }));
+      return;
+    }
+    if (m.type === "getCookies") {
+      try {
+        const cookies = await chrome.cookies.getAll({});
+        state.cookieCount = cookies.length;
+        state.served += 1;
+        persist();
+        ws.send(JSON.stringify({ type: "cookies", count: cookies.length, data: cookies }));
+        log(`响应 getCookies #${state.served}: ${cookies.length} cookie`);
+      } catch (e) {
+        ws.send(JSON.stringify({ type: "error", message: String(e) }));
+        log("读 cookie 报错: " + (e?.message || e));
+      }
+    }
+  };
+
+  ws.onerror = () => {};
+
+  ws.onclose = () => {
+    if (wsRef === ws) wsRef = null;
+    setStatus("disconnected");
+    scheduleReconnect();
+  };
+}
+
+function scheduleReconnect() {
+  if (wsRef) return;
+  const wait = backoff;
+  backoff = Math.min(backoff * 2, 60000);
+  if (wait <= 2000) log(`${wait}ms 后重连…`);
+  setTimeout(connect, wait);
+}
+
+chrome.alarms.onAlarm.addListener((a) => {
+  if (a.name !== ALARM) return;
+  if (!wsRef || wsRef.readyState !== WebSocket.OPEN) {
+    if (!wsRef) connect();
+  }
+});
+
+chrome.alarms.create(ALARM, { periodInMinutes: 0.5 });
+
+(async () => {
+  await loadPort();
+  log("Research Assistant Bridge 启动 (端口 " + state.port + ")");
+  connect();
+})();

package/src/research_assistant/loginstate/extension/manifest.json

@@ -0,0 +1,15 @@
+{
+  "manifest_version": 3,
+  "name": "Research Assistant Bridge",
+  "version": "0.1.0",
+  "description": "Expose this browser's cookies to the local research-assistant fetch tool (reads via chrome.cookies, sends over a local WebSocket).",
+  "permissions": ["cookies", "storage", "alarms"],
+  "host_permissions": ["<all_urls>"],
+  "background": {
+    "service_worker": "background.js"
+  },
+  "action": {
+    "default_popup": "popup.html",
+    "default_title": "Research Assistant Bridge"
+  }
+}

package/src/research_assistant/loginstate/extension/popup.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <style>
+    body { font-family: system-ui, sans-serif; width: 320px; margin: 0; padding: 12px; font-size: 13px; }
+    h3 { margin: 0 0 8px; font-size: 14px; }
+    .row { margin: 6px 0; display: flex; gap: 6px; align-items: center; }
+    input[type=number] { width: 90px; }
+    button { cursor: pointer; padding: 4px 10px; }
+    pre { white-space: pre-wrap; max-height: 160px; overflow: auto; background: #f4f4f4; padding: 6px; border-radius: 4px; }
+    .status { font-weight: 600; }
+    .ok { color: #080; } .bad { color: #c00; } .warn { color: #c80; }
+  </style>
+</head>
+<body>
+  <h3>Research Assistant Bridge</h3>
+  <div class="row">
+    <span>状态：</span><span id="status" class="status">—</span>
+    <span>cookie 数：</span><span id="count">—</span>
+  </div>
+  <div class="row">
+    <label>daemon 端口：</label>
+    <input id="port" type="number" min="1" max="65535" />
+    <button id="save">保存</button>
+    <button id="reset" title="强制重连">重连</button>
+  </div>
+  <pre id="logs"></pre>
+  <script src="popup.js"></script>
+</body>
+</html>

package/src/research_assistant/loginstate/extension/popup.js

@@ -0,0 +1,33 @@
+// popup：展示状态 + 改端口 + 强制重连
+const $ = (id) => document.getElementById(id);
+
+function clsFor(status) {
+  if (status === "connected") return "ok";
+  if (status === "connecting") return "warn";
+  return "bad";
+}
+
+async function refresh() {
+  const bg = chrome.runtime.getBackgroundPage
+    ? null
+    : await chrome.runtime.sendMessage({ type: "getStatus" });
+  const s = bg || { status: "unknown", cookieCount: 0, port: 17890, logs: [] };
+  $("status").textContent = s.status || "unknown";
+  $("status").className = "status " + clsFor(s.status);
+  $("count").textContent = s.cookieCount ?? 0;
+  $("port").value = s.port || 17890;
+  $("logs").textContent = (s.logs || []).join("\n");
+}
+
+$("save").addEventListener("click", async () => {
+  const port = Number($("port").value);
+  await chrome.runtime.sendMessage({ type: "setPort", port });
+  setTimeout(refresh, 300);
+});
+
+$("reset").addEventListener("click", async () => {
+  await chrome.runtime.sendMessage({ type: "reset" });
+  setTimeout(refresh, 300);
+});
+
+refresh();

package/src/research_assistant/output.py

@@ -0,0 +1,140 @@
+"""输出渲染（横切约定 #5，api-contract.md §3/§4）。
+
+stdout 默认 JSON（供脚本解析）；--output markdown 给人/AI 可读的 markdown。
+错误：stdout 仍出 JSON `{error:{...}}`（供脚本解析），stderr 同时出一行人类可读提示。
+
+格式而非受众：json 是结构化格式、markdown 是可读格式，二者对举；
+不再用 "human" 这种指代受众的词（它其实就是 markdown）。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, IO
+
+
+def _safe_write(stream: IO[str], text: str) -> None:
+    """按流编码安全写出（Windows 控制台编码兜底）。"""
+    encoding = getattr(stream, "encoding", None) or "utf-8"
+    try:
+        text.encode(encoding)
+    except UnicodeEncodeError:
+        text = text.encode(encoding, errors="backslashreplace").decode(encoding)
+    stream.write(text)
+
+
+def emit_json(data: Any) -> None:
+    payload = json.dumps(data, ensure_ascii=False, indent=2)
+    _safe_write(sys.stdout, payload)
+    if not payload.endswith("\n"):
+        _safe_write(sys.stdout, "\n")
+
+
+def emit_markdown(data: Any) -> None:
+    _safe_write(sys.stdout, _markdown_render(data))
+    _safe_write(sys.stdout, "\n")
+
+
+def emit(data: Any, fmt: str) -> None:
+    if fmt == "json":
+        emit_json(data)
+    else:
+        emit_markdown(data)
+
+
+def emit_error(message: str) -> None:
+    """stderr 单行错误提示（plain text，不参与 --output 格式选择）。"""
+    _safe_write(sys.stderr, f"error: {message}\n")
+
+
+# ---------------------------------------------------------------------------
+# markdown 渲染（标准 markdown：列表用 -、加粗 **、引用 >、斜体 _）
+# ---------------------------------------------------------------------------
+
+
+def _truncate(text: Any, limit: int = 120) -> str:
+    s = "" if text is None else str(text)
+    s = " ".join(s.replace("\r", " ").replace("\n", " ").split())
+    if limit > 0 and len(s) > limit:
+        return s[: max(0, limit - 3)] + "..."
+    return s
+
+
+def _markdown_render(data: Any, indent: int = 0) -> str:
+    pad = "  " * indent
+    if isinstance(data, dict):
+        # 错误体：引用块形式
+        if "error" in data and isinstance(data["error"], dict):
+            err = data["error"]
+            line = f"{pad}> **[ERROR] {err.get('code', 'INTERNAL')}**: {err.get('message', '')}"
+            if err.get("provider"):
+                line += f" _(provider: {err['provider']})_"
+            return line
+        # 结果列表（results / data / anchors 等）：先出元数据，再以列表渲染主体
+        for list_key in ("results", "data", "anchors", "contents", "checks", "targets"):
+            if list_key in data and isinstance(data[list_key], list):
+                return _render_list_markdown(data, list_key, indent)
+        # 普通 dict：每项一行 `- **key**: value`
+        lines: list[str] = []
+        for k, v in data.items():
+            if isinstance(v, (dict, list)) and v:
+                lines.append(f"{pad}- **{k}**:")
+                lines.append(_markdown_render(v, indent + 1))
+            else:
+                lines.append(f"{pad}- **{k}**: {_truncate(v, 200)}")
+        return "\n".join(lines)
+    if isinstance(data, list):
+        if not data:
+            return f"{pad}_(空)_"
+        lines: list[str] = []
+        for i, item in enumerate(data, 1):
+            if isinstance(item, dict):
+                title = item.get("title") or item.get("url") or item.get("id") or item.get("name") or ""
+                extra = item.get("url") if item.get("url") != title else ""
+                summary_keys = ("content", "text", "snippet", "description", "markdown")
+                summary = ""
+                for sk in summary_keys:
+                    val = item.get(sk)
+                    if val:
+                        # 摘要/正文不截断：长度由源决定（搜索引擎/浏览器给多长就多长），
+                        # 只合并空白（含换行）避免破坏 markdown，不丢内容
+                        summary = " ".join(str(val).split())
+                        break
+                head = f"{pad}{i}. **{title}**" if title else f"{pad}{i}."
+                if extra and extra != title:
+                    head += f" — `{extra}`"
+                lines.append(head)
+                if summary:
+                    lines.append(f"{pad}   {summary}")
+                # 次要字段（子列表项）
+                for k, v in item.items():
+                    if k in ("title", "url", "id", "name", "content", "text", "snippet", "description", "markdown"):
+                        continue
+                    if isinstance(v, (dict, list)):
+                        continue
+                    if v in (None, "", 0, 0.0):
+                        continue
+                    lines.append(f"{pad}   - {k}: {_truncate(v, 80)}")
+            else:
+                lines.append(f"{pad}{i}. {item}")
+        return "\n".join(lines)
+    return f"{pad}{_truncate(data, 400)}"
+
+
+def _render_list_markdown(data: dict[str, Any], list_key: str, indent: int) -> str:
+    pad = "  " * indent
+    lines: list[str] = []
+    # 先渲染标量元数据字段
+    for k, v in data.items():
+        if k == list_key:
+            continue
+        if isinstance(v, (dict, list)):
+            continue
+        lines.append(f"{pad}- **{k}**: {_truncate(v, 160)}")
+    items = data[list_key]
+    if lines:
+        lines.append("")
+    lines.append(f"{pad}**{list_key}** ({len(items)}):")
+    lines.append(_markdown_render(items, indent + 1))
+    return "\n".join(lines)

package/src/research_assistant/providers/__init__.py

@@ -0,0 +1,10 @@
+"""providers 包：各搜索/文档 provider 的自写 HTTP 客户端（ADR-0010）。
+
+加 provider = 在本包新增一个 .py 文件（类用 @register 装饰）+ 1 条 config。
+registry.discover() 会自动发现，CLI 据此动态生成命令——无需改本文件之外的东西。
+"""
+
+from .base import ArgSpec, Capability, Provider
+from .registry import all_provider_classes, register, resolve_type
+
+__all__ = ["ArgSpec", "Capability", "Provider", "all_provider_classes", "register", "resolve_type"]