pudu-cloudveil-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

云隐 CloudVeil Skill

CloudVeil (Yunyin) Skill

工作流

Workflow

1. 检查环境        → 确认 CLOUDVEIL_BASE_URL / CLOUDVEIL_ACCOUNT / CLOUDVEIL_PASSWORD
2. 认证            → 使用 SSO getSecret + SM2 加密 + accountLogin 获取 access_token
3. 理解意图        → 定位功能组 → 读取 references/capabilities.md 和命中的分组文档
4. 归一化参数名    → 将用户输入字段映射为接口规范中的真实字段名
5. 构建并执行请求  → 从 assets/*.openapi.json 读取 method、query、requestBody、schema
6. 展示结果        → 200 且 message === "SUCCESS" 视为成功，否则按失败展示

1. Check Environment        → Verify CLOUDVEIL_BASE_URL / CLOUDVEIL_ACCOUNT / CLOUDVEIL_PASSWORD
2. Authentication            → Use SSO getSecret + SM2 encryption + accountLogin to obtain access_token
3. Understand Intent        → Locate functional group → Read references/capabilities.md and the hit group documents
4. Normalize Parameter Names    → Map user input fields to the actual field names specified in the interface specification
5. Build and Execute Request  → Read method, query, requestBody, schema from assets/*.openapi.json
6. Display Results        → Consider it successful only if HTTP status is 200 and message === "SUCCESS"; otherwise, display as failed

第一步：检查环境

Step 1: Check Environment

任何真实调用前，先读取

references/request-sdk.md

并检查：

变量	作用
`CLOUDVEIL_BASE_URL`	CloudVeil 服务器基础地址，例如 `https://cloudveil.example.com`
`CLOUDVEIL_ACCOUNT`	CloudVeil 登录账号
`CLOUDVEIL_PASSWORD`	CloudVeil 登录密码

若缺少任一变量，停止执行并提示用户补齐。不要默认演示地址，不要把账号、密码、访问 token 或加密后的凭证写入仓库文件。

Before any actual call, read

references/request-sdk.md

and check the following:

Variable	Function
`CLOUDVEIL_BASE_URL`	CloudVeil server base URL, e.g., `https://cloudveil.example.com`
`CLOUDVEIL_ACCOUNT`	CloudVeil login account
`CLOUDVEIL_PASSWORD`	CloudVeil login password

If any variable is missing, stop execution and prompt the user to complete it. Do not use default demo URLs, and do not write accounts, passwords, access tokens, or encrypted credentials into repository files.

第二步：认证

Step 2: Authentication

CloudVeil 使用 SSO/SM2 登录流程：

GET /openapi/sso/api/v1/secret/getSecret

用返回的

data.secret

对

CLOUDVEIL_ACCOUNT

和

CLOUDVEIL_PASSWORD

做 SM2 加密

POST /openapi/sso/api/v1/account/accountLogin

使用
```
data.access_token
```
调用目标 OpenAPI

具体调用规则、token 头部覆盖项和

scripts/cloudveil-request.js

用法见

references/request-sdk.md

。

CloudVeil uses the SSO/SM2 login process:

GET /openapi/sso/api/v1/secret/getSecret

Use the returned

data.secret

to encrypt

CLOUDVEIL_ACCOUNT

and

CLOUDVEIL_PASSWORD

with SM2

POST /openapi/sso/api/v1/account/accountLogin

Use
```
data.access_token
```
to call the target OpenAPI

For specific call rules, token header overrides, and usage of

scripts/cloudveil-request.js

, refer to

references/request-sdk.md

第三步：理解意图并定位接口

Step 3: Understand Intent and Locate Interface

先读

references/capabilities.md

，根据用户描述定位功能组，再只打开命中的分组文档和 asset。

功能组	详细文档	OpenAPI asset	典型场景
通用接口	`references/capabilities-common.md`	`assets/common.openapi.json`	门店、地图、机器人组、位置
机器人信息	`references/capabilities-robot-info.md`	`assets/robot-info.openapi.json`	机器人状态、任务状态
机器人任务	`references/capabilities-robot-tasks.md`	`assets/robot-tasks.openapi.json`	呼叫、配送、运送、跑腿、顶升、托盘、领位
控制指令	`references/capabilities-control.md`	`assets/control.openapi.json`	位置上报、切图、一键回充、刷卡、设备影子
统计数据	`references/capabilities-statistics.md`	`assets/statistics.openapi.json`	数据看板、分析、任务明细、日志
订单到人（试用版）	`references/capabilities-order-to-person.md`	`assets/order-to-person.openapi.json`	订单、托盘配置、巷道、拣货、批次、仓库
回调通知	`references/capabilities-callbacks.md`	Not covered	被动回调参数说明
机器人调度	`references/capabilities-dispatch.md`	Not covered	交管区 / 调度接口

标记为 Not covered 的分组没有 bundled OpenAPI asset。不要编造路径、参数、回调或请求体。

First read

references/capabilities.md

, locate the functional group based on the user's description, then only open the hit group documents and assets.

Functional Group	Detailed Document	OpenAPI Asset	Typical Scenarios
Common Interfaces	`references/capabilities-common.md`	`assets/common.openapi.json`	Stores, maps, robot groups, locations
Robot Information	`references/capabilities-robot-info.md`	`assets/robot-info.openapi.json`	Robot status, task status
Robot Tasks	`references/capabilities-robot-tasks.md`	`assets/robot-tasks.openapi.json`	Calling, delivery, transport, errand, lifting, pallet, hosting
Control Commands	`references/capabilities-control.md`	`assets/control.openapi.json`	Position reporting, map switching, one-click recharge, card swiping, device shadow
Statistical Data	`references/capabilities-statistics.md`	`assets/statistics.openapi.json`	Data board, analysis, task details, logs
Order-to-Person (Beta)	`references/capabilities-order-to-person.md`	`assets/order-to-person.openapi.json`	Orders, pallet configuration, aisles, picking, batches, warehouses
Callback Notifications	`references/capabilities-callbacks.md`	Not covered	Passive callback parameter description
Robot Dispatch	`references/capabilities-dispatch.md`	Not covered	Traffic control zone / dispatch interfaces

Groups marked as Not covered do not have bundled OpenAPI assets. Do not fabricate paths, parameters, callbacks, or request bodies.

第四步：参数名归一化

Step 4: Normalize Parameter Names

用户输入的参数名可能使用驼峰、下划线或中划线格式。构建 query 或 JSON request body 前，必须根据当前接口规范中的

parameters

和

requestBody

schema，将用户字段自动映射为接口要求的真实字段名：

```
shopId
```
/
```
shop_id
```
/
```
shop-id
```
→ 按当前接口规范转换为
```
shopId
```
或
```
shop_id
```
```
groupId
```
/
```
group_id
```
/
```
group-id
```
→ 按当前接口规范转换为
```
groupId
```
或
```
group_id
```

payload.startPoint

payload.start_point

payload.start-point

→ 按 schema 转换为真实嵌套字段名

归一化规则：

用当前接口规范构建字段名白名单；不要凭常识自行决定最终字段名
匹配时忽略大小写，并忽略
```
_
```
和
```
-
```
，但最终输出必须保留规范中的原始字段名格式
对 request body 的对象、数组对象也要递归应用同样规则
只转换字段名，不改变字段值
如果同一个输入字段可匹配多个规范字段，或字段不在规范中，先向用户确认；不要把未知字段直接发给接口

Parameter names entered by users may use camelCase, snake_case, or kebab-case formats. Before building query or JSON request bodies, you must automatically map user fields to the actual field names required by the interface according to the

parameters

and

requestBody

schema in the current interface specification:

```
shopId
```
/
```
shop_id
```
/
```
shop-id
```
→ Convert to
```
shopId
```
or
```
shop_id
```
according to the current interface specification
```
groupId
```
/
```
group_id
```
/
```
group-id
```
→ Convert to
```
groupId
```
or
```
group_id
```
according to the current interface specification
```
payload.startPoint
```
/
```
payload.start_point
```
/
```
payload.start-point
```
→ Convert to the actual nested field name according to the schema

Normalization Rules:

Build a whitelist of field names using the current interface specification; do not determine the final field names based on common sense
Ignore case,
```
_
```
, and
```
-
```
during matching, but the final output must retain the original field name format specified in the specification
Apply the same rules recursively to objects and array objects in the request body
Only convert field names, do not change field values
If an input field matches multiple specification fields, or the field is not in the specification, confirm with the user first; do not send unknown fields directly to the interface

第五步：构建并执行请求

Step 5: Build and Execute Request

从对应

assets/*.openapi.json

读取精确 method、query 参数、JSON requestBody、Schema 和响应结构。不要只靠自然语言猜字段名；发出请求前必须完成参数名归一化，确保所有字段名与规范完全一致。

大范围查找时优先用

jq

或

rg

，不要把整份 asset 加载进上下文：

bash

jq -r '.paths | keys[]' assets/robot-tasks.openapi.json
jq '.paths["/openapi/open-platform-service/v1/custom_call"].post.requestBody' assets/robot-tasks.openapi.json
jq '.paths["/openapi/data-board/v1/brief/shop"].get.parameters' assets/statistics.openapi.json
jq '.paths["/openapi/order_to_user/v1/order/import"].post.requestBody' assets/order-to-person.openapi.json

真实调用使用：

bash

node scripts/cloudveil-request.js --path <api-path> [--method GET|POST] [--param key=value] [--body-json '<json>']

Read the exact method, query parameters, JSON requestBody, Schema, and response structure from the corresponding

assets/*.openapi.json

. Do not guess field names based solely on natural language; parameter name normalization must be completed before sending the request to ensure all field names are exactly consistent with the specification.

Use

jq

rg

for large-scale searches instead of loading the entire asset into the context:

bash

jq -r '.paths | keys[]' assets/robot-tasks.openapi.json
jq '.paths["/openapi/open-platform-service/v1/custom_call"].post.requestBody' assets/robot-tasks.openapi.json
jq '.paths["/openapi/data-board/v1/brief/shop"].get.parameters' assets/statistics.openapi.json
jq '.paths["/openapi/order_to_user/v1/order/import"].post.requestBody' assets/order-to-person.openapi.json

For actual calls, use:

bash

node scripts/cloudveil-request.js --path <api-path> [--method GET|POST] [--param key=value] [--body-json '<json>']

第六步：展示结果

Step 6: Display Results

成功必须同时满足：

HTTP 状态码为
```
200
```
响应 JSON 的
```
message === "SUCCESS"
```

如果 HTTP 为 200 但

message

不是

SUCCESS

，按业务失败处理。展示结果时保留接口、method、关键参数和返回 JSON；凭证、token、密码和 SM2 加密结果只能脱敏显示。

Success must meet both of the following conditions:

HTTP status code is
```
200
```
```
message === "SUCCESS"
```
in the response JSON

If HTTP status is 200 but

message

is not

SUCCESS

, treat it as a business failure. When displaying results, retain the interface, method, key parameters, and returned JSON; credentials, tokens, passwords, and SM2 encryption results must be desensitized.

常用接口速查

Quick Reference for Common Interfaces

text

undefined

text

undefined

机器人状态

Robot Status

GET /openapi/open-platform-service/v2/status/get_by_sn GET /openapi/open-platform-service/v2/status/get_by_group_id

地图与位置

Maps and Locations

GET /openapi/map-service/v1/open/current GET /openapi/open-platform-service/v1/robot/get_position POST /openapi/map-service/v1/open/group

任务

Tasks

POST /openapi/open-platform-service/v1/custom_call POST /openapi/open-platform-service/v1/delivery_task POST /openapi/open-platform-service/v1/transport_task POST /openapi/open-platform-service/v1/task_errand POST /openapi/open-platform-service/v1/lifting_task

控制

Control

GET /openapi/open-platform-service/v2/recharge POST /openapi/open-platform-service/v1/switch_map

统计

Statistics

GET /openapi/data-board/v1/brief/shop GET /openapi/data-board/v1/analysis/run

订单到人

Order-to-Person

POST /openapi/order_to_user/v1/order/import GET /openapi/order_to_user/v1/batch/query GET /openapi/order_to_user/v1/warehouse/query_points

undefined

POST /openapi/order_to_user/v1/order/import GET /openapi/order_to_user/v1/batch/query GET /openapi/order_to_user/v1/warehouse/query_points

undefined