clawshire-cli 0.1.0

ClawShire CLI for notice query, annual report query, and annual analysis

ClawShire CLI

独立可安装的 ClawShire 命令行客户端。

Hello World

要求：Python >= 3.12

推荐先用 uv 创建一个独立环境，避免污染本地其他 Python 环境：

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 注册/登录
2. 在控制台创建 API Key
3. 执行下面几条命令

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

如果想马上试一个需要认证的能力：

clawshire annual-report latest --year 2025 --keyword 平安银行

安装与升级

推荐使用 Python 3.12 或 Python 3.13。

pip install clawshire-cli

或使用 uv（推荐）：

uv tool install clawshire-cli

本地开发从源码安装：

uv tool install ./clawshire-cli

安装后可使用两个命令入口：

clawshire --help
cs --help

升级到最新版本：

clawshire update
clawshire upgrade

如果想先看将执行什么命令：

clawshire update --dry-run
clawshire --output json update --dry-run

如果想跳过确认提示：

clawshire update -y

说明：

• update 会优先检查 PyPI 上的最新版本，再决定是否执行升级
• update 适合通过 uv tool、pipx、pip 安装的场景
• upgrade 是 update 的等价别名
• 如果你当前是在源码目录里开发，优先继续使用你原来的开发安装方式

SDK Quick Start

clawshire-cli 同时包含 Python SDK，安装 CLI 后即可直接在代码中使用：

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 用法见：

docs/sdk-usage.md

Skills

clawshire-cli 仓库同时维护配套 Skills，目录位于：

skills/

当前已提供：

1. clawshire-shared
2. clawshire-data-query
3. clawshire-annual-report
4. clawshire-annual-analysis

这些 Skills 的定位不是重复实现底层请求，而是复用 clawshire CLI，把公告查询、年报定位、年报分析等能力组织成更适合 Agent 调用的工作流。

推荐按整个仓库安装 skills bundle，而不是单独安装某个 skill 子目录。

示意安装方式：

npx skills add <owner>/clawshire-cli -y -g

这意味着：

• skills/ 下的多个 Skill 会一起分发
• clawshire-shared 可以作为共享规则层存在
• 不需要假设用户只安装单个 skill 子目录

Testing

本地完整用户流程测试说明见：

docs/local-e2e.md

Python SDK 使用说明见：

docs/sdk-usage.md

一键检查脚本：

./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。

如果你只想快速确认安装成功，先跑：

clawshire --help
clawshire auth --help
clawshire update --dry-run
clawshire user info --api-key <your_api_key>

3 分钟上手

把下面几条命令直接复制执行即可：

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

如果你要查公告或年报，再继续：

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 并注册/登录你的 ClawShire 账号
2. 进入平台控制台中的 API Key 页面创建一个新 Key
3. 复制创建后的 Key，并立即保存到安全位置
4. 回到终端执行：

clawshire auth set-key <your_api_key>

如果你只想临时使用，也可以不落盘，直接通过环境变量传入：

export CLAWSHIRE_API_KEY="<your_api_key>"

先配置 API Key

建议先把 API Key 保存到本地，这样后续不用每次手动加 --api-key。

clawshire auth set-key <your_api_key>
clawshire auth show
clawshire auth status
clawshire auth check
clawshire user info

如果想临时覆盖本地配置，也可以直接传：

clawshire --api-key <your_api_key> user info

清除本地保存的 Key：

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

按命令分组查看帮助：

clawshire auth --help
clawshire update --help
clawshire user --help
clawshire notice --help
clawshire annual-report --help
clawshire annual-analysis --help

示例

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 示例：

https://static.cninfo.com.cn/finalpage/2026-04-20/1225116956.PDF

推荐直接试：

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

如果你更习惯环境变量，可直接这样配置：

export CLAWSHIRE_API_KEY=<your_api_key>
clawshire user info

最常用命令

查询用户信息：

clawshire user info

查询公告：

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>

查询年报：

clawshire annual-report latest --year 2025 --keyword 平安银行
clawshire annual-report data <met_uuid>

发起年报分析：

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

查询分析任务：

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

处理：

clawshire auth show
clawshire auth status
clawshire auth clear-key
clawshire auth set-key <your_api_key>
clawshire user info

如果你使用环境变量，也检查：

echo $CLAWSHIRE_API_KEY

2. 配置错误: 该命令需要 API Key

原因：

1. 你在调用需要认证的命令，但还没有配置 Key

处理：

clawshire auth set-key <your_api_key>
clawshire auth status
clawshire user info

或者临时传参：

clawshire --api-key <your_api_key> user info

3. unrecognized arguments: --output json

原因：

1. 把全局参数写在了子命令后面

错误示例：

clawshire notice search --start-date 2026-04-19 --end-date 2026-04-20 --keyword 603402 --output json

正确写法：

clawshire --output json notice search --start-date 2026-04-19 --end-date 2026-04-20 --keyword 603402

4. 未找到与 XXX 匹配的年报

原因：

1. 公司代码或简称不匹配
2. 指定年份没有收录对应年报
3. 交易所筛选过窄

处理：

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

示例：

clawshire annual-analysis get 123
clawshire annual-analysis get job_xxx

发布流程

版本更新

1. 修改 pyproject.toml 中的 version
2. 如有命令变化，同步更新本 README 与根目录 README.md

本地构建

cd clawshire-cli
uv build

构建产物位于：

clawshire-cli/dist/

本地安装验证

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，再补一轮：

cd clawshire-cli
pipx install .
clawshire --help

发布测试版

建议先发测试版，再发正式版，例如：

1. 0.1.0a1
2. 0.1.0b1
3. 0.1.0rc1

发布命令示例：

cd clawshire-cli
uv build
uv publish

如果要发到 TestPyPI：

cd clawshire-cli
uv build
uv publish --publish-url https://test.pypi.org/legacy/

安装验证：

pip install clawshire-cli
clawshire --help
cs --help