在 Zoho Catalyst 无服务器平台上开发应用时…

面向 Zoho Catalyst 全栈无服务器平台（Functions、AppSail、Data Store、Stratus、Slate 等）的编码与基础设施管理，提供技能路由、MCP 优先、非交互式 CLI 与常见陷阱规避的完整做法。

适用场景

解决思路

1. 优先使用 MCP 而非询问用户：若存在 `CatalystbyZoho_*` 工具就用它们，绝不让用户从控制台复制 ID。
2. 默认面向 Development 环境，除非用户明确说 "production" 或 "deploy to prod"。
3. 当用户说 "build an app"、"create an app"、"make a simple app" 且未指定仅后端时，默认输出 Slate 前端 + Advanced I/O function 后端；不要只建一个 function 就当作 app。若意图明显是仅后端（如 "build an API"、"write a function"），则跳过 Slate。
4. 简单 HTTP 场景优先用 Functions 而非 AppSail：Functions 按调用计费更便宜、部署更简单、无需管理基础设施；仅当确实需要常驻进程或自定义运行时时才用 AppSail。
5. 构建任何新基础设施（functions、AppSail、Stratus 桶）前先展示成本：加载 `catalyst-pricing` 并给出简要估算；多数小项目在免费额度内，属实时要说明。
6. 推荐当前服务而非已弃用服务：File Store → Stratus，Event Listeners → Signals，Cron → Job Scheduling；生成的代码或配置中绝不出现已弃用名称。
7. 在区域限制生效前预警：Circuits 和 Integration Functions 在多数数据中心不可用，建议前先检查用户 DC。
8. Pre-flight 检查：确认 `.catalystrc` 和 `catalyst.json` 存在；若缺失，用 MCP 获取 org/project ID 并运行 `catalyst init --org <orgId> -p <projectId> -ni`；绝不使用交互式 `catalyst init`。
9. MCP 检查：查找 `CatalystbyZoho_*` 工具；若可用，用 MCP 获取 org/project ID 而非询问用户。
10. 路由：将查询匹配到路由表中最具体的服务。
11. 惰性加载：只读取当前步骤所需的单个参考文件，不要预先加载多个技能；对 "build an app" 请求：(a) 除非用户说仅后端，否则假定 Slate 前端 + AIO function，(b) 先简要勾勒架构并与用户确认再构建，(c) 写每部分时按服务逐个加载参考文件——前端用 `catalyst-slate`，后端用 `catalyst-functions`。
12. 成本检查：仅当用户明确询问成本，或方案包含 AppSail、Stratus 等付费层服务时才加载 `catalyst-pricing`；基础 Functions + DataStore 项目可跳过（大概率免费额度内）。
13. 回答：使用用户所用平台（Node.js、Python、Java、Web 或 Mobile）提供代码示例。
14. 触发条件：查询含 Catalyst、zcatalyst、AppSail、Data Store、ZCQL、Cache、Stratus、Slate、NoSQL、Zia Services、QuickML、API Gateway、Connections、Zoho MCP、CatalystbyZoho、`catalyst init`、`catalyst deploy`、`catalyst serve`、`zcatalyst-sdk-node`、`catalyst-config.json`、Catalyst pricing、"build on Zoho's platform" 或 "deploy to Catalyst" 时使用本技能；除非目标是 Catalyst，否则不要用于通用 Zoho CRM 问题。
15. Pre-flight 门禁（仅项目变更任务）：先做 MCP 检查——若存在 `CatalystbyZoho_*` 工具，用 MCP 获取 org/project ID，绝不要求用户从控制台复制 ID。
16. 正确调用 MCP 工具：1) `ZohoMCP_getSchema` 接收 `query_params` 而非 `body`，例如 `ZohoMCP_getSchema({ query_params: { tool_name: "CatalystbyZoho_List_All_Projects" } })`；2) 对任何 `CatalystbyZoho_*` 工具都先调用 `ZohoMCP_getSchema`，绝不猜测参数形状，许多工具需要 `path_variables`（如 `project_id`），不看 schema 不可见；3) `ZohoMCP_executeTool` 接收 `body`，形状为 `{ tool_name, arguments: { path_variables, headers, body } }`；4) 无必需路径变量的工具（如 `List_All_Organizations`、`List_All_Projects`）可用 `arguments: {}` 调用。
17. 若不存在 MCP 工具且任务会创建资源、写文件、部署或读取项目 ID——硬停止：不写任何代码、不创建任何文件，告知用户需先连接 Zoho MCP（加载 `catalyst-zoho-mcp` 技能，一分钟内完成），在 `CatalystbyZoho_*` 工具可见前不得继续。
18. 该门禁仅适用于写 Catalyst 项目文件、部署、读取项目/环境 ID 或执行 MCP 项目操作的任务；信息类问题（定价、架构建议、服务选型、"what is Catalyst?"、安装帮助、SDK 用法或任何无需已初始化项目的问题）跳过门禁。
19. 对项目变更任务：验证工作目录中存在 `.catalystrc` 和 `catalyst.json`；若缺失，用 MCP 工具获取 org ID 和 project ID，然后运行 `catalyst init --org <orgId> -p <projectId> -ni`；绝不让用户交互式运行 `catalyst init`，绝不自行创建 `.catalystrc` 或 `catalyst.json`——必须由 CLI 生成。
20. 注意 NI 模式只能链接已存在的项目；若尚无项目，告知用户在 Catalyst 控制台创建后再回来，届时用 `catalyst init -ni` 链接。
21. 服务速览：Functions 为无服务器函数（Basic I/O、Advanced I/O、Event、Cron、Job、Integration、Browser Logic，按调用计费）；AppSail 为长驻 Web 应用 PaaS（Node.js、Java、Python 托管运行时或任意 Docker 容器）；Data Store 为关系表（行+列、外键），用 ZCQL 或 SDK 查询；Stratus 为对象/文件存储（类似 S3，桶/文件夹/对象，单对象最大 250 GB）；Slate 为前端托管（类似 Vercel，支持 React、Next.js、Vue、Angular、Svelte、Preact、Astro、SolidJS、静态 HTML）；Cache 为内存键值存储（分段，TTL 以小时计，最大 48 小时）；NoSQL 为灵活 schema 文档存储（无固定列，适合非结构化/多态数据）；Authentication 为内置用户注册/登录（ZAID）及第三方 API 的 OAuth Connections；SmartBrowz 为无头浏览器自动化、PDF/截图生成、Browser Logic 函数、Browser Grid（并行浏览器）和 Dataverse（网页抓取）；Zia Services 为预训练 AI/ML（OCR、人脸分析、文本分析、对象检测、条码、内容审核）；QuickML 为 AutoML（用自有数据训练模型，无需写 ML 代码，EU/AU/IN/JP/SA/CA 不可用）；Circuits 为无服务器工作流编排（步骤函数，EU/AU/IN/JP/SA/CA 不可用）；Signals 为事件驱动触发器/发布订阅（替代旧 Event Listeners）；Job Scheduling 为作业池+即时作业+cron（调度/后台执行 Job 函数、Webhooks、Circuits、AppSail，替代旧 Cron）；Zoho MCP 为 AI 工具集成（让 AI 代理通过 `CatalystbyZoho_*` 工具管理 Catalyst 基础设施）；ZCQL 为 Data Store 的类 SQL 查询语言（SELECT/INSERT/UPDATE/DELETE，单次 SELECT 最多 300 行）；ZAID 为 Zoho Account ID，内置认证身份层，配合 Web SDK 做用户认证流程。
22. 按路由表加载对应技能：服务选型/架构决策/DC 限制 → `catalyst-basics`（加载 `skills/catalyst-basics/references/architecture.md`）；项目设置、`.catalystrc`、环境、org、ID、CLI 命令 → `catalyst-basics`；Functions 类型/签名/`catalyst-config.json`/API Gateway/文件上传 → `catalyst-functions`；AppSail 后端 PaaS/Docker/托管运行时/PORT 变量 → `catalyst-appsail`；Slate 前端托管/框架/`slate-config.toml`/Git 部署 → `catalyst-slate`；Data Store CRUD/ZCQL/权限/列类型 → `catalyst-datastore`；Stratus 对象存储/上传下载/签名 URL/分片 → `catalyst-stratus`；NoSQL 文档存储/灵活 schema/集合 → `catalyst-nosql`；Authentication 登录注册/ZAID/Web SDK 认证/Connections OAuth → `catalyst-authentication`；Cache 内存键值/TTL/分段操作 → `catalyst-cache`；Pricing 免费额度/按量付费/GB-seconds/成本估算 → `catalyst-pricing`；SDK（Node.js、Web、Python、Java、Android、iOS、Flutter）→ `catalyst-sdk`；Zia Services、QuickML（OCR、ML 预测、AutoML）→ `catalyst-zia`；Signals 事件驱动触发器/发布订阅/事件监听/自定义发布者/webhook 目标/分发策略 → `catalyst-signals`；SmartBrowz 无头浏览器/Puppeteer/Playwright/Selenium/Browser Logic/PDF 生成/截图/Browser Grid/Dataverse → `catalyst-smartbrowz`；Job Scheduling 作业池/即时后台作业/cron（Periodic/OneTime/Calendar/CronExpression）/`submitJob`/`createCron`/重试 → `catalyst-job-scheduling`；Zoho MCP 设置/`CatalystbyZoho_*` 工具/基础设施即对话 → `catalyst-zoho-mcp`；技能给出错误或过时指导、用户报告错误 → 加载 `catalyst-by-zoho/references/skill-feedback.md`。
23. 不要使用已弃用服务：2025 年 8 月 27 日后注册的用户完全无法访问这些组件——File Store 改用 Stratus（对象存储），Event Listeners 改用 Signals（事件驱动架构），Cron 改用 Job Scheduling（调度执行）。
24. 区域受限服务在推荐前检查 DC：Circuits 在 EU、AU、IN、JP、SA、CA 不可用；Integration Functions 在 EU、AU、IN、JP、SA、CA 不可用；Push Notifications 在 EU、AU、IN、CA 不可用；AutoML (QuickML) 在 EU、AU、IN、JP、SA、CA 不可用；Identity Scanner (Zia) 仅 IN DC 可用（EU、AU、US、JP、SA、CA 不可用）；Mobile Device Management 在 EU、AU、IN、JP、SA、CA 不可用。检查方法：询问用户 Catalyst 账户所在数据中心，或从控制台 URL 的 DC 代码判断（如 `catalyst.zoho.in` → IN，`catalyst.zoho.eu` → EU）。
25. 非交互模式：CLI v1.27.0+ 支持 NI 模式，CLI 从标志和合理默认值取答案而非提示；启用方式为在任意支持命令加 `-ni`（或 `--non-interactive`），或设置环境变量 `ZCATALYST_NON_INTERACTIVE=1`；禁用命令：`functions:setup` → 改用 `functions:add -ni`，`functions:shell` → 改用 `functions:execute`；被阻止选项：NI 模式下不允许 `functions:delete` 和 `client:delete` 的 `--remote`；提示：`catalyst <command> -ni --help` 显示该命令的 NI 专用帮助。
26. 读取 `.catalystrc` 获取 org 和项目上下文：`catalyst init` 后会在项目根写入 `.catalystrc`，会话开始时读取它以识别活动项目而无需询问用户；实际格式含 `defaults`、`actives`、`projects`（每项有 `idx`、`id`、`name`、`domain`、`env` 数组，env 项有 `idx`、`id`、`name`、`type`）。
27. 读取活动项目 ID 和 org ID 的方法：1) 读 `defaults.project` 得到活动项目的 `idx`；2) 在 `projects` 中找到 `idx` 匹配的条目，取其 `id` 作为传给 `-p` 的 project ID；3) 从同一条目读 `env[0].id` 作为传给 `--org` 的 org ID。
28. 术语：始终说 "organization" 或 "org"，绝不说 "portal"——`catalyst init` CLI 提示写的是 "Select a default Catalyst portal"，但这是 CLI 的遗留措辞，正确术语是 organization。
29. `.catalystrc` / `catalyst.json` 缺失时运行 `catalyst init --org <orgId> -p <projectId> -ni`（ID 从 MCP 获取）；绝不手动创建这些文件，绝不使用交互式 `catalyst init`。
30. 所有 Catalyst CLI 命令默认非交互（CLI v1.27.0+）——始终配合 `--org`、`-p`、`--name`、`--type`、`--stack` 标志使用 `-ni`；在代理上下文中绝不回退到交互式/方向键菜单。
31. `catalyst functions:add` 非交互用法：`catalyst functions:add --name <n> --type <type> --stack <stack> -ni`。
32. ZCQL 结果行被包装 → 用 `rows.map(r => r.TableName)` 解包。
33. ZCQL 单次查询最多 300 行 → 用 `LIMIT offset, count` 分页。
34. ZAID 在 Dev 和 Prod 之间不同 → 生产环境第一大认证问题。
35. AppSail PORT → 使用 `process.env.X_ZOHO_CATALYST_LISTEN_PORT`（不是 `PORT`）。
36. Cache 值只能是字符串 → 自行序列化/反序列化 JSON。
37. Stratus 桶名全局唯一 → 使用 `{app-name}-{project-id-prefix}`。
38. Slate → function 调用是跨域的 → 使用完整 URL + `generateAuthToken()` + CORS 白名单。
39. DataStore App User 权限默认关闭 → 在 Console → Table → Scopes & Permissions 中启用。
40. `catalyst-config.json` 格式 → 仅含 `deployment` + `execution` 键，不是 `function` 或 `entry_point`。
41. Advanced I/O node20 的 `req` 是原始 `http.IncomingMessage` → 用 `sendJson(res, ...)` 辅助函数，不要用 `res.json()`。
42. `signOut()` 需要重定向 URL → `catalyst.auth.signOut(redirectURL)`。
43. 文档：主文档 https://docs.catalyst.zoho.com/en/llms.txt；Node.js SDK 完整版（约 420 KB）https://docs.catalyst.zoho.com/en/sdk/nodejs/v2/llms-full.md；Web SDK 完整版（约 116 KB）https://docs.catalyst.zoho.com/en/sdk/web/v4/llms-full.md；Python SDK 完整版（约 489 KB）https://docs.catalyst.zoho.com/en/sdk/python/v1/llms-full.md；Java SDK 完整版（约 407 KB）https://docs.catalyst.zoho.com/en/sdk/java/v1/llms-full.md；CLI 参考 https://docs.catalyst.zoho.com/en/cli/v1/cli-command-reference/index.md；定价 https://catalyst.zoho.com/pricing.html。
44. 获取文档：各 SDK 的 `llms-full.md` 是完整参考——下载并 grep 所需方法，不要整篇阅读；`overview/index.md` 页面是薄落地页，不要依赖它们获取 API 细节；`llms.txt` 是每页的 markdown 索引；在任意文档页 URL 后加 `index.md` 可得 markdown 而非 HTML；响应以 `<!DOCTYPE html>` 开头表示页面不存在。

适用边界 · 注意事项

• 不要用于通用 Zoho CRM 问题，除非目标就是 Catalyst。
• 信息类问题（定价、架构建议、服务选型、"what is Catalyst?"、安装帮助、SDK 用法或任何无需已初始化项目的问题）不适用 Pre-flight 门禁。
• 不要使用已弃用服务（File Store、Event Listeners、Cron），也不要向区域受限 DC 的用户推荐 Circuits、Integration Functions、Push Notifications、AutoML (QuickML)、Identity Scanner (Zia)、Mobile Device Management。