datocms-cda

DatoCMS 内容交付 API 技能

擅长使用 @datocms/cda-client 查询 DatoCMS CDA（只读 GraphQL）。请按顺序执行步骤。

步骤 1：检测上下文

如果上下文已明确，则跳过全面检测。仅在需要时重新检查。

检查项目设置：

1. 查看 package.json 中是否包含 @datocms/cda-client。如果未安装：npm install @datocms/cda-client

2. 查找现有的 executeQuery 或 rawExecuteQuery 导入，以了解使用模式。

3. 检查 .env* 文件（包括 .env.example）中的 *DATOCMS*TOKEN* 变量；复用这些变量名。入门变量：DATOCMS_PUBLISHED_CONTENT_CDA_TOKEN、DATOCMS_DRAFT_CONTENT_CDA_TOKEN。

4. 检查框架（Next.js、Astro、Remix、Nuxt、SvelteKit），以确定查询应在服务端还是客户端执行。除非使用公开的只读令牌，否则不要向浏览器暴露令牌。

5. 检查类型生成设置：

   • gql.tada： 依赖项中有 gql.tada，并调用了 initGraphQLTada（通常位于 lib/datocms/graphql.ts）
   • graphql-codegen： devDependencies 中有 @graphql-codegen/cli，并有 graphql.config.ts
   • 仅用于了解上下文——遵循现有设置。不要建议设置类型生成。

CDA 只需要只读令牌。如果 DATOCMS_API_TOKEN 也用于 CMA，最好为 CDA 单独使用只读令牌。

步骤 2：加载参考资料

如果请求明确，直接继续。只读取 references/ 中相关的参考资料：

任务	参考资料
基础（按 slug/ID 获取、单实例、集合、元数据）	references/querying-basics.md
筛选（字段/元数据筛选、AND/OR、深层筛选、上传）	references/filtering.md
分页与排序（first/skip、自动分页、排序、树）	references/pagination-and-ordering.md
本地化（本地化字段、回退、所有语言环境的值）	references/localization.md
模块化内容（区块、片段、嵌套区块）	references/modular-content.md
结构化文本（DAST 值/区块/链接、渲染）	references/structured-text.md
图片与媒体（responsiveImage、imgix、占位符、焦点、视频）	references/images-and-videos.md
SEO 与元数据（_seoMetaTags、网站图标、globalSeo、OG 标签）	references/seo-and-meta.md
草稿/预览、严格模式、读取缓存标签、CDN、环境、Content Link 查询选项	references/draft-caching-environments.md
类型生成（gql.tada、graphql-codegen、schema 类型、类型化查询）	references/type-generation.md
gql.tada 片段规范（屏蔽、组合、页面查询）	references/fragment-patterns.md
客户端设置/封装、选项、令牌权限、ApiError 处理、429/复杂度/CDN 诊断、自定义标量	references/client-and-config.md

跨领域：

• 筛选本地化内容 → references/localization.md
• 结构化文本包含模块化内容 → references/modular-content.md
• 区块中的图片 → references/images-and-videos.md
• 对筛选后的集合分页 → references/pagination-and-ordering.md
• 复杂嵌套 → 查看 references/pagination-and-ordering.md 了解复杂度开销
• 在 gql.tada 项目中编写/扩展片段 → references/fragment-patterns.md

步骤 3：生成代码的强制规则

编写代码时，同时应用步骤 4 中的所有检查。

客户端用法

• 默认使用 @datocms/cda-client 中的 executeQuery（或仓库中现有的封装）
• 仅在需要响应头（缓存标签）时使用 rawExecuteQuery

GraphQL 查询

• 使用模板字面量字符串编写（除非项目使用 TypedDocumentNode / gql.tada）；字符串查询会返回 unknown——请为其指定类型：executeQuery<Result>(query, …)
• 仅请求所需字段——不要过度获取
• 在声明中使用 DatoCMS 自定义标量（如 $first: IntType、$id: ItemId）
• 遵循项目约定；添加 /* GraphQL */ 前缀可启用编辑器高亮/验证

const query = /* GraphQL */ `query { ... }`

错误处理

• 不要编写自定义重试逻辑——autoRetry 会处理速率限制

第 4 步：验证

提交最终代码前：

1. 令牌 — 使用环境变量（绝不硬编码），并检查读取权限
2. 错误处理 — 在边界处捕获 ApiError
3. 分页 — 记录数超过 500？使用 executeQueryWithAutoPagination
4. 草稿模式 — 确认有意设置 includeDrafts（不要在生产环境中暴露未发布内容）
5. excludeInvalid — 对稳定的架构，建议使用此选项。架构会变动？改用 filter: { _isValid: { eq: true } }
6. 类型安全 — 不要使用 as / as unknown as 来规避错误
7. 导入 — 从 @datocms/cda-client 导入 CDA；如果已接入类型生成，则保留生成的 GraphQL 辅助函数；从子路径导入 React 渲染器（react-datocms/structured-text）：根路径 react-datocms 会静态导入可选的对等依赖 @mux/mux-player-react
8. 变量 — 所有动态值都通过 GraphQL 变量传递，不要插值
9. 结构化文本 — 包含所有相关子字段（value、blocks、links、inlineBlocks）；省略会导致数据静默丢失；分别使用各自的回调进行渲染（inlineBlocks → renderInlineBlock，而不是 renderInlineRecord）
10. Fetch 集成 — 使用框架原生的 fetch、标签或自定义接线？使用 buildRequestHeaders() / buildRequestInit()
11. 类型生成 — 使用 gql.tada 还是 graphql-codegen？使用项目的 graphql() 函数，并检查标量映射
12. gql.tada 片段 — 组合数组应与每个 ...Fragment 展开一一对应；遵循项目的掩码设置（参见 references/fragment-patterns.md）

跨技能路由

此技能涵盖通过 GraphQL CDA 读取。遇到以下情况时，转到配套技能：

条件	路由到
DAST 结构或验证	datocms-structured-text — 文档模型
DAST 遍历或编辑；Markdown/HTML 导入或格式导出	datocms-structured-text — 编辑 或 转换
修改内容、架构、上传、webhook 或脚本（包括 REST 查询）	datocms-cma
应用接线：草稿模式端点、Web Previews、Content Link 覆盖层、实时订阅、缓存标签失效（重新验证、CDN 清除）	datocms-frontend-integrations
构建插件	datocms-plugin

此类接线中的查询部分仍在此处处理：includeDrafts、contentLink / baseEditingUrl / _editingUrl，以及通过 rawExecuteQuery 读取 x-cache-tags。

仅在处理 DAST 任务时加载专用技能；常规 GraphQL 选择仍在此处处理。缺少同级参考资料？请从 datocms/agent-skills 安装该技能，或更新完整技能包。