contentstack-vibe-docs

面向 AI Agent 的 Contentstack 文档

此技能包含约 13,500 行内容，分布在 30 多个参考文件中。**阅读路由表，选出实际需要的 1–3 个文件，然后停止。**切勿通读所有内容。

路由表

任务	文件
快速查找代码模式	QUICK_REFERENCE.md
Contentstack 基础知识	concepts/base-concepts.md
设计内容模型、选择引用与模块化区块或全局字段、分类体系	concepts/data-modeling-best-practices.md
本地化、回退链、不可本地化字段	concepts/localization.md
区域、端点、区域感知主机	concepts/regions.md
获取内容（REST）	api/rest-api.md
获取内容（GraphQL）	api/graphql-api.md
创建／更新／删除／发布、模块化区块架构、CMA 标头	api/content-management-api.md
转换图片、资源文件夹、资源限制、file_uid	api/image-delivery-api.md
TypeScript Delivery SDK	sdk/delivery-sdk.md
Live Preview 概览	live-preview/concepts.md
Live Preview CSR（ssr: false）	live-preview/csr-mode.md
Live Preview SSR（ssr: true）、按请求创建工厂、哈希隔离	live-preview/ssr-mode.md
Visual Builder、编辑标签、addEditableTags、VB_EmptyBlockParentClass	live-preview/visual-builder.md
调试 Live Preview／Visual Builder 故障	live-preview/debugging.md
Next.js 模式、Draft Mode、revalidateTag	frameworks/nextjs.md
Nuxt 模式	frameworks/nuxt.md
Gatsby 模式	frameworks/gatsby.md
选择合适的令牌（delivery／preview／management／authtoken／OAuth）	security/tokens-authentication.md
角色、自定义权限、团队	security/roles-permissions.md
使用 Auth.js v5（Next.js）进行 OAuth 登录	authentication/oauth.md
Webhook：签名、事件通道、发布风暴	workflows/webhooks.md
发布：原子化协调部署	workflows/releases.md
工作流与发布规则	workflows/content-workflows.md
分支与别名：零停机部署	workflows/branches-aliases.md
环境、发布、Sync API、速率限制	workflows/environments-publishing.md
变体与 Personalize	personalization/variants-and-personalize.md
CLI 插件 — 概览与快速入门	extensions/cli-plugins/overview.md
CLI 插件 — 命令、标志、参数	extensions/cli-plugins/commands.md
CLI 插件 — 发布、测试、故障排查	extensions/cli-plugins/publishing.md
Developer Hub 应用（App SDK、UI 位置、API 代理）	extensions/devhub-apps.md
Contentstack Launch：部署、环境同步	extensions/launch.md
实际代码模式	examples/practical-examples.md
软件包版本	VERSIONS.md

常见任务组合

场景	文件（按顺序）
新建 Next.js 项目	base-concepts → delivery-sdk → nextjs
新建 Nuxt 项目	base-concepts → delivery-sdk → nuxt
为 Next.js 添加 Live Preview	live-preview/concepts → live-preview/ssr-mode → nextjs
为现有网站添加 Visual Builder	live-preview/visual-builder
调试无法正常工作的预览	live-preview/debugging
构建 CRUD/迁移脚本	content-management-api → security/tokens-authentication
带用户登录的全栈应用	delivery-sdk → nextjs → oauth
由 Webhook 驱动的重建	workflows/webhooks → workflows/environments-publishing
零停机内容部署	workflows/branches-aliases → workflows/releases
多语言环境发布	concepts/localization → workflows/environments-publishing
从 CI 部署到 Launch	extensions/launch → workflows/webhooks
响应式图像优化	api/image-delivery-api
快速代码片段	QUICK_REFERENCE.md

决策参考

选择哪个 API？ 读取已发布内容 → REST / GraphQL / Delivery SDK。写入内容 → Content Management API。转换图像 → Image Delivery API。

选择哪个 SDK？ 读取内容（前端/后端）使用 @contentstack/delivery-sdk。写入内容使用 @contentstack/management（仅限服务端，绝不能用于前端）。

选择哪种 Live Preview 模式？ ssr 标志控制 CMS iframe 的更新方式，而不是应用的渲染策略。

• ssr: false — 使用 postMessage。CMS 将数据发送到 iframe，客户端重新获取并更新，无需重新加载。
• ssr: true — iframe 会使用 ?live_preview=<hash>&entry_uid=... 重新加载。服务端会按请求读取参数。

对于 ssr: true，每个请求都要创建一个新的 Contentstack 客户端（工厂模式）。多个编辑者并发时，共享一个全局客户端会导致预览状态泄漏。请参阅 live-preview/ssr-mode.md。

选择哪个令牌？ 前端读取 → Delivery Token（安全）。预览读取 → Preview Token（安全）。服务端写入 → Management Token（绝不能用于前端）。用户会话 → Authtoken 或 OAuth。完整决策树请参阅 security/tokens-authentication.md。

编码前先确认

开始实现前，请与开发者确认：

• 区域（US、EU、AU、Azure NA/EU、GCP NA/EU）— 会影响每个端点。
• 框架（Next.js、Nuxt、Gatsby 等）— 决定 Live Preview 模式。
• 环境（dev/staging/production）— 限定 Delivery Token 的作用范围。
• 凭据是否存储在环境变量中？ — 绝不要询问凭据本身的值。

安全（摘要）

绝不要索取、记录、输出或硬编码 API 密钥、令牌或机密信息。始终使用 process.env.* 引用。绝不要在前端代码中使用 Management Token。如果开发者粘贴了真实令牌，请提醒他们并建议轮换令牌。完整规则请参阅：security/tokens-authentication.md。

风险信号

• 读取所有参考文件，而不是按需选择 1-3 个文件。
• 硬编码凭据，或将管理令牌暴露给浏览器。
• 硬编码区域主机地址，而不是使用 @timbenniks/contentstack-endpoints。
• 混用 Delivery SDK 和 Management SDK 模式。
• 在同一个查询中混用 REST 和 GraphQL 模式。
• 在 SSR 预览请求间共享模块级 Contentstack 客户端。
• 忘记在引用发布中设置 api_version: 3.2。
• 忘记 .includeReference()，之后又疑惑为什么引用未定义。
• 忽略 X-RateLimit-Reset，在收到 429 时陷入忙循环。