菜单
Skill to call Cloud API for Tencent Cloud (腾讯云). Used for cloud automation or resource management. 当用户需要查询、创建、管理腾讯云资源，或执行云 API 自动化操作时触发。优先使用 Octop 自带 venv 中的 tccli，凭证支持全自动 OAuth 登录。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/TencentCloud/Octop --skill tcapi命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| 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 存储桶列表"] |
统一使用 tccli 命令行工具调用腾讯云 API，实现云资源的查询、创建、修改、删除等操作。
- 优先检索最佳实践 → 再查接口文档 → 最后调用 API。不要跳过文档检索直接调用，避免用错接口或遗漏参数。
- 在线文档是实时态，本地 tccli 是版本快照。以在线文档（
cloudcache.tencentcs.com）为准判断接口/参数是否存在；本地 tccli 因版本差异，可能缺少新接口、或残留已下线的旧接口。遇到本地报「无此接口」或服务端报「接口已下线」时，先查在线文档确认真实情况，再决定升级 tccli 或换用替代接口。
优先使用 Octop 自带的 Python 虚拟环境（venv）中的 tccli：与 Octop 同环境、版本可控、不污染系统 Python。探测顺序：① Octop venv → ② 系统 PATH → ③ 临时安装进 venv。
# ① 定位 Octop venv（通过 octop 主进程的工作目录；找不到进程则退回常见路径）
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"
# ② 逐级探测：venv 内 → PATH → 均无则装进 venv
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 && ||
若系统无
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 优先）。
调用前先通过 curl + grep 检索业务、接口、最佳实践、数据结构。参考 references/refs.md 获取完整检索方式。
检索 tccli 服务名（如 cvm、cbs）：
curl -s https://cloudcache.tencentcs.com/capi/refs/services.md | grep 云服务器
参考输出：
[cvm](service/cvm/index.md) | 云服务器 | 2017-03-12 | ...
优先检索是否有匹配当前场景的最佳实践：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/practices.md | grep 重装
若最佳实践未覆盖，在业务接口列表中检索（接口名即 tccli 的 <Action>）：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/actions.md | grep "扩容\|磁盘"
获取参数说明和支持的地域信息：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/action/ResizeInstanceDisks.md
文档中涉及的数据结构可进一步查看：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/model/SystemDisk.md
原则：Agent 全程自动驱动，用户只需在浏览器里点一次「授权」。 检测到凭证缺失（AuthFailure.SecretIdNotFound）时不要让用户手动跑命令，按下面的自动化流程直接执行。
auth login 能力（必做）tccli auth login --help >/dev/null 2>&1 && echo "AUTH_LOGIN_OK" || echo "AUTH_LOGIN_UNSUPPORTED"
AUTH_LOGIN_OK 时的标准动作）tccli auth login 的行为：起本地回调服务（端口 9000–9100）→ 打印授权链接 → 阻塞等待浏览器完成授权回调。自动化的关键在四点：BROWSER=echo 防止无头环境打不开浏览器而报错退出；后台运行不卡死会话；从日志提取链接推给用户；以凭证文件落盘作为成功判据（而非进程退出）。
# ① 后台启动登录（BROWSER=echo 让 webbrowser 静默"成功"，仅打链接不真开浏览器）
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"
# ③ 基线 = 登录日志的修改时间（跨工具调用可靠；shell 变量不跨调用存活，勿用作基线）
LOG=/tmp/tccli_auth.log
CRED="$HOME/.tccli/default.credential"
监听授权（主动等回调落盘，用户零回复）：
发出链接后不要干等用户回复——继续有界监听凭证文件，用户点完「授权」的瞬间自动发现并接续流程：
# ④ 单个监听窗：每 3 秒比对凭证与日志的 mtime，最多 60 秒（必须低于工具单次执行超时；
# 若不确定超时上限，调小窗口如 seq 1 10≈30 秒，宁可多开几窗也不要单窗过长）
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 → 立即执行 ⑤ 验证并自动回显身份（全程无需用户说话）。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
auth login——重复登录会作废用户已完成授权的链接，逼用户再点一次。环境能打开浏览器时（如桌面版 Octop），去掉
BROWSER=echo，第 ② 步直接提示「浏览器已弹出，请完成授权」即可。
AUTH_LOGIN_UNSUPPORTED，旧版 tccli）旧版没有 auth 子命令。先自动升级再走 2.2（装进 Octop venv，不需要 sudo）：
uv pip install --python "$OCTOP_ROOT/.venv/bin/python3" -U tccli
# 无 uv 时："$OCTOP_ROOT/.venv/bin/python3" -m ensurepip --upgrade && ... -m pip install -U tccli
升级后重新探测（2.1），一般即可支持 auth login。若升级失败（如离线环境），才退化为半手动：引导用户在自己的终端执行 tccli configure 交互式填密钥——Agent 仍不代填、不索要、不打印密钥。
完整的多账户（--profile）、登出、凭证优先级排查细节见 references/auth.md。
安全红线：严禁向用户索要 SecretId/SecretKey，也拒绝任何有可能打印凭证的操作（尤其是 tccli configure list）。OAuth 全自动流程中 Agent 接触不到密钥明文，天然满足此红线。
基本形式：
tccli <service> <Action> [--param value ...] [--region <地域>]
输入参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
service | string | 是 | 产品标识，如 cvm、cbs、vpc。通过 Step 1.1 检索获取 |
Action | string | 是 | 接口名，如 DescribeInstances、RunInstances。通过 Step 1.3 检索获取 |
--region | string | 视接口 | 地域，如 ap-guangzhou。多数产品必传；全局接口（cam、account、dnspod、domain、ssl、ba、tag）可省略 |
--param value | 各类型 | 视接口 | 接口参数，简单类型直接传值，复杂类型传 JSON 字符串 |
常用示例 —— 查询 CVM 地域：
tccli cvm DescribeRegions
查询实例（需指定地域）：
tccli cvm DescribeInstances --region ap-guangzhou
参数规则：
--Placement '{"Zone":"ap-guangzhou-2"}'。tccli cvm RunInstances --InstanceChargeType POSTPAID_BY_HOUR \
--Placement '{"Zone":"ap-guangzhou-2"}' --InstanceType S1.SMALL1 --ImageId img-xxx \
--SystemDisk '{"DiskType":"CLOUD_BASIC","DiskSize":50}' --InstanceCount 1 ...
输出格式：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 当前并行调用存在配置文件竞争问题，会导致响应失败。当前请逐个接口调用。
部分 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 不再做本地合并/转换；tencentcloud-sdk-python）直连，把原始值（如纯日期字符串）原样赋给请求参数发出，即可通过云端类型校验。InvalidParameter 是"假参数错"，不要甩锅给用户参数填错。tccli 的 stdout 与 stderr 是两条独立流，解析时必须严格区分，否则会把警告/错误文本当结果吞掉导致解析崩溃。
① 分流捕获，禁止盲目 2>&1
tccli <service> <Action> [--region <地域>] 2>/tmp/tccli_err.log
2>&1 当作习惯写法——一旦 tccli 把 WARNING / DeprecationWarning / 版本提示吐到 stderr，合并流会让 stdout 前被塞入非 JSON 文本，导致 json.loads 直接崩溃。② 解析前"抠 JSON"
{ 到末个 } 的闭区间（或 [...]）再 json.loads，避免前后缀文本（版本提示、空格、回车）导致失败：
import re, json
m = re.search(r'\{.*\}|\[.*\]', raw, re.DOTALL)
data = json.loads(m.group(0)) if m else None
③ 解析失败兜底（不抛 Traceback）
[TencentCloudSDKException] 为唯一权威锚点提取 code / message / requestId，忽略同行 stderr 里 usage: 帮助块等噪音（它们常与异常挤在同一段，不能"出现 usage 就判参数错"而误伤）。requestId → 服务端已受理并返回（如 InvalidParameter / InternalError / UnauthorizedOperation）；无 requestId 且只有 usage: → 本地 argparse 参数解析错，与云端无关。调用失败时，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 升级；或先查在线文档确认接口存在后再操作 |
DryRunOperation | DryRun 操作成功 | 非真实错误，表示参数校验通过 |
UnsupportedRegion | 不支持的地域 | 查阅接口文档确认支持的地域列表 |
ResourceInsufficient | 资源不足 | 换可用区或调整规格重试 |
| 网络超时 / 连接失败 | 网络不通 | 检查网络连通性，确认是否需要代理 |
InternalError（message 含 nil pointer / nil pointer dereference） | 接口云端已废弃 / 后端服务已拆除 | 不是服务端随机故障，停止重试；检索在线文档确认真实情况，改用替代接口 |
AuthFailure.TokenFailure / FailedOperation.RefreshTokenError | OAuth token 已失效（浏览器授权过期或吊销） | 先按 Step 2 ④ 探测凭证文件是否已更新（可能上次授权其实成功只是被误判）；未更新才重新走 Step 2 全自动 OAuth（tccli auth login --profile <name>）；完成后按"身份确认"规范回显当前账号再继续 |
当直接执行 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 venv 的 python（Step 0 已定位 $OCTOP_ROOT）
"$OCTOP_ROOT/.venv/bin/python3" -c "
import sys
sys.argv = ['tccli', 'cvm', 'DescribeInstances', '--region', 'ap-guangzhou']
from tccli.main import main
main()
"
# ② 兜底：动态探测系统 python3 及其 site-packages（跨平台、不依赖具体版本号）
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()
"
要点：
command -v 探测系统解释器，避免写死 /usr/local/bin/python3；用 site.getsitepackages() 动态获取包目录，避免写死 python3.12 等版本号sys.argv 传参，替换示例中的 service / Action / 参数即可tccli 可用），无需本兜底，直接调用即可cloudcache.tencentcs.com 为腾讯云官方文档缓存，内容可信