iDesktopX Skill

SuperMap 同源桌面产品的 AI Agent 技能，统一通过 DesktopCLI wrapper 与目标桌面产品交互。

> idesktopx 是本 skill 和 DesktopCLI wrapper 的固定名称，不等于目标产品包必须叫 iDesktopX。目标产品可以是

> iDesktopX、TransformX、iMageX、iMaritimeEditor、ActiveMap 等同源桌面产品；安装时以用户提供的目标产品安装根目录为准，CLI

> 命令仍固定写成 idesktopx ...（Windows 为 idesktopx.cmd ...）。

能力分流门禁（强制）

• 优先使用语义最贴近任务的 domain skill；已有 domain skill

能完成时，不要先退到 component、tree、dialog、ribbon、python 等通用操作层。

• domain skill 参数或执行失败时，先按该 domain skill 的参数恢复流程排查，不要立即改走 UI、脚本或组件模拟绕行。
• 未得到用户明确许可前，禁止修改或删除原数据；允许先读取、预览、分析，或把结果输出到新数据、新文件、临时对象后再请用户确认。

新会话启动门禁（强制）

• 新会话首次使用本 skill 时，先读本总入口，再按 目标产品包配置（跨会话） 恢复或确认目标产品包根目录。
• 用户级配置文件是可选缓存：存在且有效就复用；不存在、路径无效或缺少 idesktopx.cmd / idesktopx

时，不视为错误，必须询问用户目标产品包根目录，或使用用户本轮明确提供的根目录。

• 确认目标产品包根目录后，本会话所有 CLI、启停 REST、离线命令和兜底命令都绑定该根目录下的 wrapper

绝对路径；不得中途切回裸 idesktopx 或 PATH 中其它同名命令。

• CLI wrapper 位于目标产品包根目录，不在 bin 目录；不要到 <目标产品包根目录>/bin 下搜索 exe、bat、cmd 来猜 CLI 入口。
• 会话首次业务操作前必须完成一次版本匹配校验；同一会话内已确认版本匹配后不要重复 desktop/version_get

，除非用户切换目标产品包、wrapper 路径、产品进程或版本读取失败。

• 在线能力前按 在线 HTTP 前置条件（强制） 先复用已启用 REST；离线命令和 HTTP 不便表达的场景再走 CLI。

版本匹配（强制）

• 本 skill 与目标桌面产品是分开发布的，执行前必须先确认版本匹配
• 该版本门禁适用于 skills/idesktopx/ 下全部子 skill，不应由某个子 skill 单独定义另一套版本判断规则
• Agent 必须在会话首次业务操作前调用一次 desktop/version_get，或 CLI idesktopx desktop version_get

，读取当前目标桌面产品的 desktopVersion

• 当前 skill 的兼容规则以 skills/idesktopx/_meta.json 为准；本版本要求 compatibility.idesktopx.matchRule = prefix

（配置键保留历史名称，不代表只支持 iDesktopX 产品包）

• 当前支持的 desktopVersion 前缀为 12.1.，判断时按字符串前缀匹配，不按严格 semver 解析
• 只有在版本要求匹配时，才允许继续执行后续桌面自动化、配置修改或业务操作
• 如果无法读取版本号，或当前版本不在支持范围内，必须先停止并提示用户确认；同一会话已确认版本匹配后，除非切换目标产品包、wrapper

路径、产品进程或版本读取失败，不要重复执行版本门禁

目标产品包配置（跨会话）

• 新会话首次使用本 skill 时，先读取用户级配置文件恢复目标产品包根目录；同一会话后续命令复用已确认路径，不要每条命令重复读取。
• 配置文件位置统一放在用户目录下：Windows 使用 %USERPROFILE%\.idesktopx-skill\config.json；Linux / macOS

使用 $HOME/.idesktopx-skill/config.json。

• 配置只保存目标产品包根目录等本机偏好，不写入 skill 安装目录、产品安装目录、仓库目录或 Git 管理文件。
• 配置不存在、路径无效、缺少 idesktopx.cmd / idesktopx

，或用户明确切换产品包时，询问用户并在确认后更新配置；若写入失败，本轮继续使用用户提供路径并提示未持久化。配置文件只是可选缓存，不是使用本

skill 的必要前提。

• 详细配置格式、权限处理和写入流程见 references/install-and-verify.md。

在线 HTTP 前置条件（强制）

• 判断目标同源桌面产品是否可用时，不要按固定 iDesktopX

进程名搜索；必须绑定用户指定的目标产品包根目录，并通过该包下 idesktopx.cmd / idesktopx 的 rest status 读取 REST

状态，再用最小在线 HTTP 或最小在线命令判断。

• 目标桌面产品启动并加载 DesktopCLI/DesktopTools 后，可能已经开放 REST，也可能尚未开放；不要机械重复 rest enable。
• 在线能力前先执行本地命令读取状态：

idesktopx rest status

• 如果 rest status 返回已启用并包含有效 host、port 或 baseUri，先用该入口做最小 HTTP

探测，成功后直接复用，不再执行 rest enable。

• 只有在 rest status 返回 disabled、状态入口不可用、在线命令返回 REST_NOT_ENABLED、用户切换目标产品包 / host /

port，或本会话从未确认过 REST 入口时，才执行 rest enable。

• rest enable 默认会绑定到 127.0.0.1:17532
• 如果需要指定监听地址或端口，使用：

idesktopx rest enable --host 127.0.0.1 --port 17532
idesktopx rest enable --host 0.0.0.0 --port 17540
idesktopx rest enable --host 192.168.1.20 --port 17541

• rest enable 成功后，返回的 host、port、baseUri 就是当前会话优先使用的在线 HTTP 入口；CLI 仅作为兜底路径复用同一端点。
• Agent 可以用以下命令管理运行态：

idesktopx rest status
idesktopx rest disable

• 如果 rest status 返回 disabled，或在线命令返回 REST_NOT_ENABLED，必须先重新执行 idesktopx rest enable
• 在线业务调用默认优先走

HTTP：GET /api/v1/health、GET /api/v1/status、GET /api/v1/tools、POST /api/v1/{domain}/{action}；CLI 用于启停

REST、离线命令和 HTTP 不便表达的兜底场景。

Python 运行时能力

当任务涉及 PythonForm、iobjectspy、外部 Python 脚本连接当前桌面运行时、py4j gateway 动态探测，或需要通过 Python

访问当前桌面实例中的工作空间、数据源、数据集、地图等运行时对象时，优先加载：

• skills/idesktopx/python/SKILL.md

该子 skill 已包含：

• 产品包 Python 环境解析
• gateway 动态探测
• 外部 Python 脚本直连当前桌面运行时
• 已验证的数据源 / 数据集 / 地图读取示例与注意事项

安装与验证

仅在需要安装、更新或验证目标产品包内 DesktopCLI/DesktopTools 时读取 references/install-and-verify.md。

核心门禁：

• 必须先确认目标 SuperMap 桌面产品安装根目录，不要猜测多个产品包位置。
• 必须把 DesktopCLI.jar、DesktopTools.jar、idesktopx.cmd / idesktopx 安装到目标产品包对应位置。
• 安装后需要启动或重启目标桌面产品，并用 rest status 复用或按需 rest enable、desktop/version_get、workspace/info

或对应最小在线 HTTP 做最小验证。

• 缺少任一文件或版本不匹配时，停止并提示用户确认，不要改走 PATH 中其它 idesktopx。

HTTP 与 CLI 运行态

在线 HTTP、CLI 启用步骤、在线/离线运行态、绝对路径绑定和调用节奏细节见 references/cli-runtime.md。

核心门禁：

• 在线调用前先用 idesktopx rest status 复用已启用入口；仅未启用或不可用时执行 idesktopx rest enable。在线业务默认优先走

HTTP，离线命令和 HTTP 不便表达的场景再走 CLI。

• 绑定目标产品包后，所有启服命令、CLI 兜底命令、子脚本、批处理都复用同一个 CLI 绝对路径，不得中途切回裸 idesktopx。
• 在线验证、UI 操作、状态变更按“一条命令 -> 读取 JSON -> 必要时回读/等待 -> 下一条命令”执行。

Agent 使用规则（必须）

0. 独立 domain tool 优先，禁止优先走 component tool

• 若某类能力已有独立 domain tool，必须优先使用独立 tool，不要先尝试 component/*
• component/* 只用于：
• 对话框/窗体内部的通用 Swing 组件操作
• 当前确实不存在对应独立 domain tool 的场景
• 典型优先级：
• 工作空间树、图层树：优先 tree/*
• 窗体切换、停靠、关闭：优先 form/*
• 菜单/命令执行：优先 menu/、command/
• DockBar 打开/关闭/查询：优先 dockbar/*
• 不要因为已经拿到了某个 comp_xxx，就绕过已有独立 tool 去实现本应由独立 tool 负责的语义能力

1. 先发现，再执行

• REST：先 idesktopx list --mode online --detail summary，以运行时真实注册结果为准。
• CLI：先 idesktopx list / idesktopx help ，不要猜命令名和参数名。
• 若文档、历史记忆、运行时返回不一致：一律以运行时为准，并记录差异，不要自行脑补。

2. 高风险命令的前置条件

• layer/、theme/、ribbon/*：必须先 form/active 确认当前活动窗体就是目标地图窗体；若当前活动窗体是布局、场景、

属性表或其它窗口，先 map/open 或 form/activate 切到目标地图，再次 form/active 确认 type=Map 后再执行。

• table/*：必须先定位当前活动的 Tabular 窗体，并重新执行一次 component/structure 获取最新表格组件 ID；不要长期复用旧

comp_xxx。

• component/rightclick：先 desktop/tofront，若刚切窗体再补 ui/wait_idle。

3. 只看 success 不算完成

下列命令返回成功后，必须再做回读验证：

• form/activate -> 再调 form/active
• theme/create -> 再调 map/layers 或 layer/get_style
• theme/set_style -> 再调 layer/get_style
• table/setvalue -> 再调 table/getvalue
• layer/set_style -> 再调 layer/get_style

4. 改环境后必须恢复

• theme/create 若仅用于临时操作或测试，结束后应移除新生成的专题图层。
• table/setvalue 若只是验证能力，应把原值恢复并再次回读确认。
• layer/remove、map/addlayer、form/close 这类会影响当前工作环境的操作，结束后要显式恢复到基线状态。

5. 已知运行时陷阱

• theme/create 的语义是“新建专题图层副本”，不是把原图层原地改成专题图。
• form/activate 可能出现“返回成功但活动窗体未变化”；必须以后续 form/active 为准。
• 所有树控件语义操作都优先使用 tree/；不要优先使用 component/ 去做树语义操作。
• 在线 REST/CLI 链路中，dataset/unique_values 对 datasource.datasetName 全名解析可能不稳定；若全名失败而裸数据集名可用，应按已知限制处理，不要误判为数据源不存在。

CLI 报错与参数规范

常见错误决策、在线 CLI 启用细节、中文和复杂 JSON 参数规范见 references/cli-troubleshooting.md。

核心门禁：

• REST_NOT_ENABLED 先执行 rest enable；HEADLESS_UNSUPPORTED 先判断是否误用离线参数。
• 中文或复杂 JSON 参数优先写 UTF-8 文件并用 @文件 传入，不要在 PowerShell 中内联转义复杂 JSON。
• success=true 不等于业务完成；状态变化必须用对应 domain skill 或业务读接口回读验证。

响应格式

{
  "success": true,
  "data": {
    // 返回数据
  }
}

错误响应：

{
  "success": false,
  "error": {
    "message": "错误信息"
  }
}

子领域技能

| 技能 | 说明 |

|--------------|--------------------------------|

| desktop | 桌面窗口与配置操作 |

| workspace | 工作空间操作 |

| datasource | 数据源操作 |

| dataset | 数据集操作 |

| map | 地图操作 |

| scene | 场景操作 |

| layout | 布局操作 |

| table | 表格操作 |

| form | 窗口操作（获取窗口列表、关闭窗口） |

| dialog | 对话框操作（点击按钮、填写输入框） |

| dockbar | 停靠窗口操作（工作空间管理器、图层管理） |

| ribbon | 功能区选项卡操作 |

| component | 组件操作（获取结构、点击、填写值） |

| gpa | GPA 工具操作 |

| utility | 通用工具（类型格式查询、类型转换） |

| log | 日志操作（获取日志文件、读取日志内容） |

| outputwindow | 输出窗口操作（获取输出内容、清空窗口） |

| business | 业务场景编排（优先复用现有桌面产品能力） |

| testing | 测试场景编排（证据驱动、前后对比、阻塞处理） |

| workenv | 当前工作环境静态入口目录查询 |

| ui | UI 等待器（稳定器） |

| tree | 树语义操作（所有 JTree，含工作空间树/图层树） |

| menu | 菜单命令执行（commandId） |

执行策略（性能优先）

1. 先直接执行目标命令，不先做全量探测。
2. 失败后只做最小探测，每次只补一个必要事实（例如一次 command/catalog 或一次 tree/snapshot）。
3. 默认不要读取同源桌面产品源码；仅在用户明确要求，或运行时接口无法定位目标时再查代码。
4. 涉及鼠标/右键等前台依赖命令，先 desktop/tofront 再执行，避免操作打到其他软件窗口。
5. 避免重复打开同一 UI 容器：DockBar/对话框已打开时优先复用，不要重复执行“打开”类命令。
6. 面向业务场景时，优先查看 business/SKILL.md，按业务 Skill 的分析链去发现和编排现有能力；如果最终要落到 GPA

建模，顺序必须是 business -> gpa，先补齐判定口径和探针验证，再进入 gpa_model/*，不要直接新增业务专用 CLI。

1. 需要读取记录级属性值时，优先使用 dataset/query_records，不要默认先导出 CSV。
2. 大数据场景下，优先使用 dataset/query_records 的 startAfterSmId 与 needTotal=false 组合做 seek

分页，避免深分页 offset。

1. 几何、邻接、拓扑、归属类结构证据，优先通过 GPA、空间查询、叠加分析生成结果数据集后，再回查结果字段，不要默认把原始几何明细直接拉回

Agent 内存。

1. 执行链路按目标容器分流，不要把“command/execute -> dialog/list -> component/structure”当成固定通用流程。
2. 在开始 UI 自动化前先做轻量预检：idesktopx rest status 与一个最小在线命令（如 idesktopx workspace info

）；异常时先恢复服务状态，不要盲重试业务命令。

UI 操作与取证

UI 场景取证、WorkEnvironment、Ribbon/DockBar 串联、等待器、树和菜单操作细节见 references/ui-operations.md。

核心门禁：

• 有独立 domain skill 时优先用 domain skill，不要先用 UI 组件模拟。
• UI 操作前后必须回读业务状态；必要时使用 ui/wait_idle 或对应状态接口，不能只看点击成功。
• 树操作优先用 tree/，菜单命令优先用 command/，组件层只处理缺少 domain 能力的控件交互。

快速开始

1. 确保目标桌面产品已启动并加载 DesktopCLI/DesktopTools 插件
2. 先开启在线 REST：

idesktopx rest enable

1. 检查服务状态：

idesktopx rest status

1. 获取工作空间信息：

idesktopx workspace info

阻塞对话框处理（必须执行）

在执行任何非 dialog/、component/ 命令时，若返回：

• success=false
• error.code=BLOCKED_DIALOG

表示当前有模态对话框阻塞。此时必须停止后续业务命令，先处理阻塞窗口；不要把多条在线命令继续压入桌面端。BLOCKED_DIALOG

不一定表示原业务命令已经失败，也可能表示原命令已触发模态框并正在等待用户决策。

标准流程：

1. 调 idesktopx dialog blocking 获取阻塞窗口标题。
2. 调 idesktopx component structure --id "<对话框标题>" 读取真实提示文字和按钮列表。
3. 按结构和语义分类处理：
• 单按钮且属于纯信息、完成、错误提示类弹窗，可点击唯一按钮。
• 多按钮弹窗，或提示涉及保存、删除、覆盖、退出、"是否"、问号，属于用户决策；除非用户本轮已明确授权策略，否则不要自动点击

"是"、"否"、"取消"。

1. 点击按钮后先再次调 idesktopx dialog blocking。若仍有阻塞窗口，继续处理当前阻塞窗口。
2. 阻塞窗口清零后调 idesktopx ui wait_idle，再用对应 domain 命令回读业务状态。只有确认原命令未生效且用户仍要求继续时，才重试原业务命令。

不要在 BLOCKED_DIALOG 状态下连续重试业务命令，也不要形成"点击弹窗按钮 -> 立即重试原命令"的机械循环。