工程化优化 DoclingProcessor 的 CN/HK LLM 可喂性 CI 闭环

[noho]

当前总控状态

• Phase 0：文档与边界确认已完成。
  • 提交：7bb4d0d docs: add LLM consumability framework
  • 提交：e57a8ba docs: define CN HK Docling consumability profile
  • 真源文档：docs/llm_consumability.md
• Phase 1：建立 CN/HK Docling scorer 最小闭环已完成。
  • 提交：c685912 feat: add CN HK Docling CI scorer
  • scorer：dayu.fins.score_docling_ci
  • 总控复验：pytest tests/fins/test_score_docling_ci.py -q 通过；pyright 0 errors。
• Phase 2A：生成 CN/HK Docling CI 执行文档。
  • 当前状态：待派实施 Agent。
  • 目标：新增 docs/cn_hk_docling_ci.md 或等价文档，作为 docs/ci.md 的 CN/HK Docling 版本。
  • 总控要求：先固化 baseline/iter/final、最小增量 process/score、问题归因、runner 输出目录与禁止事项，再进入 runner 实现。
• Phase 2B：新增或复用 CN/HK CI runner。
• Phase 3：跑 baseline 并归因第一批问题簇。
• Phase 4：按问题簇优化 DoclingProcessor / FinsDoclingProcessor / pipeline。
• Phase 5：全量回归与文档同步。

Phase 2A 必须遵守 Phase 0/1 的边界：CN/HK Docling CI 使用 dayu.fins.score_docling_ci 与 process --ci 的现有 tool_snapshot_*；不得套 SEC Item 体系，不得要求改 tool schema，不得把业务规则塞入 engine。

---

背景与意图

当前 SEC filings 已有较完整的 LLM 可喂性优化闭环：dayu-cli process --ci 导出 tool_snapshot_*，dayu.fins.score_sec_ci 对 snapshot 评分，再按 docs/ci.md 做 baseline、问题归因、最小增量 process/score 与最终全量对比。

CN/HK 财报下载后会自动转换为 Docling JSON，运行时主要经 DoclingProcessor / FinsDoclingProcessor 供财报工具读取。但 Docling 路线还没有类似 SEC 的 CI 优化闭环。这个 issue 的目标不是凭经验直接修改 DoclingProcessor，而是先工程化建立 CN/HK Docling 可喂性评分与优化流程，再用同源证据驱动 processor 优化。

重要修正：评分维度应继承 LLM Consumability 的上层思想，但必须结合 A 股/港股财报调整指标和阈值，不能原样套 SEC Item / Form 体系。A/H 财报没有 Item 7、Item 8 等 SEC 法定章节；它们更依赖中文/繁中文章节名、目录层级、三大报表标题、管理层讨论、公司治理、股东信息、风险提示、审计意见、附注等结构。

相关定义文档已迁移到 docs/llm_consumability.md，后续应基于该文档扩展 CN/HK 章节，而不是继续把可喂性定义留在 internel/research/。

代码级 research 结论

1. CN/HK process 已经同源导出 tool snapshot

代码位置：

• dayu/fins/pipelines/cn_pipeline.py
• dayu/fins/pipelines/tool_snapshot_export.py
• dayu/cli/arg_parsing.py

发现：

• CnPipeline.process() 已支持 ticker、overwrite、ci、document_ids，并通过共享 ingestion service 进入 process_stream_impl()。
• process_stream_impl() 同时处理 SourceKind.FILING 和 SourceKind.MATERIAL，并支持定向 document_ids，符合后续最小增量 CI 的基本要求。
• 单文档最终走 _export_tool_snapshot_for_document()，调用 export_tool_snapshot()，与 SEC 侧 snapshot 出口同源。
• CLI process 已有 --document-id、--overwrite、--ci 参数，因此 CN/HK 不需要新增 process 入口即可进入 CI 快照导出。

结论：CN/HK Docling CI 不应绕过 pipeline 或直接扫文件生成评估输入，应继续复用 process --ci 产物作为评分真源。

2. Snapshot exporter 已具备 CN/HK 查询词包与工具覆盖

代码位置：

• dayu/fins/pipelines/tool_snapshot_export.py

发现：

• export_tool_snapshot() 会写入 list_documents、get_document_sections、read_section、list_tables、get_table、get_page_content、get_financial_statement；CI 模式额外写入 search_document、query_xbrl_facts。
• _build_search_query_pack() 已按 market 选择 US/CN/HK 查询词包，并对默认财报类使用 annual_quarter_core40。
• CN/HK query pack 已包含中文/繁中文关键词，如主营业务、业务分部、现金流、董事会、关联交易、主要股东等。
• tool_snapshot_meta 已写入 market、form_type、document_type、has_financial_statement、has_financial_data、search_query_pack_* 等字段。

结论：CN/HK scorer 可以直接读取现有 snapshot，不需要先改 tool schema。首期应避免修改工具 schema，把评分建立在当前 snapshot 契约上。

3. score_sec_ci 不适合直接复用为 CN/HK scorer

代码位置：

• dayu/fins/score_sec_ci.py

发现：

• FORM_PROFILES 固定为 SEC 表单：10-K、10-Q、20-F、6-K、8-K、SC 13G、DEF 14A。
• _discover_form_snapshots() 只发现 SourceKind.FILING，并按 SEC form_type 匹配；这会漏掉 CN/HK MATERIAL，也不适配 FY、Q1、Q2、Q3、MATERIAL_* 等 form_type。
• 结构维度 A 依赖 SEC Item 顺序与 required items；内容维度 B 依赖 Item 1A/7/8 等阈值；S 维度依赖 SEC semantic profile。
• 财务覆盖门禁 _FINANCIAL_COVERAGE_THRESHOLDS 也围绕 SEC/XBRL 与 6-K HTML 提取设定。

结论：应新增 CN/HK 专用 scorer 或抽出通用 scoring core 后建立 CN profile。不能通过往 score_sec_ci.py 里硬塞 FY/Q1 来解决，否则会混淆 SEC 法定评分和 CN/HK Docling 评分边界。

4. DoclingProcessor 是 engine 通用层，不能塞财报业务规则

代码位置：

• dayu/engine/processors/docling_processor.py
• dayu/fins/processors/fins_docling_processor.py

发现：

• DoclingProcessor 负责 Docling JSON 的通用能力：线性 items、sections、tables、read_section、read_table、search、page_content。
• FinsDoclingProcessor 继承 DoclingProcessor，只调用 relabel_tables() 增强金融表格语义。
• 架构约束要求 engine 不能反向依赖 fins；因此 A/H 财报章节语义、财务表格识别、年报/季报规则应放在 fins 层或 scorer/profile，不应塞进 engine 通用 processor。

结论：未来问题归因必须区分：

• engine 通用 Docling 抽取问题：章节边界、表格渲染、caption/context/page_range、搜索基础能力。
• fins Docling 业务增强问题：金融表格识别、财报章节语义、CN/HK profile、statement 定位。
• pipeline/snapshot 问题：快照缺失、source_kind 发现、meta 字段、query pack。

5. 当前 fins 语义增强仍偏 SEC，CN/HK 语义不足

代码位置：

• dayu/fins/tools/section_semantic.py
• dayu/fins/processors/financial_enhancer.py
• dayu/fins/tools/service.py

发现：

• section_semantic.py 明确是 SEC Item 语义映射，只覆盖 10-K、10-Q、20-F。
• FinsToolService.get_document_sections() 和 read_section() 会调用 _enrich_sections_with_semantic() / resolve_section_semantic()，但 CN/HK 标题大概率无法得到 item/topic。
• financial_enhancer.py 的金融表格关键词很薄，只有少量英文与中文词，例如资产负债表、利润表、现金流量表、营业收入、净利润；未覆盖港股繁中文、合并/母公司报表、权益变动表、主要会计数据、财务摘要等常见标题。
• get_financial_statement() 对 DoclingProcessor 默认不支持，当前主要依赖 processor 是否实现该能力；Docling 路线可能更多依赖 list_tables/get_table 而非结构化 statement。

结论：CN/HK CI 的早期高价值扣分项很可能来自：章节语义不可寻址、金融表格召回不足、caption/context 不足、中文/繁中文搜索召回不足、表格 records/markdown 消费质量不足。

6. 现有测试覆盖了链路存在性，但没有覆盖 CN/HK 可喂性质量

代码位置：

• tests/fins/test_cn_pipeline_process.py
• tests/engine/test_docling_processor*.py
• tests/fins/test_score_sec_ci.py

发现：

• CN pipeline 测试验证了 filings/materials 能 process 并生成 snapshot，也验证了 --document-id 类似的定向处理能力。
• DoclingProcessor 测试覆盖了真实 PDF fixture、表格读取、章节保留 table ref、page_content 等基础能力。
• test_score_sec_ci.py 深度覆盖 SEC scorer，但没有 CN/HK scorer。

结论：落地时需要新增 CN/HK scorer 测试与 Docling 可喂性样例测试，不能只改 processor。

落地指导

Phase 0：文档与边界确认

目标：把可喂性定义从 SEC-only 扩展为 “通用框架 + SEC profile + CN/HK Docling profile”。

建议动作：

• 更新 docs/llm_consumability.md：保留通用定义，新增 CN/HK 财报适配章节。
• 明确 CN/HK 不评估 SEC Item 覆盖率，改评估：关键章节召回、章节标题可辨识、目录噪声、三大报表/附注/MD&A/治理/股东/风险等结构可导航性。
• 不在本阶段修改工具 schema。

验收：文档能明确回答“CN/HK scorer 和 SEC scorer 哪些维度同源、哪些指标不同”。

Phase 1：建立 CN/HK Docling scorer 最小闭环

目标：新增评分入口，先对现有 process --ci snapshot 出报告，不优化 processor。

建议动作：

• 新增 dayu.fins.score_docling_ci 或等价模块，避免污染 score_sec_ci.py。
• 发现样本必须走 dayu.fins.storage 仓储协议，支持 SourceKind.FILING 和 SourceKind.MATERIAL。
• profile 建议按 market/report kind 分层：CN annual/quarterly、HK annual/interim/quarterly、material。
• 读取 tool_snapshot_* 的方式可复用/抽取 score_sec_ci.py 的通用加载逻辑，但不要把 SEC form 规则混入 CN scorer。
• 输出 JSON/MD，字段与 SEC scorer 尽量相似，方便后续脚本复用。

首版评分建议：

• A 结构可导航：section_count 合理性、关键章节标题召回、父子层级、page_range 覆盖。
• B 内容充足：关键章节 read_section 内容长度、空章节比例、目录页误入比例。
• C 搜索可用：CN/HK query pack 命中率、next_section 可用率、中文/繁中文无结果 hint 比例。
• D 表格可消费：financial_count、caption/within_section/page_no 填充率、表格维度、空列/默认列/NaN/records 可读性。
• E 噪声与一致性：section table placeholders 可解引用、read_section/list_tables/get_table 一致性、mojibake/异常断行/页眉页脚噪声。
• F Docling 页面定位：get_page_content 对 section/table 页码的可复核性。

验收：能对一组 CN/HK ticker 产出 baseline JSON/MD，且不会依赖手拼 workspace/portfolio/... 路径。

Phase 2：新增 CN/HK CI runner 脚本

目标：复用 SEC 的工程节奏，实现 baseline、iter、final 的最小增量执行。

建议动作：

• 新增或扩展 utils/llm_ci_process.py 支持 CN/HK ticker 与 document-id mapping；如现有脚本已通用则只补文档。
• 新增 utils/llm_docling_ci_score.py 或让通用 score runner 能调用 CN/HK scorer。
• 生成 workspace/tmp/docling_ci_score/{tag}/summary.json、overall_summary.json。
• process 很耗时，仍遵守最小增量原则：优先 process --document-id ...。

验收：baseline 和 iter 都能只处理目标 ticker/document 子集。

Phase 3：跑 baseline，归因第一批问题簇

目标：用真实评分结果决定优化方向，不预设 DoclingProcessor 一定有错。

每个问题必须用三类证据闭环：

• scorer 扣分详情；
• 原始 Docling JSON / 源 PDF 或 snapshot 证据；
• 当前代码行为解释。

问题真源分类：

• engine 通用 Docling 抽取层
• fins Docling 财报增强层
• pipeline / snapshot 导出问题
• scorer/profile 阈值或指标问题

验收：issue 或报告中列出第一个问题簇，说明可修复性和影响文档集。

Phase 4：按问题簇优化 DoclingProcessor / FinsDoclingProcessor

目标：每轮只修一个同源问题簇。

可能的优化方向：

• engine 层：章节边界、标题识别、caption/context 推断、表格 records/markdown 渲染、page_range/table_ref 一致性、搜索噪声控制。
• fins 层：CN/HK 金融表格关键词、繁简中文同义词、三大报表定位、章节 topic 映射、材料类文档 profile。
• pipeline 层：snapshot meta、source_kind 发现、query pack 选择、CI 输出完整性。

验收：每轮有测试、有最小增量 process/score 对比；不能通过改评分标准刷分。

Phase 5：全量回归与文档同步

目标：最终判定只看 baseline vs final 的全量结果。

建议动作：

• 跑全量 CN/HK Docling score final。
• 比较 overall_avg、p10、hard_gate_failures、关键维度指标。
• 更新对应 README：dayu/fins/README.md、tests/README.md、根 README.md 中涉及 CLI/CI 入口的部分。
• 最后跑受影响测试和 pyright。

验收：final 全量指标高于 baseline，且没有新增 pyright 或测试问题。

非目标 / 明确禁止

• 不把 SEC Item 体系硬编码到 CN/HK scorer。
• 不把 A/H 财报业务语义塞进 dayu.engine.processors.docling_processor。
• 不通过修改评分规则掩盖 processor/snapshot 真问题。
• 不直接手拼 workspace/portfolio/... 读取文档或 snapshot。
• 不每轮全量 process。

下一步

等维护者确认后，按 Phase 0 → Phase 1 → Phase 2 → Phase 3 的顺序逐步细化 plan。每个 phase 独立拆分任务和测试边界，再进入实现。

[noho]

Phase 0 文档真源已落地并通过总控验收：\n\n- 已将通用 LLM 可喂性框架、SEC profile、CN/HK Docling profile 分层写入 docs/llm_consumability.md。\n- 已明确 CN/HK 不套 SEC Item 体系，未来 scorer 使用独立入口（如 dayu.fins.score_docling_ci），并以 process --ci 的 tool_snapshot_* 为评分输入。\n- 已校正 CN/HK profile 中 table/context 字段口径：首版 scorer 应使用当前 snapshot 暴露的 caption、within_section/section_ref、page_no、headers，以及 read_section.content 内的 [[t_xxxx]] 占位符，不依赖未暴露的 context_before 或 read_section.tables[]。\n- 提交：e57a8ba docs: define CN HK Docling consumability profile\n\n下一步建议进入 Phase 1：建立 CN/HK Docling scorer 最小闭环。

[noho]

Phase 1 已通过 review 并由总控固化：\n\n- 提交：c685912 feat: add CN HK Docling CI scorer\n- 新增：dayu.fins.score_docling_ci\n- 新增测试：tests/fins/test_score_docling_ci.py\n- README：dayu/fins/README.md、tests/README.md 已同步 scorer 边界\n\n总控复验：\n- pytest tests/fins/test_score_docling_ci.py -q：11 passed\n- pyright：0 errors, 0 warnings, 0 informations\n\nPhase 1 当前结论：CN/HK Docling scorer 最小闭环已落地，可以进入 Phase 2：新增或复用 CN/HK CI runner，生成 baseline/iter/final 的 score 输出目录和 summary。