AI辅助开发 (Code Agent)

AI 编程助手（如 Cursor、Trae 等）正在成为工程师日常开发中越来越重要的工具。对于 GdiSDK 的使用者来说，善用 AI 可以大幅降低上手门槛，尤其是在编写 Pipeline 脚本、配置模块参数这类需要记忆大量接口细节的场景中。

本章节介绍如何在 AI IDE 中配合 gdisdk-skills 来加速 GdiSDK 二次开发，让 AI 真正”懂”你的开发意图，而不是凭空猜测。

什么是 AI IDE？

AI IDE（AI 智能集成开发环境）是在传统代码编辑器的基础上，深度集成了大语言模型（LLM）的新一代开发工具。你可以直接用自然语言描述你的需求，让 AI 帮你生成、修改或解释代码，而不必从零查文档、逐行手写。

目前比较主流的 AI IDE 有：

Cursor

基于 VS Code 改造，内置 AI 对话和代码补全，支持多种大模型（GPT-4、Claude 等），是目前国内外使用最广泛的 AI IDE 之一。支持 Skills 机制（后文介绍）。

Trae

字节跳动出品的 AI IDE，同样基于 VS Code，专为中文用户优化，支持国内主流大模型，支持 Skills 机制（后文介绍）。

Windsurf

Codeium 出品的 AI IDE，基于 VS Code，以 “Cascade” 多步骤 AI Agent 能力见长，支持跨文件的自动化操作，也支持类似的 Skills 机制，适合需要 AI 主动规划和执行较长开发任务的场景。

GitHub Copilot

GitHub 官方的 AI 编程助手，集成在 VS Code、JetBrains 等主流 IDE 中，侧重于代码补全和行内建议。在其部分 agent 场景中，也已支持类似的 agent skills 机制。

Note

Cursor、Trae、Windsurf 以及部分 GitHub Copilot agent 场景，都已经支持类似的 Skills / agent skills 机制。 不过，gdisdk-skills 当前的目录组织、安装示例和使用说明，主要还是按 Cursor 和 Trae 编写与验证的。 如果你使用其他 IDE，通常仍可参考后文思路进行适配，但具体目录位置、触发方式和 agent 能力可能会有所不同。

什么是 Skills？

Skills（技能）是 Cursor、Trae 等 AI IDE 提供的一种**领域专家提示词包**机制。

简单来说，一个 Skill 就是一个放在项目目录中的 SKILL.md 文件，里面写着：

• “针对这类任务，AI 应该按什么流程操作”

• “有哪些常见坑需要避开”

• “应该优先使用哪些工具或接口”

当你在 AI IDE 中触发某个 Skill 时，AI 会先读取这个 SKILL.md 的指引，然后再按照你的具体需求来生成代码。这样一来，AI 的行为变得更加稳定、专业，减少了”凭空猜接口名””乱用参数”这类常见问题。

你可以把 Skill 理解为：给 AI 提前”培训”了一套领域规范，让它在特定任务上表现得更像一个有经验的 GdiSDK 开发者。

为什么推荐使用 gdisdk-skills？

直接让 AI 帮你写 GdiSDK Pipeline 脚本，往往会遇到以下问题：

• AI 不清楚有哪些模块可用，容易编造不存在的模块名或端口名

• AI 不了解 GdiSDK 的 Pipeline 组织规范（例如 add_module、add_links、add_attribute 的正确用法）

• AI 不了解 PythonCoder 的 @local_function 装饰器规则，导致本地函数写法错误

• AI 不了解「一条 Pipeline 一个文件夹」的目录约定，容易把 .pipe / run_trace 和源码混在一起，或把 workspace 写成某台机器上的绝对路径

• AI 不了解 GDIM 上传对 Pipeline 脚本的兼容性约束，导致上传后运行失败

gdisdk-skills 正是为解决这些问题而生的。它把 GdiSDK 开发中最容易出错的几类任务，整理成了一套可复用的操作流程，让 AI 在生成代码时有规范可依，而不是凭经验瞎猜。

Tip

即使你对 AI 编程还不熟悉，安装 gdisdk-skills 也不会影响你的正常开发流程。 Skills 只在你主动触发时才会介入，不会改变 IDE 的默认行为。

gdisdk-skills 仓库

gdisdk-skills 是一个开源 Skill 仓库，托管在 Gitee 上：

https://gitee.com/jimmy_kl/gdisdk-skills

仓库中的 Skill 分为两类：

• **应用创建 Skill**（gdim-app-*）：GDIM 中有五类 Pipeline 应用，每类一个 Skill，负责生成对应类型的 Pipeline 创建脚本。类型划分见 GDIM应用类型 (App Types)。

• 通用辅助 Skill：本地函数编写、目录整理、上传检查。既可以在应用创建后使用，也可以单独使用。

Skill 名称	作用
gdim-app-custom	自定义应用：通用数据处理、计算、绘图、表格/文件输出
gdim-app-data-update	自定义数据更新配置（也称「表格数据更新」）：只返回列数据或表数据，由平台预览后写入
gdim-app-map-poi	地图兴趣点弹窗：GDIM 地图应用中点击兴趣点后弹窗里运行的 Pipeline
gdim-app-data-exchange	数据对接：GDIM 数据的导出（GTB / 第三方格式）与导入
gdim-app-report	自动报告：按 Word 模板生成报告文档
local-function-coder	为 PythonCoder 模块编写或修复 @local_function 本地函数
pipeline-organizer	把仓库里的 Pipeline 脚本整理成「一条 Pipeline 一个文件夹」：源码与 README 在根目录，.pipe / run_trace 等产物放入 workspace/
pipeline-gdim-review	在 Pipeline 脚本完成后，检查其是否满足 GDIM 上传的兼容性要求

安装 Skills

安装前提

在安装 Skills 前，请确认以下条件：

1. 你的项目根目录中已有 gdisdk 文件夹（而不是仅安装在虚拟环境中）

2. 你使用的是 Cursor 或 Trae IDE

项目内安装（推荐）

1. 访问 gdisdk-skills 仓库，克隆或下载仓库。

2. 将 skills/ 目录下需要的 Skill 文件夹复制到你的项目目录中：

   • Cursor：复制到 .cursor/skills/

   • Trae：复制到 .trae/skills/

   复制完成后，项目目录结构类似于：

   your-project/
   ├─ .cursor/
   │  └─ skills/
   │     ├─ gdim-app-custom/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     ├─ gdim-app-data-update/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     ├─ gdim-app-map-poi/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     ├─ gdim-app-data-exchange/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     ├─ gdim-app-report/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     ├─ local-function-coder/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     ├─ pipeline-organizer/
   │     │  ├─ SKILL.md
   │     │  └─ scripts/
   │     └─ pipeline-gdim-review/
   │        ├─ SKILL.md
   │        └─ scripts/
   └─ gdisdk/
   

全局安装

如果你希望在多个项目中共享这些 Skills，可以将它们安装到全局目录：

• Cursor（Windows）：C:\Users\<你的用户名>\.cursor\skills\

• Cursor（macOS/Linux）：~/.cursor/skills/

• Trae：参考 Trae Skills 文档

安装后验证

重启 IDE 后，在 Agent / Chat 输入框中输入 /，确认能看到已安装的 Skill 名称（如 gdim-app-custom）。如果之前安装过旧版的 pipeline-creator 或 pipeline-gdim-data-update，请删除这两个文件夹，避免新旧 Skill 同时触发。如果看不到，请检查目录位置是否正确，以及 SKILL.md 文件是否存在。

llms.txt（文档索引）

公开文档站点还提供机器可读的 llms.txt，格式遵循 llms.txt 标准。 其中总结了 GdiSDK 的定位、核心概念，以及在线手册主要章节（入门、用户指南、运行机制、模块帮助、端口类型与数据结构、学习案例、API 参考等）的链接与提要， 便于 AI 编程助手在不翻阅整站的前提下，先建立一份可靠的「文档地图」，从而在讨论架构选型或查阅模块能力时少猜接口、少编造章节。

它与本章介绍的 gdisdk-skills 是互补关系：

• Skills：嵌入在项目或 IDE 中的 SKILL.md，在生成 Pipeline、编写本地函数、整理目录或做 GDIM 上传检查时给出**可执行的流程与约束**。

• llms.txt：托管在文档站点上的一份总索引，更适合作为对话上下文、规则引用或可被抓取的全局说明。

你可以在对话里粘贴 llms.txt 全文或其主要段落，也可以直接向助手提供上述 URL；若所用工具支持「文档索引 / 允许的上下文 URL」，可将该地址一并配置。

Skill 详解

gdim-app-*：按应用类型生成 Pipeline 脚本

五个 gdim-app-* Skill 共用同一套搭建步骤（见 工作流构建 (Pipeline Build)），区别在于各类应用在 GDIM 上的运行约定：

Skill	适用需求	关键约定（详见对应文档）
gdim-app-custom	读取数据、计算、绘图、输出表格或文件，由用户在应用界面操作	按需暴露参数与返回结果；见 工作流构建 (Pipeline Build)
gdim-app-data-update	计算或推荐某列/某表的数据，由平台预览后写入	上传的 .pipe 中不能有 GdimTableWriter；子表用 auto_bind="pk_field"；见 GDIM数据更新 (Data Update)
gdim-app-map-poi	地图应用中点击兴趣点后的弹窗内容	用 auto_bind="poi_field" + bind_field 接收点位；见 GDIM地图弹窗 (Map POI Popup)
gdim-app-data-exchange	导出为 GTB / 第三方格式，或从文件导入 GDIM	导出用 ExportGdimTables``（``save_to_gdim=True）；导入保留 GdimTableWriter；见 GDIM数据对接 (Data Exchange)
gdim-app-report	按 Word 模板生成报告	DocDataWriter → MergeDocData → DocPrinter``（``save_to_gdim=True）；见 GDIM自动报告 (Report App)

如何选择

一般不需要你自己选。直接描述需求即可，AI 会根据各 Skill 的描述判断应用类型，并在开始前向你确认。类型不明确时（例如”导出 Excel”可能是自定义应用，也可能是数据对接），AI 会先问清楚再动手。

显式触发：在 Chat 中输入 /gdim-app-custom、/gdim-app-data-update 等来指定 Skill。

推荐 Prompt 示例

请使用 gdisdk 创建一个 GDIM 自定义应用：
从 GDIM 读取钻孔一览表，过滤掉深度小于 10m 的钻孔，
然后按钻孔编号排序，以表格形式返回结果。

做一个 GDIM 自定义数据更新配置应用：根据岩芯长度和进尺计算岩芯采取率，
只返回岩芯采取率这一列，由平台预览后写入。

Note

这些 Skill 在需要 PythonCoder 本地函数时，会自动衔接 local-function-coder 的能力，通常无需你再单独触发一次。 生成脚本后，它们还会提示你使用 pipeline-organizer 整理目录、 使用 pipeline-gdim-review 做上传前检查。

local-function-coder：编写 PythonCoder 本地函数

PythonCoder 是 GdiSDK 中用于执行自定义 Python 逻辑的特殊模块，它的核心是一个用 @local_function 装饰的函数。这个 Skill 适合以下场景：

• 你需要为现有的 PythonCoder 模块补写本地函数实现

• 你需要排查本地函数的端口名、返回值类型不匹配等问题

• 你需要为 PythonCoder 编写 update_ui_schema 动态 UI 函数

触发方式

显式触发：在 Chat 中输入 /local-function-coder。

隐式触发：当你描述”为 PythonCoder 写一个函数，实现 XXX”时，AI 会自动使用此 Skill。

推荐 Prompt 示例

请帮我为 PythonCoder 编写一个 local function，
实现根据输入的表格数据计算每行的平均值，
并将结果作为新列输出。

pipeline-organizer：整理 Pipeline 目录

这个 Skill 负责把已经写好（或刚拷进仓库）的 Pipeline 脚本对齐到统一目录约定：一条 Pipeline 一个文件夹。源码和说明留在 Pipeline 根目录，运行产物全部进 workspace/。适用场景包括：

• 你刚用某个 gdim-app-* Skill 生成了脚本，需要把 .pipe、run_trace 从源码目录挪走

• 你把现有 Pipeline 拷进 gdim/、projects/ 或个人 *App/ 目录，目录还不规范

• 多个生成脚本挤在同一个领域目录里，只靠 workspace/<AppName>/ 区分

• workspace 写成了 C:\Users\... 这类本机绝对路径，或仍带有旧前缀 pipelineApps/

• Pipeline 根目录缺少 README.md，或脚本还在 from gdi ... 而不是 gdisdk

目标目录

<领域目录>/                      # 只负责分组，例如 gdim/cadDrawing/
└── <pipeline-root>/             # 一条 Pipeline 一个文件夹
    ├── xxxPipeline.py           # 生成脚本放在该文件夹根目录
    ├── README.md                # 必填：用途 + 创建所用 GdiSDK 版本
    ├── *.py                     # 可选：本地函数、辅助模块
    └── workspace/               # 全部生成 / 运行产物
        ├── Xxx.pipe
        ├── run_trace.json
        └── run_trace.html

领域目录不要同时放多条生成脚本。应拆成子文件夹，例如 gdim/cadDrawing/createGeoSections/ 与 gdim/cadDrawing/updateGeoSections/。

``workspace`` 写法

workspace 必须由脚本文件位置推导，指向该 Pipeline 自己的 workspace/，不要再套一层应用名，也不要写某台机器上的绝对路径：

from pathlib import Path

_SCRIPT_DIR = Path(__file__).resolve().parent
WORKSPACE_DIR = _SCRIPT_DIR / "workspace"

pipeline = PipeLine(..., workspace=WORKSPACE_DIR)
pipeline.save_pipeline(f"{pipeline.workspace}/{pipeline.app_name}.pipe")

README 与 GdiSDK 版本

每个 Pipeline 文件夹都要有自己的 README.md``（不要在父目录写一份覆盖多条 Pipeline）。其中「创建所用 GdiSDK 版本」只能由该 Pipeline 的作者填写或确认；不要用当前环境里的 ``gdisdk.__version__ 自动填数。若 README 里已有版本号，整理时保持原样。

``gdi`` → ``gdisdk``

整理时默认把 Python 导入改成 gdisdk``（``from gdi.X import Y → from gdisdk.X import Y）。只有当你**明确**要求继续使用 gdi``（例如「用 gdi」「保持 gdi」「不要改成 gdisdk」）时才跳过这一步。仓库里存在 ``gdi/ 目录、旧注释或残留 import gdi，都不算这种明确要求。

布局扫描脚本

Skill 自带只读扫描脚本，不会改文件。在仓库根目录执行：

python .cursor/skills/pipeline-organizer/scripts/scan_layout.py
python .cursor/skills/pipeline-organizer/scripts/scan_layout.py --root gdim/cadDrawing

若你明确要求保持 gdi 导入，加上 --keep-gdi，扫描结果里就不会再把 import gdi 报成待修复项。默认会扫描 gdim/、projects/ 以及名称以 App 结尾的个人目录，并跳过 gdi/、gdisdk/ 这两个 SDK 包本身。

触发方式

显式触发：在 Chat 中输入 /pipeline-organizer，并给出要整理的路径。

隐式触发：当你说「整理 / 规范 / 对齐 Pipeline 目录」「一条 Pipeline 一个文件夹」，或把现有 Pipeline 拷进 gdim/、projects/、*App/ 时，AI 会自动使用此 Skill。

推荐 Prompt 示例

请整理 gdim/cadDrawing 下的 Pipeline 目录，
按一条 Pipeline 一个文件夹对齐，产物放到 workspace/。

Note

这个 Skill 只整理目录、路径和导入，不会改写 Pipeline 业务逻辑， 也不会擅自重新生成 .pipe。需要新产物时请明确说一声。

pipeline-gdim-review：上传前兼容性检查

在将 Pipeline 上传到 GDIM 之前，建议先用这个 Skill 做一次检查。它的适用场景包括：

• 检查 Pipeline 脚本是否满足 GDIM 的序列化要求

• 确认 PythonCoder 的本地函数引用是否合规

• 检查返回结果的格式是否适合 GDIM 前端消费

• 按应用类型检查专属约定（例如自定义数据更新配置应用的 .pipe 中不能有 GdimTableWriter）

• 检查脚本中是否写死了账号密码

触发方式

显式触发：在 Chat 中输入 /pipeline-gdim-review，并附上你的 Pipeline 脚本。

推荐 Prompt 示例

请帮我检查这个 gdisdk 创建的 pipeline 是否可以上传到 GDIM：
[粘贴你的 Pipeline 脚本]

推荐开发工作流

各 Skill 之间有明确的分工，按照以下顺序使用效率最高：

0. 确定应用类型           ← 自定义应用 / 自定义数据更新配置 / 地图兴趣点弹窗 / 数据对接 / 自动报告
       │
       ▼
1. gdim-app-*             ← 描述需求，生成对应类型的 Pipeline 脚本
       │
       │ （如果 Pipeline 中有 PythonCoder）
       ▼
2. local-function-coder   ← 补写或修复 @local_function 本地函数
       │
       ▼
3. pipeline-organizer     ← 整理为一条 Pipeline 一个文件夹
       │
       ▼
4. pipeline-gdim-review   ← 上传前做兼容性检查
       │
       ▼
    上传到 GDIM

Tip

通常情况下，从对应的 gdim-app-* Skill 开始就够了。它会在需要时自动引入 local-function-coder 的能力。只有当你已经有了 Pipeline 脚本、 只是需要修一个本地函数时，才建议单独使用 local-function-coder。 脚本已经能跑、只是目录混乱时，直接用 pipeline-organizer 即可。

参考资料

• GdiSDK 文档索引 llms.txt（线上） · llms.txt 标准说明

• gdisdk-skills 仓库

• Cursor Skills 文档

• Trae Skills 文档