retrieving-developer-knowledge

Google Developer Knowledge

Developer Knowledge 技能可通过 Developer Knowledge MCP 服务或 REST API 回退方式，访问 Google Cloud、AI/ML（ai.google.dev、ADK、TensorFlow）、Android、Chrome、Web、Flutter、Go、Firebase 及其他 Google 开发者平台的官方开发者文档。

工作流

1. 直接检索：回答技术问题时，直接在当前对话上下文中执行一次文档查询（不要委托子 Agent 检索）：
   • 如果环境中存在 MCP 工具：调用 answer_query（适用于概念指南／工作流）或 search_documents（适用于 CLI 标志／语法）。
   • 如果不存在 MCP 工具：通过 curl 对 https://developerknowledge.googleapis.com/v1 发起 REST API 请求。
   • 声明了服务并不代表已连接服务。 某些客户端无法与此服务完成 MCP 握手，因此不会暴露任何 answer_query、search_documents 或 get_documents 工具，即使插件声明了这些工具也是如此。请将工具缺失视为正常情况，并使用下方的 REST 回退方式。
2. 使用查询结果前，先确认查询成功：收到响应并不代表已经获得答案。PERMISSION_DENIED、UNAUTHENTICATED、HTTP 401 或 403、空结果集或任何错误负载，都表示查询失败，即使工具本身没有报告错误也是如此。查询失败时，不要假装查询成功后再作答。
   • 速率限制（HTTP 429／超出配额）：如果调用 answer_query 或 REST :answerQuery 端点返回 HTTP 429（RESOURCE_EXHAUSTED／超出配额错误），这表示服务端生成式问答配额已耗尽。不要将其视为不可恢复的失败，也不要退回到未经检索验证的记忆；应立即使用搜索端点重试（MCP 使用 search_documents，REST 使用 documents:searchDocumentChunks），并从查询中选取 2–5 个有针对性的关键词。
   • 持续失败：尝试一次另一种传输方式；如果仍然失败，请在回复中明确告知用户无法访问 Developer Knowledge，且回答内容未使用该服务。将回忆中的文档内容冒充为检索结果是最糟糕的做法，因为回复中没有任何内容能让人区分它与真实的查询结果。
3. 立即提供完整解决方案：收到文档响应后，立即在回复正文中提供完整、独立且可执行的技术解决方案（包含所有必需标志和占位符的命令、YAML/JSON 配置或代码片段）。

工具选择与使用

根据当前运行环境中可用的工具选择合适的工具：

1. Developer Knowledge MCP 工具（首选）

如果当前工具定义中存在 MCP 工具：

• answer_query(query="...")：用于概念指南、架构比较、产品选择概览和多步骤工作流。此工具的配额有限。如果遇到 429 超出配额错误，请改用 search_documents。
• search_documents(query="...")：用于细粒度 CLI 标志、精确语法、参数名称和 IAM 权限（service.resource.verb）。请使用 2–5 个有针对性的关键词（例如 cloud run filestore nfs mount gcloud），而不要输入完整的对话式句子。
• get_documents(names=["documents/{uri_without_scheme}"])：按资源名称获取完整文档页面（例如 names: ["documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run"]）。

2. REST API 回退方案

当 MCP 工具不可用时，使用 curl 查询 Developer Knowledge REST API （https://developerknowledge.googleapis.com/v1）。有两种可用的凭据，应按以下顺序尝试。

现有 Google 凭据，优先使用。 如果 gcloud 已通过身份验证，请传递 bearer 令牌和配额项目。无需安装或配置任何内容：

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 或任何其他凭据错误），说明该账号的令牌无法通过 API 验证。请在上述命令中将 gcloud auth print-access-token 替换为 gcloud auth application-default print-access-token，然后重试。API 接受哪种凭据取决于环境的身份验证方式，因此遇到身份验证错误时，应尝试使用应用默认凭据，而不是将其视为查询失败。

API 密钥（如果已配置）。 如果环境中设置了 DEVELOPERKNOWLEDGE_API_KEY，请将其作为 key 查询参数传递，而不是放在 Authorization 标头中。如果两种凭据都不可用，此客户端支持的方式是使用 API 密钥：按照 Developer Knowledge 快速入门启用 API 并创建密钥， 然后将其导出为 DEVELOPERKNOWLEDGE_API_KEY。请说明你需要凭据，而不要在未查询的情况下作答。本节其余示例均使用这种方式：

• 回答查询：

  curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery?key=${DEVELOPERKNOWLEDGE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"query": "How do I configure public read access on Cloud Storage?"}'
  

  此端点的配额有限。如果遇到 429 配额耗尽错误，请改用 documents:searchDocumentChunks。
• 搜索文档分块（使用 2–5 个有针对性的关键词）：

  curl -s "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=gcloud+logging+metrics+create&key=${DEVELOPERKNOWLEDGE_API_KEY}"
  

• 获取文档：

  curl -s "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key=${DEVELOPERKNOWLEDGE_API_KEY}"
  

• 批量获取文档（使用 GET，每个文档对应一个 names 参数，不带请求正文；每次调用最多 20 个）：

  curl -s -G "https://developerknowledge.googleapis.com/v1/documents:batchGet" \
    --data-urlencode "names=documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run" \
    --data-urlencode "names=documents/docs.cloud.google.com/storage/docs/creating-buckets" \
    --data-urlencode "key=${DEVELOPERKNOWLEDGE_API_KEY}"
  

综合与输出指南

1. 以官方文档为依据：所有解决方案都必须直接基于检索到的文档。官方文档规范优先级绝对高于记忆中的默认设置。
2. 精确设置参数格式：按照 Google 官方规范设置 CLI 标志、复合键（例如 location=IP:PATH）和 IAM 权限字符串。
3. 在最终回复中提供完整解决方案：始终在最终消息中直接给出完整、独立且可执行的技术解决方案（命令、配置或代码片段），并使用清晰的标准占位符（例如 PROJECT_ID、SERVICE_NAME、REGION），即使此前在内部规划中已经提及。

参考资料

• MCP 用法与工具详情
• REST API 回退指南
• 支持的网域与范围限定