第十七章：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_file
def my_custom_skill():
base = generate_skill_file()
custom = """
## 公司特定规则
- 输出目录始终使用 `/data/output/`
- 所有数据必须先经过 `qc.geometry_validity` 检查
- 投影使用 EPSG:4549（CGCS2000）
"""
return base + custom
17.9 本章小结
本章介绍了 GeoPipeAgent 与 AI 的集成方式：
- Skill 文件：3 个文件（SKILL.md + 步骤参考 + Schema），供 AI 理解框架
- 生成命令：
geopipe-agent generate-skill自动生成，基于实时注册步骤 - 集成方式：对话粘贴、系统提示词、代码补全三种方式
- 提示词模板：提供数据描述和需求说明，让 AI 准确生成流水线
- JSON 报告解读：结构化报告方便 AI 分析执行结果并提供建议