财报下载 — 巨潮资讯报告下载技能

目的

通过巨潮资讯网公告搜索 API + 浏览器自动化 + 直链下载，自动发现并下载A股（沪市/深市）和港股上市公司的年度报告、季度报告 PDF，无需手动查找 announcementId。

触发条件

当用户请求以下任一操作时触发：

• 下载XX公司年报/季报/财报
• 下载某只股票特定年份的报告
• 批量下载多家公司的财报
• "帮我下载XX公司2020-2025年报"
• 支持A股（沪/深/北交所）和港股

交易所路由

核心工作流

A股(沪/深) + 港股：巨潮资讯四步法

① API搜索公告 → ② 提取announcementId → ③ 浏览器获取PDF直链 → ④ requests下载PDF

北交所：东方财富两步法

① 搜索公告(art_code) → ② 直接下载PDF(pdf.dfcfw.com)

详见 references/api_params.md 末尾的北交所替代方案。

第一步：通过 API 搜索公告

调用巨潮资讯公告搜索接口获取 announcementId：

POST https://www.cninfo.com.cn/new/hisAnnouncement/query
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

必填参数：

搜索策略（按情况选择）：

1. 关键词搜索（A股优先）：stock=""，searchkey="{公司名} 年报"，在结果中过滤 secCode
2. stock参数搜索（港股必需）：stock="{代码},{orgId}"，searchkey="年报"（港股不能用 category）
3. category精确搜索（A股备选）：category="category_ndbg_szsh"
4. 北交所：直接用东方财富API搜索，不走巨潮

> 详见 references/api_params.md

⚠️ A股搜索陷阱： 很多深市/科创板股票用 stock 参数+标准 orgId 格式返回0结果，必须改用公司名模糊搜索。orgId 格式也有多种：纯数字(99000xxx)、GD100xxx、nssc1000xxx 等。

⚠️ "提示性公告"陷阱： 搜索"年度报告"时可能先匹配到"2025年年度报告披露的提示性公告"——这是通知不是年报本身！需排除"提示性"/"提示"关键词，找到真正的年报公告。

获取 announcementId：从响应 JSON 中提取 announcements[].announcementId

⚡ 捷径：adjunctUrl 直连

当使用 stock 参数（非空）进行精确搜索时，API 响应中可能包含 adjunctUrl 字段（如 finalpage/2026-04-30/1225258793.PDF）。此时可直接拼接 PDF 直链，跳过 agent-browser：

https://static.cninfo.com.cn/{adjunctUrl}

优先检查 adjunctUrl，有则直连下载；无则走下面的 agent-browser 流程。

第二步：通过浏览器获取 PDF 直链

巨潮资讯公告详情页是 JS 动态渲染的，PDF 链接在 标签中。

使用 agent-browser 获取 PDF 直链：

# 1. 打开详情页
agent-browser open "https://www.cninfo.com.cn/new/disclosure/detail?plate={exchange}&orgId={orgId}&stockCode={code}&announcementId={annId}"

# 2. 等页面加载（⚠️ 巨潮页面用 networkidle 会卡死，改用 load 或直接 sleep 1.5秒）
agent-browser wait --load load

# 3. 提取 PDF 直链
agent-browser eval "document.querySelector('embed')?.src"

PDF 地址格式：https://static.cninfo.com.cn/finalpage/{日期}/{announcementId}.PDF

> ⚠️ 域名是 static.cninfo.com.cn，不是 www.cninfo.com.cn

第三步：直接下载 PDF

import requests

headers = {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    'Referer': 'https://www.cninfo.com.cn/',
}

resp = requests.get(pdf_url, headers=headers, timeout=120, stream=True)
resp.raise_for_status()

with open(output_path, 'wb') as f:
    for chunk in resp.iter_content(8192):
        f.write(chunk)

环境依赖

必需

可选

安装命令

# Python 依赖
pip install requests

# agent-browser（巨潮PDF提取必需）
npm install -g agent-browser
agent-browser install

# 可选：Playwright 兜底
pip install playwright
playwright install chromium

技能文件

~/.workbuddy/skills/财报下载/
├── SKILL.md                          # 本文件
└── references/
    └── api_params.md                 # API参数详细参考

关联代码模块

技能依赖以下 Python 模块（需放在同一项目目录下）：

输出目录规范

默认输出位置

{项目目录}/cninfo_reports/{股票代码}_{公司名}/

例如：cninfo_reports/600519_贵州茅台/2025年报.pdf

文件命名

自定义输出目录

# 巨潮下载器
from cninfo_downloader import CninfoReportDownloader
dl = CninfoReportDownloader(output_dir="/your/path/cninfo_reports")

# 东方财富下载器
from annual_report_downloader import AnnualReportDownloader
dl = AnnualReportDownloader(output_dir="/your/path/cninfo_reports")

两个下载器默认都输出到 cninfo_reports/，可通过 output_dir 参数自定义。

注意事项

• ⚠️ orgId 格式是关键：深市前缀是 gssz 不是 gszs；部分A股/港股orgId为非标准格式（纯数字/GD/nssc前缀）
• ⚠️ 港股特殊处理：不能用 category 过滤，必须用 searchkey；orgId可能为纯数字
• ⚠️ 北交所不支持巨潮：必须走东方财富API，两步即可（搜索→直链下载，无需浏览器）
• ⚠️ 年报发布年份：2020年年报可能在2021年4月发布，搜索日期范围要扩大
• ⚠️ PDF 直链域名：巨潮用 static.cninfo.com.cn，东方财富用 pdf.dfcfw.com
• ⚠️ 搜索结果过滤：排除"提示性公告"、"持续督导"、"摘要"、"修订"、"更正"、"英文"等
• ⚠️ 季报分类：搜索"年报"时也可能返回季报，需按标题精确分类
• ⚠️ agent-browser：巨潮页面 wait --load networkidle 会卡死，改用 --load load 或直接 sleep 1.5秒

参考文档

• references/api_params.md — 完整 API 参数、orgId 格式、交易所代码对照表