gemini-agent-dev-support

Gemini API 开发技能

1. 规划阶段（定义前）

在提出实施计划之前，必须核实并确认以下架构约束：

• 不依赖记忆：查询 Docs MCP search_docs，或参考 llms.txt 获取最新的 SDK 规范。
• SDK 导入：严格使用 @google/genai（JS/TS）或 google-genai（Python）。绝不导入旧版 SDK。
• 来源：Web 应用必须在本地开发服务器上运行（例如 localhost）。绝不可通过 file:// 执行。
• 凭据策略：API 密钥和凭据必须保存在服务器端／后端代理中。绝不可在客户端代码中暴露密钥。
• 时间锚定：计划必须包含动态注入系统指令中的时间。
• 不使用模拟：必须禁用或隐藏不具备实际功能的元素。生产代码路径中不得使用静态占位响应。

---

2. 编码与调试阶段（标准模式）

始终使用以下简洁代码模式，生成的生产代码中不要添加注释：

A. IME 与发送事件

input.addEventListener('keydown', (e) => {
  if (e.key === 'Enter') {
    if (e.isComposing || e.keyCode === 229) return;
    if (!e.shiftKey) {
      e.preventDefault();
      handleSend();
    }
  }
});

• 发送后立即清空 input.value。
• 当 loading === true 时，禁用输入元素和发送按钮。
• 如果 input.value.trim() === ""，则阻止发送。
• 语音输入：实现实际的麦克风权限请求、UI 状态指示（聆听、错误、重试）以及文本输入回退方式。绝不要使用无实际功能的静音麦克风图标占位符。

B. 模型选择与时间感知

new GoogleGenAI({}).models.list();

const systemInstruction = `Current local time: ${new Date().toLocaleString()}`;

// API Key Validation (verify by listing models via SDK)
async function validateApiKey(apiKey) {
  try {
    const ai = new GoogleGenAI({ apiKey });
    await ai.models.list();
    return true;
  } catch {
    return false;
  }
}

C. 工具组合（Gemini 2.x 与 3.x）

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});

function adaptGenerateContent(options) {
  // call tools seperately
  // call official tools seperately
}

function withOfficial(options) {
  // append official tools
}

async function callGemini(modelName, userInput, tools = [], enableSearch = false) {
  const options = {
    model: modelName,
    contents: userInput,
    config: { tools }
  }
  return checkAllowToolCombine(modelName) ?
    await adaptGenerateContent(options) :
    await ai.model.generateContent(options);
}

• 工具锚定：动态更新 systemInstruction。如果搜索已禁用，则追加："Tool google_search is disabled. Do not attempt to call it."

D. 工具错误处理

{
  "functionResponse": {
    "name": "unknown_or_failed_tool",
    "response": {
      "error": "Error message for model auto-correction."
    }
  }
}

• 工具执行出错或工具名称未知时，绝不要直接抛出错误。返回上面的结构化错误 JSON。

E. 历史记录架构

• 历史记录对象中不得包含复数形式的 functionCalls 字段。将每个单独的 functionCall 映射到对应的 functionResponse。
• 在对话循环中保留 thought、signature（位于交互上下文中）以及服务器端工具上下文。

F. 错误处理与安全渲染

{
  "error": {
    "code": "API_LIMIT_EXCEEDED",
    "message": "Friendly error summary in Traditional Chinese.",
    "details": {
      "status": 429,
      "reason": "rate_limit_exceeded",
      "debug_info": "Debug stack trace without API keys."
    }
  }
}

import { marked } from 'marked';
import DOMPurify from 'dompurify';

const safetyHtml = DOMPurify.sanitize(marked.parse(markdown));

---

输出格式

验证日志

• Docs MCP / 技能查询链接：[例如 search_docs 查询]
• 模型：[例如 gemini-2.5-flash]

检查清单

ID	项目	结果	证据
S1	SDK / 工具链	PASS / FAIL / N/A	[代码行或测试截图链接]

代码更改

• [file path]：[更改说明]

冒烟测试输出

[test execution logs]

剩余风险

• [尚未测试的功能、代理，或“无”]

防止问题复发

• [说明防护机制：规则 / Hook / 测试 / 技能 / “不需要”及原因]