AGENT SKILL

action-remote-call

需要通过 HTTP 控制 OpenGeoLab 时使用 — 创建几何体、截取视窗、控制相机、管理选择、生成网格,或通过 REST API 远程调用任意 Action

License 许可
GPL-3.0
最近更新
2026-08-19
Stars
★ 3
Forks
1

01 前言 Front Matter

name
action-remote-call
description
需要通过 HTTP 控制 OpenGeoLab 时使用 — 创建几何体、截取视窗、控制相机、管理选择、生成网格,或通过 REST API 远程调用任意 Action

03 SKILL.md 正文

Action Remote Call — 渐进式发现

OpenGeoLab 暴露统一的 HTTP REST API(POST /api/v1/action)用于远程控制。 所有操作共享同一 JSON 信封格式;使用内置 schema 发现 action 在运行时查询精确参数,而不是死记硬背。

启动 opengeolab 时使用 --start-http-server 参数自动启动 http server,以便你使用 http remote call actions。

快速开始

URL=http://127.0.0.1:8080/api/v1/action

# 健康检查
curl -s http://127.0.0.1:8080/api/v1/health

# 执行任意 action
curl -s -X POST $URL -H "Content-Type: application/json" \
  -d '{"module":"geometry","action":"create_box","param":{"width":2}}'

请求格式: {"module": "<模块名>", "action": "<动作名>", "param": {...}} 成功响应: {"ok": true, ...结果字段...} 失败响应: {"ok": false, "summary": "...", "errors": [...]}

默认地址:http://127.0.0.1:8080(端口可在 UI 中配置)。 已启用 CORS(Access-Control-Allow-Origin: *)。


Schema 发现(执行前必须)

执行任何 action 之前,必须先通过 system 模块查询其精确参数。 这是唯一权威来源 — 不要猜测参数名或类型。

第一步:获取模块的 action 列表

根据下方模块概览,选择目标模块并查询其所有 action:

curl -s -X POST $URL -d '{"module":"system","action":"describe_module","param":{"module":"geometry"}}'

返回:{"ok":true, "module":"geometry", "description":"...", "actions":[{"name":"create_box","description":"..."}, ...]}

第二步:获取具体 action 的精确参数

curl -s -X POST $URL -d '{"module":"system","action":"describe_action","param":{"module":"geometry","action":"create_box"}}'

返回完整参数 schema,包含类型、默认值和必填标记 — 依据此构造请求。

完整系统 schema(高级,一次性获取)

curl -s -X POST $URL -d '{"module":"system","action":"describe","param":{}}'

返回所有模块、所有 action、所有参数/返回值 schema。适合批量内省。


模块概览

每个模块负责一个独立领域。使用 system.describe_module 发现模块内的所有 action。

模块 Action 数 职责
geometry 14 创建基元体(长方体、球体、圆柱、圆环)、导入外部 CAD 文件(STEP、BRep)、查询形状拓扑/包围盒、列出子拓扑(面、边、顶点)、描述拓扑结构、查询单实体详情与邻接、删除形状、细分可视化
mesh 3 从几何面/体生成有限元网格(三角形/四边形,可配置算法)、查询网格节点/边/单元信息、清除网格数据
scene 22 截取视窗截图(PNG 文件 + 元数据 + 可选拓扑)、控制相机(位置/预设/适配/对准实体/最佳视角)、选择/取消选择实体、标注几何实体、管理可见性和场景树、重置工作区
io 1 文件读取操作(部分实现)
system 5 capabilities、describe、list_modules、describe_module、describe_action — 运行时内省

模块名区分大小写,仅以上 5 个名称有效。


关键 Action(代表性示例)

以下展示几个重要 action 的用法。完整参数请使用 system.describe_action 查询。

geometry.create_box — 创建长方体

curl -s -X POST $URL -d '{"module":"geometry","action":"create_box","param":{"width":3,"height":2,"depth":1}}'

返回:{"ok":true, "shapeId":0, "name":"Box", "topology":{"solids":1,"faces":6,"edges":12,"vertices":8}}

⚠️ 易错点: create_sphere 使用 center(不是 origin)。导入操作使用 path(不是 filePath)。

scene.capture_viewport — 截图与场景分析

# 保存到文件(filePath 必填)
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/viewport.png"}}'

# 包含拓扑信息
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/viewport.png","includeTopology":true}}'

返回元数据(相机、可见形状及屏幕包围盒/世界包围盒、选择状态、标签)和 PNG 截图路径。 includeTopology: true 时,每个可见形状附带面/边/顶点拓扑数据。 ⚠️ filePath 是必填参数。不再支持 base64 图片模式。

scene.select — 选择实体

curl -s -X POST $URL -d '{"module":"scene","action":"select","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":1}]}}'

⚠️ 选择/取消选择使用 type,标签操作使用 entityType。localId 是 1-based — 必须先用 geometry.list_sub_shapes 查询。

mesh.generate_mesh — 生成网格

curl -s -X POST $URL -d '{"module":"mesh","action":"generate_mesh","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":1}],"elementSize":0.5}}'

⚠️ 使用 system.describe_action 发现 dimension、elementType、algorithm、advanced 等选项。


实体引用格式

所有涉及实体引用的 action 使用此结构:

{"shapeId": 0, "type": "GeoFace", "localId": 1}
字段 说明
shapeId 0-based 形状 ID(来自 create_* / list_shapes)
type 或 entityType 选择/悬停用 type;标签操作用 entityType
localId 1-based 拓扑 ID(来自 list_sub_shapes)

几何类型: GeoVertex、GeoEdge、GeoWire、GeoFace、GeoSolid 网格类型: MeshNode、MeshEdge、MeshElement


典型工作流

建模 → 查看 → 截图

curl -s -X POST $URL -d '{"module":"geometry","action":"create_box","param":{"width":3,"height":2,"depth":1}}'
curl -s -X POST $URL -d '{"module":"scene","action":"fit_to_scene","param":{}}'
curl -s -X POST $URL -d '{"module":"scene","action":"set_view_preset","param":{"preset":"Isometric"}}'
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/shot.png"}}'

拓扑分析 → 定位圆柱面 → 网格剖分

curl -s -X POST $URL -d '{"module":"geometry","action":"describe_topology","param":{"shapeId":0}}'
# 从返回的 faces 中找到 surfaceType="cylinder" 的 localId
curl -s -X POST $URL -d '{"module":"geometry","action":"query_entity_info","param":{"shapeId":0,"entityType":"face","localId":2}}'
curl -s -X POST $URL -d '{"module":"scene","action":"best_view_for_entity","param":{"shapeId":0,"entityType":"face","localId":2}}'
curl -s -X POST $URL -d '{"module":"mesh","action":"generate_mesh","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":2}],"elementSize":5}}'
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/mesh.png"}}'

选择 → 标注 → 分析

curl -s -X POST $URL -d '{"module":"geometry","action":"list_sub_shapes","param":{"shapeId":0}}'
curl -s -X POST $URL -d '{"module":"scene","action":"select","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":1}]}}'
curl -s -X POST $URL -d '{"module":"scene","action":"add_label","param":{"shapeId":0,"entityType":"GeoFace","localId":1}}'
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/labeled.png"}}'

常见错误

错误做法 正确做法
猜测参数名 先用 system.describe_action 查询
localId 从 0 开始 localId 是 1-based,先用 list_sub_shapes 查
用 filePath 导入文件 导入操作参数名是 path
sphere 用 origin sphere 使用 center
add_label 用 type 标签操作使用 entityType
把 pick_area 当同步 pick_area 是异步 — 需后续调用 query_selection
文件路径用单反斜杠 使用 C:/path 或 C:\\path
未启动 HTTP Server 就调用 需先在 OpenGeoLab UI 中启动 HTTP Server 插件
capture_viewport 不带 filePath filePath 是必填参数
camera 动作用 GeoFace look_at_entity/best_view_for_entity 的 entityType 用短名 face/edge/vertex

04 同仓库更多 Skills