Pudu OpenAPI Skill

工作流

1. 检查凭证        → 读取 / 提示 ApiAppKey & ApiAppSecret
2. 确认集群        → 读取 PUDU_API_CLUSTER；若缺失，必须询问用户选择，禁止默认任意集群 → 确定 BASE_URL
3. 理解用户意图    → 定位功能组 → 读取对应 assets/*.json
4. 归一化参数名    → 将用户输入字段映射为接口规范中的真实字段名
5. 构建并执行请求  → 按环境优先级执行脚本 (js -> py -> go -> java -> cs)
6. 展示结果        → 200 且 message=SUCCESS 美化输出，否则输出错误原因

第一步：检查凭证

优先从环境变量读取：

若任意变量缺失，停止执行并提示：

缺少以下凭证，请通过以下任一方式提供：

方式一（推荐）：设置环境变量
```bash
export PUDUAPIAPP_KEY="your-key"
export PUDUAPIAPP_SECRET="your-secret"
```

方式二：直接告诉我
请输入您的 ApiAppKey 和 ApiAppSecret。

如果您还没有凭证
请访问 普渡开放平台快速开始 按照教程申请。

两项均确认后方可继续。

敏感凭证处理规则

• 优先建议用户通过环境变量提供凭证，而不是直接在对话中粘贴
• 若用户直接提供 ApiAppSecret，不要在回复、日志、报错、示例代码中回显完整值
• 不要将用户提供的 ApiAppKey / ApiAppSecret 写入仓库文件、脚本常量或示例代码
• 在排查问题时，只允许使用脱敏后的形式展示，例如 abc***xyz

第二步：确认集群

优先读取环境变量 PUDUAPICLUSTER，取值映射如下：

若环境变量未设置、为空，或当前上下文中无法明确判断集群，必须使用 AskQuestion 工具让用户明确选择集群。

严禁在未获得用户确认时默认选择任意集群（包括但不限于默认使用 cn）。

在用户完成选择后，再提示可通过以下方式固化设置：

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

所有接口请求的完整 URL 格式：

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

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

根据用户描述，定位功能组并读取对应规范文件获取接口的路径、参数和请求体结构：

完整能力范围、典型场景和代表接口请参考：references/capabilities.md

第四步：参数名归一化

用户输入的参数名可能使用驼峰、下划线或中划线格式。构建 params 前，必须根据当前接口规范中的 parameters 和 requestBody schema，将用户字段自动映射为接口要求的真实字段名：

• shopId / shopid / shop-id → 按当前接口规范转换为 shopId 或 shopid
• groupId / groupid / group-id → 按当前接口规范转换为 groupId 或 groupid
• payload.startPoint / payload.start_point / payload.start-point → 按 schema 转换为真实嵌套字段名

归一化规则：

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

第五步：构建并执行请求

构建参数并执行请求脚本。脚本执行优先级如下，当因为环境问题无法执行当前脚本时（如没有安装 Node.js），则依次向下尝试下一个脚本：

1. scripts/pudu-request.js
2. scripts/pudu-request.py
3. scripts/pudu-request.go
4. scripts/pudu-request.java
5. scripts/pudu-request.cs

示例（以执行 pudu-request.js 为例）：

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

const result = await request({
  cluster:      process.env.PUDU_API_CLUSTER,   // 或显式传入 "cn" / "sea" / "de" / "us"
  path:         "/pudu-entry<从规范文件读取的 path>",
  method:       "<GET 或 POST>",
  params:       { /* 从用户 prompt 和规范文件提取参数 */ },
  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);
}

说明：

• request() 会优先读取环境变量中的 PUDUAPIAPPKEY、PUDUAPIAPPSECRET、PUDUAPICLUSTER
• 若显式传入 apiAppKey / apiAppSecret / cluster / hostname，则以显式参数为准
• path 需包含 /pudu-entry 前缀，例如：/pudu-entry/open-platform-service/v2/status/getbysn （如果接口是针对 /data-board 的统计接口，路径也会是类似 /pudu-entry/data-board/v1/analysis/run 等，具体以规范文件为准）
• params 需要根据用户 prompt 和 OpenAPI 规范文件共同构建，不能只靠自然语言猜测字段；发出请求前必须完成参数名归一化，确保所有字段名与规范完全一致
• 当接口需要 sn 时，若用户传入的值形如 14:80:CC:89:27:A6，应判断为 MAC 地址而非 SN，并主动提醒用户改为提供真实机器人 SN

第六步：展示结果

成功判定规则

只有同时满足以下条件才表示成功：

1. HTTP 状态码为 200
2. 返回结果中的 message === "SUCCESS"

成功响应示例：

{
  "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"
}

判定成功时的展示方式

将 body 解析为 JSON 并美化展示：

✅ 调用成功

接口：GET /open-platform-service/v2/status/get_by_sn
集群：国内生产节点

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

判定失败时的展示方式

以下任一情况都视为失败：

• HTTP 状态码非 200
• HTTP 状态码为 200，但 message !== "SUCCESS"

解析错误信息并输出：

❌ 调用失败（HTTP 401）

接口：GET /open-platform-service/v2/status/get_by_sn

错误原因：Unauthorized — ApiAppKey 或签名验证失败，请检查凭证是否正确。

常见错误码参考：

常用接口速查

# 查询机器人状态（推荐 v2）
GET /open-platform-service/v2/status/get_by_sn?sn={sn}
GET /open-platform-service/v1/status/get_by_group_id?groupId={groupId}

# 下发任务
POST /open-platform-service/v1/delivery_task
POST /open-platform-service/v1/transport_task

# 一键回充（推荐 v2）
GET /open-platform-service/v2/recharge?sn={sn}

# 呼叫机器人
POST /open-platform-service/v1/custom_call

# 地图与交管区
GET /data-open-platform-service/v1/api/maps?shop_id={shop_id}
POST /map-service/v1/open/traffic_control/list

# 查询机器运行概览和分析
GET /data-board/v1/brief/run?shopId={shopId}
GET /data-board/v1/analysis/run?shopId={shopId}

# 广告播放与配置
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

# 货柜任务与货柜 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

# 闪电匣舱门拍照
POST /biz-open-service/v1/robotDoor/task_list

注意事项

• v2 接口优先于旧版本（status/getbysn），recharge 请优先使用 v2，状态字段更简洁
• 标注 (闪电匣) 的接口仅适用于带货柜的机器人型号
• sn 为机器人序列号，shopId 为门店 ID，是最常用的标识字段
• MAC 地址常见格式为 14:80:CC:89:27:A6；若接口要求 sn，不能直接用 MAC 地址替代
• 配送、运送、跑腿、顶升等任务有对应的 *_action 接口用于暂停/继续/取消
• 如果用户有编写Open API请求 sdk 的意图，根据用户指定的编程语言，参考 references/request-sdk.md，输出对应语言的标准实现范例。