# CloudBase Setup Skill

> For AI coding agents. Humans: copy the Setup Prompt from https://docs.cloudbase.net/ or the CloudBase website homepage, paste it into your AI IDE, then let the agent follow this file.

CloudBase (腾讯云开发) is an AI-native backend platform: database, auth, storage, cloud functions, hosting, and deep WeChat mini program integration. Your job is to connect the current project to CloudBase so the user can build and deploy without leaving the IDE.

**Do not stall.** Plugin / MCP often needs a session restart before tools appear. Install for the next session, then finish login / env / deploy **now** via Skills + `tcb` CLI when MCP is not yet loaded.

---

## Which site? (domestic / international) — decide first

CloudBase runs **two independent account systems**: 国内站 (domestic, `cloud.tencent.com`) and 国际站 (international, `tencentcloud.com`). Environments, consoles, API keys, and login state do **not** cross over. A wrong-site login shows up as *"logged in, but no environments visible"* rather than a clear error — so settle this **before any install or login**.

Ask the user when it is not obvious from the console URL or the envId.

| | 国内站 domestic | 国际站 international |
|---|---|---|
| Remote MCP endpoint | `https://tcb-api.cloud.tencent.com/mcp/v1` | `https://tcb-api.tencentcloud.com/mcp/v1` |
| Local stdio MCP env | default — nothing to set | `TCB_SITE=intl` + `TCB_REGION=ap-singapore` |
| `tcb` CLI | default | `TCB_IS_INTL=true` or `tcb config set isIntl true` |
| Console | `tcb.cloud.tencent.com` | `tcb.tencentcloud.com` |
| Default region | `ap-shanghai` | `ap-singapore` |
| NoSQL / document DB tools | available | **not available** |
| Free trial environment | available (3,000 resource points / month) | **not available** |

**International users: connect the international remote MCP endpoint directly** — `https://tcb-api.tencentcloud.com/mcp/v1`. It is a first-class hosted endpoint: OAuth finishes the login in the browser, no keys on disk, no local Node. The site is decided by the hostname, so there is no `site` parameter to pass.

The domestic remote endpoint — `https://tcb-api.cloud.tencent.com/mcp/v1` — works the same way and stays the default for domestic users. Both are compatible with a static credential: add `?env_id=<env_id>` plus `X-TencentCloud-SecretId` / `X-TencentCloud-SecretKey` headers from the matching site (needed for non-OAuth clients and CI).

> ⚠️ `TCB_IS_INTL` is the **CLI** switch; `TCB_SITE` is the **MCP** switch. Different names for different tools — setting the wrong one fails silently.
>
> ⚠️ Remote endpoints take **no `site` / `region` query parameter**. The hostname decides. A domestic environment located in `ap-singapore` still uses the domestic host.
>
> ⚠️ The international site has **no NoSQL / document-database tools** — route document-DB work to the domestic site or to PostgreSQL.

---

## Project type — mini program needs an extra branch

**Decide this before installing anything.** Read the project root, or the user's own words (e.g. "我主要做微信小程序开发"). A WeChat mini program has `project.config.json` plus `app.json` / `miniprogram/app.json`.

Generic CloudBase setup (§1–§5) only connects the backend. It does **not** let the agent open the simulator or preview the mini program. For a mini program project, also do all of the following:

1. **Recommend configuring the 微信开发者工具 Skill (WeChat DevTools Skill) as the concrete next step.** Route A (DevTools built-in AI) needs no import. Route B (Cursor / CodeBuddy / Claude Code / …) must export the Skill from the DevTools menu → import it into the agent (or run `wechatide` and hand the printed Skill path to the agent), then click **允许** on the first authorization dialog. Without this the agent cannot drive the simulator.
2. **Login / MCP authorization: choose 公众平台登录** (WeChat Public Platform / mini-program account, 小程序公众号扫码) **and have the mini program administrator scan the QR code.** Do not substitute another login method or a non-administrator scan; the environment bound to that mini program will not be visible.
3. Check the prerequisites: WeChat DevTools **Nightly**, a real `appid` (not empty, not `touristappid`), and `project.config.json` at the project root.
4. Verify with the tutorial's acceptance line: "检查开发者工具是否已登录，然后打开这个小程序并预览。" Only after preview works should the agent take business requests.

Tutorial: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/tutorials/ai-develop-miniprogram  
WeChat official Skills doc: https://developers.weixin.qq.com/miniprogram/dev/devtools/Skills.html

---

## Free trial environment (免费体验环境)

**Domestic site (国内站) only.** The free trial environment does not exist on the international site — international-site users need a paid environment.

**No paid plan is needed on the domestic site to start.** Since 2026-01-16, every CloudBase account can create **one free trial environment**.

- **3,000 resource points per month** for evaluating the platform — details: https://docs.cloudbase.net/quick-start/resource-point
- **One per account.** An account still on the legacy free plan cannot create a new trial environment until the previous one is upgraded to paid or destroyed.
- **Renewal: 6 months at a time**, renewable within the month before expiry — **no auto-renewal**.
- **Converting to paid manually** also converts the trial environment; renewal reminders continue.
- **No add-on resource packs and no pay-as-you-go** on a trial environment — upgrade to a paid plan first.

---

## 0. Prerequisites (Node / npm / npx / git) — run first

Plugin and Skills installs clone a repo, so they need `git`. `@cloudbase/cli`, the npm MCP server and remote MCP do not. Check everything up front:

```bash
command -v node; command -v npm; command -v npx; command -v git
node -v; npm -v
```

| Result | Action |
|---|---|
| All present (`node` ≥ 18, `npm`, `npx`, `git`) | Continue to §1 |
| Missing Node / npm / npx | Fix once (below), re-check, then continue — do **not** loop on `npx` failures |
| **`git` missing** | Do **not** retry `npx plugins add` / `npx skills add` with repo URLs — they die in the clone. Go to §4.1, or use the IDE's native marketplace / built-in connector (§3.B / §3.C) |

Missing `git` and want it? macOS `xcode-select --install` · Windows `winget install Git.Git` (or https://git-scm.com/download/win) · Linux package manager — then re-open the shell / IDE. **If the machine is locked down and git cannot be installed, do not fight it: run §4.1 instead.**

**Fast fix (pick one that fits the OS, then re-open the shell / IDE so PATH updates):**

- macOS: `brew install node` — or install LTS from https://nodejs.org
- Windows: `winget install OpenJS.NodeJS.LTS` — or https://nodejs.org
- Linux: distro Node LTS, https://nodejs.org, or `nvm` / `fnm` / `asdf` (install Node LTS, ensure PATH)
- Already have Node via nvm/fnm but `npx` missing in this shell: load the version manager (`source ~/.nvm/nvm.sh` or equivalent), then retry

**If the user cannot install Node right now:**

1. Prefer the IDE **native marketplace / plugin / built-in connector** path (§3.B / §3.C) — no hand-run `npx`.
2. Otherwise stop automating CLI installs; give console links and ask them to install Node LTS (or enable the marketplace plugin). Do not pretend `npx` works.

---

## 1. Preferred (do this first)

**Prefer `npx plugins add`. Do not hand-write MCP JSON** when the plugins CLI can install into the current AI tool.

> ⚠️ This requires `git` — the CLI always runs `git clone`, for `owner/repo` and for `https://` URLs alike. No git on the machine (or clone blocked by policy) → **§4.1**, do not retry.

Default install (user/global scope — works across projects):

```bash
npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user
```

Optional: pin one IDE with `--target`:

| `--target` | Tool |
|---|---|
| `claude-code` | Claude Code |
| `cursor` | Cursor |
| `codex` | Codex |
| `grok` | Grok Build |
| `kimi` | Kimi Code |
| `github-copilot` | GitHub Copilot CLI |
| `vscode` | VS Code (Preview) |

Omit `--target` to install into all detected supported IDEs. Inspect detection:

```bash
npx plugins targets
```

Examples:

```bash
npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user --target cursor
npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user --target claude-code
```

### After install — do **not** wait for MCP

1. If the installer says so, tell the user a **restart / reload** unlocks MCP + plugin hooks next session.
2. **This session:** treat CloudBase MCP as unavailable until tools are actually visible. Continue with §2 (CLI / Skills fallback). Do not block on restart.
3. Optionally speed up Skills-only coverage in parallel (safe if plugin already bundles skills — skip if installer confirmed skills landed):

```bash
npx skills add tencentcloudbase/cloudbase-skills -y
```

4. When MCP tools **are** already visible in this session, skip CLI for the same action and use MCP.
5. Reply in one short sentence that setup is ready (or “configured for next session; using CLI now”), then suggest the most relevant next steps for this project. **For a mini program project, the first suggested step is configuring the 微信开发者工具 Skill** (see Project type); generic backend suggestions (create a table, deploy a hello API) are not the right first step.

Docs: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ai-agent-plugins

---

## 2. First-session / MCP-not-ready path (CLI fallback)

Use this when **any** of these hold:

- User just finished plugin / MCP install and has not restarted
- No CloudBase MCP tools in the tool list
- MCP calls fail with “unknown tool” / connection errors after one verify attempt

**Decision tree:**

```
0. Mini program project? → also run the mini-program branch (Project type section) throughout the steps below
1. Probe MCP in THIS session (tool list / one envQuery-or-auth call)
2. Usable now?
   ├── YES → Prefer MCP (inspect schemas, then call). Skip CLI for the same action.
   └── NO  → Configure MCP/plugin for next session (§1 or §3), THEN use CLI now
3. CLI path
   - Ensure @cloudbase/cli: npm i -g @cloudbase/cli && tcb --version
   - tcb login → tcb env list → tcb env use <envId>  (mini program: 公众平台登录, administrator scans the QR code)
   - Deploy/manage via domain commands (tcb fn deploy / tcb hosting deploy / …)
   - Do NOT use tcb deploy
4. After user restarts → re-probe MCP; switch back to MCP-first
```

Skills pack (if not already present) gives the agent the domain playbooks:

```bash
npx skills add tencentcloudbase/cloudbase-skills -y
# GitHub unreachable → §4 CNB URL
```

If you already have the `cloudbase` skill installed locally, read its `SKILL.md` for the domain playbooks referenced above.

### No Tencent Cloud account? Log in with an API Key

The connector / device-code authorization page only offers WeChat scan. A user who holds nothing but an environment-level API Key gets stuck there — do **not** keep retrying it, and do not send them to sign up for a Tencent Cloud account.

Two ways through, both via CLI:

**Interactive (machine with a browser):**

```bash
tcb login --flow web
```

CLI starts a temporary local HTTP server and opens the authorization page itself; that page has a **使用 API Key 登录** (Use API Key) option where the key gets pasted. The callback goes to `127.0.0.1` on the machine that ran the command, so this only works on a local GUI machine — remote server, container, or headless box should stay on the default device flow.

**Non-interactive (you can finish it yourself):**

```bash
tcb login --cloudbase-api-key <key> -e <envId>
```

An environment-level API Key is scoped to one environment, so `-e` is required. Ask the user to paste the key; never invent one, and write `<key>` — not the real value — anywhere it would be stored or reported.

---

## 3. Fallbacks (only when Plugin cannot install)

Use these **only** if `npx plugins add` is unsupported for this IDE, fails (including after CNB retry), or the user already uses a conflicting native install.

### A. Skills only (fastest non-plugin path)

```bash
npx skills add tencentcloudbase/cloudbase-skills -y
```

Then follow §2 for login / env / deploy via `tcb` until MCP exists.

Docs: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/prompts/how-to-use

### B. Native MCP / IDE marketplace / mcporter

- Follow the matching IDE guide under https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/
- Typical stdio shape when you must configure MCP by hand: `npx -y @cloudbase/cloudbase-mcp@latest`
- Getting started: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started
- Do **not** also run `npx plugins add` for the same IDE if marketplace / native plugin is already installed (duplicate instances).

### C. Built-in connectors

Some tools ship CloudBase built-in (e.g. WorkBuddy connector, ZCode plugin). Prefer the built-in path for that IDE; do not double-install.

WorkBuddy, three clicks and no install:

- In the chat: **连接器** (Connectors) at the bottom left of the input box → search `cloudbase` → **腾讯云 CloudBase** → turn on the switch
- Or the management page: left sidebar **专家** (Experts) → **连接器** (Connectors) → **腾讯云 CloudBase** → `+` → **连接** (Connect)

The first enable asks for a WeChat QR scan. **For a mini program project, choose 公众平台登录 and let the mini program administrator scan it** (see Project type). With no Tencent Cloud account and only an environment-level API Key, that page cannot be completed: skip the connector and use the API Key login in §2, then drive the CLI.

#### Looking up a built-in connector

The lookup behaves in ways that waste turns if you assume a normal search (verified on WorkBuddy, 2026-10):

- **Search with the entity name, not a request.** `cloudbase` / `腾讯云开发` finds it; a sentence like "connect CloudBase so I can manage the database" returns unrelated connectors. Keyword lists are ignored.
- **Installed connectors are excluded from search results.** "No results" often means "already connected". Check the installed connector list first and reconnect from there instead of searching again.
- **Enabling or disabling a connector does not change an open session.** Tools already wired keep working until the session ends, and unbinding does not revoke them mid-session. What needs a new session is a credential change: first authorization, environment switch, key rotation.

#### Fixing a connector that is missing or not working

Triage before reinstalling. From inside the chat these failures look identical, and reinstalling only helps the first one.

| What you see | What it is | What to do |
|---|---|---|
| No `cloudbase` MCP tool in this session's tool list | not wired into this session | check the installed list (`bound: true`), `reconnect_plugin` once, then a new session |
| Tool exists, `auth(action="status")` is not `READY` | credential | follow the `next_step` in that response; a credential change needs a new session |
| `READY` but `current_env_id` is another environment | binding | `auth(action="set_env", envId=…)` |
| Network, signature, or permission error (`SIGN_PARAM_INVALID`, `INVALID_ACCESS_TOKEN`, 403, 5xx) | credential or gateway | report the code verbatim and stop; reinstalling the connector will not help |

Credentials live in `~/.config/.cloudbase/auth.json` (mode 600), with `authSource` recording how they were obtained. A connector reads that same file through `login_by_api_key`. Never put a key into `mcp.json`: the two copies drift, and then the connector and the CLI disagree about which environment is current.

Cap the repair loop at one reconnect, one search, and one authorization per session. Still not ready after that: report which step failed and the last error code, then hand it back.

### D. WeChat mini program focus

Mini program projects follow the **Project type** branch at the top of this file, whether you came from §1 or from a fallback here. Do not treat the tutorial as a fallback-only step:

- https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/tutorials/ai-develop-miniprogram

---

## 4. When the git path fails (no git / GitHub unreachable)

Two different failures land here. Check which one you have before running anything:

| Symptom | What it means | Go to |
|---|---|---|
| `program not found` / `git: command not found` / `failed to run git clone` | no `git` on PATH | **§4.1** — CNB URLs will not help, they also clone |
| timeout / DNS / TLS / 443 blocked | `git` works, GitHub is unreachable | CNB full git URLs below |

Short `owner/repo` forms **always** resolve to GitHub. CNB URLs are still git URLs, so they only help when `git` itself is present.

### Plugin via CNB

```bash
npx plugins add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-plugin.git -y --scope user

# Optional Sites plugin
npx plugins add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-sites-plugin.git -y --scope user
```

Do **not** use the monorepo mirror `CloudBase-AI-ToolKit` for `npx plugins add` — its marketplace layout is not OPS-installable the same way as the dedicated plugin repos.

### Skills via CNB

```bash
npx skills add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills.git -y
```

### 4.1 No git at all — download the tarball, install from a local directory

`plugins add` resolves anything that is not `owner/repo`, `https://` or `git@` as a **local path**, so an extracted tarball installs with no git involved. `skills add` additionally accepts GitHub / GitLab **archive URLs** and unpacks them over HTTPS.

```bash
# Plugin: HTTPS tarball → extract → install from the local directory
curl -L https://codeload.github.com/TencentCloudBase/cloudbase-plugin/tar.gz/refs/heads/main -o cloudbase-plugin.tgz
tar xzf cloudbase-plugin.tgz
npx plugins add ./cloudbase-plugin-main -y --scope user --target <target>

# Optional Sites plugin, same pattern
curl -L https://codeload.github.com/TencentCloudBase/cloudbase-sites-plugin/tar.gz/refs/heads/main -o cloudbase-sites-plugin.tgz
tar xzf cloudbase-sites-plugin.tgz
npx plugins add ./cloudbase-sites-plugin-main -y --scope user --target <target>

# Skills: archive URL is downloaded and unpacked, no git
npx skills add https://codeload.github.com/TencentCloudBase/cloudbase-skills/tar.gz/refs/heads/main -y
```

What changes versus the git path:

- **`--target` is required** when the CLI cannot detect the agent (`No supported targets detected`). Same values as §1.
- The marketplace is registered under the **directory name** (`cloudbase-plugin-main`), not the repo name.
- **No `git pull` behind it** — auto-update does not work; updating means downloading the tarball again and reinstalling.
- `skills add` only treats GitHub / GitLab archive, release and raw URLs as downloads. Any other URL falls back to `git clone`.
- Windows: `curl` and `tar` ship with Windows 10+. Installing Git for Windows is still the better long-term fix when policy allows it.

### MCP via npm (no git clone)

```bash
npx -y @cloudbase/cloudbase-mcp@latest
```

Docs: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started

---

## 5. Verify (run after install)

Ask the platform / MCP when available; otherwise use CLI. Do not invent answers.

| Check | MCP (when loaded) | CLI fallback |
|---|---|---|
| Login / env | `auth` / `envQuery` (`action=info`) | `tcb login` → `tcb env list` / `tcb env use` (no Tencent Cloud account → API Key, see §2) |
| Capabilities | List relevant tools (db, functions, hosting, auth) | Confirm `tcb --version` + skills present under the IDE skills dir |
| First task | Propose one concrete next step from the repo | Same |

Success criteria:

1. Node/npx available **or** marketplace / built-in path used without requiring `npx`.
2. Plugin and/or Skills and/or MCP config landed for the **next** session.
3. This session can resolve envId (MCP or `tcb`) — or user was given a clear login next step.
4. One concrete next task suggested (init backend, create a table, deploy hello API, etc.). **For a mini program project this must be the DevTools Skill configuration + preview check** (Project type), not a generic backend task.

If tools are missing, go back to §1 / §3 / §4 — do not fake success. If only MCP is missing after a fresh install, that is **expected**; complete §2 and report “CLI path ready; restart unlocks MCP”.

---

## 6. Troubleshooting

### (a) `npx` / `npm` / `node` not found

Re-run §0. One clear Node LTS install beats repeated failed `npx` commands.

### (b) Plugin installed but MCP tools missing in this chat

Expected on first session. Do not restart-loop. Use §2 (`tcb` + Skills). Tell the user to reload once when convenient.

### (c) `plugins add` / `skills add` fails

Read the error before retrying:

| Error | Cause | Fix |
|---|---|---|
| `program not found` / `git: command not found` | no `git` on PATH | §4.1 — CNB URLs also clone, they will not help |
| `Could not read from remote repository` / auth prompt | private repo or missing credentials | retry the `https://` form, or use §4.1 |
| timeout / DNS / TLS | GitHub unreachable | CNB full git URLs (§4), or npm MCP |

### (d) `npm` ENOTEMPTY / corrupted global package

```bash
npm uninstall -g @cloudbase/cli
npm i -g @cloudbase/cli --force
# same pattern for other global pkgs if needed
```

### (e) Duplicate MCP instances

Do not stack Plugin + hand-written MCP + marketplace install for the same IDE. Keep one path.

### (f) `tcb` not found after npm install

Confirm PATH / rehash shell (`hash -r`), or invoke via `npx @cloudbase/cli`. Never fall back to inventing SecretId in config as the default.

---

## Rules

- **Preferred path = plugins CLI** with `--scope user`. Do not default to project-local scope unless the user explicitly asks.
- **Prerequisite check first** — detect Node/npm/npx **and git**; fix or switch to marketplace before retrying installs.
- **No git means §4.1, not a retry loop** — `plugins add` / `skills add` with repo URLs cannot succeed without git; do not attempt them twice, and do not "fall back" to CNB (it clones too).
- **MCP when present, CLI when not** — never stall waiting for restart when `tcb` can finish the job now.
- **Mini program projects take the extra branch** — recommend the DevTools Skill, use 公众平台登录 with the mini program administrator's QR scan, and verify with the preview acceptance line. Do not leave the tutorial as a fallback-only step.
- If GitHub clone fails, retry with the **CNB full URL** before giving up on plugins.
- Do **not** invent env IDs, secrets, or API keys.
- Do **not** skip login / auth when the tool requires it.
- **No Tencent Cloud account → API Key** — `tcb login --flow web` on a GUI machine (the page has an API Key option), or `tcb login --cloudbase-api-key <key> -e <envId>`. The connector card only offers WeChat scan; do not loop on it.
- Do **not** stack Plugin + manual MCP + Skills on the same IDE unless the user asks.
- Do **not** recommend `tcb deploy`; use domain commands (`tcb fn deploy`, `tcb hosting deploy`, …).
- Prefer real MCP/tool results over guessing CloudBase behavior.
- Deeper product docs index: https://docs.cloudbase.net/llms.txt

---

## 中文摘要（给人 / 中文 Agent）

**先判项目类型：** 根目录有 `project.config.json` + `app.json`，或用户说「我主要做微信小程序开发」，就是小程序项目。通用接入只接好后端，**不能让 AI 打开模拟器预览**。小程序项目要额外做四件事：① 建议配置开发者工具 Skill（路 A 开发者工具内置 AI 不用导入；路 B 要「导出开发者工具 Skill → 导入 Agent」，或终端跑 `wechatide` 把输出的 Skill 路径交给 Agent，首次授权弹窗必须点允许）；② 登录 / MCP 授权时**选择公众平台登录，需要小程序的管理员扫码登录**，别换别的登录方式、也别让非管理员扫，否则看不到该小程序绑定的环境；③ 前置条件：微信开发者工具 Nightly、真实 AppID（不是空、不是 `touristappid`）、根目录 `project.config.json`；④ 验收语「检查开发者工具是否已登录，然后打开这个小程序并预览」，能预览后再提业务需求。教程：https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/tutorials/ai-develop-miniprogram ；微信官方 Skills 文档：https://developers.weixin.qq.com/miniprogram/dev/devtools/Skills.html  
**先定站点：** 国内站（`cloud.tencent.com`）/ 国际站（`tencentcloud.com`）账号体系独立，选错表现为「登录成功但看不到环境」。国际站：远端直连 `https://tcb-api.tencentcloud.com/mcp/v1`；本地 stdio 用 `TCB_SITE=intl` + `TCB_REGION=ap-singapore`；CLI 用 `TCB_IS_INTL=true`。国内站远端 `https://tcb-api.cloud.tencent.com/mcp/v1`，默认值不用声明。国际站无 NoSQL 工具。  
**免费体验（仅国内站）：** 每个云开发账号可创建 1 个免费体验环境（3,000 点/月）；仍在用旧免费套餐的账号需先把原环境转付费或销毁才能新建；单次续费 6 个月、不支持自动续费；不支持加购资源包与按量付费。详见资源点计费 FAQ：https://docs.cloudbase.net/quick-start/resource-point  
**先查 Node 和 git：** `command -v node npm npx git`；Node 缺失按系统装 LTS（或走 IDE 应用市场插件），不要反复空跑 `npx`。  
**优先：** `npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user`（不要手写 MCP JSON）—— **这条要 git**，`owner/repo` 和 `https://` 地址都会走 `git clone`。  
**装完立刻可用：** 插件 / MCP 常需重启才进本会话 —— **不要干等**；先配好供下次用，本会话用 Skills + `tcb login` / `tcb env use` / 领域部署命令（禁止默认 `tcb deploy`）。  
**加快 Skills：** `npx skills add tencentcloudbase/cloudbase-skills -y`  
**没有 git（或装不上）：** 不要重试，CNB 也是 git —— 走 §4.1：`curl -L https://codeload.github.com/TencentCloudBase/cloudbase-plugin/tar.gz/refs/heads/main -o p.tgz` → `tar xzf p.tgz` → `npx plugins add ./cloudbase-plugin-main -y --scope user --target <target>`；Skills 可直接 `npx skills add https://codeload.github.com/TencentCloudBase/cloudbase-skills/tar.gz/refs/heads/main -y`。记得显式给 `--target`，市场名会变成目录名、自动更新失效。  
**GitHub 不可达（git 正常）：** CNB  
`npx plugins add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-plugin.git -y --scope user`  
Skills：`npx skills add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills.git -y`  
再不济：npm MCP `npx -y @cloudbase/cloudbase-mcp@latest`  
**可选 `--target`：** `claude-code` / `cursor` / `codex` / `grok` / `kimi` / `github-copilot` / `vscode`  
**没有腾讯云账号：** 用 API Key 登录，别让人去注册账号，也别在连接器的扫码授权页反复试 —— 那里只有微信扫码。交互式：`tcb login --flow web`，CLI 会在本机拉起浏览器，授权页上可选「使用 API Key 登录」（回调打到 `127.0.0.1`，只适合有图形界面的本机）；非交互：`tcb login --cloudbase-api-key <key> -e <envId>`，环境级 Key 绑一个环境，`-e` 必填。密钥让用户自己粘贴，不要编、不要写回任何要保存的地方。  
**WorkBuddy 内置连接器：** 最短路径是把拉起链接发给用户，WorkBuddy 内打开直达 CloudBase 连接器：https://www.workbuddy.cn/share/asset?shareCode=ZxZ2mdZ8yKM0s3uj0JUXU5&sig=HG4sMzqfmvtP2q5L 。手动路径是输入框左下角「连接器」→ 搜 `cloudbase` →「腾讯云 CloudBase」→ 打开开关；管理页是左侧「专家」→「连接器」页签 → 卡片上的 `+` →「连接」。首次启用要微信扫码，不要让人去装 MCP JSON。  
**连接器连不上先分诊：** 工具列表里没有 `cloudbase` = 没接上（装了就 reconnect，再开新会话）；`auth(action="status")` 不是 `READY` = 凭证问题；`READY` 但 `current_env_id` 不对 = 绑定问题；网络 / 签名 / 权限报错 = 原样报错误码，重装没用。凭证只写 `~/.config/.cloudbase/auth.json`，不要写进 `mcp.json`。  
验收：能解析 envId（MCP 或 CLI），一句话说清已就绪或「已配好 + 本会话走 CLI」，再建议下一步。不要编造环境 ID 或密钥。