巨潮上市公司公告下载【谷山行 出品】

概述

用途

把巨潮资讯网某只股票的全部历史公告下载到本地（PDF 或 HTML），支持增量更新（只下载上次之后的新公告）。适用于量化研究本地存档、基本面公告归档、催化剂信号采集等场景。

也支持 ima 知识库模式（--dest ima）：本机不落公告文件，脚本只导出入库工作清单，由 agent 走 create_media → COS 上传 → add_knowledge 三步入库（字节可经内存直传 COS，不写磁盘）。

何时使用

• 用户给出股票代码（如 601225）或巨潮披露页 URL，要求「下载公告 / 拉公告 / 存档公告」
• 用户要求「更新公告到最新 / 增量更新公告」
• 用户在做 A 股公告相关的数据采集（业绩预告、重大合同、分红方案等）

输入（target）支持的三种形式

1. 巨潮披露页 URL（最推荐）：https://www.cninfo.com.cn/new/disclosure/stock?stockCode=601225&orgId=9900023204 —— 脚本自动从 URL 解析 stockCode 与 orgId
2. 代码,orgId：601225,9900023204
3. 纯股票代码：601225 —— 脚本尝试解析 orgId；若公开接口不可用，会提示用户提供 URL 或 代码,orgId

orgId 无法从代码推算（如 601225 → 9900023204 无规律），因此首选传 URL；URL 中自带 orgId，100% 可靠。

<<<<<<< HEAD港股/北交所等也支持：stockCode 允许 4–6 位，orgId 允许字母+数字（如腾讯控股 stockCode=00700&orgId=gshk0000700）。URL 与 代码,orgId 两种形式均可用，例如 00700,gshk0000700。注意 orgId 必须带正确的字母前缀（纯数字 orgId 对港股无效）。

=======

cf57cebe4feec39918b28437faa3e78c74e051ea

用法

调用 bundled 脚本 scripts/download.py：

# 全量下载（默认）
python scripts/download.py "https://www.cninfo.com.cn/new/disclosure/stock?stockCode=601225&orgId=9900023204"

# 增量更新到最新（依赖 state 记录的上次位置）
python scripts/download.py 601225,9900023204 --mode update

# 只取最近 5 条（测试 / 只想看最新公告）
python scripts/download.py 601225,9900023204 --max 5

# 指定输出目录与并发数
python scripts/download.py 601225,9900023204 --out /data/ann/601225 --workers 6

参数：

• target（必填）：上述三种形式之一
• --mode：download（全量，默认）| update（增量）
• --out：输出目录，默认 ./cninfo_<code>_announcements（update 模式会复用 state 中记录的目录）
• --max N：最多下载 N 条（默认无限制，全量）
• --workers N：下载并发数（默认 8）

ima 知识库模式（公告文件不落本机）

# 1) 导出入库工作清单（不下载正文；简版 TXT / 无附件公告自动跳过，只导 PDF）
python scripts/download.py "https://www.cninfo.com.cn/new/disclosure/stock?stockCode=601225&orgId=9900023204" 
    --dest ima --kb 7479076377872578

# 2) agent 按清单逐条执行三步入库（见下方编排规则）
# 3) 每条入库成功后回写 state，保证增量绝不重复
python scripts/download.py 601225,9900023204 --mark-imported 1225604932 1225596167

ima 模式参数：

• --dest ima：切换为知识库模式（默认 local 行为不变）
• --kb：目标知识库 ID（必填，来自 ima-mcp「可添加知识库」列表，禁止凭库名猜 ID）
• --folder：ima 文件夹 ID，空为根目录（ima MCP 无建夹工具，只能导到已存在文件夹或根目录）
• --mark-imported ID...：agent 入库成功后把公告 ID 记入 state 的 ima_imported_ids
• 产物：<out>/ima_worklist.json（每条 id/date/title/url/filename），默认 ./cninfo_<code>_ima_urls/
• --mode update 的增量判定改用 ima_imported_ids（不是本地文件）

路线结论（2026-10-15 在「上市公司财报」库实测，勿再重复试探）

ima 模式编排规则（agent 必守）

1. 两段式：脚本只出工作清单，入库必须由 agent 调 MCP 完成——Python 脚本无法直调 ima 接口。
2. 三条路缺一不可：create_media（拿 media_id + COS 上传凭证）→ 把文件字节上传到 COS → add_knowledge(media_id)。只创建 media 而未完成后续步骤 = 未入库，不得向用户报告成功。上传用 bundled 脚本 scripts/ima_upload.py（从巨潮直读字节进内存、直传 COS，不落磁盘）：

   # job JSON 从 stdin 或文件读入：items=[{media_id, url, cos_credential}]
   python scripts/ima_upload.py < job.json

依赖 cos-python-sdk-v5（装在 WorkBuddy 托管 venv）。凭证是 create_media 返回的长字符串，经 stdin/临时文件传递、用完即删；转写错误会报 InvalidAccessKeyId，重签一条即可（并行 create_media 时注意别把两条凭证配错）。

1. 字节不落盘：上传时从巨潮直读字节进内存再 PUT 到 COS，不写临时文件（用户明确要求公告文件不进本机）。
2. 去重靠 state：add_knowledge 的 duplicate_name_strategy 只是重名策略，重复入库仍产生重复条目；只导入清单中未标记部分，成功后立即 --mark-imported。
3. 写入选库：目标库由用户指定；多连接器时按 ima-mcp 技能规则先确认连接器再写。
4. 失败处置：单条失败重试一次；批量部分失败只重试失败项，不整批重提；仍失败把清单交给用户。
5. ima 无删除/改名/移动工具：误导入的空条目（如 import_urls 产物）只能引导用户在 ima 客户端手动删除，调用前务必确认路线正确。
6. 导入是异步解析：add_knowledge 后解析要时间，验证用列举（media_state=MEDIA_PARSE_SUCCESS）+ fetch_media_content 抽查正文。

工作原理（非显然要点，务必遵循）

1. 解析 target → (stockCode, orgId)。
2. 拉列表接口（关键坑）：
   • 接口：http://www.cninfo.com.cn/new/hisAnnouncement/query（POST）
   • 必填参数：column 必须留空（填 sse/shmb 或加 seDate 都会返回 0 条！）；stock 必须是 "代码,orgId"；tabName=latest
   • pageSize 必须为 30：设置 >30（如 50）时 pageNum 不推进（服务端截断，pn=1 与 pn=2 返回完全相同数据）。翻页 = pageSize=30 + pageNum 递增。
3. 下载每条公告：http://static.cninfo.com.cn/ + adjunctUrl
   • 返回 %PDF 头 → 存 .pdf
   • 返回 application/javascript（巨潮简版财务指标摘要，内容形如 var affiches=[{"Title":...,"Time":...,"Zw":...}]）→ 解析 Title/Time/Zw 存 .html
   • 返回 text/html（早期 XHTML 全文公告，约 2.8KB）→ 直接存 .html
4. 增量更新（update 模式）：读取 state 文件（<skill>/data/<code>.state.json）记录的上次最新公告 ID，从列表 newest→oldest 逐条检查，遇到已下载的 ID 即停止（列表按时间倒序，前面都是新的）；随后更新 state。这就是「知道上一次下载到哪个位置」。
5. 产物：
   • <out>/manifest_all.json：每条公告的 date / id / title / size / file / status（status ∈ ok / html / skip / fail）
   • <skill>/data/<code>.state.json：上次位置（last_id / last_date / out_dir 等），供下次 update 续传

注意事项

• 巨潮公告格式历史不统一：近期为 PDF，部分为 JS 摘要，早期为 XHTML 全文——脚本均已自动识别处理，无需人工判断。
• ima 模式已验证：static.cninfo.com.cn 静态文件不带 Referer 也可直接抓取（http/https 均 200），上传脚本可直读字节；但 ima 的 import_urls 抓取 PDF 直链后正文为空（详见「路线结论」），PDF 入库必须走 create_media 上传路线。.js 简版（adjunctType=TXT）ima 模式直接跳过。
• resolve_orgid() 当前返回 None（公开证券资料接口均已 404）；如需支持纯代码自动解析 orgId，可在该函数接入可用的证券资料接口。

示例

• 用户：「把陕西煤业的公告都下下来」→ 用其提供的披露页 URL 跑 download
• 用户：「601225 有新的公告吗？更新一下」→ 跑 update，只拉新公告
• 用户：「先下载最近 5 条看看」→ --max 5