stock-announcements

# A 股公告列表 / 公告正文下载 ## 1. 接口描述 | 项目 | 说明 | |------|------| | 接口名称 | A 股公告（stock_announcements / stock_announcements_download） | | 外部接口 | `GET /api/v2/market/data/announcements/stock-announcements`（列表）<br>`GET /api/v2/market/data/announcements/stock-announcements/{url_hash}`（正文 PDF） | | 请求方式 | GET（列表用 query 参数；下载为路径参数） | 同一个子 skill 两种模式： 1. **列表模式**（不带 `--url-hash`）：按标的或日期查公告列表。 2. **下载模式**（带 `--url-hash`）：下载该公告的正文 PDF 到本地。 必须提供 `--stock-code` 或 `--start-date`，`--type` 当前固定为 `stock`，列表模式下 `--page` 与 `--page-size` 必填。按日期范围查询时日期跨度最多 3 天。所有请求必须设置环境变量 `FTSHARE_API_KEY`；缺失凭据时不会发起请求。 ## 2. 请求参数 列表模式： | 参数名 | 类型 | 是否必填 | 描述 | 取值示例 | |--------|------|----------|------|----------| | stock_code | string | 二选一 | 股票代码 | 002142.XSHE | | start_date | string | 二选一 | 起始日期 | 20260908 | | end_date | string | 否 | 结束日期 | 20260908 | | type | string | 否 | 公告类型，固定 `stock` | stock | | page | int | 是 | 页码 | 1 | | page_size | int | 是 | 每页条数 | 5 | 下载模式： | 参数名 | 类型 | 是否必填 | 描述 | 取值示例 | 备注 | |--------|------|----------|------|----------|------| | --url-hash | string | 是 | 公告文件 URL 哈希 | d8d54544…cf574adf | 取自列表响应；传入即下载 | | --output | string | 否 | 落盘路径 | ./ann.pdf | 默认 `<url_hash>.pdf`；必须在当前工作目录内 | ## 3. 调用方式 ```bash # 列表 python <RUN_PY> stock-announcements --start-date 20260918 --end-date 20260918 --page 1 --page-size 5 # 下载正文 PDF（默认落到当前目录的 <url_hash>.pdf） python <RUN_PY> stock-announcements --url-hash d8d54544...cf574adf # 指定落盘路径 python <RUN_PY> stock-announcements --url-hash d8d54544...cf574adf --output ./ann.pdf ``` `<RUN_PY>` 为主 SKILL.md 同级 `run.py` 的绝对路径。列表模式输出 JSON；下载模式只向 stdout 输出落盘后的文件路径。 ## 4. 注意事项 - 下载用的 `url_hash` 须取自列表响应，勿硬编码。 - 下载过程中半成品写在 `<目标文件>.part`，成功后原子改名；失败会清理半成品。 - 落盘路径必须在当前工作目录及其子目录内，否则以非零状态退出。 - 下载失败（HTTP 错误、网络异常、响应地址跳出基础地址）以非零状态退出并清理半成品。