上市公司定期报告下载（多市场）

一键批量下载 A股（沪深北/北交所/B股）、港股、美股 的定期报告（年报 / 半年报 / 一季报 / 三季报），并按 代码/年份/类型 结构本地归档。

核心卖点：零第三方依赖 + 全免费无 key。

A股/北交/B股 → 巨潮资讯 CNINFO 公开接口（免费无 key）
港股 → 东方财富公告接口（免费无 key，可历史回溯多年，优于港交所仅 30 天）
美股 → SEC EDGAR 官方接口（免费无 key，10-K/10-Q/20-F）

ℹ️ 新三板（NEEQ）已明确不支持：东方财富不含三板公告、股转官网(neeq.com.cn)有 WAF 拦截（脚本请求一律返回空），唯一稳定源 CNINFO 深证信 webapi 需免费注册 Key。经用户确认放弃接入，本 skill 不做三板。

何时使用

用户要下载 A股 / 港股 / 美股的年报、半年报、季报等定期报告
用户要批量把上市公司定期报告保存到本地归档
用户要从巨潮 / 东方财富 / SEC 抓取财报 PDF（或美股 HTML iXBRL）

核心工作流

1. 定位脚本

scripts/cninfo_dl.py —— 唯一主下载器（覆盖全部市场）。其余为验证/探测辅助脚本。

2. 确认下载位置（必做）

运行前先确认保存目录，通过 --out 指定：

用户明确说了目录 → 传 --out D:/年报
用户没说 → 主动询问，否则用默认 --out ./output 并告知最终路径

文件按 股票代码/年份/报告类型/xxx 结构归档在该目录下。

3. 运行下载器

零第三方依赖：仅需 Python 3.6+（建议 3.8+）标准库（urllib/json/argparse），无需 pip install。Windows / macOS / Linux 通用。

# A股（沪深北/北交/B股，默认市场）
python scripts/cninfo_dl.py --stock 600519 --years 2024
python scripts/cninfo_dl.py --stock 600519 --years 2024 --category annual
python scripts/cninfo_dl.py --stock 900948 --years 2024 --category annual   # 沪B
python scripts/cninfo_dl.py --stock 200725 --years 2024 --category annual   # 深B
python scripts/cninfo_dl.py --stock 920185 --years 2024 --category annual   # 北交所

# 港股（东方财富，可历史回溯）
python scripts/cninfo_dl.py --market hk --stock 00700 --years 2024 --category annual
python scripts/cninfo_dl.py --market hk --stock 00700 --years 2023 2024 --category semi

# 美股（SEC EDGAR，HTML iXBRL 存为 .htm）
python scripts/cninfo_dl.py --market us --stock AAPL --years 2024 --category annual
python scripts/cninfo_dl.py --market us --stock TSM --years 2024 --category annual   # 20-F(台积电)

# 先看量级不下载
python scripts/cninfo_dl.py --stock 600519 --years 2024 --dry-run --show

4. 参数速查

| 参数 | 说明 | |---|---| | --stock | 股票代码：A股600519 / 港股00700 / 美股AAPL（美股用 ticker） | | --market | a=沪深北A股/北交/B股(默认) · hk=港股(东方财富) · us=美股(SEC EDGAR) | | --category | annual年报 · semi半年报 · q1一季报 · q3三季报；不填=全部四类 | | --years | 会计年度，如 2024 2023 | | --dry-run | 只列出不下载（所有市场均支持，已修复 A股此前缺失） | | --show | 显示每条进度 | | --out | 保存目录（默认当前目录下 output/） |

5. 归档结构

output/
├── 600519/2024/annual/600519_贵州茅台_贵州茅台2024年年度报告.PDF
├── 00700/2024/annual/00700_2024_2024 年报.PDF
├── AAPL/2024/annual/AAPL_AAPL_10-K_2024-11-01.htm
└── 900948/2024/annual/900948_伊泰Ｂ股_...2024年年度报告.PDF

6. 运行行为

限速：请求间隔 1.2s，失败自动重试 3 次
幂等：已存在且 >10KB 的文件自动跳过（支持断点续跑、重复执行安全）
完整性：A股/港股下载后校验 PDF 头 %PDF- 与大小；美股为 HTML iXBRL，不做 PDF 校验，按原文档扩展名（多为 .htm）保存
跨年过滤：按标题/披露年份匹配，混入其它年度记录自动跳过（notyear）

各市场接口与边界（2026-08 实测）

| 市场 | 数据源 | 是否需要 key | 历史回溯 | 文件格式 | 备注 | |---|---|---|---|---|---| | A股/北交/B股 | 巨潮 CNINFO hisAnnouncement/query | 否 | 多年 | PDF | orgId 取自 all_stock.json（含 A股+B股）；北交所旧码→新码映射 | | 港股 | 东方财富 np-anotice-stock (ann_type=H) | 否 | 多年 | PDF | 列表 GET；内容取 np-cnotice 的 attach_url→pdf.dfcfw.com | | 美股 | SEC EDGAR submissions/CIK{x}.json | 否 | 多年 | HTML(iXBRL) | 需简单 UA（SEC 拒类浏览器 UA）；10-K/10-Q/20-F | | 新三板 | — | 需免费 Key | — | — | 已放弃支持（用户确认不做） |

港股注意：年度报告标题里是财年（如「2024 年报」），归档按财年归类；列表按披露日期降序翻页，遇到早于请求最小年份即停止。

美股注意：--years 按 filingDate 的年份过滤；外国发行人（如台积电 TSM）年报为 20-F，已包含在 annual 内。

环境与兼容性

零第三方依赖：仅 Python 标准库，python --version 可用即可运行。
网络：需可访问 cninfo.com.cn / static.cninfo.com.cn（A股）、eastmoney.com / pdf.dfcfw.com（港股）、sec.gov（美股）。境内网络一般无碍；受限/境外网络可能超时或 403。
常见失败排查：① 返回空列表 → 接口限流，稍后重试；② 403 → 检查网络/UA；③ 中文乱码 → 终端非 UTF-8，脚本已内置兼容，不影响落盘。

量级参考

| 口径 | 数量级 | 估算耗时 | |---|---|---| | 单股单年全类型 | ~4-12 份 | ~1 分钟 | | 单股多年历史回溯 | 数十份 | 数分钟 |

全量前务必 --dry-run 评估规模。

目录结构

scripts/cninfo_dl.py — 主下载器（A股/港股/美股，4 类定期报告，限速/重试/幂等/归档）
scripts/verify.py — 一键自检（各市场连通性 + 真实下载样例）
references/api.md — 各市场接口完整参考

新三板（NEEQ）说明（已放弃）

经用户确认，本 skill 不做新三板。原因：东方财富不含三板公告、股转官网 neeq.com.cn 有 WAF（脚本请求一律拦截），唯一稳定源 CNINFO 深证信 webapi 需注册 Key，成本不匹配。如需三板请另寻工具。