clawshire-cli 0.1.0__py3-none-any.whl

clawshire_cli/__init__.py

@@ -0,0 +1 @@
+__all__ = []

clawshire_cli/commands/__init__.py

@@ -0,0 +1 @@
+__all__ = []

clawshire_cli/commands/annual_analysis.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from clawshire_cli.context import build_client, resolve_output
+from clawshire_cli.output import render
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("annual-analysis", help="年报分析")
+    annual_analysis_subparsers = parser.add_subparsers(dest="annual_analysis_command", required=True)
+
+    pdf_file = annual_analysis_subparsers.add_parser("pdf-file", help="通过本地 PDF 文件提交分析")
+    pdf_file.add_argument("pdf_path", help="本地 PDF 路径")
+    _add_job_submit_args(pdf_file)
+    pdf_file.set_defaults(handler=_handle_pdf_file)
+
+    pdf_url = annual_analysis_subparsers.add_parser("pdf-url", help="通过 PDF 链接提交分析")
+    pdf_url.add_argument("pdf_url", help="PDF 直链")
+    _add_job_submit_args(pdf_url)
+    pdf_url.set_defaults(handler=_handle_pdf_url)
+
+    company = annual_analysis_subparsers.add_parser("company", help="通过公司代码或简称分析最新年报")
+    company.add_argument("keyword", help="公司证券代码或简称")
+    company.add_argument("--year", type=int, help="年份，如 2025")
+    company.add_argument("--exchange", choices=["sz", "sh", "bj"], help="交易所过滤")
+    company.add_argument("--notify-email", help="分析完成后通知邮箱")
+    company.set_defaults(handler=_handle_company)
+
+    get_cmd = annual_analysis_subparsers.add_parser("get", help="查询年报分析任务")
+    get_cmd.add_argument("task_or_job_id", help="分析任务 ID。支持 direct job_id 或 company task_id")
+    get_cmd.add_argument("--save-report-to", help="已完成时将 HTML 报告保存到指定路径")
+    get_cmd.set_defaults(handler=_handle_get)
+
+
+def _add_job_submit_args(parser: ArgumentParser) -> None:
+    parser.add_argument("--lang", default="zh", choices=["zh", "en"], help="报告语言")
+    parser.add_argument("--wait", action="store_true", help="阻塞等待任务完成")
+    parser.add_argument("--poll-interval", type=int, default=10, help="轮询间隔秒数")
+    parser.add_argument("--max-polls", type=int, default=60, help="最大轮询次数")
+
+
+def _handle_pdf_file(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.annual.analyze_submit(args.pdf_path, lang=args.lang)
+    data = _attach_follow_up_command(data, id_key="job_id")
+    return _render_or_wait_job(client, data, args)
+
+
+def _handle_pdf_url(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.annual.analyze_submit_pdf_url(args.pdf_url, lang=args.lang)
+    data = _attach_follow_up_command(data, id_key="job_id")
+    return _render_or_wait_job(client, data, args)
+
+
+def _handle_company(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.annual.analyze_company(
+        args.keyword,
+        year=args.year,
+        exchange=args.exchange,
+        notify_email=args.notify_email,
+    )
+    data = _attach_follow_up_command(data, id_key="task_id")
+    render(data, output=resolve_output(args))
+    return 0
+
+
+def _handle_get(args: Namespace) -> int:
+    client = build_client(args)
+    if str(args.task_or_job_id).isdigit():
+        data = client.annual.get_analysis_task(int(args.task_or_job_id))
+        data = _maybe_download_report(client, data, args)
+    else:
+        data = client.annual.analyze_get(args.task_or_job_id)
+    render(data, output=resolve_output(args))
+    return 0
+
+
+def _maybe_download_report(client, data: dict, args: Namespace) -> dict:
+    if data.get("status") != "completed":
+        return data
+    report_url = data.get("report_url")
+    met_uuid = data.get("met_uuid")
+    if not report_url or not met_uuid:
+        return data
+
+    dest = args.save_report_to
+    saved_path = client.annual.download_report(
+        met_uuid=met_uuid,
+        report_url=report_url,
+        company_name=data.get("company_name"),
+        dest=dest,
+    )
+    enriched = dict(data)
+    enriched["saved_report_path"] = str(Path(saved_path).resolve())
+    return enriched
+
+
+def _attach_follow_up_command(data: dict, *, id_key: str) -> dict:
+    task_id = data.get(id_key)
+    if not task_id:
+        return data
+    enriched = dict(data)
+    enriched["next_command"] = f"clawshire annual-analysis get {task_id}"
+    return enriched
+
+
+def _render_or_wait_job(client, data: dict, args: Namespace) -> int:
+    if not args.wait:
+        render(data, output=resolve_output(args))
+        return 0
+
+    job_id = data.get("job_id")
+    if not job_id:
+        render(data, output=resolve_output(args))
+        return 0
+
+    for attempt in range(args.max_polls):
+        result = client.annual.analyze_get(job_id)
+        status = result.get("status", "unknown")
+        print(f"[{attempt + 1}/{args.max_polls}] status={status}")
+        if status in {"completed", "failed"}:
+            render(result, output=resolve_output(args))
+            return 0
+        time.sleep(args.poll_interval)
+
+    print(f"轮询超时，job_id={job_id}")
+    return 1

clawshire_cli/commands/annual_report.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from clawshire_cli.context import build_client, resolve_output
+from clawshire_cli.output import render
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("annual-report", help="年报查询")
+    annual_report_subparsers = parser.add_subparsers(dest="annual_report_command", required=True)
+
+    latest = annual_report_subparsers.add_parser("latest", help="获取最新年报列表")
+    latest.add_argument("--page", type=int, default=1, help="页码")
+    latest.add_argument("--page-size", type=int, default=20, help="每页数量")
+    latest.add_argument("--year", type=int, help="年份，如 2025")
+    latest.add_argument("--exchange", help="交易所，如 bj")
+    latest.add_argument("--keyword", help="关键词或公司代码")
+    latest.set_defaults(handler=_handle_latest)
+
+    data = annual_report_subparsers.add_parser("data", help="获取年报结构化数据")
+    data.add_argument("met_uuid", help="年报 met_uuid")
+    data.set_defaults(handler=_handle_data)
+
+
+def _handle_latest(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.annual.latest(
+        page=args.page,
+        page_size=args.page_size,
+        year=args.year,
+        exchange=args.exchange,
+        keyword=args.keyword,
+    )
+    render(data, output=resolve_output(args))
+    return 0
+
+
+def _handle_data(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.annual.data(args.met_uuid)
+    render(data, output=resolve_output(args))
+    return 0

clawshire_cli/commands/auth.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from clawshire_cli.config import CONFIG_PATH, load_config, mask_api_key, save_config
+from clawshire_cli.context import build_client, resolve_output
+from clawshire_cli.output import render
+from clawshire_sdk import ClawShireApiError, ClawShireAuthError, ClawShireNetworkError
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("auth", help="认证与连通性检查")
+    auth_subparsers = parser.add_subparsers(dest="auth_command", required=True)
+
+    set_key = auth_subparsers.add_parser("set-key", help="保存 API Key 到本地配置")
+    set_key.add_argument("api_key", help="ClawShire API Key")
+    set_key.set_defaults(handler=_handle_set_key)
+
+    clear_key = auth_subparsers.add_parser("clear-key", help="清除本地保存的 API Key")
+    clear_key.set_defaults(handler=_handle_clear_key)
+
+    logout = auth_subparsers.add_parser("logout", help="退出登录并清除本地保存的 API Key")
+    logout.set_defaults(handler=_handle_clear_key)
+
+    show = auth_subparsers.add_parser("show", help="查看当前认证配置")
+    show.set_defaults(handler=_handle_show)
+
+    status = auth_subparsers.add_parser("status", help="查看当前认证状态")
+    status.set_defaults(handler=_handle_status)
+
+    check = auth_subparsers.add_parser("check", help="检查当前认证是否可用")
+    check.set_defaults(handler=_handle_check)
+
+    whoami = auth_subparsers.add_parser("whoami", help="检查当前 API Key")
+    whoami.set_defaults(handler=_handle_whoami)
+
+
+def _handle_set_key(args: Namespace) -> int:
+    config = load_config()
+    config.api_key = args.api_key
+    path = save_config(config)
+    print(f"API Key 已保存到 {path}")
+    print(f"当前 Key: {mask_api_key(args.api_key)}")
+    return 0
+
+
+def _handle_clear_key(args: Namespace) -> int:
+    config = load_config()
+    config.api_key = None
+    path = save_config(config)
+    print(f"API Key 已清除: {path}")
+    return 0
+
+
+def _handle_show(args: Namespace) -> int:
+    config = load_config()
+    render(
+        {
+            "base_url": config.base_url,
+            "api_key": mask_api_key(config.api_key),
+            "output": config.output,
+            "timeout": config.timeout,
+        },
+        output=resolve_output(args),
+    )
+    return 0
+
+
+def _handle_status(args: Namespace) -> int:
+    source = _resolve_api_key_source()
+    config = load_config()
+    payload = {
+        "base_url": config.base_url,
+        "config_path": str(CONFIG_PATH),
+        "api_key_source": source,
+        "api_key": mask_api_key(config.api_key),
+        "configured": bool(config.api_key),
+        "authenticated": False,
+        "message": "未配置 API Key",
+    }
+    if not config.api_key:
+        render(payload, output=resolve_output(args))
+        return 1
+
+    client = build_client(args)
+    try:
+        client.get("/api/v1/api-key/info", auth_required=True)
+        payload["authenticated"] = True
+        payload["message"] = "认证可用"
+    except (ClawShireAuthError, ClawShireApiError, ClawShireNetworkError) as exc:
+        payload["message"] = str(exc)
+
+    render(payload, output=resolve_output(args))
+    return 0 if payload["authenticated"] else 1
+
+
+def _handle_check(args: Namespace) -> int:
+    client = build_client(args)
+    try:
+        client.get("/api/v1/api-key/info", auth_required=True)
+        print("ok")
+        return 0
+    except (ClawShireAuthError, ClawShireApiError, ClawShireNetworkError):
+        return 1
+
+
+def _handle_whoami(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.get("/api/v1/api-key/info", auth_required=True)
+    render(data, output=resolve_output(args))
+    return 0
+
+
+def _resolve_api_key_source() -> str:
+    import os
+
+    if os.getenv("CLAWSHIRE_API_KEY"):
+        return "env"
+    if CONFIG_PATH.exists():
+        return "config"
+    return "none"

clawshire_cli/commands/notice.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from clawshire_cli.context import build_client, resolve_output
+from clawshire_cli.output import render
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("notice", help="公告查询")
+    notice_subparsers = parser.add_subparsers(dest="notice_command", required=True)
+
+    search = notice_subparsers.add_parser("search", help="按日期范围查询公告")
+    _add_search_args(search)
+    search.set_defaults(handler=_handle_search)
+
+    stock = notice_subparsers.add_parser("stock", help="按证券代码查询公告")
+    stock.add_argument("sec_code", help="证券代码")
+    _add_search_args(stock)
+    stock.set_defaults(handler=_handle_stock)
+
+    link = notice_subparsers.add_parser("link", help="按公告原文链接查询")
+    link.add_argument("--met-link", required=True, help="公告原文链接")
+    link.set_defaults(handler=_handle_link)
+
+
+def _add_search_args(parser: ArgumentParser) -> None:
+    parser.add_argument("--start-date", required=True, help="开始日期 YYYY-MM-DD")
+    parser.add_argument("--end-date", required=True, help="结束日期 YYYY-MM-DD")
+    parser.add_argument("--keyword", help="关键词（证券代码或公司名称）")
+    parser.add_argument("--infotype", help="公告类别")
+    parser.add_argument("--page", type=int, default=1, help="页码")
+    parser.add_argument("--page-size", type=int, default=20, help="每页数量")
+    parser.add_argument("--page-all", action="store_true", help="自动翻页获取全部结果")
+
+
+def _fetch_all(fetch_fn, **kwargs) -> dict:
+    page, items = 1, []
+    while True:
+        data = fetch_fn(**kwargs, page=page, page_size=100)
+        batch = data.get("items") or data.get("data") or []
+        items.extend(batch)
+        if len(batch) < 100:
+            break
+        page += 1
+    return {"items": items, "total": len(items)}
+
+
+def _handle_search(args: Namespace) -> int:
+    client = build_client(args)
+    kw = dict(start_date=args.start_date, end_date=args.end_date,
+               keyword=args.keyword, infotype=args.infotype)
+    if args.page_all:
+        data = _fetch_all(client.filings.search, **kw)
+    else:
+        data = client.filings.search(**kw, page=args.page, page_size=args.page_size)
+    render(data, output=resolve_output(args))
+    return 0
+
+
+def _handle_stock(args: Namespace) -> int:
+    client = build_client(args)
+    kw = dict(start_date=args.start_date, end_date=args.end_date,
+               keyword=args.keyword, infotype=args.infotype)
+    if args.page_all:
+        data = _fetch_all(lambda **k: client.filings.stock(args.sec_code, **k), **kw)
+    else:
+        data = client.filings.stock(args.sec_code, **kw, page=args.page, page_size=args.page_size)
+    render(data, output=resolve_output(args))
+    return 0
+
+
+def _handle_link(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.filings.link(args.met_link)
+    render(data, output=resolve_output(args))
+    return 0

clawshire_cli/commands/update.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from typing import Any
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+import httpx
+from packaging.version import Version
+
+from clawshire_cli.context import resolve_output
+from clawshire_cli.output import render
+from clawshire_sdk import ClawShireApiError, ClawShireNetworkError
+
+
+PACKAGE_NAME = "clawshire-cli"
+PYPI_JSON_URL = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
+PYPI_PROJECT_URL = f"https://pypi.org/project/{PACKAGE_NAME}/"
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "update",
+        aliases=["upgrade"],
+        help="升级当前 CLI 到最新版本",
+    )
+    parser.add_argument(
+        "--manager",
+        choices=["auto", "uv", "pipx", "pip"],
+        default="auto",
+        help="指定升级方式，默认自动检测",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="只显示将要执行的升级命令，不实际执行",
+    )
+    parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="跳过确认提示，直接执行升级",
+    )
+    parser.set_defaults(handler=_handle_update)
+
+
+def _handle_update(args: Namespace) -> int:
+    current_version = _read_current_version()
+    latest_version, version_source = _read_latest_version()
+    manager = _resolve_manager(args.manager)
+    command = _build_update_command(manager)
+    payload = {
+        "current_version": current_version,
+        "latest_version": latest_version,
+        "version_source": version_source,
+        "project_url": PYPI_PROJECT_URL,
+        "manager": manager,
+        "command": " ".join(command),
+        "dry_run": args.dry_run,
+    }
+
+    if latest_version is not None and Version(current_version) >= Version(latest_version):
+        payload["message"] = "当前已经是最新版本"
+        render(payload, output=resolve_output(args))
+        return 0
+
+    if args.dry_run:
+        if latest_version is None:
+            payload["message"] = "暂时无法从 PyPI 确认最新版本，可执行以下命令尝试升级"
+        else:
+            payload["message"] = "检测到新版本，可执行以下命令升级当前 CLI"
+        render(payload, output=resolve_output(args))
+        return 0
+
+    if latest_version is None:
+        payload["message"] = "暂时无法从 PyPI 确认最新版本，准备尝试升级 clawshire-cli"
+    else:
+        payload["message"] = "检测到新版本，准备升级 clawshire-cli"
+    render(payload, output=resolve_output(args))
+
+    if not args.yes and not _confirm_upgrade(command):
+        print("已取消升级。")
+        return 1
+
+    result = subprocess.run(command, check=False)
+    if result.returncode != 0:
+        raise ClawShireApiError(f"升级失败，请手动执行: {' '.join(command)}")
+
+    print("升级命令执行完成。建议重新运行 `clawshire version` 确认版本。")
+    return 0
+
+
+def _resolve_manager(preferred: str) -> str:
+    if preferred != "auto":
+        if not _manager_available(preferred):
+            raise ClawShireApiError(f"未检测到 {preferred}，请先安装或改用其他 manager")
+        return preferred
+
+    for candidate in ("uv", "pipx", "pip"):
+        if _manager_available(candidate):
+            return candidate
+    raise ClawShireApiError("未检测到可用的升级工具，请安装 uv、pipx 或 pip 后重试")
+
+
+def _manager_available(manager: str) -> bool:
+    if manager == "pip":
+        return True
+    return shutil.which(manager) is not None
+
+
+def _build_update_command(manager: str) -> list[str]:
+    if manager == "uv":
+        return ["uv", "tool", "upgrade", PACKAGE_NAME]
+    if manager == "pipx":
+        return ["pipx", "upgrade", PACKAGE_NAME]
+    return [sys.executable, "-m", "pip", "install", "--upgrade", PACKAGE_NAME]
+
+
+def _confirm_upgrade(command: list[str]) -> bool:
+    answer = input(f"将执行升级命令: {' '.join(command)}\n继续? [y/N] ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+def _read_current_version() -> str:
+    try:
+        from clawshire_cli.main import get_cli_version
+
+        return get_cli_version()
+    except Exception:
+        return "unknown"
+
+
+def _read_latest_version() -> tuple[str | None, str]:
+    try:
+        payload = _fetch_pypi_metadata()
+    except ClawShireApiError:
+        return None, "pypi-not-published"
+    except ClawShireNetworkError:
+        return None, "pypi-unreachable"
+
+    info = payload.get("info")
+    if not isinstance(info, dict):
+        return None, "pypi-invalid-response"
+    version = info.get("version")
+    if not isinstance(version, str) or not version.strip():
+        return None, "pypi-invalid-response"
+    return version.strip(), "pypi"
+
+
+def _fetch_pypi_metadata() -> dict[str, Any]:
+    try:
+        with httpx.Client(timeout=10.0) as client:
+            response = client.get(PYPI_JSON_URL, headers={"Accept": "application/json"})
+    except httpx.HTTPError as exc:
+        raise ClawShireNetworkError(f"访问 PyPI 失败: {exc}") from exc
+
+    if response.status_code == 404:
+        raise ClawShireApiError(f"PyPI 上暂未发布 {PACKAGE_NAME}", status_code=404)
+    if response.status_code >= 400:
+        raise ClawShireApiError(
+            f"读取 PyPI 版本失败: HTTP {response.status_code}",
+            status_code=response.status_code,
+        )
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ClawShireApiError("PyPI 返回了非 JSON 响应") from exc
+    if not isinstance(payload, dict):
+        raise ClawShireApiError("PyPI 返回了无效响应")
+    return payload

clawshire_cli/commands/user.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from clawshire_cli.context import build_client, resolve_output
+from clawshire_cli.output import render
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("user", help="用户信息与额度查询")
+    user_subparsers = parser.add_subparsers(dest="user_command", required=True)
+
+    info = user_subparsers.add_parser("info", help="查询余额、免费次数、配额等用户信息")
+    info.set_defaults(handler=_handle_info)
+
+
+def _handle_info(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.get("/api/v1/api-key/info", auth_required=True)
+    render(data, output=resolve_output(args))
+    return 0

clawshire_cli/config.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+import tomli_w
+import tomllib
+
+
+DEFAULT_BASE_URL = "https://api.clawshire.cn"
+CONFIG_PATH = Path.home() / ".config" / "clawshire" / "config.toml"
+
+
+@dataclass
+class CliConfig:
+    base_url: str = DEFAULT_BASE_URL
+    api_key: str | None = None
+    output: str = "table"
+    timeout: float = 30.0
+
+
+def load_config() -> CliConfig:
+    config = CliConfig()
+
+    if CONFIG_PATH.exists():
+        data = tomllib.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        config.base_url = str(data.get("base_url") or config.base_url)
+        config.api_key = data.get("api_key") or config.api_key
+        config.output = str(data.get("output") or config.output)
+        timeout = data.get("timeout")
+        if timeout is not None:
+            config.timeout = float(timeout)
+
+    config.base_url = os.getenv("CLAWSHIRE_BASE_URL", config.base_url)
+    config.api_key = os.getenv("CLAWSHIRE_API_KEY", config.api_key)
+    config.output = os.getenv("CLAWSHIRE_OUTPUT", config.output)
+
+    env_timeout = os.getenv("CLAWSHIRE_TIMEOUT")
+    if env_timeout:
+        config.timeout = float(env_timeout)
+    return config
+
+
+def save_config(config: CliConfig) -> Path:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "base_url": config.base_url,
+        "api_key": config.api_key,
+        "output": config.output,
+        "timeout": config.timeout,
+    }
+    CONFIG_PATH.write_text(tomli_w.dumps(data), encoding="utf-8")
+    return CONFIG_PATH
+
+
+def mask_api_key(api_key: str | None) -> str:
+    if not api_key:
+        return ""
+    if len(api_key) <= 8:
+        return "*" * len(api_key)
+    return f"{api_key[:6]}...{api_key[-4:]}"

clawshire_cli/context.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from argparse import Namespace
+
+from clawshire_cli.config import load_config
+from clawshire_sdk import ClawShireClient
+
+
+def build_client(args: Namespace) -> ClawShireClient:
+    config = load_config()
+    base_url = args.base_url or config.base_url
+    api_key = args.api_key if args.api_key is not None else config.api_key
+    timeout = args.timeout if args.timeout is not None else config.timeout
+    return ClawShireClient(base_url=base_url, api_key=api_key, timeout=timeout)
+
+
+def resolve_output(args: Namespace) -> str:
+    config = load_config()
+    return args.output or config.output