volcengine-sdk-generator

name	volcengine-sdk-generator
description	Generate accurate Volcengine SDK examples by locating an API with the bundled local ranker, fetching its API Explorer swagger, and calling api/common/explorer/make-code with user-provided Params. Use when the user asks how to write Volcengine SDK code, generate SDK samples, or call a Volcengine API in Python, Go, Java, PHP, cURL, Node.js. Supports Chinese and English API names such as "角色扮演", "AssumeRole", or "STS AssumeRole". Also use for explicit SDK configuration questions about retry, timeout, AK/SK, STS, AssumeRole, temporary credentials, proxy, connection pooling, SSL, debug mode, request signing, response parsing, and error handling. If the user only needs API parameters, enum values, required fields, error codes, response schemas, pagination, or API comparisons, hand off to volcengine-api. If they need CLI-based operations, hand off to volcengine-cli.
license	MIT

Volcengine SDK Generator

Generate ordinary Volcengine API call examples by default. Keep the default output focused on the API call itself: authentication setup, request object/params, invocation, and printing the response. Do not add retry, proxy, connection pool, debug logging, or other advanced SDK configuration unless the user explicitly asks for those topics.

For advanced SDK configuration questions, use the language-specific files under references/. These reference files are self-contained; answer from them directly.

Topic	Reference
Go SDK configuration	references/sdk-integration-go.md
Python SDK configuration	references/sdk-integration-python.md
Java SDK configuration	references/sdk-integration-java.md
Node.js SDK configuration	references/sdk-integration-nodejs.md
PHP SDK configuration	references/sdk-integration-php.md

Core Rules

• API discovery uses scripts/rg_rank.py. After a concrete API is selected, call scripts/make_code.py in direct mode with --service-code, --api-version, and --action.
• rg_rank.py searches the bundled local ranker by default. It uses one rg recall pass when rg is installed and automatically falls back to pure Python scanning when rg is unavailable.
• If local ranking has zero results, rg_rank.py automatically falls back to the API Explorer search endpoint and marks those results as remote_search. Use --remote-search sparingly only when local results are clearly wrong or incomplete.
• Use the user's original request as the default --query; do not rewrite it into a guessed API name or SDK method. The ranker tolerates surrounding noise through keyword inference, alias matching, OR recall, and field-weighted scoring.
• Extract a shorter --query only when the user clearly self-corrects with words such as 等等, 不对, 重新来, 我改主意, 其实想要, 其实是想要, 应该是, or 改成; the extracted query must be a continuous substring from the user request, not a guessed API name.
• When multiple resources or services appear without a clear self-correction, run rg_rank.py once with the original request. If top candidates are across different services and top1 does not lead top2 by at least 30%, list concise candidates and ask the user to choose.
• Use --resource, --intent, --service, --action, and --extra only as high-confidence overrides or supplements when local ranking is noisy, the product alias is rare, or the user provides an explicit machine term. Values must come from the user wording or a trusted alias; do not invent terms. Manually provided --resource, --intent, and --service replace built-in inference for that group, so partial values can reduce recall. Include all known Chinese, English, and camelCase variants together when using them.
• Pure-generic queries such as api, sdk, or demo skip local matching by themselves and either trigger remote search or return empty_query when remote fallback is disabled. Refine the query with a concrete resource or action word.
• ServiceCode is case-sensitive. Preserve the exact service_code value from the selected API record when calling make_code.py; for example, Kafka is not kafka.
• When local ranking returns the same service_code + action across multiple API versions and the user did not specify a version, prefer the packaged API Explorer default version.
• Fetch api-swagger only after a concrete API is selected.
• The api-swagger fetch may include both Version and APIVersion because that endpoint expects them; the make-code payload must not include Version.
• Call make-code with ApiAction, ServiceCode, APIVersion, Region, and Params.
• Do not send Version to make-code.
• Params must come from the user. Do not auto-fill from swagger demos.
• Swagger is used for API metadata, required parameter hints, and lightweight validation. Do not serialize query arrays, form arrays, or .N parameters for make-code; pass the user’s JSON object as Params.
• If the user omits required top-level parameters, mock only those top-level required parameters and clearly mark them as mock values. Do not mock optional parameters. If a required top-level parameter is an object or array, recursively fill only required child fields/items.
• Mock values must be derived from the fetched swagger first: prefer example, then examples, then default, then enum, then type/constraint-aware fallback. If a swagger example is masked, such as **** or XX, skip it and use a valid fallback value.
• Mock comments must be in Chinese by default and placed near the mocked assignment line when the target language supports line comments; do not add a duplicate mock banner at the top of the returned code.
• Returned SDK code must print the API response value. The script post-processes fixed make-code templates for Python, Go, Java, and PHP to assign the response and print it.
• Return the code generated by scripts/make_code.py as the primary SDK example. Do not rewrite SDK request construction, authentication setup, or response handling into a custom application unless the user explicitly asks for that. If optional formatting or convenience logic is added, keep the generated active response print, such as print(resp), fmt.Println(resp), System.out.println(resp), print_r($response), or console.log(response).
• If language is not specified, return all languages from DemoSdk.
• SDK install/dependency info is a separate, on-demand capability. Only when the user explicitly asks how to install the SDK or which package/version to use (keywords such as 依赖, 安装, install, 版本, 包, maven, go get, pip, composer, npm), run scripts/sdk_info.py with --service-code and --api-version (reuse the selected API's values; add --language to filter to one of go/python/java/php/nodejs). It returns the live install command (RunCommand) plus package and version per language. Do NOT run it during normal code generation.
• If the API match is ambiguous, show concise candidates and ask the user to choose one. Do not add follow-up execution boilerplate such as saying that you will fetch swagger, mock required params, and call make-code after the user chooses.

Workflow

1. Parse the user request:

   • API hint: action, Chinese name, service code, or natural-language description.
   • Language: Python, Go, Java, PHP, cURL, Node.js, or unspecified.
   • Params: JSON object supplied by the user.
   • Region: user value or default cn-beijing.

2. Locate or validate the API once for every request. If the user already provides service_code, api_version, and action, use those values as strict filters and verify they exist locally before direct mode. For natural-language requests, call scripts/rg_rank.py with --query first. Use the full original request unless a clear self-correction keyword points to a later target; in that case use the final target substring. Avoid optional term flags on the first pass. Manually provided --resource, --intent, and --service replace built-in inference for that group rather than merging with it, so a partial flag value can reduce recall. If you must use them, include all known variants together. If rg_rank.py returns remote_search results because the local ranker had zero hits, treat them as candidates and still verify the selected service_code, api_version, and action before calling direct mode. Avoid --remote-search unless the local candidates are obviously wrong or incomplete.

3. After selecting service_code, api_version, and action, call scripts/make_code.py in direct API mode with --service-code, --api-version, and --action. If top-level required params are missing, the script fills only those required top-level params with swagger-derived mock values and annotates the returned code in Chinese. Ask for clarification only when API selection is genuinely ambiguous after local ranking; in that clarification, only list candidates and ask the user to choose.

4. Once params are available, call make-code through the script and return the official code. Do not transform the generated sample into a hand-written utility; any custom formatting must be secondary and must preserve the active response print.

Commands

Rank local candidates:

python3 scripts/rg_rank.py \
  --query '角色扮演' \
  --limit 10 \
  --format text

Use optional term flags only for high-confidence overrides or supplements, and keep --query as the user's wording:

python3 scripts/rg_rank.py \
  --query '标准型加速器替换公网带宽包' \
  --service 'ga' \
  --resource '公网带宽包|PublicBandwidthPackage' \
  --intent '替换|Replace' \
  --limit 10 \
  --format text

Direct API mode:

In TRN examples, <account-id> is the Volcengine account ID segment, such as a masked 2134xxxyyy.

python3 scripts/make_code.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --action AssumeRole \
  --language python \
  --params-json '{"DurationSeconds":3600,"RoleSessionName":"demo","RoleTrn":"trn:iam::<account-id>:role/demo"}'

Use --refresh-swagger when API Explorer metadata has just changed or generated code looks stale:

python3 scripts/make_code.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --action AssumeRole \
  --refresh-swagger \
  --params-json '{}'

Fetch SDK install/dependency info on demand (only when the user asks about install, package, or version):

python3 scripts/sdk_info.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --language go