AI 友好 Headless CMS

这个 pack 装了什么

这个包收齐了五个值得装的 headless 后端，当你要让 AI agent 读或写真实业务数据 —— 内容 / 商品 / 订单 / 用户 —— 又不想自己手写 CRUD 端点时用。

分工是有意的：编辑型内容用 Strapi，商品 + 订单数据用 Medusa / Vendure，任意 SQL 表面用 Directus / Hasura。多数生产系统按主导用例从每行各挑一个。

为什么 headless 对 agent 重要

传统 CMS 吐 HTML，agent 消费 HTML 不行。Headless CMS 吐带类型的 JSON 和 GraphQL schema。差距复利：

• Schema 内省：GraphQL 端点自描述。Agent 调 __schema 就能发现有哪些字段、返回什么、接受什么参数。不用手维护 API 文档
• 写操作安全：REST + GraphQL 端点用输入类型显式声明写操作。Agent 发送前可以校验，server 在传输层就拒绝畸形 payload，而不是写到一半
• 权限：每个工具都自带 RBAC。可以给 agent 限定 token，只读特定内容类型或只能改特定资源，带审计日志
• 多语言 / i18n：Strapi 和 Directus 有一等公民 locale 支持，agent 生成或翻译内容时关键

这些属性就是为什么 headless CMS 对人工内容团队可能过度，但对 agent 驱动的产品往往是正确底座。

一条命令装齐

# 装整个 pack
tokrepo install pack/headless-cms-for-ai

# 或者单装一个后端
tokrepo install strapi
tokrepo install hasura

每个工具装成一段 Docker compose 加一个懂工具 API 表面的 Claude Code skill。Skill 暴露带类型的方法如 strapi.list_articles({ filters })，agent 不用手拼 REST URL。

常见坑

• agent 和 server 间的 schema 漂移：在 admin UI 加内容类型时，agent 本地 schema 缓存就过期。每次会话启动重新内省，或者挂 webhook 让 agent 在内容类型变化时失效缓存
• agent 的 N+1 查询：agent 倾向一条一条拉。用批量端点（Strapi 的 populate=*，Hasura 的嵌套选择），并控制查询预算 —— 设 agent 级别的限流
• public 读 token：很容易就给 agent 开宽口读 token。别。范围限定到具体 collection，角色变化时撤销。这五个工具都有细粒度权限 UI
• 写操作幂等性：agent 会重试。如果 agent 在网络波动后重试 createOrder，你会拿到重复。用幂等 key（Medusa 原生支持，其他要叠 request_id 字段）
• 备份：Headless CMS 集中内容，数据库坏了你丢一年编辑工作。在让 agent 写入生产之前先建好每日快照

常见误解

• 「Hasura 和 Directus 可互换」：「把 SQL 暴露成 GraphQL」上重叠，但受众不同。Hasura 是给想要 Postgres 之上薄 GraphQL 蒙皮的工程师；Directus 是给团队还要内容 admin UI 的。只要 API 用 Hasura；非工程师要编辑数据用 Directus
• 「Strapi 能替代 Medusa 做电商」：Strapi 处理内容很漂亮，但缺订单工作流 / 支付 / 库存原语。这些用 Medusa 或 Vendure，然后让 Strapi 管商品邻接的内容（博客 / 营销页）
• 「agent 用 GraphQL 永远比 REST 好」：有时是 —— schema 内省很爽。但对简单 list/get，REST 端点更易缓存、更易让 agent 用 HTTP 层工具组合。五个工具都说两种；按调用挑

跟其他 pack 的关系

• Postgres for Agent是 Hasura 和 Directus 下面的数据层
• MCP 服务器全家桶包含这些 CMS 的 MCP 包装，让 agent 通过 MCP 而不是裸 HTTP 用
• AI 应用生成器从前端侧消费这些 GraphQL 端点