第十二章：贡献指南与社区

本章写给希望为 OpenGIS-Skills 贡献新技能或参与社区建设的读者。无论你是 GIS 开发者、CAD 工程师、C# 后端程序员还是 AI 技术爱好者，只要你掌握某个专业工具的用法，就可以通过本章的指引把你的知识沉淀成一份 SKILL.md，让成千上万的开发者在 AI 对话中受益。

OpenGIS-Skills 的生命力来自社区共建。一个人的知识边界有限，但当一个 GIS 老手贡献 GDAL 技能、一个 CAD 工程师贡献 FreeCAD 技能、一个 C# 后端贡献 SqlSugar 技能时，整套技能集的价值就会指数级增长。114 个技能只是一个起点——你的贡献才是这个项目真正的未来。

在开始之前请明确一点：你不必是所贡献工具的”核心开发者”，也不必是行业顶级专家。只要：

• 你至少用这个工具完成过 2-3 个实际项目
• 你愿意花时间查阅官方文档验证 API 的正确性
• 你乐意遵循第三章的编写规范来组织内容

那么你就具备贡献一个高质量技能的能力。关于编号——本教程中部分篇章（特别是第十章和第十一章）也可能还在逐步出版中；若你在阅读本章时发现尚缺某章的链接，请以 GitHub 仓库 上的最新状态为准。

12.1 为什么贡献

在提笔写第一个 SKILL.md 之前，理解贡献的动机很重要——它决定了你在遇到困难时是否会坚持下去。

12.1.1 让 AI 更好地服务 GIS/CAD 开发者社区

当前 AI 编程助手在 Web 开发和通用脚本编写方面表现不俗，但在专业领域（特别是 GIS、CAD、IoT 这类小众但技术纵深极深的领域）仍然频频失误。通用大语言模型的能力存在明确短板：

• Gemini 和 GPT-4 对 GDAL 的 OGR SQL 语法掌握程度不一致，某些方言特性会被它当成”标准 SQL”来处理
• Claude 3.5 在 FreeCAD 的 PartDesign 脚本中，可能混淆 App.ActiveDocument 和 Gui.ActiveDocument 的使用场景
• 主流模型对 GeoServer REST API 的理解往往停留在 2.x 早期版本，SLD 1.1 的某些标签写法被频繁编造

每一个你贡献的技能文件，就是一份”喂给 AI 的正确答案”。一次编写，所有 AI 工具使用者受益——今天加载了你写的 GDAL 技能的人，明天就不会再被 AI 编造出来的 gdal.ProjectVector() 浪费半小时排查时间。你贡献的不只是一份 Markdown 文档，而是无数开发者在暗夜中排查 bug 时的一份可靠参照。

12.1.2 一次编写，所有 AI 工具使用者受益

OpenGIS-Skills 的独特之处在于它的”纯文本 + 标准格式”设计。SKILL.md 不绑定任何特定 IDE 或平台：

• Claude Code / Cursor 通过 .claude/skills/ 或 .cursorrules 加载
• OpenCode 通过 opencode.json 的 skills 配置项加载
• Cline / Roo Code 通过 .clinerules 或自定义指令加载
• GitHub Copilot 通过自定义指令（Custom Instructions）加载
• Aider 通过 --read 参数或 .aider.conf.yml 的 read 配置加载

一份 SKILL.md 写好后，可以不加任何修改地在上述所有工具中生效。你在 FreeCAD 技能里写下 PartDesign.Body.newObject('PartDesign::Pad') 的正确调用方式，明天有人用 Cursor 做 CAD 脚本开发时 AI 就能正确生成代码，有人用 Claude Code 做同样的事也一样受益。这种”编写一次、处处运行”的传播效率，远超传统文档（只能给人看）或传统代码库（有平台依赖）。

12.1.3 开源协作的乐趣

参与开源项目不同于在公司内部写文档——你会收到来自全球开发者的反馈、建议和感谢。你的一个 PR 可能被远在德国斯图加特做空间数据处理的人看到，或者被某个在东京研究无人机点云算法的工程师引用。这种”你的知识影响到了你从未见过的人”的体验，是闭门造车所无法获得的。

此外，open source 协作的副产品也很有价值：

• Git 协作经验：学会 Fork、分支管理、PR 描述、Code Review，这些技能在任何技术团队中都是加分项
• 文档工程能力：编写给 AI 看的高信息密度文档，和编写给人看的教程完全不同——你会获得一种新的表达技巧
• 英语写作练习：frontmatter 的 description 和代码注释中的关键技术名词需要用英文书写，这是一次低成本的国际化写作训练

12.1.4 在贡献过程中加深对工具的理解

费曼学习法（Feynman Technique）的核心思想是：”如果你不能简单地解释一个概念，说明你并没有真正理解它。”编写一份 SKILL.md 正是这种”费曼练习”的极致场景：

• 你需要把工具的核心 API 用尽可能简洁的代码示例展示出来——这意味着你必须筛选出”真正重要的那 20%”，而不是照搬官方文档
• 你需要整理 FAQ——这意味着你必须回忆并总结自己踩过的坑、见过的典型错误
• 你需要写完整工作流——这意味着你必须验证自己的理解是否正确，因为 AI 会按照你写的流程去生成代码

不少贡献者在完成第一个 SKILL.md 后反馈：”写了技能的这三天，比用这个工具用了三个月学到的东西还多。”因为被迫”把隐性的经验知识显性化”这个过程，本身就是最高效的学习。

12.1.5 构建个人/团队的技术影响力

在技术社区中，贡献开源项目是最有效的个人品牌建设方式之一：

• 你的 GitHub 贡献记录会被招聘人员和技术负责人看到
• 你的名字会出现在 OpenGIS-Skills 的贡献者列表中，关联到每个被你创建或大幅改进的技能
• 如果你代表公司/团队贡献技能，这本身就是一种技术营销——展示你们团队在特定领域的专业深度
• 一份被社区广泛使用的 SKILL.md，其影响力可能远超你写的一篇博客文章——因为前者是”嵌入到他人日常工作流”的，后者只是”被搜索引擎收录”

提醒：贡献的起点不需要很高。哪怕是修正了一个拼写错误、补充了一个缺失的 CLI 参数、修正了一个已过期的文档链接，都是有意义的贡献。GitHub 上最活跃的贡献者，往往就是从修一个拼写错误开始的。

12.2 贡献方式

OpenGIS-Skills 接受三种层次的贡献，你可以根据自己的时间和能力选择最适合的方式。三种方式的门槛从低到高排列，但价值并不因门槛低而打折——一份清晰的 bug 报告和一个新技能 PR 同样重要。

12.2.1 方式一：贡献新技能

适合： 你希望让 AI 更好地支持某个你熟悉的开源项目，但该项目的技能文件尚不存在。

典型场景：

• 你是一个 pgRouting 的长期用户，但 gis/pgrouting/SKILL.md 还没人写
• 你的团队重度依赖 AutoGen 做 GIS 相关的多 Agent 协作开发，但 ai/autogen/SKILL.md 缺失
• 你发现 CloudCompare 在点云数据处理领域非常重要，但 gis/cloudcompare/SKILL.md 还没有人写

贡献新技能是三种方式中工作量最大但影响也最持久的方式。一个新技能从无到有地被创建后，所有使用该工具的 AI 编程助手用户都会直接受益。关于具体流程，详见 12.3 新技能贡献流程。

12.2.2 方式二：改进现有技能

适合： 你发现已有技能存在错误、过时信息或可以增强的地方，希望帮助改善它。

典型改进场景：

• 修正错误：GDAL 技能中的某个 API 参数名写错了、ogr2ogr 的某个命令行选项的默认行为描述有误、FreeCAD 技能中引用的类名拼写错误
• 补充新版本特性：某个工具发布了新版本，新增了重要的 API 或 CLI 命令，需要同步更新技能文件。例如 QGIS 3.40 新增的处理算法、CesiumJS 1.120 引入的新 API
• 增加代码示例：某个技能只有基础 API 列表面面俱到但缺少完整场景的代码，你可以补充一个从数据读取到结果可视化的端到端示例
• 完善 FAQ：你在使用该工具时遇到了技能 FAQ 中没有覆盖的问题并自行解决了，可以将问题和解法添加到 FAQ 表中
• 修正文档链接：官方文档迁移到新域名后，技能中的旧链接全部失效，需要批量更新

改进现有技能的流程比创建新技能简单得多，通常一个 commit 就能完成。详见 12.5 改进现有技能。

12.2.3 方式三：反馈问题

适合： 你发现了 bug、想到了新功能点子、或者注意到技能内容已经过期，但目前没有时间或能力自己修改。

反馈问题的方式：

1. Bug 报告：某个技能中的命令无法运行、API 签名与实际不符、某个示例代码在执行时报错
2. 功能建议：建议新增某个分类、建议增加对某个工具的覆盖、建议改进索引结构
3. 内容过时报告：指出某个技能的信息对应的是两年前的版本，当前版本行为已经改变

要提交问题反馈，打开 GitHub Issues，点击 “New Issue”，选择合适的模板（如果有）或用自由格式描述。一个高质量的问题报告应当包含：

## 描述
[清晰描述问题或建议]

## 涉及文件
[具体哪个 SKILL.md 的哪个章节]

## 预期行为
[你期望的正确内容应该是什么]

## 补充信息
[环境、版本号、相关链接等]

即使只是提 Issue 而没有提交代码，你仍然帮助了社区——维护者可能没有注意到某些角落的问题，而你的反馈就是触发改进的开关。

12.3 新技能贡献流程

贡献一个新技能需要六步，每一步都有明确的产出物和要求。整个流程设计的目标是降低维护者的 Code Review 负担，同时保证新增技能的质量与现有技能库一致。

第一步：确认范围

在动笔之前，先用以下四个问题做一次”可行性检查”，避免写了半天发现不符合收录标准而白费功夫。

问题一：该技能所代表的项目是否是开源的？

OpenGIS-Skills 的立场是服务于开源工具社区。所覆盖的项目原则上应该是开源的（OSI 认可的许可证），包括但不限于 MIT、Apache 2.0、GPL、LGPL、BSD 等。如果项目是闭源的（商业专有软件），一般不予收录。不过有一个例外：如果某商业产品提供了公开的、免费的 REST API 或 Python SDK（例如某些在线地图服务），且 API 文档完全公开，则可以考虑收录。

问题二：是否在 GIS/CAD/C#/AI/IoT/3D/Others 领域内？

仓库目前覆盖 8 个分类——6 个专业领域加 1 个杂项分类（others）和 1 个演示项目分类（demos）。你需要判断你的技能属于哪个分类：

如果项目属于上述领域之一，继续往下；如果不确定，先提 Issue 询问。宁可多花 1 分钟确认分类，也不要等写完 500 行 SKILL.md 后发现分类不合适需要大改。

问题三：是否与现有技能有重叠？

在仓库根目录下搜索现有技能，检查是否已经有同名或功能高度重叠的技能存在。搜索方法：

# 搜索全局索引中的技能名
grep -r "你的工具名" SKILL.md

# 搜索分类索引
grep -r "你的工具名" gis/SKILL.md cad/SKILL.md csharp/SKILL.md ai/SKILL.md iot/SKILL.md 3d/SKILL.md others/SKILL.md

# 搜索 tags
grep -r "你的工具名" */**/SKILL.md

如果发现已有技能覆盖相同项目，应该选择”改进现有技能”（方式二）而非”创建新技能”。

问题四：建议先提 Issue 讨论

这是整个流程中最容易被跳过但最重要的步骤。在 Fork 仓库和动手写代码之前，先在 GitHub Issues 创建一个 Discussion Issue：

注：MapServer 技能已于 2026 年 10 月由社区补齐，以下流程示例保留以演示贡献步骤。

## 提议新增技能

### 项目信息
- **项目名**：MapServer
- **项目地址**：https://github.com/MapServer/MapServer
- **分类建议**：GIS
- **标签建议**：mapserver, wms, wfs, cgi, mapfile

### 为什么需要这个技能
MapServer 是 WMS/WFS 服务端的核心实现之一，很多 GIS 后端开发者
需要用它配置地图服务。当前 AI 对 MapServer 的 mapfile 语法和
OGC 标准参数组合理解很差，经常编造不存在的参数名。

### 我计划覆盖的内容
- mapfile 核心语法（LAYER, CLASS, STYLE, LABEL 等对象）
- ogr2ogr 与 MapServer 配合的数据准备流程
- WMS/WFS 请求参数和常见配置
- 至少 3 个完整工作流（WMS 服务发布、WFS 查询、SLD 样式绑定）
- FAQ 至少 5 条

这样做有四个好处：

1. 避免重复劳动：可能已经有人在写同样的技能但还没发 PR，通过 Issue 可以获知
2. 提前对齐预期：维护者可以告诉你”这个工具有某些特殊注意事项”或”建议把重点放在某个方面”
3. 获得社区建议：其他关注者可能补充一些你没想到但值得覆盖的知识点
4. 建立归属感：在 Issue 讨论中你就已经是社区的一份子了，而不是一个突然扔过来 PR 的”陌生人”

第二步：Fork 仓库

确认通过后，开始标准的 GitHub Fork → Clone → Branch 工作流。

# 1. 在 GitHub 上 Fork 仓库
# 打开 https://github.com/znlgis/opengis-skills
# 点击右上角 "Fork" 按钮，将仓库 Fork 到自己的账号下

# 2. 克隆你自己的 Fork
git clone https://github.com/YOUR_USERNAME/opengis-skills.git
cd opengis-skills

# 3. 添加上游仓库的远程引用（便于后续同步）
git remote add upstream https://github.com/znlgis/opengis-skills.git

# 4. 创建功能分支
# 分支命名建议：feat/[分类]/[项目名]
git checkout -b feat/gis/mapserver

# 或者对于非 GIS 分类
git checkout -b feat/ai/langchain
git checkout -b feat/cad/blender

关于分支命名的进一步说明：

• feat/ 前缀表示这是一个新功能（新技能）
• fix/ 前缀表示修正（改进现有技能）
• 中划线连接、全小写、无特殊字符

创建好分支后，确认一切就绪：

git branch  # 应该显示 * feat/gis/mapserver（或你设置的分支名）
git status  # 应该显示 "nothing to commit, working tree clean"

第三步：编写 SKILL.md

这是整个流程中最核心也是最耗时的步骤。按照第三章《SKILL.md 编写规范》的完整指导进行编写。这里做一次要点回顾，但完整规范请务必参考第三章原文。

创建目录结构

在对应的分类目录下创建以项目名命名的子目录：

注：MapServer 技能已于 2026 年 10 月由社区补齐，以下流程示例保留以演示贡献步骤。

# 例如为 MapServer 创建技能
mkdir -p gis/mapserver

文件组织结构：

gis/mapserver/
├── SKILL.md          # 主技能文件（必须）
└── reference/        # 拆分出的子文件（当 SKILL.md 超过 500 行时建议使用）
    ├── mapfile-syntax.md
    ├── wms-config.md
    └── ogc-standards.md

拆分时机：如果你的 SKILL.md 超过了 500 行，说明这个工具的体量较大，建议将某些独立主题拆到 reference/ 子目录中，每个子文件专注一个主题。主文件只保留概述、核心 API 和关键工作流，子文件中放详细语法、配置参数表等。这样 AI 在不需要那些细节时就不会加载它们，提高检索效率。

编写 SKILL.md 核心内容

注：MapServer 技能已于 2026 年 10 月由社区补齐，以下流程示例保留以演示贡献步骤。

打开 gis/mapserver/SKILL.md（以 MapServer 为例），按以下结构编写：

（1）YAML Frontmatter

---
name: mapserver
description: Use when working with MapServer, configuring WMS/WFS map services,
  writing mapfile configurations, or integrating with OGC standards. Covers
  mapfile syntax, CGI parameters, and OGC service setup.
tags: [mapserver, wms, wfs, ogc, mapfile, gis, c]
---

要点回顾：

• name 全小写、连字符分隔、与目录名一致
• description 以 Use when 开头、英文、单行
• tags 覆盖语言（如果有）和功能领域，YAML 数组格式

（2）头部引用块

# MapServer

**项目地址**：https://github.com/MapServer/MapServer
**官方文档**：https://mapserver.org/documentation.html
**许可证**：MIT
**版本覆盖**：8.x（撰写时最新稳定版为 8.2）

（3）概述

用 3-5 句话交代清楚这个工具是什么、做什么、在什么场景下用。不要写成长篇介绍，AI 需要的是快速建立”这个工具和我当前任务是否相关”的判断。

（4）环境准备 / 安装

各平台（Linux、macOS、Windows）的安装命令，并附上验证安装是否成功的方法。

## 环境准备

### Ubuntu/Debian

\`\`\`bash
sudo apt-get install cgi-mapserver mapserver-bin
mapserv -v
\`\`\`

### macOS

\`\`\`bash
brew install mapserver
mapserv -v
\`\`\`

（5）核心 API / 命令

按功能分组列出该工具最重要的 API 或 CLI 命令，每组配上可运行的代码示例。注意：

• 代码示例必须是可运行的（你在本地验证过的）
• 不要编造不存在的函数或参数
• 优先展示真实场景下的用法而非孤立的方法签名

（6）典型工作流

至少包含 1 个端到端的完整使用场景。一个好工作流的特征：

• 有明确的”输入 → 处理 → 输出”结构
• 每一步的代码/命令是独立的、可逐步骤执行的
• 能体现该工具的最核心价值（即 AI 用了这个技能后在什么场景下真正受益）

（7）常见问题（FAQ）

至少 5 条，表格形式。FAQ 是技能文件中”经验价值”最高的部分——它不是从官方文档翻译过来的，而是从真实踩坑经历中总结出来的。

## FAQ

| 问题 | 解答 |
|:---|:---|
| Q: mapfile 中的 LAYER 顺序有影响吗？ | 有。MapServer 按从下到上的顺序渲染图层，最后定义的 LAYER 在最上面。 |
| Q: 如何调试 mapfile 语法错误？ | 使用 `mapserv -nh "QUERY_STRING=map=/path/to/your.map&mode=map"` 查看错误输出。 |
| Q: WMS GetCapabilities 返回空？ | 检查 mapfile 中是否正确设置了 `WEB` 和 `METADATA` 块，特别是 `wms_title` 和 `wms_onlineresource`。 |

建议你在写 FAQ 时，翻一翻自己过去的项目历史——那些让你花了一个下午排查的”坑”，往往就是 FAQ 中最有价值的内容。

（8）参考资源

官方文档链接、相关教程、本技能拆分出的 reference 子目录索引。

质量自检清单

在继续下一步之前，用这份检查清单自检你的 SKILL.md：

如果以上全部通过，你的 SKILL.md 已经达到了提交 PR 的质量标准。

第四步：更新索引

这一步是新手最常见的遗漏点。写好了 SKILL.md 不等于完成了贡献——你还必须更新三层索引中的相关文件，让 AI 能够”发现”你新增的技能。

4.1 更新根索引 SKILL.md

仓库根目录的 SKILL.md 是全局入口文件。你需要在两个地方添加条目：

（a）技能目录列表：在对应分类下添加一行，格式为 - **[项目名]** - [description 的中文概要] — 详见 [路径]`。找到你对应的分类区块：

## GIS 技能

- **[gdal](gis/gdal/SKILL.md)** — GDAL/OGR 地理空间数据转换和处理 — 详见 `gis/gdal/SKILL.md`
- **[pyqgis](gis/pyqgis/SKILL.md)** — QGIS Python API (PyQGIS) 和 Processing 框架 — 详见 `gis/pyqgis/SKILL.md`
...
+ - **[mapserver](gis/mapserver/SKILL.md)** — MapServer WMS/WFS 地图服务配置 — 详见 `gis/mapserver/SKILL.md`

（b）标签索引：在文件末尾的标签索引区域，新增你的技能所使用的标签（如果这些标签之前不存在）。例如如果你用了 mapserver、mapfile、wms 三个新标签：

### 按标签检索

| 标签 | 关联技能 |
|:---|:---|
...
+ | `mapfile` | mapserver |
+ | `mapserver` | mapserver |
+ | `wms` | mapserver, geoserver |

注意：标签 wms 可能已经关联到 geoserver，你只需要在关联技能列表中追加 , mapserver 即可，不要覆盖已有的关联。

4.2 更新分类索引

找到对应分类目录下的 SKILL.md（如 gis/SKILL.md），在子技能列表中新增条目：

### MapServer

MapServer 是一个开源的 WMS/WFS 地图服务引擎，通过 mapfile 配置文件和 CGI 接口
发布空间数据。适用于构建 OGC 标准兼容的地图服务。

**覆盖内容**：
- mapfile 核心语法（LAYER, CLASS, STYLE, LABEL）
- WMS/WFS 服务配置与发布
- OGC 标准请求参数
- 与 GDAL/OGR 的数据处理协作

**适用场景**：构建 WMS/WFS 服务端、OGC 标准地图发布、mapfile 调试

详见：[gis/mapserver/SKILL.md](gis/mapserver/SKILL.md)

分类索引不需要面面俱到，但需要让 AI（和人类读者）在浏览分类时快速判断”这个技能是否值得进一步加载”。

4.3 索引更新自检

第五步：本地验证

在提交 PR 之前，做一轮本地验证。没人喜欢提交一个 PR 后瞬间被 CI 检查或维护者的手动审查打回来——预先做好自检，是对维护者时间的尊重，也是对自己贡献质量的负责。

5.1 检查文件编码

所有 SKILL.md 文件必须使用 UTF-8 编码（不带 BOM）。在 Windows 上尤其容易产生编码问题。

# Linux / macOS
file -I gis/mapserver/SKILL.md
# 输出应包含: charset=utf-8

# Windows PowerShell
# 用记事本打开文件，另存为 → 确认编码选择 "UTF-8"
# 或者用 VS Code 打开文件，查看右下角状态栏的编码显示

在 VS Code 中，点击右下角的编码显示（通常是 “UTF-8”），如果显示其他编码，选择 “Save with Encoding” → “UTF-8”。

5.2 检查 YAML 语法

YAML frontmatter 是 AI 发现和索引技能的入口，语法错误会导致整个技能文件无法被正确加载。

在线验证工具（任选其一）：

• YAML Lint：粘贴 frontmatter 部分检查
• 在线 YAML 解析器：检查解析结果是否符合预期

命令行工具（如果已安装）：

# 使用 yamllint（需要 pip install yamllint）
yamllint gis/mapserver/SKILL.md

# 使用 Python 检查（quick and dirty）
python3 -c "import yaml; yaml.safe_load(open('gis/mapserver/SKILL.md').read().split('---')[1])"

常见 YAML 错误：

• tags 列表中的某个标签包含冒号而没有用引号包裹
• description 跨多行但没有正确缩进（YAML 多行字符串要求后续行至少有一个空格的缩进）
• name 字段使用了保留关键字（如 yes, no, on, off, true, false）

5.3 验证链接有效性

所有 Markdown 链接（指向官方文档的、指向仓库内部其他文件的）都需要是可访问的。

# 提取所有外部链接
grep -oP 'https?://[^\s)]+' gis/mapserver/SKILL.md | sort -u

# 逐个在浏览器中打开检查（或使用 curl）
curl -sI https://mapserver.org/documentation.html | head -1
# 应该返回 HTTP/1.1 200 OK 或 301/302（重定向）

注意：GitHub 链接有时在部分地区访问受限，在验证时如果遇到单次超时不要立刻判定为死链——换个网络环境再试一次或用手机热点验证。

5.4 检查代码块语言标记

确保所有代码块都有正确的语言标记，以便 AI 工具可以高亮和识别。

# 正例
\`\`\`bash
sudo apt-get install cgi-mapserver
\`\`\`

\`\`\`python
import mapscript
mapobj = mapscript.mapObj('/path/to/mapfile.map')
\`\`\`

\`\`\`text
# mapfile 配置片段
MAP
  NAME "demo"
  STATUS ON
END
\`\`\`

# 反例
\`\`\`
# 没有语言标记的代码块
\`\`\`

对于 mapfile 这种没有对应语言标识符的配置格式，使用 text 或不指定语言（裸 ` ``` `）也是可接受的。

5.5 全文通读

最后一步也是最重要的一步：从头到尾通读你写的 SKILL.md，就像你是一个第一次接触这个工具的读者。

阅读时自问：

• 如果我不了解这个工具，读完概述后我知道它是做什么的吗？
• 如果我需要配置一个 WMS 服务，这个工作流能直接拿来用吗？
• 如果我在使用中遇到了 FAQ 覆盖范围外的错误，我还有信心继续排查吗？
• 有没有哪些句子是”废话”——删掉它信息量几乎不变？（如果有，删掉）

第六步：提交 PR

一切准备就绪，提交 Pull Request。

6.1 提交到你的 Fork

# 检查当前改动
git status
git diff

# 添加文件
git add gis/mapserver/SKILL.md          # 新技能文件
git add gis/SKILL.md                     # 分类索引
git add SKILL.md                         # 根索引

# 如果还有 reference/ 子目录
git add gis/mapserver/reference/

# 提交
git commit -m "feat(gis): add mapserver SKILL.md"

# 推送到你的 Fork
git push origin feat/gis/mapserver

6.2 Commit Message 格式

遵循 Conventional Commits 规范：

feat(分类): 简短描述

示例：

feat(gis): add mapserver SKILL.md
feat(cad): add blender SKILL.md with Python bpy API coverage
feat(ai): add langchain SKILL.md
fix(gis): correct gdal ogr2ogr -t_srs parameter description
fix(cad): update freecad PartDesign API for 1.0 changes

• feat 表示新功能/新技能
• fix 表示修正/改进
• docs 表示纯文档更新（如更新 README、修正注释）
• 括号内写分类缩写：gis / cad / csharp / ai / iot / 3d / others
• 描述部分使用英文，小写开头，无句号结尾

6.3 在 GitHub 上创建 Pull Request

推送完成后，在 GitHub 上操作：

1. 打开你 Fork 后的仓库页面（https://github.com/YOUR_USERNAME/opengis-skills）
2. 点击 “Compare & pull request” 按钮（通常在页面顶部自动出现）
3. 确认 base repository 为 znlgis/opengis-skills，base branch 为 main
4. 确认 head repository 为 YOUR_USERNAME/opengis-skills，compare branch 为 feat/gis/mapserver

6.4 PR 标题和描述模板

PR 标题格式：feat: add [项目名] SKILL.md

PR 描述模板：

## 新增技能

- **项目名**：MapServer
- **项目地址**：https://github.com/MapServer/MapServer
- **分类**：GIS
- **标签**：mapserver, wms, wfs, mapfile, ogc, gis, c
- **关联 Issue**：closes #123（如果有对应的 Issue）

## 覆盖内容概要

- mapfile 核心语法（LAYER、CLASS、STYLE、LABEL、PROJECTION 对象）
- WMS/WFS 服务配置（GetCapabilities、GetMap、GetFeatureInfo、DescribeFeatureType）
- 与 GDAL/OGR 的数据预处理协作流
- 3 个完整工作流（WMS 服务发布、动态 SLD 样式绑定、WFS 空间查询）
- FAQ 8 条，覆盖常见 mapfile 语法错误、OGC 参数问题等

## 检查清单

- [x] YAML frontmatter 完整（name、description、tags）
- [x] description 遵循 Use when... 格式
- [x] tags 覆盖语言和功能领域
- [x] 所有命令/代码已基于官方文档核对
- [x] 包含 3 个完整工作流
- [x] FAQ 8 条
- [x] 已更新根 SKILL.md 索引
- [x] 已更新分类 gis/SKILL.md 索引
- [x] 文件编码 UTF-8
- [x] 所有外部链接可访问
- [x] 没有包含第三方受限制内容

6.5 PR 提交后的跟进

提交 PR 后：

• 关注 GitHub 通知，维护者可能会在 Code Review 中提出修改建议
• 收到修改建议后，直接在你已有的分支上修改并再次 push——不要开新的 PR
• 如果 PR 超过一周没有收到反馈，可以在 PR 评论中礼貌地 @ 维护者询问进度
• 在等待期间，可以继续准备下一个技能的草稿（但不要开新 PR 以免混乱）

12.4 PR 审查标准

了解维护者如何审查 PR，有助于你在提交前就把自己放在审查者的视角上做一次预审。以下是维护者在审查技能 PR 时会逐项检查的八个标准。

标准一：YAML Frontmatter 格式和内容

这是审查的第一关，也是自动化程度最高的检查项。frontmatter 错误会导致 CI 工具或 AI 无从索引你的技能。

检查要点：

• 三个必填字段 name、description、tags 缺一不可
• name 格式正确（全小写、连字符、与目录名匹配）
• description 以 Use when 开头，英文，语义清晰——维护者会读一遍，看这条 description 是否能正确触发 AI 加载技能
• tags 覆盖合理——如果工具的主要语言是 Python，tags 中必须有 python；如果是 CLI 工具，可以不加语言标签但应补充 cli 等使用方式标签

标准二：代码示例的正确性

这一关维护者会抽样验证——不是逐行跑一遍，而是挑几个关键 API 去官方文档或本地测试环境中核实。

常见问题：

• 编造不存在的函数名/参数名（这是 AI 最”擅长”的，也是维护者最警惕的）
• API 签名使用了旧版本文档的写法
• 命令行的选项参数写成了长选项但在某些平台上不被支持
• Python 代码示例中的 import 路径错误

防御策略：你的每一条代码示例旁都应该有”来源注释”——它可能是一条官方文档的链接、你在本地跑通的截图存证，或者你项目里真实使用过的代码片段。虽然 PR 描述不要求附上这些，但你自己心里要清楚每个示例的可信度。

标准三：语言风格一致性

OpenGIS-Skills 使用”中文论述 + 原汁原味的代码/命令/API 名称”的语言混合风格。审查时会关注：

• 中文部分的表述是否清晰、准确、无歧义
• 代码块中的 API 名称、命令参数是否保持了原文（不翻译）
• 有没有”AI 套话”——那些看起来很有道理但实际上没有任何信息量的填充句。包括但不限于：
  • “显而易见”/”显然”——如果显然，为什么要写出来？
  • “简单地说”/”简而言之”——然后下面的解释并不简短
  • “此外”/”进一步说”/”更重要的是”——这些连接词本身没有错，但连续使用会让文章啰嗦
  • “通过上述分析我们可以得出结论”——直接说结论

一个实用建议：写完后把中文部分单独复制出来，在另一个编辑器里读一遍。如果你觉得某句话删掉完全不损失信息量，就删掉它。

标准四：AI 套话和填充词

这与标准三相关但更具体，因为 AI 辅助写作时特别容易产生这类问题。维护者会关注：

• 大段的”背景介绍”——例如某个工具是 1994 年由谁在哪个大学创建的。这些信息对 AI 写代码没有帮助，不应出现在 SKILL.md 中
• 重复的强调——同样的意思用两三种句式各说一遍
• 无信息量的过渡句
• 空洞的总结段落（”总之，XXX 是一个非常强大的工具…“）

标准五：标签分类是否正确

标签的准确性直接影响 AI 的按需匹配能力。审查时会检查：

• 语言标签是否正确（比如不要把 C++ 写的库标成 python）
• 功能标签是否准确（比如只做 WMS 的工具不应标 wmts）
• 标签是否与现有标签体系一致（不要自创与现有体系风格不同的标签名）

标准六：索引是否完整更新

这是最常见的驳回原因之一。维护者会检查：

• 根 SKILL.md 是否在对应分类下添加了新技能的条目
• 分类 SKILL.md 是否更新（内容是否充实，不只是敷衍的一句”详见 xxx”）
• 标签索引是否更新（新标签是否添加，已有标签是否追加关联）

标准七：文件编码是否为 UTF-8

技术原因：Markdown 文件如果使用非 UTF-8 编码（如 GBK、Windows-1252），会导致特殊字符（中文标点、图形符号、非 ASCII 的 API 名称）在不同平台上显示为乱码。AI 工具读取乱码后会产生不可预期的行为。

标准八：许可合规

• 技能文件中不能包含上游项目的受限制内容（付费文档的原文翻译、反编译代码、未公开的 API）
• 可以引用官方文档中的公开 API 签名（这属于事实性信息，不受版权保护），但不能大量复制粘贴官方教程的段落
• 如果引用了其他人的代码示例（例如从 StackOverflow 或博客中借鉴），需要注明出处
• 技能文件本身是 MIT 许可的，这意味着你愿意将你写的内容以 MIT 许可方式贡献给社区

12.5 改进现有技能

改进现有技能的工作量通常小于创建新技能，但审查标准同样严格。流程更简洁——有时一个 commit 就完成了全部改动。

12.5.1 改进的类型

A. 修正错误 这是最直接也最受欢迎的改进类型。例如：

• GDAL 技能中 ogr2ogr -t_srs 的参数格式描述错误（应该是 EPSG:4326 而不是 EPSG4326）
• FreeCAD 技能中 PartDesign.Body.newObject() 的参数写法与实际 API 不符
• CesiumJS 技能中某个 Camera API 的返回值类型标注错误

修正时需要：指出错误是什么、正确的应该是什么、最好附上官文链接或测试截图为证。

B. 补充新版本特性 当工具发布新版本时，技能文件需要跟进。例如：

• QGIS 3.40 新增了 native:shortestline 处理算法，需要在技能文件中补充
• FreeCAD 1.0 中 PartDesign 工作台的某些 API 发生了变化
• CesiumJS 1.120 引入了新的 Cesium3DTileset 配置选项

补充时注意：不要删除旧版本的信息（除非它已经完全无效且会导致错误），而是在对应 API 旁注明 （自 v1.120 新增） 或 （v1.0+ 行为变更：...）。

C. 增加代码示例 当前技能可能覆盖了 API 列表但缺少某些典型场景的完整示例。你可以补充：

• 一个”从 Shapefile 输入到 GeoJSON 输出”的 GDAL pipeline 示例
• 一个”在 FreeCAD 中通过 Python 脚本批量修改尺寸”的工作流
• 一个”使用 GeoServer REST API 批量发布图层”的脚本

D. 完善 FAQ FAQ 是技能文件中最”鲜活”的部分——每一条 FAQ 背后都有一个真实踩坑故事。如果你在使用该工具时遇到了技能中没有覆盖的问题并解决了，请务必补充到 FAQ 中。

E. 修正文档链接 官方文档迁移域名或重构目录结构后，技能中的链接可能大量失效。这类修正通常是机械性的（把 old-domain.com 替换成 new-domain.com），但非常重要——一个满篇 404 链接的技能文件比没有这个技能更糟糕。

12.5.2 改进的流程

对于较小的改动（拼写、链接修正），可以直接 commit 并发 PR：

git checkout -b fix/gis/gdal-typo
# ... 修改文件 ...
git commit -m "fix(gis): correct ogr2ogr -s_srs parameter format in gdal SKILL.md"
git push origin fix/gis/gdal-typo

PR 标题格式：fix: 修正 [技能名] 的 [具体问题]

示例：

fix: 修正 gdal 的 ogr2ogr -t_srs 参数格式
fix: 更新 freecad PartDesign API 至 1.0 版本
fix: 修复 qgis SKILL.md 中 3 个失效的文档链接

对于较大的改动（重写某个章节、全面重构某个技能），建议先开 Issue 说明你的改进计划，与维护者和其他关注者讨论后再动手。这样可以避免”你花了 5 小时重写了一个章节，但维护者认为应该保持现有结构”的尴尬局面。

12.5.3 改进的 PR 描述

## 改进说明

- **技能**：gdal
- **类型**：fix / update / enhancement
- **关联 Issue**：closes #456（如果有）

## 具体改动

### 改动 1：修正 ogr2ogr -t_srs 参数格式
- **问题**：原文写道 `-t_srs EPSG4326`，缺少冒号
- **修正**：改为 `-t_srs EPSG:4326`
- **来源**：https://gdal.org/programs/ogr2ogr.html#cmdoption-ogr2ogr-t_srs

### 改动 2：补充 GDAL 3.9 新增的 of KML 支持
- **新增内容**：GDAL 3.9 起 KML 驱动支持直接写出带样式信息

## 检查清单

- [x] 改动已在对应最新版本文档中核对
- [x] 没有删除仍然有效的信息
- [x] 文件编码保持 UTF-8
- [x] 相关索引无需更新（或已更新）

12.6 技能选题建议

以下领域特别需要贡献者（状态基于 2026 年 10 月仓库的实际覆盖情况）。如果你在以下任一工具上有实际使用经验，你的贡献将对社区产生重大影响——因为这些是目前覆盖空白、需求呼声很高但还没有人动手写的工具。

12.6.1 GIS 领域可补充

OpenGIS-Skills 的 GIS 分类当前有 40 个技能，覆盖了最核心的数据处理（GDAL、PostGIS、GeoPandas、DuckDB Spatial、SpatiaLite）、Web 服务（GeoServer、MapServer、QGIS Server）、前端可视化（CesiumJS、OpenLayers、Leaflet、Mapbox GL JS、MapsUI、Kepler.gl）、桌面/平台应用（GeoLibre、GeoNode）等方向，但仍有部分重要开源 GIS 工具未被覆盖。

Web 地图服务

Web 前端可视化

桌面 GIS 与空间分析

点云数据处理

空间数据库

12.6.2 CAD 领域可补充

当前 CAD 分类覆盖了 21 个技能，集中在 FreeCAD 生态和核心几何库，但参数化设计和工程 CAD 方向仍有明显的空白带。

12.6.3 AI 领域可补充

AI 分类当前有 17 个技能，覆盖了 MCP 协议、检索增强生成、主流 LLM 应用框架（LangChain、LlamaIndex）、本地模型部署（Ollama、Hugging Face Transformers）、自建推理服务（vLLM）、多 Agent 协作（CrewAI）与文档解析（MinerU）等能力。随着 2025-2026 年 AI Agent 和大语言模型应用生态的爆发式增长，AI 领域是当前覆盖缺口最大的分类之一。

12.6.4 C# 领域可补充

C# 分类当前有 12 个技能，集中在后端 ORM、AOP 框架与生产可观测性（Serilog / Polly / Hangfire）。.NET 生态中仍有许多常用库缺少技能覆盖。

12.6.5 IoT / 3D / Others 领域可补充

12.6.6 如何选择从哪个开始

面对这么多可补充的工具，你可能会觉得”选项太多无从下手”。一个简单的决策框架：

1. 凭经验选：你日常工作中最依赖的 3 个工具中，哪个在仓库中还没有技能？从你最熟悉的开始。
2. 凭需求选：回想一下，过去一个月你在 AI 编程助手中问过最多的专业问题是什么？问得最多的那个工具就是最该被写成技能的那个。
3. 凭优先级选：上面表格中标注了”高”优先级的工具，是社区需求最迫切的。如果你在这些工具上有经验，优先选择它们。
4. 凭体量选：如果你是第一次贡献，选一个体量适中的工具（API 数量 20-50 个左右的中型库），不要一上来就挑战 GDAL 那种上百个命令的巨无霸。

12.7 社区资源

OpenGIS-Skills 的社区建设正处在活跃发展阶段。以下是当前可用的社区入口和资源。

12.7.1 核心入口

12.7.2 Issue 和 Discussion 的使用区分

很多开源项目的新手会困惑：什么时候该提 Issue，什么时候该用 Discussion？

一个简单的区分规则：

12.7.3 获取帮助的方式

• 技术问题：在 GitHub Discussions 的 Q&A 类别下发帖。描述问题时请附上：你用的 AI 工具及版本、你加载了哪些技能文件、你给 AI 的提示词全文、AI 给出的错误回答
• 贡献流程问题：同样在 Discussions 中提问，或在相关 Issue 下 @ 维护者
• 紧急 Bug：如果发现了会导致 AI 生成危险代码的严重错误（例如安全漏洞相关的错误命令），请在 Issue 标题中标注 [URGENT] 前缀

12.7.4 订阅更新

• Watch 仓库：点击 GitHub 仓库页面右上角的 “Watch” 按钮，选择 “All Activity” 可收到所有 Issue、PR 和 Discussion 的通知
• Star 仓库：表达你的支持和关注，也有助于增加项目的社区影响力
• Release 通知：在仓库 Releases 页面可以订阅新版本发布通知

12.8 行为准则

OpenGIS-Skills 社区遵循通用的开源社区行为准则。虽然我们没有一份冗长的法律文书，但以下原则是所有参与者共同遵守的底线。

12.8.1 基本要求

尊重他人，保持专业和友善。 任何形式的骚扰、侮辱性言论、人身攻击、性别歧视、种族歧视、地域歧视都是不被容忍的。技术分歧可以激烈辩论，但必须围绕”事实与逻辑”而非”身份与立场”展开。

对初学者保持耐心。 每个人都是从零开始的。当一个新人提出一个”显而易见”的问题时，请回想你第一次接触 GIS 坐标系转换时的迷茫——那时的你也希望有人能耐心解答，而不是被甩一句”去看 PROJ 的文档”。一句有耐心的回答可能比一份详细的文档更能留住一个潜在的长期贡献者。

建设性反馈，避免人身攻击。 Code Review 中对代码的批评 != 对人的批评。当你发现一个 PR 中的错误时：

# 建设性（推荐）
"ogr2ogr -t_srs 的参数应该使用 EPSG:4326（带冒号），
不带冒号的格式只在旧版 OGR 中有效。建议参考 
https://gdal.org/programs/ogr2ogr.html#cmdoption-ogr2ogr-t_srs 修正。"

# 不建设性（禁止）
"这个参数格式都不对，你没看过文档吗？"

12.8.2 社区互动准则

• 先搜索再提问：提问前先搜索已有 Issues 和 Discussions，避免重复提问
• 在合适的频道发言：Bug 报告用 Issue，技术讨论用 Discussion，不要混淆
• 给足上下文：描述问题时附上环境信息、版本号、错误日志、复现步骤——”它坏了，帮我修”不是一个好的问题描述
• 感谢贡献者：如果有人帮你解决了问题，一句”谢谢”是最好的社区润滑剂
• 尊重维护者的时间：开源维护者多数是利用业余和周末时间维护项目，不要因为一个 PR 两天没被 review 就开始催更。一周没有回复后，可以礼貌地跟进一次

12.8.3 违规处理

如果发现有人违反行为准则：

• 轻微违规：维护者会在 Issue/PR 评论中公开提醒
• 重复违规或严重违规：维护者保留删除评论、锁定讨论、封禁账号的权利
• 如果你遭遇了骚扰或不当行为，请在 Issue 中 @ 维护者或通过 GitHub 提供的联系方式私信反馈

12.9 许可证说明

理解许可证对于贡献开源项目至关重要——它决定了你的贡献如何被他人使用，以及你能如何使用他人的贡献。

12.9.1 opengis-skills 仓库的许可证

opengis-skills 仓库整体使用 MIT 许可证。这意味着：

• 你可以自由地：使用、复制、修改、合并、发布、分发、再许可和/或销售本软件的副本
• 你需要遵守的：在所有副本或实质性部分中包含版权声明和许可声明
• 免责声明：软件按”原样”提供，不提供任何形式的明示或暗示担保

MIT 是开源社区中使用最广泛、限制最少的许可证之一。选择 MIT 的目的是最大化技能文件的传播和使用——我们不希望许可证成为任何人使用这些技能的障碍。

12.9.2 贡献者的权利

• 你保留你贡献内容的版权。你不是在”转让”版权，而是在”授予许可”——你授权仓库以 MIT 许可方式分发你的贡献
• 你的贡献以 MIT 许可证的方式被发布。当你提交 PR 并被合并后，你的贡献内容成为仓库的一部分，跟随 MIT 许可证的条款使用
• 你的名字会留在贡献历史中。Git 的 commit 记录中永久保留你的贡献记录，你的名字（或 GitHub 用户名）会作为作者出现在 git log 和 git blame 中

12.9.3 上游项目的许可证

SKILL.md 中引用的上游项目（GDAL、QGIS、FreeCAD 等）以各自的许可证为准。编写技能文件时，你不需要为引用这些项目的公开 API 信息而获得额外授权——API 签名、命令参数、功能描述属于事实性信息，不受版权保护。

但以下行为是不被允许的：

• 将上游项目的付费文档、培训材料、专有资料的实质性内容复制到技能文件中
• 反编译商业软件后将其内部 API 或未公开接口写入技能文件
• 将他人的博客文章、教程内容不加标注地全文复制作为技能文件的章节
• 包含上游项目中标注为”All Rights Reserved”或类似限制性声明的内容

如果你从某个来源（如技术博客、StackOverflow 回答）借鉴了某个代码示例的思路，建议在代码注释中注明参考来源，例如：

# 参考: https://gis.stackexchange.com/a/123456
result = processing.run("native:buffer", {'INPUT': layer, 'DISTANCE': 100})

这不仅是对原作者的尊重，也方便后续维护者追溯信息的来源。

12.9.4 简化总结

12.10 本章小结与教程结尾

恭喜你读完了全部十二章的教程。从第一章的”什么是 OpenGIS-Skills”到本章的”如何贡献和参与社区”，我们共同走过了一趟从认知到实践、从使用到贡献的完整旅程。

12.10.1 十二个篇章的回顾

现在让我们回头看看这十二个篇章各自完成了什么使命：

12.10.2 从”使用者”到”贡献者”的跨越

阅读本教程的十二个章节，你已经经历了一次角色转变：

• 第一章到第四章让你成为了一个合格的使用者（Consumer）——你知道这个仓库是做什么的、AI 如何加载它、如何在你的日常工具中配置它
• 第五章到第十章让你成为了一个高效的实践者（Practitioner）——你不仅能加载技能，还能组合多个技能完成复杂的跨领域开发任务
• 第十一章和第十二章邀请你成为贡献者（Contributor）——你有能力发现问题、改进技能、甚至创建全新的技能来填补覆盖空白

现在，是从”读者”变成”作者”的时候了。

12.10.3 下一步行动：三件今天就可以做的事

不要让你花了几小时（甚至十小时）阅读本教程的收获只停留在脑子里。以下三件事，每一件都可以在 30 分钟内启动：

第一件：克隆仓库，真正用起来。

git clone https://github.com/znlgis/opengis-skills.git
cd opengis-skills
# 根据你用的 AI 工具，参考第四章将技能目录配置进去
# 打开你的 AI 编程助手，试着说一句：
# "帮我写一段 Python 代码，用 GDAL 把一个 Shapefile 转换成 GeoJSON"

理论需要实践的检验。只有亲手把技能加载进工具、亲眼看到 AI 的回答质量发生变化，你才能真正理解这 105 个 SKILL.md 的价值。哪怕只是加载了一个 GDAL 技能和一个 QGIS 技能，也是一种全新的体验。

第二件：找到那个”还没有技能”的工具，试着写第一份草稿。

打开仓库目录，快速地对照一下：你日常工作最常用的 5 个专业工具中，有哪几个还没有对应的 SKILL.md？挑一个体量适中的（参考 12.6 节的优先级表），打开 VS Code，创建一个新目录，按照第三章的 10 节结构和本章的 6 步流程，开始写你的第一份技能草稿。

第一份不需要完美——把核心 API 写清楚、把你自己踩过的坑总结成 FAQ、附上一个你亲身用过的端到端工作流就够了。剩下的可以在 PR 的 Code Review 中由维护者和你共同完善。

第三件：将你的使用经验分享到社区。

欢迎在 GitHub Issues 中分享你的故事：

• 你用哪些技能组合完成了什么任务？
• 哪个技能的哪段内容帮了你最大的忙？
• 你在使用过程中遇到了什么困惑或发现了什么可以改进的地方？

你的分享可能成为下一位读者手中的灯塔——一个”别人也遇到过这个问题并且解决了”的故事，对于在深夜排查 bug 的开发者来说，价值不可估量。

12.10.4 写在最后

OpenGIS-Skills 是一个朴素的工程：没有酷炫的 AI 模型训练、没有复杂的知识图谱、没有高大上的自然语言处理 pipeline——有的只是一群 GIS/CAD/C#/AI 开发者把自己踩过的坑、验证过的 API、总结出来的最佳实践，一笔一画地写成结构化的 Markdown 文件，然后放进 Git 仓库里，供全世界的 AI 编程助手按需加载。

它的价值不在于技术本身有多先进，而在于”把领域知识结构化、标准化、可复用”这个想法被执行到了极致。当 114 个技能变成 100 个、200 个，当 GIS 的覆盖面从桌面工具扩展到云原生地图服务、从 2D 制图延伸到 3D 点云和数字孪生时，这套技能集将不再是”一个有用的辅助工具”，而是 AI 在 GIS/CAD 领域辅助编程的基础设施。

而这一切的推进，只取决于一件事：有没有人愿意坐下来，把 ta 知道的，写下来。

如果这本教程让你产生了”我也可以贡献一个技能”的念头——那就去写吧。不需要等”准备好的那一天”，因为你永远不会觉得自己”完全准备好了”。打开编辑器，创建第一个 SKILL.md，哪怕它只有 50 行——那也是从 0 到 1 的一步，是整个社区向前推进的一步。

感谢你的阅读。感谢你的关注。更感谢你即将做出的贡献。

Star the repo: https://github.com/znlgis/opengis-skills

教程到此结束。 共 12 章，覆盖 OpenGIS-Skills 的核心理念、三层索引架构、SKILL.md 编写规范、全部 114 个技能详解、AI 工具集成方式、实战工作流组合、最佳实践、以及贡献指南与社区。欢迎提出反馈和改进建议——这本教程本身也是一个开源项目，它的完善同样需要你的参与。