案例库/完整蓝皮书

证据边界：本文记录玄宿科技 GIS 数据发布系统的项目实践。流程、失败案例和架构取舍由案例方熊钰柯提供，尚未经过独立审计。页面截图来自案例运行环境；示例契约由 ADPS 根据公开机制整理，不代表案例方实际字段名。

案例速览

1. 先认识这条 GIS 发布链

GIS 数据发布不等于上传一个文件。系统需要识别格式，确定坐标系，处理数据，生成样式，把数据注册到 GeoServer，配置缓存，最后验证地图服务。

几个常见字段可以先用业务语言理解。

这些值在前一步产生，后一步逐值引用。名称或坐标错一位，接口可能直接失败，也可能发布出位置错误的地图。

玄宿科技的流程还跨越桌面 GIS、GDAL、PostGIS、GeoServer 和 GWC。操作顺序长期依赖工程师记忆，重复发布后很难回答“哪一次运行的哪一步出了问题”。

2. 两个现场失败改变了设计

第一个失败来自 S-57 电子海图。一组海图导入 PostGIS 后会按物标类生成上百张表，随后逐表建立 store、发布图层并组成图层组。图层组配置为 OPAQUE_CONTAINER 后，成员图层可能从 WMS 列表消失。直接请求 GetMap 返回 LayerNotDefined，HTTP 状态仍是 200。只看状态码，系统会把错误结果登记成成功。

第二个失败出现在 WMTS 瓦片请求。GetTile 返回 400，响应含有 / by zero。排查后发现 metatile 尺寸被配置为 0×0。官方文档没有说明这个取值的后果，结论来自平台实测。

两个问题分别给出了明确要求。

1. 发布接口自报成功不能作为最终验收。
2. 平台实测经验必须进入下一次运行能读取的规则，不能只留在操作人员记忆里。

3. 为什么运行期没有调用模型

团队评估过将 GeoServer REST API 封装为工具，再让模型运行时选择接口和参数。这个方案没有进入主链。GIS 发布的 workspace、store、layer、SRS 和 bbox 都有严格来源，模型重新生成会增加参数漂移风险。

与此同时，输入意图可以从数据签名确定。目录中包含 .000 文件时进入 S-57 管线，包含 .tif 时进入栅格管线。未匹配签名就返回明确错误。这里不需要模型猜测用户意图。

团队把开放判断放到设计期：Coding Agent 起草新管线，工程师审阅并完成首次运行，系统验证通过后再认证为 active。运行期只使用已认证规则。

案例方把这项取舍称为推理资产化。这个名称指一件具体的事：一次开放推理的结论写成管线声明和错误规则，后续高频运行直接复用。

“运行期零 LLM”是当前输入空间下的结果，不是系统目标，也不适合被推广为通用准则。

4. 六个阶段怎样完成一次发布

主链固定为六个阶段。每个阶段在独立子进程中运行，编排器只读取返回码、结构化输出和错误签名。

这条链刻意没有并行。案例方记录过两个数据集并发发布时，其中一个 verify 短暂出现零个瓦片请求成功。当前规模下，团队选择排队执行，换取可复现性。吞吐要求超过排队能力时，这项取舍需要重新评估。

5. 状态为什么落在磁盘上

阶段之间不共享进程内对象，状态通过文件传递。

run/
  metadata.json       # 输入签名、管线、处理结果和发布坐标
  run-state.json      # 当前阶段、重试次数和状态迁移
  verify_report.json  # 真实请求、截图和验收结论

validate 写识别结果，process 追加坐标系和 bbox，下游阶段读取这些值，不重新计算。案例方称这套结构为磁盘事实平面。它遵守“一个事实一个写入者”：同一个 bbox 只有一个权威生产阶段。

文件方式带来四个直接收益：进程退出后仍可审计；重跑时可以跳过已完成阶段；前端、命令行和执行代理共享文件契约；新子进程会加载磁盘上的最新实现。

代价也很具体。状态文件需要 schema 版本，前端轮询与命令行时间精度必须一致，错误前缀若被规则表使用就不能随意改名。部署进入多机、多租户和高并发写入后，文件真源需要迁移到支持事务和隔离的存储。

6. 发布后怎样证明地图真的能用

verify 不读取 publish 阶段的“成功”字段来替代验收。它请求真实的 GetMap 或 GetTile 地址，至少核对下面三项。

1. HTTP 状态符合预期。
2. content-type 是 image/*，响应体不是 XML ServiceException。
3. 截图或图像分析能观察到有效地图内容。

这项机制在 ADPS 中对应外部验收探针：系统离开自身状态，到真实消费端检查结果。它适用于数据库写入、文件交付、支付回执和网页发布等无法只靠内部调用结果判定的任务。

7. 一次失败怎样进入下一次运行

运行期只处理已经认识的错误签名，动作限定为 retry、abort 和 skip。缺少空间参考、海图更新链断号等问题不允许自动补猜，系统直接停止。

新的失败由人复盘，并写成五段式失败卡。

signature: "GetTile=400 and body contains '/ by zero'"
root_cause: "metatile size was configured as 0x0"
fallback: "disable the invalid metatile setting and rerun verify"
fixed_by: "set a safe SDK default"
related_rules: ["wmts-metatile-zero"]

这张卡同时保存现象、原因、当前处置、永久修复和运行规则。后续运行不需要重新阅读整篇复盘，只读取压缩后的错误签名与动作。原始事实仍可沿 source 字段回查。

8. 新能力怎样取得自动运行资格

新管线经过三个状态。

活跃管线的当前版本与认证版本不一致时，系统自动退回 candidate。一次代码修改不会沿用旧认证继续自动运行。

模型在生长期生成脚手架，人员决定是否认证，运行时只接受 active 管线。这个生命周期比“生成后直接上线”多了首跑证据和明确责任人，也比每次运行都请人批准更适合重复任务。

9. 没有运行期模型，为什么仍把它作为 Agent 案例

名称并不由是否每次调用 LLM 决定。这个系统会感知输入签名，选择能力，修改外部环境，主动验收，按错误签名回退，并通过失败卡和管线生命周期扩展能力。

它的自主范围很窄。签名空间封闭，未知输入拒绝；已接受任务必须留下可验收结果和可查询状态。若只剩一条固定脚本，没有输入识别、能力选择、外部验收和生命周期管理，把它称为 Agent 就没有额外解释价值。

10. 复制这套做法时从哪里开始

1. 选一条每周重复发生、输入类型有限、失败可以观察的发布流程。
2. 把完整流程拆成阶段，为每个阶段定义唯一输出和错误签名。
3. 标出必须由程序传递的机械参数，禁止下游重新计算或由模型生成。
4. 设计一项离开系统内部的验收，例如真实请求、回读数据库或打开交付文件。
5. 先记录三次真实失败，再决定哪些可以进入自动 retry，哪些必须 abort。
6. 为能力设置 draft、candidate、active，代码变更后取消旧认证。
7. 连续运行后再评估是否需要并行、动态规划或运行期模型。

这七步不依赖 GIS。数据导入、媒体转码、模型部署、报表发布和静态网站发布都可以使用同样的骨架。

11. 失效信号与迁移边界

错误规则和失败卡来自 GeoServer 与 GIS 领域，不能原样迁移。可复用的是阶段契约、单一事实生产者、外部验收、失败到规则的路径和能力认证过程。

12. 当前证据与下一步数据

下一版应记录每条管线的运行次数、成功率、人工接管率、verify 发现的假成功数、规则命中率和代码变更后的重新认证耗时。

13. ADPS 对照

案例提供与引用

案例提供：熊钰柯（Yuke Xiong），玄宿科技。

建议引用：ADPS、熊钰柯，《玄宿科技 GIS 数据发布 Agent：把运行经验固化成可验收管线》，ADPS 企业 Agent 系统蓝皮书·案例报告 02，v0.4，2026。