gemini-smart-search — gemini-smart-搜索

Gemini Smart 搜索

Use this 技能 when Gemini should be the 搜索 backend, but gateway-level 网页_搜索 config is too static or too disruptive to change.

Purpose

This 技能 is a script-backed 搜索 工作流, not a gateway 工具 override.

It exists to provide:

dynamic Gemini 模型 selection quota-aware fallback a separate Gemini API key path if desired structured JSON 输出 no gateway re启动 requirement for 模型 changes Modes

模型 routing is split into two layers:

display chAIn: human-facing preferred 模型 family labels candidate API ids: the actual 模型 ids to probe, especially for 3.x preview-era 模型s

Current display chAIns:

cheap Prefer gemini-2.5-flash-lite Then gemini-3.1-flash-lite Then gemini-2.5-flash balanced Prefer gemini-2.5-flash Then gemini-3-flash Then gemini-2.5-flash-lite deep Prefer gemini-3-flash Then gemini-2.5-flash Then gemini-3.1-flash-lite

For 3.x 模型s, do not assume the UI label is the raw API id. Probe candidate ids such as preview-suffixed names when needed.

Invocation

运行 the Python script or the shell wr应用er via exec and 请求 JSON 输出.

Python is now the canonical entrypoint because it also loads repo-local .env.local when present. The shell wr应用er remAIns a convenience layer.

Primary example (preferred):

python3 技能s/gemini-smart-搜索/scripts/gemini_smart_搜索.py \ --查询 "BoundaryML 上下文 engineering" \ --mode cheap \ --json

Wr应用er example (convenience only):

bash 技能s/gemini-smart-搜索/scripts/gemini_smart_搜索.sh \ --查询 "BoundaryML 上下文 engineering" \ --mode cheap \ --json

python -m gemini_smart_搜索 may work when 运行 from the scripts/ directory, but it is not a supported interface for 代理s right now. Do not depend on it.

输出 contract

Expect JSON with at least:

ok 查询 mode 模型_used fallback_chAIn display_chAIn answer citations error escalation

Notes:

模型_used is the actual probed API 模型 id (for example gemini-3-flash-preview), not the human-facing display label. Citation URLs may initially be Google/Vertex grounding redirect URLs instead of canonical source URLs; treat that as a known current limitation. With --json, supported 运行time paths should return structured JSON on 机器人h 成功 and error. Invalid 命令行工具 arguments now also return JSON when --json is present. API key policy

The script should prefer a dedicated key path for this 技能, then fall back to the standard Gemini key.

Required key resolution order:

SMART_搜索_GEMINI_API_KEY (primary declared env) GEMINI_API_KEY (compatibility fallback)

If neither key is present, the 代理 must explicitly ask the human for a Gemini API key before clAIming 设置up is complete.

Do not store the key in 追踪ed 仓库 files. Prefer a repo-local, gitignored file such as .env.local.

See references/config.md.

When to use this 技能 instead of built-in 网页_搜索

Use this 技能 when:

you want Gemini-only 搜索 you want to test or isolate quota pools you want 模型 routing without touching gateway config you want predictable JSON 输出 for down流 orchestration

Do not use this 技能 when:

a normal built-in 网页_搜索 is sufficient you need non-Gemini 提供者s you only need to fetch and read a known URL (网页_fetch) you need 记录ged-in or JS-heavy page interaction (browser) Fallback policy

Fallback only for errors like:

quota exceeded / 429 模型 unavAIlable transient up流 失败

Do not silently fallback on obvious local/script bugs or invalid arguments.

References references/config.md — 环境 variables and de签名 notes references/qa-test-plan.md — focused QA scope for v1 behavior and release gates references/qa-结果s-2026-03-12.md — 命令行工具-oriented QA outcomes from the current release cycle references/代理-qa-cases.md — adversarial 代理-style misuse review references/模型-id-recon.md — verified callable Gemini 模型 IDs and m应用ing notes references/escalation-de签名.md — when to return a GitHub issue URL for human escalation references/release-检查列出.md — artifact release 检查列出 with current completion 状态 references/development-goals-v0.1.1.md — next small version scope and artifact policy references/release-notes-v0.1.1.md — release notes for the current artifact as设置s/example-输出.json — expected 响应 shape scripts/smoke_test.sh — non-destructive local smoke 检查s for the scaffold scripts/prepare_artifact.sh — deterministic 清理 artifact 导出 辅助工具 状态

Python implementation is now wired for a first real version:

direct Gemini API call path Google 搜索 grounding enabled mode-based 模型 routing Python-side repo-local .env.local loading fallback across Gemini Flash-Lite / Flash variants for retryable up流 errors structured JSON 输出 for orchestration

This is still intentionally minimal: it does not yet expose advanced tuning flags, caching, or richer citation post-processing.

Before publishing an artifact, consult references/release-检查列出.md, review references/development-g