cloudbase

CloudBase 開発ガイドライン

ステップ 0 — サイトを確認する（国内か海外か）

CloudBase には独立した 2 つのアカウントシステムがあります。国内站（国内向け、cloud.tencent.com）と国际站（海外向け、tencentcloud.com）です。環境、コンソール、API キー、ログイン状態は相互に共有されません。サイトを間違えてログインした場合、明確なエラーではなく、通常は*「ログインできたが、環境が表示されない」*という状態になります。そのため、MCP のインストール、ログイン、環境のバインドを行う前にサイトを確定してください。

可能であれば、コンソールドメイン、envId、既存のエラーから判断してください。それ以外の場合は、ユーザーに一度だけ確認してください。推測してはいけません。

	国内站 国内向け	国际站 海外向け
リモート MCP（推奨）	https://tcb-api.cloud.tencent.com/mcp/v1	https://tcb-api.tencentcloud.com/mcp/v1
ローカル stdio MCP	設定不要（TCB_SITE のデフォルトは domestic）	TCB_SITE=intl + TCB_REGION=ap-singapore
tcb CLI	デフォルト	TCB_IS_INTL=true（または tcb config set isIntl true）
プロジェクトレコード .cloudbase/project.json	site は省略、または "domestic"	"site": "intl", "region": "ap-singapore"
コンソール	tcb.cloud.tencent.com	tcb.tencentcloud.com
デフォルトのリージョン	ap-shanghai	ap-singapore
NoSQL／ドキュメント DB ツール	利用可能	利用不可

• デフォルトではリモートに接続してください。 どちらのホストも正式なエンドポイントです。OAuth がログインを処理し、ホスト名によってサイトが決まるため、渡す site パラメーターはありません。海外向け：https://tcb-api.tencentcloud.com/mcp/v1、国内向け：https://tcb-api.cloud.tencent.com/mcp/v1。
• ローカル stdio は、必要な場合にのみ使用してください。CloudBase API キーでログインするアカウント、両方のサイトをカバーする必要がある 1 つのセッション（リモート URL は 1 つのサイトに紐付けられます）、またはホストされたエンドポイントに登録されていないツールを必要とするタスクが該当します。関数やアプリのデプロイは理由になりません。2 段階のアップロードを使えば、リモート経由で実行できます。比較については references/mcp-setup.md を参照してください。
• TCB_IS_INTL（CLI）と TCB_SITE（MCP）は、異なるツールで使う別々の変数名です。使用中のツールに対応する方を設定してください。誤った方を設定しても、何も起こらず無視されます。
• 初回実行時に、サイトを一度確定し、保存してください。CLI の切り替え設定はマシン全体に適用され、MCP の切り替え設定はクライアントごとに適用されます。MCP が再起動後に読み取れるプロジェクト単位の設定は .cloudbase/project.json だけです。references/site-onboarding.md に従い、以降のセッションでは再確認しないでください。

詳細およびコピー＆ペースト用の設定については references/mcp-setup.md を参照してください。CLI の詳細については references/tooling-fallback.md を参照してください。初回実行のオーケストレーション（起動／スキップ、競合の調整、MCP がダウンした場合のフォールバック）については references/site-onboarding.md を参照してください。

ワークフロー

1. Exploration  →  Read the matching skill completely before writing any code.
                   Search with searchKnowledgeBase(mode="skill"), then Read full SKILL.md.
2. Implementation
   ├── 2a. Resource preparation → Prefer MCP; if MCP tools are missing in THIS session,
   │     configure MCP for next session and use `tcb` CLI now (see tooling-fallback.md)
   └── 2b. Frontend implementation → Write code, install deps, start server, test
3. Close-out  →  Run cloudbase-code-review, fix errors, declare done
                   (after a verified deploy: optionally offer Deployment Share once — see references/deployment-workflow.md §5)

主な制約： ステージ 2a はフロントエンドコードより先に実施する必要があります。ステージ 3 は必須です。

有効化の契約

ルーティングでは、ソース、生成されたアーティファクト、インストール環境を通じて、安定したスキル ID（auth-tool-cloudbase、auth-web-cloudbase、http-api-cloudbase、…）を使用します。

スタンドアロンのスキルに対するフォールバック

公開されているスキルが 1 つだけの場合：

• ワークスペースにファイルがある場合は、ローカルの相対パス（references/<skill-id>/SKILL.md または隣接するスキルディレクトリ）を優先してください。
• リモートの raw URL から兄弟スキルの Markdown を取得し、エージェントのコンテキストに追加しないでください。
• 必須の兄弟スキルがローカルにない場合は、CloudBase スキルパック全体または IDE プラグイン（npx skills add tencentcloudbase/cloudbase-skills）をインストールするよう、ユーザーに依頼してください。git が見つからず失敗する場合は、references/mcp-setup.md に記載されている tarball の方法を使い、その後はローカルファイルのみを使用してください。

現在のスキルからの相対パス references/... に従ってください。このセッションで MCP が利用できない場合は、references/tooling-fallback.md に従ってください。次のセッションに向けて references/mcp-setup.md で MCP を設定し、今すぐログイン／管理を完了するには cloudbase-cli スキル経由で tcb CLI を使用してください（core.md と対応するドメインのリファレンスを読み、tcb deploy は使用しないでください）。npm／npx が見つからない場合は、tooling-fallback.md の「No npm/npx」セクションに従ってください。

アクション実行前の共通ルール

• シナリオを特定してから、コードを書く、または CloudBase API を呼び出す前に、該当するスキルを読みます。
• ツールキットの保守ではセマンティックな情報源を優先し、ランタイムのルーティングには安定したスキル ID を使用します。
• このセッションで利用可能な場合は、管理タスクには MCP または mcporter を優先します。実行前にツールのスキーマを確認してください。まだ利用できない場合も、作業を止めずに references/tooling-fallback.md の CLI による代替手順を使用します。
• MCP への接続全般（ローカルの stdio とリモートの違い）、mcporter を使ったシェルからのツール呼び出し、サイト／リージョン／プラグインの切り替え、またはこのオープンソースリポジトリの修正を行う場合は、cloudbase-mcp を読みます。
• UI タスクでは、まず ui-design を読み、インターフェースのコードを書く前にデザイン仕様を出力します。
• 認証タスクでは、まず auth-tool-cloudbase を読み、フロントエンドを実装する前にプロバイダーを有効にします。
• 認証ドメインを分けて扱います。管理画面へのログインには auth を使用します（MCP 認証を利用できない場合は tcb login）。アプリ側の認証には queryAppAuth / manageAppAuth を使用します。

共通のガードレール

• 同じ方法で 2〜3 回失敗したら、作業を止めて別の方法に切り替えます（プラットフォームのスキル、ランタイム、認証ドメイン、権限モデル、SDK の境界など）。
• 必ず EnvId を明示します。CLI で選択された環境や暗黙の環境状態に依存してはいけません。
• 環境識別子がエイリアス、ニックネーム、その他の短縮形の場合、それをそのまま auth.set_env、SDK の初期化、コンソール URL、生成される設定に渡してはいけません。まず queryEnv(action=list, alias=..., aliasExact=true) で正規の完全な EnvId に解決します。複数の環境が一致する場合、または完全一致するエイリアスがない場合は、作業を止めてユーザーに確認します。
• MCP／ツールの結果をファイルに書き込む場合は、生のオブジェクトではなく、シリアライズしたテキスト（JSON.stringify(result, null, 2)）を渡します。書き込みツールが、文字列を期待する content にオブジェクトが渡されたと報告した場合、同じ生のオブジェクトで再試行してはいけません。オブジェクトをシリアライズしてから一度だけ再試行し、再試行時に元のオブジェクトではなくシリアライズ済みの文字列が実際に渡されていることを確認します。
• シナリオ固有の注意点は子スキルに記載し、このエントリーファイルに追加しないでください。
• フロントエンドの初回デプロイでは、必ず manageApps(action="deployApp", ...) を使用します。 createApp / updateApp アクションはありません。初回デプロイも再デプロイも deployApp を使用し、再デプロイ時には同じ serviceName を再利用します。manageHosting は、もともとホスティング経由でデプロイされたプロジェクトの増分更新にのみ使用します。

エンジニアリングの基本原則（すべてのシナリオに適用）

これらのルールは利便性より優先されます。詳しい理由は web-development に記載されています。

• フロントエンドのコードを書く前に、バックエンドのリソースを準備します。 認証プロバイダー、テーブル、ストレージドメイン、セキュリティルールには MCP を優先します。このセッションで MCP ツールを利用できない場合は、次のセッションに向けて MCP を設定したうえで tcb CLI を使用します（references/tooling-fallback.md）。
• 型エラーを回避するために any を使用してはいけません。 unknown と型ガード／正確なインターフェースを優先します。
• 完了と報告する前に、必ず自分で検証します。 静的検証（tsc / lint / build / tests）とランタイム検証（ユーザーに見えるフローには agent-browser）を行います。実行できないレイヤーがある場合は、明示します。
• 失敗を取り繕ってはいけません。 空の try/catch を使わず、テストを削除して成功扱いにしないでください。
• ai.createModel(...) / wx.cloud.extend.AI.createModel(provider) が受け取るのは GroupName であり、ベンダー／モデル ID ではありません。 有効な値は "cloudbase"、"hunyuan-v3"（レガシープランのグループ。hy3 のみで、廃止予定）、"hunyuan-exp"（旧式のレガシー組み込み）、または "custom-<name>" です。モデル ID は generateText / streamText の model フィールドに指定します。ai-model-web / ai-model-nodejs / ai-model-wechat を参照してください。
• 低機能環境向けの STOP カード： PostgreSQL / CloudBase PG / app.rdb() / queryPgDatabase / managePgDatabase の場合は、postgresql-development-cloudbase に振り分けます。この経路で NoSQL コレクション API や MySQL ツールを使用してはいけません。Web 認証ガードでは auth.getSession() を使用し、data.session があることを必須にします。非推奨の getLoginState() / auth.getUser() をログインの証明として使用してはいけません。

優先度の高いルーティング

シナリオ	最初に読む	次に読む	最初にルーティングしない	操作前に必ず確認すること
最小構成の Web BaaS デモ（最速ルート）	minimal-web-baas-demo	web-development, no-sql-web-sdk, postgresql-development	cloud-functions, cloudrun, spec-workflow, ui-design	BaaS を優先する Web SDK CRUD、MCP スキーマのみ、シークレット／cron／ルールで表現できない要件がない限りクラウド関数は不要
Web ログイン／登録／認証 UI	auth-tool-cloudbase	auth-web, web-development	cloud-functions, http-api	プロバイダーの状態と公開可能キー
WeChat ミニプログラム＋CloudBase	miniprogram-development	auth-wechat, no-sql-wx-mp-sdk	auth-web, web-development	プロジェクトで実際に CloudBase／wx.cloud を使用しているか
ネイティブアプリ／Flutter／React Native	http-api-cloudbase	auth-tool, postgresql-development	auth-web, cloudbase-document-database-web-sdk, web-development	SDK の境界、OpenAPI、認証方式
Web プロジェクト＋NoSQL データベース	web-development	no-sql-web-sdk, auth-web	relational-database-tool, http-api	ログイン状態とデータベースアクセス権限モデル
CloudBase PostgreSQL／PG	postgresql-development-cloudbase	auth-tool, auth-web-cloudbase, web-development, miniprogram-development, cloud-storage-web, http-api	relational-database-tool, no-sql-web-sdk	PG スキーマ、usernamePassword ログイン、バックエンド／RLS 権限モデル。新規のリレーショナルデータベース開発では PostgreSQL を使用
既存の MySQL（推奨しない）	relational-database-mcp-cloudbase	relational-database-web	postgresql-development, no-sql-web-sdk	環境にすでに MySQL がある場合のみ。新規のリレーショナルデータベース開発では PostgreSQL を使用
クラウド関数	cloud-functions	auth-tool, ai-model-nodejs	cloudrun-development, auth-web	イベント関数か HTTP 関数か、ランタイム、scf_bootstrap
CloudRun バックエンド	cloudrun-development	auth-tool, postgresql-development	cloud-functions	コンテナの境界、Dockerfile、CORS
AI エージェント（智能体开发）	cloudbase-agent	cloud-functions, cloudrun-development	cloud-functions, cloudrun-development	AG-UI プロトコル、scf_bootstrap、SSE ストリーミング
AI モデル呼び出し（大模型调用／文本生成／图片生成／流式对话）	ai-model-web	ai-model-nodejs, ai-model-wechat	cloudbase-agent, cloud-functions, cloudrun-development	まず「呼び出し前に必須の利用資格チェック」を実行します：DescribeActivityInfo（ミニプログラム成長プラン）＋DescribeEnvPostpayPackage（Token Credits リソースパッケージ）
UI 生成	ui-design	web-development, miniprogram-development	cloud-functions	最初に設計仕様を確認
AI モデル（Web）	web-development	ai-model-web, ui-design	ai-model-wechat, http-api	プラットフォームとストリーミングの対話モード
リソースの健全性チェック／トラブルシューティング	ops-inspector	cloud-functions, cloudrun-development	ui-design, spec-workflow	CLS が有効であること。QPS／CPU には queryEnv(action=metrics) を使用する（callCloudApi は絶対に呼び出さない）。ログの対象期間
仕様ワークフロー／アーキテクチャ設計	spec-workflow	cloudbase	web-development, cloud-functions	要件、設計、タスクが確定していること

ルーティングに関する注意事項

• Web 認証の失敗は、通常、フロントエンドのスニペット不足ではなく、プロバイダー設定の見落としが原因です。
• ネイティブアプリの失敗は、通常、HTTP API の知識不足ではなく、Web SDK のパスを使用していることが原因です。
• ミニプログラムの失敗は、wx.cloud を Web 認証／SDK と同様に扱うことが原因です。
• 新規のリレーショナルデータベースには PostgreSQL を使用します。MySQL のスキルは、環境にすでに MySQL インスタンスがある場合にのみ適用されます。
• CloudBase PG の失敗は、NoSQL または MySQL への切り替え、username-password の準備状況の確認漏れ、または app.rdb()／文書化された OpenAPI ではなく生の HTTP を推測して使用することが原因です。
• AI モデルの失敗は、通常、Token Credits／成長プランの不足が原因です。コードを変更する前に DescribeEnvPostpayPackage／DescribeActivityInfo を実行してください。

MCP + CLI の前提条件

現在のセッションでツールが読み込まれている場合は、管理／デプロイに CloudBase MCP を優先して使用してください。セットアップ：references/mcp-setup.md。初回セッション／利用できない場合の手順：references/tooling-fallback.md。

• 推奨インストール方法： npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user。サポートされている --target ID：claude-code、cursor、codex、grok、kimi、github-copilot、vscode。references/mcp-setup.md を参照してください。plugins add が program not found で失敗する場合は、そのファイルに記載されている Git を使わない tarball の方法を使用してください。
• npx mcporter list | grep cloudbase または IDE の MCP パネルで確認してください。npm／npx がない場合は、references/tooling-fallback.md を参照してください（Node LTS をインストールするか、IDE マーケットプレイスの MCP を使用）。MCP がない、または設定後もまだ表示されない場合でも、作業を続行してください。インストール／設定を完了し、次回は再起動すると MCP が利用可能になることをユーザーに伝えて、今すぐ cloudbase-cli ドメインスキルを使って tcb CLI を使用してください。tcb deploy は推奨しないでください。
• 利用可能な場合は、MCP の auth によるデバイスコードログインを優先してください。それ以外の場合は tcb login を使用してください。シークレットをハードコードしないでください。

必要に応じて参照

必要な場合にのみ読み込んでください（この項目を展開しないでください）。

• references/tooling-fallback.md — 初回セッション／ツール不足時の MCP と tcb CLI の判断フロー
• references/site-onboarding.md — サイトの初回オンボーディング：開始／スキップ、永続化、競合の調停、MCP ダウン時のフォールバック
• references/deployment-workflow.md — バックエンド／フロントエンドのデプロイ、manageApps とホスティング、URL／ドキュメントの更新、任意のデプロイ後の Deployment Share の提案（§5）
• references/console-links.md — リソース作成後のコンソールのハッシュパス
• references/scenarios.md — ユーザーのニーズから CloudBase の機能へのマッピング
• references/mcp-setup.md — プラグインのインストール（デフォルトのグローバル設定とターゲット）、IDE MCP／mcporter の設定および認証の例
• references/activation-map.yaml — 正規のルーティング契約のソース

参照インデックス

パッケージに含まれるすべての参照ファイル（スキルのリントで到達可能にするために必須）：

• activation-map.yaml
• console-links.md
• deployment-workflow.md
• mcp-setup.md
• scenarios.md
• site-onboarding.md
• tooling-fallback.md