Ran2424/transportx-agent / modules/capabilities/geo/skills
geo-visualization-explanation
Verified在 Tau 中使用 publish_geodata、present_visualization 和 capture_geo_screenshot 构建、解释、截图并调试声明式交互 Web GIS 地图。适用于发布 GeoJSON、绘制点/线/面图层、展示空间热点与专题样式、添加 POI 参考图层、切换图层、生成报告地图截图、处理选择交互,或排查任何 Invalid GeoScene 错误。不适用于普通的静态 matplotlib 图表。
地理可视化说明
使用 Tau Geo 工具发布当前会话范围内的 GeoJSON,并呈现声明式二维地图。将数据准备、地图描述和 Web 渲染分开处理。
选择工作流
- 始终先调用
publish_geodata,再调用present_visualization。呈现工具接收命令式参数,并在内部构建 GeoScene;不要手写scene、sources、layers或encoding对象。 - 先完成查询、聚合、空间关联、指标计算和结果校验,再发布数据。Geo 工具负责保存资源和表达分析结果,不代替 GIS 数据分析。
- 发布前聚合密集观测数据。
publish_geodata最多接受 50,000 个要素和 100 MiB 数据;不要把上百万个原始点发送到浏览器。
Agent 命令决策
| 当前意图 | 使用命令 | 不要做 |
|---|---|---|
| 首次展示一项分析 | create_map | 不要为同一分析连续创建多个 visualizationId |
| 叠加另一份结果或参考数据 | add_layer | 不要重建整张地图 |
| 添加或替换点位统计图式 | add_chart_layer、set_chart | 不要手工生成 SVG 或 MapLibre 图标 |
| 设置固定、分类、分级或连续样式 | set_constant、set_categorical、set_step、set_continuous | 不要生成 MapLibre expression |
| 增加可解释属性 | set_popup、set_metadata | 不要把完整属性表塞进标题或说明 |
| 改变地图视角 | set_camera 或 fit_bounds | 不要通过重新创建地图改变视角 |
| 控制图层或高亮结果 | set_visibility 或 select | 不要把临时 hover 当成 Scene 事实 |
| 删除或排序图层 | remove_layer 或 reorder_layers | 不要通过重建整个地图来改变图层顺序 |
| 清除当前可视化 | clear | 不要创建空 GeoJSON 来模拟清除 |
| 将最终地图插入报告 | capture_geo_screenshot | 不要另画一张与 Canvas 状态不一致的静态图 |
每条 present_visualization 命令只修改一个关注点。工具成功后会返回完整、递增 revision 的 GeoScene Snapshot;后续命令继续使用同一个 visualizationId。
准备 GeoJSON
- 可视化前,将源坐标转换为 WGS84 经纬度。不要期待工具自动转换 GCJ-02 或 BD-09。
- 校验坐标顺序和范围:使用
[经度, 纬度];经度范围为[-180, 180],纬度范围为[-90, 90]。 - 为每个要素提供稳定且唯一的顶层
Feature.id,或添加唯一的字符串/整数属性,并把属性名传给idField。发布器目前只对显式传入的idField校验唯一性;顶层Feature.id的唯一性需自行验证。 - 当线、普通点、高亮 POI 或不同专题组需要不同样式时,将它们拆分到不同数据源;GeoScene v1 没有筛选通道。
- 调用
publish_geodata前,将生成的 GeoJSON 写入当前任务目录。 - 发布前检查根类型、要素数量、文件大小、几何类型、坐标范围和 ID 唯一性。数据需小于 50,000 个要素和 100 MiB;超出任一限制时,先提高聚合粒度。
在 GeoPandas 中使用 idField: "id" 时,导出前显式创建该属性:
grid["id"] = grid.index.astype(str)
不要假设 DataFrame 索引会自动成为 GeoJSON 属性。
发布数据
调用 publish_geodata 时,传入 GeoJSON 相对路径、清晰的标题,并在使用属性 ID 时传入 idField。将返回的 resourceId 原样传给 present_visualization,同时使用 command: "create_map";不要自行构造数据源对象。
发布失败时,修复数据,不要移除有意义的 idField:
- 缺少 ID:确保每个要素都包含对应属性。
- ID 重复:生成确定且唯一的值。
- 坐标无效:修正坐标参考系或坐标顺序。
- 数据过大:聚合、简化或拆分数据。
渐进构建地图
从 publish_geodata 返回的资源和一个固定样式图层开始:
{
"command": "create_map",
"visualizationId": "hotspot_map",
"title": "热点分布",
"resourceId": "geo_0123456789abcdef01234567",
"sourceId": "hotspots",
"layerId": "hotspot_fill",
"layerType": "fill",
"layerTitle": "热点",
"color": "#2563eb"
}
上面的 resourceId 仅用于演示所需的小写十六进制格式。必须替换为当前 publish_geodata 调用实际返回的 ID。
create_map 成功后,每条命令只增加一个关注点,并按以下顺序执行:
- 使用
set_step、set_continuous、set_categorical或set_constant设置一个通道。 - 使用
add_layer添加第二个数据源/图层或参考 POI 图层。 - 必要时使用
reorder_layers调整图层绘制顺序,layerIds必须包含当前所有图层 ID,顺序为从底到顶。 - 使用
set_popup添加详情。 - 需要改变导航、全屏、“回到范围”按钮或图例时使用
set_controls。fitToData: false隐藏回到范围按钮;legend: false隐藏图例符号与专题详情,并从截图中移除图例。图层开关列表始终保留,layerSwitcher仍为预留标志。 - 使用
set_metadata添加说明和警告。 - 仅当根据资源范围自动推导的视图不合适时,使用
set_camera或fit_bounds。
优化地图时复用同一个 visualizationId。当用户要求在当前地图中“添加”“叠加”“标注”或“包含”内容时,更新该可视化,不要新建第二张地图。仅当用户明确要求单独地图时才创建新 ID。
遵守编码约束
- 颜色只使用十六进制字符串,例如
#2563eb、#fff、#2563ebcc或#fffc。不要使用rgb(...)、rgba(...)、CSS 变量、URL 或颜色名称。 - 透明度使用
[0, 1]范围内的数值。 - 为
step和continuous提供 2–16 个严格递增的数值断点。 set_step命令必须包含defaultValue;不要向set_continuous传入该字段。- 仅使用图层类型支持的通道:
circle:color、radius、opacity、strokeColor、strokeWidthline:color、width、opacity、dashfill:color、opacity、outlineColorlabel:textField、color、size、haloColor、haloWidthchart:不使用通用样式通道;通过chartType、valueFields、colors、size、collisionMode、maxValue、labelField和labelFormat配置
- 将通道及其值传给对应命令。例如,使用
command: "set_constant"、channel: "opacity"、value: 0.75;不要自行构造 VisualValue、MapLibrepaint、layout或 JavaScript 表达式。
组合易读的专题地图
-
点位统计图式使用
add_chart_layer添加,并使用set_chart在pie、donut和bar之间切换。图式仅适用于 Point/MultiPoint 数据。 -
pie使用 2–5 个非负数值字段,工具按每个点位的字段总和计算扇区比例。 -
donut使用单字段时,该字段必须提前计算为[0, 1]比例;使用多个字段时按字段总和绘制构成。 -
bar只使用一个非负数值字段,并必须传入正数maxValue作为柱高上限。不要让渲染器猜测全局最大值。 -
size是 16–96 像素的固定图符画布大小;柱高或扇区比例由valueFields决定。collisionMode默认为show-all,确保每个点位图式可见;只有用户接受密集点位被隐藏时才用hide-overlap。 -
需要显示标签时设置
labelField。名称字段使用text,数值字段使用integer、decimal或percent;不要把名称字段配置成数值格式。 -
图式字段、比例分母和
maxValue必须在发布前根据分析口径确定;不要把“当前视图最大值”无说明地称为百分比。 -
重叠的填充图层默认只让一个图层设置为
visible: true,其他备选图层设为visible: false。Web 地图始终显示当前图层可见性列表;不要依赖预留的layerSwitcher标志。 -
remove_layer只删除图层,不删除数据源;如果该数据源不再被其他图层使用,它会作为无可见用途的资源保留在 Scene 中。 -
reorder_layers使用完整的图层 ID 排列,顺序为从底到顶;不能只传需要移动的两个图层。 -
当用户需要理解热点与场馆或车站的相对位置时,添加参考 POI 或标签图层。
-
当地图展示场馆、车站、机场等可命名 POI 点时,除非点位极其密集或用户明确不要标注,否则应同时添加
label图层,并以名称字段设置textField;不要只画无名称的圆点。 -
使用清晰的图层标题和简短的弹窗字段。
-
“地图图例”是通用的地图内浮层,默认展开,只显示已开启图层的符号、指标名称、色带与完整分类或大小图例;普通名称标注仅出现在图层设置中,阅读视图没有图层树、计数和显隐开关。通过右上角设置入口管理全部图层,开关使用中性色;Escape 返回图例。面板沿用工作台主题,内容决定初始尺寸,支持拖动、键盘移动、Home 复位与右下角调整宽高,超出地图范围或手动缩小时内部滚动;底部说明仍可展开。同一指标共用标题,字段名和单位来自 set_popup 的 label。连续与分级按真实编码分别标识,完整区间不抽样;不推测业务分组、指标含义或风险等级。截图导出阅读版图例,省略设置控件和技术性映射备注;空间不足时明确提示调整,不截断分类。
-
已知数据源范围时,优先使用带内边距的 bounds 视图;需要刻意安排固定构图时,使用 camera 视图。
-
在回复中说明时间范围、空间范围、聚合单元、坐标参考系和重要的覆盖限制。
从校验失败中恢复
当 present_visualization 拒绝某条命令时:
- 保留上一次成功的场景。
- 读取返回的校验问题路径和代码,只修改该命令对应的参数。
- 检查颜色格式、通道名称、断点顺序、数据源/图层 ID、边界和弹窗格式。
- 如果此前没有成功创建地图,使用一个固定样式图层重试
create_map。 - 最小地图成功后,逐条重新添加命令。
- 如果相同的
visualizationId + command + layerId + channel在同一字段路径上连续失败两次,停止重试。保留最后成功的场景并报告工具故障,不要继续猜测参数。
不要反复提交互不相关的整体改写。当工具返回字段级错误时,以该错误为准。
使用地图交互上下文
- 用户在地图中点选要素、点位、矩形或当前视野后,先调用
inspect_map_context读取本轮消息显式附带的 Geo Context;不要从自然语言猜测地图选择,也不要沿用历史消息中的 Context。 inspect_map_context返回no_geo_context时,按普通对话继续。Feature Context 只返回弹窗白名单属性;需要来源校验信息时再设置includeProvenance: true。- 只有确实需要用户在地图上补充空间输入时才调用
request_geo_input。明确指定visualizationId、sceneRevision、固定mode和简短提示;Feature 模式可限制targetLayerIds与maxFeatures。 request_geo_input会等待用户提交、取消、超时、地图失效或任务中止。逐一处理submitted、cancelled、expired、invalidated、aborted,不要在取消或失效后自行重试,也不要伪造选择结果。- 用户提交后,以工具返回的冻结 Context 为事实继续分析。地图 revision 变化会使尚未提交的选择失效,但已经保存的 Context 仍是可审计的历史事实。
Canvas 视图
每个 visualizationId 对应一个地图标签。创建独立地图时使用新 ID,更新原图时复用 ID。用户要求查看已有地图时,调用 present_visualization(command="show_map", visualizationId=...);此操作仅激活 Canvas 标签,不修改地图或 revision。
将地图截图写入报告
- 完成图层、样式、说明和视角设置后,再调用
capture_geo_screenshot;传入最后一次成功结果中的visualizationId和revision。 - 工具会让工作台打开对应地图,捕获当前浏览器渲染的底图、业务图层、图例和说明,并把 PNG 保存到当前任务目录。
- 工具返回
relativePath后,使用插入 Markdown。报告需要地理展示时,不要只在最终回复中说明“地图已在 Canvas 打开”。 - 地图截图是展示产物,不是分析依据;指标结论仍须来自已校验的数据和空间分析结果。
- 截图请求失败时,根据返回的 revision、地图可用性或前端连接错误处理;不要用未经说明的 Python 示意图冒充 Geo Canvas 截图。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |