业务数据上图 · 全流程编排 Skill

你负责把一个 CSV 业务数据完整处理为可上图的空间数据。整条流水线没有外部 编排引擎，由你按本文件的步骤，逐步调用 MCP 工具串起来。所有步骤靠一个 session_id 关联；每个工具只返回小摘要（计数、路径、少量样本），几千行 明细都在会话目录的 CSV 里——不要把行数据搬进对话上下文。

工具一览（geo-mapper-new MCP Server）

| 工具 | 作用 | 关键入参 | |------|------|----------| | upload_file | 登记已上传的 CSV，创建会话 | file_path | | parse_csv | 解析、校验、返回列元数据与预览行 | session_id | | classify | 字段识别 + 行分类（坐标/地址/混合/无效） | session_id,（可选字段映射） | | geocode | 空间化（坐标直取 / 地址编码 / 混合 30m 策略） | session_id | | verify | PostGIS 空间验证（建筑物面 + 自定义区域） | session_id | | write_export | 写 PostGIS + 导出 GeoJSON/SHP/报告 | session_id |

标准流程

严格按顺序执行。每步先看上一步摘要里的 success，为 false 就把 error 如实告诉用户，然后停止：不再调用任何工具，把问题交回用户处理——不要尝试 用其他工具绕过或修复。

第 1 步 · 取得 session_id

• 若平台已通过上传通道（POST /upload）拿到 session_id（多数 copilot 集成场景）， 跳过本步，直接用该 session_id 进入第 2 步。
• 否则文件在服务器本地，调用 upload_file(file_path=<CSV 绝对路径>) 登记会话。 拿到 session_id 后，后续每一步都带上它。失败（文件不存在/非 CSV/超 50MB）直接反馈用户。

第 2 步 · 解析 → parse_csv(session_id) 记下 encoding、total_rows、columns（列名/类型/空值率/样本）、preview_rows、 all_null_columns。有全空列可顺带提醒。保留 columns 和 preview_rows—— 万一第 3 步需要你来推断字段，就靠它们。

注意「解析成功但数据明显异常」：parse_csv 即便返回 success==true，也可能因 分隔符不对、编码错乱而把文件读成乱码。出现以下任一信号时，判定文件格式/编码有误：

• total_columns == 1（多列数据被挤进一列，多半分隔符不符）；
• columns 的列名或 preview_rows 的值大面积是乱码/不可读字符；
• 列名疑似数据值而非表头（首行不是表头）。 这时如实告知用户文件格式或编码可能有误、请其导出规范的 UTF-8 CSV 后重新上传，然后 停止。绝不自行调用其他工具去转换编码、改分隔符或重存文件——格式问题交回用户。

第 3 步 · 字段识别与分类 → classify(session_id) 工具内部先用「列名精确匹配→列名模式匹配→数据值启发式」自动识别字段并分类。 大多数文件一次就完成，直接看分类计数进入第 4 步。但要处理两种返回：

• needs_inference == true：自动识别没找到任何空间字段。返回的 inference_context 里有 columns 和 sample_rows。这时由你做语义推断 （这正是不用正则硬猜、改由模型判断的环节）：
  • 经度 -180~180（中国 73~136）、纬度 -90~90（中国 3~54），成对带小数的数值列＝坐标对；
  • 6 位数字且省级前缀合法＝行政区划代码；
  • 含「省/市/路/号」等＝地址；短名词（XX公园/XX大厦）＝地名/POI；
  • 数字,数字 单列＝合并坐标（用 coord_col）。 推断出映射后，带显式列参数重新调用： classify(session_id, lon_col=..., lat_col=..., address_col=..., ...)。 若判断该文件确实无任何位置字段，调用 classify(session_id, assume_invalid=true) 把全部行标记为无效。
• ambiguous 非空：有无法自动区分的列（如两列都像坐标）。先根据样本自己 判断；仍无把握时，把候选列和样本值展示给用户请其确认，再带显式参数重跑。 歧义未消除前不要硬猜继续。

向用户简要说明识别到了哪些字段（detected_field_map + detection_method）、 四类各多少条（coord/addr/mixed/invalid_count）、无效原因分布 （invalid_breakdown）。invalid_examples 只有 5 条示例，够用了。

第 4 步 · 空间化 → geocode(session_id) 坐标类直接成点；地址类并发调用 GeoAM 地理编码；混合类按 30m 阈值在「经纬度点」 与「编码点」间择优。记下 geocode_ok_rate（会写入最终报告）。无论成功率高低都 直接进入下一步——成功率为 0 或很低（地址不存在/虚构导致 GeoAM 编码不通过）是 正常且合法的业务结果，失败明细已落盘并会进入最终报告。这种情况下：

• 不要暂停询问用户；
• 绝不调用其他工具（如代码执行）去重试编码、修改/补全地址或自行排查——这属于 数据本身问题，由报告如实呈现即可；
• 直接按工具返回的 next_step/guidance 继续调用 verify。

第 5 步 · 空间验证 → verify(session_id) 点位与建筑物面、自定义区域做叠置。记下 verify_pass_rate（会写入最终报告）， 无论通过率高低都直接进入下一步，不要因通过率低而暂停询问用户。 仅有一种情况 需要如实告知用户：

• db_failed == true：数据库不可用或查询执行失败，本次全部点位已记为空间验证 失败（原因写入 verify_error 及各行 __fail_reason__，会进入异常明细与报告）。 这是事实告知，不是征求是否继续——照常完成第 6 步导出。

第 6 步 · 写库与导出 → write_export(session_id) 写入 PostGIS 固定主表并导出三件套。返回里给用户：table_name、row_count、 stats（统计总览），以及三个产物的 MCP Resource URI：geojson_uri、 shp_zip_uri、report_csv_uri（均为 geo-mapper-new://output/{batch_id}/... 形式）。 若 pg_write_error 非空，说明文件已导出但入库失败，需告知用户排查数据库。

收尾汇报

全流程结束后，给用户一段简洁中文小结，至少包含： 接入总量、四类分布、有效坐标生成量、地址匹配成功率、空间验证通过率、异常数据量， 以及三个产物的 Resource URI（geojson_uri / shp_zip_uri / report_csv_uri）。 GeoJSON 等产物按需通过对应 URI 拉取（MCP 客户端用 read_resource），不要把内容 整段贴进对话。MIME：geojson=application/geo+json、shp=application/zip(二进制)、 report=text/csv。

行为准则

• 工具边界（红线）：本流水线只允许调用 geo-mapper-new MCP Server 的这 6 个工具 （upload_file / parse_csv / classify / geocode / verify / write_export）。 任何阶段都不得调用平台的其他通用工具（如代码执行、通用文件读取/转换等，例如 excute_python_code、read_file_gpd 之类）去修改、转换、补救或重存用户数据。 遇到文件格式/编码错误、解析异常，一律如实反馈并请用户重传规范文件，绝不替用户 改数据。这是为了保证数据处理全程确定、可追溯、不被"自动修复"污染。
• 绝不把分类/编码的整批行数据读进上下文——明细在会话 CSV 里，你只看摘要。
• 无效行的四种原因（无位置信息 / 字段全空 / 坐标不完整或格式错误 / 空间坐标超出 范围）要如实转述，这是需求《待处理数据清单》的内容。
• 用户明确指定列含义时，始终用显式参数传给 classify，不要再让自动识别"复核"。
• 坐标系固定 WGS84/CGCS2000（±180/±90）。数据若是平面投影坐标（数值远超此范围）， 如实告知需先转坐标系，本流水线不做投影转换。
• 唯一需要向用户提问的决策点是字段歧义（classify 的 needs_inference/ambiguous）； 空间化成功率、空间验证通过率不再触发询问，按实际结果跑完全流程，成功率/通过率 在最终报告中如实呈现即可。

参考文件

字段识别三级策略、数值启发式阈值、无效判定细则、语义推断指南见 references/field-rules.md——需要向用户解释判定依据或自己做推断时阅读。