ChatGPT Apps 中的 Search/Fetch 工具标准面向企业知识库与深度研究的只读 MCP 工具规范【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文基于本仓库chatgpt-apps技能集中收录的 Search And Fetch Standard 参考文档系统讲解在 ChatGPT Apps SDKMCP Server Widget应用开发中如何为连接器型connector-like、纯数据型data-only、同步型sync-oriented以及面向企业知识库与深度研究场景的应用落地一套标准化的search与fetch只读工具。读完本文你将掌握这套标准的适用场景判定、精确的工具 Schema 契约、JSON 载荷格式、实现规则与验证清单并能结合仓库源码理解它在完整技能流程中的调用位置。一、这套标准是什么为什么需要统一的search/fetch在 ChatGPT Apps 生态中大量应用本质上是一类只读知识源它们对接文档库、工单系统、Wiki 页面、CRM 记录等企业数据模型需要先搜索找到相关内容再获取某一条记录的完整正文用于引用与回答。如果每个应用都自创一套语义相近但命名和 Schema 各异的检索工具例如query_docs、lookup、get_record模型与宿主就需要为每个应用学习不同的调用方式企业知识库之间的互操作性也无从谈起。为此本技能集定义了一份 search-fetch-standard.md 参考标准在下列场景中作为默认约定加载应用是**纯数据型data-only**应用应用是**同步型sync**应用应用是企业知识源company knowledge source应用需要与深度研究deep research兼容应用是连接器型集成connector-like面向文档、工单、Wiki 页面、CRM 记录等只读数据。默认规则Default Rule标准给出的默认规则非常明确如果应用本质上是只读知识源不要发明search和fetch的自定义等价物默认应精确实现标准化的search与fetch工具只有用例确实需要时才追加其他工具。这一规则意味着search/fetch不是可选的另一种实现而是此类应用的默认工具面default tool surface其他工具只能作为补充不能替代。二、工具契约search与fetch的精确 Schema标准对两个工具分别规定了输入与输出的精确契约这是整套规范中最核心、最需要逐字对齐的部分。search单查询串搜索维度要求工具类型只读read-only输入单个查询字符串a single query string输出恰好一个MCP content 项type: text文本内容JSON 编码的对象包含results字段每条结果含id、title、url三个字段对应的载荷形状示意如下{ results: [ { id: doc-2024-001, title: Internal API Migration Guide, url: https://kb.example.com/docs/doc-2024-001 } ] }注意关键约束输出必须是恰好一个exactly onetype: text的 MCP content 项且其text字段承载的是 JSON 编码后的对象而非 Markdown 文本或纯字符串。fetch按文档 ID 取详情维度要求工具类型只读read-only输入单个文档/条目 ID 字符串输出恰好一个MCP content 项type: text文本内容JSON 编码的对象含id、title、text、url可选字段metadata{ id: doc-2024-001, title: Internal API Migration Guide, text: 本文档描述了从 v1 迁移到 v2 的步骤……, url: https://kb.example.com/docs/doc-2024-001, metadata: { updated_at: 2024-05-01, author: platform-team } }fetch与search的互补关系在于search负责缩小范围、给出候选列表fetch负责按 ID 获取正文全文。模型通常先调用search再对选中的id调用fetch最后以url作为引用来源。三、实现规则四条硬性要求标准为实际编码划定了四条实现规则用于保证工具面的一致性与可引用性Schema 精确匹配当应用面向企业知识库或深度研究兼容时输入输出结构必须与标准完全一致不允许近似、改名或精简字段。使用规范化 URL 用于引用canonicalurlvalues for citations每条结果的url必须是稳定、可被引用的规范地址而不是临时会话链接或易变的内网路径因为模型会直接把这些 URL 当作回答的引用来源。标记为只读两个工具都必须在注解中声明只读语义避免宿主或模型误判其副作用。优先使用精确名称search与fetch不要用同义词如find、retrieve替代确需追加其他只读工具时它们应当**补充complement而非替代replace**标准工具。与仓库源码的对应关系在本仓库中工具注解与只读标记的具体实现方式可以从 scaffold_node_ext_apps.mjs 的registerAppTool调用中看到端倪——脚手架为示例工具设置了完整的annotations集合annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false, idempotentHint: true, }其中readOnlyHint: true正是标记为只读落地到 Apps SDK 注解层的直接体现。实现标准search/fetch时可参照同样的registerAppTool模式来自modelcontextprotocol/ext-apps/server结合 zod 定义输入 Schema如z.string().describe(查询串)并在返回体中用content: [{ type: text, text: JSON.stringify(payload) }]承载 JSON 编码的输出。四、验证清单交付前的五项检查当search与fetch与当前应用相关时标准要求逐一验证以下五项两个工具都存在both tools exist均为只读read-only输入形状与标准匹配input shapes match the standard返回载荷被包装为单个content项且text为 JSON 编码returned payloads are wrapped as onecontentitem with JSON-encodedtext结果 URL 足够规范、可用于引用result URLs are canonical enough for citation use。这五项检查在本仓库中并非孤立存在而是被纳入了更广的验证体系repo-contract-and-validation.md 的最小可运行仓库契约Minimum Working Repo Contract第 3 节明确要求当应用是连接器型、纯数据型、同步型或面向企业知识库/深度研究时必须实现标准search/fetch而非自定义替代品同一文档的验证阶梯Validation LadderLevel 0静态契约审查也把search和fetch是否存在且符合标准形状列为检查点之一该文档还要求交付时明确声明实际到达的验证级别静态审查 / 语法编译 / 本地运行 / 宿主联调把文件建了与应用真能跑区分开。也就是说search/fetch的符合性检查是整套技能在生成或审查 ChatGPT Apps 仓库时的一等公民检查项不是可选加分项。五、在技能流程中的调用位置从判定到落地的完整链路理解这套标准何时被触发、如何被使用有助于读者在实际开发中正确套用。在本仓库的 SKILL.md 中该标准被多处显式引用形成了完整的决策链路初始判定阶段SKILL.md 的 Overview 明确当应用是连接器型、纯数据型、同步型或面向企业知识库/深度研究时读取 references/search-fetch-standard.md工具规划阶段在 Plan Tools Before Code 一节中要求如果是连接器型/纯数据型/同步型/企业知识库/深度研究默认实现标准search与fetch而不是发明自定义只读等价物架构分类阶段配套的 app-archetypes.md 在tool-only原型中明确指出如果应用是连接器型或同步型search与fetch应作为默认只读工具并在选择启发式Selection Heuristic中建议如果提示词是关于知识源、同步应用、连接器型集成或深度研究强烈优先选择tool-only加标准search/fetch工具——除非用户明确需要 Widget 界面契约与验证阶段如上一节所述repo-contract-and-validation.md 在契约与验证阶梯中强制检查其存在性与形状Agent 默认行为层面仓库中的 openai.yaml 将当应用是连接器型或同步型时默认使用标准search和fetch工具写入 Agent 的default_prompt意味着该行为已成为 Agent 的默认策略而非临时建议。从源码结构看这套标准在设计上呈现一处定义、多点引用、全程校验的形态标准本体只维护在单一参考文档中而判定规则、工具规划、架构分类、契约校验与 Agent 默认提示词全部指向它避免了多份文档各自定义造成的不一致。六、实战建议最小可复用的实现思路结合标准契约与仓库脚手架模式scaffold_node_ext_apps.mjs 中registerAppTool的用法给出一个贴合标准的最小实现思路search工具名称search输入query字符串必填注解readOnlyHint: true、destructiveHint: false、openWorldHint: false、idempotentHint: true输出对检索后端返回的结果列表做字段映射确保每条结果只含id/title/url然后返回content: [{ type: text, text: JSON.stringify({ results }) }]。fetch工具名称fetch输入id字符串必填应取自search返回的id注解同search全部只读语义输出组装{ id, title, text, url, metadata? }对象同样以单个type: text的 JSON 编码项返回。需要特别提醒两点实现细节保持一工具一职责search不要顺带返回全文fetch不要顺带返回其他文档的列表职责边界越清晰模型越容易正确编排调用顺序url的规范化是引用质量的生命线在开发阶段就应使用稳定的知识库规范地址如永久链接而不是带会话 token 或易变参数的地址否则模型产出的引用会在后续失效。如果在search/fetch之外确有追加只读工具的需求例如按分类筛选、获取文档版本历史标准允许追加但前提是这些工具补充而非替代标准工具且不影响search/fetch的 Schema 精确匹配。七、标准来源与适用范围说明search-fetch-standard.md 文档末尾注明该标准源自 OpenAI 开发者文档中关于 MCP Server 构建的企业知识兼容性company knowledge compatibility章节以及 MCP 相关文档。在本仓库的 SKILL.md 中与之对应的基线文档页面为apps-sdk/build/mcp-server与apps-sdk/plan/tools——这提示读者标准的具体细节应以当前 OpenAI Apps SDK 官方文档为准本仓库技能集负责在生成代码前引导 Agent 先抓取官方文档通过$openai-docs或 OpenAI 开发者文档 MCP Server见 openai.yaml再按最新文档与本文标准对齐实现。适用边界需要强调的是这套标准只面向只读知识源类应用并非所有 ChatGPT Apps 都适用应用涉及写操作创建工单、修改记录、复杂交互 Widget、需要自定义渲染等场景时不需要强行套用search/fetch判定依据以 app-archetypes.md 的原型分类为准先分类、再决定工具面是技能集一贯强调的顺序Classify The App Before Choosing Code。总结search/fetch工具标准为 ChatGPT Apps 生态中的只读知识源应用提供了一套零协商、零歧义的默认契约统一的命名、统一的输入、统一的 JSON 载荷形状与统一的引用 URL 规范。本仓库通过 search-fetch-standard.md 定义标准本体并通过 SKILL.md、app-archetypes.md、repo-contract-and-validation.md 与 openai.yaml 将其嵌入从分类、规划到校验的完整开发链路。开发者在实现此类应用时只需精确复刻标准 补齐验证五项即可获得与 ChatGPT 企业知识兼容性及深度研究能力开箱即用的互操作基础。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考