灵犀在 GIS 工程中的技术特点：一个 AI Agent 的领域实战观察

本文基于一个 .NET GIS 数据分析与质检框架的真实开发记录写成，复盘桌面 AI Agent（灵犀，金山办公）在其中承担的工作。纯技术视角，不谈产品。

0. GIS 为什么是 AI 编程能力的试金石

GIS 开发者对 AI 编程助手的疑虑通常很具体：写个 CRUD 没问题，但它知道坐标系该怎么沿着数据流传播吗？知道 Shapefile 的字段名只有 10 个字符吗？知道 GDAL 会悄悄改写你的字段名吗？知道质检报告里的 FID 为什么不能当业务主键吗？

这些问题背后是 GIS 工程的本质特征：难点不在算法，而在边角。空间分析算法是教科书内容，真正让工程翻车的是 CRS 元数据丢失、三维坐标被静默降维、DBF 字段名截断、驱动返回的 FID 语义不稳定这类“领域税”。它们不出现在教程里，只出现在血泪里。

判断一个 AI Agent 是否真懂 GIS，不能看它生成空间分析代码的流畅度，要看它处理这些边角的方式。本文从能力维度（而非任务流水账）复盘灵犀在一个真实 GIS 框架开发中的表现，每个论点都对应可验证的技术细节。

---

1. 领域知识的正确性：细节出现在正确的位置

先看一组硬事实。以下每一个细节，都不是“被修出来的”，而是要么预先设计进了契约，要么在定位后被正确归因：

• 未知 CRS 保持未知。框架的 GeoJSON 输出器曾硬编码 Wkid = 4326——任何坐标系的数据写出来都自称 WGS84。这在合成演示数据上永远不会暴露，在 EPSG:2326（米制）真实数据上就是灾难性坐标错位。灵犀给出的修复原则是三条：CRS 必须从数据源经算子沿数据流传播；未知时不按坐标范围猜测，更不伪造 4326；推断不出就显式表达未知。
• Z 值保真，但二维不补维。WKT writer 设为 OutputOrdinates = Ordinates.XYZ，PointZ/LineStringZ 全链路保留；同时二维几何不会被凭空补 Z。三维语义的“保留”和“不越界”是一体两面，缺一个都是错的。
• FID 不当业务主键。质检报告的 FeatureId 是驱动分配的要素 FID，GDAL 通常从 0 开始，跨驱动版本不稳定。灵犀不仅没有把它当稳定标识用，还把这个限制写进了文档，并让教学数据自带业务 id 字段作为正确示范。
• 字段匹配 OrdinalIgnoreCase。GDAL 数据源读回的列名是大写，用户方案里写的是小写。一个大小写差异，曾让属性完整性检查器对全数据集每个要素误报 ATTR_MISSING——质检场景下，一个字符放大成“全数据不合格”的假阳性。
• Date 字段不降级。DBF 的 Date 类型曾被映射成 String，历史数据里“1992-07-01”和“1992/07/01”从此无法区分。修复是扩展字段类型枚举，让类型保真成为契约。

这些细节的共同点：它们出现在了正确的位置。CRS 规则进了边界契约而不是散在各算子里，FID 语义进了文档而不只是代码注释，大小写匹配进了统一的属性解析接口而不是各算子各写一份。领域知识正确且被结构化，这比知识本身更难得——前者会随代码演进保持正确，后者会腐烂。

平庸实现与正确实现的分水岭，往往就一个选择：面对不确定的 CRS，是猜一个 4326 让流程跑下去，还是让未知保持未知并显式报告。前者是演示思维，后者是工程思维。

2. 计划驱动的工程纪律：先收敛问题空间，再动手

面对两轮真实测试暴露的 27 个缺陷，最自然的做法是逐个修。灵犀的选择是先写两份文档：一份 13 章的设计文档，把 27 个散点缺陷归并为五条边界契约（方案输入、要素元数据、质检、运行边界、底层写入），再一份 8 任务实施计划，每步带 checkbox、文件清单和“最窄验证命令”。

这个抽象的价值在于修复的杠杆点。比如参数反序列化问题：方案 JSON 的参数以 JsonElement 形态进入算子，直接强转失败就抛裸的 InvalidCastException。逐个修是给每个算子加 try-catch；契约化修是在反序列化边界统一归一化为 CLR 基元，再提供四个类型化参数读取器，六个算子一次受益，契约从此稳定。

同样重要的是知道不改什么。设计文档明确列出非目标：不重做执行结果公共协议、不新增 3D 几何类型枚举成员、不把 FeatureId 改成可配置业务主键。为兼容既有第三方数据源实现，新能力走可选接口（IFeatureSchemaProvider）而非破坏性修改——不实现该接口的源仍能工作，框架在写出前单次物化并推断字段并集。克制是工程成熟度的信号：没有计划约束的 AI 修改，最容易漂移成“哪里报错修哪里”的补丁堆，每处看似合理，整体越来越散。

对 AI Agent 而言这套流程尤其关键：人类工程师靠经验守住边界，Agent 靠把边界写成文档和契约来守住。

3. 验证闭环：让证据说话

灵犀在验证上的行为模式有三个层次。

红测试先行。 修复 27 个缺陷的第一步不是修任何缺陷，而是把已知缺陷的断言改成目标契约，为参数形态、输出元数据、QC 契约、CLI 行为各写一组预期失败的测试，跑一遍记录失败清单，然后才动手。修复过程中这批测试由红转绿，任务结束时成为永久回归资产。这与测试驱动开发的纪律完全一致——先定义“对”长什么样，再让实现达到它。

真实数据逼问。 合成数据测试全绿后，用 EPSG:2326 的真实 SHP 数据反复压测，缺陷数按轮次收敛：8 → 6 → 2。这条收敛曲线是质量信号——如果每轮修复只治标，下一轮会重新发现老问题，曲线不会收敛。每轮还强制配套回归测试（3 + 6 + 13 个），修复成果被固化而不是挥发。

失败路径同等对待。 退出码矩阵覆盖成功 0、失败/跳过/取消/超时/报告错误全部非零；零问题 QC 也生成报告；TotalChecked = 0 时 PassRate = 1.0 并注明“无可检查要素”而不是抛除零错误。GIS 数据管线大多跑在 CI 和批处理里，失败语义不清晰的工具等于不可运维。一个只在 happy path 上演示能力的实现，和一个把失败路径当一等公民的实现，工程成熟度差一个量级。

贯穿三个层次的是一个朴素习惯：任何结论先看证据。“修好了”必须对应一条变绿的测试，“收敛了”必须对应缺陷数的下降，“能用了”必须对应真实数据的核对结果。Agent 的输出天然自信，这套习惯是中和它的关键。

4. 问题定位能力：跨层归因

GIS 工程的依赖栈很长：业务框架 → 本地封装库 → GDAL/OGR → 原生驱动。同一个症状可能出现在任何一层。一个典型案例：

Shapefile 的 DBF 规范限制字段名 10 字符，landuse_type 写出时被 GDAL 截断为 landuse_ty（name laundering）。封装层按字段名回读属性对不上，值静默丢失——不报错，不警告，数据就是没了。灵犀的定位路径是：主仓库发现症状 → 判定根因在封装层而非框架层 → 封装层改为按字段序号映射（绕开名字这个不稳定键）→ 框架侧输出器对超长字段名主动告警。双仓库联动，子模块先独立构建测试提交，主仓库只更新 gitlink。

同类归因还发生在：写入器曾把数据源创建失败、图层创建失败、单要素写入失败吞成 Console warning 后继续跑，上层于是把“部分写入”报告为成功——修复方向是让底层把带 FID 的聚合异常完整抛上来，而不是在上层猜着兜底。调度器曾把所有异常折叠成万能字符串 SCH_UNEXPECTED，“输入文件不存在”“连接密文无效”“表已存在”三种故障无法区分——修复是沿内异常链映射到细分错误码家族。

错误码的粒度就是可运维性，异常的传播路径就是可靠性。 判断症状在哪一层、该修在哪一层，这是定位能力，不是编码能力——也是 AI 工具与 AI 工程协作者的真正分界线。

5. 知识沉淀：坑变成路标

AI 会话的默认命运是用完即弃。灵犀在这个项目里的一个显著特点是让经验离开会话、进入仓库：

• 真实数据踩过的坑（launder 截断、FID 语义、clip 逐面求交与 QGIS“先联合再裁剪”的语义差异、无效几何抛 TopologyException 的表现）被整理成教学材料的 FAQ——下一个人的路标；
• 更进一步，坑被做成了教具：教学数据集刻意注入精确数量的已知缺陷（蝴蝶结多边形、自相交线、null 属性、边界外要素……），质检评分是确定值 83.67/100——跑出的分数不对，就说明环境或步骤出了问题。把“已知答案的脏数据”作为教学设计，说明它理解可验证的教学与“跑个样子”的区别；
• 连“失败”都被做成了教学断言：演示方案里一个 item 输入不存在的文件、一个独立 item 成功、一个依赖 item 被跳过，一键脚本对包括失败在内的每步退出码做断言；
• .NET 插件体系最经典的坑（核心 DLL 被复制进插件目录导致 PluginLoadContext 加载了另一份副本、接口 Type 不一致、插件被静默跳过）被原样记录，连同解法（Private="false" ExcludeAssets="runtime"）。

工程经验从会话记录迁移进仓库，就成了团队资产——不依赖任何特定工具的存续。这是复利：第二轮踩的坑，第三轮就是别人的台阶。

6. 如实记录的另一面

技术复盘的价值在于不遮蔽短板。有两点值得如实说明：

其一，Agent 的正确性高度依赖验收标准由人定义。“真实数据矩阵”的具体数值（哪个数据集、多少要素、哪些字段）、“真实数据不能进教学材料”这类约束、“未知 CRS 保持未知”这类领域原则的最终裁量，都来自工程负责人。Agent 把这些判断执行到了细枝末节，但判断本身是人的。

其二，Agent 的输出需要核对。本次复盘中，初稿里的几处细节（某轮回归测试数、任务时间跨度、一个 API 的具体写法）与仓库记录不符，是在与 git 提交逐项核对后修正的。自信流畅的错误叙述比笨拙的正确更危险——让 Agent 的产出保持可溯源、可核对，是使用它的前提而非可选项。

---

7. 结语

回到开头的问题：AI Agent 能处理坐标系的坑吗？

这个项目的回答是：能，但前提是工作方式对了。灵犀在 GIS 工程中的优势，不体现在生成空间分析代码的速度上，而体现在几个更根本的地方：

• 领域细节的正确性——让未知保持未知、让 Z 值不降维、让 FID 不冒充主键；
• 契约先行的纪律——先收敛问题空间、明确非目标，再动手；
• 证据驱动的闭环——红测试先行、真实数据逼问、失败路径断言；
• 跨层定位的能力——知道症状在哪层、修复该在哪层；
• 知识沉淀的习惯——把坑变成 FAQ 和教具，让经验离开会话。

在这些维度上，Agent 的价值不是加速，而是维持工程质量的下限——契约不漂移、回归不缺位、坑被记录、失败被断言。

这大概就是当前阶段人机协作在 GIS 工程里比较健康的形态：人定义什么是正确，灵犀负责让正确的定义在每个角落都成立。