cloud-functions

兄弟技能（仅限本地）

兄弟 CloudBase 技能与此技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 等本地相对路径。

如果当前环境缺少所引用的兄弟技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要通过 HTTP 将远程技能或协议 Markdown 获取到 Agent 上下文中。

跨领域协议（代码变更或部署前必须遵循）：

• 变更安全协议：../cloudbase-platform/references/protocols/change-safety-protocol.md
• 部署关卡：../cloudbase-platform/references/protocols/deployment-gate.md
• 敏感运行时数据保护：../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md

Cloud Functions 开发

激活约定

以下情况优先使用此技能

• 任务是创建、更新、部署、检查或调试用于承载应用运行时逻辑的 CloudBase Event Function 或 HTTP Function。
• 请求提及函数运行时、函数日志、scf_bootstrap、函数触发器或函数网关暴露。

编写代码前阅读的情况

• 仍需在 Event Function 和 HTTP Function 之间做出选择。
• 任务提及 manageFunctions、queryFunctions、manageGateway 或旧版函数工具名称。
• 任务可能需要将 callCloudApi 用作日志或网关配置的后备方案。
• HTTP Function 将通过 @cloudbase/node-sdk 或 @cloudbase/manager-node 调用 CloudBase 资源 -> 阅读 ./references/http-function-credentials.md。HTTP Function 必须使用显式凭证；不要依赖 Event Function 的无密码运行时路径。

仅限以下例外（默认不要阅读）

• 迁移已使用经典 TCP DB 客户端（DATABASE_URL / Prisma / mysql2 / pg / Redis）的现有应用 -> 通过 ./references.md 阅读 ./references/vpc-and-tcp-database.md。新的业务 CRUD 应优先使用 CloudBase 原生 SDK（app.database() / app.rdb()）或 MCP SQL 工具，而不是 TCP。

此外还需阅读

• 详细的参考资料路由 -> ./references.md
• 身份验证设置或提供方相关的后端工作 -> ../auth-tool-cloudbase/SKILL.md
• CloudBase Integration Center 生成的 WeChat Pay 或 Official Account 函数 -> ../cloudbase-wechat-integration/SKILL.md（官方文档：https://docs.cloudbase.net/integration/introduce.md）
• 函数中的 AI -> ../ai-model-nodejs/SKILL.md
• 长期运行的容器服务或 Agent 运行时 -> ../cloudrun-development/SKILL.md
• 从客户端或脚本调用 CloudBase 官方平台 API -> ../http-api-cloudbase/SKILL.md

不适用的情况

• CloudRun 容器服务。
• Web 身份验证 UI 实现。
• 数据库模式设计或通用数据模型工作。
• CloudBase 官方平台 API 客户端，或仅调用平台端点的原始 HTTP 集成。
• 通过猜测的 API 创建 Integration Center 实例。对于 WeChat Pay 或 Official Account 生成的函数，业务约定请使用 cloudbase-wechat-integration，函数操作才使用此技能。
• CloudBase JS SDK 可直接处理的任务 — 简单的数据读写、排行榜、文件上传、实时查询。编写函数前，应先考虑匹配的 SDK 接口：仅对已确认的 NoSQL 集合使用 db.collection(...).get/add/update，对 CloudBase PG 表使用 app.rdb().from(...)。函数会增加部署复杂度、CORS 配置和 HTTP 网关绑定，而 SDK 可完全避免这些问题。

常见错误 / 注意事项

• 选错函数类型，之后再试图补救。
• 混淆官方 CloudBase API 客户端工作与构建自己的 HTTP 函数。
• 混用事件函数代码结构（exports.main(event, context)）和 HTTP 函数代码结构（在端口 9000 上使用 req / res）。
• 将 HTTP 访问视为 HTTP 函数的实现模式。HTTP 访问是事件函数的网关配置，并非 HTTP 函数的运行时模式。
• 以为 db.collection("name").add(...) 会自动创建缺失的文档数据库集合。创建集合是单独的管理步骤。
• 将静态内容打包进部署包——例如媒体文件、用户上传内容，或更新节奏不同的资源。 每次部署都会上传该软件包，而且函数软件包有严格的大小上限，因此，大型内容或独立更新的内容会拖慢每次部署，还可能导致软件包超出限制。
  • 媒体文件（*.mp4、大尺寸图像、字体）——应放在云存储中，通过 URL 引用，而不是放进软件包。
  • 写入函数本地文件系统的用户上传内容——函数是临时的，且 /tmp 空间很小，也不共享。上传内容应放在云存储中。
  • 打包在函数中的频繁更新的静态资源——每次变更都会触发完整的函数重新部署。将其托管在云存储中，这样只有在代码变更时才需要重新部署函数。
• 忘记运行时在创建后无法更改。
• 将云函数作为 Web 登录问题的首选解决方案。
• 忘记 HTTP 函数必须包含 scf_bootstrap、监听端口 9000，并包含依赖项。
• 以为 HTTP 函数无需显式凭证即可使用 CloudBase SDK。默认的临时凭证路径对 HTTP 函数并不可靠，凭证轮换还可能导致运行中的服务中断。使用 CloudBase 服务 API Key 或腾讯云密钥对来配置 @cloudbase/node-sdk；使用腾讯云密钥对来配置 @cloudbase/manager-node。参见 references/http-function-credentials.md。
• 忘记 HTTP 函数应如何访问。不带凭证的调用会失败并返回 401 MISSING_CREDENTIALS；携带凭证但未获授权的调用会失败并返回 403 EXCEED_AUTHORITY。对于浏览器、游戏或应用客户端，应添加网关路由（manageGateway(action="createRoute", auth: false)），而不是放宽函数安全规则——在 PostgreSQL 环境中，该规则位于环境级的 authz.user.rego 文档中，编辑它会覆盖整个环境的策略。参见 references/http-functions.md。
• 将 InsufficientBalance 调用失败误判为账户问题。 云函数会以 HTTP 410 返回此代码，代码名称看起来像账户余额不足，但实际耗尽的是环境资源点数——它们会先于任何账户余额被扣减，且充值后不会恢复。四种原因（试用点数耗尽 / 套餐点数耗尽 / 套餐已过期 / 账户欠费）需要四种不同的处理方式，只有最后一种需要充值，因此在给出建议前，应通过 manageEnv(action="usage") 和账户余额进行诊断。参见 ../cloud-api-operations/references/recipes/credits-exhaustion.md。
• scf_bootstrap 中的 Node.js 二进制文件路径与函数运行时不匹配（例如使用 /var/lang/node18/bin/node，但设置了 runtime: "Nodejs16.13"）。
• 对于自定义镜像 HTTP 函数：忘记 TCR、CloudApp 构建和 SCF 必须位于同一区域；使用 :latest 而不是唯一标签；或将由请求驱动、监听端口 9000 的镜像模式与监听注入的 PORT 的长驻 CloudRun 容器混淆。
• 以为 MCP 覆盖整个镜像流程。manageFunctions 通过 runtime: "CustomImage" 和 imageConfig 覆盖 SCF 镜像部署（阶段 B），但 CloudApp 自定义构建 → 推送到 TCR（阶段 A）属于原始腾讯云 API 路径——在任何 callCloudApi 回退方案之前，先从官方文档确认操作名称和参数。
• 未遵循变更安全协议（cloudbase-platform/references/protocols/change-safety-protocol.md），就修改代码或配置。
• 未完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查，就公开函数或进行部署。
• 原样返回 req.headers、process.env、event 或 context——网关可能会注入 x-cloudbase-context（base64 编码的临时凭证）。切勿回显该标头，也不要将凭证环境变量转储给客户端。请遵循 ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md。
• 在多个环境中使用不带后缀的层名称（例如 common）。 SCF 的 LayerName 是账户范围内共享的命名空间：相同名称会共用版本序列。创建新层时使用固定格式 {layerName}_{当前envId}（例如 common_cloud1-d9ghadgak3edf6b36）。将完整名称作为 layerName 传入——不要自行添加自动后缀。将 MCP 层的 warnings 视为软性提示（操作仍会成功）。详情：./references/operations-and-config.md。
• 长时间运行的 MCP 镜像部署必须完成整个工作流：使用 manageFunctions 通过 deployFunction 执行实际的 cloud 或 local 部署时，优先使用 wait=false，避免单个 Tool Call 长时间阻塞。如果工具返回了 taskId，在状态为 running 时，不要结束工作流、报告成功或让用户等待。应自动调用 queryFunctions(action="getFunctionDeployStatus", taskId="...")，并根据报告的进度持续轮询，直到状态变为 succeeded 或 failed。只有达到合理的轮询上限后，才能报告部署仍在进行；同时提供 taskId、当前阶段和最新进度。成功时，报告镜像 URI 或构建 ID、函数状态和 Gateway URL。失败时，报告失败阶段、错误代码、请求 ID 和诊断建议。如果状态为 expired，请说明本地任务记录已超出保留期限；云端部署可能仍在运行，因此应调用 getFunctionDetail 确认云端实际状态，而不要将其视为失败。

最简清单

• 在部署或运行时变更前，阅读 Cloud Functions Execution Checklist。
• 判断任务属于 Event Function、HTTP Function，还是实际上属于 CloudRun。
• 将静态内容与动态内容分开：媒体文件、用户上传内容和频繁更新的资源应存放在云存储中，而不是函数包内。
• 编写实现代码前，先在 references.md 中选择详细参考文件。

使用轮询部署 MCP 镜像

对于真正的 cloud 或 local 自定义镜像部署，优先使用：

{
  "action": "deployFunction",
  "dryRun": false,
  "confirm": true,
  "wait": false,
  "deployConfig": {}
}

wait 字段控制当前 MCP 工具调用是否等待部署完成：

• wait=true：等待管理器部署达到终态并返回结果。
• wait=false：立即返回 taskId，同时部署继续在 MCP 后台运行。

当 wait=false 返回 taskId 时，部署工作流尚未完成。自动调用 queryFunctions，并设置 action="getFunctionDeployStatus" 和该 taskId；只要状态为 running，就继续查询，直到状态变为 succeeded 或 failed 才停止。首次后续查询前等待约 5 秒，并根据返回的进度或 nextActions 继续操作，避免频繁轮询。在返回终态之前，不要告诉用户稍后再来询问，也不要暗示部署已成功。expired 状态表示任务超过最长保留期限，已在本地被强制终止——云端部署可能仍在进行，因此应通过 getFunctionDetail 确认实际状态，而不要报告失败。

如果达到合理的轮询次数上限，只报告任务仍在运行，并提供 taskId、当前状态、当前阶段和最新进度。对于终态结果，应报告部署策略、操作、镜像 URI/摘要、构建 ID、函数状态、Gateway URL；如果失败，则报告失败阶段、错误代码、请求 ID 和诊断后续步骤。

个人版 TCR 凭据——绝不要将密码放入工具参数

个人版镜像构建（imageConfig.imageType="personal"，搭配 local / cloud）需要 TCR 推送凭据。应从 MCP 进程环境中读取，而不是从工具参数中读取：

• 如果 MCP 服务 env 块中设置了 TCB_TCR_USERNAME 和 TCB_TCR_PASSWORD，则在请求中不要包含 func.imageConfig.build.registryCredential——MCP 会自动填入凭据，方式与处理 TENCENTCLOUD_SECRETID 相同。
• 绝不要让用户将密码粘贴到聊天中，也绝不要将密码写入工具参数。 参数中的任何内容都会进入模型上下文和工具调用历史记录。
• 如果部署因 CLOUD_REGISTRY_CREDENTIAL_MISSING 或 CLOUD_REGISTRY_CREDENTIAL_INVALID 而失败，请指示用户将这两个变量添加到 MCP 配置的 env 块中，然后重启 MCP 服务。不要通过内联传递凭据来绕过此问题。
• 用户名是腾讯云账户 UIN，本身不属于机密；如有需要，可以显式传入。显式参数按字段优先，因此参数中传入用户名、从环境中读取密码是有效的组合。

了解何时不存在此环境变量通道。 只有本地 stdio MCP 服务的客户端配置公开了自定义 env 块时，此方式才有效。一些 GUI 客户端不会继承 shell 导出的变量；IDE 内嵌的 MCP 服务通常只会从硬编码的允许列表中注入凭据（往往只包含 TENCENTCLOUD_*），导致用户无法设置任意变量。告诉这些用户“在 MCP env 块中设置”是无法执行的指示。应引导他们改用企业版注册表（imageType="enterprise"，该方式会生成短期 TCR 令牌，而不是使用固定密码），或者使用 buildStrategy="image" 并提供已推送的镜像。

企业级构建需要具有 CAM 权限的登录状态

cloud / local 构建使用企业级镜像仓库时，会通过 CAM 获取 TCR 令牌（autoGrant 也会如此）。环境级 API Key 和通过 OAuth 签发的 STS 凭证不携带 CAM 策略，因此这些调用会因 UnauthorizedOperation 而失败。MCP 会在启动实际的企业级构建前检查登录状态，并提前拒绝请求，而不是等到构建中途失败；请将此错误视为路由信号，而非可重试故障：

• 使用账户级 TENCENTCLOUD_SECRETID / TENCENTCLOUD_SECRETKEY 密钥对登录，或
• 切换到 buildStrategy="image"，并部署从其他位置推送的镜像，或
• 使用个人级镜像仓库——其静态密码可直接用于 docker login，无需经过 CAM，因此这是 API Key 用户唯一可用的构建方式。

写作模式一览

• 如果请求涉及 SDK 调用、定时器或事件驱动的工作流，请编写 事件云函数，使用 exports.main = async (event, context) => {}。
• 如果请求涉及 REST API、面向浏览器的端点、SSE 或 WebSocket，请编写 HTTP 云函数，在端口 9000 上使用 req / res。
• 对于 Node.js HTTP 云函数，默认使用原生 http 模块，除非用户明确要求使用 Express、Koa、NestJS 或其他框架。
• 如果 HTTP 云函数需要自定义系统库或任意运行时，但仍应由 SCF 请求驱动并缩容至零，请将其部署为基于 TCR 镜像的 自定义镜像 HTTP 云函数（Runtime: CustomImage）。容器仍监听固定端口 9000。请参阅 ./references/http-functions-custom-image.md。这与 CloudRun 容器不同；CloudRun 容器监听注入的 PORT，并长期运行。
• 有 Dockerfile 的 HTTP 无状态服务可优先考虑 HTTP 云函数，不必上云托管——仅有 Dockerfile 并不意味着要用 CloudRun。如果服务是无状态、由请求驱动的 HTTP 服务，且不涉及长连接、自定义运行时或 VPC 数据库访问，请优先选择 HTTP 云函数（或自定义镜像 HTTP 云函数）——部署更快、成本更低，也无需初始化 CloudRun 环境。只有在需要 WebSocket/SSE 长连接、稳定运行的独立进程、自定义系统依赖项或 VPC 数据库访问时，才选择 CloudRun（../cloudrun-development/SKILL.md）。
• 如果用户提到要为现有事件云函数提供 HTTP 访问，请保留事件云函数的代码结构，并单独添加网关访问。

HTTP Function 编写规范

编写函数代码本身时，请遵循以下规则：

• 不要将 HTTP Function 编写为 exports.main(event, context)。这是 Event Function 的规范。
• 将函数视为必须监听 9000 端口的标准 Web 服务器进程。
• 对于 Node.js，默认优先使用 http.createServer((req, res) => { ... })，以明确运行时规范。
• 使用 Node.js 原生 http 模块时，不要假设存在 Express 风格的辅助方法。req.body、req.query 和 req.params 并不会自动提供。
• 对于 Node.js HTTP Function，请预先选定一种模块系统并保持一致。简单函数默认使用 CommonJS（require(...)，且 package.json 中没有 "type": "module"），除非你明确需要 ES Modules。
• 如果选择 ES Modules（"type": "module" + import ...），不要混用仅限 CommonJS 的全局变量或 API，例如 require(...)、module.exports 或不带路径的 __dirname。在 ESM 中，仅在需要时使用 fileURLToPath(...) 从 import.meta.url 推导文件路径。
• 使用原生 http 模块时，请自行使用 new URL(...) 解析 req.url，从流中收集请求正文，然后再调用 JSON.parse。应明确处理空正文，而不要假设始终存在 JSON。
• 使用 res.writeHead(...) 和 res.end(...) 显式返回响应。对于 JSON API，还应包含 Content-Type，例如 application/json; charset=utf-8。
• 处理 CORS 标头——但首先要确认由谁处理 CORS。 通过 HTTP 网关访问的函数不得自行设置 Access-Control-Allow-Origin：网关已根据环境安全域名允许列表填入该值；如果再设置一个值，就会产生 <origin>,*，浏览器会直接拒绝——所有请求都会失败，并报出看似服务不可用的 CORS 错误。只有函数被网关之外的调用方直接调用时，才设置 CORS 标头：
  • 对 OPTIONS 预检请求返回空的 204
  • 仅为直接的非网关调用方设置 Access-Control-Allow-Origin
  • 根据需要包含 Access-Control-Allow-Methods: GET, POST, OPTIONS
  • 对 JSON 请求包含 Access-Control-Allow-Headers: Content-Type
• 明确处理路由和请求方法。未知路径应返回 404，已知路径不支持的请求方法通常应返回 405。
• 将网关设置和安全规则变更与运行时代码分开处理。它们影响的是访问控制，而不是 HTTP Function 编程模型。
• 如果任务仅是创建 HTTP Function 本身，不要添加 HTTP 访问服务配置。网关路径或自定义域名属于独立的访问层工作；公开调用需求应通过函数安全规则工作流处理（注意：匿名登录默认已禁用）。
• 如果 HTTP Function 通过 @cloudbase/node-sdk 或 @cloudbase/manager-node 调用 CloudBase，请在部署前完成 ./references/http-function-credentials.md 中明确要求的凭据检查。切勿在函数包中硬编码凭据。
• 切勿回显敏感运行时数据。 不要在响应中返回 req.headers、process.env 或 x-cloudbase-context。调试端点必须使用明确的非敏感允许列表。请参阅 ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md。

快速决策表

问题	选择
由 SDK 调用或计时器触发？	Event Function
需要面向浏览器的 HTTP 端点？	HTTP Function
需要 SSE 或 WebSocket 服务？	HTTP Function
需要自定义系统库／任意运行时，但仍由 SCF 请求驱动并支持缩至零？	使用 Runtime: CustomImage 的 HTTP Function（从 TCR 镜像部署）
有 Dockerfile，但属于无状态 HTTP 服务（无长连接／自定义运行时／VPC 数据库）？	HTTP Function（或 Custom Image HTTP Function）——不要选择 CloudRun
需要长期运行的容器运行时或自定义系统环境？	CloudRun
只需要为现有 Event Function 提供 HTTP 访问？	Event Function + 网关访问

如何使用此技能（面向编码 Agent）

1. 先选择正确的运行时模型

   • 事件函数 -> exports.main(event, context)
   • HTTP 函数 -> 在端口 9000 上运行 Web 服务器
   • 如果需求实际上是容器服务，请尽早改用 CloudRun

2. 使用统一后的 MCP 入口

   • 读取 -> queryFunctions、queryGateway
   • 写入 -> manageFunctions、manageGateway
   • 执行操作前先转换旧版名称，而不是照搬原名称

3. 编写代码并部署，不要止步于本地文件

   • 创建函数时使用 manageFunctions(action="createFunction")
   • 更新代码时使用 manageFunctions(action="updateFunctionCode")
   • 更新配置（timeout、memorySize、envVariables）时使用 manageFunctions(action="updateFunctionConfig")
   • 对于自定义镜像 HTTP 函数，调用 manageFunctions(action="createFunction")，并设置 func.runtime="CustomImage" 和 imageConfig（imageUri 需包含标签；企业版 TCR 需设置 registryId）；之后使用 manageFunctions(action="updateFunctionCode") + imageConfig 进行迭代。代码位于镜像中，因此不需要 functionRootPath。参见 ./references/http-functions-custom-image.md。
   • 将 functionRootPath 设为直接包含函数目录的目录（例如 cloudfunctions/ 或 functions/），而不是项目根目录，也不是函数子目录本身
   • 有 MCP 时优先使用 MCP —— 如果当前会话中有这些工具，请使用 manageFunctions 和 queryFunctions
   • 缺少 MCP 时回退到 CLI —— 如果函数工具尚未加载（首次会话／重启前），请配置 MCP 以供下次使用，然后通过 ../cloudbase-cli/SKILL.md 使用 tcb fn deploy（参见指南 tooling-fallback.md）。不要停下来等待重启。
   • 运行时没有 shell 时，不要臆造 CLI —— 如果只有 MCP 且可正常工作，就使用 MCP；如果两者都不可用，请报告这一限制
   • 批量更新（多个函数）时，请对每个函数分别调用 manageFunctions(action="updateFunctionConfig") —— MCP 没有像 CLI 那样的 --all 批量参数
   • 如果 HTTP 函数使用 @cloudbase/node-sdk，优先使用通过 manageAppAuth(action="createApiKey", keyType="api_key") 创建的服务端 API Key，并将其注入为 CLOUDBASE_APIKEY；也支持腾讯云 SecretId／SecretKey
   • 如果 HTTP 函数使用 @cloudbase/manager-node，请注入腾讯云 SecretId／SecretKey；不要声称 CloudBase API Key 可以初始化 Manager SDK
   • 将凭证环境变量与现有函数配置合并，而不是替换整组环境变量

4. 回退时优先查阅文档

   • 如果任务需要回退到 callCloudApi，请先查看该操作的官方文档或知识库条目
   • 调用前确认准确的操作名称和参数约定
   • 不要凭记忆猜测原始云 API 负载

5. 查阅正确的详细参考文档

   • 事件函数详情 -> ./references/event-functions.md
   • HTTP 函数详情 -> ./references/http-functions.md
   • HTTP 函数 CloudBase SDK 凭证 -> ./references/http-function-credentials.md
   • 基于容器镜像的 HTTP 函数（Runtime: CustomImage、TCR 镜像流水线）-> ./references/http-functions-custom-image.md
   • 日志、网关、环境变量、层（{layerName}_{当前envId}）和旧版映射 -> ./references/operations-and-config.md

数据库写入提醒

• 如果函数要写入 CloudBase 文档数据库，请先通过控制台或管理工具创建目标集合。
• db.collection("feedback").add(...) 只会向已存在的集合插入数据；如果 feedback 不存在，它不会自动创建。
• 如果产品需求要求“缺失时创建”，请在首次写入前显式执行集合管理步骤，不要假设运行时写入调用会自动创建集合。

函数类型对比

特性	事件函数	HTTP 函数
主要触发方式	SDK 调用、定时器、事件	HTTP 请求
入口形式	exports.main(event, context)	使用 req / res 的 Web 服务器
端口	无需端口	必须监听 9000
scf_bootstrap	不需要	必需
依赖项	从 package.json 自动安装	必须与函数代码一起打包
适用于	无服务器处理程序、定时任务	API、SSE、WebSocket、面向浏览器的服务

最小代码框架

事件函数 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 函数 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);

如需包含路由、方法检查和错误处理的完整示例，请参阅 ./references/http-functions.md。

cloudfunctions/hello-http/scf_bootstrap

#!/bin/bash
/var/lang/node18/bin/node index.js

scf_bootstrap 二进制文件的路径必须与运行时匹配——请参阅 ./references/http-functions.md 中的完整映射表。

cloudfunctions/hello-http/package.json

{
  "name": "hello-http",
  "version": "1.0.0"
}

推荐工具映射

函数管理

• queryFunctions(action="listFunctions"|"getFunctionDetail")
• manageFunctions(action="createFunction")
• manageFunctions(action="updateFunctionCode")
• manageFunctions(action="updateFunctionConfig")

层（SCF 层）

层的作用范围是账号级，而非环境级。遵循 MCP manageFunctions / queryFunctions 中关于层的指导：

• 命名（新建层时必需）： {layerName}_{当前envId} — 示例：common_cloud1-d9ghadgak3edf6b36。不要在其他环境中重复使用 common 这样的裸名称。
• 创建： 先调用 queryFunctions(action="listLayers") 检查是否重名，再调用 manageFunctions(action="createLayerVersion", layerName="…_{envId}", …)。如果名称中缺少当前 envId，MCP 可能会返回一条软性 warnings 提示；它不会重写名称。
• 读取： queryFunctions(action="listLayers"|"listLayerVersions"|"getLayerVersionDetail"|"listFunctionLayers") — 列表结果为账号级视图，可能包含在其他环境中创建的层。
• 绑定 / 解绑 / 替换： manageFunctions(action="attachLayer"|"detachLayer"|"updateFunctionLayers")
• 删除版本： manageFunctions(action="deleteLayerVersion") — 删除某个版本可能会影响绑定了该版本的所有环境。
• 完整契约和警告语义 → ./references/operations-and-config.md

日志

查询函数日志 —— 使用 queryFunctions 工具：

• queryFunctions(action="listFunctionLogs", functionName="xxx") —— 列出特定函数的执行日志
• queryFunctions(action="getFunctionLogDetail", requestId="xxx") —— 获取一条日志记录的详细信息

queryFunctions 与 queryLogs 的区别：

• queryFunctions 查询单个云函数的执行日志，且需要 functionName
• queryLogs 使用 CLS 查询语法搜索 CLS（跨服务日志聚合）

示例：

// 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")

queryLogs 的 queryString 遵循 CLS 语法（参见 https://cloud.tencent.com/document/api/876/128127）。以下示例仅供参考；请根据查询涉及的具体日志内容进行调整：

• 函数日志：(src:app OR src:system) AND log:"START RequestId"
• 聚合函数请求状态：| 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
• 文档数据库（NoSQL）：module:database
• 文档数据库慢查询事件：module:database AND eventType:(MongoSlowQuery) —— MongoSlowQuery 是文档数据库慢查询事件
• 关系型数据库（MySQL）：module:rdb
• 关系型数据库（MySQL）事件：module:rdb AND eventType:(MysqlFreeze OR MysqlRecover OR MysqlSlowQuery) —— MysqlFreeze = 冻结，MysqlRecover = 恢复，MysqlSlowQuery = 慢查询
• 工作流（审批流）：module:workflow
• 数据模型：module:model
• 用户权限：module:auth
• 大模型追踪日志：module:llm AND logType:llm-tracelog
• 网关访问日志：logType:accesslog
• 应用发布／删除事件：module:app AND eventType:(AppProdPub OR AppProdDel) —— AppProdPub = 应用发布，AppProdDel = 应用删除

如果这些工具不可用，请先阅读 ./references/operations-and-config.md，再考虑使用 callCloudApi 作为备用方案

网关暴露

• queryGateway(action="getRoute") / listRoutes / listCustomDomains
• manageGateway(action="createRoute") —— 对于 HTTP 函数，传入 upstreamResourceType="WEB_SCF"；对于 Event 函数，传入 upstreamResourceType="SCF"。省略 domain，即可将路由绑定到 HTTP 网关的 IsDefault 域名（DomainType=HTTPSERVICE，通常为 *.{region}.app.tcloudbase.com）
• IsDefault 与静态托管 CDN 的区别： 环境通常还会暴露一个独立的 IsDefault STATIC_STORE 域名（*.tcloudbaseapp.com）。省略 domain 不会绑定该静态托管 CDN 条目，而且这也不是 STATIC_STORE 上游绑定（这需要 upstreamResourceType="STATIC_STORE"）。使用 queryGateway(action="listRoutes") 验证，并检查 Domain / DomainType / Path / UpstreamResourceType
• manageGateway(action="updateRoute") / deleteRoute / enableRoute / disableRoute / bindCustomDomain / deleteCustomDomain
• 禁用路由或静态托管默认域名： 优先使用 manageGateway(action="disableRoute", domain=..., path=...)（查找现有路由，并通过 ModifyHTTPServiceRoute 设置 Routes[].Enable=false）。updateRoute 也可以传入 enable=false / route.enable=false。若要关闭 *.tcloudbaseapp.com，请列出路由，找到 STATIC_STORE IsDefault 域名，然后使用该 domain 和通常为 path="/" 的参数调用 disableRoute —— 不要使用 manageHosting，也不要使用 ModifyGatewayRoute
• 工具结果包含 accessUrl / accessUrls 时，优先直接使用它们（自定义网关域名 URL 的排序高于默认域名）
• 不要通过 callCloudApi 调用已弃用的 GWAPI 操作（CreateCloudBaseGWAPI 等）

相关技能

• cloudrun-development -> 容器服务、长时间运行的运行时、Agent 托管
• http-api-cloudbase -> 原始 CloudBase HTTP API 调用模式
• cloudbase-platform -> CloudBase 平台通用决策
• ops-inspector -> AIOps 式检查和跨服务日志搜索

参考索引

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

• 事件函数
• HTTP 函数凭据
• HTTP 函数自定义镜像
• HTTP 函数
• 操作与配置
• VPC 与 TCP 数据库