SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsvolcengine-troubleshooting

volcengine-troubleshooting

General & other

View repository

Updated 10-16 01:49

About this skill

VolcEngine Troubleshooting

This skill is intended for use in the user's local environment, and its goal is to help locate the causes of failures in VolcEngine products, OpenAPI, Python SDK,ve/tosutil CLI, and console operations without modifying cloud resources. The main entry retains only the necessary startup rules, scenario routing, and security boundaries; local tool checks and the complete domain index are placed in references/getting-started.md, quick checks for OpenAPI errors, signing, authentication, parameters, rate limiting, and ve/tosutil/Python SDK call chains are placed in references/openapi-quick-check.md, and specific product domain manuals are placed in references/domain-guides/。

First resolve SKILL_ROOT into an absolute directory containing this SKILL.md . All scripts and references are resolved from ${SKILL_ROOT} , without depending on the repository layout or the current working directory.

Before starting

  1. first read references/getting-started.md, and confirm local tools, environment variables, scenario dependencies, and domain routing.

  2. If the user permits running a local health check, run the general check:

    bash "${SKILL_ROOT}/scripts/common_check.sh"
  1. Prefer using ve sts GetCallerIdentity to verify the current identity chain. Report only whether it is available and the necessary identity summary; do not output SecretKey, SessionToken, the full AccessKeyId, full phone numbers, billing details, or object contents.
  2. Do not run ve configure, login/SSO initialization, dependency installation, config file writing, or cloud resource modification unless the user explicitly requests it and confirms the impact.
  3. If the ownership is uncertain, locate the domain according to the "scenario routing" in references/getting-started.md . For OpenAPI errors, signing/authentication failures, parameter validation, rate limiting, server-side errors, or OpenAPI call failures exposed by ve/tosutil/Python SDK, first read references/openapi-quick-check.md to narrow down the RequestId, Action, Region, error code, and minimal reproduction context.
  4. Open the corresponding references/domain-guides/<domain>/README.mdaccording to the routing below, then read query-cli-catalog.md, chapter README,api-coverage-matrix.md , and the script README according to the "read these first" section of the domain manual.

Scenario Routing

First extract from the user's error RequestId、ErrorCode、Action、Service、Region, resource ID, occurrence time, and invocation method. If missing, ask the minimum necessary questions first.

For domain determination, read references/getting-started.mdfirst. After determining the domain, enter the corresponding references/domain-guides/<domain>/README.md：

  • openapi-sdk-cli：OpenAPI、ve CLI, Python SDK, signing, API gateway.
  • account-permission: account, AK/SK, STS, IAM, roles, insufficient permissions.
  • billing-quota: billing, balance, arrears, orders, quotas, resource packages.
  • compute-container-network: ECS, VKE, CLB/ALB, VPC, NAT, EIP, routing, security groups.
  • storage-database: TOS, EBS, file storage, cloud backup, RDS, Redis, database connections.
  • domain-cdn-ingress: DNS, domains, certificates, CDN/DCDN, origin ingress.
  • communication-media：SMS、RTC、VOD、Live、CV/OCR、veImageX。
  • llm-ecosystem: Ark, Doubao, VikingDB, AgentKit, ArkClaw, Coze, machine learning platform.
  • security-kms-encryption: KMS, Secret, cloud HSM, WAF, DDoS, Cloud Firewall, Security Center.

If it still cannot be classified, after completing scripts/common_check.sh , look up ve SERVICE --help and ve SERVICE ACTION --help。

Non-blocking feedback

When existing evidence shows that the skill guidance is incorrect, CLI behavior is abnormal, a required capability is missing, or the user's goal is still not fully resolved, first continue the authorized troubleshooting, recovery, and main task. At a natural summary point, you may briefly invite the user to share this real scenario; clearly distinguish confirmed issues from causes not yet verified. Feedback does not replace fault handling, nor is it a prerequisite for continuing the task or ending troubleshooting.

  • For the same conversation, proactively invite at most once; cross-skill routing also shares this limit; after the user declines or ignores it, do not remind them again. Attach the entry point using a skippable declarative sentence, and do not stop to wait for a response.
  • The invitation uses only existing context, and does not install tools or skills, log in, search issues, collect additional logs, or retry cloud operations to reproduce the error for this purpose. If the main task can still continue, continue directly.
  • When the user proactively provides feedback, use the already available volcengine-feedback to organize the actual goal, observations, and expectations. If the skill is not installed or cannot be loaded in the current conversation, directly provide the feedback form, and you may also organize a sanitized draft in the current conversation; do not ask to install, log in, or restart the main conversation for feedback. Content confirmation and sanitization before public release are handled by the feedback process.

For example: "If you want to provide feedback on the capability gap found this time, you can use the feedback form to describe the usage scenario and improvement suggestions; feedback is optional and does not affect the continuation of the current task."

Core principles

  • Read-only first: By default, only execute Describe/List/Get/Query/Lookup/Check types of commands. Write operations such as Create/Update/Delete/Attach/Detach/Put/Set/Start/Stop/Run/Invoke/Pay/Renew/Refresh/Preload must first explain the impact and wait for user confirmation.
  • CLI first, SDK assisted: Only support ve and tosutil two types of CLI. Only when pagination aggregation, cross-resource topology, log merging, or CLI coverage is insufficient, suggest volc-sdk-python or volcengine-python-sdk scripts.
  • Credential security: Read AK/SK/Token only from environment variables; do not ask users to write credentials to files; do not print SecretKey, SessionToken, or the full AccessKeyId; when displaying AK, mask at least the middle part.
  • Minimal context: For each troubleshooting session, collect only the service, region, resource, and time window needed for the current issue. Do not batch-enumerate unrelated account resources.
  • Explain the criteria: For each check, explain why it is being checked, what is expected to be seen, what an anomaly means, and what evidence should be collected next.