research-assistant 0.1.0

package/src/research_assistant/commands/fetch.py

@@ -0,0 +1,99 @@
+"""fetch 命令：跨工具爬取增强（PM §4.2 / api-contract §2.2）。
+
+    research-assistant fetch <url> [<url>...] [--output <path>] [--no-browser]
+                              [--login|--no-login] [--concurrency N]
+
+普通接口（tavily extract / firecrawl scrape，直接出 md）→ 失败回退 headed 浏览器 + CF auto-detect。
+批量 = 单浏览器多页并发（ADR-0004）。落盘只写快照（D8）。
+响应：FetchResult[]{url, method, status, md_path, error?}
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from .. import config as config_mod
+from ..config import Config
+from ..errors import ArgsError, ResearchAssistantError
+from ..fetch import fetch_normal, fetch_with_browser, write_snapshot
+
+NAME = "fetch"
+ALIASES: list[str] = ["f"]
+HELP = "Cross-tool page fetch with browser fallback."
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    p.add_argument("urls", nargs="+", metavar="URL", help="URL(s) to fetch.")
+    p.add_argument("--output", help="Write markdown to this path (single URL only).")
+    p.add_argument("--no-browser", action="store_true", help="Disable browser fallback.")
+    login = p.add_mutually_exclusive_group()
+    login.add_argument("--login", action="store_true", default=True, help="Inject login cookies (default).")
+    login.add_argument("--no-login", action="store_true", help="Do not inject login cookies.")
+    p.add_argument("--concurrency", type=int, default=4, help="Browser page concurrency (default 4).")
+    p.set_defaults(_handler=run)
+
+
+async def run(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    urls = list(args.urls)
+    if args.output and len(urls) > 1:
+        raise ArgsError("fetch: --output 仅支持单个 URL")
+
+    use_login = not getattr(args, "no_login", False)
+
+    # 1) 普通抓取（并发）
+    import asyncio
+
+    normal_results: dict[str, str | None] = {}
+    normal_results_list = await asyncio.gather(
+        *[fetch_normal(config, u) for u in urls], return_exceptions=True
+    )
+    for url, res in zip(urls, normal_results_list):
+        if isinstance(res, Exception) or res is None:
+            normal_results[url] = None
+        else:
+            normal_results[url] = res
+
+    # 2) 失败的回退浏览器
+    failed = [u for u in urls if normal_results.get(u) is None]
+    browser_results: dict[str, str | None] = {}
+    if failed and not args.no_browser:
+        try:
+            browser_results = await fetch_with_browser(
+                config, failed, login=use_login, concurrency=args.concurrency
+            )
+        except ResearchAssistantError:
+            browser_results = {u: None for u in failed}
+
+    # 3) 组装 FetchResult + 落盘
+    results: list[dict[str, Any]] = []
+    for url in urls:
+        md = normal_results.get(url)
+        if md is not None:
+            method = "normal"
+            status = "success"
+            error = None
+        else:
+            md = browser_results.get(url)
+            method = "browser"
+            if md:
+                status = "success"
+                error = None
+            else:
+                status = "failed"
+                error = "普通接口与浏览器回退均失败" if not args.no_browser else "普通接口失败且已禁用浏览器回退"
+        md_path = None
+        if md and status == "success":
+            md_path = write_snapshot(url, method, md, args.output)
+        results.append(
+            {
+                "url": url,
+                "method": method,
+                "status": status,
+                "md_path": md_path,
+                **({"error": error} if error else {}),
+            }
+        )
+    return {"results": results}
+

package/src/research_assistant/commands/locate.py

@@ -0,0 +1,71 @@
+"""locate 命令：锚点法速览预筛（PM §4.3）。
+
+    research-assistant locate <md_path> <query> [--concurrency N] [--top N=5]
+                              [--scope lines|paragraph] [--context K=3]
+
+行号基于已落盘 md 副本（基线 §7.4 稳定性）。
+响应：{md_path, query, anchors[]{quote, line_start, line_end, scope, context, relevance}}
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from ..config import Config
+from ..errors import ArgsError
+from ..locate import locate as locate_engine
+
+NAME = "locate"
+ALIASES: list[str] = []
+HELP = "Anchor-based relevance scan of a local markdown file."
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    p.add_argument("md_path", help="Path to the local markdown file.")
+    p.add_argument("query", help="Question / topic to locate.")
+    p.add_argument("--concurrency", type=int, default=None, help="Override locate model concurrency.")
+    p.add_argument("--top", type=int, default=5, help="Max anchors to return (default 5).")
+    p.add_argument("--scope", choices=["lines", "paragraph"], default="paragraph", help="Chunking scope.")
+    p.add_argument("--context", type=int, default=3, help="Context lines each side (default 3).")
+    p.set_defaults(_handler=run)
+
+
+async def run(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    path = Path(args.md_path).expanduser()
+    if not path.is_file():
+        raise ArgsError(f"locate: 文件不存在: {path}")
+    try:
+        md_text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as e:
+        raise ArgsError(f"locate: 读取失败: {e}") from e
+
+    if not md_text.strip():
+        return {"md_path": str(path), "query": args.query, "anchors": []}
+
+    anchors = await locate_engine(
+        config,
+        md_text,
+        args.query,
+        scope=args.scope,
+        top=args.top,
+        context_k=args.context,
+        concurrency=args.concurrency,
+    )
+    return {
+        "md_path": str(path),
+        "query": args.query,
+        "anchors": [
+            {
+                "quote": a.quote,
+                "line_start": a.line_start,
+                "line_end": a.line_end,
+                "scope": a.scope,
+                "context": a.context,
+                "relevance": a.relevance,
+            }
+            for a in anchors
+        ],
+    }

package/src/research_assistant/commands/search.py

@@ -0,0 +1,161 @@
+"""search 命令：聚合搜索源 API（exa/tavily 等）的统一搜索入口（原义）。
+
+    research-assistant search "<query>" [--providers exa,tavily] [--limit N]
+
+search 是「调搜索 API」的纯粹语义：把 query 发给 exa/tavily（等 web 搜索源 provider）
+各自的 search 能力，聚合去重，返回候选源。它不是 LLM 问答（自然语言意图问答见 ask）。
+
+默认查已配置的 exa、tavily；--providers CSV 指定子集或加入 firecrawl（如 exa,firecrawl）。
+
+响应：{query, candidates[]{url, title?, snippet?}, sources[]}
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from .. import providers as providers_pkg
+from ..config import Config
+from ..errors import ArgsError
+
+NAME = "search"
+ALIASES: list[str] = []
+HELP = "Aggregate web search across search-source APIs (exa/tavily); not an LLM."
+
+# 默认搜索源（顺序即优先级）：exa/tavily 需已配置；browser 永远可用（本地浏览器，免配置兜底）。
+# firecrawl 需显式 --providers 加入（有 key 才有意义）。
+_DEFAULT_SOURCES = ("exa", "tavily", "browser")
+
+
+def _resolve_wanted(spec: str, configured: set[str]) -> list[str]:
+    """解析要聚合的搜索源：--providers 显式指定；否则已配置的 exa/tavily + browser（免配置兜底）。"""
+    spec = (spec or "").strip()
+    if spec:
+        return [s.strip() for s in spec.split(",") if s.strip()]
+    # browser 永远可用（本地浏览器），exa/tavily 需已配置 → 默认永远至少有 browser（开箱即用）
+    return [p for p in _DEFAULT_SOURCES if p == "browser" or p in configured]
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    p.add_argument("query", help="Search query (keywords for the search APIs).")
+    p.add_argument(
+        "--providers",
+        help="Comma list of search-source providers (default: configured exa,tavily + browser). "
+        "e.g. exa,tavily,firecrawl,browser.",
+    )
+    p.add_argument("--limit", type=int, default=5, help="Max results to take per provider (default 5).")
+    p.set_defaults(_handler=run)
+
+
+async def run(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    wanted = _resolve_wanted(args.providers or "", {p.type for p in config.providers})
+    if not wanted:
+        raise ArgsError(
+            "search: 没有可用的搜索源 provider；请用 --providers 指定",
+            provider="search",
+        )
+
+    candidates: list[dict[str, Any]] = []
+    used: list[str] = []
+    for ptype in wanted:
+        try:
+            extra = await _from_provider(config, ptype, args.query, args.limit)
+        except Exception:
+            # 单家失败不阻断其余源（如某家未配置/限流）；跳过该家继续聚合
+            continue
+        _merge_unique(candidates, extra)
+        used.append(ptype)
+
+    return {"query": args.query, "candidates": candidates, "sources": used}
+
+
+async def _from_provider(
+    config: Config, ptype: str, query: str, limit: int
+) -> list[dict[str, Any]]:
+    """调用指定 provider 的 search 能力（复用插件实例），返回候选源列表。"""
+    classes = providers_pkg.all_provider_classes()
+    pclass = classes.get(ptype)
+    if pclass is None:
+        raise ArgsError(f"search: 未知 provider '{ptype}'", provider=ptype)
+    provider = pclass(config)
+    cap = next((c for c in provider.capabilities() if c.name == "search"), None)
+    if cap is None:
+        raise ArgsError(f"search: provider '{ptype}' 无 search 能力", provider=ptype)
+    ns = argparse.Namespace(query=query)
+    # 给各 provider search 通用 flag 默认值，避免 AttributeError
+    for attr, default in (
+        ("num_results", limit),
+        ("max_results", limit),
+        ("limit", limit),
+        ("type", "auto"),
+        ("depth", "basic"),
+        ("topic", "general"),
+        ("text", False),
+        ("highlights", False),
+        ("include_domains", None),
+        ("exclude_domains", None),
+        ("category", None),
+        ("start_date", None),
+        ("end_date", None),
+        ("scrape", False),
+        ("sources", None),
+        ("include_subdomains", False),
+        ("only_main_content", False),
+        ("wait_for", None),
+        ("extract_depth", "basic"),
+        ("format", "markdown"),
+        ("include_answer", None),
+        ("time_range", None),
+        ("include_text", None),
+        ("exclude_text", None),
+        ("include_raw_content", None),
+        ("chunks_per_source", None),
+        ("country", None),
+        ("days", None),
+        ("include_images", False),
+        ("include_image_descriptions", False),
+        ("include_favicon", False),
+        ("auto_parameters", False),
+        ("engine", "bing-intl"),  # browser search 用
+        ("max_pages", 10),        # browser search 用
+    ):
+        if not hasattr(ns, attr):
+            setattr(ns, attr, default)
+    result = await cap.handler(ns)
+    return _normalize_provider_results(result, limit)
+
+
+def _normalize_provider_results(result: dict[str, Any], limit: int) -> list[dict[str, Any]]:
+    """把各 provider 的 search 响应归一为候选源列表。"""
+    items: list[Any] = []
+    for key in ("results", "data", "contents"):
+        raw = result.get(key)
+        if isinstance(raw, list):
+            items = raw
+            break
+    out: list[dict[str, Any]] = []
+    for it in items[:limit]:
+        if not isinstance(it, dict):
+            continue
+        url = it.get("url") or it.get("id")
+        if not url:
+            continue
+        item: dict[str, Any] = {"url": url}
+        title = it.get("title") or it.get("name")
+        if title:
+            item["title"] = title
+        snippet = it.get("content") or it.get("text") or it.get("snippet") or it.get("description")
+        if snippet:
+            item["snippet"] = snippet
+        out.append(item)
+    return out
+
+
+def _merge_unique(target: list[dict[str, Any]], extras: list[dict[str, Any]]) -> None:
+    seen = {c["url"] for c in target}
+    for e in extras:
+        if e["url"] not in seen:
+            target.append(e)
+            seen.add(e["url"])

package/src/research_assistant/commands/setup.py

@@ -0,0 +1,249 @@
+"""setup 命令：配置 provider/代理/浏览器 + 可选安装 managed skill/agent（api-contract §2.3）。
+
+交互式：逐项问答（key 用 getpass 遮蔽输入）。
+非交互式：
+    --config-inline "<toml>"              直接写整份 TOML
+    --provider type[,k=v,k=v]...          重复添加/更新 provider
+    --proxy <url> --browser-channel <c> --daemon-port <n>
+幂等：重复 setup 合并更新配置；重复 install 覆盖 managed 文件。
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+from typing import Any
+
+from ..config import Config, ProviderConfig, load, save
+from ..errors import ArgsError, ResearchAssistantError
+from .. import targets as targets_mod
+from .. import installer
+
+NAME = "setup"
+ALIASES: list[str] = ["init"]
+HELP = "Configure providers/proxy/browser and optionally install managed skill/agent."
+
+# 已知 provider 类型 + 是否需要 model
+_PROVIDER_TYPES: dict[str, dict[str, Any]] = {
+    "openai_compat": {"needs_model": True, "label": "OpenAI-compatible (search/LLM)", "default_base": ""},
+    "locate": {"needs_model": True, "label": "locate 模型 (openai 兼容小模型)", "default_base": ""},
+    "exa": {"needs_model": False, "label": "Exa", "default_base": "https://api.exa.ai"},
+    "tavily": {"needs_model": False, "label": "Tavily", "default_base": "https://api.tavily.com"},
+    "firecrawl": {"needs_model": False, "label": "Firecrawl", "default_base": "https://api.firecrawl.dev/v2"},
+    "context7": {"needs_model": False, "label": "Context7", "default_base": "https://context7.com"},
+}
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    mode = p.add_mutually_exclusive_group()
+    mode.add_argument("--non-interactive", action="store_true", help="Non-interactive (use flags/inline).")
+    mode.add_argument("--config-inline", help="Write a full TOML config string (non-interactive).")
+    p.add_argument(
+        "--provider",
+        action="append",
+        metavar="TYPE[,k=v,...]",
+        help="Add/update a provider, e.g. exa,api_key=... or openai_compat,base_url=...,api_key=...,model=...",
+    )
+    p.add_argument("--proxy", help="Proxy URL (empty=auto-detect; 'none' to clear).")
+    p.add_argument("--browser-channel", choices=["msedge", "chrome"], help="Browser channel for fetch fallback.")
+    p.add_argument("--daemon-port", type=int, help="Cookie daemon port.")
+    p.add_argument("--install-skills", help="Comma list of families to install (claude,codex,cursor,hermes,all).")
+    p.add_argument("--skills-root", help="Override install root (default $HOME).")
+    p.set_defaults(_handler=run)
+
+
+async def run(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    inline = getattr(args, "config_inline", None)
+    if inline:
+        cfg = _config_from_inline(inline, config.path)
+    elif getattr(args, "non_interactive", False):
+        cfg = _config_from_flags(args, config)
+    else:
+        cfg = _interactive(config)
+
+    saved_path = save(cfg, config.path)
+
+    result: dict[str, Any] = {"config_path": str(saved_path), "providers": [p.type for p in cfg.providers]}
+
+    # 可选：安装 managed skill/agent
+    if args.install_skills:
+        families = _parse_families(args.install_skills)
+        root = args.skills_root
+        install_result = installer.install(families, root=root)
+        result["install"] = install_result
+        # 装了扩展桥时标记 browser.extension_status
+        if install_result.get("extension_copied"):
+            cfg.browser.extension_status = "installed"
+            save(cfg, config.path)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 非交互式
+# ---------------------------------------------------------------------------
+
+
+def _config_from_inline(toml_str: str, current_path: str) -> Config:
+    import sys
+
+    if sys.version_info >= (3, 11):
+        import tomllib
+    else:  # pragma: no cover
+        import tomli as tomllib
+    try:
+        raw = tomllib.loads(toml_str)
+    except Exception as e:
+        raise ArgsError(f"setup: --config-inline TOML 解析失败: {e}") from e
+    # 复用 config.load 的解析逻辑：写临时再加载
+    import tempfile
+
+    with tempfile.NamedTemporaryFile("w", suffix=".toml", delete=False) as f:
+        f.write(toml_str)
+        tmp = f.name
+    try:
+        return load(tmp)
+    finally:
+        try:
+            import os
+
+            os.unlink(tmp)
+        except OSError:
+            pass
+
+
+def _config_from_flags(args: argparse.Namespace, current: Config) -> Config:
+    cfg = current  # 在现有基础上合并（幂等）
+    if args.provider:
+        for spec in args.provider:
+            pc = _parse_provider_spec(spec)
+            _upsert_provider(cfg, pc)
+    if args.proxy is not None:
+        cfg.proxy.url = "" if args.proxy.lower() in ("none", "") else args.proxy
+    if args.browser_channel:
+        cfg.browser.channel = args.browser_channel
+    if args.daemon_port:
+        cfg.browser.daemon_port = args.daemon_port
+    return cfg
+
+
+def _parse_provider_spec(spec: str) -> ProviderConfig:
+    parts = [p.strip() for p in spec.split(",") if p.strip()]
+    if not parts:
+        raise ArgsError("setup: --provider 缺少 type")
+    ptype = parts[0]
+    if ptype not in _PROVIDER_TYPES:
+        raise ArgsError(f"setup: 未知 provider type '{ptype}'")
+    kv: dict[str, str] = {}
+    for token in parts[1:]:
+        if "=" not in token:
+            raise ArgsError(f"setup: --provider 错误的 k=v 片段 '{token}'")
+        k, v = token.split("=", 1)
+        kv[k.strip()] = v.strip()
+    return ProviderConfig(
+        type=ptype,
+        base_url=kv.get("base_url", _PROVIDER_TYPES[ptype]["default_base"] or ""),
+        api_key=kv.get("api_key", ""),
+        model=kv.get("model", ""),
+        timeout=int(kv.get("timeout", "30")),
+        concurrency=int(kv.get("concurrency", "8")),
+    )
+
+
+def _upsert_provider(cfg: Config, pc: ProviderConfig) -> None:
+    for i, existing in enumerate(cfg.providers):
+        if existing.type == pc.type:
+            cfg.providers[i] = pc
+            return
+    cfg.providers.append(pc)
+
+
+def _parse_families(raw: str) -> list[str]:
+    tokens = [t.strip().lower() for t in raw.replace(";", ",").split(",") if t.strip()]
+    if not tokens:
+        return []
+    out: list[str] = []
+    for t in tokens:
+        if t in ("all", "全部"):
+            return list(targets_mod.ALL_FAMILIES.keys())
+        if t in targets_mod.ALL_FAMILIES:
+            out.append(t)
+        else:
+            raise ArgsError(f"setup: 未知 install 目标 '{t}'（可选: {','.join(targets_mod.ALL_FAMILIES)}）")
+    # 去重保序
+    seen, dedup = set(), []
+    for t in out:
+        if t not in seen:
+            seen.add(t)
+            dedup.append(t)
+    return dedup
+
+
+# ---------------------------------------------------------------------------
+# 交互式
+# ---------------------------------------------------------------------------
+
+
+def _interactive(current: Config) -> Config:
+    cfg = current
+    print("\nresearch-assistant setup（交互式，回车保留当前值）\n")
+    for ptype, meta in _PROVIDER_TYPES.items():
+        existing = next((p for p in cfg.providers if p.type == ptype), None)
+        if _ask_enable(meta["label"], existing is not None):
+            pc = _prompt_provider(ptype, meta, existing)
+            _upsert_provider(cfg, pc)
+    # 代理
+    cur = cfg.proxy.url or "(空=自动检测)"
+    val = input(f"\n代理 URL [{cur}]: ").strip()
+    if val:
+        cfg.proxy.url = "" if val.lower() in ("none", "无") else val
+    # 浏览器
+    cur_ch = cfg.browser.channel
+    ch = input(f"浏览器 channel (msedge|chrome) [{cur_ch}]: ").strip().lower()
+    if ch in ("msedge", "chrome"):
+        cfg.browser.channel = ch
+    cur_port = cfg.browser.daemon_port
+    port = input(f"cookie daemon 端口 [{cur_port}]: ").strip()
+    if port.isdigit():
+        cfg.browser.daemon_port = int(port)
+    return cfg
+
+
+def _ask_enable(label: str, currently_enabled: bool) -> bool:
+    default = "y" if currently_enabled else "n"
+    ans = input(f"\n配置 {label}? [y/N] ({default}): ").strip().lower()
+    if not ans:
+        return currently_enabled
+    return ans in ("y", "yes", "是")
+
+
+def _prompt_provider(ptype: str, meta: dict[str, Any], existing: ProviderConfig | None) -> ProviderConfig:
+    cur_base = existing.base_url if existing else meta["default_base"]
+    cur_key = existing.api_key if existing else ""
+    cur_model = existing.model if existing else ""
+    cur_timeout = existing.timeout if existing else 30
+
+    base = input(f"  base_url [{cur_base or '必填'}]: ").strip() or cur_base
+    key = getpass.getpass(f"  api_key [{'已配置' if cur_key else '必填'}]: ").strip() or cur_key
+    model = ""
+    if meta["needs_model"]:
+        model = input(f"  model [{cur_model or '必填'}]: ").strip() or cur_model
+    timeout_s = input(f"  timeout 秒 [{cur_timeout}]: ").strip()
+    timeout = int(timeout_s) if timeout_s.isdigit() else cur_timeout
+    concurrency = 8
+    if ptype == "locate":
+        cc = input(f"  concurrency [{existing.concurrency if existing else 8}]: ").strip()
+        if cc.isdigit():
+            concurrency = int(cc)
+        elif existing:
+            concurrency = existing.concurrency
+
+    return ProviderConfig(
+        type=ptype,
+        base_url=base,
+        api_key=key,
+        model=model,
+        timeout=timeout,
+        concurrency=concurrency,
+    )

package/src/research_assistant/commands/skills.py

@@ -0,0 +1,60 @@
+"""skills 命令：managed skill/agent 的同步（api-contract §2.3）。
+
+    research-assistant skills status [--targets list]
+    research-assistant skills update  [--targets list] [--skills-root path]
+
+status 判定 missing/stale/up-to-date/extra；update 刷新 managed 文件。
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from .. import installer
+from ..config import Config
+from ..errors import ArgsError
+from ..targets import ALL_FAMILIES
+
+NAME = "skills"
+ALIASES: list[str] = ["skill"]
+HELP = "Manage managed skill/agent files across AI agent families."
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, aliases=ALIASES, help=HELP, description=HELP)
+    sub = p.add_subparsers(dest="subcommand", required=True, metavar="<status|update>")
+    st = sub.add_parser("status", help="Check managed file freshness.")
+    st.add_argument("--targets", help=f"Comma list (default all: {','.join(ALL_FAMILIES)}).")
+    st.add_argument("--skills-root", help="Override install root (default $HOME).")
+    st.set_defaults(_handler=run_status)
+    up = sub.add_parser("update", help="Refresh managed files.")
+    up.add_argument("--targets", help=f"Comma list (default all: {','.join(ALL_FAMILIES)}).")
+    up.add_argument("--skills-root", help="Override install root (default $HOME).")
+    up.set_defaults(_handler=run_update)
+
+
+def _resolve_targets(raw: str | None) -> list[str]:
+    if not raw:
+        return list(ALL_FAMILIES.keys())
+    tokens = [t.strip().lower() for t in raw.replace(";", ",").split(",") if t.strip()]
+    if not tokens:
+        return list(ALL_FAMILIES.keys())
+    if "all" in tokens:
+        return list(ALL_FAMILIES.keys())
+    out: list[str] = []
+    for t in tokens:
+        if t not in ALL_FAMILIES:
+            raise ArgsError(f"skills: 未知目标 '{t}'（可选: {','.join(ALL_FAMILIES)}）")
+        out.append(t)
+    return out
+
+
+async def run_status(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    families = _resolve_targets(args.targets)
+    return installer.status(families, root=args.skills_root)
+
+
+async def run_update(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    families = _resolve_targets(args.targets)
+    return installer.update(families, root=args.skills_root)