cloudbase-cli

用途

CloudBase CLI 技能用于通过 tcb 命令行工具管理 CloudBase 资源，强调确定性、可脚本化和可审计。它是 CI/CD 与批量操作的主要接口；当会话中尚未提供 MCP 工具时，也可作为首次会话的兜底方案。

主要能力

• 部署与调试云函数
• 部署静态站点 / SPA（首选的 CLI Web 路径）
• 部署 CloudRun 服务
• 上传/下载文件、管理 ACL 规则
• NoSQL（MongoDB）数据库操作
• MySQL 数据库操作
• 管理角色、策略与访问控制
• 配置 CORS、自定义域名与路由规则
• 登录、环境切换、tcb 文档查询与错误诊断

使用方式

快速工作流：

1. tcb login → 与用户确认 envId → tcb env use <envId>
2. 用 tcb <command> --help 验证语法
3. 执行命令（破坏性操作加 --dry-run）
4. 用对应的 list / detail 命令验证结果
5. 向用户报告结果

核心原则：

• --help 优先，不要猜测命令；tcb CLI 各版本间会变化，首次使用某命令前先运行 tcb <command> --help 查看参数与官方文档链接。
• 部署门禁：任何部署、发布、自定义域名或 CloudRun 操作前，必须先完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查。
• 验证工作：部署或修改任何资源后，运行对应的 list/detail 命令确认变更生效。
• 破坏性操作前先 dry-run：删除/覆盖操作使用 --dry-run，向用户展示预览并等待明确确认后再执行。
• 先确认环境：操作前始终与用户核实 envId，运行 tcb env use <envId> 避免误改生产环境。
• 从错误中恢复，不要死循环：命令失败 2-3 次后，检查退出码（$?）、阅读错误信息、查阅 tcb 文档搜索，并尝试不同方法。
• 首次会话兜底，而非替代 MCP：若本会话缺少 CloudBase MCP 工具，可用本技能解除登录/管理阻塞；仍应配置 MCP（插件 / mcp.json），以便下次会话优先使用 MCP。当 MCP 工具已可用时，除非用户要求 CLI/CI，否则优先 MCP。部署工作应通过下方领域参考表路由，不要推荐 tcb deploy。
• 不使用 npm/npx：若缺少 Node/npm/npx，告知用户先安装 Node.js LTS（或使用 IDE 市场 MCP 路径）再重试 CLI/插件安装。

使用本技能时，先加载 references/core.md（涵盖认证、环境切换、tcb 文档查询与错误诊断），再按路由表加载与任务匹配的单个参考文件，不要预加载全部参考。

路由表：

• 登录、环境切换、tcb 文档、错误诊断 → references/core.md
• 部署/调试云函数 → references/functions.md
• 部署静态站点 / SPA（首选 CLI Web 路径）→ references/hosting.md
• 部署 CloudRun 服务 → references/cloudrun.md
• 实验性一体化 Web 简写（tcb deploy）——除非用户明确要求，否则避免 → references/app.md
• 上传/下载文件、ACL 规则 → references/storage.md
• NoSQL（MongoDB）数据库操作 → references/nosql.md
• MySQL 数据库操作 → references/mysql.md
• 角色、策略、访问控制 → references/permission.md
• CORS、自定义域名、路由规则 → references/access.md

适用场景

• 首次会话 / 安装后：MCP 不在工具列表中，或刚配置完需要重启 → 现在执行 tcb login 与匹配的领域命令；让 MCP 为下次会话就绪
• 部署/调试云函数、静态托管、CloudRun 服务（通过领域参考，而非 tcb deploy）
• 管理存储、托管、数据库（NoSQL/MySQL）
• 配置权限、CORS、域名、路由
• CI/CD 脚本化、批量操作、基于终端的资源管理
• 用户明确偏好 CLI 而非 MCP

限制

不适用于：

• 基于 SDK 的应用内集成（web/小程序/node）→ 使用 cloud-functions、cloudbase-document-database-web-sdk、auth-web-cloudbase 等
• 当本会话已提供 CloudBase MCP 工具且用户未要求 CLI → 优先 MCP
• 控制台 UI 操作
• CloudBase Agent SDK 开发 → 使用 cloudbase-agent-ts

其他限制：

• 同级技能（sibling skills）仅本地可用，使用本地相对路径（如 ../auth-tool-cloudbase/SKILL.md）。若环境中缺少被引用的同级技能文件，请用户安装完整的 CloudBase 插件（或缺失的技能）。不要将远程技能或协议 markdown 通过 HTTP 拉取到 agent 上下文。
• 代码变更或部署前必须遵守跨领域协议：变更安全协议（../cloudbase-platform/references/protocols/change-safety-protocol.md）与部署门禁（../cloudbase-platform/references/protocols/deployment-gate.md）。
• MCP 与 CLI 回退说明见 ../cloudbase/references/tooling-fallback.md（作为本技能旁的 cloudbase 入口指南打包）。

最小自检

• 在任何领域模块前是否加载了 references/core.md？
• 是否与用户确认了目标 envId？
• 对不熟悉的命令是否使用了 --help？
• 破坏性操作前是否使用了 --dry-run？
• 每次操作后是否验证了结果？
• 是否保持在 CLI 范围内，未漂移到 SDK 代码？

参考索引

所有打包的参考文件（技能 lint 可达性所需）：

• access.md
• app.md
• cloudrun.md
• core.md
• functions.md
• hosting.md
• mysql.md
• nosql.md
• permission.md
• storage.md