kujiale-3d-model-upload（酷家乐 3d 模型上传）

What is this skill

This skill wraps kujiale_upload.py — a self-contained Python script that validates the complete Kujiale OpenAPI 3D model upload pipeline in exactly 5 steps. The script uses Python requests / oss2 only, and explicitly disables environment-derived proxy / certificate overrides (trust_env=False) because those settings can cause TLS handshake failures in some Windows environments:

Authentication: md5(appSecret + appKey + timestamp_ms)

API Key: Apply at Manycore OpenAPI Console

Quick Start

# 1. Install dependencies
pip install requests oss2

# 2. Copy the example env file and fill in YOUR credentials
cp .env.example .env
# Windows PowerShell:
# Copy-Item .env.example .env

# 3. Set env vars for the current shell session
export KUJIALE_APP_KEY=your_app_key_here
export KUJIALE_APP_SECRET=your_app_secret_here
# Windows PowerShell:
# $env:KUJIALE_APP_KEY="your_app_key_here"
# $env:KUJIALE_APP_SECRET="your_app_secret_here"

# 4. Run a safe local smoke test first
python kujiale_upload.py --dry-run

# 5. Run the real flow
python kujiale_upload.py

Prerequisites and Scope

This skill is intended for users who already have:

• A valid Kujiale OpenAPI appKey / appSecret — Apply at Manycore OpenAPI Console
• Permission to call the commodity model upload APIs in their Kujiale tenant
• A .zip package that matches Kujiale's 3D model import requirements
• Network access to openapi.kujiale.com and the OSS endpoint returned by Step 1

This repository does not include:

• Any built-in credentials
• Any guarantee that the generated placeholder ZIP is a production-valid 3D model package
• Any tenant-specific category mapping beyond the sample defaults in kujiale_upload.py

The auto-generated ZIP is only for API connectivity and workflow smoke testing.

Configuration

Required credentials

You must supply your own Kujiale OpenAPI credentials. There are no built-in defaults.

Priority: explicit CLI/dict value > environment variable

If credentials are missing, you will see:

FAILED: Missing required credentials: app_key (env: KUJIALE_APP_KEY), app_secret (env: KUJIALE_APP_SECRET).
Set environment variables or pass via --app-key / --app-secret.
See .env.example for reference.

All configuration parameters

Transport behavior

• Default path: API calls use requests; OSS upload uses oss2
• The script creates dedicated sessions with trust_env=False
• This prevents inherited proxy / CA bundle environment settings from breaking TLS handshakes
• If you run this skill inside an agent or IDE that sandboxes outbound network access, the real upload path requires unrestricted network access to openapi.kujiale.com and the returned OSS endpoint. The script now reports this case explicitly and tells you to rerun with network permissions enabled.

Built-in Step 5 defaults

kujiale_upload.py currently submits with these sample defaults:

• location = 1
• brandCats = ["3FO4K6E984C7"]

These values are not universal. They appear to be business defaults from the original implementation and may be wrong for another tenant or another catalog tree. If your account requires different category metadata, update the script before using the real submit step.

Usage

CLI

# Install dependencies
pip install requests oss2

# Run with credentials from environment variables (recommended)
python kujiale_upload.py

# Run with explicit credentials
python kujiale_upload.py \
  --app-key YOUR_APP_KEY \
  --app-secret YOUR_APP_SECRET

# Run with a specific ZIP file
python kujiale_upload.py \
  --app-key YOUR_APP_KEY \
  --app-secret YOUR_APP_SECRET \
  --zip /path/to/your/model.zip

# Dry run — no network calls, no credentials needed
python kujiale_upload.py --dry-run

# Custom polling parameters
python kujiale_upload.py \
  --app-key YOUR_APP_KEY \
  --app-secret YOUR_APP_SECRET \
  --poll-interval 3 \
  --poll-timeout 120

Programmatic (Python)

Import and call run_skill(params) directly:

from kujiale_upload import run_skill

# Credentials from environment variables KUJIALE_APP_KEY / KUJIALE_APP_SECRET
summary = run_skill({})
print(summary)
# {
#   "uploadTaskId": "...",
#   "filePath": "...",
#   "previewImg": "...",
#   "brandGoodId": "..."
# }

# Or pass credentials explicitly
summary = run_skill({
  "app_key": "YOUR_APP_KEY",
  "app_secret": "YOUR_APP_SECRET",
})

# With a specific zip and overridden polling
summary = run_skill({
  "app_key": "YOUR_APP_KEY",
  "app_secret": "YOUR_APP_SECRET",
  "zip_path": "/path/to/model.zip",
  "poll_interval": 3.0,
  "poll_timeout": 120.0,
})

# Dry run — no network calls, no credentials needed
mock = run_skill({"dry_run": True})
print(mock)
# {
#   "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
# }

Test / Run

What to expect on a successful run

============================================================
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 successFlag=True

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

Parse status codes (Step 4)

Common failure modes

Dependencies

requests>=2.20.0
oss2>=2.14.0

Install:

pip install requests oss2

Publishing Checklist

Before publishing externally, verify:

• [ ] No real credentials in any tracked file — run:

  grep -rn "app_key\|app_secret" . --include="*.py" --include="*.json" --include="*.md" | grep -v ".env.example" | grep -v "YOUR_APP"

Confirm only placeholder / env-var references remain.

• [ ] .env is not committed (keep it local only)
• [ ] .env.example is committed with placeholder values only
• [ ] Add .env to .gitignore in the repo that vendors this skill
• [ ] README / SKILL.md directs users to set KUJIALE_APP_KEY / KUJIALE_APP_SECRET
• [ ] python kujiale_upload.py --dry-run succeeds on a clean machine
• [ ] python kujiale_upload.py without credentials fails with a single-line FAILED: message, not a traceback

Security Notes

• Credentials are never logged. The script logs appKey (for traceability) but never logs appSecret or the computed sign.
• appSecret flows only through the in-memory _sign() function and is never serialised to disk or printed.
• STS tokens returned by Step 1 are temporary (short TTL) and scoped to a single upload — no long-lived secrets are stored.
• If you suspect your appKey/appSecret have been exposed, rotate them immediately on the Manycore OpenAPI Console.

File Tree

kujiale-3D-model-upload/
├── SKILL.md           # This file
├── .env.example       # Credential template — copy to .env and fill in your keys
└── kujiale_upload.py  # Main script (CLI + run_skill entrypoint)