clawshire-cli 0.1.0__tar.gz

clawshire_cli-0.1.0/PKG-INFO

@@ -0,0 +1,564 @@
+Metadata-Version: 2.4
+Name: clawshire-cli
+Version: 0.1.0
+Summary: ClawShire CLI for notice query, annual report query, and annual analysis
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: packaging>=24.0
+Requires-Dist: tomli-w>=1.2.0
+
+# ClawShire CLI
+
+独立可安装的 ClawShire 命令行客户端。
+
+## Hello World
+
+要求：`Python >= 3.12`
+
+推荐先用 `uv` 创建一个独立环境，避免污染本地其他 Python 环境：
+
+```bash
+mkdir clawshire-demo && cd clawshire-demo
+uv venv .venv --python 3.12
+source .venv/bin/activate
+uv pip install clawshire-cli
+```
+
+然后：
+
+1. 访问 [https://clawshire.cn](https://clawshire.cn) 注册/登录
+2. 在控制台创建 API Key
+3. 执行下面几条命令
+
+```bash
+clawshire auth set-key <your_api_key>
+clawshire auth status
+clawshire user info
+clawshire notice search --start-date 2026-04-19 --end-date 2026-04-20 --keyword 603402
+```
+
+如果想马上试一个需要认证的能力：
+
+```bash
+clawshire annual-report latest --year 2025 --keyword 平安银行
+```
+
+## 安装与升级
+
+推荐使用 `Python 3.12` 或 `Python 3.13`。
+
+```bash
+pip install clawshire-cli
+```
+
+或使用 uv（推荐）：
+
+```bash
+uv tool install clawshire-cli
+```
+
+本地开发从源码安装：
+
+```bash
+uv tool install ./clawshire-cli
+```
+
+安装后可使用两个命令入口：
+
+```bash
+clawshire --help
+cs --help
+```
+
+升级到最新版本：
+
+```bash
+clawshire update
+clawshire upgrade
+```
+
+如果想先看将执行什么命令：
+
+```bash
+clawshire update --dry-run
+clawshire --output json update --dry-run
+```
+
+如果想跳过确认提示：
+
+```bash
+clawshire update -y
+```
+
+说明：
+
+- `update` 会优先检查 PyPI 上的最新版本，再决定是否执行升级
+- `update` 适合通过 `uv tool`、`pipx`、`pip` 安装的场景
+- `upgrade` 是 `update` 的等价别名
+- 如果你当前是在源码目录里开发，优先继续使用你原来的开发安装方式
+
+## SDK Quick Start
+
+`clawshire-cli` 同时包含 Python SDK，安装 CLI 后即可直接在代码中使用：
+
+```python
+from clawshire_sdk import ClawShireClient
+
+client = ClawShireClient(
+    base_url="https://api.clawshire.cn",
+    api_key="your_api_key",
+)
+
+reports = client.annual.latest(
+    year=2025,
+    keyword="平安银行",
+    page_size=1,
+)
+
+print(reports["items"][0]["pdf_url"])
+```
+
+完整 SDK 用法见：
+
+```text
+docs/sdk-usage.md
+```
+
+## Skills
+
+`clawshire-cli` 仓库同时维护配套 Skills，目录位于：
+
+```text
+skills/
+```
+
+当前已提供：
+
+1. `clawshire-shared`
+2. `clawshire-data-query`
+3. `clawshire-annual-report`
+4. `clawshire-annual-analysis`
+
+这些 Skills 的定位不是重复实现底层请求，而是复用 `clawshire` CLI，把公告查询、年报定位、年报分析等能力组织成更适合 Agent 调用的工作流。
+
+推荐按**整个仓库**安装 skills bundle，而不是单独安装某个 skill 子目录。
+
+示意安装方式：
+
+```bash
+npx skills add <owner>/clawshire-cli -y -g
+```
+
+这意味着：
+
+- `skills/` 下的多个 Skill 会一起分发
+- `clawshire-shared` 可以作为共享规则层存在
+- 不需要假设用户只安装单个 skill 子目录
+
+## Testing
+
+本地完整用户流程测试说明见：
+
+```text
+docs/local-e2e.md
+```
+
+Python SDK 使用说明见：
+
+```text
+docs/sdk-usage.md
+```
+
+一键检查脚本：
+
+```bash
+./scripts/e2e_local_check.sh
+```
+
+该脚本默认执行：
+
+1. 测试集
+2. CLI 基础命令检查
+3. skills 目录结构检查
+
+若环境中存在 `CLAWSHIRE_API_KEY`，还会继续执行真实线上链路验证，包括 `auth check`、`user info`、`notice stock`、`annual-report latest`、`annual-analysis company`。
+
+如果你只想快速确认安装成功，先跑：
+
+```bash
+clawshire --help
+clawshire auth --help
+clawshire update --dry-run
+clawshire user info --api-key <your_api_key>
+```
+
+## 3 分钟上手
+
+把下面几条命令直接复制执行即可：
+
+```bash
+pip install 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
+
+1. 访问 [https://clawshire.cn](https://clawshire.cn) 并注册/登录你的 ClawShire 账号
+2. 进入平台控制台中的 API Key 页面创建一个新 Key
+3. 复制创建后的 Key，并立即保存到安全位置
+4. 回到终端执行：
+
+```bash
+clawshire auth set-key <your_api_key>
+```
+
+如果你只想临时使用，也可以不落盘，直接通过环境变量传入：
+
+```bash
+export CLAWSHIRE_API_KEY="<your_api_key>"
+```
+
+## 先配置 API Key
+
+建议先把 API Key 保存到本地，这样后续不用每次手动加 `--api-key`。
+
+```bash
+clawshire auth set-key <your_api_key>
+clawshire auth show
+clawshire auth status
+clawshire auth check
+clawshire user info
+```
+
+如果想临时覆盖本地配置，也可以直接传：
+
+```bash
+clawshire --api-key <your_api_key> user info
+```
+
+清除本地保存的 Key：
+
+```bash
+clawshire auth clear-key
+clawshire auth logout
+```
+
+## 命令
+
+主命令分组：
+
+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 掩码、输出格式、超时 |
+| 查看认证状态 | `clawshire auth status` | 否/建议有 | 查看当前 key 来源、是否已配置、是否认证可用 |
+| 检查认证可用性 | `clawshire auth check` | 是 | 用退出码检查当前认证是否可用，`0=ok` |
+| 清除 Key | `clawshire auth clear-key` | 否 | 清除本地保存的 API Key |
+| 退出登录 | `clawshire auth logout` | 否 | `clear-key` 的用户友好别名 |
+| 检查当前 Key | `clawshire auth whoami` | 是 | 校验当前 API Key 是否有效 |
+| 用户信息 | `clawshire user info` | 是 | 查询余额、免费次数、配额等用户信息 |
+| 公告按日期查询 | `clawshire notice search --start-date <d> --end-date <d> --keyword 603402` | 否/建议有 | 按日期范围查询公告，示例默认限定证券代码避免结果过大 |
+| 公告按证券代码查询 | `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 --keyword 603402` |
+| `ar` | `annual-report` | `cs ar latest --year 2025 --keyword 平安银行` |
+| `aa` | `annual-analysis` | `cs aa company 000001 --year 2025` |
+
+按命令分组查看帮助：
+
+```bash
+clawshire auth --help
+clawshire update --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 --keyword 603402
+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 --keyword 603402
+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 status
+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 auth status
+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 --keyword 603402 --output json
+```
+
+正确写法：
+
+```bash
+clawshire --output json notice search --start-date 2026-04-19 --end-date 2026-04-20 --keyword 603402
+```
+
+### 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 --keyword 603402
+```
+
+如果本机已安装 `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/
+```
+
+安装验证：
+
+```bash
+pip install clawshire-cli
+clawshire --help
+cs --help
+```