catalyst-by-zoho

Zoho Catalyst — 技能索引

这是路由层。加载最具体匹配的技能 — 不要仅依据此文件作答。

---

理念

• 优先使用 MCP，而不是提问。 如果有 CatalystbyZoho_* 工具可用，就使用它们。绝不要让用户从控制台复制 ID。
• 默认使用 Development 环境。 始终以 Development 环境为目标，除非用户明确提到“production”或“deploy to prod”。
• “构建应用”默认指 Slate + Function。 如果用户说“build an app”“create an app”或“make a simple app”，但没有指定仅需后端，默认输出应为 Slate 前端 + Advanced I/O 函数后端。不要只构建一个函数就称之为应用。如果用户的意图显然仅涉及后端（例如“build an API”“write a function”），则跳过 Slate。
• 简单 HTTP 场景优先使用 Functions，而不是 AppSail。 Functions 按调用次数计费，成本更低、部署更简单，也无需管理基础设施。只有在用例确实需要持久进程或自定义运行时的情况下，才选择 AppSail。
• 构建前说明成本。 对于任何新基础设施（函数、AppSail、Stratus 存储桶），都要加载 catalyst-pricing，并在编写代码前提供简要估算。大多数小型项目都在免费层范围内 — 符合情况时请说明。
• 推荐当前服务，而非已弃用服务。 File Store → Stratus。Event Listeners → Signals。Cron → Job Scheduling。生成的代码或配置中绝不要提及已弃用的名称。
• 提前提醒用户注意区域限制。 Circuits 和 Integration Functions 在大多数数据中心都无法使用。推荐它们之前，先确认用户所在的数据中心。

---

工作方式

1. 预检 — 检查 .catalystrc 和 catalyst.json 是否存在。如果缺失，使用 MCP 获取组织 / 项目 ID，并运行 catalyst init --org <orgId> -p <projectId> -ni。绝不要使用交互式 catalyst init。
2. 检查 MCP — 查找 CatalystbyZoho_* 工具。如果可用，就使用 MCP 获取组织 / 项目 ID，而不是询问用户。
3. 路由 — 将查询匹配到下方路由表中最具体的服务。
4. 按需加载 — 仅阅读当前步骤所需的单个参考文件。不要预先加载多个技能。对于“构建应用”请求：(a) 除非用户明确表示仅需后端，否则默认使用 Slate 前端 + AIO 函数；(b) 简要概述架构，并在构建前与用户确认；(c) 随后在编写各部分时，每项服务只加载一个参考文件 — 前端加载 catalyst-slate，后端加载 catalyst-functions。
5. 成本检查 — 只有在用户明确询问成本，或计划中包含 AppSail、Stratus 或其他付费层服务时，才加载 catalyst-pricing。对于基础 Functions + DataStore 项目（可能在免费层范围内），跳过此步骤。
6. 作答 — 使用用户的平台（Node.js、Python、Java、Web 或 Mobile）提供代码示例。

触发条件

包含以下内容的查询适用此技能：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 定价、“build on Zoho's platform”或“deploy to Catalyst”。除非目标是 Catalyst，否则不要用于一般的 Zoho CRM 问题。

---

操作前检查（仅适用于会修改项目的任务）

步骤 1 — MCP 检查（对于基础设施任务，必须先执行）： 在你的工具列表中查找 CatalystbyZoho_* 工具。

• 如果存在 — 使用 MCP 获取组织 / 项目 ID。切勿要求用户从控制台复制 ID。 如何正确调用 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），不查看架构就无法看到这些参数。
  3. ZohoMCP_executeTool 接受包含以下结构的 body：

     ZohoMCP_executeTool({ body: {
       tool_name: "CatalystbyZoho_List_All_Functions",
       arguments: {
         path_variables: { project_id: "31594000000127002" },
         headers: {},
         body: {}
       }
     }})
     

  4. 不需要必填路径变量的工具（例如 List_All_Organizations、List_All_Projects）可以使用 arguments: {} 调用。
• 如果不存在，且任务会创建资源、写入文件、部署或读取项目 ID — 立即停止。 不要编写任何代码或创建任何文件。告诉用户：

  "在处理你的 Catalyst 项目之前，需要先连接 Zoho MCP。加载 catalyst-zoho-mcp 技能即可完成设置 — 不到一分钟。" 在 CatalystbyZoho_* 工具可见之前，不要继续。

此检查仅适用于会写入 Catalyst 项目文件、部署、读取项目 / 环境 ID 或执行 MCP 项目操作的任务。 对于信息咨询（定价、架构建议、服务选择、“什么是 Catalyst？”，安装帮助、SDK 用法，或任何不需要已初始化项目的问题），请跳过此检查。

对于会修改项目的任务：请确认工作目录中存在 .catalystrc 和 catalyst.json。

• 如果缺失 → 使用 MCP 工具获取组织 ID 和项目 ID，然后运行：

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

  切勿要求用户以交互方式运行 catalyst init。切勿自行创建 .catalystrc 或 catalyst.json — 必须由 CLI 生成。 注意： NI 模式只能关联现有项目。如果尚无项目，请告诉用户在 Catalyst 控制台中创建一个，然后再回来 — 你将使用 catalyst init -ni 将其关联。

---

Catalyst 概览

刚接触 Catalyst？以下是一句话介绍各项服务的用途：

服务	用途
Functions	无服务器函数 — 基本 I/O（HTTP）、高级 I/O、事件、Cron、任务、集成、浏览器逻辑。按调用计费。
AppSail	用于长时间运行的 Web 应用的 PaaS — Node.js、Java、Python 托管运行时，或任意 Docker 容器。
Data Store	关系型表格（行 + 列、外键）。通过 ZCQL（类似 SQL）或 SDK 查询。
Stratus	对象／文件存储（类似 S3）。包含存储桶、文件夹、对象。单个对象最大 250 GB。
Slate	前端托管（类似 Vercel）。可部署 React、Next.js、Vue、Angular、Svelte、Preact、Astro、SolidJS、静态 HTML。
Cache	内存键值存储。划分为多个分区。TTL 以小时为单位，最长 48 h。
NoSQL	采用灵活架构的文档存储（无固定列）。适用于非结构化／多态数据。
Authentication	内置用户注册／登录（ZAID）。OAuth Connections 用于第三方 API。
SmartBrowz	无头浏览器自动化、PDF／屏幕截图生成、Browser Logic 函数、Browser Grid（并行浏览器）和 Dataverse（网页抓取）。
Zia Services	预训练 AI/ML：OCR、人脸分析、文本分析、对象检测、条码、内容审核。
QuickML	无代码／低代码 ML 平台 — ML 流水线、AutoML、LLM 服务、RAG、知识库、预测端点。（预测模型：所有 DC 均可用。生成式 AI：AU/SA/CA 不可用。Zia Model Library：仅 IN 可用。）
Circuits	无服务器工作流编排（步骤函数）。（EU/AU/IN/JP/SA/CA 不可用）
Signals	事件驱动触发器／发布订阅（替代旧版 Event Listeners）。
Job Scheduling	任务池 + 立即执行的任务 + Cron — 用于定时／后台执行 Job 函数、Webhooks、Circuits、AppSail（替代旧版 Cron）。
Zoho MCP	AI 工具集成 — 让 AI Agent 通过 CatalystbyZoho_* 工具管理 Catalyst 基础设施。
ZCQL	用于 Data Store 的类 SQL 查询语言。SELECT、INSERT、UPDATE、DELETE。每条 SELECT 最多返回 300 行。
ZAID	Zoho Account ID — 内置的身份验证层。与 Web SDK 搭配使用，处理用户身份验证流程。

---

技能路由表

查询内容…	加载此技能
要使用哪项服务、架构决策、DC 限制	catalyst-basics（加载 ../catalyst-basics/references/architecture.md）
项目设置、.catalystrc、环境、组织、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 — 文档存储、灵活架构、集合	catalyst-nosql
身份验证 — 用户登录/注册、ZAID、Web SDK 身份验证、Connections/OAuth	catalyst-authentication
Cache — 内存键值存储、TTL、分段操作	catalyst-cache
定价 — 免费套餐、按用量付费、GB 秒、费用估算	catalyst-pricing
SDK — Node.js、Web、Python、Java、Android、iOS、Flutter	catalyst-sdk
Zia Services — OCR、人脸/文本分析、内容审核	catalyst-zia
QuickML — ML 管道、AutoML、LLM Serving、RAG、模型端点	catalyst-quickml
Signals — 事件驱动触发器、发布/订阅、事件监听器、自定义发布器、webhook 目标、分发策略	catalyst-signals
SmartBrowz — 无头浏览器、Puppeteer、Playwright、Selenium、Browser Logic、PDF 生成、屏幕截图、Browser Grid、Dataverse	catalyst-smartbrowz
Job Scheduling — 作业池、即时/后台作业、crons（Periodic/OneTime/Calendar/CronExpression）、submitJob、createCron、重试	catalyst-job-scheduling
Zoho MCP — MCP 设置、CatalystbyZoho_* 工具、以对话为基础的基础设施	catalyst-zoho-mcp
技能提供了错误或过时的指导 — 用户报告错误	加载 references/skill-feedback.md

---

切勿使用（已弃用 + 受区域限制）

已弃用的服务 — 请勿用于新项目

2025 年 8 月 27 日之后注册的用户完全无法访问这些组件。

请勿使用	改用此服务
File Store	Stratus（对象存储）
Event Listeners	Signals（事件驱动架构）
Cron	Job Scheduling（计划执行）

受区域限制的服务 — 推荐前请检查 DC

这些服务在列出的数据中心不可用。在这些区域为用户使用这些服务构建项目会导致运行时错误。

服务	不可用地区
Circuits	EU、AU、IN、JP、SA、CA
Integration Functions	EU、AU、IN、JP、SA、CA
QuickML — Generative AI（LLM Serving、RAG、Knowledge Base）	AU、SA、CA（预测/ML 模型在所有 DC 均可用；QuickML 控制台中的 Zia Model Library 仅在 IN 可用）
Identity Scanner（Zia）— Document Processing（Aadhaar、PAN 等）	仅在 IN DC 可用，API 也包括在内
Identity Scanner（Zia）— Facial Comparison	可通过 API/SDK 从任何 DC 使用；仅控制台测试限于 IN DC
Mobile Device Management	EU、AU、IN、JP、SA、CA

**如何检查：**询问用户其 Catalyst 账户使用的是哪个数据中心，或查看其控制台 URL 中的 DC 代码（例如，catalyst.zoho.in → IN，catalyst.zoho.eu → EU）。

---

非交互模式

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 专属帮助。

---

.catalystrc — 读取组织和项目上下文

运行 catalyst init 后，系统会在项目根目录写入 .catalystrc 文件。每次会话开始时读取此文件，即可识别当前项目，无需询问用户。

实际格式：

{
  "defaults": { "project": 1, "env": 1 },
  "actives":  { "project": 1, "env": 1 },
  "projects": [
    {
      "idx": 1,
      "id": "<projectId>",
      "name": "<projectName>",
      "domain": { "id": "<domainId>", "name": "<projectName>-<orgId>.development" },
      "env": [{ "idx": 1, "id": "<orgId>", "name": "Development", "type": 3 }]
    }
  ]
}

如何读取当前项目 ID 和组织 ID：

1. 读取 defaults.project → 这是当前项目的 idx 值
2. 在 projects 中找到 idx 相匹配的条目 → 获取其 id → 这是要与 -p 一起使用的项目 ID
3. 在同一条目中读取 env[0].id → 这是要与 --org 一起使用的组织 ID

---

快速参考：常见陷阱

• 术语：始终使用“organization”或“org”，绝不要使用“portal” — catalyst init CLI 提示中写着“Select a default Catalyst portal”，但这是 CLI 沿用的旧措辞；正确术语是 organization
• 缺少 .catalystrc / catalyst.json → 运行 catalyst init --org <orgId> -p <projectId> -ni（从 MCP 获取 ID）；不要手动创建这些文件，也不要使用交互式 catalyst init
• 所有 Catalyst CLI 命令默认采用非交互模式（CLI v1.27.0+）— 始终使用 -ni 以及 --org、-p、--name、--type、--stack 标志；在 Agent 上下文中，绝不要退回到交互式菜单或方向键菜单
• catalyst functions:add 非交互用法 — catalyst functions:add --name <n> --type <type> --stack <stack> -ni
• ZCQL 结果行带有包装层 → 使用 rows.map(r => r.TableName) 解包
• ZCQL 每个查询最多返回 300 行 → 使用 LIMIT offset, count 分页
• Dev 和 Prod 的 ZAID 不同 → 这是生产环境中最常见的身份验证问题
• AppSail PORT → process.env.X_ZOHO_CATALYST_LISTEN_PORT（而非 PORT）
• Cache 值只能是字符串 → 自行序列化/反序列化 JSON
• Stratus 存储桶名称全局唯一 → 使用 {app-name}-{project-id-prefix}
• Slate → 函数调用属于跨域调用 → 使用完整 URL + generateAuthToken() + CORS 白名单
• DataStore 的 App User 权限默认关闭 → 在 Console → Table → Scopes & Permissions 中启用
• catalyst-config.json 格式 → 仅使用 deployment + execution 键；不要使用 function 或 entry_point
• Advanced I/O node20 的 req → 原始 http.IncomingMessage；使用 sendJson(res, ...) 助手，而非 res.json()
• signOut() 需要重定向 URL → catalyst.auth.signOut(redirectURL)

---

文档

• 主要文档：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

每个 SDK 的 llms-full.md 文件都是完整参考文档——请下载文件并搜索所需方法，而不是从头到尾阅读。overview/index.md 页面只是简略的入口页；不要依赖它们获取 API 详情。

• CLI 参考：https://docs.catalyst.zoho.com/en/cli/v1/cli-command-reference/index.md
• 定价：https://catalyst.zoho.com/pricing.html

获取文档：llms.txt 是包含所有页面的 Markdown 索引。在任意文档页面 URL 后追加 index.md，即可获取 Markdown 格式而非 HTML 格式的内容。如果响应以 <!DOCTYPE html> 开头，则表示页面不存在。