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 获取文稿契约、叙事结构、证据分层规则和质量门。
- 根据 Excel 和已核验原文起草
{output_dir}/PPT文稿.md：元信息、执行摘要、逐页章节（结论式标题、要点、图表规格、讲稿、来源）和附录。 - 读取 references/report-facts.md，为执行摘要和所有结论式标题建立
{output_dir}/report_claims.json，运行report_facts.py生成{output_dir}/report_facts.json。任一事实性 claim 未通过时，修正结论或回到数据修正，不得交付。 - 运行
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；工具不可用或处理后仍异常则标记人工复核，不猜测数值。 - 调研信息与官方披露冲突：以披露为准，差异写入文稿附录的局限说明。
- 涉及未公开资料、个人信息或内部敏感数据：提醒用户确认脱敏和共享范围。