| name | clawshire-data-query |
| description | ClawShire 公告数据查询技能 - A 股上市公司公告提取结果查询，支持按日期范围、证券代码、公告原文链接检索结构化提取数据 |
ClawShire 公告数据查询技能
A 股上市公司公告提取结果查询服务。支持按日期范围、证券代码、公告原文链接检索结构化提取数据。
服务地址： https://api.clawshire.cn
前置检查
在执行任何 API 调用前，必须检查 CLAWSHIRE_API_KEY 环境变量是否存在。
- 只判断是否存在，不得在输出中明文显示 key 内容
- 若不存在，引导用户注册获取：
https://clawshire.cn/api-docs
认证方式
若接口需要认证，所有请求头携带：
Authorization: Bearer $CLAWSHIRE_API_KEY
公告查询接口（/api/v1/announcements、/api/v1/stock/{sec_code}/announcements、/api/v1/met_link）无需认证即可调用。
工作流
工作流 1：按日期查询公告
适用场景：用户想获取某天或某段时间内的所有公告提取结果。
步骤：
- 确认日期范围（
start_date、end_date，格式 YYYY-MM-DD）
- 可选：用户是否指定公告类别（
infotype，如 董事会决议）
- 调用
GET /api/v1/announcements
- 展示结果：公告总数、公司名、公告类型、日期、结构化提取内容
默认行为：
- 未指定数量时，默认展示前 20 条（
page_size=20）
- 结果包含
extracted_info 字段时，完整展示提取内容
工作流 2：按证券代码查询公告
适用场景：用户关注特定上市公司的公告。
步骤：
- 确认证券代码（6 位数字，如
000001）
- 可选：日期范围（默认当天）、公告类别筛选
- 调用
GET /api/v1/stock/{sec_code}/announcements
- 展示该公司的公告列表及提取结果
工作流 3：按公告链接查询
适用场景：用户有公告原文链接，想获取结构化提取结果。
步骤：
- 获取用户提供的公告原文链接（
met_link）
- 调用
GET /api/v1/met_link?met_link=<url_encoded_link>
- 展示该公告的完整提取结果
工作流 4：获取 API Key
适用场景：用户需要获取 API Key。
步骤：
- 引导用户登录控制台：
https://clawshire.cn
- 在控制台完成登录认证后，手动创建 API Key
- 将控制台生成的
api_key 设置为环境变量：
export CLAWSHIRE_API_KEY="sk-xxxxxxxx"
API Key 必须在控制台登录后手动创建，不支持通过 API 接口注册或获取。
结果展示规范
每条公告结果必须包含：
- 公司：
{sec_name}（{sec_code}）
- 类型：
infotype
- 日期：
doc_date
- 原文链接：
met_link
- 提取内容：
extracted_info 的完整 JSON（若存在）
调用限制
- 免费账户：每个 API Key 共 100 次调用额度，请合理规划使用
- 每次查询日期范围建议不超过 30 天，避免结果过多
page_size 最大 100，超出需分页获取- 若用户未指定数量，默认
page_size=20
- 建议优先用宽日期范围 + 类别筛选一次性取完，减少不必要的翻页请求
错误处理
| 错误码 | 含义 | 处理方式 |
|---|
| 400 | 参数错误 | 检查日期格式（YYYY-MM-DD）和必填字段 |
| 401 | API Key 无效 | 提示用户检查 CLAWSHIRE_API_KEY 环境变量 |
| 404 | 资源不存在 | 确认证券代码或链接是否正确 |
| 500 | 服务器错误 | 稍后重试，或访问 https://clawshire.cn 查看服务状态 |
