catalyst-functions

工作原理

意图检查——请先执行：

• 如果用户提出的是操作方法或概念性问题（“如何编写一个函数”“给我展示一个 Basic I/O 处理程序”“Security Rules 如何工作”），请直接给出正确的代码或说明。不要检查工作目录，不要生成 CLAUDE.md，也不要切换到代码库分析模式。目录为空也可以回答操作方法类问题。
• 只有当用户明确要求在其项目中搭建、添加或部署内容时，才检查文件系统。

1. 验证本地脚手架（仅在搭建时执行，操作方法类问题除外）——catalyst init 和 functions:add 均支持非交互模式（CLI v1.27.0+）。 检查 .catalystrc 是否存在。如果不存在，使用 MCP 工具获取组织 ID 和项目 ID，然后运行：

   catalyst init --org <orgId> -p <projectId> -ni
   

   绝不要要求用户以交互方式运行 catalyst init。NI 模式只能关联现有项目——如果不存在项目，请告知用户先在控制台中创建项目。执行 init -ni 后，catalyst.json 尚不存在，这是正常情况。接下来添加函数（此操作会创建 catalyst.json）：

   catalyst functions:add --name <name> --type <type> --stack <stack> -ni
   # e.g. catalyst functions:add --name api --type aio --stack node20 -ni
   

2. 确定函数类型——简单请求/响应使用 Basic I/O；需要原始 HTTP 控制时使用 Advanced I/O；基于触发器的函数使用 Event；定时运行使用 Cron/Job；Zoho 服务事件使用 Integration；Puppeteer 使用 Browser Logic。

3. 加载 references/functions-basics.md——查找匹配的处理程序签名、catalyst-config.json 键、SDK 初始化模式和 CORS 设置。

4. 加载 references/functions-advanced.md——处理文件上传（busboy）、流式响应、错误处理或函数串联时使用。

5. 加载 references/api-gateway.md——处理路由规则、速率限制或网关级 CORS 时使用。

6. 验证配置——确认 catalyst-config.json 只使用 deployment 和 execution 键。绝不要使用 function 或 entry_point。

默认响应语法

始终默认使用原生 Node.js 响应语法。 Advanced I/O 提供原始的 http.ServerResponse——除非用户明确选择 Express 模板，否则不存在 Express 方法（res.status()、res.json()）。

• 原生（默认）：res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(data));
• Express（仅限主动选择）：res.status(200).json(data)——仅当用户已安装 express 并将其配置为中间件时使用

如果不清楚用户使用的是哪种模板，请先询问，或默认使用原生语法。

安全检查清单

• 函数默认可公开访问。 创建函数时，Security Rules 会将 authentication 设为 optional——任何人都可以不受限制地通过 URL 访问该函数。对于任何会读取或写入用户数据或敏感资源的函数，请在 Security Rules JSON 中设置 "authentication": "required"。
• API Gateway 会取代 Security Rules——不要同时使用两者。 启用 API Gateway 会自动禁用 Security Rules。每个函数只能选择一个身份验证/路由层。

触发条件

在以下情况下使用此技能：“编写函数”“catalyst function”“Basic I/O”“Advanced I/O”“Event function”“Cron function”“Browser Logic”、catalyst-config.json、“function handler”“API Gateway”“速率限制”“busboy”“函数中的文件上传”、catalyst deploy --only functions:<function-name>、catalyst functions:add、“函数 CORS”，或任何函数类型或函数配置相关问题。

部署命令说明：

• 使用 catalyst deploy --only functions:<function-name> 部署单个函数（其中 functions:<name> 根据函数的文件夹名称指定目标函数）。
• 使用 catalyst deploy --only functions 一次性部署所有函数。

参考资料

参考资料	在查询涉及以下内容时加载……
references/functions-basics.md	任何函数相关问题都从这里开始。 函数类型选择、基础 I/O 和高级 I/O 处理程序签名、catalyst-config.json、用户范围与管理员范围、CORS、安全规则、执行限制
references/functions-advanced.md	仅适用于高级 I/O 模式。 Express 与原始 HTTP 模板的差异、文件上传（busboy）、从 Stratus 流式传输文件、错误处理模式、本地开发的 CORS、本地测试、函数链式调用、ZCQL 结果解包、HTTP 负载限制
references/functions-templates.md	事件、Cron、Job 或集成函数。 所有后台／计划任务类型的处理程序模板、SDK 组件参考、重试行为、冷启动数据，以及完整的常见错误表
references/api-gateway.md	仅适用于 API Gateway 配置。 启用／停用网关、路由规则、速率限制、通过网关配置 CORS