Skip to content

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

  1. 可视化前,将源坐标转换为 WGS84 经纬度。不要期待工具自动转换 GCJ-02 或 BD-09。
  2. 校验坐标顺序和范围:使用 [经度, 纬度];经度范围为 [-180, 180],纬度范围为 [-90, 90]。
  3. 为每个要素提供稳定且唯一的顶层 Feature.id,或添加唯一的字符串/整数属性,并把属性名传给 idField。发布器目前只对显式传入的 idField 校验唯一性;顶层 Feature.id 的唯一性需自行验证。
  4. 当线、普通点、高亮 POI 或不同专题组需要不同样式时,将它们拆分到不同数据源;GeoScene v1 没有筛选通道。
  5. 调用 publish_geodata 前,将生成的 GeoJSON 写入当前任务目录。
  6. 发布前检查根类型、要素数量、文件大小、几何类型、坐标范围和 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 成功后,每条命令只增加一个关注点,并按以下顺序执行:

  1. 使用 set_step、set_continuous、set_categorical 或 set_constant 设置一个通道。
  2. 使用 add_layer 添加第二个数据源/图层或参考 POI 图层。
  3. 必要时使用 reorder_layers 调整图层绘制顺序,layerIds 必须包含当前所有图层 ID,顺序为从底到顶。
  4. 使用 set_popup 添加详情。
  5. 需要改变导航、全屏、“回到范围”按钮或图例时使用 set_controls。fitToData: false 隐藏回到范围按钮;legend: false 隐藏图例符号与专题详情,并从截图中移除图例。图层开关列表始终保留,layerSwitcher 仍为预留标志。
  6. 使用 set_metadata 添加说明和警告。
  7. 仅当根据资源范围自动推导的视图不合适时,使用 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、strokeWidth
    • line:color、width、opacity、dash
    • fill:color、opacity、outlineColor
    • label:textField、color、size、haloColor、haloWidth
    • chart:不使用通用样式通道;通过 chartType、valueFields、colors、size、collisionMode、maxValue、labelField 和 labelFormat 配置
  • 将通道及其值传给对应命令。例如,使用 command: "set_constant"、channel: "opacity"、value: 0.75;不要自行构造 VisualValue、MapLibre paint、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 拒绝某条命令时:

  1. 保留上一次成功的场景。
  2. 读取返回的校验问题路径和代码,只修改该命令对应的参数。
  3. 检查颜色格式、通道名称、断点顺序、数据源/图层 ID、边界和弹窗格式。
  4. 如果此前没有成功创建地图,使用一个固定样式图层重试 create_map。
  5. 最小地图成功后,逐条重新添加命令。
  6. 如果相同的 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 后,使用 ![地图说明](relativePath) 插入 Markdown。报告需要地理展示时,不要只在最终回复中说明“地图已在 Canvas 打开”。
  • 地图截图是展示产物,不是分析依据;指标结论仍须来自已校验的数据和空间分析结果。
  • 截图请求失败时,根据返回的 revision、地图可用性或前端连接错误处理;不要用未经说明的 Python 示意图冒充 Geo Canvas 截图。
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall