volcengine VolcEngine Troubleshooting
本 skill 面向用户本地环境使用，目标是在不修改云上资源的前提下，帮助定位 VolcEngine 产品、OpenAPI、Python SDK、ve/tosutil CLI 和控制台操作失败的原因。主入口只保留必要的启动规则、场景路由和安全边界；本地工具检查与完整领域索引放在 references/getting-started.md，OpenAPI 报错、签名、鉴权、参数、限流以及 ve/tosutil/Python SDK 调用链路的快速检查放在 references/openapi-quick-check.md，具体产品域手册放在 references/domain-guides/。
先把 SKILL_ROOT 解析为包含本 SKILL.md 的绝对目录。所有脚本和 reference 都从
${SKILL_ROOT} 解析，不依赖仓库布局或当前工作目录。
开始前
先读取
references/getting-started.md，确认本地工具、环境变量、场景依赖和领域路由。如用户允许执行本地体检，运行通用检查：
bash "${SKILL_ROOT}/scripts/common_check.sh"优先用
ve sts GetCallerIdentity验证当前身份链路，只报告是否可用和必要的身份摘要，不输出 SecretKey、SessionToken、完整 AccessKeyId、完整手机号、账单明细或对象内容。不要运行
ve configure、登录/SSO 初始化、安装依赖、写入配置文件或修改云资源，除非用户明确要求并确认影响。若不确定归属，按
references/getting-started.md中的“场景路由”定位领域；遇到 OpenAPI 报错、签名/鉴权失败、参数校验、限流、服务端错误，或由ve/tosutil/Python SDK 暴露出的 OpenAPI 调用失败，先读references/openapi-quick-check.md收敛 RequestId、Action、Region、错误码和最小复现上下文。根据下方路由打开对应
references/domain-guides/<domain>/README.md，再按领域手册的“先读这些”读取query-cli-catalog.md、章节 README、api-coverage-matrix.md和脚本 README。
场景路由
先从用户报错中提取 RequestId、ErrorCode、Action、Service、Region、资源 ID、发生时间和调用方式。如果缺失，先问最少必要问题。
领域判断优先读 references/getting-started.md。确定领域后，再进入对应 references/domain-guides/<domain>/README.md：
openapi-sdk-cli：OpenAPI、veCLI、Python SDK、签名、API 网关。account-permission：账号、AK/SK、STS、IAM、角色、权限不足。billing-quota：账单、余额、欠费、订单、配额、资源包。compute-container-network：ECS、VKE、CLB/ALB、VPC、NAT、EIP、路由、安全组。storage-database：TOS、EBS、文件存储、云备份、RDS、Redis、数据库连接。domain-cdn-ingress：DNS、域名、证书、CDN/DCDN、入口回源。communication-media：SMS、RTC、VOD、Live、CV/OCR、veImageX。llm-ecosystem：Ark、豆包、VikingDB、AgentKit、ArkClaw、Coze、机器学习平台。security-kms-encryption：KMS、Secret、云加密机、WAF、DDoS、Cloud Firewall、安全中心。
仍无法分类时，完成 scripts/common_check.sh 后，按报错中的服务名查 ve SERVICE --help 和 ve SERVICE ACTION --help。
核心原则
- 只读优先：默认只执行 Describe/List/Get/Query/Lookup/Check 类命令。Create/Update/Delete/Attach/Detach/Put/Set/Start/Stop/Run/Invoke/Pay/Renew/Refresh/Preload 等写操作必须先解释影响并等待用户确认。
- CLI 优先，SDK 辅助：只支持
ve和tosutil两类 CLI。只有分页聚合、跨资源拓扑、日志归并或 CLI 未覆盖时，才建议volc-sdk-python或volcengine-python-sdk脚本。 - 凭证安全：只从环境变量读取 AK/SK/Token；不要要求用户把凭证写入文件；不要打印 SecretKey、SessionToken 或完整 AccessKeyId；展示 AK 时至少遮蔽中间部分。
- 最小上下文：每次排障只收集当前问题所需的服务、地域、资源和时间窗口。不要批量枚举无关账号资源。
- 解释判据：每个检查都说明为什么查、期望看到什么、异常意味着什么，以及下一步该收集哪一项证据。