使用 Catalyst Data Store 时避免…

在 Zoho Catalyst Data Store 上通过 MCP 进行建表、ZCQL 查询与 CRUD 操作时，规避结果包装、布尔存储和 App User 权限等隐蔽 bug。

适用场景

解决思路

1. 在任何 Data Store 操作前，先在可用工具列表中搜索 `CatalystbyZoho_*` 工具以验证 MCP 连接。
2. 若未找到 `CatalystbyZoho_*` 工具：立即停止，不要编写任何代码、脚手架文件或指导 Console 步骤；加载 `catalyst-zoho-mcp` 技能并引导用户完成 MCP 设置，直到用户确认 `CatalystbyZoho_*` 工具可见后再继续。
3. 若找到工具：依次运行 `CatalystbyZoho_List_All_Organizations` → `CatalystbyZoho_List_All_Projects` 设置项目上下文，然后继续操作。
4. 按顺序执行检查清单：Step 0 确认 `CatalystbyZoho_*` 工具可见（否则停止并先设置 MCP）；Step 1 运行 `CatalystbyZoho_List_All_Organizations`；Step 2 运行 `CatalystbyZoho_List_All_Projects`；Step 3 建表用 `CatalystbyZoho_Create_Table`，已有表用 `CatalystbyZoho_List_All_Tables`；Step 4 执行操作。
5. 建表时直接使用 `CatalystbyZoho_Create_Table`，不要指示用户打开 Catalyst Console 手动建表；读写数据时用 `CatalystbyZoho_List_All_Tables` 获取表 ID，绝不让用户手动复制表 ID。
6. 加载 `references/datastore-basics.md` 以获取 CRUD 操作、ZCQL 语法、结果解包和权限设置。
7. 始终解包 ZCQL 结果：使用 `rows.map(r => r.TableName)`；原始 ZCQL 结果是包装过的，不解包直接访问是 Data Store 的头号 bug。
8. 检查 App User 权限：默认关闭；若查询涉及已登录用户读取数据，检查 Console → Table → Scopes & Permissions。
9. 处理分页：ZCQL 每次查询最多 300 行，更大数据集使用 `LIMIT offset, count`。
10. 不要从空目录或未读取的目录中断言项目特定值：若工作目录没有项目文件，不要臆造时区、表名、项目 ID、环境名等；请开发者提供。
11. 时区：除非从真实项目配置文件中读取到时区，否则不要为 ZCQL 日期查询声明时区；询问开发者其项目使用的时区。
12. 表名/列名：只使用 `CatalystbyZoho_List_All_Tables` 返回的名称或用户明确提供的名称。
13. 编写函数代码时默认使用原生 Node.js 响应语法：`res.writeHead()` + `res.end()`，而非 Express 方法（`res.status()`、`res.json()`），除非用户明确选择 Express 模板。
14. App User 写权限默认关闭：App User 角色默认启用 SELECT，但 INSERT、UPDATE、DELETE 必须按表手动启用；前往 Console → Table → Scopes and Permissions → App User 角色 → 为需要写入的表勾选 Insert/Update/Delete。
15. App Administrator 默认拥有所有权限：绝不要将 App Administrator 角色分配给普通终端用户，因为它授予所有表的完整读/写/删除权限。

适用边界 · 注意事项

• 未确认 `CatalystbyZoho_*` MCP 工具可见时，不要进行任何 Data Store 操作或编写相关代码。
• 工作目录为空或未读取到项目文件时，不要臆造时区、表名、项目 ID、环境名等项目特定信息。
• 用户未明确选择 Express 模板时，不要使用 Express 响应方法编写函数代码。