Google Developer Knowledge Skill让 Agent 通过 MCP 与 REST API 检索官方 Google 开发者文档的实战指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本指南深入解析本仓库中skills/developers/retrieving-developer-knowledge这一 Agent Skill 的设计与用法它让 AI Agent 能够跨 Google Cloud、AI/Gemini、Android、Chrome、Flutter、Go、Firebase 等平台通过 Developer Knowledge MCP 服务器answer_query、search_documents、get_documents或 Developer Knowledge REST API 兜底方案检索、合成并落地输出官方开发者文档中的技术答案。读完本文你将掌握该 Skill 的完整工作流、三种 MCP 工具与四个 REST 端点的精确调用方式、两套认证协议的选择逻辑以及如何在答案中保证检索结果 100% 优先于记忆的可信输出规范。一、Skill 定位面向 Google 全系开发者文档的检索中枢retrieving-developer-knowledge是发布在 skills/developers/retrieving-developer-knowledge/SKILL.md 的官方 Agent Skill其 Frontmatter 中声明了明确的适用边界能力范围搜索、检索并综合 Google 官方开发者文档覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 及其他 Google 开发者平台集成方式优先集成 Developer Knowledge MCP 服务器search_documents、get_documents、answer_query无法连入时退化为 Developer Knowledge REST API典型触发场景查找 gcloud CLI 命令、API 语法、IAM 权限、官方文档、架构对比或产品选型概览明确不适用场景本地文件系统查询、非 Google 官方文档。该 Skill 的 MCP 服务器声明为https://developerknowledge.googleapis.com/mcpstreamable-http 类型在仓库中的插件配置里可以看到完整登记plugins/cloud/google-cloud-developer/mcp.json定义了developer-knowledge服务器plugins/cloud/google-cloud-developer/mcp_config.json记录了serverUrl而plugins/cloud/google-cloud-developer/gemini-extension.json进一步标注了authProviderType: google_credentials说明该服务器在 Gemini 扩展场景下使用 Google 凭据完成鉴权。Skill 文档、MCP 配置与插件元数据共同构成了一条技能定义 → 服务器登记 → 鉴权方式的完整链路这正是 Agent 运行时发现并连入该能力的基础。二、核心工作流三步完成一次可信检索SKILL.md 将整个检索过程收敛为三个明确的步骤每一步都带有防幻觉约束1. 直接检索Direct Retrieval回答技术问题时在当前对话上下文内直接执行一次文档检索不要把检索委托给子 Agent。传输方式按运行时环境降级选择环境中存在 MCP 工具概念性指南/工作流调用answer_queryCLI 标志位/语法细节调用search_documents环境中不存在 MCP 工具用curl直接请求https://developerknowledge.googleapis.com/v1的 REST API关键认知已声明的服务器 ≠ 已连接的服务器。部分客户端无法与这台服务器完成 MCP 握手即便插件声明了developer-knowledge运行时也可能完全没有暴露answer_query、search_documents、get_documents任何一个工具。Skill 明确要求把这种情况视为正常直接落入 REST 兜底方案而不是卡死在 MCP 上重试。2. 确认检索成功后再使用Confirm the lookup succeeded这是整个 Skill 最强调可信度的一步返回了响应并不等于检索成功。以下任何情况都判定为 FAILED lookup即使工具本身没有报错PERMISSION_DENIED、UNAUTHENTICATED错误HTTP 401 / 403空结果集任何错误 payload。失败时的纪律不能当作成功来作答换另一种传输方式再试一次如 MCP 失败换 REST再次失败则必须在回复中向用户明说无法连上 Developer Knowledge本次答案未经过检索。文档特别强调把记忆中的文档伪装成检索结果是最坏的结果——因为没有任何机制能让用户在回复中区分真检索与伪检索这直接摧毁了输出的可信度。3. 立即输出完整可执行的解决方案收到文档响应后立刻把完整的、自包含的、可直接执行的技术方案带全部必需标志位与占位符的命令、YAML/JSON 配置或代码片段直接输出到回复正文中不要只给摘要或间接转述。三、MCP 工具详解三个工具的职责分工当 MCP 工具出现在运行时工具定义中时按 references/mcp-usage.md 的分工使用1.answer_query(query...)入参自然语言问题职责概念性指南、架构对比、产品选型概览、多步骤工作流返回服务端 RAG 合成后的回答附带来源引用source citations便于追根溯源。2.search_documents(query..., page_size5)入参查询串 分页大小职责细粒度的 CLI 标志位、精确语法、参数名、IAM 权限格式service.resource.verb返回命中的相关文档文本块每项包含content字段与parentURI 字段查询技巧使用 25 个聚焦关键词如cloud run filestore nfs mount gcloud不要写完整口语化长句——块检索对关键词型查询更有效。3.get_documents(names[documents/{uri_without_scheme}])入参资源名数组names格式为去掉 scheme 的文档路径职责按资源名拉取整篇文档页面的完整 Markdown 内容命名示例若父 URI 为https://cloud.google.com/run/docs/deploying则传入names: [documents/cloud.google.com/run/docs/deploying]——即去掉https://前缀。从实现细节看get_documents对应 REST 的batchGet语义按资源名批量取整页search_documents对应searchDocumentChunks按关键词取相关块answer_query对应answerQuery服务端 RAG 合成。理解这层对应关系有助于在 MCP 与 REST 两种传输之间平滑迁移。四、REST API 兜底方案零依赖的 curl 实战当 MCP 工具缺失时references/api-fallback.md 给出了完整的 REST 兜底规范核心纪律是不要猜命令不要依赖未经校验的预训练记忆。服务概况与端点清单Base URLhttps://developerknowledge.googleapis.comAPI 版本v1GA与v1alpha输出格式JSON内含 Markdown 内容块端点方法用途/v1:answerQueryPOST宽泛概念问答、多步骤指南/v1/documents:searchDocumentChunksGET精确语法、IAM 权限、CLI 标志位/v1/documents/{URI_WITHOUT_SCHEME}GET按资源名取整篇文档/v1/documents:batchGetPOST一次往返批量取多篇文档认证协议两种凭据的优先级方式一现有 Google 凭据推荐零安装零配置# 若 gcloud 已认证直接用 Bearer Token 配额项目 curl -s -X POST https://developerknowledge.googleapis.com/v1:answerQuery \ -H Authorization: Bearer $(gcloud auth print-access-token) \ -H X-Goog-User-Project: $(gcloud config get-value project 2/dev/null) \ -H Content-Type: application/json \ -d {\query\: \How do I configure public read access on Cloud Storage?\}认证失败时的正确动作若遇到 401、403 或任何凭据错误说明该账户持有的 token 不被 API 接受此时应把gcloud auth print-access-token替换为gcloud auth application-default print-access-token重试。API 接受哪种凭据取决于环境的认证方式因此认证错误应视为换应用默认凭据重试的理由而非检索失败。方式二API Key若已配置检查环境变量DEVELOPERKNOWLEDGE_API_KEYfallback 文档同时提到GOOGLE_API_KEY通过查询参数或请求头传递查询参数?key${DEVELOPERKNOWLEDGE_API_KEY}请求头-H X-Goog-Api-Key: ${DEVELOPERKNOWLEDGE_API_KEY}四个端点的完整调用示例① answerQuery概念问答curl -s -X POST https://developerknowledge.googleapis.com/v1:answerQuery?key${DEVELOPERKNOWLEDGE_API_KEY} \ -H Content-Type: application/json \ -d {query: How do I create a custom metric in Cloud Logging?}请求体仅含query字段服务端完成 RAG 检索与合成。② searchDocumentChunks精确语法/权限curl -s https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?querygcloudloggingmetricscreatekey${DEVELOPERKNOWLEDGE_API_KEY}可选查询参数queryURL 编码的搜索词如gcloudloggingmetricscreatefilter按域过滤如data_source docs.cloud.google.compageSize返回块数上限默认 10keyAPI Key。③ get 整篇文档curl -s https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key${DEVELOPERKNOWLEDGE_API_KEY}资源名格式为documents/{去 scheme 的 URI}例如把https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run去掉https://即得documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run。④ batchGet 批量取文档curl -s -X POST https://developerknowledge.googleapis.com/v1/documents:batchGet?key${DEVELOPERKNOWLEDGE_API_KEY} \ -H Content-Type: application/json \ -d {names: [documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run]}请求体为names数组可一次传入多篇文档的资源名节省往返开销。响应处理与合成纪律提取内容解析返回 JSON 中的answer、documentChunks[].content或document.content权威优先检索到的文档对预训练知识具有 100% 优先级——官方文档约定永远压倒模型记忆的默认值上下文防御只综合输出所需的技术方案代码片段、配置、CLI 命令不要把原始 API 响应信封整体倾倒给用户。五、可检索语料范围支持的 Google 开发者域references/supported-domains.md 明确了 Developer Knowledge API 与 MCP 服务器可检索的完整官方文档语料分为四类Google Cloud 与基础设施docs.cloud.google.com官方 Google Cloud 文档、cloud.google.com解决方案与产品、docs.apigee.comApigee API 管理、firebase.google.comFirebase 平台AI 与机器学习ai.google.devGoogle AI for Developers 与 Gemini API、adk.devAgent Development Kit、antigravity.googleProject Antigravity / Gemini CLI、geminicli.comGemini CLI 文档、www.tensorflow.orgTensorFlow移动、Web 与客户端平台developer.android.comAndroid、docs.flutter.devFlutter、dart.devDart、developer.chrome.comChrome 与 Web 扩展、web.dev现代 Web 最佳实践语言、工具与生态go.devGo、developers.google.comGoogle 开发者技术、developers.home.google.comGoogle Home、mapsplatform.google.comGoogle Maps Platform、fuchsia.devFuchsia OS。这 18 个域构成了可搜索、可检索技术内容的完整语料集任何超出该范围的文档都不在检索能力之内Agent 应如实说明而不是假装命中。六、输出规范合成与最终回答的三条铁律SKILL.md 的 Synthesis Output Guidelines 为最终答案的形态定了三条基线扎根官方文档所有解决方案必须直接基于检索到的文档官方文档约定对记忆中的默认值拥有绝对优先权精确参数格式化CLI 标志位、复合键如locationIP:PATH、IAM 权限字符串必须严格按 Google 官方规范格式化不允许按印象简化最终回复输出完整方案即使内部规划阶段已经引用过最终消息仍要输出完整、自包含、可执行的完整技术方案命令、配置或代码并给出清晰的标准占位符如PROJECT_ID、SERVICE_NAME、REGION确保用户可直接复制替换运行。七、在 Agent 架构中的位置与 Skill 发现机制的配合理解本 Skill 在整体 Agent 架构中的位置有助于正确编排调用仓库中的 skills/developers/finding-google-skills/SKILL.md 承担按需发现并加载正确 Google 技能的路由职责——它在请求伊始从远程目录索引中筛选出适用的技能再按 entrypoint 拉取对应 SKILL.md。retrieving-developer-knowledge正是这类被路由到的目标技能之一当用户问题涉及 gcloud 命令、IAM 权限、API 语法、架构对比或产品选型时它负责把记忆替换为检索从官方语料中取回带来源的证据化答案。两者配合的最终效果是发现层解决该用哪个技能检索层解决答案从哪来共同把 Agent 的技术回答从可能出错的记忆升级为可追溯、可执行、符合官方规范的文档检索结果。八、快速上手检查清单场景首选传输调用方式环境已连上 MCPanswer_query概念/工作流类问题环境已连上 MCPsearch_documents(query, page_size5)CLI 标志位、IAM 权限、精确语法环境已连上 MCPget_documents(names[...])按资源名取整篇文档MCP 缺失且 gcloud 已认证REST Bearer Tokengcloud auth print-access-token失败换application-defaultMCP 缺失且已配置 API KeyREST ?keyDEVELOPERKNOWLEDGE_API_KEY环境变量任何检索失败换另一种传输重试一次仍失败则如实告知用户未经过检索准确性的最后防线响应到达 ≠ 检索成功PERMISSION_DENIED/UNAUTHENTICATED/HTTP 401/403/空结果集都是失败失败时宁可明说未连上 Developer Knowledge也不要把记忆伪装成检索结果。深入阅读完整工作流见 SKILL.mdMCP 工具细节见 references/mcp-usage.mdREST 端点与认证协议见 references/api-fallback.md语料域清单见 references/supported-domains.mdMCP 服务器登记与鉴权配置见 plugins/cloud/google-cloud-developer/mcp.json 与 plugins/cloud/google-cloud-developer/gemini-extension.json。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考