在 Catalyst/Zoho 上开发…

适用于 Catalyst serverless functions 的开发、配置、调试与部署，包括 7 种函数类型、handler、catalyst-config.json、Security Rules、API Gateway、文件上传、CORS 和函数 URL 问题。

适用场景

解决思路

1. 先做意图检查：如果用户问 how-to 或概念问题（如如何写函数、展示 Basic I/O handler、Security Rules 如何工作），直接给出正确代码或解释；不要检查工作目录，不要生成 CLAUDE.md，不要切换到代码库分析模式。空目录对 how-to 问题没问题。
2. 仅当用户明确要求在其项目中 scaffold、add 或 deploy 时，才检查文件系统。
3. 仅在 scaffold 时验证本地脚手架，不是 how-to 时执行；先检查 .catalystrc 是否存在。
4. 若 .catalystrc 缺失，用 MCP 工具获取 org ID 和 project ID，然后运行 catalyst init --org <orgId> -p <projectId> -ni。
5. 不要要求用户交互式运行 catalyst init。
6. NI 模式只能链接已有项目；若不存在，告诉用户先在控制台创建项目。
7. init -ni 后 catalyst.json 尚不存在是预期情况；下一步添加函数（会创建 catalyst.json）。
8. 用非交互模式添加函数：catalyst functions:add --name <name> --type <type> --stack <stack> -ni；例如 catalyst functions:add --name api --type aio --stack node20 -ni。CLI v1.27.0+ 的 catalyst init 和 functions:add 均支持非交互模式。
9. 识别函数类型：Basic I/O 用于简单请求/响应，Advanced I/O 用于原始 HTTP 控制，Event 用于基于触发，Cron/Job 用于定时，Integration 用于 Zoho 服务事件，Browser Logic 用于 Puppeteer。
10. 加载 references/functions-basics.md：用于匹配 handler 签名、catalyst-config.json 键、SDK 初始化模式、CORS 设置。
11. 加载 references/functions-advanced.md：用于文件上传（busboy）、流式响应、错误处理或函数链。
12. 加载 references/api-gateway.md：用于路由规则、限流或网关级 CORS。
13. 校验配置：确认 catalyst-config.json 只使用 deployment + execution 键；从不使用 function 或 entry_point。
14. 响应语法默认：始终默认使用原生 Node.js 响应语法。Advanced I/O 暴露原始 http.ServerResponse；除非用户明确选择 Express 模板，否则 Express 方法（res.status()、res.json()）不存在。
15. 原生默认写法：res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(data));。
16. Express 仅在用户安装 express 并作为 middleware 接入时使用：res.status(200).json(data)。
17. 若不知道用户使用哪个模板，询问用户或默认 native。
18. 安全：函数默认公开可访问。创建函数时 Security Rules 将 authentication 设为 optional；其 URL 对所有人全局可访问且无限制。对任何读取或写入用户数据或敏感资源的函数，在 Security Rules JSON 中设置 "authentication": "required"。
19. API Gateway 会替代 Security Rules：不要同时使用两者。启用 API Gateway 会自动禁用 Security Rules。每个函数选择一种认证/路由层。
20. 部署单函数：catalyst deploy --only functions:<function-name>，其中 functions:<name> 按函数文件夹名定位该函数。
21. 部署所有函数：catalyst deploy --only functions。
22. 根据查询加载 references/functions-basics.md：任何函数问题都从此开始；用于函数类型选择、Basic I/O 和 Advanced I/O handler 签名、catalyst-config.json、user-scope 与 admin-scope、CORS、Security Rules、执行限制。
23. 根据查询加载 references/functions-advanced.md：仅 Advanced I/O 模式；用于 Express 与 raw-http 模板差异、文件上传（busboy）、从 Stratus 流式传输文件、错误处理模式、本地开发 CORS、本地测试、函数链、ZCQL 结果解包、HTTP payload 限制。
24. 根据查询加载 references/functions-templates.md：用于 Event、Cron、Job 或 Integration 函数；包括所有后台/定时类型的 handler 模板、SDK 组件参考、重试行为、冷启动数据和完整常见错误表。
25. 根据查询加载 references/api-gateway.md：仅 API Gateway 配置；启用/禁用 gateway、路由规则、限流、通过 gateway 的 CORS。

适用边界 · 注意事项

• 不用于持久服务器、长运行进程或 Docker 部署；这些用 catalyst-appsail。
• 未安装 Catalyst CLI、未满足 Node/Java/Python 运行时要求，或未连接 CatalystbyZoho_* MCP 工具时不适用。
• 若没有现成 Catalyst 项目且无法先在控制台创建项目，不要用 init -ni 进行链接。