当前位置：首页 > news >正文

第十七章：Skill 文件与 AI 集成

news 2026/5/28 18:43:21

第十七章：Skill 文件与 AI 集成

GeoPipeAgent 的 AI 集成能力是其核心价值之一。本章介绍 Skill 文件的结构、生成方式，以及如何将 AI（如 ChatGPT、Claude）与 GeoPipeAgent 结合，实现自然语言驱动的 GIS 分析。

17.1 AI 集成理念

GeoPipeAgent 的 AI 集成遵循以下设计理念：

AI 是操作者：AI 负责理解用户需求、生成 YAML 流水线
框架是执行者：框架负责校验和执行 AI 生成的流水线
JSON 报告是反馈：执行结果以结构化 JSON 返回给 AI，AI 可以解读结果并给出建议
Skill 文件是接口：Skill 文件精确描述框架能力，让 AI 无需猜测

这形成了一个完整闭环：用户需求 → AI 生成 YAML → 框架执行 → JSON 报告 → AI 解读 → 用户获得结果。

17.2 Skill 文件结构

通过 geopipe-agent generate-skill 生成的 Skill 文件集：

skills/geopipe-agent/
├── SKILL.md                        # AI 入口文档
└── reference/├── steps-reference.md          # 步骤参数完整参考（auto-generated）└── pipeline-schema.md          # YAML Schema 文档

17.2.1 `SKILL.md`：AI 入口文档

SKILL.md 是为 AI 设计的简洁入门文档，包含：

框架功能概述
使用流程说明
快速 YAML 示例
步骤类别速查表
QC 步骤的"检查并透传"机制说明

geopipe-agent generate-skill --output-dir skills
cat skills/geopipe-agent/SKILL.md

17.2.2 `reference/steps-reference.md`：步骤参考

自动生成的步骤参考文档，包含每个步骤的：

ID 和名称
参数表（含类型、是否必填、默认值、说明）
输出描述
使用示例
支持的后端

geopipe-agent generate-skill-doc > reference.md

17.2.3 `reference/pipeline-schema.md`：YAML Schema

完整的 YAML 流水线格式说明，包含：

顶层结构示例
引用语法表（$step、${var} 等）
步骤 ID 规则
when 条件表达式语法
错误处理策略说明

17.3 生成 Skill 文件

# 生成到默认目录 skills/geopipe-agent/
geopipe-agent generate-skill# 指定输出目录
geopipe-agent generate-skill --output-dir /tmp/geopipe-skills# 仅生成步骤参考（单个 Markdown 文件）
geopipe-agent generate-skill-doc > my-steps-reference.md

生成的文件是基于当前注册步骤的实时快照。如果添加了自定义步骤，重新运行即可更新文档。

17.4 与大语言模型集成

方式一：直接对话（ChatGPT / Claude）

推荐工作流：

步骤1: 生成 Skill 文件
$ geopipe-agent generate-skill步骤2: 将以下内容提供给 AI（粘贴到对话中）- skills/geopipe-agent/SKILL.md（必须）- skills/geopipe-agent/reference/steps-reference.md（建议）- 数据文件信息（geopipe-agent info 的输出）步骤3: 向 AI 描述分析需求"我有一份 EPSG:4326 的道路 Shapefile，需要做 500 米缓冲区分析，先进行几何质检，有问题则自动修复，最终输出 GeoJSON"步骤4: AI 生成 YAML 流水线步骤5: 校验并执行
$ geopipe-agent validate ai-pipeline.yaml
$ geopipe-agent run ai-pipeline.yaml步骤6: 将 JSON 报告返回 AI 解读（如有错误）

方式二：系统提示词（System Prompt）

将 Skill 文件内容嵌入 AI 的系统提示词，实现持久化 GIS 分析能力：

# System Prompt（示例）你是一个专业的 GIS 分析师，使用 GeoPipeAgent 框架执行分析。## 工具说明
[粘贴 SKILL.md 内容]## 步骤参考
[粘贴 steps-reference.md 内容]## 工作规则
1. 用户提出 GIS 分析需求时，生成 YAML 流水线
2. 总是先确认输入文件的 CRS（向用户询问或通过 info 命令获取）
3. 投影坐标系中进行距离相关分析（缓冲、服务区等）
4. 对重要数据添加 QC 步骤
5. 当执行报告中有错误时，分析原因并提供修复建议

方式三：Copilot / 代码补全

将 Skill 文件放在项目目录中，让代码编辑器的 AI 助手（GitHub Copilot、Cursor 等）自动获取上下文。

17.5 提示词最佳实践

有效的需求描述模板

我有以下数据：
- 文件：[文件路径]
- 格式：[GeoJSON/Shapefile/GeoTIFF]
- CRS：[EPSG:4326 等]
- 字段：[相关字段名]
- 要素数：[数量级]我需要：
[具体分析需求，包括：- 分析目标- 输出格式和路径- 需要哪些质检- 任何特殊要求]请生成 GeoPipeAgent YAML 流水线。

示例提示词

我有以下数据：
- 文件：data/poi.geojson（兴趣点）和 data/districts.shp（行政区划）
- POI 字段：name, type, lng, lat
- 行政区划 CRS：EPSG:4326
- 约 50,000 个 POI我需要：
1. 统计每个行政区内的 POI 数量
2. 进行 DBSCAN 聚类找出 POI 热点（邻域半径 500 米，最小 20 个点）
3. 将聚类结果（去掉噪声点）输出为 output/poi_clusters.geojson
4. 先将数据转换为 EPSG:3857（米制）再进行距离相关分析请生成 GeoPipeAgent YAML 流水线，并说明每个步骤的作用。

17.6 JSON 报告的 AI 解读

执行报告的 JSON 结构设计为"AI 友好"格式，以下是示例解读提示：

以下是 GeoPipeAgent 流水线执行报告，请分析：
1. 流水线是否成功？
2. 各步骤执行情况如何？
3. 如果有 QC 问题，请说明类型和数量
4. 如果有步骤失败，请根据 suggestion 字段提供修复建议[粘贴 JSON 报告]

17.7 `skillgen/generator.py`：Skill 生成器原理

Skill 生成器位于 src/geopipe_agent/skillgen/generator.py，提供以下函数：

generate_steps_reference() -> str# 遍历 registry.list_all()，按类别生成 Markdown 参数表generate_pipeline_schema_doc() -> str# 返回预定义的 YAML Schema 文档字符串generate_skill_file() -> str# 返回 SKILL.md 内容（AI 入口文档，含快速示例）write_skill_files(output_dir) -> list[str]# 将所有文件写入目录，返回生成的文件路径列表

由于 generate_steps_reference() 从注册表实时读取，每次重新安装或添加自定义步骤后，运行 generate-skill 可更新文档。

17.8 自定义 Skill 扩展

如需在 Skill 文档中添加自定义内容（如公司特定的使用规范、常见任务模板等），可以在生成后手动编辑 SKILL.md，或在 Python 中扩展 generate_skill_file()：

from geopipe_agent.skillgen.generator import generate_skill_filedef my_custom_skill():base = generate_skill_file()custom = """
## 公司特定规则- 输出目录始终使用 `/data/output/`
- 所有数据必须先经过 `qc.geometry_validity` 检查
- 投影使用 EPSG:4549（CGCS2000）
"""return base + custom