dial-your-context

Dial Your Context

帮助用户为 Sanity Context MCP 服务创建 Instructions 字段内容。目标是形成一组简洁的纯增量信息——仅包含 Agent 无法从自动生成的架构中推断出的信息。

此技能适用于 GROQ 模式端点（数据集来源）。对于知识库模式端点，可在 Context 应用中通过解决问题和修复来源来改善回答；请参阅解决知识库问题。

你要构建的内容

Sanity Context MCP 服务已向 Agent 提供：

• 所有文档类型和字段的精简架构
• 效率和准确性方面的指导
• groq_query 工具描述中的 GROQ 查询教程
• GROQ 查询、语义搜索等工具的描述

你要编写的是 Context 应用中 MCP 端点的 Instructions 字段。它会显示在初始上下文顶部的 Context Instructions 标题下方，位于效率、准确性、工具和架构部分之前。它应该只包含架构无法明确说明的内容：

• 反直觉的字段名（例如，body 实际上是一个 slug，hero 是对 mediaAsset 的引用）
• 架构未串联起来的二级引用链（例如，“要查找具有 Dolby Atmos 的产品，请串联 product → productFeature，并匹配功能的 id 字段——架构展示了每一跳，但没有展示完整路径”）
• 架构无法揭示的数据质量问题（例如，“product 类型有一个 features 数组，但它始终为空——请改用 support-product”）
• Agent 必须始终应用的筛选条件（locale、编辑状态字段等）
• 用户确认的已知数据缺失（例如，“未使用 subtitle 字段——请忽略它”）
• 常见用例中架构无法明确说明的查询模式
• 主要方法无效时的备用策略

切勿重复架构已经清楚传达的信息。

前提条件

你需要：

• MCP 端点 URL：https://api.sanity.io/v1/context/organizations/:organizationId/mcp/:endpointName，可在 Context 应用的端点页面查看
• 具有 Context 访问权限的组织 API 令牌（本次会话使用 Viewer 权限即可）

你需要通过端点上的 URL 查询参数测试所有内容，因此本次会话不会触及生产 Agent：

• ?instructions=<URL-encoded>会替换该请求的端点说明。空的 ?instructions= 会提供空白起点（不要写成 ?instructions=""：那会将两个引号字符作为说明发送）
• ?groqFilter=<URL-encoded>会缩小端点已保存的筛选范围：两者会用 && 组合。它不能扩大已保存筛选条件允许的范围

用户会在 Context 应用中保存结果。你不会自行修改端点配置。

**调用工具。**如果未将端点连接为 MCP 服务，请通过 HTTP 调用。将查询参数放在 URL 上：

curl -X POST "$SANITY_CONTEXT_MCP_URL?instructions=" \
  -H "Authorization: Bearer $SANITY_ORGANIZATION_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"groq_query","arguments":{"query":"*[0...3]._type"}}}'

使用 GET $SANITY_CONTEXT_MCP_URL/initial-context 读取初始上下文（架构加说明），并使用相同的认证标头和查询参数。

关键规则

1. **只包含纯增量信息。**如果架构已清楚说明，就不要写入 Instructions。
2. **切勿根据少量样本进行概括。**查询 3 篇文档后断定“字段 X 始终为 null”，是最常见的失败模式。每项声明都必须先与用户核实，才能纳入。
3. **用户最了解自己的数据。**架构对话优先于数据探索。展示架构、提出问题并认真听取回答。
4. **用证据核实每项声明。**对于草稿 Instructions 中的每一行，都要展示支持该行的查询和结果。由用户确认或更正。
5. **保持简洁、客观。**压缩步骤（将发现总结为 Instructions）最容易导致信息丢失或失真。不要进行创造性解读。使用简短的陈述句。

工作流

步骤 1：连接并清空工作区

目标： 建立 MCP 访问权限，设置安全的工作环境。

向用户获取 MCP 端点 URL 和组织令牌（参见前提条件）。

判断是否需要草稿端点。 由于 ?groqFilter= 只能缩小范围，请询问用户端点已保存的 GROQ 筛选条件是什么（可在 Context 应用中查看端点）：

• 没有已保存的筛选条件，或只打算进一步缩小范围： 使用现有端点和 URL 参数进行操作。无需进行其他设置。
• 可能需要扩大范围： 请用户在 Context 应用中创建草稿端点（New MCP endpoint），使用相同的数据集来源，名称可设为 tuning-draft，且不设置 GROQ 筛选条件。创建草稿端点需要在组织和数据集所属项目中拥有 Administrator 或 Developer 角色（项目角色与步骤 7 中更改筛选条件所需的角色相同）。使用草稿端点的 URL 运行会话。生产端点不会受到影响。

在每次调用中都使用空的 ?instructions=，直到测试草稿说明时为止，这样现有说明就不会掩盖仅凭架构会出错的地方。

检查端点是否已有说明（请用户从 Context 应用中复制，或在不带 instructions 参数的情况下获取 /initial-context，并查找 Context Instructions 部分）：

• 如果有，逐字向用户展示现有说明
• 询问：“你想保留其中的哪些内容，还是从头开始？”
• 由用户决定——不要擅自认定现有说明有误
• 如果用户有上一轮会话留下的说明，应逐项验证并完善每项发现，而不是从头开始

运行简单的 GROQ 查询（例如 *[0...3]._type），确认你可以查询数据集。

输出： 确认 MCP 访问正常，已建立安全的工作环境（使用 URL 参数，并在需要时创建草稿端点），并已向用户展示任何现有说明。

步骤 2：模式对话

目标： 通过对话了解数据集，而不只是探索。

获取模式（MCP 会提供）。用清晰的列表向用户展示文档类型：

以下是数据集中的文档类型：

• article（14 个字段）
• author（8 个字段）
• category（5 个字段）
• ...

你的 Agent 需要使用哪些类型？

这是一场对话，不是独白。询问用户：

1. 哪些类型重要？“你的 Agent 需要查询哪些类型？这里面有没有应忽略的内部类型或系统类型？”
2. 哪些信息容易产生误解？“有没有字段名容易让人误解？有没有未使用或已弃用的字段？”
3. 这些类型之间有什么关系？“这些类型如何关联？例如，文章会引用作者吗？通过什么方式关联——直接引用、引用数组，还是其他方式？”
4. 是否需要使用特定筛选条件？“Agent 是否需要始终按区域设置、编辑状态字段或其他条件进行筛选？”
5. 主要内容使用什么语言？ 如果涉及国际化，请明确其模式。

建议使用筛选条件。 端点的 GROQ 筛选条件决定了 Agent 可以访问哪些文档。这是影响很大的设置——它能显著减少干扰，并防止 Agent 查询无关类型。这也是一道硬性边界：筛选条件在服务端生效，因此对话中的任何内容都无法扩大其范围。

筛选条件是 GROQ 筛选表达式（即 *[...] 中的部分），而不只是类型列表。这意味着你可以精确筛选出所需的文档集合：

• 简单类型筛选：_type in ["product", "support-article", "productFeature"]
• 区域设置筛选：_type in ["product", "article"] && lang == "en-us"
• 复杂筛选：_type in ["product", "article"] && lang == "en-us" && defined(title)

不要编写完整查询（*[...]）、投影（{ name, price }）或排序／切片条件：这些会被拒绝或匹配不到任何内容，看起来就像连接出了问题。无需筛选草稿：默认情况下，端点会读取已发布视图。

根据对话内容，提出一个筛选条件：

根据你告诉我的信息，我建议使用以下筛选条件：

_type in ["article", "author", "category", "tag"]

这意味着 Agent 看不到 siteSettings、redirect、migration 等类型。这样合适吗？

立即应用筛选条件。 用户同意后，在后续所有 MCP 调用中添加 ?groqFilter=<URL-encoded expression>。

从这一步开始，所有探索都应使用双方同意的筛选条件。

输出： 对重要类型、已知特殊情况、类型关系和当前筛选条件达成共识。探索生产环境中的 Agent 无法看到的类型没有意义。

步骤 3：预期问题

目标： 获取生产环境中的 Agent 将被问到的具体示例。

询问用户：

人们会向使用此上下文的 Agent 提出哪些问题？请给我 5-20 个示例——越贴近实际越好。

示例可能包括：

• “哪些扬声器支持 Dolby Atmos？”
• “如何解决 WiFi 连接问题？”
• “翻新产品的退货政策是什么？”
• “比较产品 X 和产品 Y 的功能”

这些问题将指导步骤 4 中的探索，并告诉你哪些查询模式确实重要。

对于简单数据集，5 个问题就够了。对于复杂数据集，应尽量获取 15-20 个。

输出： 一份编号排列的预期问题列表。

第 4 步：探索与验证

目标： 使用 MCP 回答每个预期问题，记录哪些方法有效、哪些无效。

第 4–6 步是迭代过程，而不是按顺序执行。 随着探索进行，及时与用户核实发现。不要先探索 15 个问题、起草完所有内容，最后才发现一半的说法站不住脚。

逐个（或按逻辑分组）处理预期问题。针对每个问题：

1. 编写一个 GROQ 查询来回答问题
2. 通过 MCP 运行查询
3. 记录结果——是否有效？数据是否符合预期？
4. 在持续更新的清单中跟踪发现：
   • ✅ 按预期有效（无需说明）
   • ⚠️ 有效，但需要不明显的模式（需要说明）
   • ❌ 失败或返回意外结果（调查后与用户核实）

关键：不要想当然。 如果查询返回空结果或意外数据：

• 不要根据少量样本就断定“此字段始终为空”
• 而应立即询问用户——不要把空字段的发现攒在一起再问：“我查询 X 时得到了 Y。这是预期结果吗？数据实际存在吗？”
• 用户会确认或解释差异

用一个简单的表格跟踪发现：

#	问题	查询	结果	发现
1	“最近的文章”	*[_type == "article"] | order(publishedAt desc)[0..4]	✅ 5 个结果	仅凭架构即可奏效
2	“按作者查找文章”	*[_type == "article" && references(authorId)]	⚠️ 空结果	作者通过 contributors[].person 关联，而非直接引用
3	“仅限指南”	*[_type == "article" && category == "guide"]	❌ 空结果	用户确认：指南的 articleType == "howto"

根据规模调整：

• 简单数据集（3–5 种类型，5 个问题）：此步骤可能需要 10 分钟
• 复杂数据集（50 种类型，20 个问题）：将相关问题分组，系统地探索，但仍要核实每项发现

输出： 一张记录了每个预期问题经核实结果的发现表。

第 5 步：起草说明

目标： 将发现提炼成简洁、准确的说明内容。

查看第 4 步中的发现表。只纳入标记为 ⚠️ 或 ❌ 的项目——也就是需要不明显的模式，或使用直观方法时失败的项目。

按类别将说明写成简短、明确的陈述：

### Rules

- Guides are `article` documents with `articleType == "howto"` — there is no `guide` category
- Always include `[_lang == "en"]` for localized content unless user specifies otherwise

### Schema notes

- `contributors` on `article` is an array of objects with a `person` reference to `author` — not a direct author reference
- `hero` on `article` is a reference to `mediaAsset`, not an image field
- `body` on `page` is a Portable Text array, not a string — use `pt::text(body)` for plain text search

### Query patterns

- Articles by author: `*[_type == "article" && contributors[].person._ref == $authorId]`
- Recent guides: `*[_type == "article" && articleType == "howto"] | order(publishedAt desc)`

### Known limitations

- `subtitle` field on `article` is unused — ignore it
- `relatedArticles` is manually curated and often empty for older content

保持简洁。 每一行都应通过这项测试：“仅凭架构的 Agent 会弄错吗？”如果不确定，就进行测试——尝试在 ?instructions= 为空的情况下回答 2–3 个问题，看看模型会自行弄错什么。这就是实际需要写在这里的内容的经验基准。如果答案是否定的，就删掉。

不要包含：

• 通用 GROQ 语法（教程会介绍）
• 字段列表或类型说明（架构会介绍）
• 响应格式指导（这属于系统提示词；请参阅 shape-your-agent 技能）
• Agent 能够自行推断的内容

输出： 一段说明草稿，通常为 10–40 行，具体取决于数据集的复杂程度。

Step 6：验证声明

目标： 确保草稿中的每一行都有证据支持。

逐行检查草稿中的 Instructions。对于每项声明，向用户展示：

1. **声明：**例如，“article 上的 contributors 是一个包含人员引用的对象数组”
2. **证据：**能够证明该声明的 GROQ 查询及结果
3. 请求确认：“这准确吗？有什么需要补充或更正的吗？”

示例：

声明：“指南是 article 文档，且 articleType == "howto"——没有 guide 类别”

证据：*[_type == "article" && category == "guide"][0...3] → 0 个结果。array::unique(*[_type == "article"].articleType) → ["howto", "news", "opinion"]。

这样正确吗？

如果用户更正某项声明，请立即更新草稿。

如果用户补充新信息（“哦，还有一点你也应该知道……”），请将其加入草稿，并以同样的方式进行验证。

**输出：**经过验证的 Instructions 区块，其中每项声明都已得到用户确认。

第 7 步：部署

**目标：**安全地将 Instructions 和筛选条件应用到生产环境。

向用户展示最终的 Instructions 内容和筛选条件，供其最后审核：

这是最终配置：

筛选条件（GROQ 表达式）：

_type in ["article", "author", "category", "tag"]

Instructions： [最终的 Instructions 区块]

准备好部署了吗？

用户会在 Context 应用中保存配置。请准确告知他们要粘贴的内容：

1. 在 Sanity Dashboard 中打开 Context 应用，并选择 production 端点
2. Instructions 字段：[最终的 Instructions 区块]
3. GROQ filter 字段：[最终的 GROQ 表达式]。新值会替换已保存的值。如果你在已有筛选条件的端点上通过 ?groqFilter= 进行调试，那么你测试的筛选条件是 (<saved filter>) && (<your filter>)，因此请粘贴这个组合表达式。如果用户想移除旧筛选条件，这会扩大测试范围：请先在 draft 端点上重新测试（步骤 1），再保存
4. 保存。更改会在下次连接时生效，无需重新部署 Agent。如果 Agent 缓存了 /initial-context，则 Instructions 的更改会在该缓存刷新时显示

更改 GROQ 筛选条件还要求在每个已连接数据集所属的项目中拥有 Administrator 或 Developer 角色。如果用户保存时遇到 403 错误，则必须由拥有该角色的人进行更改。

请将配置粘贴到 production 端点，而不是让 Agent 指向 draft：端点名称是 URL 的一部分，无法重命名，因此切换端点意味着更改 Agent 的配置。

**保存后，进行验证：**在 production 端点上获取 /initial-context，不要使用任何 instructions 或 groqFilter 参数，并确认 Context Instructions 部分内容一致。运行一个预期问题，确认筛选条件已生效。如果创建了 tuning-draft 端点，请提醒用户可以在 Context 应用中将其删除。

**输出：**Instructions 和筛选条件已应用到 production，并确认运行正常。

调整指南

根据数据集规模调整工作流。小型且清晰的架构可能只需要 5 行 Instructions，也可能完全不需要，这同样是成功。大型架构（50+ 种类型）则需要在步骤 2 中按领域对类型分组，在步骤 3 中准备 15-20 个预期问题，并且最适合使用筛选条件。

会话状态跟踪

在整个会话过程中，持续维护以下内容的心理模型：

- [ ] MCP access verified
- [ ] Working environment set up (URL params, plus a draft endpoint if needed)
- [ ] Existing instructions reviewed (if any)
- [ ] Schema discussed with user
- [ ] Filter agreed and applied
- [ ] Expected questions collected
- [ ] Questions explored and findings tracked
- [ ] Draft instructions written
- [ ] Each claim verified with evidence
- [ ] Instructions and filter saved in the Context app
- [ ] Production deployment verified

此清单用于跟踪进度。请定期与用户分享，让他们了解当前流程进展。