GdiSDK 开发文档

欢迎使用 GdiSDK 开发文档。GdiSDK 是一个面向地学和环境相关领域的数据处理与智能分析应用，以及 GDIM平台二次开发的 Python 开发包。

通过本套文档，你可以从总体概念入手，逐步了解：

GdiSDK 能解决什么问题（概述）
如何快速上手并构建第一个 pipeline（新手入门）
如何在 AI IDE 中借助 Skills 加速开发（AI辅助开发 (Code Agent)）
如何把 Pipeline 做成可用应用（用户指南）
Pipeline 的核心运行机制（运行机制）
Pipeline 内的循环与条件控制（流程控制）
在 GDIM 前端开启开发模式查看表名 / 字段名，以及平台侧 Pipeline 节点状态图（GDIM 开发模式）
常用模块的中文使用说明和小例子（模块帮助）
端口类型与端口数据结构的使用说明
通过完整案例学习真实项目实践（学习案例）
完整的类与函数接口定义（API 参考）

概述

GdiSDK (Geo Data Intelligence Software Development Kit) 是一个用于 GDIM平台二次开发，以及岩土工程、土壤与地下水、资源与矿产等相关领域数据处理和智能分析应用的 Python 开发包。

它基于工作流编程框架，提供了丰富的分析模块和灵活的数据结构，帮助工程师和研究人员以「搭积木」的方式组合模块，而不是从零开始编写大量样板代码，从而更高效地把专业经验固化为可复用的应用。

核心特性

模块化设计：将常用的数据读取、清洗、转换、分析、可视化等能力拆分为独立模块，可自由组合与复用。
工作流编程框架：通过 pipeline 将多个模块按业务流程串联起来，实现复杂数据处理任务的一键执行和可视化管理。
标准化数据结构：基于 Pandas 和 Pydantic 定义核心数据类，在不同模块和项目之间保持统一的数据结构和验证规则。
易于扩展：支持自定义模块、脚本和插件机制，方便将现有算法与企业自有规范集成到 GdiSDK 中。
现代化架构：采用现代 Python 技术栈，配合类型注解、单元测试和持续集成，支持长期维护和团队协作。

主要组件

GdiSDK 主要包含以下三个核心包，它们共同组成了从「数据」到「工作流」再到「应用」的完整链路：

modules：数据处理和分析的核心模块集合，涵盖读取、转换、计算、绘图等常见操作。
pipeline：工作流编程框架，用于组织和执行复杂的数据处理工作流，是模块之间「连线」和调度的核心。
dataclass：核心数据类定义，包括表格数据、结果数据、地质数据等，为模块之间的数据传递提供统一结构。

模块帮助

如果你已经了解了 GdiSDK 的基本概念，希望直接查阅「某个模块怎么用、有哪些常用参数、有没有简单示例」，可以参考 模块帮助 章节（本 index 顶部目录中的 module_help）。

模块帮助与 API 参考 的区别在于：

模块帮助：面向日常使用的说明，强调「怎么用」「常见配置」「典型场景」「在 pipeline 中如何串联」，适合快速查阅和复制粘贴示例。
API 参考：由代码文档生成，提供最完整的类与函数签名、参数类型和详细说明，适合做精细开发和调试时使用。

端口类型

在 Pipeline 中，模块之间所有数据交换都是通过「端口 (Port)」完成的。每个端口都有一个明确的 端口类型 (PortType)，并在代码层面通过 gdisdk.pipeline.portTypes.PortTypeHint 进行类型标注，用来约束可以在端口上传递哪些数据。

常见的端口类型大致分为三类：

基础类型端口（如 SingleValue、 NumberArray、 HttpUrl 等）——直接封装标量、数组、字符串等轻量数据；
核心数据结构相关端口： - PortType.TableData / PortType.TableCollection 等，对应 gdisdk.dataclass.tables 中的 TableData / TableCollection 等表格数据结构； - PortType.ResultModel / PortType.SingleResult / PortType.ResultsDict / PortType.MultiResultsDict ，对应结果与运行数据相关结构；
面向 GDIM / 可视化 / 文档的端口（如 PortType.PlotData、 PortType.GdimFile、 PortType.DocData 等），用于前端展示和自动报告生成。

这些端口类型背后的数据结构都做了有意识的二次封装：在原生 pandas / dict 之上增加「字段元数据（标题、单位、描述）和上下文结构」，核心目的是 让 AI / 智能模块以及 GDIM 前端更容易“读懂”数据含义，支持自动报告、可视化和智能分析等高级能力。

如果你想先确定模块端口该怎么设计，建议先看 端口类型 (Port Type) 章节：端口类型 (Port Type)。

这一章的定位是：

如何给模块端口选择合适的 PortTypeHint / PortType；
不同端口类型分别对应什么 Python 数据结构；
端口数据如何导出为文档上下文、GDIM 可视化数据或 JSON 可序列化结构；

端口数据结构

如果你已经先确定了端口类型，但还想进一步了解这些端口背后到底在传什么数据、有哪些常用方法、以及 ResultModel、SingleResult、TableData、DocData 等结构在代码里该怎么用，可以继续看 端口数据结构 (Port Dataclass) 章节：端口数据结构 (Port Dataclass)。

这一章位于 端口类型 和 API 参考 之间，定位是：

帮你理解“这个数据结构是什么、怎么初始化、常用方法有哪些”；
重点展开各数据结构的详细用法，而不是重复讲端口选型；
在结果数据中优先介绍 ResultModel，SingleResult 仅作为兼容历史模块的旧方案说明。

推荐查阅顺序：

先看端口类型 (Port Type)，决定端口该声明为什么类型。
再看端口数据结构 (Port Dataclass)，查具体数据结构的初始化方式与常用方法。

与 API参考 (API Reference) 相比，porttype_help 更关注「在组织 Pipeline 和模块端口时如何选型、如何使用」而不是完整的类签名：它会从 端口类型 → 对应数据结构 → 典型场景与示例 的角度展开，类似模块帮助 (Module Help) 之于模块。

快速开始

from gdisdk.modules.operators import ArithmeticOperator
from gdisdk.pipeline.pipeline import PipeLine
import numpy as np

# 实例化一个简单的四则运算模块
calc = ArithmeticOperator(mname="Calc")    # 初始化四则运算模块
calc.operator = "+"    # 设置运算符属性值为 "+"
calc.InputNumbers1 = np.array([1, 2, 3])    # 设置 InputNumbers1 端口值为 [1, 2, 3]
calc.InputNumbers2 = np.array([4, 5, 6])    # 设置 InputNumbers2 端口值为 [4, 5, 6]

# 执行计算
calc.execute()
result = calc.OutputNumbers.data
print(result)  # 输出: [5, 7, 9]

# 或组织pipeline
pipeline = PipeLine(app_name="Calculator", app_title="计算器")    # 初始化pipeline
pipeline.add_module(calc)     # 添加模块到pipeline
result = pipeline.run()      # 执行pipeline
print(result.get_result(module_name="Calc", port_name="OutputNumbers"))   # 输出: [5, 7, 9]
print(calc.OutputNumbers.data)    # 输出: [5, 7, 9]

AI 工具支持

本文档提供 llms.txt 文件，遵循 llms.txt 标准，方便 AI 编程助手（如 Cursor、ChatGPT、Claude 等）快速索引本文档的结构与关键页面，从而在你编写 GdiSDK 代码时提供更准确的上下文和建议。