CNInfo Report Downloader（巨潮资讯报告下载）

批量下载 A 股上市公司年报/半年报 PDF（数据源：巨潮资讯 cninfo.com.cn）。

何时启用

• 用户希望下载 A 股上市公司年报或半年报
• 用户提及“巨潮”、“cninfo”、“年报下载”、“半年报”、“annual report”
• 用户需根据股票代码列表批量获取报告 PDF

前置条件

pip install -r requirements.txt

工作流程

1. 确认存在股票 CSV 文件，且其第一列为股票代码（6 位 A 股代码）。
2. 若不确定匹配结果，可先运行 --dry-run 预览匹配项，不执行实际下载。
3. 在该技能（skill）目录下执行命令。脚本使用 SQLite 追踪进度，支持中断后恢复。
4. 运行完成后，检查 runtime/manifest_.csv 和 runtime/logs/cninfo_.log。
5. 仅当需要调整标题匹配逻辑、文件命名规则或重置行为时，才参考 references/filter_rules.md。

命令

常规下载（默认年份为 2025）：

python scripts/run_cninfo_reports.py --stock-csv 

预览模式（仅显示匹配结果，不下载）：

python scripts/run_cninfo_reports.py --stock-csv  --dry-run

指定年份：

python scripts/run_cninfo_reports.py --stock-csv  --year 2024

强制重新下载（忽略缓存）：

python scripts/run_cninfo_reports.py --stock-csv  --force-redownload

完整 CLI 参数列表：

特性

• 智能标题过滤 — 基于正则表达式匹配正式的年报/半年报；自动排除摘要、英文版本、ESG 报告、通知等非目标文档。
• 断点续传 — 使用 SQLite 记录每条公告的搜索进度与下载状态，支持中断后恢复执行。
• 清单输出 — 生成 runtime/manifest_.csv，包含所有匹配报告的完整元数据。
• 幂等命名 — 主文件命名为 {code}_{year}_{kind}.pdf；同一股票存在多个匹配项时，额外变体追加 _{announcement_id} 后缀。

架构

scripts/
  run_cninfo_reports.py          # 入口脚本
  cninfo_annual_reports/
    cli.py                       # 参数解析与日志配置
    config.py                    # AppConfig 数据类定义
    service.py                   # 核心编排逻辑
    repository.py                # SQLite 状态管理
    http_client.py               # CNInfo API 调用与文件下载
    models.py                    # 数据模型定义
    filters.py                   # 标题评估与正则匹配逻辑
references/
  filter_rules.md                # 详细的过滤器与重置说明文档
agents/
  openai.yaml                    # Codex 集成配置

重置

如需从头开始重新运行，请删除状态文件：

rm runtime/state.db runtime/state.db-wal runtime/state.db-shm