clawshire-cli 0.1.0a2__tar.gz

clawshire_cli-0.1.0a2/PKG-INFO

@@ -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 发布凭据。  
+如果存在内网源可直连且无需额外凭据，则可以直接发布到内网源并验证安装链路。