用 Claude + Headless CMS 统一内容管道

用 Claude + Headless CMS 统一内容管道 | 前端进阶之旅

Full translation

完整中文译文

大多数“AI 内容流水线”教程，都会让你再接入一家供应商。你需要安装 AI 提供商的 SDK，管理第二个 API key，承担第二份账单，然后编写胶水代码，把生成结果搬到真正存放内容的地方。

Cosmic 通过存储内容的同一个 API 生成文本、图片和视频。只需一个 SDK、一个 key、一份账单。本指南将基于这个 API 搭建一条可实际运行的流水线：输入一份源文档，输出一篇待审核的草稿，并且在任何内容进入生产环境之前，都必须由人工批准。

下文全部使用官方 TypeScript SDK：@cosmicjs/sdk。无需接入第二家 AI 提供商。

一条内容流水线包含四个阶段，其中第三个阶段，正是另外三个阶段值得自动化的原因。

Source（素材）。原始材料：brief、访谈记录、季度报告、调查结果电子表格。

Generate（生成）。把素材转换成结构化草稿。

Review（审核）。由人工阅读、编辑，并决定是否发布。

Publish（发布）。通过现有前端，将审核通过的草稿正式上线。

如果跳过第三个阶段，你运行的就是一座垃圾内容工厂。下面这条流水线把审核关卡视为承重基础设施，而不是事后补上的流程。

你需要一个 Cosmic 账号。Free 方案包含 1 个 Bucket、2 名团队成员、1,000 个 Object，以及每月一定额度的 AI token，足以完成端到端的搭建和测试。

你还需要 Bucket slug、read key 和 write key，它们可以在 Bucket 的 Settings → API Access 中找到。

此外，需要安装 Node.js 和一个包管理器。

每项 AI 操作都需要 write key。务必只在服务端保存它。

第 1 步：安装 SDK 并创建客户端

npm install @cosmicjs/sdk

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY,
  writeKey: process.env.COSMIC_WRITE_KEY,
})

这就是完整的依赖列表。同一个客户端既能读取内容、写入内容，也能生成内容。

第 2 步：生成第一篇草稿

cosmic.ai.generateText() 接收一个 prompt，并返回生成的文本以及 token 用量。

const response = await cosmic.ai.generateText({
  prompt: 'Write a 400-word product description for a ceramic pour-over coffee dripper. Audience: home brewers. Tone: plain and specific. No superlatives.',
  max_tokens: 1000,
})

console.log(response.text)
console.log(response.usage) // { input_tokens, output_tokens }

usage 对象比表面看起来更重要。通过它，你可以为流水线生成的每一篇内容计算出真实成本，后文还会再次谈到这一点。

如果你更喜欢直接使用 HTTP，同一个调用也可以通过 REST 完成：

curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/text \
  -d '{"prompt":"Write a product description for a coffee mug","max_tokens":500}' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BUCKET_WRITE_KEY}"

第 3 步：输入一份真实的源文档

正是这一步，把一个 prompt 玩具变成了真正的流水线。media_url 参数可以指向 Bucket 中的任意文件，模型会在处理请求时分析该文件，包括图片、PDF、Excel 电子表格和 Word 文档。

把一份季度报告上传到 Bucket，然后基于它生成内容：

const summary = await cosmic.ai.generateText({
  prompt:
    'Summarize the key points from this document as a bulleted list. Include only figures stated in the source. Do not extrapolate.',
  media_url: 'https://cdn.cosmicjs.com/quarterly-report.pdf',
  max_tokens: 1000,
})

这样做的核心价值，就是让生成内容有事实依据。仅根据 prompt 工作的模型会编造看似合理的数字；基于你的 PDF 工作时，模型会受到你所控制的文档约束。此时，“只使用原文明确给出的数字”这条指令也变得可以核查：审核人员可以打开同一份 PDF，验证每一项陈述。

当你需要围绕同一份素材进行多轮完善时，同一个参数也适用于 chat 格式：

const analysis = await cosmic.ai.generateText({
  messages: [
    { role: 'user', content: 'What trends do you see in this sales data?' },
    { role: 'assistant', content: 'Looking at the spreadsheet, I can see several patterns...' },
    { role: 'user', content: 'What was the highest performing month?' },
  ],
  media_url: 'https://cdn.cosmicjs.com/sales-data.xlsx',
  max_tokens: 500,
})

对于内容团队来说，实用的源文档包括：客户访谈记录、客服工单导出文件、发布说明、分析数据 CSV，以及保存为 PDF 的竞品定价页面。

第 4 步：将结果作为草稿写入 CMS

生成和存储使用的是同一个客户端，因此这里只需要一次调用，也不需要任何胶水代码。

const { object } = await cosmic.objects.insertOne({
  title: 'Q3 Performance Recap',
  type: 'blog-posts',
  status: 'draft', // never 'published' from an automated step
  metadata: {
    markdown_content: summary.text,
    teaser: 'Generated from the Q3 report. Pending editorial review.',
  },
})

console.log(object.id)

status: 'draft' 这一行，是整条流水线的安全保障。每个生成的 Object 都会进入一种对生产环境前端不可见的状态，直到有人手动更改它。

第 5 步：让审核关卡真正发挥作用

如果审核流程依赖某个人记得去检查文件夹，它迟早会失效。要让这道关卡真正可靠，需要做好两件事。

查询审核队列。只需一次请求，就能获得所有等待审核的内容：

const { objects } = await cosmic.objects
  .find({ type: 'blog-posts', status: 'draft' })
  .props(['id', 'title', 'created_at'])

把这个查询接入定时发送的 Slack 消息，审核队列就会主动来到团队面前，而不是被动等待别人发现。

发布必须始终由人工操作。批准步骤应当是一次由某个人有意执行的状态变更：

await cosmic.objects.updateOne(objectId, { status: 'published' })

不要把这次调用放进生成脚本。应当把它放在 dashboard 中编辑人员点击的按钮背后，或者放进一个必须指定批准人的内部工具中。

第 6 步：选择模型，同时保留随时切换的能力

model 参数默认为 claude-opus-5。它也支持 Gemini 模型，例如 gemini-3.1-pro-preview；支持 OpenAI 模型，例如 gpt-5.2-codex；还支持 Moonshot Kimi 模型，例如 kimi-k3。

const draft = await cosmic.ai.generateText({
  prompt: brief,
  model: 'gemini-3.1-pro-preview',
  max_tokens: 2000,
})

切换提供商只需修改一行代码，不需要增加新的依赖、新的 key，也不需要建立新的付费关系。这一点很重要，因为你今天选择的模型终将被更新的模型取代。如果一条流水线把自己绑定在单一供应商的 SDK 上，那么每当前沿模型发生变化时，它都需要重新搭建。若想了解更完整的论证，可以参阅为什么你的 AI 技术栈应当与模型无关。

内容流水线可以采用一种实用的模型分工：使用成本更低的 Budget-tier 模型处理机械性工作，例如提取要点或起草 meta description；使用 Standard-tier 模型撰写读者真正会看到的正文。

第 7 步：在同一条流水线中生成特色图片

AI API 还可以生成图片和视频，因此，特色图片不必再通过人工交接给设计师，也不需要去素材库中寻找。图片生成按每张图片的固定 token 成本计费：一张 DALL-E 3 图片需要 4,800 个 output token；一张 Gemini 1K 或 2K 图片需要 32,160 个；一张 Gemini 4K 图片需要 57,600 个。通过 Veo 生成视频的成本要高得多，一段 4 秒的快速渲染视频需要至少 144,000 个 token。

图片和视频的请求格式请参阅 AI API 参考文档。生成的媒体会进入 Bucket 的媒体库，因此你可以在创建草稿的同一次运行中，把它附加到草稿 Object 上。

第 8 步：有人实时查看时使用流式输出

批处理任务不需要流式输出，但面向编辑人员的工具需要。因为屏幕空白二十秒，会让人觉得功能已经出故障。

import { TextStreamingResponse } from '@cosmicjs/sdk'

const result = await cosmic.ai.generateText({
  prompt: 'Draft an intro paragraph for this post',
  max_tokens: 500,
  stream: true,
})

const stream = result as TextStreamingResponse

let fullResponse = ''
stream.on('text', (text) => {
  fullResponse += text
})
stream.on('usage', (usage) => console.log('Usage:', usage))
stream.on('end', () => console.log('Complete:', fullResponse))
stream.on('error', (error) => console.error('Error:', error))

第 9 步：让流水线拥有记忆

生成只是一条实用流水线的一半，检索是另一半。在起草新文章之前，先检查是否已经发布过相同主题的文章，再把现有内容作为上下文提供给 prompt。

Cosmic 内置了针对 Bucket 内容的语义搜索。它根据含义而不是关键词匹配来查找 Object。借助它，可以避免流水线生成四篇彼此竞争同一个搜索查询的文章。查询格式请参阅语义搜索文档。

无代码方案：把 Claude 直接连接到 CMS

如果你希望 AI assistant 以交互方式操作内容，而不是运行脚本任务，可以使用 Cosmic MCP server。它会把你的 Bucket 暴露为 Claude Code、Claude Desktop 或 Cursor 可以直接调用的工具，包括读取 Object、创建草稿、上传媒体和生成内容。

这里有必要了解仅使用 read key 的配置方式。让 MCP server 使用 read key 后，所有创建、更新和删除工具都会被阻止。这样，你就能获得一个可以分析内容库并提出修改建议，却无法写入任何内容的 assistant。完整配置方法可以参阅“通过 MCP 将 Claude Code 连接到 CMS”以及 MCP server 文档。

真正重要的防护措施

以下六条规则，都是从实践中总结出来的。

绝不要在自动化步骤中发布内容。生成步骤只负责写入草稿，只有人工才能把状态改为 published。

每项事实陈述都必须以源文档为依据。使用 media_url，并指示模型只能使用文档明确给出的数字。如果某项陈述无法由审核人员追溯到来源，就应将其删除，而不是改成更含糊的说法。

为每项任务设置 max_tokens 上限。这是防止失控循环耗尽整月额度的断路器。

记录每次调用的 usage。把 input token 和 output token 与 Object 一起存储，以便计算每篇内容的成本。

只在服务端保存 write key。每项 AI 操作都需要 write key。出现在客户端代码中的 write key，就等于公开的 write key。

生成之前先去重。首先运行语义搜索。两篇面向同一个查询的文章，会分散彼此的搜索排名。

AI 用量会消耗方案中的 token 配额，文本生成还会根据实际使用的 token 应用不同等级的倍率。

Budget，1.0x：GPT-5 Nano、GPT-5 Mini、Claude Haiku 4.5。实际使用 1,000 个 token，就会扣除 1,000 个。

Standard，2.0x：GPT-5、GPT-5.2、GPT-5.2 Codex、GPT-5.5、Claude Sonnet 4.6、Claude Sonnet 5、Claude Opus 4.7、Claude Opus 4.8、Gemini 3.1 Pro、Kimi K3。实际使用 1,000 个 token，就会扣除 2,000 个。

Premium，4.0x：Claude Fable 5。实际使用 1,000 个 token，就会扣除 4,000 个。

媒体按每项资产的固定成本计费，并以 output token 计算。图片和视频的具体数字已在第 7 步中列出。

截至本文写作时，各方案价格如下：Free 为每月 0 美元，Builder 为每月 49 美元，Team 为每月 299 美元，Business 为每月 499 美元，Enterprise 采用定制定价。每增加一名团队成员，费用为每人每月 29 美元。如果超出每月配额，还可以购买 token 包。当前配额和 token 包规格请查看定价页面。

衡量流水线是否有效

产量是错误的指标。如果一条流水线让内容产出变成原来的三倍，却让互动率减半，那它反而让情况变得更糟。你应该追踪以下指标：

批准率。生成的草稿中，有多大比例可以由人工直接发布，无需重写。批准率较低，通常说明问题出在 prompt 和源文档，而不是模型。

编辑距离。审核人员在发布之前修改了多少内容。编辑距离不断上升，意味着质量正在发生偏移。

每篇已发布内容的成本。用记录的 usage 除以实际发布的内容数量，同时把最终被丢弃的草稿成本也计算在内。

生成内容与人工撰写内容的互动表现对比。这才是诚实的检验方式。

我需要自己的 Anthropic 或 OpenAI API key 吗？

不需要。文本、图片和视频生成都通过 Cosmic API 运行，使用的是 Bucket write key。模型使用额度已经包含在方案配额中。

可以使用哪些模型？

可以使用 Claude、Gemini、OpenAI 和 Moonshot Kimi 模型，通过 model 参数选择。默认模型是 claude-opus-5。完整列表可以在 AI API 文档中查看。

AI 能读取我现有的文件吗？

可以。通过 media_url 指向 Bucket 中的任意文件，包括图片、PDF、Excel 电子表格、Word 文档等。

Cosmic 提供 GraphQL API 吗？

不提供。Cosmic 提供 REST API，以及 JavaScript/TypeScript SDK：@cosmicjs/sdk。

不写代码也能运行这套流程吗？

可以，可以通过 MCP server 或 dashboard 中的 AI 功能实现。代码方案则可以为你提供定时调度和可重复执行能力。

生成内容会损害我的 SEO 吗？

未经审核的内容会。第 5 步设置审核关卡，正是出于这个原因。只发布经过人工验证的内容；凡是无人能够找到来源的内容，都应该删除。

先发布那个朴素的版本

最小但实用的流水线，只需要一份源文档、一个 prompt、一个草稿 Object 和一名审核人员。先把它搭建起来，运行一周；等你信任它的输出之后，再加入定时调度、图片生成和检索能力。

这正是团队自动化内容运营时想要的结果。正如 FINN 联合创始人 Maximilian Wuhr 所说：“Cosmic 意味着：我们再也不必为了修改网站后端的任何内容而去找开发人员。”

你可以免费开始搭建，所有方案都包含 AI 生成功能；也可以预约 20 分钟，与我们的 CEO 讨论你的内容工作流。如果你想要的是交互式版本，则可以接入 Cosmic AI Agent 或 MCP server，从一次对话开始。

对于后续操作，你可以考虑屏蔽此人和/或举报滥用行为。