clawshire-cli 0.1.0a2__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,97 @@
+from __future__ import annotations
+
+import time
+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.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)
+    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)
+    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,
+    )
+    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))
+    else:
+        data = client.annual.analyze_get(args.task_or_job_id)
+    render(data, output=resolve_output(args))
+    return 0
+
+
+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,63 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from clawshire_cli.config import load_config, mask_api_key, save_config
+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("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)
+
+    show = auth_subparsers.add_parser("show", help="查看当前认证配置")
+    show.set_defaults(handler=_handle_show)
+
+    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_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

clawshire_cli/commands/notice.py

@@ -0,0 +1,66 @@
+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("--infotype", help="公告类别")
+    parser.add_argument("--page", type=int, default=1, help="页码")
+    parser.add_argument("--page-size", type=int, default=20, help="每页数量")
+
+
+def _handle_search(args: Namespace) -> int:
+    client = build_client(args)
+    data = client.filings.search(
+        start_date=args.start_date,
+        end_date=args.end_date,
+        infotype=args.infotype,
+        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)
+    data = client.filings.stock(
+        args.sec_code,
+        start_date=args.start_date,
+        end_date=args.end_date,
+        infotype=args.infotype,
+        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/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

clawshire_cli/main.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from clawshire_cli.commands import annual_analysis, annual_report, auth, notice, user
+from clawshire_sdk import (
+    ClawShireApiError,
+    ClawShireAuthError,
+    ClawShireConfigError,
+    ClawShireNetworkError,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="clawshire",
+        description="ClawShire CLI",
+    )
+    parser.add_argument("--base-url", help="API 基础地址，如 https://api.clawshire.cn")
+    parser.add_argument("--api-key", help="API Key，优先级高于本地配置")
+    parser.add_argument("--output", choices=["table", "json", "markdown"], help="输出格式")
+    parser.add_argument("--timeout", type=float, help="HTTP 超时秒数")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    notice.register(subparsers)
+    annual_report.register(subparsers)
+    annual_analysis.register(subparsers)
+    auth.register(subparsers)
+    user.register(subparsers)
+    return parser
+
+
+def run(argv: list[str] | None = None) -> int:
+    argv = list(argv or sys.argv[1:])
+    if argv:
+        alias_map = {"gg": "notice", "ar": "annual-report", "aa": "annual-analysis"}
+        if argv[0] in alias_map:
+            argv[0] = alias_map[argv[0]]
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 2
+    try:
+        return int(handler(args) or 0)
+    except ClawShireConfigError as exc:
+        print(f"配置错误: {exc}", file=sys.stderr)
+        return 2
+    except ClawShireAuthError as exc:
+        print(f"认证失败: {exc}", file=sys.stderr)
+        return 3
+    except ClawShireNetworkError as exc:
+        print(f"网络错误: {exc}", file=sys.stderr)
+        return 4
+    except ClawShireApiError as exc:
+        print(f"接口错误: {exc}", file=sys.stderr)
+        return 5
+
+
+def main() -> None:
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":
+    main()

clawshire_cli/output.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def render(data: Any, *, output: str) -> None:
+    output = output.lower()
+    if output == "json":
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return
+    if output == "markdown":
+        print(_to_markdown(data))
+        return
+    print(_to_table(data))
+
+
+def _to_markdown(data: Any) -> str:
+    if isinstance(data, list):
+        if not data:
+            return "_No data_"
+        if all(isinstance(item, dict) for item in data):
+            return _dict_list_to_markdown(data)
+    if isinstance(data, dict):
+        if "items" in data and isinstance(data["items"], list):
+            head = {k: v for k, v in data.items() if k != "items"}
+            parts = []
+            if head:
+                parts.append(_dict_to_bullets(head))
+            parts.append(_dict_list_to_markdown(data["items"]))
+            return "\n\n".join(part for part in parts if part)
+        return _dict_to_bullets(data)
+    return str(data)
+
+
+def _to_table(data: Any) -> str:
+    if isinstance(data, list):
+        if not data:
+            return "No data"
+        if all(isinstance(item, dict) for item in data):
+            return _dict_list_to_table(data)
+    if isinstance(data, dict):
+        if "items" in data and isinstance(data["items"], list):
+            header = _dict_to_lines({k: v for k, v in data.items() if k != "items"})
+            body = _dict_list_to_table(data["items"])
+            if header:
+                return f"{header}\n\n{body}"
+            return body
+        return _dict_to_lines(data)
+    return str(data)
+
+
+def _dict_to_lines(data: dict[str, Any]) -> str:
+    return "\n".join(f"{key}: {_format_value(value)}" for key, value in data.items())
+
+
+def _dict_to_bullets(data: dict[str, Any]) -> str:
+    return "\n".join(f"- {key}: {_format_value(value)}" for key, value in data.items())
+
+
+def _dict_list_to_table(rows: list[dict[str, Any]]) -> str:
+    if not rows:
+        return "No data"
+    columns = []
+    for row in rows:
+        for key in row.keys():
+            if key not in columns:
+                columns.append(key)
+    widths = {col: len(col) for col in columns}
+    for row in rows:
+        for col in columns:
+            widths[col] = max(widths[col], len(_format_value(row.get(col))))
+    header = " | ".join(col.ljust(widths[col]) for col in columns)
+    sep = "-+-".join("-" * widths[col] for col in columns)
+    body = [
+        " | ".join(_format_value(row.get(col)).ljust(widths[col]) for col in columns)
+        for row in rows
+    ]
+    return "\n".join([header, sep, *body])
+
+
+def _dict_list_to_markdown(rows: list[dict[str, Any]]) -> str:
+    if not rows:
+        return "_No data_"
+    columns = []
+    for row in rows:
+        for key in row.keys():
+            if key not in columns:
+                columns.append(key)
+    header = "| " + " | ".join(columns) + " |"
+    sep = "| " + " | ".join("---" for _ in columns) + " |"
+    body = []
+    for row in rows:
+        body.append("| " + " | ".join(_format_value(row.get(col)) for col in columns) + " |")
+    return "\n".join([header, sep, *body])
+
+
+def _format_value(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)

clawshire_cli-0.1.0a2.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: clawshire-cli
+Version: 0.1.0a2
+Summary: ClawShire CLI for notice query, annual report query, and annual analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: tomli-w>=1.2.0
+
+# ClawShire CLI
+
+独立可安装的 ClawShire 命令行客户端。
+
+## 安装
+
+当前优先使用内网 PyPI 安装：
+
+```bash
+uv tool install --index http://192.168.41.95:8141/memect/dev/+simple/ clawshire-cli
+```
+
+如果本机已安装 `pipx`，也可通过内网源安装：
+
+```bash
+PIP_INDEX_URL=http://192.168.41.95:8141/memect/dev/+simple/ pipx install clawshire-cli
+```
+
+本地开发可直接从源码目录安装：
+
+```bash
+uv tool install ./clawshire-cli
+pipx install ./clawshire-cli
+```
+
+说明：
+
+1. 当前文档以内网安装方式为准
+2. 未来如果公开发布到外网 PyPI，再补充公共安装命令
+
+安装后可使用两个命令入口：
+
+```bash
+clawshire --help
+cs --help
+```
+
+如果你只想快速确认安装成功，先跑：
+
+```bash
+clawshire --help
+clawshire auth --help
+clawshire user info --api-key <your_api_key>
+```
+
+## 3 分钟上手
+
+把下面几条命令直接复制执行即可：
+
+```bash
+uv tool install --index http://192.168.41.95:8141/memect/dev/+simple/ clawshire-cli
+clawshire auth set-key <your_api_key>
+clawshire user info
+clawshire annual-analysis pdf-url https://static.cninfo.com.cn/finalpage/2026-04-20/1225116956.PDF
+```
+
+如果你要查公告或年报，再继续：
+
+```bash
+clawshire notice search --start-date 2026-04-19 --end-date 2026-04-20
+clawshire annual-report latest --year 2025 --keyword 平安银行
+```
+
+## 先配置 API Key
+
+建议先把 API Key 保存到本地，这样后续不用每次手动加 `--api-key`。
+
+```bash
+clawshire auth set-key <your_api_key>
+clawshire auth show
+clawshire user info
+```
+
+如果想临时覆盖本地配置，也可以直接传：
+
+```bash
+clawshire --api-key <your_api_key> user info
+```
+
+清除本地保存的 Key：
+
+```bash
+clawshire auth clear-key
+```
+
+## 命令
+
+主命令分组：
+
+1. `notice`
+2. `annual-report`
+3. `annual-analysis`
+
+高频简写：
+
+1. `gg` -> `notice`
+2. `ar` -> `annual-report`
+3. `aa` -> `annual-analysis`
+
+## 全部命令能力
+
+| 能力 | 命令 | 是否需要 API Key | 说明 |
+|------|------|------------------|------|
+| 保存 Key | `clawshire auth set-key <key>` | 否 | 保存本地 API Key |
+| 查看认证配置 | `clawshire auth show` | 否 | 查看当前 base_url、key 掩码、输出格式、超时 |
+| 清除 Key | `clawshire auth clear-key` | 否 | 清除本地保存的 API Key |
+| 检查当前 Key | `clawshire auth whoami` | 是 | 校验当前 API Key 是否有效 |
+| 用户信息 | `clawshire user info` | 是 | 查询余额、免费次数、配额等用户信息 |
+| 公告按日期查询 | `clawshire notice search --start-date <d> --end-date <d>` | 否/建议有 | 按日期范围查询公告 |
+| 公告按证券代码查询 | `clawshire notice stock <sec_code> --start-date <d> --end-date <d>` | 否/建议有 | 查询某证券代码公告 |
+| 公告按链接查询 | `clawshire notice link --met-link <pdf_link>` | 否/建议有 | 按公告 PDF 链接查询 |
+| 年报列表 | `clawshire annual-report latest --year <YYYY> --keyword <kw>` | 是 | 查询指定年份年报列表 |
+| 年报结构化数据 | `clawshire annual-report data <met_uuid>` | 是 | 查询指定年报的结构化数据 |
+| 年报分析: 本地文件 | `clawshire annual-analysis pdf-file <path>` | 是 | 上传本地 PDF 分析 |
+| 年报分析: PDF 链接 | `clawshire annual-analysis pdf-url <url>` | 是 | 下载 PDF 链接后分析 |
+| 年报分析: 公司 | `clawshire annual-analysis company <代码或简称> --year <YYYY>` | 是 | 先查询指定年份年报，再自动发起分析 |
+| 查询分析任务 | `clawshire annual-analysis get <task_id_or_job_id>` | 是 | 查询分析任务状态或结果 |
+
+简写命令：
+
+| 简写 | 全称 | 示例 |
+|------|------|------|
+| `gg` | `notice` | `cs gg search --start-date 2026-04-19 --end-date 2026-04-20` |
+| `ar` | `annual-report` | `cs ar latest --year 2025 --keyword 平安银行` |
+| `aa` | `annual-analysis` | `cs aa company 000001 --year 2025` |
+
+按命令分组查看帮助：
+
+```bash
+clawshire auth --help
+clawshire user --help
+clawshire notice --help
+clawshire annual-report --help
+clawshire annual-analysis --help
+```
+
+## 示例
+
+```bash
+clawshire user info
+clawshire notice search --start-date 2026-04-01 --end-date 2026-04-20
+clawshire annual-report latest --year 2025 --keyword 平安银行
+clawshire annual-analysis pdf-file ./report.pdf
+clawshire annual-analysis pdf-url https://example.com/report.pdf
+clawshire annual-analysis company 000001 --year 2025
+```
+
+年报分析测试 PDF 示例：
+
+```text
+https://static.cninfo.com.cn/finalpage/2026-04-20/1225116956.PDF
+```
+
+推荐直接试：
+
+```bash
+clawshire annual-analysis pdf-url https://static.cninfo.com.cn/finalpage/2026-04-20/1225116956.PDF
+```
+
+## 配置
+
+支持环境变量：
+
+1. `CLAWSHIRE_API_KEY`
+2. `CLAWSHIRE_BASE_URL`
+3. `CLAWSHIRE_OUTPUT`
+4. `CLAWSHIRE_TIMEOUT`
+
+如果你更习惯环境变量，可直接这样配置：
+
+```bash
+export CLAWSHIRE_API_KEY=<your_api_key>
+clawshire user info
+```
+
+## 最常用命令
+
+查询用户信息：
+
+```bash
+clawshire user info
+```
+
+查询公告：
+
+```bash
+clawshire notice search --start-date 2026-04-19 --end-date 2026-04-20
+clawshire notice stock 000001 --start-date 2026-04-01 --end-date 2026-04-20
+clawshire notice link --met-link <pdf_link>
+```
+
+查询年报：
+
+```bash
+clawshire annual-report latest --year 2025 --keyword 平安银行
+clawshire annual-report data <met_uuid>
+```
+
+发起年报分析：
+
+```bash
+clawshire annual-analysis pdf-file ./report.pdf
+clawshire annual-analysis pdf-url https://static.cninfo.com.cn/finalpage/2026-04-20/1225116956.PDF
+clawshire annual-analysis company 000001 --year 2025
+```
+
+查询分析任务：
+
+```bash
+clawshire annual-analysis get <task_id_or_job_id>
+```
+
+## 必要提示
+
+1. 全局参数要放在子命令前面，例如：`clawshire --output json user info`
+2. `notice` 查询通常不需要 API Key，但如果本地配置了错误的 Key，可能会带上错误认证头
+3. `annual-report`、`annual-analysis`、`user info` 都需要有效 API Key
+4. CLI 不单独实现计费，仍然走服务端原有配额和计费逻辑
+
+## 常见报错与处理
+
+### 1. `认证失败: Authorization 格式错误，应为 Bearer <api_key>`
+
+原因：
+
+1. 本地保存了错误的 API Key
+2. 环境变量里有错误的 `CLAWSHIRE_API_KEY`
+3. 你传入的不是完整 API Key
+
+处理：
+
+```bash
+clawshire auth show
+clawshire auth clear-key
+clawshire auth set-key <your_api_key>
+clawshire user info
+```
+
+如果你使用环境变量，也检查：
+
+```bash
+echo $CLAWSHIRE_API_KEY
+```
+
+### 2. `配置错误: 该命令需要 API Key`
+
+原因：
+
+1. 你在调用需要认证的命令，但还没有配置 Key
+
+处理：
+
+```bash
+clawshire auth set-key <your_api_key>
+clawshire user info
+```
+
+或者临时传参：
+
+```bash
+clawshire --api-key <your_api_key> user info
+```
+
+### 3. `unrecognized arguments: --output json`
+
+原因：
+
+1. 把全局参数写在了子命令后面
+
+错误示例：
+
+```bash
+clawshire notice search --start-date 2026-04-19 --end-date 2026-04-20 --output json
+```
+
+正确写法：
+
+```bash
+clawshire --output json notice search --start-date 2026-04-19 --end-date 2026-04-20
+```
+
+### 4. `未找到与 XXX 匹配的年报`
+
+原因：
+
+1. 公司代码或简称不匹配
+2. 指定年份没有收录对应年报
+3. 交易所筛选过窄
+
+处理：
+
+```bash
+clawshire annual-report latest --year 2025 --keyword 平安银行
+clawshire annual-report latest --year 2025 --keyword 000001
+clawshire annual-analysis company 000001 --year 2025
+```
+
+如果仍然找不到，先去掉 `--exchange` 再试。
+
+### 5. `查询分析任务` 没返回结果
+
+原因：
+
+1. `annual-analysis get` 传错了 ID
+2. `pdf-file/pdf-url` 用的是 `job_id`
+3. `company` 用的是平台异步分析 `task_id`
+
+处理：
+
+1. `pdf-file` / `pdf-url` 后续查询传 `job_id`
+2. `company` 后续查询优先传 `task_id`
+
+示例：
+
+```bash
+clawshire annual-analysis get 123
+clawshire annual-analysis get job_xxx
+```
+
+## 发布流程
+
+### 版本更新
+
+1. 修改 [pyproject.toml](/Users/memect/work/code/sz_extract/hermeshub/clawshire-cli/pyproject.toml) 中的 `version`
+2. 如有命令变化，同步更新本 README 与根目录 [README.md](/Users/memect/work/code/sz_extract/hermeshub/README.md)
+
+### 本地构建
+
+```bash
+cd clawshire-cli
+uv build
+```
+
+构建产物位于：
+
+```text
+clawshire-cli/dist/
+```
+
+### 本地安装验证
+
+```bash
+cd clawshire-cli
+uv tool install .
+clawshire --help
+cs --help
+clawshire notice search --start-date 2026-04-19 --end-date 2026-04-20
+```
+
+如果本机已安装 `pipx`，再补一轮：
+
+```bash
+cd clawshire-cli
+pipx install .
+clawshire --help
+```
+
+### 发布测试版
+
+建议先发测试版，再发正式版，例如：
+
+1. `0.1.0a1`
+2. `0.1.0b1`
+3. `0.1.0rc1`
+
+发布命令示例：
+
+```bash
+cd clawshire-cli
+uv build
+uv publish
+```
+
+如果要发到 TestPyPI：
+
+```bash
+cd clawshire-cli
+uv build
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+如果要发到内网 PyPI：
+
+```bash
+cd clawshire-cli
+uv build
+uv publish --publish-url http://192.168.41.95:8141/memect/dev
+```
+
+安装验证：
+
+```bash
+uv tool install --index memect clawshire-cli
+clawshire --help
+cs --help
+```
+
+### 当前仓库内的限制
+
+当前仓库环境没有可用的公共 PyPI / TestPyPI 发布凭据。  
+如果存在内网源可直连且无需额外凭据，则可以直接发布到内网源并验证安装链路。

clawshire_cli-0.1.0a2.dist-info/RECORD

@@ -0,0 +1,22 @@
+clawshire_cli/__init__.py,sha256=da1PTClDMl-IBkrSvq6JC1lnS-K_BASzCvxVhNxN5Ls,13
+clawshire_cli/config.py,sha256=ch5LcNK4_ApdWYY4y3h-r8kdEB0II09gQDRXi334BFA,1753
+clawshire_cli/context.py,sha256=kpfRrprafoOm77Hr0gElnmBnYgsGTe3czfzeRzMNqps,629
+clawshire_cli/main.py,sha256=9oXNRiNY4NAfBPvN8i7fq-82WOlG4lZU3vxLK6FWWlc,2063
+clawshire_cli/output.py,sha256=LP01YtB5ytMyFGBKkJ913TF9WQ_tovLByTtREjDTNi4,3343
+clawshire_cli/commands/__init__.py,sha256=da1PTClDMl-IBkrSvq6JC1lnS-K_BASzCvxVhNxN5Ls,13
+clawshire_cli/commands/annual_analysis.py,sha256=UG2o4Abj24VVCwkoIJQRaLwwDqDip_1OwjpwDfr3_Og,3863
+clawshire_cli/commands/annual_report.py,sha256=MSKViEF6W2Guj0D3GEtrjvwRU-n-2AEgEppD1NLpcTw,1640
+clawshire_cli/commands/auth.py,sha256=R4KsV0hj_zFII_8S-XOuBFqKahevsj_Naq1YfX_Q-mU,2078
+clawshire_cli/commands/notice.py,sha256=leuZm0OJHrHHbHrWE6ok-Mi5xEQxyl4whtSrwopRWug,2328
+clawshire_cli/commands/user.py,sha256=5j9ENnUJ_kZIXwlvt7f-I2VtAEk-eGnwcaBatsdXrrM,788
+clawshire_sdk/__init__.py,sha256=Djxzwp60qYpiUw3yzBBDojdZv8zZv8LhDKSxLHJM-4g,332
+clawshire_sdk/client.py,sha256=y6Cyc5Qmqxru1YX0iH3rG0EW3MZj95IHNvTpeOguVns,4103
+clawshire_sdk/errors.py,sha256=UFZkh8peISPf3q-WylS6IblHs0-7WD7AmGjutyRRmLE,619
+clawshire_sdk/domains/__init__.py,sha256=9rNGg008368ApuC31DOP9rFF8BlDJ8KdHNpH8AhleXE,177
+clawshire_sdk/domains/annual_reports.py,sha256=r-7-w2ceNHSlkmZJr6XHoUNDa42kuHpgLsnj_JVFVaE,4602
+clawshire_sdk/domains/filings.py,sha256=TIjK9L0Kv1RbZLO_T6YsafQz39IREDV4MrwLUrojhd0,1482
+clawshire_cli-0.1.0a2.dist-info/METADATA,sha256=BVPcHY9nCOIvsqjXbuUMmpNo2nsz0koXcbaG29g4WLk,9671
+clawshire_cli-0.1.0a2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+clawshire_cli-0.1.0a2.dist-info/entry_points.txt,sha256=F5_iwYGiXfJoZYApY0Iggq94mQoWD0X96mmPw8RHX7s,83
+clawshire_cli-0.1.0a2.dist-info/top_level.txt,sha256=VUvb6M2T4sGoyZf9uvZrSkW9QwjXQvQmIQokT-mpRLc,28
+clawshire_cli-0.1.0a2.dist-info/RECORD,,

clawshire_cli-0.1.0a2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clawshire_cli-0.1.0a2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clawshire = clawshire_cli.main:main
+cs = clawshire_cli.main:main

clawshire_cli-0.1.0a2.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+clawshire_cli
+clawshire_sdk

clawshire_sdk/__init__.py

@@ -0,0 +1,15 @@
+from clawshire_sdk.client import ClawShireClient
+from clawshire_sdk.errors import (
+    ClawShireApiError,
+    ClawShireAuthError,
+    ClawShireConfigError,
+    ClawShireNetworkError,
+)
+
+__all__ = [
+    "ClawShireApiError",
+    "ClawShireAuthError",
+    "ClawShireClient",
+    "ClawShireConfigError",
+    "ClawShireNetworkError",
+]

clawshire_sdk/client.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from clawshire_sdk.domains import AnnualReportsDomain, FilingsDomain
+from clawshire_sdk.errors import (
+    ClawShireApiError,
+    ClawShireAuthError,
+    ClawShireConfigError,
+    ClawShireNetworkError,
+)
+
+
+class ClawShireClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.filings = FilingsDomain(self)
+        self.annual = AnnualReportsDomain(self)
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        auth_required: bool,
+        unwrap: bool = True,
+    ) -> dict[str, Any]:
+        return self._request("GET", path, params=params, auth_required=auth_required, unwrap=unwrap)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        auth_required: bool,
+        unwrap: bool = True,
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            path,
+            json=json,
+            data=data,
+            files=files,
+            auth_required=auth_required,
+            unwrap=unwrap,
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        auth_required: bool,
+        unwrap: bool = True,
+    ) -> dict[str, Any]:
+        headers = self._build_headers(auth_required=auth_required)
+        url = f"{self.base_url}{path}"
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.request(
+                    method,
+                    url,
+                    headers=headers,
+                    params=params,
+                    json=json,
+                    data=data,
+                    files=files,
+                )
+        except httpx.HTTPError as exc:
+            raise ClawShireNetworkError(str(exc)) from exc
+
+        payload = self._decode_payload(response)
+        if response.status_code in (401, 403):
+            raise ClawShireAuthError(self._extract_message(payload, fallback="认证失败"))
+        if response.status_code >= 400:
+            raise ClawShireApiError(
+                self._extract_message(payload, fallback=f"请求失败: HTTP {response.status_code}"),
+                status_code=response.status_code,
+            )
+
+        if unwrap and isinstance(payload, dict) and "code" in payload and "data" in payload:
+            code = payload.get("code")
+            if code != 200:
+                raise ClawShireApiError(self._extract_message(payload, fallback="业务请求失败"))
+            return payload["data"]
+        return payload
+
+    def _build_headers(self, *, auth_required: bool) -> dict[str, str]:
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        elif auth_required:
+            raise ClawShireConfigError("该命令需要 API Key。请设置 CLAWSHIRE_API_KEY 或使用 --api-key。")
+        return headers
+
+    @staticmethod
+    def _decode_payload(response: httpx.Response) -> dict[str, Any]:
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise ClawShireApiError("上游返回了非 JSON 响应", status_code=response.status_code) from exc
+
+    @staticmethod
+    def _extract_message(payload: Any, *, fallback: str) -> str:
+        if isinstance(payload, dict):
+            for key in ("message", "detail", "error"):
+                value = payload.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value
+        return fallback

clawshire_sdk/domains/__init__.py

@@ -0,0 +1,4 @@
+from clawshire_sdk.domains.annual_reports import AnnualReportsDomain
+from clawshire_sdk.domains.filings import FilingsDomain
+
+__all__ = ["AnnualReportsDomain", "FilingsDomain"]

clawshire_sdk/domains/annual_reports.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from clawshire_sdk.errors import ClawShireApiError, ClawShireNetworkError
+
+
+class AnnualReportsDomain:
+    def __init__(self, client):
+        self._client = client
+
+    def latest(
+        self,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+        year: int | None = None,
+        exchange: str | None = None,
+        keyword: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if year is not None:
+            params["year"] = year
+        if exchange:
+            params["exchange"] = exchange
+        if keyword:
+            params["keyword"] = keyword
+        return self._client.get("/api/v1/annual-report/latest", params=params, auth_required=True)
+
+    def data(self, met_uuid: str) -> dict[str, Any]:
+        return self._client.get(f"/api/v1/annual-report/data/{met_uuid}", auth_required=True)
+
+    def analyze_submit(self, pdf_path: str, *, lang: str = "zh") -> dict[str, Any]:
+        path = Path(pdf_path)
+        content = path.read_bytes()
+        return self.analyze_submit_bytes(content, filename=path.name, lang=lang)
+
+    def analyze_submit_bytes(
+        self,
+        content: bytes,
+        *,
+        filename: str = "report.pdf",
+        lang: str = "zh",
+    ) -> dict[str, Any]:
+        files = {"file": (filename, content, "application/pdf")}
+        data = {"lang": lang}
+        return self._client.post(
+            "/api/v1/financial-analysis/jobs",
+            files=files,
+            data=data,
+            auth_required=True,
+        )
+
+    def analyze_submit_pdf_url(self, pdf_url: str, *, lang: str = "zh") -> dict[str, Any]:
+        try:
+            with httpx.Client(timeout=self._client.timeout) as client:
+                response = client.get(pdf_url)
+                response.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise ClawShireNetworkError(f"下载 PDF 失败: {exc}") from exc
+
+        filename = Path(urlparse(pdf_url).path).name or "report.pdf"
+        return self.analyze_submit_bytes(response.content, filename=filename, lang=lang)
+
+    def analyze_get(self, job_id: str) -> dict[str, Any]:
+        return self._client.get(
+            f"/api/v1/financial-analysis/jobs/{job_id}",
+            auth_required=True,
+            unwrap=False,
+        )
+
+    def analyze_company(
+        self,
+        keyword: str,
+        *,
+        year: int | None = None,
+        exchange: str | None = None,
+        notify_email: str | None = None,
+    ) -> dict[str, Any]:
+        reports = self.latest(page=1, page_size=20, year=year, exchange=exchange, keyword=keyword)
+        items = reports.get("items", [])
+        if not items:
+            if year is not None:
+                raise ClawShireApiError(f"未找到与 {keyword} 匹配的 {year} 年年报")
+            raise ClawShireApiError(f"未找到与 {keyword} 匹配的年报")
+
+        selected = self._pick_report(items, keyword)
+        payload: dict[str, Any] = {}
+        if notify_email:
+            payload["notify_email"] = notify_email
+
+        task = self._client.post(
+            f"/api/v1/annual-report/analyze/{selected['met_uuid']}",
+            json=payload,
+            auth_required=True,
+        )
+        return {
+            **task,
+            "selected_report": {
+                "met_uuid": selected.get("met_uuid"),
+                "company_code": selected.get("company_code"),
+                "company_name": selected.get("company_name"),
+                "pdf_url": selected.get("pdf_url"),
+                "publish_time": selected.get("publish_time"),
+            },
+        }
+
+    def get_analysis_task(self, task_id: int) -> dict[str, Any]:
+        tasks = self._client.get("/api/v1/annual-report/analysis-tasks", auth_required=True)
+        if isinstance(tasks, list):
+            for task in tasks:
+                if int(task.get("task_id", -1)) == int(task_id):
+                    return task
+        raise ClawShireApiError(f"未找到 task_id={task_id} 的分析任务")
+
+    @staticmethod
+    def _pick_report(items: list[dict[str, Any]], keyword: str) -> dict[str, Any]:
+        normalized = keyword.strip().lower()
+        for item in items:
+            if str(item.get("company_code", "")).strip().lower() == normalized:
+                return item
+        for item in items:
+            if str(item.get("company_name", "")).strip().lower() == normalized:
+                return item
+        return items[0]

clawshire_sdk/domains/filings.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class FilingsDomain:
+    def __init__(self, client):
+        self._client = client
+
+    def search(
+        self,
+        *,
+        start_date: str,
+        end_date: str,
+        infotype: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> dict[str, Any]:
+        params = {
+            "start_date": start_date,
+            "end_date": end_date,
+            "page": page,
+            "page_size": page_size,
+        }
+        if infotype:
+            params["infotype"] = infotype
+        return self._client.get("/api/v1/announcements", params=params, auth_required=False)
+
+    def stock(
+        self,
+        sec_code: str,
+        *,
+        start_date: str,
+        end_date: str,
+        infotype: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> dict[str, Any]:
+        params = {
+            "start_date": start_date,
+            "end_date": end_date,
+            "page": page,
+            "page_size": page_size,
+        }
+        if infotype:
+            params["infotype"] = infotype
+        return self._client.get(
+            f"/api/v1/stock/{sec_code}/announcements",
+            params=params,
+            auth_required=False,
+        )
+
+    def link(self, met_link: str) -> dict[str, Any]:
+        return self._client.get(
+            "/api/v1/met_link",
+            params={"met_link": met_link},
+            auth_required=False,
+        )

clawshire_sdk/errors.py

@@ -0,0 +1,22 @@
+class ClawShireError(Exception):
+    """Base exception for SDK and CLI errors."""
+
+
+class ClawShireConfigError(ClawShireError):
+    """Missing or invalid local configuration."""
+
+
+class ClawShireAuthError(ClawShireError):
+    """Authentication or authorization failed."""
+
+
+class ClawShireApiError(ClawShireError):
+    """The upstream API returned an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ClawShireNetworkError(ClawShireError):
+    """Network failure while calling the upstream API."""