功能描述

控制Kunwu Builder工业仿真软件的HTTP API，实现模型管理、机器人控制、物流设备、相机及传感器操作、场景与行为配置等功能。

使用说明 (SKILL.md)

Kunwu Builder 控制技能

Name: Kunwu Builder
Author: samwlh

控制 Kunwu Builder (坤吾) 工业仿真软件的 HTTP API。

基础信息

项目	值
API 地址	`http://192.168.30.9:16888`
认证	无
请求方式	POST
Content-Type	`application/json`

工具

`kunwu_call`

kunwu_call endpoint="/model/create" data='{"id":"M900iB_280L","position":[0,0,0],"checkFromCloud":true}'

参数	必填	说明
`endpoint`	✅	API 路径
`method`	❌	HTTP 方法，默认 `POST`
`data`	❌	请求体 JSON

常用 API

1. 模型加载机制（核心流程）⚡

唯一推荐方式：使用 /model/create + checkFromCloud=true

kunwu_call endpoint="/model/create" data='{
  "id": "M900iB_280L",
  "rename": "机器人_右",
  "position": [0, 2500, 515],
  "eulerAngle": [0, 0, 0],
  "checkFromCloud": true
}'

机制说明：

checkFromCloud: true → 本地有直接加载（快速），本地没有自动从云端下载
checkFromCloud: false → 仅从本地加载，本地没有则失败

决策树：

需要加载模型？
  ├─ 是 → 用 /model/create + checkFromCloud:true（99% 场景）
  └─ 否 → 不需要任何操作

步骤 1: 直接使用 /model/create 创建模型

kunwu_call endpoint="/model/create" data='{
  "id": "辊床_01",
  "position": [0, 0, 0],
  "checkFromCloud": true
}'

批量加载（推荐）：使用 scripts/model-loader.js

# 准备 models.json
node scripts/model-loader.js models.json

# 环境变量指定 API 地址
KUNWU_API_URL=http://192.168.30.9:16888 node scripts/model-loader.js models.json

步骤 2: 设置模型参数化（如支持）

kunwu_call endpoint="/model/set_pose" data='{
  "id": "皮带线_01",
  "position": [-11013.5, -603.5, 0],
  "eulerAngle": [0, 0, -90],
  "parameterizationCfg": [
    {"type": 0, "value": 10000},
    {"type": 1, "value": 1460},
    {"type": 2, "value": 1000}
  ]
}'

ModelName 说明：

使用本地模型库中的 modelName 字段值
常见模型：辊床_01, M900iB_280L, 方形底座_02, 吸盘_10, 托盘_07

参数化模型说明：

部分模型支持参数化（如皮带线、方形等）
使用 /model/set_pose 设置参数化配置
parameterizationCfg 格式：[{"type": 0, "value": 值}, ...]
type 编号含义：0=长，1=宽，2=高（具体参考模型文档）

2. 场景查询

获取层级树

kunwu_call endpoint="/models/tree" data='{"rootId":"scene","useModeId":true}'

3. 装配（核心）

kunwu_call endpoint="/model/assemble" data='{
  "childId": "子模型 modelId",
  "parentId": "父模型 modelId",
  "assemblePosIndex": 0,
  "replaceExisting": false
}'

响应码：

200 - 装配成功
409 - 装配位被占用（设置 replaceExisting: true 替换）

4. 销毁模型

kunwu_call endpoint="/model/destroy" data='{"id":"modelId","useModeId":true}'

夹具行为配置（核心功能）

四大原则（必须遵守！）

原则	说明	示例
1. 轴向判断	使用 transform 相对位置确定运动轴向	ΔX 最大 → X 轴开合
2. 相向夹紧	主动臂朝中心运动，从动臂反向	主动 X+ → 从动 X-
3. 行程计算	行程 = boundSize ÷ 3	52mm → 17mm
4. 联动配置	从动臂必须配置 `dependentTargetId`	⚠️ 不配无法联动

轴向对照表

轴向	值	相反轴向	值	异或
X+	0	X-	1	`0^1=1`
Y+	2	Y-	3	`2^1=3`
Z+	4	Z-	5	`4^1=5`

快速反向： dependentAxis = activeAxis ^ 1

7 步配置流程

# 步骤 1: 获取层级树
kunwu_call endpoint="/models/tree" data='{"rootId":"scene"}'

# 步骤 2-3: 分析结构，确定轴向
# 读取 transform 计算 ΔX/ΔY/ΔZ，选最大值的轴
# 根据相对位置确定方向（相向夹紧原则）

# 步骤 4: 计算行程
# travel = boundSize[axisIndex] / 3

# 步骤 5: 配置主动臂 (behavioralType: 1)
kunwu_call endpoint="/behavior/add" data='{
  "id": "DH_PGS_5_5/1",
  "useModeId": false,
  "behavioralType": 1,
  "referenceAxis": 0,
  "minValue": 0,
  "maxValue": 4,
  "runSpeed": 80,
  "targetValue": 2
}'

# 步骤 6: 配置从动臂 (behavioralType: 3 + dependentTargetId！)
kunwu_call endpoint="/behavior/add" data='{
  "id": "DH_PGS_5_5/2",
  "useModeId": false,
  "behavioralType": 3,
  "referenceAxis": 1,
  "minValue": 0,
  "maxValue": 4,
  "runSpeed": 80,
  "targetValue": 2,
  "dependentTargetId": "DH_PGS_5_5/1",
  "dependentTargetUseModeId": false
}'

# 步骤 7: 验证配置
kunwu_call endpoint="/behavior/list" data='{"id":"夹具 modelId","useModeId":true}'

实测案例

夹具型号	ΔX	ΔY	ΔZ	轴向	行程
DH_PGS_5_5	16mm	-	-	X 轴	4mm
DH_PGI_140_80	40mm	34.7mm	-	X 轴	17mm
DH_PGE_100_26	-	46mm	-	Y 轴	15mm
DH_RGD_5_14	40mm	-	-	X 轴	13mm

完整示例：搭建双机器人工作站（带托盘布局）

方式 A: 使用批量加载工具（推荐）

node scripts/model-loader.js scripts/models-dual-robot-trays.json

方式 B: 手动逐步创建

# 步骤 1: 创建模型（使用 checkFromCloud=true，本地有则快，没有自动下载）
# 1.1 输送线
kunwu_call endpoint="/model/create" data='{
  "id": "辊床_01",
  "rename": "输送线",
  "position": [0, 0, 0],
  "checkFromCloud": true
}'

# 1.2 底座×2
kunwu_call endpoint="/model/create" data='{
  "id": "方形底座_02",
  "rename": "底座_右",
  "position": [0, 2500, 0],
  "checkFromCloud": true
}'
kunwu_call endpoint="/model/create" data='{
  "id": "方形底座_02",
  "rename": "底座_左",
  "position": [0, -2500, 0],
  "checkFromCloud": true
}'

# 1.3 机器人×2
kunwu_call endpoint="/model/create" data='{
  "id": "M900iB_280L",
  "rename": "机器人_右",
  "position": [0, 2500, 515],
  "checkFromCloud": true
}'
kunwu_call endpoint="/model/create" data='{
  "id": "M900iB_280L",
  "rename": "机器人_左",
  "position": [0, -2500, 515],
  "checkFromCloud": true
}'

# 1.4 吸盘×2
kunwu_call endpoint="/model/create" data='{
  "id": "吸盘_10",
  "rename": "吸盘_右",
  "position": [0, 2500, 2000],
  "checkFromCloud": true
}'
kunwu_call endpoint="/model/create" data='{
  "id": "吸盘_10",
  "rename": "吸盘_左",
  "position": [0, -2500, 2000],
  "checkFromCloud": true
}'

# 1.5 托盘×4（分布在机器人前后两侧）
kunwu_call endpoint="/model/create" data='{
  "id": "托盘_07",
  "rename": "托盘_右前",
  "position": [3000, 4500, 0],
  "checkFromCloud": true
}'
kunwu_call endpoint="/model/create" data='{
  "id": "托盘_07",
  "rename": "托盘_右后",
  "position": [3000, 500, 0],
  "checkFromCloud": true
}'
kunwu_call endpoint="/model/create" data='{
  "id": "托盘_07",
  "rename": "托盘_左前",
  "position": [3000, -500, 0],
  "checkFromCloud": true
}'
kunwu_call endpoint="/model/create" data='{
  "id": "托盘_07",
  "rename": "托盘_左后",
  "position": [3000, -4500, 0],
  "checkFromCloud": true
}'

# 步骤 2: 设置参数化（必须同时传 position + eulerAngle + parameterizationCfg）
kunwu_call endpoint="/model/set_pose" data='{
  "id": "输送线 modelId",
  "useModeId": true,
  "position": [0, 0, 0],
  "eulerAngle": [0, 0, 0],
  "parameterizationCfg": [
    {"type": 0, "value": 7940},
    {"type": 1, "value": 4340},
    {"type": 2, "value": 708}
  ]
}'

kunwu_call endpoint="/model/set_pose" data='{
  "id": "底座_右 modelId",
  "useModeId": true,
  "position": [0, 2500, 0],
  "eulerAngle": [0, 0, 0],
  "parameterizationCfg": [
    {"type": 0, "value": 1000},
    {"type": 1, "value": 1000},
    {"type": 2, "value": 515}
  ]
}'

# 步骤 3: 获取模型 ID 并执行装配
# 吸盘 → 机器人 → 底座
kunwu_call endpoint="/model/assemble" data='{
  "childId": "吸盘 modelId",
  "parentId": "机器人 modelId",
  "assemblePosIndex": 0,
  "useModeId": true
}'
kunwu_call endpoint="/model/assemble" data='{
  "childId": "机器人 modelId",
  "parentId": "底座 modelId",
  "assemblePosIndex": 0,
  "useModeId": true
}'

托盘布局说明：

         Y+
          ↑
    左后  |  右后
    ──────┼──────
    左前  |  右前
          |
──────────┼──────────→ X+
    输送线 (0,0)
    
机器人_右：Y=2500
机器人_左：Y=-2500
托盘_右前：(3000, 4500)   托盘_右后：(3000, 500)
托盘_左前：(3000, -500)   托盘_左后：(3000, -4500)

装配规则

正确层级：

场景
├── 地轨/底座 → 机器人 → 夹具
├── 桁架 → 自由臂 → 抓手
└── 相机支架 → 相机

错误示例： ❌ 底座 → 桁架（两者都是支撑结构，不应互相装配）

多装配位选择规则：

优先 assemblePosName（按名称匹配）
优先 assemblePosIndex >= 0（兼容位）
自动选择（先找兼容且空闲位）

完整 API 参考

模型库管理

接口	说明	示例
`/model/library/local`	获取本地模型库	`{"get":"true"}`
`/model/library/remote`	获取远程模型库	`{"pageNum":1,"pageSize":10}`
`/model/library/categories`	获取分类列表	`{}`
`/model/library/favorites`	获取收藏列表	`{}`
`/model/library/favorite`	收藏模型	`{"id":"模型名"}`
`/model/library/delete`	删除本地模型	`{"id":"模型名"}`

模型创建与加载

接口	说明	示例
`/model/create`	创建/加载模型（唯一推荐）	`{"id":"模型名","position":[x,y,z],"checkFromCloud":true}`
`/model/set_pose`	设置位置/参数化	`{"id":"模型名","position":[x,y,z],"parameterizationCfg":[...]}`
`/model/set_render`	设置渲染颜色	`{"id":"模型名","color":"#FF0000"}`
`/model/export`	导出模型	`{"id":"模型名"}`
`/model/destroy`	销毁模型	`{"id":"modelId","useModeId":true}`

重要： 始终使用 /model/create 并设置 checkFromCloud: true：

本地有模型 → 直接加载（快速）
本地没有 → 自动从云端下载（无需额外步骤）

⚠️ 参数化设置注意事项： /model/set_pose 设置参数化时必须同时传位置和角度，否则返回 406 错误！

# ✅ 正确 - 三者一起传
kunwu_call endpoint="/model/set_pose" data='{
  "id": "皮带线_01",
  "position": [0, 0, 0],
  "eulerAngle": [0, 0, 0],
  "parameterizationCfg": [
    {"type": 0, "value": 7940},
    {"type": 1, "value": 4340},
    {"type": 2, "value": 708}
  ]
}'

# ❌ 错误 - 只传参数化会失败（406 NotAcceptable）
kunwu_call endpoint="/model/set_pose" data='{
  "id": "皮带线_01",
  "parameterizationCfg": [...]
}'

场景查询

接口	说明	示例
`/models/tree`	获取场景层级树	`{"rootId":"scene","useModeId":true}`
`/GetModelInfo`	获取单个模型信息	`{"id":"modelId","useModeId":true}`
`/GetAllModelInfo`	获取所有模型信息	`{}`
`/scene/get_scene_json`	获取场景 JSON	`{}`

层级与装配

接口	说明	示例
`/model/assemble`	装配到指定位置	`{"childId":"xxx","parentId":"xxx","assemblePosIndex":0}`
`/model/set_parent`	设置父子关系	`{"childId":"xxx","parentId":"xxx"}`

行为控制

接口	说明	示例
`/behavior/add`	添加行为	`{"id":"模型/子节点","behavioralType":1,"referenceAxis":0,...}`
`/behavior/list`	获取行为配置列表	`{"id":"modelId","useModeId":true}`
`/behavior/get`	获取行为参数	`{"id":"模型/子节点","useModeId":false}`
`/behavior/delete`	删除行为	`{"id":"模型/子节点","useModeId":false}`

其他功能

接口	说明	示例
`/batch/execute`	批量执行命令	`{"commands":[{"url":"...","body":{}}]}`
`/view/show_progress`	显示进度条	`{"progress":50,"message":"处理中..."}`
`/ResetScene`	重置场景	`{}`
`/ChangeMode`	切换模式	`{"mode":0}` (0:构建 1:信号 2:机器人 3:孪生)

错误码

Code	说明	处理
200	成功	-
202	任务运行中	等待后查询
400	请求错误	检查参数
404	资源不存在	检查 modelId
409	装配位被占用	`replaceExisting: true`

快速参考

参考轴 (referenceAxis)： 0=X+, 1=X-, 2=Y+, 3=Y-, 4=Z+, 5=Z-

行为类型 (behavioralType)： 1=主动，3=从动

层级路径： "DH_PGS_5_5/1" → 夹具的第一个子关节

更新日志

2026-03-20: 统一模型加载机制（仅用 /model/create + checkFromCloud:true），彻底移除 /model/download
2026-03-19 (3): 补充完整 API 参考表（25+ 接口）
2026-03-19 (2): 新增参数化设置方法（/model/set_pose）+ 完整场景搭建示例
2026-03-16: 固化四大原则 + 相向夹紧原则 + 7 步流程
2026-03-14: 支持从属运动配置
2026-03-13: 新增模型库管理

安全使用建议

This skill appears to implement a legitimate Kunwu Builder API client and many useful helper scripts, but there are inconsistent and potentially dangerous defaults you should fix before use: - Inspect kunwu-tool.js for BASE_URL (line that sets DEFAULT = process.env.KUNWU_API_URL || 'http://100.85.119.45:16888'). That default points to a non-local IP. Before running anything, set KUNWU_API_URL explicitly to the expected host (for example http://127.0.0.1:16888 or your known internal IP) or edit the file to use a safe default. - SKILL.md, README, and QUICKSTART show different default addresses (192.168.30.9, 127.0.0.1, and 100.85.119.45). Decide which host is correct for your environment and update all config/docs; do not rely on package defaults. - Because the skill contains runnable node scripts that will POST scene/model data to the configured API, run the scripts in a controlled environment first (offline or on an isolated network) and monitor network traffic to confirm they only contact the intended host. - The skill requests no credentials, but APIs are unauthenticated in the docs — confirm your Kunwu instance is on a trusted network and not exposed to the Internet. - Search the codebase for any other hardcoded URLs or references to external hosts (e.g., '100.85.119.45', '192.168.30.9', or 'SpeedBot') and replace or remove them. - If you allow the agent to invoke the skill autonomously, be aware it could run scripts that change the simulation state; prefer manual invocation until you vet the scripts. If you want, I can highlight the exact lines in kunwu-tool.js and SKILL.md where the differing defaults appear and suggest an explicit safe configuration to apply.

功能分析

Type: OpenClaw Skill Name: kunwu-builder Version: 1.0.1 The 'kunwu-builder' skill bundle is a comprehensive and legitimate integration for controlling Kunwu Builder (坤吾) industrial simulation software via its HTTP API. The core logic resides in 'kunwu-tool.js', which provides a robust wrapper for model management, robotic control, and scene manipulation. The bundle includes extensive documentation, migration guides, and numerous functional test scripts (e.g., 'test-50-rounds.js', 'test-robot-assembly.js') that demonstrate thorough development and debugging. All network communication is directed toward local or private network IP addresses (such as 192.168.x.x and 100.85.x.x), which is consistent with industrial software environments. No evidence of data exfiltration, malicious execution, or harmful prompt injection was found.

能力评估

ℹ Purpose & Capability

The skill's name, docs, and many JS helpers all implement HTTP calls and helpers for model/behavior management — consistent with 'control Kunwu Builder'. However documentation and code disagree about the API host (SKILL.md: http://192.168.30.9:16888; README/QUICKSTART: 127.0.0.1:16888; kunwu-tool.js default: http://100.85.119.45:16888) and some docs mention 'SpeedBot' (different product name). These mismatches are sloppy and create risk of contacting the wrong machine, but the core capability (HTTP control of a simulation) aligns with the stated purpose.

⚠ Instruction Scope

SKILL.md and other docs instruct the agent (and user) to run node scripts (e.g., scripts/model-loader.js, test-connection-kunwu.js, auto-gripper-behavior.js) that will enumerate scene models and call API endpoints. Those instructions are within the stated purpose, but they also include explicit IP addresses and examples that may point to non-local hosts. The runtime instructions and included code will make arbitrary POSTs to whatever BASE_URL is set to; because some docs and code default to external/non-local addresses, the skill could send scene/model data to an unexpected host if not reconfigured.

✓ Install Mechanism

There is no install spec — the package is instruction + JS files. That is the lower-risk pattern because nothing is automatically downloaded or executed during install. The included scripts will only run if the agent/user invokes them. No remote downloads or extract-from-URL installs were found.

⚠ Credentials

requires.env lists none and no credentials are requested, which is appropriate. However the code reads process.env.KUNWU_API_URL (optional) and the hardcoded default in kunwu-tool.js is an external IP (http://100.85.119.45:16888). That default is disproportionate for a tool that should target a local instance and could cause network calls to a remote host without additional credentials or explicit user configuration.

✓ Persistence & Privilege

always is false and the skill does not request system-wide privileges. The package contains scripts and docs that instruct how to tar/transfer the skill, but there is no automatic persistence or modification of other skills' configuration. Note: autonomous invocation is allowed by default (normal for skills); combined with the non-local default endpoint this increases the impact if an agent runs scripts without the user locking the API URL.

版本历史

v1.0.1

统一模型加载机制：移除/model/download，全面采用/model/create+checkFromCloud:true；新增批量加载工具 scripts/model-loader.js；完善参数化设置注意事项；新增双机器人 + 托盘布局示例

v1.0.0

Kunwu Builder 控制技能 1.0.0 初始发布 - 提供通过 HTTP API 控制 Kunwu Builder 工业仿真软件的丰富功能 - 支持模型管理、机器人控制、物流及传感器操作、相机控制、场景管理等 - 新增批量执行、进度提示、排产结果回传及模型库管理接口 - 提供夹具等高级行为配置指引与实用示例 - 所有功能无需认证，为本地接口，使用范例覆盖常见场景

元数据

Slug kunwu-builder

版本 1.0.1

许可证 MIT-0

累计安装 1

当前安装数 1

历史版本数 2

常见问题

Kunwu Builder 是什么？

控制Kunwu Builder工业仿真软件的HTTP API，实现模型管理、机器人控制、物流设备、相机及传感器操作、场景与行为配置等功能。它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 303 次。

如何安装 Kunwu Builder？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install kunwu-builder」即可一键安装，无需额外配置。

Kunwu Builder 是免费的吗？

是的，Kunwu Builder 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Kunwu Builder 支持哪些平台？

Kunwu Builder 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Kunwu Builder？

由 Sam（@samwlh）开发并维护，当前版本 v1.0.1。

Kunwu Builder