Financial Disclosure Analysis

将官方财务披露转化为可追溯数据底稿，并撰写逐页、带证据链的 PPT 文稿。文稿是最终交付物：用户亲自审阅、修改文稿，满意后自行完成成品 PPT。本项目不生成 HTML 或 PPTX。

依赖

安装本项目依赖：

pip install -r requirements.txt
playwright install chromium

无外部集成依赖，开始任务前不需要检查任何外部工具。

核心原则

• 只从官方披露渠道下载并保留原始 PDF。
• 不修改原始 PDF/TXT；所有派生文件写入新的输出目录。
• 使每个数据点可在 30 秒内定位回原文。
• 不用估算值补齐缺失数据，不编造图表、KPI 或分析结论中的数字。
• 将 数据底稿.xlsx 作为数值事实源，将年报原文作为披露事实源。
• 证据分层并在文稿中标注等级：披露事实（D）、可重算推导（C）、调研信息（R）。调研信息不得写成披露事实，不得进入事实性 claim。
• 文稿按页组织、一页一判断；PPT文稿.md 是唯一文字交付物。除非用户明确要求网页附件，HTML 不属于交付物。

工作流

1. 意图分析与确认

从用户请求中识别并补全：

• 受众与用途：管理层汇报、投研参考、董事会材料等
• 对标公司集与顺序、证券代码、市场（A股/港股）
• 期间、报表类型、分析深度、输出目录

默认：

• 输出目录：<当前目录>/finance_analysis/data
• 分析深度：标准
• 标准报告：10–15 页；简要报告：5–8 页；深度报告：15 页以上

意图不明时给出默认假设，一次性请用户确认后再执行；确认后除阻断错误外不再打断。

2. 调研与数据收集

令 SD 指向本 Skill 的 scripts/。

A 股：

python {SD}/a_share.py search-annual --codes {代码...} --years {年份...} -d "{output_dir}/pdfs" --quiet

港股：

python {SD}/hk_share.py search-annual --codes "{代码,...}" --years "{年份,...}" -d "{output_dir}/pdfs" --quiet

批量转文本：

python {SD}/pdf_to_text.py --input-dir "{output_dir}/pdfs" --output-dir "{output_dir}/txt" --skip-existing --ocr-mode auto --quiet

下载器默认按 URL 和内容 SHA-256 复用本机缓存；用 FINANCIAL_DISCLOSURE_CACHE_DIR 改变位置，或用 FINANCIAL_DISCLOSURE_NO_CACHE=1 禁用。转文本同时生成同名 .pages.json，记录逐页字符范围、文本密度、表格数、源文件哈希和 OCR 状态。若 OCRmyPDF 不可用或 OCR 后仍有低文本页，将其列入人工复核，不能把空页视为未披露。

需要排错时才启用详细日志。不要把下载明细、解析警告或 TXT 正文刷入主会话。

3. 提取、复核与 Excel

读取 references/data-extraction.md 并严格执行。完成后必须得到：

• {output_dir}/tsv/*.tsv
• {output_dir}/数据底稿.xlsx
• 缺失项、口径差异、交叉验证异常的摘要

在对话中展示简洁的“指标 × 公司-期间”Markdown 汇总表。数据单元格只写数字，单位单列，缺失填 -。

生成 Excel 时必须通过 TSV 表头、重复指标和单位标准化校验。未知单位或未定义的混合单位属于阻断错误；不得沿用首个非空单位而不换算。

Excel 生成器同时输出 normalized_records.json 和 validation_summary.json，并在工作簿第二张生成“校验摘要”。存在阻断错误时停止进入文稿阶段；警告、缺失和单位换算必须进入交付说明。

4. 文稿撰写

读取 references/report-script.md 获取文稿契约、叙事结构、证据分层规则和质量门。

1. 根据 Excel 和已核验原文起草 {output_dir}/PPT文稿.md：元信息、执行摘要、逐页章节（结论式标题、要点、图表规格、讲稿、来源）和附录。
2. 读取 references/report-facts.md，为执行摘要和所有结论式标题建立 {output_dir}/report_claims.json，运行 report_facts.py 生成 {output_dir}/report_facts.json。任一事实性 claim 未通过时，修正结论或回到数据修正，不得交付。
3. 运行 validate_script.py 校验结构、密度和 claim 覆盖；存在阻断错误时修正后重跑。

先核验每个结论都能回指 Excel 或原文，再进入验收。

5. 验收与交付

运行 python {SD}/validate_delivery.py --data-dir "{output_dir}"；状态为 failed 时停止交付。

至少验收：

• validation_summary.json 无阻断错误；警告进入交付说明。
• report_facts.json 状态不为 failed。
• PPT文稿.md 通过结构、密度和 claim 覆盖检查。
• 文稿中每个数字都能回指 Excel 单元格或原文位置。

最终消息仅列出交付路径、文稿页数、数据缺失/局限和验证结果，不粘贴原始披露正文。

6. 审阅循环

用户会亲自审阅文稿，可能要求修改或重新生成，直至满意后自行制作成品 PPT：

• 重新生成前，请用户按失败分类清单（见 report-script.md）指出不满意项，记入 {output_dir}/review_notes.md，下一版针对性修正。
• 用户手改后的文稿另存为新版本（如 PPT文稿_v2.md），不覆盖上一版；对比版本差异，提炼用户偏好用于后续文稿。
• 只重跑受影响阶段：数据未变时不重复下载和提取；claim 未失效时不重复校验。

脚本

脚本	用途
a_share.py	搜索、下载 A 股年报
hk_share.py	搜索、下载港股年报
pdf_to_text.py	批量 PDF 转 TXT
generate_excel.py	从 TSV 生成 Excel 底稿
report_facts.py	生成 Excel 单元格级事实包并校验报告结论
validate_script.py	校验文稿结构、密度与 claim 覆盖
validate_delivery.py	一键验收数据、事实链与文稿

scripts/archive/ 中的桥接与 PPTX 校验脚本已停止维护；需要对接 PPT Master 时参见 references/ppt-master-handoff.md。

故障边界

• 官方渠道下载失败：列出公告、期间、失败原因和重试情况。
• PDF 无法解析或 .pages.json 标记 needs_ocr：保留 PDF，尝试 OCRmyPDF；工具不可用或处理后仍异常则标记人工复核，不猜测数值。
• 调研信息与官方披露冲突：以披露为准，差异写入文稿附录的局限说明。
• 涉及未公开资料、个人信息或内部敏感数据：提醒用户确认脱敏和共享范围。