dx-delivery-sdk

dx-delivery-sdk

描述

帮助 Agent 使用 @contentstack/delivery-sdk 为 Contentstack 条目、资源、引用、筛选、排序、分页、区域设置、Live Preview 和 Visual Builder 支持编写正确、可用于生产环境的 TypeScript 代码。当方法名称、选项或调用链顺序很重要时，请根据 Delivery SDK Spec 验证 SDK 行为。

适用场景

当用户询问 Contentstack Delivery SDK 代码、查询示例、辅助函数、SDK 设置、Stack 初始化、引用包含、筛选、排序、分页、带类型的条目获取、资源获取、Live Preview 设置、Visual Builder 支持、SSR 预览处理，或 SDK 查询链调试时使用。

用户问题

用户需要当前且正确的 Contentstack Delivery SDK 代码，并确保方法名称、调用链顺序和查询模式正确。此技能应避免细微的 SDK 错误，并默认提供可用于生产环境的 TypeScript 代码。

成功标准

• 使用当前的 @contentstack/delivery-sdk 方法名称和正确的调用链顺序。
• 当 API 行为不确定时，根据 Delivery SDK Spec 验证详情。
• 提供以 TypeScript 为主的示例，并使用安全的、基于环境变量的凭据。
• 正确处理引用、筛选、排序、分页、字段选择、资源、区域设置和 Live Preview。
• 指出或避免常见错误，例如使用错误的查询方法、缺少分页，或在 SSR 中共享 Live Preview Stack。

预期输入

• 内容类型 UID
• 条目 UID 或适用时的资源 UID
• 用于筛选、排序、选择或引用的字段 UID
• 需要本地化内容时使用的区域设置
• 期望的返回结构或辅助函数行为
• 涉及 Live Preview 时的 SSR 或 Visual Builder 上下文

预期输出

• TypeScript 代码片段
• 可复用的辅助函数
• 正确的 SDK 查询链
• 适用于 Live Preview 或 SSR 的安全 Stack 设置
• 针对错误 Contentstack SDK 用法的调试指导

用户请求示例

• 编写一个 Contentstack Delivery SDK 查询，获取博客文章并包含作者引用。
• 展示如何在 Next.js SSR 中正确设置 Contentstack Live Preview。
• 修复这个 Contentstack 查询链；它没有返回正确的条目。
• 创建一个按 URL 获取条目并支持分页和类型的辅助函数。
• 如何在 @contentstack/delivery-sdk 中获取资源并按内容类型筛选？

工作流概述

1. 确定目标对象：条目、资源、内容类型、分类体系或辅助函数。
2. 当方法名称、选项或调用链顺序很重要时，查阅 Delivery SDK Spec。
3. 仅询问正确构建查询所需但缺失的信息。
4. 选择正确的 SDK 调用链和方法顺序。
5. 根据需要添加分页、区域设置、字段选择和引用。
6. 使用安全的 TypeScript 类型和可复用的辅助函数。
7. 适用时加入错误处理和常见错误警告。

说明

确定目标

判断请求针对的是条目、资源、分类体系、引用、Live Preview，还是可复用的辅助函数。仅在必要时询问缺失的 UID、区域设置、引用或返回结构。

验证 SDK 行为

以 Delivery SDK Spec 作为方法名称、支持的选项和调用链顺序的权威来源。如果请求依赖 SDK 行为，请在回答前确认确切的 API。

使用当前 SDK 模式

优先使用 TypeScript 和当前的 @contentstack/delivery-sdk API。使用安全的、基于环境变量的凭据；除非有文档说明，否则不要硬编码令牌或主机值。

构建正确的查询

在 .query() 之前应用引用，使用 QueryOperation 进行筛选，使用 orderByAscending() / orderByDescending() 排序，并为集合查询添加分页。

安全处理 Live Preview

对于 SSR 或 Visual Builder，应为每个请求创建新的 Stack，并在获取数据前应用 Live Preview 配置。不要跨请求重复使用 Live Preview Stack。

输出格式

优先使用 TypeScript。 使用简洁、可用于生产环境的代码块。 涉及方法顺序限制时，请根据 Delivery SDK Spec 进行核实。 不要硬编码凭据。 返回多个条目时，请说明分页限制。 相关时，请简要说明 Live Preview 或 SSR 安全注意事项。

工具说明

优先将 @contentstack/delivery-sdk 用作主要 SDK。 需要按区域指定预览主机时，使用 @timbenniks/contentstack-endpoints。 使用 getContentstackEndpoints(region, true)，确保 SDK 主机值不包含 https://。 对于 SSR Live Preview 或 Visual Builder，每个请求都要创建一个新的 stack。

安全

默认规则

绝不暴露部署令牌或环境机密。 触发部署前验证部署目标。 生产环境部署必须经过确认。 未经审核，绝不自动部署到生产环境。 示例中绝不硬编码 Contentstack 凭据。 回复中避免分享预览令牌或其他机密。 对于 SSR Live Preview，不要在多个请求之间复用 stack 实例。

破坏性操作

此技能不会执行破坏性操作。如果请求涉及删除、发布或更改生产内容，必须要求明确确认，并在操作前核实目标。

机密

所有凭据和令牌都使用环境变量。绝不打印、推断或回显机密。如果缺少机密，请求提供变量名称或仅显示占位符。

环境变量

示例中使用 process.env 占位符。只有在周围代码明确验证配置时，才优先使用必填非空断言。不要建议将机密提交到源代码管理中。

产品背景

• • 产品：Developer Experience
• • 描述：开发者体验工具
• • 产品安全规则：- 绝不暴露部署令牌或环境机密。
• 触发部署前验证部署目标。
• 生产环境部署必须经过确认。
• 未经审核，绝不自动部署到生产环境。

参考资料

此技能在 references/ 文件夹中提供参考资料。只有当任务与文件内容相关时，才按需阅读这些文件；不要根据以下摘要推断文件内容。

Delivery SDK 规范（产品文档，必读）

• 来源：官方文档（https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/reference.md）
• 摘要：Contentstack 提供 TypeScript Delivery SDK，用于构建应用。下文是一份深入指南，并提供了帮助你开启 TypeScript Delivery SDK 使用之旅的实用资源。此外，该 SDK 还支持在 Node.js 和 React Native 环境中创建应用。
• 阅读：references/delivery-sdk-spec.md

示例

Stack 设置（少样本示例 *）

用户： 使用 TypeScript 设置 Contentstack Delivery SDK。

助手： ```ts import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";

const stack = contentstack.stack({ apiKey: process.env.CONTENTSTACK_API_KEY!, deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!, environment: process.env.CONTENTSTACK_ENVIRONMENT!, region: process.env.CONTENTSTACK_REGION || "us", });

*Default stack setup with env vars and current import style.*

### Live Preview stack factory (few shot *)

**User:** Show the recommended SSR Live Preview setup.

**Assistant:** ```ts
import contentstack from "@contentstack/delivery-sdk";

export function createStack() {
  return contentstack.stack({
    apiKey: process.env.CONTENTSTACK_API_KEY!,
    deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
    environment: process.env.CONTENTSTACK_ENVIRONMENT!,
    region: process.env.CONTENTSTACK_REGION || "us",
    live_preview: {
      enable: true,
      preview_token: process.env.CONTENTSTACK_PREVIEW_TOKEN,
      host: "rest-preview.contentstack.com",
    },
  });
}

适用于 SSR 或 Visual Builder 的按请求工厂。

获取单个条目（少样本示例 *）

用户： 按 UID 获取一篇博客文章。

助手： ```ts const entry = await stack.contentType("blog_post").entry("entry_uid").fetch();

*Use direct fetch for single entries.*

### Entry query (few shot *)

**User:** Fetch multiple blog posts.

**Assistant:** ```ts
const result = await stack.contentType("blog_post").entry().query().find();
const entries = result.entries;

对于集合，请使用 query().find()。

引用（少样本示例 *）

用户： 包含作者和类别引用。

助手： ```ts const result = await stack .contentType("blog_post") .entry() .includeReference(["author", "category"]) .query() .find();

*`includeReference()` belongs before `.query()`.*

### Filtering (few shot *)

**User:** Filter by title.

**Assistant:** ```ts
const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .where("title", QueryOperation.EQUALS, "My Post")
  .find();

请准确使用 QueryOperation 名称。

排序（少样本*）

用户： 按发布日期降序排列。

助手： ```ts const result = await stack .contentType("blog_post") .entry() .query() .orderByDescending("published_date") .find();

*Never use `.descending()`.*

### Pagination (few shot *)

**User:** Return page 1 with 10 items and total count.

**Assistant:** ```ts
const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .skip(0)
  .limit(10)
  .includeCount()
  .find();

未提供分页参数时，提及默认限制为 100 条。

字段选择（少样本*）

用户： 仅获取标题和 URL。

助手： ```ts const result = await stack .contentType("blog_post") .entry() .query() .only(["title", "url"]) .find();

*Use `only()` and `except()` for payload control.*

### Asset fetch and query (few shot *)

**User:** Fetch an asset and query JPEG assets.

**Assistant:** ```ts
const asset = await stack.asset("asset_uid").fetch();

const result = await stack
  .asset()
  .query()
  .where("content_type", QueryOperation.EQUALS, "image/jpeg")
  .find();

同时支持直接获取和资源查询。

辅助函数模式（少样本*）

用户： 创建可复用的辅助函数来获取条目。

助手： ```ts export async function getEntryByUrl(contentTypeUid: string, url: string) { try { const result = await stack .contentType(contentTypeUid) .entry() .query() .where("url", QueryOperation.EQUALS, url) .includeCount() .find();

return result.entries[0] || null;

} catch (error) { if (error instanceof Error) { console.error("Failed to fetch entry by url:", error.message); } return null; } }

*Include safe error handling in reusable helpers.*

### Common mistakes checklist (edge case *)

**User:** What mistakes should I avoid with the Delivery SDK?

**Assistant:** - Do not call `includeReference()` after `.query()`.
- Use `orderByAscending()` / `orderByDescending()`, not `ascending()` / `descending()`.
- Use `QueryOperation.NOT_EQUALS`, not `NOT_EQUAL`.
- Do not hardcode credentials.
- Add pagination for collection queries.
- Do not reuse a Live Preview SSR stack across requests.

*Use as a compact guardrail response.*