Executor 工具算子参考手册#

基于 executor 服务代码（executor/executor/tools/）与 executor/docs/API.md 整理。
整理日期：2026-09-23。算子真值以运行时 GET /tools 为准，本文档为静态快照，共 112 个算子。
本文档已经过自动化对账（reconcile_docs.py 对照注册表运行时导出的 tools-truth.json）与多路人工复核。

一、API 总览#

1.1 服务信息#

• 默认本地地址：http://127.0.0.1:8000
• 自动文档：/docs、/redoc、/openapi.json
• 推荐联调主线：docker-env 编排 db + executor + ai-core

1.2 HTTP 端点#

1.3 调用约定（POST /execute）#

请求体：

{
  "request_id": "req_demo_001",
  "session_id": "11111111-1111-4111-8111-111111111111",
  "tool_name": "io.load_layer",
  "arguments": { "source": "admin.divisions" }
}

• request_id：调用方请求 ID，用于日志追踪
• session_id：UUID 字符串；所有 layer_id 仅在同一 session_id 下有效
• tool_name：算子名
• arguments：算子参数对象。所有算子的参数模型均为 extra="forbid"（system.echo 无参数模型，接受任意参数对象），传未定义字段返回 INVALID_ARGUMENT

请求头：配置 EXECUTOR_EXECUTE_TOKEN 后必须携带 X-Execute-Token；公共部署应设 EXECUTOR_EXECUTE_ALLOW_UNAUTHENTICATED=0。客户端前端不要直接调用 /execute，应经 ai-core/网关编排。

响应外壳（成功）：

{ "request_id": "...", "tool_name": "...", "ok": true, "result": {}, "error": null, "meta": {} }

响应外壳（失败）：

{ "request_id": "...", "tool_name": "...", "ok": false, "result": null,
  "error": { "code": "INVALID_ARGUMENT", "message": "..." }, "meta": null }

1.4 统一错误码#

1.5 通用规则#

• 会话隔离：layer_id 是 io.load_layer 等返回的 opaque handle，仅同会话可复用；跨会话使用返回 INVALID_ARGUMENT
• 只读核心 schema：admin / poi / transport / environment / knowledge / system / tkg 只读；写能力以 GET /tools 中每个算子的 writes_session 为准
• 会话写回：写会话的算子把结果物化到 session_{uuid} schema，返回新 layer_id
• session.write_stub 是保留项（仅存在参数模型），未注册、未对上游开放
• 无状态几何算子（§六）不读写数据库，失败统一返回 INVALID_ARGUMENT

1.6 文档结构约定#

• 每个算子小节标注会话属性：无（不读写任何存储）/ 读全局 / 读会话 / 写会话 的组合，与注册表 reads_global / reads_session / writes_session 一一对应
• 输入参数表统一五列：参数、类型、必填、默认、说明；— 表示无默认值（即必填或缺省为 None）
• "输出 result" 描述响应外壳中 result 对象的字段；meta 单独说明
• 写会话算子的输出图层可通过 rows.preview / stats.row_count 等继续消费

二、算子总目录（112）#

三、系统与数据加载算子#

3.1 system.echo#

• 会话属性：无（不读写任何存储）
• 用途：回显参数，通路测试。无参数模型（接受任意参数对象）。
• 输入参数：任意 JSON 对象。
• 输出 result：

{ "message": "ok", "arguments": { "...": "原样回显" } }

3.2 system.cleanup_session#

• 会话属性：无（清理自身会话产物）
• 用途：删除当前 session_id 的 session 分析产物，清理会话缓存的 layer 句柄、会话栅格与上传文件。
• 输入参数：无参数（arguments: {}，禁止额外字段）。
• 输出 result：

{
  "session_id": "11111111-1111-4111-8111-111111111111",
  "target_schema": "session_11111111-1111-4111-8111-111111111111",
  "dropped_tables": 1,
  "dropped_rasters": 2,
  "dropped_uploads": 3
}

• 规则与限制：dropped_rasters / dropped_uploads 仅在对应产物存在（非零）时出现。

3.3 schema.columns#

• 会话属性：读全局
• 用途：查看只读源表的列名与基础元信息；不生成 layer_id。
• 输入参数：

• 输出 result：{ "source": "admin.divisions", "columns": ["adcode", "name", "level", "parent_code"] }
• meta：{rows, columns, geom_type, crs}
• 规则与限制：表不存在 → INVALID_ARGUMENT；schema 不允许 → INVALID_ARGUMENT / PERMISSION_DENIED。

3.4 io.load_layer#

• 会话属性：读全局
• 用途：只读加载核心资产表，返回会话内可复用的 layer_id。
• 输入参数：

• 输出 result：{ "layer_id": "divisions_abc12345", "source": "admin.divisions", "rows": 1 }
• meta：{rows, columns, geom_type, crs}
• 规则与限制：
• 四类过滤对象必须是 object（不能是数组/字符串）；多条件之间以 AND 连接
• 不支持：范围过滤、嵌套对象、自由 SQL、原始 LIKE/IN、显式 null 过滤
• in_filters / array_contains_filters 空数组 → INVALID_ARGUMENT
• 过滤列不存在 → INVALID_ARGUMENT；过滤后 0 行不是错误，返回 ok=true, rows=0
• 注意：array_contains_filters 现行语义为 overlap（&&）；早期版本曾为"包含全部元素"（@>）

3.5 stats.row_count#

• 会话属性：读会话
• 用途：统计会话内已注册 layer_id 的行数。
• 输入参数：

• 输出 result：{ "layer_id": "...", "row_count": 1, "source": "admin.divisions" }
• meta：图层元信息 {rows, columns, geom_type, crs}。

3.6 rows.preview#

• 会话属性：读会话
• 用途：预览已加载图层的实际记录内容。
• 输入参数：

• 输出 result：{ layer_id, source, columns, returned_rows, rows }；请求的列在图层不存在时会被跳过，并以 dropped_columns 字段显式回显（order_by 指向未知列时同样降级，不报错）。
• meta：图层元信息。

四、模糊检索与地标算子#

4.1 io.fuzzy_search_poi#

• 会话属性：读全局 + 写会话
• 用途：对 POI 表做容错模糊名称检索（基于 pg_trgm similarity()），候选物化为会话图层。
• 输入参数：

• 输出 result：{ layer_id, source, rows, operation: "fuzzy_search_poi", name_query, similarity_threshold }；候选按相似度降序保存在返回的会话图层中（含 similarity_score 列）。

4.2 geo.locate_landmark#

• 会话属性：读全局 + 写会话
• 用途：地标解析——把地名（可含错别字）解析为坐标与候选列表。
• 输入参数：

• 输出 result：{ layer_id, source, operation: "locate_landmark", name_query, matched_name, matched_adcode, similarity, center, candidates }；候选项结构 {name, adcode, address, similarity_score}。center 可直接作为 rows.rank_by_distance 的 center 输入。
• 规则与限制：无候选命中时抛 INVALID_ARGUMENT。

4.3 schema.semantic_search#

• 会话属性：读全局
• 用途：对目录表（POI 类别 / 行政区划）做语义检索（向量索引）。
• 输入参数：

• 输出 result：{ query, source, typecode|adcode（Top-1 快捷字段）, matches }；matches 项 {key, score, <文本列>, sample_count?, sample_scope?}。
• 规则与限制：依赖持久化 embedding 索引；索引未就绪报 EMBEDDING_INDEX_UNVERIFIED（以 INVALID_ARGUMENT 透出）；embedding 服务失败返回 EXTERNAL_DEPENDENCY_ERROR。

4.4 tools.semantic_search#

• 会话属性：无
• 用途：对算子目录本身做语义检索（用自然语言找算子）。
• 输入参数：

• 输出 result：{ query, matches }；matches 项 {tool_name, score, tags, description_preview}。
• 规则与限制：embedding 服务失败返回 EXTERNAL_DEPENDENCY_ERROR（HTTP 502）。

五、行级排序算子#

5.1 rows.rank_by_distance#

• 会话属性：读会话 + 写会话
• 用途：对源点图层按到参考点的距离做 Top-N 排序（KNN）。
• 输入参数：

• 输出 result：{ layer_id, source, rows, operation: "rank_by_distance", center, max_distance_meters }；物化图层每行附 distance_meters。

5.2 rows.rank_layer_by_distance#

• 会话属性：读会话（不写会话）
• 用途：批量 KNN——对源图层每个要素找目标图层的 K 个最近邻，避免逐点 HTTP 调用。
• 输入参数：

• 输出 result：
• aggregate=none：{ mode: "pairs", k, pair_count, results: [{source_id, target_id, distance_m}] }
• aggregate=avg：{ mode: "avg", k, source_count, results: [{source_id, avg_distance_m}] }

六、无状态几何算子（geo.*）#

共同特点：直接使用坐标值或 GeoJSON geometry；不读写数据库；失败统一 INVALID_ARGUMENT。共同限制：geo.transform_crs v1 仅支持 EPSG:4326 ↔ EPSG:3857；不支持 GeometryCollection；几何输入必须是合法 GeoJSON geometry 对象。

6.1 geo.calculate_distance#

• 会话属性：无
• 用途：两点大圆距离。
• 输入参数：

• 输出 result：{ "distance_meters": 3266.76, "distance_kilometers": 3.26676 }（米保留 3 位，公里 6 位）。

6.2 geo.calculate_bearing#

• 会话属性：无
• 用途：点 1 指向点 2 的方位角与简化方向。
• 输入参数：

• 输出 result：{ "bearing_degrees": 86.7, "direction": "E" }（方位角 6 位小数；方向为 N/NE/E/SE/S/SW/W/NW 八方位）。

6.3 geo.get_bounding_box#

• 会话属性：无
• 用途：GeoJSON geometry 的最小外接矩形。
• 输入参数：geometry（必填，合法 GeoJSON geometry 对象）。
• 输出 result：{ "bbox": { "min_x": ..., "min_y": ..., "max_x": ..., "max_y": ... } }。

6.4 geo.get_centroid#

• 会话属性：无
• 用途：几何中心点。
• 输入参数：geometry（必填）。
• 输出 result：{ "centroid": { "type": "Point", "coordinates": [...] } }；meta：geom_type=Point。

6.5 geo.is_point_in_polygon#

• 会话属性：无
• 用途：点是否落在面内（支持 Polygon / MultiPolygon）。
• 输入参数：lon、lat（必填，经纬度范围校验）；polygon（必填，GeoJSON Polygon 或 MultiPolygon）。
• 输出 result：{ "contains": true }。

6.6 geo.transform_crs#

• 会话属性：无
• 用途：坐标系转换（v1 仅 EPSG:4326 ↔ EPSG:3857）。
• 输入参数：

• 输出 result：{ "geometry": {...}, "source_epsg": 4326, "target_epsg": 3857 }；meta：geom_type、crs=EPSG:{target}。
• 规则与限制：source_epsg == target_epsg 时原样返回（不报错）。

6.7 geo.simplify_geometry#

• 会话属性：无
• 用途：几何简化（减少节点）。
• 输入参数：geometry（必填）；tolerance（必填，>0，单位与源坐标一致）。
• 输出 result：{ "geometry": {...简化后}, "tolerance": 0.001 }；meta：geom_type。

6.8 geo.line_interpolate_point#

• 会话属性：无
• 用途：沿线按比例取点。
• 输入参数：geometry（必填，LineString）；fraction（必填，0–1）。
• 输出 result：{ "point": { "type": "Point", "coordinates": [...] } }；meta：geom_type=Point。

6.9 geo.line_substring#

• 会话属性：无
• 用途：按比例截取线的子段。
• 输入参数：geometry（必填，LineString）；start_fraction（必填，0–1）；end_fraction（必填，0–1）。
• 输出 result：{ "geometry": { "type": "LineString", "coordinates": [...] } }；meta：geom_type=LineString。
• 规则与限制：start_fraction 必须 ≤ end_fraction，否则 INVALID_ARGUMENT。

七、会话空间叠加算子（geo.* / vector.aggregate_geometry）#

共同特点：读会话 + 写会话——读会话图层，结果物化为新会话图层，返回 {layer_id, source, rows, operation, ...参数回显} + meta（rows/columns/geom_type/crs）。所有 layer_id 必须属于当前会话。

7.1 geo.buffer#

• 会话属性：读会话 + 写会话
• 用途：对图层做缓冲区（自动处理 CRS 投影）。
• 输入参数：layer_id（必填）；distance_meters（必填，>0，米）。
• 输出 result：{ layer_id, source, rows, operation, distance_meters }（新会话图层）。

7.2 geo.clip#

• 会话属性：读会话 + 写会话
• 用途：用掩膜图层裁剪目标图层。
• 输入参数：target_layer_id、mask_layer_id（均必填）。
• 输出 result：新会话图层 {layer_id, source, rows, operation, ...}。

7.3 geo.intersects#

• 会话属性：读会话 + 写会话
• 用途：以过滤图层的空间约束筛选目标图层（相交要素）。
• 输入参数：target_layer_id、filter_layer_id（均必填）。
• 输出 result：新会话图层。

7.4 geo.spatial_join#

• 会话属性：读会话 + 写会话
• 用途：两图层空间连接。
• 输入参数：left_layer_id、right_layer_id（必填）；predicate（默认 intersects，可选 contains / within / crosses）。
• 输出 result：新会话图层（回显 predicate）。

7.5 geo.difference#

• 会话属性：读会话 + 写会话
• 用途：图层差集（A − B）。
• 输入参数：layer_id_a（基础层）、layer_id_b（被减层）。
• 输出 result：新会话图层。

7.6 geo.union#

• 会话属性：读会话 + 写会话
• 用途：图层的几何合并。
• 输入参数：layer_id（必填）；group_by_column（可选，先分组再合并）。
• 输出 result：新会话图层。

7.7 geo.dissolve#

• 会话属性：读会话 + 写会话
• 用途：按列融合（dissolve）。
• 输入参数：layer_id（必填）；dissolve_column（必填，分组列）。
• 输出 result：新会话图层（回显 dissolve_column）。

7.8 vector.aggregate_geometry#

• 会话属性：读会话 + 写会话
• 用途：分组几何聚合，支持叠加模式（先与 mask 求交再按 mask 的分组列汇总）。
• 输入参数：

• 输出 result：新会话图层，每组含 area_square_meters / length_meters 统计列（按所求 stats）。

八、矢量几何分析算子（vector.*）#

8.1 vector.convex_hull#

• 会话属性：无
• 用途：凸包。
• 输入参数：geometry（必填，GeoJSON geometry；参数模型描述为 MultiPoint 或 GeometryCollection）。
• 输出 result：{ "convex_hull": {...} }；meta：geom_type。

8.2 vector.area_calculate#

• 会话属性：无
• 用途：面积计算。
• 输入参数：geometry（必填，Polygon 或 MultiPolygon）。
• 输出 result：{ "area_square_meters": ..., "area_square_kilometers": ..., "area_hectares": ... }（分别保留 3/6/6 位）。

8.3 vector.length_calculate#

• 会话属性：无
• 用途：长度计算。
• 输入参数：geometry（必填，LineString 或 MultiLineString）。
• 输出 result：{ "length_meters": ..., "length_kilometers": ... }（3/6 位）。

8.4 vector.multi_to_single#

• 会话属性：无
• 用途：Multi 类型炸开为单部件。
• 输入参数：geometry（必填，Multi* 类型）。
• 输出 result：{ "geometries": [...], "count": n }；meta：geom_type（单部件类型）。

8.5 vector.merge_layers#

• 会话属性：无
• 用途：合并多个 GeoJSON 几何 / Feature / FeatureCollection 为一个 FeatureCollection。
• 输入参数：geometries（必填，≥1，元素可为 geometry、Feature 或 FeatureCollection）。
• 输出 result：{ "merged": {"type": "FeatureCollection", "features": [...]}, "feature_count": n }。

九、Phase8 固定样本算子#

这组算子面向固定数据样本的确定性核验流程，参数中携带的 profile/版本字段由服务端核验，不代表审批或身份依据。均为读会话 + 写会话，输出含 input_validation 证据块。

9.1 vector.extract_by_location#

• 会话属性：读会话 + 写会话
• 用途：固定样本的 within 选择，仅引用当前会话图层。
• 输入参数：target_layer_id、reference_layer_id（均必填，会话图层）；predicate 固定 within。
• 输出 result：{ input_validation, layer_id, rows, operation: "extract_by_location", predicate: "within" } + 图层 meta。

9.2 vector.join_attributes_by_location#

• 会话属性：读会话 + 写会话
• 用途：固定样本的 within 首次匹配连接，不允许行扩张。
• 输入参数：

• 输出 result：连接后的新图层 + input_validation。

9.3 topo.snap_geometries_to_layer#

• 会话属性：读会话 + 写会话
• 用途：固定 420205 Point-to-Line 样本的捕捉（3 米 profile）。
• 输入参数：target_layer_id（点图层）、reference_layer_id（道路线图层）必填；tolerance_meters（>0，默认 3.0，由服务端固定 profile 核验）；behavior 固定 prefer_closest_insert_vertices；analysis_crs（默认 EPSG:4547，必须匹配服务端 profile 的原始 CRS）。
• 输出 result：{ input_validation, layer_id, rows, operation: "snap_geometries_to_layer" } + meta。

9.4 topo.delete_holes#

• 会话属性：读会话 + 写会话
• 用途：删洞保护——仅允许 NO_HOLE_DELETION 零变化保护模式。
• 输入参数：layer_id（行政区图层）、protected_holes_layer_id（保护洞图层）必填；deletion_policy 固定 NO_HOLE_DELETION；approved_threshold_m2 固定 0（ge=0, le=0）；auto_delete_allowed 固定 false；analysis_crs（默认 USER:100001，自定义 Albers 别名，按原始 WKT 解析，不是 EPSG 编号）。
• 输出 result：{ input_validation, layer_id, rows, operation: "delete_holes" } + meta。

9.5 vector.split_with_lines#

• 会话属性：读会话 + 写会话
• 用途：固定 422823 样本（一面七线）分割线切割。
• 输入参数：layer_id（目标面）、split_layer_id（切割线）必填；split_layer_version（可选兼容字段，必须与服务端实际 SHA256 一致——允许 sha256- 前缀、大小写不敏感，不作为身份依据）；approved_for_split（可选兼容提示，Literal[True]——若提供只能为 true，不代表审批/许可/身份验证）；min_fragment_area_sq_meters（>0，默认 1000.0，服务端固定 profile 核验）；analysis_crs（默认 USER:100001）。
• 输出 result：{ input_validation, layer_id, rows, operation: "split_with_lines" } + meta。

十、坐标转换算子（coord.*）#

10.1 coord.utm_zone#

• 会话属性：无
• 用途：由经纬度计算 UTM 带号与 EPSG（北半球 32600+带号，南半球 32700+带号）。
• 输入参数：lon、lat（必填，范围校验）。
• 输出 result：{ "zone_number": 50, "zone_letter": "S", "zone": "50S", "epsg": 32750 }。

10.2 coord.dms_to_decimal#

• 会话属性：无
• 用途：度分秒 → 十进制度。
• 输入参数：

• 输出 result：{ "decimal_degrees": 113.6254 }（8 位小数；S/W 为负）。

10.3 coord.decimal_to_dms#

• 会话属性：无
• 用途：十进制度 → 度分秒。
• 输入参数：decimal_degrees（必填，float）；axis（必填，lat 或 lon，大小写不敏感转小写）。
• 输出 result：{ "degrees": 113, "minutes": 37, "seconds": 31.44, "direction": "E", "formatted": "113°37'31.44\"E" }。

10.4 coord.wgs84_to_gcj02 / 10.5 coord.gcj02_to_wgs84 / 10.6 coord.gcj02_to_bd09 / 10.7 coord.bd09_to_gcj02#

• 会话属性：无
• 用途：火星坐标（GCJ-02）与 WGS-84、百度坐标（BD-09）互转。
• 输入参数（四个算子相同）：lon、lat（必填，范围校验）。
• 输出 result：{ "lon": ..., "lat": ... }（8 位小数）。

十一、格式转换算子（convert.*）#

11.1 convert.geojson_to_wkt#

• 会话属性：无
• 输入参数：geometry（必填，GeoJSON geometry）。
• 输出 result：{ "wkt": "POLYGON((...))" }。

11.2 convert.wkt_to_geojson#

• 会话属性：无
• 输入参数：wkt（必填，非空 WKT 字符串）。
• 输出 result：{ "geometry": {...} }。

十二、测量算子（measure.*）#

注意单位约定：输出键以 _meters 结尾的使用 Haversine 大圆距离（米）；以 _degrees 结尾的为坐标空间平面欧氏距离（度）。

12.1 measure.perimeter#

• 会话属性：无
• 用途：多边形周长。
• 输入参数：geometry（必填，Polygon 或 MultiPolygon）。
• 输出 result：{ "perimeter_meters": ... }（米，保留 4 位）。

12.2 measure.compactness#

• 会话属性：无
• 用途：多边形紧凑度（Polsby-Popper 指数，4πA/P²）。
• 输入参数：geometry（必填，Polygon 或 MultiPolygon）。
• 输出 result：{ "compactness": ..., "area_sq_meters": ..., "perimeter_meters": ..., "geometry_type": ... }。

12.3 measure.hausdorff_distance#

• 会话属性：无
• 用途：两几何的 Hausdorff 距离。
• 输入参数：geometry_a、geometry_b（必填，任意 GeoJSON geometry）。
• 输出 result：{ "hausdorff_distance_degrees": ... }（坐标空间平面距离，度，10 位小数）。

12.4 measure.frechet_distance#

• 会话属性：无
• 用途：两线的 Fréchet 距离。
• 输入参数：geometry_a、geometry_b（必填，均为 LineString）。
• 输出 result：{ "frechet_distance_degrees": ... }（度）。

12.5 measure.point_to_line_distance#

• 会话属性：无
• 用途：点到线的最近/垂直距离（适用"最近距离/最短距离"类问题）。
• 输入参数：point（必填，GeoJSON Point）；line（必填，GeoJSON LineString）。
• 输出 result：{ "distance_degrees": ... }（坐标空间平面距离，度，10 位小数；如需米请先投影）。

12.6 measure.angle_at_vertex#

• 会话属性：无
• 用途：折线某顶点处的夹角。
• 输入参数：geometry（必填，LineString）；vertex_index（必填，int ≥0，必须是内部顶点，即 1..n-2）。
• 输出 result：{ "angle_degrees": ... }（度，6 位小数）。

十三、几何生成算子（gen.*）#

13.1 gen.regular_grid#

• 会话属性：无
• 用途：规则网格生成。
• 输入参数：

• 输出 result：GeoJSON FeatureCollection（恒为 FeatureCollection），含 grid_info: {nrows, ncols, total_cells}。
• 规则与限制：总格元数上限 10000，超出报错。

13.2 gen.random_points#

• 会话属性：无
• 用途：多边形内随机撒点。
• 输入参数：polygon（必填，GeoJSON Polygon）；count（必填，正整数）；seed（可选 int，随机种子）。
• 输出 result：随机点集合。

13.3 gen.circle#

• 会话属性：无
• 用途：生成圆（度数半径）。
• 输入参数：center_lon、center_lat（必填，float）；radius_degrees（必填，>0，度）；num_segments（默认 64，建议 ≥3）。
• 输出 result：圆形 Polygon geometry。

13.4 gen.ellipse#

• 会话属性：无
• 用途：生成椭圆。
• 输入参数：center_lon、center_lat（必填）；semi_major_degrees、semi_minor_degrees（必填，>0）；rotation_degrees（默认 0，长轴逆时针旋转角）；num_segments（默认 64）。
• 输出 result：椭圆 Polygon geometry。

13.5 gen.line_from_points#

• 会话属性：无
• 用途：由坐标对构造 LineString（纯几何构造，无度量输出）。
• 输入参数：points（必填，[[lon,lat], ...]，≥2）。
• 输出 result：LineString geometry。

13.6 gen.polygon_from_points#

• 会话属性：无
• 用途：由坐标对构造 Polygon（自动闭合）。
• 输入参数：points（必填，[[lon,lat], ...]，≥3）。
• 输出 result：Polygon geometry。

13.7 gen.points_along_line#

• 会话属性：无
• 用途：沿线等距取点。
• 输入参数：geometry（必填，LineString）；interval_fraction（必填，(0,1]——大于 0 且 ≤1，按总长比例取间隔）。
• 输出 result：MultiPoint geometry（沿线点集）。

十四、拓扑检查与修复算子（topo.*）#

14.1 topo.check_validity#

• 会话属性：无（无状态）
• 用途：检查单个 GeoJSON 几何的有效性。
• 输入参数：geometry（必填）。
• 输出 result：{ "is_valid": true|false, "errors": [...] }。

14.2 topo.check_layer_validity#

• 会话属性：读会话
• 用途：检查图层全部要素的几何有效性。
• 输入参数：layer_id（必填）；id_column（必填，标识每个要素的列，结果中回显）。
• 输出 result：{ layer_id, id_column, invalid_count, invalid_features }。

14.3 topo.find_overlaps#

• 会话属性：读会话
• 用途：图层内自相交重叠检测（self-join）。
• 输入参数：layer_id、id_column（必填）；mode（默认 pairs：返回重叠对及面积；count：返回每要素重叠计数）。
• 输出 result：{ layer_id, id_column, mode, count, overlaps }。

14.4 topo.repair_layer#

• 会话属性：读会话（不写会话）
• 用途：修复图层几何（结果在响应中返回，不物化新图层）。
• 输入参数：layer_id、id_column（必填）。
• 输出 result：{ layer_id, id_column, repaired_count, features }。

14.5 topo.fix_winding#

• 会话属性：无（无状态）
• 用途：修复多边形绕向。
• 输入参数：geometry（必填，Polygon 或 MultiPolygon）。
• 输出 result：{ "geometry": {...} }。
• 规则与限制：非面类型输入不报错，返回 { "error": ... } 且 ok=true（未文档化的宽松行为）。

topo.snap_geometries_to_layer 与 topo.delete_holes 属于 Phase8 固定样本组，见 §九。

十五、聚类算子（cluster.*）#

15.1 cluster.dbscan#

• 会话属性：读会话 + 写会话
• 用途：DBSCAN 密度聚类（PostGIS ST_ClusterDBSCAN）。
• 输入参数：layer_id（必填，源点图层）；eps_meters（必填，>0，邻域半径，米）；min_samples（必填，正整数，核心簇最小点数）。
• 输出 result：新会话图层 {layer_id, source, rows}，含 cluster_id 与 cluster_size 列（噪声点 cluster_id 为 NULL）。

15.2 cluster.kmeans#

• 会话属性：读会话 + 写会话
• 用途：KMeans 聚类。
• 输入参数：layer_id（必填，源点图层）；k（必填，正整数，2 ≤ k ≤ 50——由 handler 校验，越界报 INVALID_ARGUMENT）。
• 输出 result：新会话图层 {layer_id, source, rows, k}（含簇标签列）。

十六、密度 / 插值 / 热点算子#

16.1 density.grid_count#

• 会话属性：读会话 + 写会话
• 用途：点图层规则网格计数。
• 输入参数：layer_id（必填，源点图层）；cell_size_meters（必填，>0，网格边长，米，如 500 表示 500m×500m）。
• 输出 result：新网格图层 {layer_id, source, rows, cell_size_meters}，meta 含 rows/columns/geom_type/crs。

16.2 density.kde#

• 会话属性：读会话 + 写会话
• 用途：核密度估计（高斯 KDE）。
• 输入参数：layer_id（必填，源点图层）；cell_size_meters（必填，>0）；bounds_layer_id（可选，以其范围定义分析网格）；bandwidth（可选 >0，米；缺省时 scipy Scott 规则自动选取）；max_cells（默认 5000，输出网格硬上限）。
• 输出 result：KDE 网格图层。

16.3 hotspot.getis_ord_gi_star#

• 会话属性：读会话 + 写会话
• 用途：Getis-Ord Gi* 热点分析。
• 输入参数：layer_id（必填，密度网格图层，须有 count 与 centroid）；distance_threshold_meters（必填，>0，空间权重邻域半径）；value_column（默认 count）。
• 输出 result：带 Gi* 统计量的网格图层。

16.4 interp.idw#

• 会话属性：读会话 + 写会话
• 用途：反距离加权插值。
• 输入参数：layer_id（必填，点图层，含数值列）；value_column（必填，数值列名）；cell_size_meters（必填，>0）；power（默认 2.0，范围 0.5–5.0）；max_cells（默认 5000）。
• 输出 result：IDW 插值网格图层。

16.5 interp.tin#

• 会话属性：读会话 + 写会话
• 用途：TIN/线性插值。
• 输入参数：layer_id（必填）；value_column（必填）；cell_size_meters（必填，>0）；max_cells（默认 5000）。
• 输出 result：TIN 插值网格图层。

十七、扩散模拟与代理模型#

17.1 diffusion.gaussian_plume#

• 会话属性：读会话 + 写会话
• 用途：高斯烟羽扩散模拟。气体物性（摩尔质量等）由调用方显式传入，executor 不硬编码任何气体常数。
• 输入参数：

• 互斥校验：source_layer_id 与 source_lon+source_lat 必须二选一；source_lon/source_lat 必须成对出现，否则 INVALID_ARGUMENT。
• 输出 result：浓度网格图层（稳态单帧或瞬态多帧，每帧物化为会话图层）。

17.2 surrogate.delivery_plume_eval#

• 会话属性：读会话（不写会话）
• 用途：配送烟羽代理模型评估（读取上传的 surrogate zip 包）。
• 输入参数：filename（必填，POST /upload 上传的会话 .zip 文件名，禁止路径分隔符）。
• 输出 result：评估指标（对照包内报告的预测做漂移核验，内部固定容差 1e-3；本算子不接受 tolerance 参数）。

17.3 surrogate.delivery_plume_predict#

• 会话属性：读会话（不写会话）
• 用途：配送烟羽代理模型批量预测。
• 输入参数：

• 输出 result：预测 zip 产物（经 GET /renders/{filename} 读取）及摘要。

十八、选址适宜性#

18.1 suitability.opportunity_score#

• 会话属性：读会话 + 写会话
• 用途：机会得分选址模型（需求 − 竞争 + 可达性的加权合成）。
• 输入参数：

• 输出 result：机会得分网格图层（含 Top-K 候选）。

十九、网络分析算子（network.*）#

基于 pgRouting。所有 graph_layer_id 来自 network.build_graph。均为读会话 + 写会话。

19.1 network.build_graph#

• 会话属性：读会话 + 写会话
• 用途：由线图层构建路网拓扑图。
• 输入参数：layer_id（必填，源 LineString 图层）；tolerance_meters（默认 1.0，>0，端点捕捉容差）。
• 输出 result：图图层 {layer_id, source, rows}。

19.2 network.shortest_path#

• 会话属性：读会话 + 写会话
• 用途：单对最短路径。
• 输入参数：graph_layer_id（必填）；start_lon、start_lat、end_lon、end_lat（必填，经纬度范围校验）。
• 输出 result：路径几何与代价，物化为会话图层。

19.3 network.service_area#

• 会话属性：读会话 + 写会话
• 用途：服务区（等时/等距圈）。
• 输入参数：graph_layer_id（必填）；center_lon、center_lat（必填）；max_cost_meters（必填，>0，代价上限，米）。
• 输出 result：服务区范围图层。

19.4 network.connectivity#

• 会话属性：读会话 + 写会话
• 用途：路网连通分量分析。
• 输入参数：graph_layer_id（必填）；min_component_size（默认 1，正整数，过滤顶点数少于此值的微小分量）。
• 输出 result：连通分量图层。

19.5 network.od_matrix#

• 会话属性：读会话 + 写会话
• 用途：起点-终点代价矩阵。
• 输入参数：

• 来源校验：origins 与 origins_layer_id 至少给一个（两者同时给出时 origins 优先）；destinations 与 destinations_layer_id 同理，否则 INVALID_ARGUMENT。
• 输出 result：OD 代价矩阵结果。

19.6 network.batch_shortest_path#

• 会话属性：读会话 + 写会话
• 用途：批量最短路径。
• 输入参数：graph_layer_id（必填）；pairs（必填，[{id?, origin_id?, destination_id?, start_lon, start_lat, end_lon, end_lat}]，1–50 对）。
• 输出 result：{layer_id, source, pairs, reachable_pairs, unreachable_pairs, edges, rows}。

二十、空间统计与回归#

20.1 spatial.morans_i#

• 会话属性：读会话
• 用途：全局 Moran's I 空间自相关。
• 输入参数：layer_id、value_column（必填）；weights（对象：type ∈ queen/rook/knn/distance_band 默认 queen；k 默认 8（knn）；threshold_meters 在 distance_band 时必填）；permutations（默认 99，0–9999）。
• 输出 result：Moran's I 统计量与显著性。

20.2 spatial.lisa_clusters#

• 会话属性：读会话 + 写会话
• 用途：LISA 局部空间聚类（HH/LL/HL/LH）。
• 输入参数：layer_id、value_column（必填）；weights（同 §20.1）；permutations（默认 99，1–9999）；significance（默认 0.05，(0, 1]——0 会被拒绝）。
• 输出 result：带 LISA 聚类标签的图层。

20.3 regression.ols#

• 会话属性：读会话 + 写会话
• 用途：普通最小二乘回归（闭式解，含 t 统计与双侧 p 值）。
• 输入参数：layer_id（必填，含因变量与自变量列）；dependent_var（必填，数值列 y）；independent_vars（必填，数值列数组，≥1）。
• 输出 result：回归系数、R²、显著性等；残差写入 _residual 列、预测值写入 _predicted 列（物化图层）。
• 规则与限制：要求行数 > 系数个数（系数含截距项，即 n > 1 + 自变量个数），否则 INVALID_ARGUMENT；另有"至少 3 条完整 (y, X) 观测"的前置校验。

20.4 regression.gwr#

• 会话属性：读会话 + 写会话
• 用途：地理加权回归。
• 输入参数：layer_id（必填）；dependent_var（必填）；independent_vars（必填，≥1）；bandwidth_method（AICc/CV/fixed，默认 AICc）；bandwidth（可选 >0）；kernel（bisquare/gaussian，默认 bisquare）。
• 输出 result：GWR 局部系数图层与诊断。
• 规则与限制：要求 ≥8 条完整观测。

20.5 residual.morans#

• 会话属性：读会话
• 用途：OLS 残差的 Moran's I（空间自相关诊断）。
• 输入参数：layer_id（必填，含残差列）；residual_column（默认 _residual）；model_id（可选）；weights（type ∈ knn/queen/rook 默认 knn；k 默认 8）；permutations（默认 99，0–9999）。
• 输出 result：残差 Moran's I 统计量与显著性。

二十一、统计工具算子（stats.*）#

21.1 stats.layer_extent#

• 会话属性：无（无状态）
• 用途：GeoJSON FeatureCollection 的范围。
• 输入参数：features（必填，GeoJSON FeatureCollection）。
• 输出 result：{ "bbox": {...}, "width": ..., "height": ... }。

21.2 stats.basic_stats#

• 会话属性：读会话（生产装配下；纯内存装配时为无状态）
• 用途：基础统计量。
• 输入参数：values（float 数组，≥1）或 layer_id + value_column（会话图层数值列）——两种模式互斥，同时给出报错。
• 输出 result：{ count, min, max, mean, median, std, sum, range }；图层模式追加 {layer_id, value_column, source_rows}。

21.3 stats.histogram#

• 会话属性：无
• 用途：直方图分箱。
• 输入参数：values（必填，float 数组，≥1）；bins（默认 10，正整数）。
• 输出 result：{ bins: [{bin_index, lower, upper, count}], total_count }。

21.4 stats.classify_jenks#

• 会话属性：无
• 用途：Jenks 自然断点分级（Fisher-Jenks，O(n²·k)）。
• 输入参数：values（必填，float 数组，≥2）；n_classes（必填，2–7，超出报 INVALID_ARGUMENT）。
• 输出 result：{ breaks, n_classes, classes: [{class_index, lower, upper, count}] }。

21.5 stats.percentile#

• 会话属性：无
• 用途：百分位数。
• 输入参数：values（必填，≥1）；percentile（必填，0–100）。
• 输出 result：{ percentile, value }。

21.6 stats.per_capita#

• 会话属性：读会话
• 用途：人均/比率归一化。
• 输入参数：

• 输出 result：归一化比率。
• 规则与限制：population_column 与 population_total 均可选、可同时给出（同时给出时 population_column 优先）；两者都不给时不报错，返回 population_baseline: "unavailable"、per_capita_value: null 并附 disclosure 说明。

二十二、渲染算子（render.*）#

产物经 GET /renders/{filename} 读取。静态图产物信息键：{path, filename, url, size_bytes, width_px, height_px, base64_thumbnail}；HTML/GIF 产物相应返回 {path, filename, url, format, ...}。

22.1 render.map#

• 会话属性：读会话
• 用途：多图层叠加静态地图。
• 输入参数：

• 输出 result：PNG 产物信息七键（见 §二十二开头）。

22.2 render.choropleth#

• 会话属性：读会话
• 用途：分级设色图。
• 输入参数：layer_id、value_column（必填）；classify（jenks/quantiles/equal_interval，默认 jenks）；n_classes（默认 5）；cmap（默认 YlOrRd）；title、width_px、height_px（默认 1024/768）。
• 输出 result：PNG 产物信息 + render_mode、value_column。

22.3 render.heatmap#

• 会话属性：读会话
• 用途：热度图（密度/机会得分网格）。
• 输入参数：layer_id（必填，含计数/密度列的面网格）；value_column（默认 count）；boundary_layer_id（可选，裁剪/描边）；clip_to_boundary（默认 true）；colorbar_label、cmap（默认 YlOrRd）、title、width_px、height_px、hide_axis（默认 true）；smooth（可选，缺省时 density 默认平滑、opportunity_score 默认网格硬边）；show_parameters（默认 true，图层含 analysis_parameters 时叠加参数文本）；background_layer_ids（可选参考图层数组，如主要道路）；background_style（可选对象：color 默认 #37474f、linewidth 默认 0.58、alpha 默认 0.34（0–1）、point_size 默认 6.0）。
• 输出 result：PNG 产物信息。

22.4 render.contour#

• 会话属性：读会话
• 用途：等值线图。
• 输入参数：layer_id、value_column（必填）；levels（默认 10，≤50）；cmap（默认 viridis）；colorbar_label、title、width_px、height_px、hide_axis（默认 true）。
• 输出 result：PNG 产物信息 + layer_id、value_column、levels、render_mode: "contour"。

22.5 render.webmap#

• 会话属性：读会话
• 用途：交互式 Web 地图（folium）。
• 输入参数：layer_id（必填）；popup_columns（默认 []——为空时自动取前 6 个非几何列作弹窗）；title、layer_name（可选）；tiles（默认 CartoDB positron）；zoom_start（默认 12，≤20）。
• 输出 result：HTML 产物信息 {path, filename, url, format: "html", layer_id, feature_count}。

22.6 render.time_slider#

• 会话属性：读会话
• 用途：带时间轴的交互帧序列（如扩散瞬态帧）。
• 输入参数：

• 输出 result：HTML 产物 {path, filename, url, format: "html", frame_count, feature_count, value_column, global_max_value}。

22.7 render.frame_sequence#

• 会话属性：读会话
• 用途：帧序列 GIF 动画。
• 输入参数：frames（必填，≥1，{t, layer_id}）；value_column（默认 concentration_ppm）；cmap（默认 YlOrRd）；colorbar_label；boundary_layer_id（可选，每帧叠加行政边界）；clip_to_boundary（默认 true）；title；width_px（默认 720）；height_px（默认 540）；hide_axis（默认 true）；duration_ms（默认 600，每帧显示时长）；loop（默认 0 = 无限循环）。
• 输出 result：GIF 产物 {path, filename, url, format: "gif", frame_count, value_column, global_max_value, size_bytes}。

22.8 render.analysis_report#

• 会话属性：无
• 用途：分析报告（Markdown/JSON）。
• 输入参数：title（必填非空）；sections（必填，≥1，每项可含 heading/title/text/metrics(对象)/artifacts(路径数组)）；format（markdown/json，默认 markdown）；protocol（可选 AnalysisProtocol 方法学证据）；spatial_qa（可选 SpatialQA 质量证据）。
• 输出 result：{path, filename, url, format, sections}——注意 sections 为节区数量（int）。

二十三、栅格与地形算子（raster.* / terrain.* / overlay.*）#

23.1 raster.load#

• 会话属性：无
• 用途：加载 GeoTIFF 为进程内栅格记录。支持 synthetic:// / demo:// / stub:// 合成演示 URI。
• 输入参数：path（必填非空，GeoTIFF 路径或 URI）；crs（可选覆盖，如 EPSG:32650——一旦传入即优先于文件内置 CRS）；pixel_size_m（可选 >0，标称像元大小，米）。
• 输出 result：{ layer_id, is_synthetic, source_paths, raster_metadata: {crs, shape, nodata, bands, pixel_size_m, ...} }。

23.2 raster.zonal_stats#

• 会话属性：读会话 + 写会话
• 用途：分区统计；传入 vector_layer_id 时统计结果同时物化为新会话矢量图层。
• 输入参数：raster_layer_id（必填）；zones（GeoJSON FeatureCollection 面）或 vector_layer_id（会话矢量图层）——至少给一个；stats（可选，sum/mean/min/max/count/std 子集，默认全部六项，非法值报错）；nodata_strategy（skip/fill_zero/fail，默认 skip）。
• 输出 result：{ raster_layer_id, vector_layer_id, layer_id（新会话图层或 null）, rows, stats_requested, feature_count }。

23.3 raster.resample#

• 会话属性：无
• 用途：栅格重采样。
• 输入参数：raster_layer_id（必填）；target_pixel_size_m（必填，>0）；resampling（默认 bilinear，rasterio 重采样枚举名，如 nearest/cubic；未知名报错）。
• 输出 result：{ layer_id, raster_metadata, source_layer_id, resampling_method }。

23.4 raster.reclassify#

• 会话属性：无
• 用途：栅格重分类。
• 输入参数：raster_layer_id（必填）；breaks（必填，float 数组 ≥2，严格递增的有限断点，如 [0, 35, 75, 115]）；labels（可选，非空字符串数组，长度必须等于 len(breaks)-1）；nodata_class（默认 0，≥0，nodata/越界格元的类别值）。
• 输出 result：重分类栅格。

23.5 terrain.slope#

• 会话属性：无
• 用途：DEM 坡度计算。
• 输入参数：raster_layer_id（必填，DEM）；units（degrees/percent，默认 degrees，其他值报 INVALID_ARGUMENT）；z_factor（默认 1.0，>0，垂直夸张因子）。
• 输出 result：坡度栅格 + slope_min / slope_max / slope_mean。

23.6 overlay.weighted#

• 会话属性：无
• 用途：多因子加权栅格叠加（选址/双评价）。所有因子对齐到第一个因子的网格，各自 min-max 归一化到 [0,1]，按权重合成（权重由调用方给出并归一化使和为 1，不硬编码）。
• 输入参数：factors（必填，≥2，每项 {raster_layer_id, weight>0}）；invert（可选 raster_layer_id 数组，这些因子的归一化值取 1−x，用于"越高越不适宜"的约束因子）。
• 输出 result：加权合成栅格 + normalized_weights / suitability_min / suitability_max / suitability_mean。

二十四、数据摄取算子（ingest.*）#

24.1 ingest.load_vector#

• 会话属性：写会话
• 用途：导入当前会话已上传的矢量文件（不接受任意路径）。支持扩展名白名单：.geojson / .json / .shp / .zip / .gpkg，其他格式报 VECTOR_FORMAT_UNSUPPORTED。
• 输入参数：

• 输出 result：{ layer_id, source, rows, crs, coordinate_system, native_crs, native_crs_wkt, source_crs_wkt, source_layer, actual_sha256, feature_count, preserve_source_crs }。

24.2 ingest.load_raster#

• 会话属性：写会话
• 用途：导入当前会话已上传的 GeoTIFF（仅 .tif / .tiff）。
• 输入参数：filename（必填，上传的 GeoTIFF 文件名，禁止路径分隔符）；crs（可选——一旦传入即覆盖 GeoTIFF 内置 CRS；未传入时用文件内置 CRS，缺省回退 EPSG:4326）；pixel_size_m（可选 >0）。
• 输出 result：同 raster.load 的输出结构（{is_synthetic, source_paths, layer_id, raster_metadata}）。

24.3 ingest.load_table#

• 会话属性：写会话
• 用途：导入当前会话已上传的表格（.csv/.tsv/.txt/.dat/.xls/.xlsx），可选由"源点+距离+方位角"合成点几何。
• 输入参数：

• 互斥校验：点合成四件套（origin_lon/origin_lat/distance_column/azimuth_column）必须全给或全不给，否则 INVALID_ARGUMENT；不给时表格按纯属性存储（无几何）。
• 输出 result：{ layer_id, source, rows, crs: "EPSG:4326", geometry_synthesized, columns }。

二十五、时序知识图谱#

25.1 tkg.query_events#

• 会话属性：无读写标志（直接查询只读的 tkg 全局 schema；注册表 writes_session=false）
• 用途：查询 tkg.events 时序事件（实体-关系-实体+时间）。
• 输入参数：

• 输出 result（明细模式）：

{
  "events": [
    { "entity1": "...", "relation": "...", "entity2": "...",
      "event_time": "2019-08-10", "source": "...", "pack_id": "..." }
  ],
  "count": 1,
  "filters": { "entity": null, "relation": null, "time_start": null, "time_end": null, "limit": 50 }
}

• 输出 result（count_only 模式）：{ "total": 0, "filters": {entity, relation, time_start, time_end}, "count_only": true }——注意此模式 filters 不含 limit 键。
• meta：{rows}（明细模式为事件数；count_only 模式为 0）。
• 规则与限制：事件时间以 UTC YYYY-MM-DD 返回，按时间升序 + entity1 排序。

附录 A：算子索引（按名称排序）#

cluster.dbscan · cluster.kmeans · convert.geojson_to_wkt · convert.wkt_to_geojson · coord.bd09_to_gcj02 · coord.decimal_to_dms · coord.dms_to_decimal · coord.gcj02_to_bd09 · coord.gcj02_to_wgs84 · coord.utm_zone · coord.wgs84_to_gcj02 · density.grid_count · density.kde · diffusion.gaussian_plume · gen.circle · gen.ellipse · gen.line_from_points · gen.points_along_line · gen.polygon_from_points · gen.random_points · gen.regular_grid · geo.buffer · geo.calculate_bearing · geo.calculate_distance · geo.clip · geo.difference · geo.dissolve · geo.get_bounding_box · geo.get_centroid · geo.intersects · geo.is_point_in_polygon · geo.line_interpolate_point · geo.line_substring · geo.locate_landmark · geo.simplify_geometry · geo.spatial_join · geo.transform_crs · geo.union · hotspot.getis_ord_gi_star · ingest.load_raster · ingest.load_table · ingest.load_vector · interp.idw · interp.tin · io.fuzzy_search_poi · io.load_layer · measure.angle_at_vertex · measure.compactness · measure.frechet_distance · measure.hausdorff_distance · measure.perimeter · measure.point_to_line_distance · network.batch_shortest_path · network.build_graph · network.connectivity · network.od_matrix · network.service_area · network.shortest_path · overlay.weighted · raster.load · raster.reclassify · raster.resample · raster.zonal_stats · regression.gwr · regression.ols · render.analysis_report · render.choropleth · render.contour · render.frame_sequence · render.heatmap · render.map · render.time_slider · render.webmap · residual.morans · rows.preview · rows.rank_by_distance · rows.rank_layer_by_distance · schema.columns · schema.semantic_search · spatial.lisa_clusters · spatial.morans_i · stats.basic_stats · stats.classify_jenks · stats.histogram · stats.layer_extent · stats.per_capita · stats.percentile · stats.row_count · suitability.opportunity_score · surrogate.delivery_plume_eval · surrogate.delivery_plume_predict · system.cleanup_session · system.echo · terrain.slope · tkg.query_events · tools.semantic_search · topo.check_layer_validity · topo.check_validity · topo.delete_holes · topo.find_overlaps · topo.fix_winding · topo.repair_layer · topo.snap_geometries_to_layer · vector.aggregate_geometry · vector.area_calculate · vector.convex_hull · vector.extract_by_location · vector.join_attributes_by_location · vector.length_calculate · vector.merge_layers · vector.multi_to_single · vector.split_with_lines

附录 B：校验与对账#

本文档的正确性通过两条独立途径验证：

1. 自动对账：export_tool_truth.py 以与服务启动完全相同的方式实例化工具注册表，导出 112 个算子的权威 JSON Schema（tools-truth.json）；reconcile_docs.py 逐算子比对文档中的参数名、必填性、默认值、会话属性与 schema 的一致性。 2. 多路人工复核：4 组独立校验（基础与几何 / 矢量与拓扑 / 分析与统计 / 渲染与摄取）逐字段对照 handler 实现核实输出结构。

复核过程中同步修正了 executor/docs/API.md 的 7 处问题：失效的权威文档引用、§5.6 小节编号错误（5.5.x→5.6.x）、rows.preview 参数过时（补 offset/order_by/order_desc 与 dropped_columns 行为）、无状态几何清单遗漏 2 个算子、array_contains_filters 语义描述（现行 overlap &&）、只读 schema 清单补 tkg、错误码补 EXTERNAL_DEPENDENCY_ERROR。