金大哥 - kujiale-3d-model-upload Skill 详情

Skill 说明

此 skill 封装 kujiale_upload.py，用于校验完整的酷家乐 OpenAPI 3D 模型上传链路。它只依赖 Python requests / oss2，并显式关闭从环境继承的代理和证书配置（trust_env=False），避免某些 Windows 环境中的 TLS 握手问题。

| 步骤 | 方法 | 端点 | 说明 | |------|------|------|------| | 1 | GET | /v2/commodity/upload/sts | 获取 OSS STS 凭据和 uploadTaskId | | 2 | PUT | Alibaba OSS (oss2) | 将 ZIP 文件上传到 OSS | | 3 | POST | /v2/commodity/upload/create | 触发服务端模型解析 | | 4 | GET | /v2/commodity/upload/status | 轮询解析状态，直到 status == 3 | | 5 | POST | /v2/commodity/upload/submit | 提交已解析模型，返回 brandGoodId |

认证签名规则：md5(appSecret + appKey + timestamp_ms)。

API Key 申请入口：Manycore OpenAPI Console。

快速开始

Windows PowerShell：

python -m pip install requests oss2

$env:KUJIALE_APP_KEY = "your_app_key_here"
$env:KUJIALE_APP_SECRET = "your_app_secret_here"

python .\kujiale_upload.py --dry-run
python .\kujiale_upload.py --zip "C:\path\to\model.zip"

macOS/Linux Bash：

python -m pip install requests oss2

export KUJIALE_APP_KEY="your_app_key_here"
export KUJIALE_APP_SECRET="your_app_secret_here"

python kujiale_upload.py --dry-run
python kujiale_upload.py --zip /path/to/model.zip

前置条件和范围

使用者需要具备：

有效的酷家乐 OpenAPI appKey / appSecret
具备调用商品模型上传 API 的租户权限
符合酷家乐 3D 模型导入要求的 .zip 包
能访问 openapi.kujiale.com 以及步骤 1 返回的 OSS 端点

本仓库不包含：

任何内置真实凭据
对自动生成占位 ZIP 是生产可用 3D 模型包的保证
除 kujiale_upload.py 示例默认值之外的租户专属类目映射

自动生成的 ZIP 仅用于 API 连通性和流程烟测。

配置

必填凭据

必须提供自己的酷家乐 OpenAPI 凭据；脚本没有任何内置默认凭据。

| 方式 | 设置方法 | |------|----------| | 环境变量（推荐） | KUJIALE_APP_KEY=xxx / KUJIALE_APP_SECRET=xxx | | CLI 参数 | --app-key xxx --app-secret xxx | | Python 字典 | run_skill({"app_key": "xxx", "app_secret": "xxx"}) |

优先级：显式 CLI/字典值 > 环境变量。

缺少凭据时会看到：

失败: 缺少必填凭据: app_key (env: KUJIALE_APP_KEY), app_secret (env: KUJIALE_APP_SECRET).
请设置环境变量，或通过 --app-key / --app-secret 传入。

参数列表

| 参数 | 环境变量 / 字典 key | 默认值 | 说明 | |------|----------------------|--------|------| | app_key | KUJIALE_APP_KEY | 必填 | 酷家乐 OpenAPI appKey | | app_secret | KUJIALE_APP_SECRET | 必填 | 酷家乐 OpenAPI appSecret | | zip_path | - | 自动生成测试 ZIP | 要上传的 ZIP 文件路径 | | poll_interval | - | 5.0 | 状态轮询间隔，单位秒 | | poll_timeout | - | 300.0 | 等待解析完成的最长时间，单位秒 | | dry_run | - | False | 为 True 时跳过所有网络调用并返回 mock 数据 |

传输行为

API 调用使用 requests，OSS 上传使用 oss2
脚本创建独立 session，并设置 trust_env=False
这样可以避免 shell 或 IDE 注入的代理、CA bundle 等环境变量破坏 TLS 握手
如果在限制外网访问的 agent 或沙箱环境中运行，真实上传路径需要能访问 openapi.kujiale.com 和返回的 OSS 端点；脚本会明确提示这类网络限制

步骤 5 内置默认值

kujiale_upload.py 当前提交模型时使用这些示例默认值：

location = 1
brandCats = ["3FO4K6E984C7"]

这些值不是通用配置。它们来自原始实现中的业务默认值，可能不适合其他租户或类目树。真实提交前，如果账号需要不同类目信息，请先更新脚本。

用法

CLI

# 从环境变量读取凭据
python .\kujiale_upload.py

# 显式传入凭据
python .\kujiale_upload.py `
  --app-key YOUR_APP_KEY `
  --app-secret YOUR_APP_SECRET

# 上传指定 ZIP 文件
python .\kujiale_upload.py `
  --app-key YOUR_APP_KEY `
  --app-secret YOUR_APP_SECRET `
  --zip "C:\path\to\model.zip"

# dry run：不发起网络调用，不需要凭据
python .\kujiale_upload.py --dry-run

# 自定义轮询参数
python .\kujiale_upload.py `
  --app-key YOUR_APP_KEY `
  --app-secret YOUR_APP_SECRET `
  --poll-interval 3 `
  --poll-timeout 120

Python 调用

直接导入并调用 run_skill(params)：

from kujiale_upload import run_skill

# 从环境变量 KUJIALE_APP_KEY / KUJIALE_APP_SECRET 读取凭据
summary = run_skill({})
print(summary)

# 或显式传入凭据
summary = run_skill({
    "app_key": "YOUR_APP_KEY",
    "app_secret": "YOUR_APP_SECRET",
})

# 指定 ZIP 和轮询参数
summary = run_skill({
    "app_key": "YOUR_APP_KEY",
    "app_secret": "YOUR_APP_SECRET",
    "zip_path": r"C:\path\to\model.zip",
    "poll_interval": 3.0,
    "poll_timeout": 120.0,
})

# dry run：不发起网络调用，不需要凭据
mock = run_skill({"dry_run": True})
print(mock)

返回摘要格式：

{
  "uploadTaskId": "...",
  "filePath": "...",
  "previewImg": "...",
  "brandGoodId": "..."
}

dry run 会额外返回：

{
  "uploadTaskId": "DRY_RUN_TASK_ID",
  "filePath": "dry_run/path/test_model_for_api_test.zip",
  "previewImg": "",
  "brandGoodId": "DRY_RUN_BRAND_GOOD_ID",
  "dry_run": true
}

成功输出示例

============================================================
Kujiale OpenAPI Full Flow
appKey=<your_key> zip=test_model_for_api_test.zip
============================================================
[INFO] Created test zip: test_model_for_api_test.zip
[Step 1] GET https://openapi.kujiale.com/v2/commodity/upload/sts file_name=test_model_for_api_test.zip
[Step 1] OK uploadTaskId=1234567890 filePath=kujiale-models/xxx/test_model_for_api_test.zip
[Step 2] OSS PUT endpoint=https://oss-cn-hangzhou.aliyuncs.com bucket=xxx key=... size=212
[Step 2] OK status=200 etag="..."
[Step 3] POST https://openapi.kujiale.com/v2/commodity/upload/create upload_task_id=1234567890
[Step 3] OK m=
[Step 4] Polling status for uploadTaskId=1234567890 (timeout=300.0s)
[Step 4] Attempt 1 status=1
[Step 4] Attempt 2 status=3
[Step 4] OK status=3 (zip parse success, ready to submit) previewImg=https://...
[Step 5] POST https://openapi.kujiale.com/v2/commodity/upload/submit name=test_model_for_api_test uploadTaskId=1234567890
[Step 5] OK brandGoodId=ABCxyz123

============================================================
ALL STEPS PASSED
{
  "uploadTaskId": "1234567890",
  "filePath": "kujiale-models/xxx/test_model_for_api_test.zip",
  "previewImg": "https://...",
  "brandGoodId": "ABCxyz123"
}
============================================================

解析状态码

步骤 4 的 status 含义：

| status | 含义 | |--------|------| | 0 | 生成中 | | 1 | ZIP 解析中 | | 2 | ZIP 解析失败，抛出 RuntimeError | | 3 | ZIP 解析成功，等待提交；继续步骤 5 | | 4 | 提交成功 | | 5 | 提交任务异常，抛出 RuntimeError |

常见失败

| 错误 | 原因 | 处理方式 | |------|------|----------| | 失败: 缺少必填凭据 | 未配置凭据 | 设置 KUJIALE_APP_KEY / KUJIALE_APP_SECRET，或通过 --app-key / --app-secret 传入 | | Step 1 错误: c=10001 | appKey/appSecret 无效 | 到酷家乐开放平台核对凭据 | | 失败: 未找到 ZIP 文件: ... | --zip 路径无效 | 传入存在的本地 .zip 文件 | | 失败: ZIP 文件必须以 .zip 结尾: ... | 文件类型不正确 | 先将模型打包为 .zip | | Step 4 轮询在 300s 后超时 | 解析耗时过长 | 增大 --poll-timeout | | Step 4 失败: status=2 | ZIP 格式不符合要求 | 检查 ZIP 中的模型文件结构 | | Step 1 请求失败: ... / Step 5 请求失败: ... | 网络、API 连通性或本地环境变量影响 | 检查防火墙、VPN、DNS、代理、CA 配置 | | 当前运行时或沙箱似乎阻止了外网访问 | 当前 agent/运行时限制外网访问 | 使用有外网权限的环境重跑 | | Step 2 OSS PUT status=... | OSS 连通性或 STS 问题 | 检查返回的 OSS region/bucket 和网络连通性 |

依赖

核心 CLI 依赖：

requests>=2.20.0
oss2>=2.14.0

安装 CLI 依赖：

python -m pip install requests oss2

发布检查

发布前确认：

[ ] 没有真实凭据进入任何 tracked 文件：
```
rg -n "app_key|app_secret|KUJIALE_APP_(KEY|SECRET)" -g "*.py" -g "*.json" -g "*.md" .
```
结果应只包含占位符或环境变量说明。
[ ] .env 未提交，只保留本地使用
[ ] .env、*.log、__pycache__/ 和生成的测试 ZIP 未提交
[ ] README / SKILL.md 明确要求设置 KUJIALE_APP_KEY / KUJIALE_APP_SECRET
[ ] python kujiale_upload.py --dry-run 在干净环境中可运行
[ ] 未配置凭据时，python kujiale_upload.py 返回稳定的 失败: 信息，而不是 traceback

安全说明

脚本不会打印 appSecret 或计算出的 sign
appSecret 只在内存中的 _sign() 函数里使用，不序列化到磁盘
步骤 1 返回的 STS token 是临时凭据，并绑定单次上传范围
如果怀疑 appKey / appSecret 已泄露，请立即在酷家乐开放平台轮换凭据

文件结构

kujiale-3d-model-upload/
└── cn/
    ├── config.json                 # OpenClaw 包配置
    ├── SKILL.md                    # Skill 说明
    └── kujiale_upload.py           # 主 CLI + run_skill 入口

本地生成并忽略：

.env
test_model_for_api_test.zip
__pycache__/
*.log