用 Sanity Context 给 AI…

当需要为 Sanity 内容搭建可查询、可语义搜索的 AI 聊天机器人或助手时，按此流程完成 MCP 接入、Studio 配置、对话分类与指令调优。

适用场景

解决思路

1. 先收集凭据：Sanity Project ID（在 sanity.config.ts 或 sanity.io/manage 获取）、Dataset 名称（通常为 production）、Sanity API 只读令牌（在项目目录运行 `npx sanity tokens add "Sanity Context" --role=viewer --yes --json`，或在 sanity.io/manage → Project → API → Tokens 创建 Viewer 角色令牌）、LLM API Key（任意支持工具调用的提供商）。
2. 理解核心集成模式：1) 通过 `/initial-context` HTTP 端点获取 schema 上下文并注入系统提示；2) 用 HTTP transport 连接 Sanity Context MCP URL；3) 用 Bearer 令牌认证；4) 从 MCP 客户端获取可用工具并传给 LLM；5) 编写系统提示说明生产智能体的角色、语气与边界。
3. 选择 MCP URL 格式：基础 URL 为 `https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset`（无需文档，可用查询参数配置）；文档 URL 为 `https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset/:slug`（应用某个 Sanity Context 文档的# 配置）。
4. 在 Sanity Studio 中创建 `sanity.agentContext` 类型文档来配置 MCP 端点，包含三个字段：Slug（唯一 URL 标识，成为 MCP URL 中的 `:slug`）、Instructions（领域特定指导，注入到工具描述中）、Content Filter（`groqFilter`，一个 GROQ 表达式，限定智能体可访问的文档范围）。
5. 用 URL 查询参数覆盖文档配置以便测试：`?instructions=<content>` 覆盖指令（用 `?instructions=""` 清空），`?groqFilter=<expression>` 覆盖内容过滤器。
6. 始终获取初始上下文：在 MCP URL 路径后（查询参数之前）追加 `/initial-context`，用相同认证头请求，例如 `curl https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset/:slug/initial-context -H "Authorization: Bearer $SANITY_API_TOKEN"`；获取一次后缓存并注入系统提示，同时从传给 LLM 的工具中排除 `initial_context` 工具以避免重复调用。若无法控制系统提示（如第三方 MCP 客户端），`initial_context` MCP 工具仍会在首条消息时被调用。
7. 使用三个 MCP 工具：`initial_context`（获取压缩的 schema 概览：类型、字段、文档数量）、`groq_query`（执行 GROQ 查询，可选语义搜索）、`schema_explorer`（获取特定文档类型的详细 schema）。开发调试时可用通用 Sanity MCP，但不要用于面向客户的应用。
8. 在写代码前检查项目：读取顶层 `package.json`（检查 `workspaces` 或 `pnpm-workspace.yaml`）、定位 lockfile、梳理各应用/包；确认框架/运行时、AI 库（Vercel AI SDK、LangChain、直接 API 调用等）、领域用途、需要帮助的组件。注意四个组件（Studio 配置、智能体实现、前端、Functions）可能位于不同仓库，只完成可访问的部分并告知用户剩余步骤。
9. 按四步工作流推进并始终展示完整流程：1) 构建智能体（连接 MCP 与 LLM）；2) Studio 配置（配置插件并创建 Sanity Context 文档）；3) 对话洞察（追踪并分类对话）；4) 调优智能体（用调优技能优化指令与系统提示）。每完成一步主动展示下一步，除非用户明确推迟。
10. 可选快速验证：若用户还没有只读令牌，从终端创建（`npx sanity tokens add "Sanity Context" --role=viewer --yes --json`，不在 Sanity 项目目录时加 `--project-id=<id>`），然后测试端点：`curl -X POST https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset -H "Authorization: Bearer $SANITY_API_TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'`。
11. 构建智能体时按框架参考实现：Next.js 见 references/nextjs-agent.md，SvelteKit 见 references/sveltekit-agent.md，其他栈（Express、Remix、Python、LangChain）见 references/adapting-to-stacks.md；系统提示结构见 references/system-prompts.md。核心设置包括 MCP 连接、认证、基础聊天路由；可选包括前端聊天组件（需用 react-markdown 或 marked 渲染 markdown）和高级模式（客户端工具、自动续写、自定义指令渲染）。
12. 配置 Studio：在 Studio 中配置 `@sanity/context/studio` 插件并创建 Sanity Context 文档，详见 references/studio-setup.md。
13. 设置对话洞察（推荐）：1) 遥测——在现有 `streamText` 调用中添加一个集成，将对话记录存入组织的 Context 存储；2) 分类——部署定时函数，用用户自己的 AI SDK 模型分析对话并通过 Context API 记录判定结果。两者都要做，仅遥测只存原始对话，分类才能提取成功分数、情感和内容缺口。详见 references/conversation-classification.md。
14. 调优智能体（推荐）：1) 用 `dial-your-context` 技能调优 Instructions 字段——交互式探索数据集、验证发现、产出简洁指令，说明 schema 无法直接体现的内容（反直觉字段名、二级引用链、数据质量问题、必需过滤器、查询模式），也可配置 `groqFilter` 限定内容范围；2) 可选地用 `shape-your-agent` 技能塑造系统提示（定义语气、边界、护栏），仅在用户控制系统提示时使用。
15. 部署 Sanity Blueprints 与 Functions：先搜索项目中是否已有 `sanity.blueprint.ts`，若已有且函数已部署则把新函数加在那里；否则新建时确保 `sanity.blueprint.ts` 与 lockfile 同目录（CLI 从 lockfile 检测包管理器，无 lockfile 时传 `--fn-installer pnpm`/`npm`/`yarn`），函数 `src` 路径相对 blueprint 文件解析（默认 `functions/<name>/`，可用 `src` 属性指向其他目录）。Monorepo 中 lockfile 在工作区根目录，blueprint 和 functions 也放那里。函数依赖默认用 blueprint 旁的 `package.json`（project-level），也可每个函数有自己的 `package.json`（function-level），但只能二选一。
16. 运行 Blueprint 命令（在含 `sanity.blueprint.ts` 的目录）：`npx sanity blueprints init`（首次初始化）、`npx sanity blueprints promote`（提升到组织范围，定时函数必需）、`npx sanity blueprints doctor`（检查健康）、`npx sanity blueprints plan`（预览部署变更）、`npx sanity blueprints deploy`（部署）、`npx sanity functions env add <fn> <key> <value>`（部署后设置环境变量）、`npx sanity functions logs <name>`（查看日志）、`npx sanity functions test <name> --with-user-token`（本地测试）。
17. 使用语义搜索：在 GROQ 中用 `text::semanticSimilarity()` 做语义排序，例如 `*[_type == "article" && category == "guides"] | score(text::semanticSimilarity("getting started tutorial")) | order(_score desc) { _id, title, summary }[0...10]`，用 `score()` 时始终加 `order(_score desc)` 以获取最佳匹配。
18. 遵循最佳实践：从简单集成开始再添加高级模式；使用描述性字段名（智能体依赖 schema 理解）；GROQ 投影中始终包含 `_id` 以便引用文档；用 `groqFilter` 限定生产智能体可见内容（先宽后窄）；Instructions 保持简洁，只写 schema 未体现的内容，不重复 schema 信息；系统提示明确禁止行为和格式规则，避免过度设计；始终使用最新版 `@sanity/context`（用 `npm info @sanity/context version` 查询），其他包用 `npm info <package> version` 查询。
19. 排障：Sanity Context 报错或无 schema 时确认 Studio 已部署；MCP 返回 401 时重新生成只读令牌；结果为空时检查 `groqFilter` 是否正确、文档类型拼写、是否有匹配的已发布文档；工具不出现时检查 `mcpClient.tools()` 返回值、MCP URL 是否正确、slug 文档是否已发布。

适用边界 · 注意事项

• 需要先有已部署的 Sanity Studio（v5.1.0+）和 Sanity 项目/数据集，纯本地未部署环境无法使用。
• 依赖 Sanity 云服务与付费/账号体系（Sanity 项目、API 令牌、Sanity Context MCP 端点），不是纯本地通用方案。
• 若用户不控制生产智能体的系统提示（如使用第三方 MCP 客户端），则无法注入初始上下文或调优系统提示，只能依赖 `initial_context` 工具自动调用。