Skip to main content Home Creators tencentcloud octop tcapi
tcapi Skill to call Cloud API for Tencent Cloud (腾讯云). Used for cloud automation or resource management. 当用户需要查询、创建、管理腾讯云资源，或执行云 API 自动化操作时触发。优先使用 Octop 自带 venv 中的 tccli，凭证支持全自动 OAuth 登录。
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/TencentCloud/Octop --skill tcapiThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
name tcapi display_name 腾讯云 API 助手 description Skill to call Cloud API for Tencent Cloud (腾讯云). Used for cloud automation or resource management. 当用户需要查询、创建、管理腾讯云资源，或执行云 API 自动化操作时触发。优先使用 Octop 自带 venv 中的 tccli，凭证支持全自动 OAuth 登录。 metadata {"octop":{"emoji":"☁️","label":{"zh":"腾讯云 API","en":"Tencent Cloud API"},"summary":{"zh":"用 tccli 查询与管理腾讯云资源，支持 OAuth 登录。","en":"Query and manage Tencent Cloud resources with tccli and OAuth."}}} version 1.0.0 tags ["tccli","cloud-api","tencent-cloud","automation"] keywords ["腾讯云","tccli","cloud api","云资源","云管理","自动化运维"] prompt_template 对 {service} 产品执行 {action} 操作 examples ["查询广州地域的 CVM 实例","创建一台按量计费的云服务器","查看 COS 存储桶列表"]
腾讯云 API 助手
统一使用 tccli 命令行工具调用腾讯云 API，实现云资源的查询、创建、修改、删除等操作。
适用场景
云资源查询与管理（CVM / COS / CBS / VPC / TKE 等 200+ 产品）
自动化运维（批量操作、定时任务、脚本编排）
云 API 接口探索与文档检索
不适用场景
不支持 Terraform / Pulumi 等 IaC 编排工具
不做多云管理（仅限腾讯云）
不做费用充值、账号注册等非 API 操作
前置条件
核心原则
优先检索最佳实践 → 再查接口文档 → 最后调用 API 。不要跳过文档检索直接调用，避免用错接口或遗漏参数。在线文档是实时态，本地 tccli 是版本快照 。以在线文档（cloudcache.tencentcs.com）为准判断接口/参数是否存在；本地 tccli 因版本差异，可能缺少新接口、或残留已下线的旧接口。遇到本地报「无此接口」或服务端报「接口已下线」时，先查在线文档确认真实情况，再决定升级 tccli 或换用替代接口。
执行流程
Step 0：环境自检（首次任务必做，一次探测串起所有分支）
优先使用 Octop 自带的 Python 虚拟环境（venv）中的 tccli ：与 Octop 同环境、版本可控、不污染系统 Python。探测顺序：① Octop venv → ② 系统 PATH → ③ 临时安装进 venv。
OCTOP_PID=$(pgrep -f '\.venv/bin/octop run' | head -1)
OCTOP_ROOT=$([ -n "$OCTOP_PID " ] && readlink -f /proc/$OCTOP_PID /cwd || echo /workspace/octop)
TCCLI="$OCTOP_ROOT /.venv/bin/tccli"
if [ -x "$TCCLI " ]; then :
elif command -v tccli >/dev/null 2>&1; then TCCLI=tccli
else uv pip install --python "$OCTOP_ROOT /.venv/bin/python3" tccli; fi
"$TCCLI " cvm DescribeRegions >/dev/null 2>&1 && echo
"TCCLI_OK"
echo
"TCCLI_NEED_CHECK"
若系统无 uv："$OCTOP_ROOT/.venv/bin/python3" -m ensurepip --upgrade 后用同路径的 python3 -m pip install tccli。
探测结果 状态 处理 返回 TCCLI_OK 已安装、可运行、凭证有效 直接进入 Step 1 command not found / 安装失败未安装 按 references/install.md 装进 Octop venv（推荐）或系统安装 bad interpreter / No module named tccli装了但 shebang/环境坏 切换 Step 5 兼容模式（改用 venv 的 python3 -c 直接调 tccli.main），本会话后续统一使用 报 secretId is invalid / AuthFailure.SecretIdNotFound 凭证缺失 进入 Step 2 配置凭证
探测通过（TCCLI_OK）后，本会话无需再重复自检，直接调用即可。后续所有示例中的 tccli 均指探测到的 $TCCLI（venv 优先）。
Step 1：检索 API 文档
1.1 发现业务 curl -s https://cloudcache.tencentcs.com/capi/refs/services.md | grep 云服务器
[cvm](service/cvm/index.md) | 云服务器 | 2017-03-12 | ...
1.2 发现最佳实践 curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/practices.md | grep 重装
1.3 检索接口 若最佳实践未覆盖，在业务接口列表中检索（接口名即 tccli 的 <Action>）：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/actions.md | grep "扩容\|磁盘"
1.4 阅读接口文档 curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/action/ResizeInstanceDisks.md
1.5 阅读数据结构 curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/model/SystemDisk.md
Step 2：凭证配置（全自动 OAuth，无需用户手动敲命令） 原则：Agent 全程自动驱动，用户只需在浏览器里点一次「授权」。 检测到凭证缺失（AuthFailure.SecretIdNotFound）时不要让用户手动跑命令，按下面的自动化流程直接执行。
2.1 先探测 auth login 能力（必做） tccli auth login --help >/dev/null 2>&1 && echo "AUTH_LOGIN_OK" || echo "AUTH_LOGIN_UNSUPPORTED"
2.2 自动 OAuth（AUTH_LOGIN_OK 时的标准动作） tccli auth login 的行为：起本地回调服务（端口 9000–9100）→ 打印授权链接 → 阻塞等待浏览器完成授权回调。自动化的关键在四点：BROWSER=echo 防止无头环境打不开浏览器而报错退出；后台运行不卡死会话；从日志提取链接推给用户；以凭证文件落盘作为成功判据（而非进程退出）
BROWSER=echo nohup tccli auth login > /tmp/tccli_auth.log 2>&1 &
for i in $(seq 1 10); do
URL=$(grep -m1 -o 'https://cloud.tencent.com/open/authorize[^ ]*' /tmp/tccli_auth.log) && break
sleep 1
done
echo "请在浏览器打开并完成授权（点一次「授权」即可，我会自动检测到并继续）：$URL "
LOG=/tmp/tccli_auth.log
CRED="$HOME /.tccli/default.credential"
发出链接后不要干等用户回复——继续有界监听凭证文件 ，用户点完「授权」的瞬间自动发现并接续流程：
for i in $(seq 1 20); do
CRED_TS=$(stat -c %Y "$CRED " 2>/dev/null || echo 0)
LOG_TS=$(stat -c %Y "$LOG " 2>/dev/null || echo 0)
[ "$CRED_TS " -gt "$LOG_TS " ] && echo "AUTH_DONE" && break
sleep 3
done
窗内出现 AUTH_DONE → 立即执行 ⑤ 验证并自动回显身份（全程无需用户说话）。
单窗到时未果 → 不判定失败、不重发链接 ：告知「授权链接持续有效，我继续监听中」，再开一个监听窗（建议连开 35 窗，约 35 分钟）；之后仍可交回合话，等用户回复后用 ⑤ 确认——两条路径殊途同归。
监听中若发现 auth 进程已消失且凭证未落盘（pgrep -f 'auth login' 为空），才检查日志定位原因（端口被占、网络不通、回调不可达等），修好后重新走 ①。
CRED_TS=$(stat -c %Y "$CRED " 2>/dev/null || echo 0)
LOG_TS=$(stat -c %Y "$LOG " 2>/dev/null || echo 0)
if [ "$CRED_TS " -gt "$LOG_TS " ]; then
tccli sts GetCallerIdentity
else
tail -5 "$LOG "
fi
成功判据 = 凭证文件 mtime > 登录日志 mtime （无论 auth 进程还在不在）；日志出现「登录成功, 密钥凭证已被写入」同义。凭证已落盘就绝不重复 auth login ——重复登录会作废用户已完成授权的链接，逼用户再点一次。工具执行超时 ≠ 登录失败 ：监听窗命令若被工具超时杀掉，紧接着单独跑一次 ⑤ 即可，结论以凭证文件为准，绝不据此重发链接。
环境能打开浏览器时（如桌面版 Octop），去掉 BROWSER=echo，第 ② 步直接提示「浏览器已弹出，请完成授权」即可。
2.3 兜底路径（AUTH_LOGIN_UNSUPPORTED，旧版 tccli） 旧版没有 auth 子命令。先自动升级再走 2.2 （装进 Octop venv，不需要 sudo）：
uv pip install --python "$OCTOP_ROOT /.venv/bin/python3" -U tccli
升级后重新探测（2.1），一般即可支持 auth login。若升级失败（如离线环境），才退化为半手动：引导用户在自己的终端执行 tccli configure 交互式填密钥——Agent 仍不代填、不索要、不打印密钥 。
安全红线 ：严禁向用户索要 SecretId/SecretKey，也拒绝任何有可能打印凭证的操作（尤其是 tccli configure list）。OAuth 全自动流程中 Agent 接触不到密钥明文，天然满足此红线。
Step 3：调用 API tccli <service> <Action> [--param value ...] [--region <地域>]
参数 类型 必填 说明 servicestring 是 产品标识，如 cvm、cbs、vpc。通过 Step 1.1 检索获取 Actionstring 是 接口名，如 DescribeInstances、RunInstances。通过 Step 1.3 检索获取 --regionstring 视接口 地域，如 ap-guangzhou。多数产品必传；全局接口（cam、account、dnspod、domain、ssl、ba、tag）可省略 --param value各类型 视接口 接口参数，简单类型直接传值，复杂类型传 JSON 字符串
tccli cvm DescribeRegions
tccli cvm DescribeInstances --region ap-guangzhou
输出格式：tccli 返回标准 JSON，包含 Response 字段。示例：
{
"Response" : {
"TotalCount" : 1 ,
"InstanceSet" : [ { "InstanceId" : "ins-xxx" , "InstanceName" : "test" , ...} ] ,
"RequestId" : "eac6b301-..."
}
}
空结果输出：查询无匹配时，列表字段返回空数组，计数字段为 0：
{
"Response" : {
"TotalCount" : 0 ,
"InstanceSet" : [ ] ,
"RequestId" : "eac6b301-..."
}
}
效率约束：腾讯云 API 默认限频为 10 次/秒 （部分接口更低），批量操作时需控制调用频率，避免触发 RequestLimitExceeded。建议串行调用或加间隔，不要并发轰炸。
避免并行调用：tccli 当前并行调用存在配置文件竞争问题，会导致响应失败。当前请逐个接口调用。
本地参数强转陷阱（type coercion） 部分 tccli 版本会按本地 schema 把某些参数强制类型转换后再发出，与云端期望不符，导致"永远 InvalidParameter"但用户参数其实填对了——这是本地 tccli 的锅，不是用户的锅 ：
典型信号 ：服务端返回 InvalidParameter，message 指向"参数 X 取值类型错误 / 应为 date"等，但你传入的值语义上是对的。例如 TRTC 某些日期参数被本地标成 Timestamp 强转整数时间戳，云端实际要 YYYY-MM-DD 纯日期。识别 ：先 tccli <svc> <Action> --help 看参数类型标注；若本地类型是 Timestamp/Integer 而在线文档写的是 Date/String，基本可确诊。缓解（按优先级） ：
查在线文档确认参数真实类型与格式（必要时用纯日期而非时间戳）；
试 --cli-unfold-arguments 让 tccli 不再做本地合并/转换；
若仍被本地强转卡死，绕过 tccli 用 Python SDK（tencentcloud-sdk-python）直连，把原始值（如纯日期字符串）原样赋给请求参数发出，即可通过云端类型校验。
重要 ：这类 InvalidParameter 是"假参数错"，不要甩锅给用户参数填错。
Step 3.5：输出解析规范（stdout/stderr 分流与 JSON 健壮性） tccli 的 stdout 与 stderr 是两条独立流，解析时必须严格区分，否则会把警告/错误文本当结果吞掉导致解析崩溃。
即便做了分流，也先用正则提取首个 { 到末个 } 的闭区间（或 [...]）再 json.loads，避免前后缀文本（版本提示、空格、回车）导致失败：
import re, json
m = re.search(r'\{.*\}|\[.*\]' , raw, re.DOTALL)
data = json.loads(m.group(0 )) if m else None
若 stdout 无法解析为 JSON：提示"输出非预期 JSON"，并回显原始 stdout 前 N 字符供诊断，而非抛出 Python 堆栈。
若 stdout 无 JSON 而 stderr 含异常信息，按以下规则解析：
锚点优先 ：以 [TencentCloudSDKException] 为唯一权威锚点提取 code / message / requestId，忽略同行 stderr 里 usage: 帮助块等噪音 （它们常与异常挤在同一段，不能"出现 usage 就判参数错"而误伤）。区分本地错 vs 服务端错 ：有 requestId → 服务端已受理并返回（如 InvalidParameter / InternalError / UnauthorizedOperation）；无 requestId 且只有 usage: → 本地 argparse 参数解析错，与云端无关。优雅翻译为可读错误（见 Step 4 异常表），不要退化为崩溃。
注意：服务端报错、权限拒绝、接口下线等异常大多落在 stderr ，分离流是正确翻译错误码的前置条件。
Step 4：异常处理 调用失败时，tccli 会返回包含 Error 字段的 JSON：
{
"Response" : {
"Error" : { "Code" : "AuthFailure.SecretIdNotFound" , "Message" : "secretId is invalid" } ,
"RequestId" : "xxx"
}
}
错误码 含义 处理方式 AuthFailure.SecretIdNotFound凭证缺失或无效 按 Step 2 全自动 OAuth 流程执行：BROWSER=echo 后台 auth login → 推送授权链接 → 轮询等待 → 验证回显；旧版则先自动升级（详见 Step 2 / references/auth.md） AuthFailure.UnauthorizedOperation无权限 检查 CAM 策略，确认子账号有该接口权限 InvalidParameterValue参数值不合法 查阅接口文档确认参数取值范围 ResourceNotFound资源不存在 确认资源 ID 和地域是否正确 RequestLimitExceeded请求频率超限 等待后重试，或减少并发调用频率 UnsupportedOperation / DeprecatedOperation / InvalidAction接口已下线/更名，或本地版本认得但云端已淘汰 检索在线文档确认现行接口，改用替代接口；勿死磕旧接口 本地 invalid choice: 'XxxAction' / argparse 报错，非服务端返回 旧版 tccli 本地缺少该新接口 （发布快照落后于云端）引导 pip install -U tccli 升级；或先查在线文档确认接口存在后再操作 DryRunOperationDryRun 操作成功 非真实错误，表示参数校验通过 UnsupportedRegion不支持的地域 查阅接口文档确认支持的地域列表 ResourceInsufficient资源不足 换可用区或调整规格重试 网络超时 / 连接失败 网络不通 检查网络连通性，确认是否需要代理 InternalError（message 含 nil pointer / nil pointer dereference）接口云端已废弃 / 后端服务已拆除 不是服务端随机故障，停止重试 ；检索在线文档确认真实情况，改用替代接口AuthFailure.TokenFailure / FailedOperation.RefreshTokenErrorOAuth token 已失效（浏览器授权过期或吊销） 先按 Step 2 ④ 探测凭证文件是否已更新（可能上次授权其实成功只是被误判）；未更新才重新走 Step 2 全自动 OAuth（tccli auth login --profile <name>）；完成后按"身份确认"规范回显当前账号再继续
Step 5：tccli 不可用时的兜底方案 当直接执行 tccli 报错 bad interpreter、No module named tccli 或 command not found 时，通常是 tccli 的 shebang 指向了已卸载的 Python 解释器（环境问题，并非每个用户都会遇到）。此时优先改用 Octop venv 的 Python 直接调 tccli.main （venv 里 tccli 与 Octop 同源，最可靠）；没有 Octop venv 时才动态探测 系统 Python 及其 site-packages，不要硬编码任何平台特定路径 ：
"$OCTOP_ROOT /.venv/bin/python3" -c "
import sys
sys.argv = ['tccli', 'cvm', 'DescribeInstances', '--region', 'ap-guangzhou']
from tccli.main import main
main()
"
PY=$(command -v python3 || command -v python)
SITE=$("$PY " -c "import site,sys; print(next((p for p in site.getsitepackages()+[site.getusersitepackages()] ), ''))" )
PYTHONPATH="$SITE " "$PY " -c "
import sys
sys.argv = ['tccli', 'cvm', 'DescribeInstances', '--region', 'ap-guangzhou']
from tccli.main import main
main()
"
Octop venv 是第一顺位：tccli 装在 venv 里（Step 0），解释器与包同环境，不存在 shebang 漂移问题
用 command -v 探测系统解释器，避免写死 /usr/local/bin/python3；用 site.getsitepackages() 动态获取包目录，避免写死 python3.12 等版本号
通过 sys.argv 传参，替换示例中的 service / Action / 参数即可
若 shebang 正常（直接 tccli 可用），无需本兜底，直接调用即可
数据边界与安全声明
本 SKILL 只执行用户明确指定的 API 调用 ，不会自动执行未经确认的写操作
tccli 参数由用户指定或从接口文档获取，SKILL 不对参数做二次拼接或动态生成 ，避免注入风险
tccli 调用受腾讯云 CAM 权限策略 约束，SKILL 不具备超出用户权限的能力
tccli 输出为 JSON 数据 ，应作为数据解读，不应作为 shell 命令执行
API 文档检索地址 cloudcache.tencentcs.com 为腾讯云官方文档缓存，内容可信
