| name | cninfo |
| description | 巨潮资讯网(cninfo.com.cn)A 股法定披露公告数据契约 — 年报/季报/中报/三季报/临时公告 PDF + PyMuPDF 全文 Markdown。真实抓取逻辑由独立开源工具 use_cninfo 实现,本仓库通过 data_sources/cninfo.py 适配 CLI 输出。 |
| owner_group | 开发3组(数据) |
| domain | data |
| status | draft |
巨潮资讯网公告数据契约 Skill
1. 适用范围
所属小组:开发3组(数据)
适用任务:
- 描述从巨潮资讯网(cninfo.com.cn)获取 A 股上市公司法定披露公告所需的数据契约
- 提供两类查询能力:(a) 单股指定财年的定期报告本体(年报/一季报/中报/三季报);(b) 单股时间窗的全部公告列表
- 输出包含 PDF 直链路径 + PyMuPDF 提取的 Markdown 全文,供财务分析/事件追踪/舆情前置等 Skill 消费
- 适合 A 股全市场(沪/深/创业板/科创板/北交所),回溯历史可至 2021 年
边界说明:
- 本 Skill 只描述数据契约,真实抓取逻辑在外部独立开源工具
use_cninfo
- 适配薄包装位于
data_sources/cninfo.py(CninfoDataSource),内部 subprocess 调 cninfo CLI 并解析 JSON
- 数据源是法定披露平台,不存在"代表性偏差",但 cninfo 接口
pageSize 服务端硬限 30,长时间窗会触发翻页,建议每次窗口 ≤ 1 个月
- 部分 PDF 是扫描件(主要是会计师审计意见 / 内控鉴证),
extracted_pages=0 时 md 正文为空,本 Skill 不内置 OCR
- 同一份报告可能有 2 条记录(announcementId 不同 PDF 内容相同),需在调用方按
(stock_code, ann_date, title) 去重
- 二次访问命中本地缓存(
~/.cache/cninfo/,可被 $CNINFO_CACHE_DIR 覆盖),秒级返回不发网络
2. 执行数据源
真实数据获取逻辑位于:
data_sources/cninfo.py # 薄 shim,subprocess 调 use_cninfo CLI
推荐调用方式:
from data_sources import CninfoDataSource
source = CninfoDataSource()
r = source.get_periodic_report(stock_code="600519", year=2024, kind="annual")
r = source.get_announcements(stock_code="600519", since="2025-04-01", until="2025-04-30")
r = source.get_announcements(
stock_code="600519", since="2025-04-01", until="2025-04-30", download=True,
)
前置依赖(用户在 Agent 运行环境装好):
git clone https://github.com/rollysys/use_cninfo.git
cd use_cninfo && pip install -e .
git clone https://github.com/rollysys/announcement_filter.git
cd announcement_filter && pip install -e .
cninfo 命令需要在 PATH 中(pip install -e . 自动配置)。CninfoDataSource 初始化时若未找到 CLI 会输出 warning,所有方法返回 status: error 并在 error 字段提示安装命令。
3. 输入参数
get_periodic_report(stock_code, year, kind, force=False)
必填参数
| 参数 | 类型 | 说明 | 示例 |
|---|
| stock_code | string | 6 位股票代码(无后缀) | "600519" |
| year | int | 报告所属财年 | 2024 |
| kind | string | 报告类型:annual / q1 / h1 / q3 | "annual" |
可选参数
| 参数 | 类型 | 默认值 | 说明 |
|---|
| force | bool | False | 忽略本地缓存重新下载并重新解析 |
get_announcements(stock_code, since, until, download=False)
必填参数
| 参数 | 类型 | 说明 | 示例 |
|---|
| stock_code | string | 6 位股票代码 | "600519" |
| since | string | 起始日期 YYYY-MM-DD | "2025-04-01" |
| until | string | 截止日期 YYYY-MM-DD | "2025-04-30" |
可选参数
| 参数 | 类型 | 默认值 | 说明 |
|---|
| download | bool | False | True 时下载并 PyMuPDF 解析每份 PDF |
4. 输出格式
get_periodic_report 成功
{
"status": "success",
"stock_code": "600519",
"fetch_time": "2026-05-04T17:30:00",
"report": {
"ann_id": "1222993920",
"sec_code": "600519",
"ts_code": "600519.SH",
"ann_date": "20250403",
"title": "贵州茅台2024年年度报告",
"category": "01010503||010113||010301",
"pdf_url": "http://static.cninfo.com.cn/finalpage/2025-04-03/1222993920.PDF",
"pdf_path": "/Users/x/.cache/cninfo/pdf/600519.SH/20250403__1222993920.pdf",
"md_path": "/Users/x/.cache/cninfo/md/600519.SH/20250403__1222993920.md",
"meta_path": "/Users/x/.cache/cninfo/meta/1222993920.json",
"total_pages": 143,
"extracted_pages": 143,
"text_chars": 176373,
"cache_hit": false
}
}
md_path 指向的文件含 YAML frontmatter(ann_id / ts_code / sec_code / sec_name / ann_date / title / category / source / total_pages / extracted_pages / text_chars)+ PyMuPDF 提取的全文 Markdown,直接可读。
get_announcements 成功
{
"status": "success",
"stock_code": "600519",
"since": "2025-04-01",
"until": "2025-04-30",
"fetch_time": "2026-05-04T17:30:00",
"total": 18,
"announcements": [
{
"ann_id": "1222993920",
"sec_code": "600519",
"ann_date": "20250403",
"title": "贵州茅台2024年年度报告",
"adjunct_size_kb": 3542
}
]
}
download=True 时每条 announcement 额外含 cache_hit / md_path / pages / text_chars 字段。
失败
{
"status": "error",
"stock_code": "600519",
"error": "..."
}
常见 error:
`cninfo` 命令未安装。装一下: ...cninfo CLI 超时 (120s)OrgIdNotFound: orgId not found for sec_code=XXX(代码错 / 已退市 / cninfo 接口变)no annual report body found for ... year=YYYY(报告期窗口外 / 只有摘要无本体)
5. 数据边界
法定属性:cninfo 是中国证监会指定的 A 股法定信息披露平台,所有上市公司必须在此披露,无遗漏风险。
频次限制:
- cninfo 接口
pageSize 服务端硬限 30,长时间窗会自动翻页(本工具内部已处理)
- 单页响应 ~0.2-0.3s,建议调用方控制窗口长度避免超时
- 5 次/秒连发实测无限流,但持续大批量建议加 sleep,详见上游
docs/gotchas.md
缓存语义:
- 默认本地长期缓存(
~/.cache/cninfo/),pdf + md + meta 三件齐全才算命中
force=True 跳过缓存重新下载cninfo cache prune --older-than 365d 可手动清理(本契约未暴露,直接命令行)
已知陷阱(继承自上游):
- 同一公告可能有 2 条记录,需调用方去重
- 部分 2024-06 前的老 PDF URL 可能 404,失败重试 3 次后跳过
- 部分 PDF 是扫描件,
extracted_pages=0,md 正文为空但 PDF 已落盘
完整陷阱清单见 use_cninfo/docs/gotchas.md。
6. 调用示例
from data_sources import CninfoDataSource
source = CninfoDataSource()
r = source.get_periodic_report("600519", 2024, "annual")
if r["status"] == "success":
md_path = r["report"]["md_path"]
with open(md_path, encoding="utf-8") as f:
annual_report_text = f.read()
from datetime import date, timedelta
today = date.today()
r = source.get_announcements(
"600519",
since=(today - timedelta(days=30)).isoformat(),
until=today.isoformat(),
)
titles = [a["title"] for a in r["announcements"]]
r = source.get_announcements(
"600519", since="2025-04-01", until="2025-04-30", download=True,
)
7. 与已有数据源的关系
| 已有 | 数据 | cninfo 与之关系 |
|---|
EastMoneyDataSource | 三大表结构化数据(资产负债/利润/现金流) | 互补。东方财富给数字,cninfo 给原文。年报正文里有"管理层讨论与分析 / 关键审计事项 / 重大合同"等结构化字段无法替代的内容 |
EastMoneyGubaDataSource | 散户帖子(舆情) | 互补。cninfo 是机构口径(法定披露),股吧是散户口径(情绪) |
cninfo 的典型消费方:
- 财务分析 Agent:直接读年报"管理层讨论与分析"段对账三大表
- 事件追踪 Agent:监听单股近 30 天公告标题,识别减持/重组/关联交易等事件
- 舆情前置 Agent:用 cninfo 公告作为"事实锚",再去股吧看散户对该事件的反应
