端口类型 (Port Type)

本章节专门介绍 GdiSDK 中的 端口类型 (PortType / PortTypeHint)，以及它们与核心数据结构（特别是 TableData、TableCollection、ResultModel、SingleResult、AgentRunResult、DocData、PlotData）之间的关系，帮助你在组织 Pipeline 和设计模块端口时做出合理选择。

相比 API参考 (API Reference) 中按类/函数罗列的接口文档，本章节更关注：

在 模块端口 上应该选哪一种 PortTypeHint / PortType；
典型业务场景分别适合用哪一种端口类型；
这些端口类型各自对应什么 Python 数据结构；
如何利用这些结构支持 自动报告生成、数据可视化和 LLM 智能分析。

如果你已经先确定端口类型，但还想进一步了解某种数据结构本身的初始化方式、常用方法和适用边界，可继续参考端口数据结构 (Port Dataclass)。

推荐查阅顺序：

先看本章，决定模块端口该声明为哪一种 PortType / PortTypeHint。
再看端口数据结构 (Port Dataclass)，查询对应数据结构的详细用法与方法签名。

端口、端口类型与 PortTypeHint

在 GdiSDK 中，一个模块之间的数据交换单元是 端口 (Port)：

在代码层面，端口通过 PortReference[PortTypeHint.xxx] 声明；
在运行时，端口的类型由枚举 gdisdk.pipeline.portTypes.PortType 表示；
PortTypeHint 和 PortType 之间存在 1:1 对应关系（详见 gdisdk.pipeline.portTypes.get_port_type_hint_to_port_type_mapping()）。

Hint

优先从 gdisdk.pipeline 包根导入公共 API，例如 from gdisdk.pipeline import PipeModule, PortReference, PortTypeHint。只有在需要底层实现或未重导出的辅助类型时，再使用 gdisdk.pipeline.portTypes、gdisdk.pipeline.pipeData 等子模块路径。

一个典型的端口声明如下：

from gdisdk.pipeline import PipeModule, PortReference, PortTypeHint, module_decorator


@module_decorator()
class ThresholdFilter(PipeModule):
    """根据阈值过滤 TableData 中的某一列。"""

    InputTable: PortReference[PortTypeHint.TableData]
    OutputTable: PortReference[PortTypeHint.TableData]

    def execute(self) -> PortTypeHint.TableData | None:
        table = self._ports_in["InputTable"].data
        # ... 业务逻辑略 ...
        self._ports_out["OutputTable"].data = table
        return table

这里：

PortTypeHint.TableData 表示端口上传递的是一个 gdisdk.dataclass.tables.TableData 对象；
对应的运行时端口类型为 PortType.TableData，可在 GDIM 前端或 Pipeline 描述文件中看到；
在可视化编辑器中，只允许 端口类型兼容 的端口之间连线，避免类型错误。

TableData：模块之间传递单张业务表

当一个端口需要传递 单张业务表，并且这张表后续还要继续参与模块计算、报告、AI 分析或前端展示时，通常优先选择 PortType.TableData / PortTypeHint.TableData。

这个端口类型最适合：

Reader 模块输出的单张业务表；
过滤、统计、聚合、转换模块的输入与输出；
需要保留字段标题、单位、描述等语义信息的表格结果。

选型建议：

如果下游仍然把它当“表”继续处理，优先用 TableData；
如果只是临时内部计算、且不会通过端口长期流动，普通 pandas.DataFrame 也可以；
如果你需要一次传多张相关表，而不是单张表，应改用 TableCollection。

进一步阅读：TableData、TableSeries

TableCollection：模块之间整体传递多张关联表

当一个端口需要传递 多张彼此有关联的表，例如“主表 + 明细表 + 附属表”，应优先选择 PortType.TableCollection / PortTypeHint.TableCollection。

这个端口类型最适合：

一次读取或整理一个项目的多张业务表；
报告、剖面绘制、综合分析等需要多表协同的场景；
需要把多张表作为一个整体交给下游模块时。

选型建议：

只有一张表时，用 TableData 更直接；
多张表要一起流动，且关系本身有业务意义时，再用 TableCollection；
如果你只是在函数内部临时维护一个 dict[str, DataFrame]，不一定需要把它设计成此端口类型。

进一步阅读：TableCollection

ResultModel：推荐的结构化结果端口类型

当一个端口需要传递的是 结构明确的结果对象，例如一组带名称、标题、单位、说明的计算结果字段，或需要类型校验、默认值、稳定序列化的业务结果，推荐使用 PortType.ResultModel / PortTypeHint.ResultModel。

这个端口类型最适合：

新模块输出的结构化计算结果；
既希望保留字段语义，又希望获得 Pydantic 类型校验与默认值能力的场景；
结构化 AI 输出；
需要类型校验和默认值的业务对象；
需要长期维护、多人协作的字典型结果；
希望结果结构能够清晰建模，而不是停留在自由 dict 层面。

与 SingleResult / JsonObject 相比：

ResultModel 是新的主线方案，基于 Pydantic BaseModel，字段定义更清晰、类型约束更强；
ResultModel 同样支持 title / unit / description 元数据，并保留 export_doc_context、convert_to_table_data、字典式访问等结果场景能力；
大多数需要传“结构化结果数据”的场景，都应优先推荐 ``ResultModel``；
SingleResult 更适合兼容旧模块，而不是新设计；
JsonObject 更轻量，但缺少字段约束和结果元数据能力。

进一步阅读：ResultModel

SingleResult：兼容旧模块的“关键指标结果”端口类型

当一个端口要输出的是 一组简单结果字段，例如统计指标、计算结论、若干关键参数，历史上常使用 PortType.SingleResult / PortTypeHint.SingleResult。

Warning

SingleResult 已进入逐步淘汰阶段。新模块、新端口设计应优先使用 PortType.ResultModel / PortTypeHint.ResultModel；仅在兼容旧模块、旧 Pipeline 或已有接口约束时继续使用 SingleResult。

这个端口类型最适合：

平均值、最大值、最小值、计数等统计指标；
一组需要写入报告模板的关键结果；
维护老模块时，结果以“键值对”为主，且每个 key 还希望带标题、单位、说明等信息。

选型建议：

如果你在维护旧逻辑、旧模块或旧 .pipe，SingleResult 仍可继续使用；
如果是新开发，哪怕结果本质上是一组简单值，也优先用前面的 ResultModel；
如果只是临时透传一个普通 JSON 字典，则 JsonObject 更轻量。

进一步阅读：SingleResult

AgentRunResult：用于保留大模型原始运行结果的端口类型

当一个端口需要传递 大模型调用的原始运行结果对象，而不仅仅是最终文本或结构化字段时，推荐使用 PortType.AgentRunResult / PortTypeHint.AgentRunResult。

这个端口类型最适合：

需要保留完整 LLM 调用上下文和元数据的场景；
需要读取模型原始输出文本、消息历史、token 使用量等信息的场景；
需要基于同一次运行结果继续做多轮对话、调试或审计的场景。

选型建议：

如果下游只关心最终结构化结果，优先输出 ResultModel；
如果下游只关心一段纯文本，优先输出 Text 或封装后的 ResultModel；
只有当下游确实需要访问 .output、.all_messages()、.usage()、.new_messages() 等运行时信息时，再传递 AgentRunResult。

AgentRunResult 与 ResultModel 的区别：

ResultModel 面向“业务结果”，适合后续模板、计算、展示和结构化处理；
AgentRunResult 面向“模型运行过程结果”，适合保留原始响应与调用元数据；
在很多 LLM 模块中，这两者会同时出现：一个用于给业务模块消费，一个用于保留原始 AI 运行上下文。

进一步阅读：AgentRunResult

DocData：报告打印的数据容器（模板 keys 与渲染数据）

DocData 对应 PortType.DocData / PortTypeHint.DocData，它是 文档模板打印链路 中的专用端口类型。

这个端口类型最适合：

输出给 DocPrinter、ExcelPrinter 一类打印模块；
需要同时携带“渲染数据”和“模板 key 结构”的场景；
报告打印链路中的中间结果传递。

选型建议：

如果你的目标是文档模板打印，不要直接传 TableData 或 SingleResult 给最终打印模块，而应先整理为 DocData；
在大多数情况下，DocData 由 DocDataWriter、MergeDocData 等模块自动生成，而不是手动构造；
当你想排查模板变量或最终渲染数据时，再去查看 DocData 的导出能力即可。

进一步阅读：DocData

PlotData：前端图表输出端口

PlotData 对应 PortType.PlotData / PortTypeHint.PlotData，它用于在 Pipeline 中传递 前端图表渲染数据。

这个端口类型最适合：

各类绘图模块输出给 GDIM / Web 前端显示；
把多个图表输出继续传给 PlotMerger 合并；
需要把图表作为结果返回到界面，而不是作为业务表继续处理。

选型建议：

如果数据的下一步是“画图并显示”，应使用 PlotData；
如果数据下一步仍然是统计、过滤、导出报告，优先继续使用 TableData / ResultModel / SingleResult，到真正绘图时再转换为 PlotData；
虽然 PlotData 底层也是 JSON 字典，但它表示的是 图表协议数据，不应把它与通用 JsonObject 混用。

进一步阅读：PlotData

Text：前端可展示的文本端口

Text 对应 PortType.Text / PortTypeHint.Text，用于在 Pipeline 中传递 文本内容，并可直接作为 GDIM 前端可展示结果的一部分。

这个端口类型最适合：

输出说明文字、结论文本、AI 生成摘要等字符串结果；
在前端展示纯文本内容；
需要以 Markdown 形式展示富文本说明的场景。

选型建议：

如果结果本质上是一段文本，而不是结构化字段集合，优先使用 Text；
如果你希望在 GDIM 前端中展示标题、段落、列表等格式化说明，可直接输出 Markdown 文本；
如果下游还需要继续做结构化计算或字段级引用，仍应优先考虑 ResultModel。

Picture：前端可展示的图片端口

Picture 对应 PortType.Picture / PortTypeHint.Picture，用于在 Pipeline 中传递 图片内容，当前约定为 Base64 字符串，并可在 GDIM 前端直接展示。

这个端口类型最适合：

输出流程生成的结果图片、示意图或截图；
在前端页面中直接回显单张图片结果；
需要把图像作为展示结果返回，而不是继续作为业务数据处理的场景。

选型建议：

如果你传递的是图片文件路径，应优先使用 FilePath / FilesPath；
如果你传递的是可直接渲染的图片内容，使用 Picture 更合适；
如果你的目标是图表协议数据而不是最终图片，应继续使用 PlotData。

设计动机：为数据智能准备好的结构

GdiSDK 在端口层面引入 TableData / TableCollection / ResultModel / SingleResult 等结构，一个重要目标是：

让“懂业务的数据结构”在整个 Pipeline 里流动，而不是无语义的 DataFrame / dict。

这带来的直接好处包括：

更安全的模块组合：端口类型一目了然，连线错误在可视化编辑器和类型检查阶段就能暴露；
更易于自动报告： export_doc_context / DocData / ToGdimJsonTable 等接口可以直接消费这些结构；
更友好的 AI 集成：LLM 模块拿到的不再是“没有列名语义的表”，而是带有「标题、单位、字段描述、主表/子表关系」的信息，可以更准确地生成结论和文字说明。

在设计新模块时，可以优先考虑：

表类数据 → 使用 TableData / TableCollection 系列端口；
结构化结果对象 → 优先使用 ResultModel；
存量简单指标结果 → 仅在兼容旧逻辑时继续使用 SingleResult；
可视化输出 → 优先使用 PlotData；
文档输出 → 使用 DocData。

这样，你的 Pipeline 不仅「能跑」，而且对后续的数据智能和应用集成都更加友好。如果你想进一步比较这些数据结构本身的差异与适用场景，可继续参考端口数据结构 (Port Dataclass)。

端口类型家族概览

前面的章节更偏向「如何选类型」；本节作为速查表，按类别汇总当前有效、推荐使用的端口类型。

每一项都包含：

对应的运行时枚举：PortType.xxx
对应的声明提示：PortTypeHint.xxx
一句话用途说明
对应 Python type / 业务数据类型

一、基础标量与轻量容器

PortType.SingleValue / PortTypeHint.SingleValue：传递单个基础值，适合轻量参数或简单结果。对应 type：numbers.Number | str。
PortType.Number / PortTypeHint.Number：传递单个数值，适合计算参数、阈值和数值结果。对应 type：numbers.Number。
PortType.NumberArray / PortTypeHint.NumberArray：传递一维数值数组。对应 type：np.ndarray | pd.Series。
PortType.GeneralArray / PortTypeHint.GeneralArray：传递一维通用数组，可包含非纯数值元素。对应 type：np.ndarray | pd.Series | list[Any]。
PortType.FilePath / PortTypeHint.FilePath：传递单个文件路径。对应 type：pathlib.Path | str。
PortType.FilesPath / PortTypeHint.FilesPath：传递多个文件路径。对应 type：list[pathlib.Path | str]。
PortType.NumberTable / PortTypeHint.NumberTable：传递纯数值二维表。对应 type：pandas.DataFrame。
PortType.GeneralTable / PortTypeHint.GeneralTable：传递通用二维表。对应 type：pandas.DataFrame。
PortType.HttpUrl / PortTypeHint.HttpUrl：传递 HTTP/HTTPS 地址。对应 type：str。
PortType.Text / PortTypeHint.Text：传递纯文本内容，可在 GDIM 前端直接展示，也可用于 Markdown 格式展示。对应 type：str。
PortType.Picture / PortTypeHint.Picture：传递图片内容，当前约定为 Base64 字符串，可在 GDIM 前端直接展示。对应 type：str。
PortType.JsonObject / PortTypeHint.JsonObject：传递一般 JSON 对象，适合轻量、临时、无需严格建模的字典数据。对应 type：dict。详见 ResultModel。
PortType.General / PortTypeHint.General：传递任意值，用于无法提前限定类型的场景。对应 type：Any。

二、结果、模型与文档数据

PortType.TableData / PortTypeHint.TableData：传递带字段元信息的单张语义表。对应 type：gdisdk.dataclass.tables.TableData。详见 TableData。
PortType.TableSeries / PortTypeHint.TableSeries：传递带元信息的单列表格序列。对应 type：gdisdk.dataclass.tables.TableSeries。详见 TableSeries。
PortType.TableCollection / PortTypeHint.TableCollection：传递多张表组成的语义表集合。对应 type：gdisdk.dataclass.tables.TableCollection。详见 TableCollection。
PortType.TableCollectionDict / PortTypeHint.TableCollectionDict：传递以名称索引的多套表集合，适合批量组织多组 TableCollection。对应 type：dict[str, TableCollection]。
PortType.ResultModel / PortTypeHint.ResultModel：推荐的结构化结果模型类型，适合大多数需要字段约束、结果元数据和稳定序列化的结果场景。对应 type：gdisdk.dataclass.results.ResultModel。详见 ResultModel。
PortType.SingleResult / PortTypeHint.SingleResult：旧版结构化单组指标结果类型，适合兼容历史模块中的“简单值 + 标题/单位/说明”场景；新设计不再推荐继续使用。对应 type：gdisdk.dataclass.results.SingleResult。详见 SingleResult。
PortType.AgentRunResult / PortTypeHint.AgentRunResult：传递 pydantic_ai 的原始运行结果对象，适合保留 LLM 原始输出、消息历史和 token 使用量等运行元信息。对应 type：pydantic_ai.run.AgentRunResult。详见 AgentRunResult。
PortType.ResultsDict / PortTypeHint.ResultsDict：传递单次执行的结构化结果集合，适合按模块/端口组织的一次运行结果。对应 type：gdisdk.pipeline.pipeData.ResultsDict。
PortType.MultiResultsDict / PortTypeHint.MultiResultsDict：传递多组结构化结果集合，适合批量执行、迭代执行后的结果汇总。对应 type：gdisdk.pipeline.pipeData.MultiResultsDict。
PortType.CoordinateSystem / PortTypeHint.CoordinateSystem：传递坐标系统信息。对应 type：gdisdk.dataclass.results.CoordinateSystem。详见 CoordinateSystem。
PortType.DocData / PortTypeHint.DocData：传递面向文档渲染的结构化打印数据。对应 type：gdisdk.dataclass.results.DocData。详见 DocData。

三、流程控制与执行辅助

PortType.Token / PortTypeHint.Token：传递平台访问凭据及上下文信息。对应 type：tuple[str | None, str | None, str | None]，含义为 (token, proj_id, host)。
PortType.Attributes / PortTypeHint.Attributes：传递模块属性字典，常用于 InputAttributes / OutputAttributes。对应 type：dict[str, Any]。
PortType.IterationData / PortTypeHint.IterationData：传递迭代输入数据，主要供 gdisdk.pipeline.flowControl.ForEachController 的 InputIterData 使用。对应 type：list[dict[str, Any]]。用法详见流程控制 (Flow Control)。
PortType.IterationResult / PortTypeHint.IterationResult：传递迭代聚合结果，主要作为 gdisdk.pipeline.flowControl.ForEachController 的输出类型使用。对应 type：list[Any]。用法详见流程控制 (Flow Control)。

四、地质剖面与结构对象

PortType.Profile1D / PortTypeHint.Profile1D：传递单个一维地质剖面。对应 type：gdisdk.dataclass.geoProfiles.Profile1D。
PortType.MultiProfile1D / PortTypeHint.MultiProfile1D：传递多个一维地质剖面。对应 type：gdisdk.dataclass.geoProfiles.MultiProfile1D。
PortType.BoreForCadDraw / PortTypeHint.BoreForCadDraw：传递用于 CAD 柱状图/钻孔图绘制的钻孔数据。对应 type：gdisdk.dataclass.geoProfiles.BoreForCadDraw。
PortType.BoreForPlanDraw / PortTypeHint.BoreForPlanDraw：传递用于平面布孔图绘制的钻孔数据。对应 type：gdisdk.dataclass.geoProfiles.BoreForPlanDraw。
PortType.RecFoundation / PortTypeHint.RecFoundation：传递矩形基础对象。对应 type：gdisdk.dataclass.geoStructures.RecFoundation。
PortType.Pile / PortTypeHint.Pile：传递桩基础对象。对应 type：gdisdk.dataclass.geoStructures.BasicPile。
PortType.CompositePile / PortTypeHint.CompositePile：传递复合桩对象。对应 type：gdisdk.dataclass.geoStructures.BasicCompositePile。
PortType.GeoSection / PortTypeHint.GeoSection：传递单个二维地质剖面绘图对象。对应 type：gdisdk.dataclass.geoProfiles.SectionForCadDraw。
PortType.GeoSection3D / PortTypeHint.GeoSection3D：传递单个三维地质剖面对象。对应 type：gdisdk.dataclass.geoProfiles.Section3D。
PortType.GeoSections / PortTypeHint.GeoSections：传递多个二维地质剖面对象。对应 type：list[SectionForCadDraw]。
PortType.GeoSections3D / PortTypeHint.GeoSections3D：传递多个三维地质剖面对象。对应 type：list[Section3D]。

五、GDIM 平台与可视化相关

PortType.GdimTemplate / PortTypeHint.GdimTemplate：传递 GDIM 模板结构对象。对应 type：gdisdk.dataclass.gdimData.GdimTemplate。详见 GdimTemplate。
PortType.GdimFile / PortTypeHint.GdimFile：传递单个 GDIM 文件对象。对应 type：gdisdk.dataclass.gdimData.GdimMinIOFile。详见 GdimTemplate。
PortType.GdimFiles / PortTypeHint.GdimFiles：传递多个 GDIM 文件对象，适合文件批量上传、下载或下游批处理。对应 type：list[GdimMinIOFile]。
PortType.PlotData / PortTypeHint.PlotData：传递供 GDIM 前端图表组件消费的绘图 JSON 数据，适合图表展示链路。对应 type：dict。详见 PlotData。