pudu-openapi-skill

Original：🇨🇳 Chinese

Translated

2 scriptsChecked / no sensitive code detected

Call the cloud OpenAPI of Pudu robots, supporting operations such as robot task distribution, status query, delivery, cruise, call, and statistical data analysis. When using, first check the credentials and cluster environment variables; if missing, prompt the user to supplement them, then call the corresponding interface according to the user's intention and display the results. Trigger scenarios: Use this skill when the user mentions keywords such as "Pudu robot", "pudu", "robot task distribution", "query robot status", "delivery task", "cruise task", "call robot", "lifting task", "errand", "Flash Cabinet", "advertisement playback", "advertisement configuration", "cabinet task", "cabinet SKU", "product SKU", "hatch door photo", "traffic control zone", "map list", "statistical data", "risk avoidance", "dashboard overview", "OpenAPI".

6installs

Sourcepudu-robotics/skills

Added on2026-06-02

NPX Install

npx skill4agent add pudu-robotics/skills pudu-openapi-skill

SKILL.md Content (Chinese)

View Translation Comparison →

Pudu OpenAPI Skill

Workflow

1. Check Credentials        → Read / Prompt for ApiAppKey & ApiAppSecret
2. Confirm Cluster        → Read PUDU_API_CLUSTER; if missing, must ask user to select, prohibit defaulting to any cluster → Determine BASE_URL
3. Understand User Intent    → Locate functional group → Read corresponding assets/*.json
4. Normalize Parameter Names    → Map user input fields to real field names specified in the interface specification
5. Build and Execute Request  → Execute scripts according to environment priority (js -> py -> go -> java -> cs)
6. Display Results        → Beautify output if status code is 200 and message=SUCCESS, otherwise output error cause

Step 1: Check Credentials

Read from environment variables first:

Variable Name	Description
`PUDU_API_APP_KEY`	ApiAppKey
`PUDU_API_APP_SECRET`	ApiAppSecret

If any variable is missing, stop execution and prompt:

The following credentials are missing. Please provide them via one of the following methods:

Method 1 (Recommended): Set environment variables
bash
export PUDU_API_APP_KEY="your-key"
export PUDU_API_APP_SECRET="your-secret"
Method 2: Tell me directly Please enter your ApiAppKey and ApiAppSecret.

If you don't have credentials yet Please visit Pudu Open Platform Quick Start and follow the tutorial to apply.

Proceed only after both are confirmed.

Sensitive Credential Handling Rules

Prioritize suggesting users to provide credentials via environment variables instead of pasting directly in the conversation
If the user provides
```
ApiAppSecret
```
directly, do not echo the full value in replies, logs, error messages, or sample code
Do not write the user-provided
```
ApiAppKey
```
/
```
ApiAppSecret
```
into repository files, script constants, or sample code
When troubleshooting, only display the desensitized form, e.g.,
```
abc***xyz
```

Step 2: Confirm Cluster

First read the environment variable

PUDU_API_CLUSTER

, with value mappings as follows:

Environment Variable Value	Cluster	hostname
`cn`	Domestic Production Node	`open-platform.pudutech.com`
`sea`	Overseas (Japan, Korea, Singapore) Production Node	`css-open-platform.pudutech.com`
`de`	Germany Production Node	`csg-open-platform.pudutech.com`
`us`	US Production Node	`csu-open-platform.pudutech.com`

If the environment variable is not set, empty, or the cluster cannot be clearly determined in the current context, must use the AskQuestion tool to let the user explicitly select the cluster.

Strictly prohibit defaulting to any cluster (including but not limited to defaulting to

cn

) without user confirmation.

After the user completes the selection, prompt that the setting can be persisted as follows:

bash

export PUDU_API_CLUSTER="cn"   # cn / sea / de / us

Full URL format for all interface requests:

https://{hostname}/pudu-entry{path}

Step 3: Understand Intent → Locate Interface

According to the user's description, locate the functional group and read the corresponding specification file to obtain the interface path, parameters, and request body structure:

Functional Group	Specification File	Typical Scenarios
Robot Status and Information Query	`assets/01-robot-status.json`	Query status, location, task status
Delivery and Transport Tasks	`assets/02-delivery-transport.json`	Issue delivery tasks, multi-point transport
Errand Tasks	`assets/03-errand.json`	Errand mode tasks
Lifting and Tray Tasks	`assets/04-lifting-tray.json`	Lifting robot tasks, tray orders
Cruise Tasks	`assets/05-cruise-guide.json`	Issue cruise tasks, query cruise routes
Call Tasks	`assets/06-call.json`	Custom call robot
Flash Cabinet Exclusive Functions	`assets/07-flash-cabinet.json`	Hatch door status/control, hatch door photo tasks, elevator internal screenshots
Content, Voice and Media	`assets/08-media-content.json`	Screen display, voice broadcast, volume
Basic Control and Data Reporting	`assets/09-control-reporting.json`	Charging, map switching, location reporting, traffic control zone reporting and query
Cleaning Statistical Analysis	`assets/10-analysis-clean.json`	Charts and paginated data for cleaning modes like floor mopping, sweeping
General Statistical Analysis	`assets/11-analysis-common.json`	Machine overview, store overview and operation analysis data
Delivery Statistical Analysis	`assets/12-analysis-delivery.json`	Details and chart data for modes like delivery, call, cruise
Industry Statistical Analysis	`assets/13-analysis-industry.json`	Statistical details and chart data for industry tasks like lifting
Briefing Data	`assets/14-brief.json`	Core operation dashboard data for stores and machines
Logs and Reporting Records	`assets/15-log.json`	List query for self-test on startup, battery charging, fault events, etc.
Task Scheduling and History	`assets/16-tasks.json`	Execution details and timeline of destinations for tasks like call, delivery
Store and Basic Data	`assets/17-shop-data.json`	Store list query, machine list query
Map Services	`assets/18-map-service.json`	Get map list, map list under store, map details, current map, point information, point grouping, map base map
Advertisement Playback and Configuration	`assets/19-ad.json`	Advertisement list, details, creation, update, deletion, scenario menu
Cabinet Tasks and Cabinet SKU	`assets/20-cabinet-sku.json`	Product SKU synchronization, SKU query, cabinet list, cabinet delivery order placement
Machine Risk Avoidance	`assets/21-risk-avoidance.json`	Initiate risk avoidance task, cancel risk avoidance task

For complete capability scope, typical scenarios and representative interfaces, please refer to:

references/capabilities.md

Step 4: Parameter Name Normalization

Parameter names entered by users may use camelCase, snake_case, or kebab-case formats. Before building

params

, must automatically map user fields to the real 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 real nested field names according to the schema

Normalization Rules:

Build a whitelist of field names using the current interface specification; do not decide the final field names based on common sense
Ignore case,
```
_
```
and
```
-
```
when matching, but the final output must retain the original field name format 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 the same input field can match 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

Build parameters and execute the request script. The script execution priority is as follows; if the current script cannot be executed due to environment issues (e.g., Node.js not installed), try the next script in sequence:

```
scripts/pudu-request.js
```
```
scripts/pudu-request.py
```
```
scripts/pudu-request.go
```
```
scripts/pudu-request.java
```
```
scripts/pudu-request.cs
```

Example (taking execution of

pudu-request.js

as an example):

const { request } = require("./scripts/pudu-request");

const result = await request({
  cluster:      process.env.PUDU_API_CLUSTER,   // Or explicitly pass "cn" / "sea" / "de" / "us"
  path:         "/pudu-entry<path read from specification file>",
  method:       "<GET or POST>",
  params:       { /* Parameters extracted from user prompt and specification file */ },
  apiAppKey:    process.env.PUDU_API_APP_KEY,
  apiAppSecret: process.env.PUDU_API_APP_SECRET,
});

if (result.ok) {
  console.log(result.json);
} else {
  console.error(result.errorMessage);
}

Explanation:

request()

will first read

PUDU_API_APP_KEY

PUDU_API_APP_SECRET

PUDU_API_CLUSTER

from environment variables

If
```
apiAppKey
```
/
```
apiAppSecret
```
/
```
cluster
```
/
```
hostname
```
are explicitly passed, the explicit parameters will take precedence
```
path
```
must include the
```
/pudu-entry
```
prefix, e.g.,
```
/pudu-entry/open-platform-service/v2/status/get_by_sn
```
(if the interface is a statistical interface for
```
/data-board
```
, the path will be similar to
```
/pudu-entry/data-board/v1/analysis/run
```
, etc., subject to the specification file)
```
params
```
needs to be built based on both the user prompt and the OpenAPI specification file; do not guess fields only by natural language; must complete parameter name normalization before sending the request to ensure all field names are completely consistent with the specification
When the interface requires
```
sn
```
, if the value passed by the user is in the format of
```
14:80:CC:89:27:A6
```
, it should be judged as a MAC address instead of SN, and the user should be actively reminded to provide the real robot SN

Step 6: Display Results

Success Judgment Rules

Only when the following conditions are met simultaneously is it considered successful:

HTTP status code is
```
200
```
```
message === "SUCCESS"
```
in the returned result

Success response example:

json

{
  "data": {
    "count": 110,
    "list": [
      {
        "company_id": "13947",
        "company_name": "chixzdls_internal02二级代理商",
        "shop_id": "324100000",
        "shop_name": "【10月08日】出尘门店"
      },
      {
        "company_id": "13947",
        "company_name": "chixzdls_internal02二级代理商",
        "shop_id": "325300001",
        "shop_name": "闪电匣和很多葫芦"
      }
    ]
  },
  "message": "SUCCESS",
  "trace_id": "YourApiAppKey_405eb004-7f09-4d86-bff1-4657cdec2717"
}

Display Method When Successful

Parse the

body

into JSON and display it beautifully:

✅ Call Successful

Interface: GET /open-platform-service/v2/status/get_by_sn
Cluster: Domestic Production Node

{
  "message": "SUCCESS",
  "data": {
    "sn": "robot-001",
    "runState": "IDLE",
    "battery": 85,
    ...
  }
}

Display Method When Failed

Any of the following situations is considered a failure:

HTTP status code is not
```
200
```
HTTP status code is
```
200
```
, but
```
message !== "SUCCESS"
```

Parse the error message and output:

❌ Call Failed (HTTP 401)

Interface: GET /open-platform-service/v2/status/get_by_sn

Error Cause: Unauthorized — ApiAppKey or signature verification failed, please check if the credentials are correct.

Common Error Code Reference:

HTTP Status Code	Meaning	Handling Suggestion
401	Signature verification failed	Check if ApiAppKey / ApiAppSecret are correct
403	No permission	Confirm whether the interface has been activated
404	Interface path does not exist	Check if path and cluster match
500	Server error	Retry or contact Pudu technical support

Quick Reference for Common Interfaces

# Query Robot Status (v2 recommended)
GET /open-platform-service/v2/status/get_by_sn?sn={sn}
GET /open-platform-service/v1/status/get_by_group_id?groupId={groupId}

# Issue Tasks
POST /open-platform-service/v1/delivery_task
POST /open-platform-service/v1/transport_task

# One-click Recharge (v2 recommended)
GET /open-platform-service/v2/recharge?sn={sn}

# Call Robot
POST /open-platform-service/v1/custom_call

# Maps and Traffic Control Zones
GET /data-open-platform-service/v1/api/maps?shop_id={shop_id}
POST /map-service/v1/open/traffic_control/list

# Query Machine Operation Overview and Analysis
GET /data-board/v1/brief/run?shopId={shopId}
GET /data-board/v1/analysis/run?shopId={shopId}

# Advertisement Playback and Configuration
POST /biz-service/openPlatform/api/v1/gg/list
GET /biz-service/openPlatform/api/v1/gg/get?id={id}&shop_id={shop_id}
POST /biz-service/openPlatform/api/v1/gg/create

# Cabinet Tasks and Cabinet SKU
POST /community-open-service/api/product_sku/v2/upsert
GET /community-open-service/api/cabinet/v1/list?shop_id={shop_id}
POST /community-open-service/api/cabinet/send_task

# Flash Cabinet Hatch Door Photo
POST /biz-open-service/v1/robotDoor/task_list

Notes

v2 interfaces take precedence over older versions (e.g.,
```
status/get_by_sn
```
), please use v2 for
```
recharge
```
as the status fields are more concise
Interfaces marked with
```
(Flash Cabinet)
```
are only applicable to robot models with cabinets
```
sn
```
is the robot serial number,
```
shopId
```
is the store ID, which are the most commonly used identification fields
MAC addresses are commonly in the format of
```
14:80:CC:89:27:A6
```
; if the interface requires
```
sn
```
, do not directly use a MAC address instead
Tasks such as delivery, transport, errand, lifting have corresponding
```
*_action
```
interfaces for pause/resume/cancel
If the user intends to write an Open API request SDK, according to the programming language specified by the user, refer to
```
references/request-sdk.md
```
and output a standard implementation example in the corresponding language.