CloudBase function runtime guide for building, deploying, and debugging your own Event Functions or HTTP Functions. This skill should be used when users need application runtime code on CloudBase, not
1---2name: cloud-functions3description: CloudBase function runtime guide for building, deploying, and debugging your own Event Functions or HTTP…4---56# config/.claude/skills/cloud-functions/SKILL.md
C
SKILL.mdAgent skill
Transport
File
Status
Listed
SKILL.md
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill cloud-functions -a cursor -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
CloudBase function runtime guide for building, deploying, and debugging your own Event Functions or HTTP Functions. This skill should be used when users need application runtime code on CloudBase, not when they are merely calling CloudBase official platform APIs.
Download config/.claude/skills/cloud-functions/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does cloud-functions live?
The publisher keeps it at https://github.com/TencentCloudBase/CloudBase-AI-Toolkit.
Which agents can use cloud-functions?
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
From the publisher
SKILL.md
name
cloud-functions
description
CloudBase function runtime guide for building, deploying, and debugging your own Event Functions or HTTP Functions. This skill should be used when users need application runtime code on CloudBase, not when they are merely calling CloudBase official platform APIs.
version
2.37.5
license
MIT
alwaysApply
false
Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.
Cross-cutting protocols (required before code changes or deployments):
Sensitive Runtime Data Protection: ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md
Cloud Functions Development
Activation Contract
Use this first when
The task is to create, update, deploy, inspect, or debug a CloudBase Event Function or HTTP Function that serves application runtime logic.
The request mentions function runtime, function logs, scf_bootstrap, function triggers, or function gateway exposure.
Read before writing code if
You still need to decide between Event Function and HTTP Function.
The task mentions manageFunctions, queryFunctions, manageGateway, or legacy function-tool names.
The task might require callCloudApi as a fallback for logs or gateway setup.
An HTTP Function will call CloudBase resources through @cloudbase/node-sdk or @cloudbase/manager-node -> read ./references/http-function-credentials.md. HTTP Functions must use explicit credentials; do not rely on the Event Function passwordless runtime path.
Exception only (do not read by default)
Migrating an existing app that already uses classic TCP DB clients (DATABASE_URL / Prisma / mysql2 / pg / Redis) → read ./references/vpc-and-tcp-database.md via . New business CRUD must prefer CloudBase native SDK ( / ) or MCP SQL tools instead of TCP.
./references.md
app.database()
app.rdb()
Then also read
Detailed reference routing -> ./references.md
Auth setup or provider-related backend work -> ../auth-tool-cloudbase/SKILL.md
CloudBase Integration Center generated WeChat Pay or Official Account functions -> ../cloudbase-wechat-integration/SKILL.md (official docs: https://docs.cloudbase.net/integration/introduce.md)
AI in functions -> ../ai-model-nodejs/SKILL.md
Long-lived container services or Agent runtimes -> ../cloudrun-development/SKILL.md
Calling CloudBase official platform APIs from a client or script -> ../http-api-cloudbase/SKILL.md
Do NOT use for
CloudRun container services.
Web authentication UI implementation.
Database-schema design or general data-model work.
CloudBase official platform API clients or raw HTTP integrations that only consume platform endpoints.
Creating Integration Center instances through guessed APIs. For WeChat Pay or Official Account generated functions, use cloudbase-wechat-integration for the business contract and this skill only for function operations.
Tasks that the CloudBase JS SDK can handle directly — simple data reads/writes, leaderboards, file uploads, real-time queries. Reach for the matching SDK surface before writing a function: db.collection(...).get/add/update only for confirmed NoSQL collections, and app.rdb().from(...) for CloudBase PG tables. Functions add deployment complexity, CORS configuration, and HTTP gateway binding that the SDK eliminates entirely.
Common mistakes / gotchas
Picking the wrong function type and trying to compensate later.
Confusing official CloudBase API client work with building your own HTTP function.
Mixing Event Function code shape (exports.main(event, context)) with HTTP Function code shape (req / res on port 9000).
Treating HTTP Access as the implementation model for HTTP Functions. HTTP Access is a gateway configuration for Event Functions, not the HTTP Function runtime model.
Assuming db.collection("name").add(...) will create a missing document-database collection automatically. Collection creation is a separate management step.
Baking static content into the deployment package — media files, user uploads, or assets that change on their own cadence. The package is uploaded on every deploy and a function package has a hard size ceiling, so large or independently-changing content makes every deploy slower and can push the package over the limit.
Media files (*.mp4, large images, fonts) — go to cloud storage, referenced by URL, not into the package.
User uploads written to the function's local filesystem — the function is ephemeral and /tmp is small and not shared. Uploads go to cloud storage.
Frequently-updated static resources bundled in — every change forces a full function redeploy. Serve them from cloud storage so the function only redeploys when the code changes.
Forgetting that runtime cannot be changed after creation.
Using cloud functions as the first answer for Web login.
Forgetting that HTTP Functions must ship scf_bootstrap, listen on port 9000, and include dependencies.
Assuming an HTTP Function can use CloudBase SDKs without explicit credentials. The default temporary credential path is not reliable for HTTP Functions and credential rotation can break a running service. Use a CloudBase server API Key or Tencent Cloud key pair for @cloudbase/node-sdk; use a Tencent Cloud key pair for @cloudbase/manager-node. See references/http-function-credentials.md.
Forgetting how an HTTP Function is meant to be reached. A call with no credential fails 401 MISSING_CREDENTIALS; a call that carries one but is not allowed fails 403 EXCEED_AUTHORITY. For browser, game or app clients, add a gateway route (manageGateway(action="createRoute", auth: false)) instead of widening the function security rule — in PostgreSQL environments that rule lives in an environment-wide authz.user.rego document, so editing it overwrites the policy for the whole environment. See references/http-functions.md.
Reading an InsufficientBalance invoke failure as an account problem. A cloud function answers HTTP 410 with this code and the code reads as a short account balance, but what runs out is the environment's resource points — drawn down before any account balance and not restored by a top-up. The four causes (trial points exhausted / plan points exhausted / plan expired / account in arrears) need four different answers, only the last of which involves topping up, so diagnose with manageEnv(action="usage") plus the account balance before advising. See ../cloud-api-operations/references/recipes/credits-exhaustion.md.
Mismatching the scf_bootstrap Node.js binary path with the function runtime (e.g. using /var/lang/node18/bin/node but setting runtime: "Nodejs16.13").
For Custom Image HTTP Functions: forgetting that TCR, the CloudApp build, and SCF must be in the same region; using :latest instead of a unique tag; or confusing the request-driven port-9000 image model with a long-lived CloudRun container that listens on the injected PORT.
Assuming MCP covers the whole image pipeline. manageFunctions covers SCF image deploy (Stage B) via runtime: "CustomImage" + imageConfig, but the CloudApp custom build → TCR push (Stage A) is a raw Tencent Cloud API path — confirm action names and parameters from official docs before any callCloudApi fallback.
Making code or configuration changes without first following the Change Safety Protocol (cloudbase-platform/references/protocols/change-safety-protocol.md).
Exposing functions publicly or deploying without first completing the checks in cloudbase-platform/references/protocols/deployment-gate.md.
Returning req.headers, process.env, event, or context wholesale — gateways may inject x-cloudbase-context (base64 temporary credentials). Never echo that header or dump credential env vars to clients. Follow ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md.
Using a bare layer name (e.g. common) across environments. SCF LayerName is an account-scoped shared namespace: same name → shared version sequence. Create new layers with fixed format {layerName}_{当前envId} (e.g. common_cloud1-d9ghadgak3edf6b36). Pass the full name as layerName — do not invent automatic suffixes. Treat MCP layer warnings as soft advisories (operation still succeeds). Details: ./references/operations-and-config.md.
Long-running MCP image deployments must complete the full workflow: When using manageFunctions with deployFunction for a real cloud or local deployment, prefer wait=false to avoid blocking a single Tool Call for an extended period. If the tool returns a taskId, do not end the workflow, report success, or ask the user to wait while the status is running. Automatically call queryFunctions(action="getFunctionDeployStatus", taskId="...") and continue polling according to the reported progress until the status becomes succeeded or failed. Only after reaching a reasonable polling limit may you report that the deployment is still in progress; include the taskId, current stage, and latest progress. On success, report the image URI or build ID, function status, and Gateway URL. On failure, report the failed stage, error code, request ID, and diagnostic guidance. If the status is expired, explain that the local task record exceeded its retention window; the cloud deployment may still be running, so call getFunctionDetail to confirm the actual cloud-side status instead of treating it as a failure.
Passing a self-managed CAM role as the execution role to "reduce the function's permissions". A custom role does not make a function read less data — collection security rules do that (managePermissions action updateResourcePermission, with permission="CUSTOM" and a securityRule). It also commonly leaves the function Active but with no logs: delivery to the managed log topic stays empty, and widening the role's log-write resource to * does not change it. Always verify with queryFunctions(action="listFunctionLogs") after creating; if logs are missing, bind a user-owned CLS topic instead. Only integration / platform-tier multi-tenant isolation justifies a custom role — read ./references/custom-execution-role.md before taking that path. Creating such a function does force you onto a raw API path that cannot report failure synchronously, but updating it does not: manageFunctions(action="updateFunctionConfig") reuses the function's existing role, so keep using it for config changes. What that call cannot do on 2.36.2 and earlier is keep the SDK from attaching the environment's log pair — a role without log-write access makes even a plain env-var change fail with the same InvalidParameter.Cls.
Reading InvalidParameter.Cls: ClsLogSetId & ClsTopicId not matched as "the logset ID is wrong". That code is a catch-all. It also fires when the execution role lacks CLS permissions, when the environment's stored log pair no longer resolves to live resources, and when the caller passed another environment's IDs. Read StatusReasons in full — it can hold several entries at once — and compare DescribeEnvs → LogServices to see whether LogsetName / TopicName carry this environment's ID. Do not fix only one direction: changing IDs does nothing when the real cause is role permissions, and adding permissions does nothing when the pair is genuinely mismatched.
The wait field controls whether the current MCP Tool call waits for the complete deployment:
wait=true: wait for the manager deployment to reach a terminal result and return it.
wait=false: return a taskId promptly while the deployment continues in the MCP background.
When wait=false returns a taskId, the deployment workflow is not complete. Automatically call queryFunctions with action="getFunctionDeployStatus" and that taskId; continue while the status is running, then stop only at succeeded or failed. Wait about 5 seconds before the first follow-up query and use the returned progress/nextActions to continue without aggressive polling. Do not tell the user to ask again or imply success before a terminal status is returned. An expired status means the task exceeded the maximum retention window and was force-terminated locally — the cloud deployment may still be in progress, so confirm the real state with getFunctionDetail instead of reporting failure.
If a reasonable polling limit is reached, report only that the task is still running, including the taskId, current status, current stage, and latest progress. For a terminal result, report the deployment strategy, action, image URI/digest, build ID, function status, Gateway URL, or the failed stage, error code, request ID, and diagnostic next step.
Personal-tier TCR credentials — never put the password in tool arguments
Personal-tier image builds (imageConfig.imageType="personal" with local / cloud) need a TCR push credential. Read it from the MCP process environment, not from tool arguments:
Leave func.imageConfig.build.registryCredentialout of the request when TCB_TCR_USERNAME and TCB_TCR_PASSWORD are set in the MCP server env block — the MCP fills them in automatically, the same way TENCENTCLOUD_SECRETID works.
Never ask the user to paste the password into chat, and never write it into tool arguments. Anything placed in arguments enters the model context and the tool-call history.
If deployment fails with CLOUD_REGISTRY_CREDENTIAL_MISSING or CLOUD_REGISTRY_CREDENTIAL_INVALID, instruct the user to add these two variables to the env block of their MCP configuration and restart the MCP server. Do not work around it by passing the credential inline.
The username is the Tencent Cloud account UIN and is not itself a secret; it may be passed explicitly if needed. Explicit arguments take precedence per field, so username-in-argument plus password-from-environment is a valid combination.
Know when that environment channel does not exist. It works only for a local stdio MCP server whose client configuration exposes a custom env block. Some GUI clients do not inherit shell exports, and IDE-embedded MCP servers usually inject credentials from a hard-coded allowlist (often only TENCENTCLOUD_*), leaving the user no way to set arbitrary variables. Telling those users to "set it in the MCP env block" is an instruction they cannot act on. Route them to an enterprise registry (imageType="enterprise", which mints a short-lived TCR token instead of using a fixed password) or to buildStrategy="image" with an already-pushed image.
Enterprise-tier builds require a login state with CAM permission
cloud / local builds against an enterprise registry mint a TCR token through CAM (as does autoGrant). Environment-level API Keys and OAuth-issued STS credentials carry no CAM policy, so those calls fail with UnauthorizedOperation. The MCP probes the login state before starting a real enterprise build and refuses up front rather than failing midway; treat that error as a routing signal, not a retryable fault:
Sign in with an account-level TENCENTCLOUD_SECRETID / TENCENTCLOUD_SECRETKEY pair, or
Switch to buildStrategy="image" and deploy an image that was pushed elsewhere, or
Use a personal-tier registry — its static password goes straight to docker login without touching CAM, which makes it the one build path that does work for API Key users.
Writing mode at a glance
If the request is for SDK calls, timers, or event-driven workflows, write an Event Function with exports.main = async (event, context) => {}.
If the request is for REST APIs, browser-facing endpoints, SSE, or WebSocket, write an HTTP Function with req / res on port 9000.
For Node.js HTTP Functions, default to the native http module unless the user explicitly asks for Express, Koa, NestJS, or another framework.
If the HTTP Function needs custom system libraries or an arbitrary runtime but should still be SCF request-driven and scale to zero, deploy it as a Custom Image HTTP Function (Runtime: CustomImage) from a TCR image. The container still listens on the fixed port 9000. See ./references/http-functions-custom-image.md. This is distinct from a CloudRun container, which listens on the injected PORT and runs long-lived.
有 Dockerfile 的 HTTP 无状态服务可优先考虑 HTTP 云函数，不必上云托管 — a Dockerfile alone does not mean CloudRun. If the service is stateless, request-driven HTTP without long connections / custom runtime / VPC database access, prefer an HTTP Function (or Custom Image HTTP Function) — faster to deploy, cheaper, and no CloudRun environment initialization needed. Route to CloudRun (../cloudrun-development/SKILL.md) only for WebSocket/SSE long connections, stable independent processes, custom system dependencies, or VPC DB access.
If the user mentions HTTP access for an existing Event Function, keep the Event Function code shape and add gateway access separately.
HTTP Function authoring contract
Use these rules whenever you are writing the function code itself:
Do not write an HTTP Function as exports.main(event, context). That is the Event Function contract.
Treat the function as a standard web server process that must listen on port 9000.
With Node.js, prefer http.createServer((req, res) => { ... }) by default so the runtime contract stays explicit.
With the Node.js native http module, do not assume Express-style helpers exist. req.body, req.query, and req.params are not provided for you.
For Node.js HTTP Functions, choose one module system up front and keep it consistent. Default to CommonJS for simple functions (require(...), no "type": "module" in package.json) unless you explicitly want ES Modules.
If you do choose ES Modules ("type": "module" + import ...), do not mix in CommonJS-only globals or APIs such as require(...), module.exports, or bare __dirname. In ESM, derive file paths from import.meta.url with fileURLToPath(...) only when needed.
With the native http module, parse req.url yourself with new URL(...), collect the request body from the stream, and only then call JSON.parse. Empty bodies should be handled explicitly instead of assuming JSON is always present.
Return responses explicitly with res.writeHead(...) and res.end(...), including Content-Type such as application/json; charset=utf-8 for JSON APIs.
Handle CORS headers — but first check who terminates CORS. A function reached through the HTTP gateway must not set Access-Control-Allow-Origin itself: the gateway already fills it from the environment security-domain allowlist, and a second value yields <origin>,*, which browsers reject outright — every request fails with a CORS error that looks like the service is down. Only set CORS headers when the function is called directly, outside the gateway:
Respond to OPTIONS preflight with an empty 204
Include Access-Control-Allow-Origin only for direct, non-gateway callers
Include Access-Control-Allow-Methods: GET, POST, OPTIONS as needed
Include Access-Control-Allow-Headers: Content-Type for JSON requests
Keep routing and method handling explicit. Unknown paths should return 404, and known paths with unsupported methods should normally return 405.
Keep gateway setup and security-rule changes separate from the runtime code. They affect access, not the HTTP Function programming model.
Do not add HTTP access service configuration when the task is only to create an HTTP Function itself. Gateway paths or custom domains are separate access-layer work; public invocation requirements should be handled through the function security rule workflow (note: anonymous login is disabled by default).
If the HTTP Function calls CloudBase through @cloudbase/node-sdk or @cloudbase/manager-node, complete the explicit credential gate in ./references/http-function-credentials.md before deployment. Never hardcode credentials in the function package.
Never echo sensitive runtime data. Do not return req.headers, process.env, or x-cloudbase-context in responses. Debug endpoints must use an explicit non-sensitive allowlist. See ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md.
Quick decision table
Question
Choose
Triggered by SDK calls or timers?
Event Function
Needs browser-facing HTTP endpoint?
HTTP Function
Needs SSE or WebSocket service?
HTTP Function
Needs custom system libraries / arbitrary runtime, but still SCF request-driven + scale-to-zero?
HTTP Function with Runtime: CustomImage (deploy from a TCR image)
Has a Dockerfile but is a stateless HTTP service (no long connections / custom runtime / VPC DB)?
HTTP Function (or Custom Image HTTP Function) — not CloudRun
Needs long-lived container runtime or custom system environment?
CloudRun
Only needs HTTP access for an existing Event Function?
Event Function + gateway access
How to use this skill (for a coding agent)
Choose the correct runtime model first
Event Function -> exports.main(event, context)
HTTP Function -> web server on port 9000
If the requirement is really a container service, reroute to CloudRun early
Use the converged MCP entrances
Reads -> queryFunctions, queryGateway
Writes -> manageFunctions, manageGateway
Translate legacy names before acting rather than copying them literally
Write code and deploy, do not stop at local files
Use manageFunctions(action="createFunction") for creation
Use manageFunctions(action="updateFunctionCode") for code updates
Use manageFunctions(action="updateFunctionConfig") for config updates (timeout, memorySize, envVariables)
For a Custom Image HTTP Function, call manageFunctions(action="createFunction") with func.runtime="CustomImage" and imageConfig (imageUri with tag; registryId for enterprise TCR); iterate later with manageFunctions(action="updateFunctionCode") + imageConfig. No functionRootPath is needed because the code lives in the image. See ./references/http-functions-custom-image.md.
Keep functionRootPath as the directory that directly contains function folders (e.g., cloudfunctions/ or functions/), NOT the project root and NOT the function subdirectory itself
Prefer MCP when available — use manageFunctions and queryFunctions when those tools are in this session
CLI fallback when MCP is missing — if function tools are not loaded (first session / pre-restart), configure MCP for next time, then use tcb fn deploy via ../cloudbase-cli/SKILL.md (see guideline tooling-fallback.md). Do not stall waiting for restart.
Do NOT invent CLI when the runtime has no shell — if only MCP exists and it works, stay on MCP; if neither works, report the gap
For batch updates (multiple functions), call manageFunctions(action="updateFunctionConfig") individually for each function — MCP does not have a --all batch parameter like CLI
If an HTTP Function uses @cloudbase/node-sdk, prefer a server API Key created with manageAppAuth(action="createApiKey", keyType="api_key") and inject it as CLOUDBASE_APIKEY; Tencent Cloud SecretId / SecretKey is also supported
If an HTTP Function uses @cloudbase/manager-node, inject Tencent Cloud SecretId / SecretKey; do not claim that a CloudBase API Key initializes the Manager SDK
Merge credential environment variables with the existing function configuration instead of replacing the whole environment-variable set
Prefer doc-first fallbacks
If a task falls back to callCloudApi, first check the official docs or knowledge-base entry for that action
Confirm the exact action name and parameter contract before calling it
Do not guess raw cloud API payloads from memory
Read the right detailed reference
Event Function details -> ./references/event-functions.md
HTTP Function details -> ./references/http-functions.md
HTTP Function CloudBase SDK credentials -> ./references/http-function-credentials.md
HTTP Function from a container image (Runtime: CustomImage, TCR image pipeline) -> ./references/http-functions-custom-image.md
If a function will write to CloudBase document database, create the target collection first through console or management tooling.
db.collection("feedback").add(...) only inserts into an existing collection; it does not auto-create feedback when absent.
If the product requirement says "create when missing", implement that as an explicit collection-management step before the first write instead of assuming the runtime write call will provision it.
Function types comparison
Feature
Event Function
HTTP Function
Primary trigger
SDK call, timer, event
HTTP request
Entry shape
exports.main(event, context)
web server with req / res
Port
No port
Must listen on 9000
scf_bootstrap
Not required
Required
Dependencies
Auto-installed from package.json
Must be packaged with function code
Best for
serverless handlers, scheduled jobs
APIs, SSE, WebSocket, browser-facing services
Minimal code skeletons
Event Function hello world
cloudfunctions/hello-event/index.js
exports.main = async (event, context) => {
// Do not return event/context/process.env — they may contain platform secrets.
const name = typeof event?.name === "string" ? event.name : "world";
return {
ok: true,
message: `hello ${name} from event function`,
};
};
cloudfunctions/hello-event/package.json
{
"name": "hello-event",
"version": "1.0.0"
}
HTTP Function hello world
cloudfunctions/hello-http/index.js
const http = require("http");
const { URL } = require("url");
// CORS: leave this empty when the function is reached through the HTTP gateway.
// The gateway already fills Access-Control-Allow-Origin from the environment
// security-domain allowlist; adding a second value makes the header illegal
// ('<origin>,*') and browsers block every request. Only set CORS headers here
// when the function is called directly, outside the gateway.
const CORS_HEADERS = {};
function sendJson(res, statusCode, data) {
res.writeHead(statusCode, {
"Content-Type": "application/json; charset=utf-8",
...CORS_HEADERS,
});
res.end(JSON.stringify(data));
}
function sendOptions(res) {
res.writeHead(204, CORS_HEADERS);
res.end();
}
function readJsonBody(req) {
return new Promise((resolve, reject) => {
let raw = "";
req.on("data", (chunk) => { raw += chunk; });
req.on("end", () => {
if (!raw) { resolve({}); return; }
try { resolve(JSON.parse(raw)); } catch (e) { resolve({}); }
});
req.on("error", reject);
});
}
const server = http.createServer(async (req, res) => {
// Handle CORS preflight
if (req.method === "OPTIONS") {
return sendOptions(res);
}
const url = new URL(req.url || "/", "http://127.0.0.1");
if (req.method === "GET" && url.pathname === "/") {
sendJson(res, 200, { ok: true, message: "hello from http function" });
} else if (req.method === "POST" && url.pathname === "/") {
const body = await readJsonBody(req);
sendJson(res, 200, { received: body });
} else {
sendJson(res, 404, { error: "Not Found" });
}
});
server.listen(9000);
For a more complete example with routing, method checks, and error handling, see ./references/http-functions.md.
cloudfunctions/hello-http/scf_bootstrap
#!/bin/bash
/var/lang/node18/bin/node index.js
The scf_bootstrap binary path must match the runtime — see the full mapping table in ./references/http-functions.md.
cloudfunctions/hello-http/package.json
{
"name": "hello-http",
"version": "1.0.0"
}
Preferred tool map
Function management
Create and update functions through manageFunctions, not through callCloudApi:
Why this is a rule and not a preference.manageFunctions owns the execution role and the log binding, and it re-checks the resulting Status after a config or code change — a failure surfaces with its real StatusReasons instead of a bare success.
Calling tcb:CreateFunction / tcb:UpdateFunctionCode / tcb:UpdateFunctionConfig directly is an asynchronous path: the SCF-level failure is carried in SCFErrorCode, and that field can be an empty string even when the function ends up in CreateFailed. The synchronous response then looks like success. Callers then "fix" parameters that were never wrong and end up in a delete-recreate loop.
Exception: an integration / platform-tier environment that must give each tenant its own execution role. Only then use callCloudApi, and still poll DescribeFunctions for Status yourself. See references/custom-execution-role.md before going down that path — it has a price.
Layers (SCF Layer)
Layers are account-scoped, not env-scoped. Align with MCP manageFunctions / queryFunctions layer guidance:
Naming (required for new layers):{layerName}_{当前envId} — example common_cloud1-d9ghadgak3edf6b36. Do not reuse a bare name like common in another env.
Create:manageFunctions(action="createLayerVersion", layerName="…_{envId}", …) after queryFunctions(action="listLayers") to check duplicates. MCP may return a soft warnings entry if the name lacks the current envId; it does not rewrite the name.
Read:queryFunctions(action="listLayers"|"listLayerVersions"|"getLayerVersionDetail"|"listFunctionLayers") — list results are an account-level view and may include layers created in other envs.
Delete version:manageFunctions(action="deleteLayerVersion") — deleting a version can affect every env that binds that version.
Full contract and warning semantics → ./references/operations-and-config.md
Logs
Query function logs — use the queryFunctions tool:
queryFunctions(action="listFunctionLogs", functionName="xxx") — list execution logs of a specific function
queryFunctions(action="getFunctionLogDetail", requestId="xxx") — fetch the detail of one log entry
queryFunctions vs queryLogs:
queryFunctions queries execution logs of a single cloud function and requires functionName
queryLogs searches CLS (cross-service log aggregation) using CLS query syntax
Examples:
// List recent logs for cloud function "my-function"
queryFunctions(action="listFunctionLogs", functionName="my-function", limit=10)
// Inspect the log detail for a specific request id
queryFunctions(action="getFunctionLogDetail", requestId="abc-123")
// Cross-service error search via CLS
queryLogs(action="searchLogs", queryString='(src:app OR src:system) AND log:"ERROR"', service="tcb")
Function logs: (src:app OR src:system) AND log:"START RequestId"
Aggregated function request status: | select request_id, max(status_code) as status where ((request_id='xxxx' AND retry_num=0) AND retry_num=0) AND status_code!=202 group by request_id, retry_num
Document database (NoSQL): module:database
Document database slow-query events: module:database AND eventType:(MongoSlowQuery) — MongoSlowQuery is the document-database slow-query event
Relational database (MySQL): module:rdb
Relational database (MySQL) events: module:rdb AND eventType:(MysqlFreeze OR MysqlRecover OR MysqlSlowQuery) — MysqlFreeze = freeze, MysqlRecover = recover, MysqlSlowQuery = slow query
Workflow (approval flow): module:workflow
Data model: module:model
User permissions: module:auth
LLM trace logs: module:llm AND logType:llm-tracelog
Gateway access logs: logType:accesslog
App publish / delete events: module:app AND eventType:(AppProdPub OR AppProdDel) — AppProdPub = app publish, AppProdDel = app delete
If these are unavailable, read ./references/operations-and-config.md before any callCloudApi fallback
manageGateway(action="createRoute") — for HTTP functions pass upstreamResourceType="WEB_SCF"; for Event functions pass upstreamResourceType="SCF". Omit domain to attach the route on the HTTP gateway IsDefault domain (DomainType=HTTPSERVICE, typically *.{region}.app.tcloudbase.com)
IsDefault vs static hosting CDN: environments often also expose a separate IsDefault STATIC_STORE domain (*.tcloudbaseapp.com). Omitting domain does not bind that static-hosting CDN entry, and it is not a STATIC_STORE upstream binding (that requires upstreamResourceType="STATIC_STORE"). Verify with queryGateway(action="listRoutes") and check Domain / DomainType / Path / UpstreamResourceType
Disable a route or the static hosting default domain: prefer manageGateway(action="disableRoute", domain=..., path=...) (looks up the existing route, sets Routes[].Enable=false via ModifyHTTPServiceRoute). updateRoute may also pass enable=false / route.enable=false. To close *.tcloudbaseapp.com, list routes, take the STATIC_STORE IsDefault domain, then disableRoute with that domain and usually path="/" — not manageHosting, and not ModifyGatewayRoute
When tool results include accessUrl / accessUrls, prefer them directly (gateway custom-domain URLs are ranked before default domains)
Do not call deprecated GWAPI actions via callCloudApi (CreateCloudBaseGWAPI, etc.)