全能金融爬虫

概述

cn-financial-scraper v12.0.0 — 信息获取一键编排 + 交付包自证 + 登录态接管

全量机构名单（2334家/43大类） | 🆕 v12 8 类意图编排 / sha256 交付包 / 登录档案脱敏 | 110 MCP 工具 / 10 Resource / 14 Prompt | v11 实时数据中枢 + 24 指标引擎 + 证据融合 | 36种查询类型自动降级（akshare/东方财富/yfinance/RSS） | 60+ 商业财经媒体源 + RSS + akshare 兜底 | 智能多级爬取 + 网页内容识别 | 数据分析汇总 + 语音交互

⚡ 一键上手

直接对话即可触发，无需记忆命令：

帮我爬一下某上市公司最近7天的舆情
某基金公司最近3天的负面新闻，并导出 Excel
把这篇网页完整归档，包含图片和表格
搜索"贵州茅台2026半年报"然后把结果爬取下来
爬一下银行板块最近3天的舆情并导出 Word
我已经登录了雪球，用我的会话抓一下这个页面        🆕
这批公告 PDF 全部下载下来，给我一个能校验的交付包   🆕
先别真跑，把计划和数据源给我看一下再决定           🆕

一键启动（Windows 直接 python run_sentiment.py 或）：

python run_sentiment.py                          # 交互式对话
python run_sentiment.py "贵州茅台最近7天的舆情"     # 直接命令行

🧭 先试哪个（8 类意图 → 入口 → 你要手动衔接的地方）

gather_info() 是 v12 的唯一编排入口：路由 → 抓取 → 去占位 → 质量分 → 能力边界 → 回执 → 打包，一次调用跑完，plan 里每一步都标了真实状态（done/empty/skipped/failed）。拿不准问法属于哪一类时，先跑 list_info_intents(keyword="你的原话")，它直接回你路由结论与备选。

from scripts.pipeline_runner import gather_info, render_pipeline_markdown

plan = gather_info(topic="贵州茅台最近7天负面舆情", dry_run=True)      # 只看计划，不发请求
res  = gather_info(topic="贵州茅台最近7天负面舆情", days=7, package=True)  # 实跑 + 交付包
print(render_pipeline_markdown(res))   # 回执：来源/质量分/能答什么/缺口/下一步

三条诚实性保证（v12 起是硬行为，不是可选项）：

• 反爬产生的 [未能直接抓取] … 占位条目一律剔除并计入 meta.placeholders_dropped，

全部为空时直接报 E_SOURCE_EMPTY，不会把 15 条假数据判成 B 级成功；

• quality 给 A–D 分档并说明扣分项，样本 <10 条时 answer_ability.cannot_answer

会显式禁止比例/排名类结论；

• 登录探测没有稳定证据时返回 unknown + HTTP 诊断，不硬猜"已登录"。

🧭 场景速查（想做什么 → 直接入口）

无需记忆命令，按「想做什么」直接找到入口。完整 API 与 MCP 工具表见 [README.md](README.md)。

📚 文档导航（找什么 → 去哪里）

能力矩阵

依赖层级说明：核心 = 零 pip 依赖即可用 | 推荐 = --recommended 安装后可用（bs4/lxml/docx） | Playwright = 需额外 pip install playwright && playwright install chromium | akshare = 需额外 pip install akshare

⚠️ 能力边界（重要）

预期成功率：天天基金 95%+ / 东方财富 90%+ / 同花顺 85%+ / 基金公司官网 70-90% / 银行官网 30-50% / 反爬严格的网站 20-40%。

安装（三层依赖）

python setup_env.py                # 仅核心（零 pip 依赖，舆情/HTTP 可用）
python setup_env.py --recommended  # + bs4/lxml/docx/openpyxl（解析+导出）
python setup_env.py --full         # + scrapling/playwright/mcp/akshare（全功能）

🆕 v12.0.0 三条新线速查

1️⃣ 信息获取编排（scripts/pipeline_runner.py）

from scripts.pipeline_runner import (INTENTS, route, plan_for, gather_info,
                                     render_pipeline_markdown, quality_score,
                                     answer_ability, PIPELINE_ERRORS, self_check)
route("我已经登录了，用我的会话抓这一页")            # → intent=login_page，confidence=high
gather_info(topic="贵州茅台", days=7, dry_run=True)   # 只出计划与契约，不发请求
res = gather_info(topic="贵州茅台", days=7, analyze=True, fuse=True,
                  package=True, out_dir=r"D:out")    # 实跑 + 交付包
res["quality"]          # {'grade': 'B', 'score': 76.7, 'fill_rate': …, 'counts': …}
res["answer_ability"]   # can_answer / cannot_answer / confidence / why
render_pipeline_markdown(res)   # 回执：来源、发布时间、质量分、缺口、下一步

9 个错误码（PIPELINE_ERRORS）每个都带 cause + next_step：E_SOURCE_EMPTY、E_LOGIN_REQUIRED、E_ROUTE_NOT_FOUND、E_SAMPLE_TOO_SMALL、E_PACKAGE_FAILED …

2️⃣ 交付包自证（scripts/crawl_packager.py）

from scripts.crawl_packager import (build_delivery_package, verify_delivery_package,
                                    package_remote_files)
build_delivery_package([p1, p2], zip_name="maotai_2026q3",
                       manifest_payload={"topic": "贵州茅台", "records": 42})
verify_delivery_package("maotai_2026q3.zip")   # ok / checked / mismatched / missing / extra
package_remote_files(urls, retries=2)          # 单条失败不中断整批；失败清单只重下那几条

CLI：python scripts/crawl_packager.py deliver "<文件1,文件2>" 包名、verify 包名.zip（校验不通过 exit 2，便于脚本判断）。

3️⃣ 登录态接管（scripts/login_session.py）

from scripts.login_session import (add_profile, list_profiles, update_profile,
                                   check_login, cookie_header, apply_to_session,
                                   storage_state, wait_for_manual_login,
                                   login_status_report)
add_profile("eastmoney", "quote.eastmoney.com", cookie_file=r"C:cookies.txt")
check_login("eastmoney")                        # fresh/expiring/expired/session_only + 下一步
n = apply_to_session(my_session, "quote.eastmoney.com")   # 注入后照常爬
wait_for_manual_login("xueqiu", "https://xueqiu.com")     # 扫码完成后自动收会话

档案默认落 data/login_profiles/（CNFS_LOGIN_DIR 可改道到包外），交付前由 clean.py 删除；任何对外输出（summary / 列表 / 交付清单）只给 Cookie 条数与名称，绝不回显值。边界：不托管账号密码、不破解验证码、不做违反站点条款的批量抓取。

MCP 工具 96 → 110（v12 新增 14 个）

list_info_intents / gather_info / render_info_receipt / package_delivery / verify_package / package_remote_files / add_login_profile / list_login_profiles / update_login_profile / remove_login_profile / check_login_status / export_login_storage_state / wait_for_login / capability_self_check（v11 的 17 个实时/指标/融合工具与 v10 的调度、网页操作工具全部保留）

历史版本速查（v5 → v11，完整说明见 [README.md](README.md)）

关键命令

故障排查速查

❓ 常见问题（FAQ）

Q1: 舆情爬取返回空怎么办？

A: 1）检查目标名称是否正确（用 list_sentiment_targets 查看）；2）尝试扩大时间范围（days=7）；3）增加媒体源类别（source_categories=["authoritative", "financial_vertical", "self_media"]）。

Q2: 结构化数据（期货/宏观）返回 None？

A: 需要安装 akshare：pip install akshare。未安装时函数自动返回 None，不会报错。

Q3: 动态渲染页面（SPA）爬不到内容？

A: 默认 mode="static" 只走 HTTP。SPA 页面需用 mode="realtime"（需 Playwright）：

result = scrape_webpage(url="...", mode="realtime")

Q4: 爬取银行官网成功率很低？

A: 银行官网普遍反爬严格（验证码/IP 封禁），预期成功率 30-50%。建议：1）用 browser_human_fetch 走浏览器；2）加 proxy 轮换；3）降低频率。

Q5: 如何自定义舆情监控目标？

A: 两种方式：

# 方式 1：对话式
chat_handle("新增自定义目标：恒生电子")

# 方式 2：API
add_custom_sentiment_target("custom", "恒生电子")

Q6: pip 安装依赖很慢怎么办？

A: 使用国内镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
# 或永久设置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Q7: 不知道自己的问法会走哪条链，也不知道哪几步要手动衔接？

A: 先 list_info_intents(keyword="你的原话") 看路由结论与备选，再 gather_info(..., dry_run=True) 看步骤计划与数据源；确认后去掉 dry_run——整条链在 gather_info 内部自动衔接，plan 每步标 done/empty/skipped/failed。

Q8: 抓到的结果长什么样？能直接下结论吗？

A: render_info_receipt(result) 出 Markdown 回执（逐条来源+发布时间、共识事件、洞察、质量分档、缺口、下一步）。结论前看 answer_ability：样本 <10 条禁止比例/排名类结论，单源禁止跨源一致性结论，confidence=low 就别拿去当结论。

Q9: 结果条数比预期少？

A: 反爬失败留下的 [未能直接抓取] … 占位条目会被编排层剔除并记进 meta.placeholders_dropped（条数+来源）；全空时直接报 E_SOURCE_EMPTY 并给"放宽 days / 加 source_categories / 换 intent"的下一步，不会把空壳算成成功。

Q10: 登录后的页面怎么爬？Cookie 会不会被回显出去？

A: 用户自己导出 Cookie 建档（add_login_profile）或扫码接管（wait_for_login）→ check_login_status 验健康度 → gather_info(intent="login_page", profile="…")。所有对外输出只含 Cookie 条数与名称，值永不回显；档案在 data/login_profiles/，交付前由 clean.py 删除。不支持托管密码、破解验证码、违反站点条款的批量抓取。

Q11: 交付包怎么证明没被改过、没漏文件？

A: package_delivery 的 zip 内含 manifest.json（逐文件 sha256+字节数），接收方 verify_package(zip_path) 得到 mismatched/missing/extra；批量链接下载用 package_remote_files——单条失败不中断整批，失败项进 manifest.failed，下一轮只重下那几条。

📘 更多故障排查见 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | 🔒 安全审计见 [SECURITY.md](SECURITY.md)

详细文档

完整功能说明、机构清单、媒体源/目标库、MCP 工具表（110 个）、实战场景、变更日志与不兼容说明，见 [README.md](README.md)。