#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
📘 cn-financial-scraper 技能说明文档生成器
生成该 Skill 的完整功能说明 Word 文档到桌面
"""
from __future__ import annotations
import sys, os, json, zipfile
from datetime import datetime
from pathlib import Path
from xml.sax.saxutils import escape
SCRIPT_DIR = Path(__file__).resolve().parent
DATA_DIR = SCRIPT_DIR.parent / "data"
sys.path.insert(0, str(SCRIPT_DIR))
DESKTOP = Path.home() / "Desktop"
OUTPUT = DESKTOP / "cn-financial-scraper_技能说明文档.docx"
# ──── Word XML 模板 ────
CONTENT_TYPES = """
"""
RELS = """
"""
WORD_RELS = """
"""
STYLES = """
"""
def p(text, style="Normal"):
return f'{escape(text)}'
def p_bold(text, style="Normal"):
return f'{escape(text)}'
def tr(cells, bold=False, color=""):
b = '' if bold else ''
c = f'' if color else ''
cx = ''.join(
f'{b}{c}{escape(str(cell))}'
for cell in cells
)
return f'{cx}'
def load_json_counts():
counts = []
total = 0
for f in sorted(DATA_DIR.glob("*_list.json")):
try:
with open(f, 'r', encoding='utf-8') as fh:
data = json.load(fh)
insts = data.get('institutions', [])
type_name = data.get('type_name', data.get('type', f.stem))
count = len(insts)
source = data.get('data_source', '')
counts.append((type_name, count, source))
total += count
except Exception:
counts.append((f.stem, 0, '读取失败'))
return counts, total
def get_mcp_tools():
return [
("query_institution", "查询机构名单", "按类型/关键词查询27大类1330家金融机构"),
("scrape_webpage", "网页爬取", "爬取指定URL,支持静态/动态渲染模式"),
("scrape_institution", "机构官网爬取", "按机构名自动查找URL并爬取官网"),
("parse_financial_product", "产品解析", "解析基金/ETF/FOF/股票/债券页面"),
("crawl_financial_news", "新闻资讯", "爬取东方财富/同花顺最新金融新闻"),
("search_announcements", "公告搜索", "搜索沪深两市上市公司公告"),
("download_announcement", "公告PDF下载", "下载公告PDF到本地"),
("query_broker_reports", "券商研报", "查询个股研报(评级/分析师/目标价)"),
("get_company_reports", "综合报告", "一站式获取年报+研报+公告"),
("parse_document", "文档解析", "解析PDF/Word/Excel文件内容"),
("export_stock_report", "研报导出", "导出PPT/PDF/Word/Excel多格式"),
("batch_crawl_institutions", "批量爬取", "按名称列表或类型批量爬取机构"),
("search_report_index", "索引搜索", "在全量报告索引中搜索关键词"),
("analyze_document", "文档分析", "深度分析金融文档(分类/元数据/章节/财务指标/风险)"),
("organize_documents", "文档整理", "批量整理文档目录(分类聚合+索引+汇总)"),
("compare_documents", "文档对比", "多文档并排对比(指标/规模/差异高亮)"),
]
def get_core_modules():
return [
("scraper.py", "基础爬虫", "三级降级链(Scrapling→requests→缓存),统一爬取入口"),
("http_utils.py", "HTTP基础设施", "统一限流/重试/会话复用/LRU缓存/请求抖动"),
("web_parser.py", "网页解析器", "基金/ETF/FOF/股票/债券/投顾组合解析"),
("name_scraper.py", "机构名爬虫", "机构名→URL查找,反爬+双语展示+外机构翻译"),
("institution_scraper.py", "机构爬虫", "金融机构官网产品信息爬取"),
("announcement_scraper.py", "公告爬虫", "搜索+页面扫描+PDF下载"),
("research_report_scraper.py", "券商研报", "评级/分析师/目标价查询"),
("company_report_scraper.py", "公司财报", "年报/半年报/季报爬取"),
("news_scraper.py", "新闻爬虫", "东方财富/同花顺新闻多源获取"),
("document_parser.py", "文档解析", "PDF/Word/Excel/TXT内容提取"),
("document_analyzer.py", "文档分析", "结构化深度分析+批量整理+多文档对比"),
("report_exporter.py", "报告导出", "PPT/PDF/Word/Excel多格式导出"),
("report_indexer.py", "报告索引", "SQLite全量索引+断点续扫"),
("batch_institution_crawler.py", "批量爬虫", "按名称/类型/文件批量爬取"),
("analyzer.py", "产品分析", "风险指标/投资风格/配置建议"),
("adaptive_parser_v2.py", "智能解析", "AI识别各类金融页面结构"),
("scrapable_registry.py", "可爬注册表", "URL映射维护+增量更新"),
("full_institution_crawler.py", "全量爬虫", "从监管机构获取完整名单"),
("realtime_monitor.py", "实时监控", "动态检测页面变化/新公告"),
("visualization_reporter.py", "可视化报告", "ASCII图表生成"),
]
def build_document():
body = []
counts, total = load_json_counts()
tools = get_mcp_tools()
modules = get_core_modules()
# 封面
body.append(p("cn-financial-scraper", "Heading1"))
body.append(p("中国大陆金融数据爬取与分析综合工具 — 技能说明文档", "Heading2"))
body.append(p(f"生成日期: {datetime.now().strftime('%Y年%m月%d日')} | 版本: 2.6.0 | 最后更新: 2026-06-26", "Normal"))
body.append(p("", "Normal"))
body.append(p("─" * 60, "Normal"))
body.append(p("", "Normal"))
# 一、概览
body.append(p("一、技能概览", "Heading1"))
body.append(p("cn-financial-scraper 是一个专注于中国大陆金融数据的爬取与分析综合工具。它覆盖全量金融机构名单、A股上市公司报告、券商研报、公告下载、金融产品解析、文档分析整理等场景。", "Normal"))
body.append(p("", "Normal"))
body.append(p_bold(f"📊 总体规模: {total} 家金融机构,覆盖 {len(counts)} 个类别"))
body.append(p_bold(f"🔧 MCP 工具: {len(tools)} 个,通过 MCP 协议暴露给 Claude Code"))
body.append(p_bold(f"📁 核心模块: {len(modules)} 个 Python 模块"))
body.append(p_bold(f"📦 数据文件: {len(counts)} 个 JSON 名单文件 + 1 个机构注册表"))
body.append(p("", "Normal"))
# 二、机构名单
body.append(p("二、全量金融机构名单 (27大类)", "Heading1"))
body.append(p(f"注册表文件: data/institution_registry.json({total}家,紧凑列式存储)", "Normal"))
body.append(p("", "Normal"))
body.append('')
body.append(tr(["序号", "机构类别", "数量", "数据来源"], bold=True, color="1F4E79"))
for i, (name, cnt, src) in enumerate(counts, 1):
body.append(tr([str(i), name, str(cnt), src[:25]]))
body.append('')
body.append(p("", "Normal"))
# 三、MCP 工具
body.append(p(f"三、MCP 工具清单 ({len(tools)}个)", "Heading1"))
body.append(p("通过 MCP 协议暴露的工具,可在 Claude Code 中直接调用:", "Normal"))
body.append(p("", "Normal"))
body.append('')
body.append(tr(["#", "工具名称", "分类", "功能说明"], bold=True, color="1F4E79"))
cat_names = ["机构查询", "网页爬取", "产品解析", "新闻资讯", "公告管理", "券商研报", "综合报告", "文档解析", "报告导出", "批量操作", "索引搜索", "文档分析"]
cat_map = {
"query_institution": 0, "scrape_webpage": 1, "scrape_institution": 1, "parse_financial_product": 2,
"crawl_financial_news": 3, "search_announcements": 4, "download_announcement": 4,
"query_broker_reports": 5, "get_company_reports": 6, "parse_document": 7,
"export_stock_report": 8, "batch_crawl_institutions": 9, "search_report_index": 10,
"analyze_document": 11, "organize_documents": 11, "compare_documents": 11,
}
for i, (name, cat, desc) in enumerate(tools, 1):
cat_idx = cat_map.get(name, 0)
body.append(tr([str(i), name, cat_names[cat_idx], desc]))
body.append('')
body.append(p("", "Normal"))
# 四、核心模块
body.append(p("四、核心模块架构 (20个)", "Heading1"))
body.append(p("", "Normal"))
body.append('')
body.append(tr(["模块文件", "功能"], bold=True, color="1F4E79"))
for name, cat, desc in modules:
body.append(tr([name, desc]))
body.append('')
body.append(p("", "Normal"))
# 五、数据源
body.append(p("五、数据来源", "Heading1"))
body.append(p("• 行业协会公开名单 — 银行/保险/信托/金融租赁等持牌机构名单", "Normal"))
body.append(p("• 行业协会公开名单 — 券商/基金/期货/外资机构名单", "Normal"))
body.append(p("• 中国证券投资基金业协会 — 私募基金管理人名单", "Normal"))
body.append(p("• 中国期货业协会 — 期货公司/风险管理子公司名单", "Normal"))
body.append(p("• 中国财务公司协会 — 企业集团财务公司名单", "Normal"))
body.append(p("• 东方财富 — 实时行情/财报/研报/新闻/公告数据", "Normal"))
body.append(p("• 天天基金 — 基金净值/持仓/规模数据", "Normal"))
body.append(p("• 各机构官网 — 银行/基金/券商官网产品信息", "Normal"))
body.append(p("", "Normal"))
# 六、爬取架构
body.append(p("六、爬取架构", "Heading1"))
body.append(p("三级降级链: Scrapling 隐身模式 → requests 标准请求 → 本地缓存", "Normal"))
body.append(p("• 限流策略: 按域名独立限流(1~3s),请求抖动(±30%),指数退避(1.5x)", "Normal"))
body.append(p("• 缓存机制: 按域名设置TTL(1~24h),LRU内存缓存(128条),文件缓存", "Normal"))
body.append(p("• User-Agent: 桌面Chrome/移动端Safari随机切换", "Normal"))
body.append(p("• 反爬对抗: Scrapling StealthyFetcher隐身注入,Playwright动态渲染", "Normal"))
body.append(p("", "Normal"))
# 七、文档分析整理
body.append(p("七、文档分析整理系统", "Heading1"))
body.append(p("• 单文档深度分析:自动分类(年报/研报/公告等),提取标题/机构/日期/股票代码等元数据", "Normal"))
body.append(p("• 章节结构化:按层级正则切分章节,提取财务指标(营收/净利/EPS/ROE等)、风险因素、术语表", "Normal"))
body.append(p("• 批量整理:扫描目录逐份分析,按类别聚合,生成索引与汇总报告(data/document_index/)", "Normal"))
body.append(p("• 多文档对比:并排提取相同维度(类型/日期/关键指标/规模),高亮差异", "Normal"))
body.append(p("", "Normal"))
# 八、优化建议
body.append(p("八、代码优化建议", "Heading1"))
body.append(p("以下为代码审查发现的问题:", "Normal"))
body.append(p("", "Normal"))
body.append(p("1️⃣ 版本号不一致(已修复)", "Heading3"))
body.append(p("__init__.py 中 __version__ 已从 2.1.0 修复为 2.6.0,与 _meta.json 一致。", "Normal"))
body.append(p("", "Normal"))
body.append(p("2️⃣ crawl_utils 模块缺失", "Heading3"))
body.append(p("batch_institution_crawler.py 尝试导入 crawl_utils 模块,该模块不存在。导入失败有 try/except 兜底,但建议移除死代码或创建该模块。", "Normal"))
body.append(p("", "Normal"))
body.append(p("3️⃣ 招商银行URL错误(已修复)", "Heading3"))
body.append(p("scrapable_registry.py 中招商银行URL已从 cmbc.com.cn(民生银行)修复为 cmbchina.com(招商银行)。", "Normal"))
body.append(p("", "Normal"))
body.append(p("4️⃣ 数据描述不一致(已修复)", "Heading3"))
body.append(p("_meta.json 已更新描述:918家/17类 → 1330家/27大类,与实际数据一致。", "Normal"))
body.append(p("", "Normal"))
body.append(p("5️⃣ 导入模式不一致", "Heading3"))
body.append(p("mcp_server.py 中 web_parser 使用 importlib.import_module 延迟加载,其他模块使用顶层 import。建议统一为顶层导入。", "Normal"))
body.append(p("", "Normal"))
body.append(p("6️⃣ 缺少单元测试", "Heading3"))
body.append(p("整个项目无任何测试文件。建议为以下关键模块添加测试:scraper.py(爬取降级链)、http_utils.py(限流/缓存)、web_parser.py(产品解析)、document_analyzer.py(文档分析CRUD)。", "Normal"))
body.append(p("", "Normal"))
# 页脚
body.append(p("─" * 60, "Normal"))
body.append(p(f"文档自动生成于 {datetime.now().strftime('%Y-%m-%d %H:%M')} | Reasonix AI", "Normal"))
body.append(p("本文档仅供参考,实际功能以代码为准。", "Normal"))
return ''.join(body)
def generate():
print("📘 正在生成 cn-financial-scraper 技能说明文档...")
body = build_document()
doc_xml = f'''
{body}
'''
with zipfile.ZipFile(OUTPUT, 'w', zipfile.ZIP_DEFLATED) as docx:
docx.writestr('[Content_Types].xml', CONTENT_TYPES)
docx.writestr('_rels/.rels', RELS)
docx.writestr('word/_rels/document.xml.rels', WORD_RELS)
docx.writestr('word/document.xml', doc_xml.encode('utf-8'))
docx.writestr('word/styles.xml', STYLES)
size = os.path.getsize(OUTPUT)
print(f"\n✅ 文档已生成!")
print(f"📄 {OUTPUT}")
print(f"📏 {size:,} 字节")
if __name__ == '__main__':
generate()