专业路由¶

src/pipeline/router.py 中的 Router 类决定哪些专业富化策略适用于给定的提取结果，规划其执行顺序，并将相关上下文条目分配给每个专业策略。

路由工作原理¶

路由器接收 ExtractionResult 和 UserTableSchema，构建提取数据的紧凑摘要——表格角色、表头、行数、样本单元格值、上下文类型、context_id 及内容片段——并携带 ROUTER 提示词发送至高级 Gemini 模型（gemini-3.1-pro-preview）。Gemini 返回包含策略列表、执行顺序、上下文分配及推理依据的 GeminiRoutingResult。

def route(self, extraction_result, schema) -> GeminiRoutingResult:
    summary = self._build_summary(extraction_result, schema)
    result = self.gemini.request(summary, GeminiRoutingResult, model=ModelType.ADVANCED)
    return result

摘要包含每张主表前三行最多五列的样本单元格值及每个上下文条目的 context_id。这使路由器无需发送完整表格数据，即可检测复合引用（如 GL-03/GMT-01）等模式，并通过 ID 将特定上下文条目分配给策略。

五种策略类型¶

每种策略类型对应一个专业提示词和一种特定的富化方式。路由器仅在提取数据中存在明确证据时才选择相应策略。

T1：辅助表富化¶

辅助表专业策略处理主清单与辅助参考表之间的交叉引用。它将主清单列中的参考编码（如 GL-03、HW-05）与辅助表行匹配，并将匹配数据填充至目标模式列。对于复合引用（如 GL-03/GMT-01），它解析主要组件，并将次要组件记录在 Special Notes 中。

T2：文本规则富化¶

文本规则专业策略应用提取为文本上下文条目的文档级规则，包括 IBC 规范要求（如"距门 24 英寸内需钢化玻璃"）、性能规格（U 值、STC、SHGC 目标）、材料要求以及含条件语句的通用备注。结果主要体现在 Special Notes 列。

T3：图例富化¶

图例专业策略将主清单中的样式代码或类型标识与图像上下文中的图例图示解读进行匹配。它填充开启方式（使用 WindowOperabilityType / DoorOperabilityType 约束枚举值）、玻璃配置及面板属性。支持子类型继承——当 P1a 等行无直接图例匹配时，继承自基础类型 P1。

T4：尺寸富化¶

尺寸专业策略从图像上下文的条目卡片图和详图中提取宽度、高度、粗开口尺寸、玻璃排列配置及其他尺寸值。它通过类型标记或标签将图纸与清单行关联。面板布局数据（面板高度、类型、数量）提取至 Glass Arrangement Configuration 列而非 Special Notes。

T5：多标签富化¶

多标签专业策略处理两种模式：

1. 复合单元格值 — 主清单单元格中含 / 或 , 分隔的多个参考编码（如 GL-03/GMT-01）。策略根据建筑领域知识确定主要与次要组件（GL- 前缀通常为幕墙的主要组件）。
2. 共享条目卡片 — 单张图像上下文图示标注了多个清单条目（如 W39A-PTHP / W39B-NO PTHP）。策略通过将卡片标签与 __row_id__ 值匹配，将特定变体属性映射至正确行。

执行规划¶

路由器不仅决定运行哪些策略，还决定以何种顺序运行。GeminiRoutingResult 包含三个关键字段：

• strategies — 选定的策略类型列表
• execution_order — 有序的阶段列表，每个阶段包含可安全并行运行的策略列表。后续阶段的策略可能依赖于前面阶段的输出。
• context_assignments — 将每个策略名称映射到与该策略相关的 context_id 值列表的字典

执行顺序¶

路由器针对特定文档推理策略间的依赖关系。例如：

• 如果 text_rule 需要 auxiliary_table 的解析参考值才能正确应用条件规则，则 auxiliary_table 在更早的阶段运行。
• multi_label 始终在最后阶段运行，以便使用完全解析的数据。
• 如果不存在依赖关系，所有策略（multi_label 除外）在单个并行阶段运行。

有依赖关系的示例：

[["auxiliary_table"], ["text_rule", "image_legend", "dimension_card"], ["multi_label"]]

无依赖关系的示例：

[["auxiliary_table", "text_rule", "image_legend", "dimension_card"], ["multi_label"]]

上下文分配¶

路由器使用 context_id 值将特定上下文条目分配给每个策略。默认分配规则：

一个上下文条目可以分配给多个策略（如果与两者都相关）。当文档证据表明不同分配时，路由器会覆盖默认规则。

模型层级¶

路由器使用 ModelType.ADVANCED（Gemini Pro）。路由器扩展的职责——依赖分析、上下文分配和执行规划——需要高级模型层级。专业策略降级为 ModelType.FAST（Gemini Flash），因为它们接收预过滤、预分配的有效载荷。

单体回退¶

当路由器返回空策略列表——即没有专业策略有明确支持证据时——富化器回退至单体 ENRICHMENT 提示词。该单次 Gemini 调用接收所有表格、上下文和模式，尝试在一次调用中从任何可用来源填充所有列。与专业策略路径不同，该回退路径不会对多策略输出应用 FIELD_AUTHORITY_MATRIX 解析。

路由决策流程¶

下图展示了路由器输出如何决定富化路径。

flowchart TB
    ER["ExtractionResult + Schema"] --> ROUTER["路由器<br/>(Gemini Pro)"]
    ROUTER --> CHECK{返回策略?}

    CHECK -->|空| MONO["单体 ENRICHMENT<br/>(单次 Gemini Pro 调用)"]
    MONO --> OUT["list[EnrichedRow]"]

    CHECK -->|非空| PLAN["分阶段执行计划"]
    PLAN --> STAGE1["阶段 1: [auxiliary_table]<br/>(Gemini Flash)"]
    STAGE1 --> MERGE1["MergeResolver<br/>(聚合全部已完成输出)"]
    MERGE1 --> STAGE2["阶段 2: [text_rule, image_legend, dimension_card]<br/>(Gemini Flash, 并发)"]
    STAGE2 --> MERGE2["MergeResolver<br/>(聚合全部已完成输出)"]
    MERGE2 --> STAGE3["阶段 3: [multi_label]<br/>(Gemini Flash)"]
    STAGE3 --> MERGE3["MergeResolver"]
    MERGE3 --> ADJ["SpecialNotesAdjudicator<br/>(语义 bullet)"]
    ADJ --> VALID["枚举校验<br/>(Other: ... 兜底)"]
    VALID --> OUT

并非每个专业策略都在每份文件上运行。路由器仅选择有明确证据的策略，因此典型运行会激活两到三个专业策略。阶段数取决于所选策略之间是否存在依赖关系。