@8-/gemini-web-api 1.0.0 → 1.0.1

package/README.md

@@ -30,9 +30,16 @@
 
 - **Zero Configuration**: As long as you are logged into [gemini.google.com](https://gemini.google.com) in Chrome (or Brave / Edge), the server automatically extracts and decrypts your tokens. No manual cookie copying or `.env` required!
 - **Dual Runtime Support**: Native ultra-high performance on **Bun** (`Bun.serve`) and seamless native support on **Node.js** (>= 22.5.0, via `node:sqlite` and Web Streams).
-- **Zero External Dependencies**: 100% built on standard Web APIs (`fetch`, `ReadableStream`, `crypto.subtle`) and built-in Node/Bun modules.
-- **OpenAI Drop-in Replacement**: Fully compatible with `/v1/chat/completions` and `/v1/models`. Works seamlessly with ChatGPT-Next-Web, LobeChat, Cherry Studio, OpenAI SDKs, etc.
-- **Reasoning & Thinking Models**: Full streaming support for `<think>` thoughts and `reasoning_content` deltas (compatible with DeepSeek/Gemini thinking UI renderers).
+- **Zero External Dependencies**: 100% built on standard Web APIs (`fetch`, `ReadableStream`, `crypto.subtle`) and built-in Node/Bun modules. Zero `node_modules` required!
+- **OpenAI Drop-in Replacement**: Fully compatible with `/v1/chat/completions` and `/v1/models`. Works seamlessly with ChatGPT-Next-Web, LobeChat, Cherry Studio, Cline, Roo Code, Cursor, Aider, and official OpenAI SDKs.
+- **Robust 4-Tier Tool / Function Calling Engine**:
+  1. **Tier 1 (Fenced Code Blocks)**: Parses ` ```tool_call `, ` ```tool_calls `, ` ```json `, or bare ` ``` ` blocks.
+  2. **Tier 2 (Tool Call Arrays)**: Extracts structured `"tool_calls": [...]` arrays embedded in output.
+  3. **Tier 3 (Unfenced / Broken Fences)**: Recovers missing opening backticks (e.g. `tool_call\n{...}````).
+  4. **Tier 4 (Bare JSON Objects)**: Bracket-matched scanner for raw JSON objects with `name` and `arguments`/`args`/`input`.
+  - **Auto Syntax Healing**: Automatically cleans escaped markdown underscores (`subagent\_type` → `subagent_type`), trailing commas, unquoted keys, and invalid escapes.
+  - **Framework Agnostic**: Natively normalizes tool call formats from Vercel AI SDK, ZCode, LangChain, and OpenAI SDKs (`toolCalls`, `input`, `toolName`, `toolCallId`).
+- **Reasoning & Thinking Models**: Full support for `<think>` thoughts and `reasoning_content` deltas in SSE streaming with an automatic tag closure state machine, as well as `reasoning_content` in non-streaming responses.
 - **Dynamic Model Discovery**: Automatically discovers available Gemini models (Flash, Pro, etc.) and capacity tiers directly from your web session.
 - **Image Proxy**: Built-in `/gemini-proxy/image` endpoint to safely render generated card images without CORS or anti-hotlinking issues.
 
@@ -101,7 +108,7 @@ PORT=8000 API_KEY=sk-mysecret ENABLE_THINKING=true gemini-web-api
 
 ### API Calling Examples
 
-#### Test with cURL (Streaming)
+#### 1. Streaming Chat (cURL)
 
 ```bash
 curl -N http://127.0.0.1:7860/v1/chat/completions \
@@ -115,28 +122,48 @@ curl -N http://127.0.0.1:7860/v1/chat/completions \
   }'
 ```
 
-#### Use with OpenAI Python SDK
+#### 2. Function Calling / Tool Calling (Python SDK)
 
 ```python
 from openai import OpenAI
 
 client = OpenAI(
     base_url="http://127.0.0.1:7860/v1",
-    api_key="none"  # Any string if API_KEY is not set
+    api_key="none"
 )
 
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get current weather for a city.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "city": {"type": "string"}
+                },
+                "required": ["city"]
+            }
+        }
+    }
+]
+
 response = client.chat.completions.create(
     model="gemini-flash",
-    messages=[{"role": "user", "content": "Hello Gemini!"}],
-    stream=True
+    messages=[{"role": "user", "content": "What is the weather in Tokyo?"}],
+    tools=tools,
+    tool_choice="auto"
 )
 
-for chunk in response:
-    content = chunk.choices[0].delta.content or ""
-    print(content, end="", flush=True)
+message = response.choices[0].message
+if message.tool_calls:
+    for tool_call in message.tool_calls:
+        print(f"Tool: {tool_call.function.name}")
+        print(f"Arguments: {tool_call.function.arguments}")
 ```
 
-#### Use with OpenAI Node.js SDK
+#### 3. Streaming Chat with Node.js SDK
 
 ```javascript
 import OpenAI from "openai";
@@ -148,7 +175,7 @@ const openai = new OpenAI({
 
 const stream = await openai.chat.completions.create({
   model: "gemini-flash",
-  messages: [{ role: "user", content: "Tell me a joke." }],
+  messages: [{ role: "user", content: "Tell me a short joke." }],
   stream: true,
 });
 
@@ -173,9 +200,16 @@ for await (const chunk of stream) {
 
 - **开箱即用，零手动配置**：自动探测 Chrome / Brave / Edge 浏览器会话，全自动解密并获取登录令牌，彻底告别手动抓包复制 Cookie 的烦恼！
 - **Bun 与 Node.js 双运行时支持**：在 **Bun** 下使用原生 `Bun.serve` 极速响应；在 **Node.js** (>= 22.5.0) 下利用内置 `node:sqlite` 与原生 Web Streams 同样流畅运行。
-- **零第三方外部依赖**：纯基于 Web 标准接口（`fetch`、`ReadableStream`、`crypto.subtle`）与运行时内置标准模块构建。
-- **无缝替代 OpenAI 接口**：标准 `/v1/chat/completions` 与 `/v1/models` 路由，直接兼容 ChatGPT-Next-Web、LobeChat、Cherry Studio 以及各类 OpenAI SDK。
-- **深度思考与推理模式**：完整支持 `<think>` 思考标签与 SSE `reasoning_content` 流式字段传输，兼容各类思考过程前端渲染。
+- **零第三方外部依赖**：纯基于 Web 标准接口（`fetch`、`ReadableStream`、`crypto.subtle`）与运行时内置标准模块构建，零 `node_modules` 外部依赖！
+- **无缝替代 OpenAI 接口**：标准 `/v1/chat/completions` 与 `/v1/models` 路由，直接兼容 ChatGPT-Next-Web、LobeChat、Cherry Studio、Cline、Roo Code、Cursor、Aider 以及官方 OpenAI SDK。
+- **四级高鲁棒性 Function Calling / 工具调用引擎**：
+  1. **第一级（围栏代码块）**：精确解析 ` ```tool_call `、` ```tool_calls `、` ```json ` 或裸反引号代码块。
+  2. **第二级（数组提取）**：自动提取内嵌于回复中的 `"tool_calls": [...]` 结构体。
+  3. **第三级（缺失开头围栏容错）**：支持缺失开头反引号等残缺输出自愈（如 `tool_call\n{...}````）。
+  4. **第四级（无围栏裸 JSON 深度探测）**：括号平衡算法精确提取包含 `name` 与 `arguments`/`args`/`input` 的独立 JSON 对象，游标防跳步确保多个紧邻调用不遗漏。
+  - **语法自动修复**：自动反转义 Markdown 下划线（`subagent\_type` → `subagent_type`），智能修复未加引号的键名与尾随逗号。
+  - **框架协议泛化**：原生兼容 Vercel AI SDK、ZCode、LangChain 及各类 Agent 框架自定义字段（`toolCalls`、`input`、`toolName`、`toolCallId`）。
+- **深度思考与推理模式**：完整支持 `<think>` 思考标签与 SSE `reasoning_content` 流式字段传输，内置状态机保证思考标签严格闭合，且在非流式调用中完整保留思考链。
 - **动态模型列表发现**：启动时自动从 Gemini 网页端动态拉取已解锁的可用模型及配额层级。
 - **图片安全代理**：内置 `/gemini-proxy/image` 接口，解决 Google 生成图片防盗链和跨域展示问题。
 
@@ -244,7 +278,7 @@ PORT=8000 API_KEY=sk-mysecret ENABLE_THINKING=true gemini-web-api
 
 ### 接口调用示例
 
-#### cURL 流式对话调用
+#### 1. cURL 流式对话调用
 
 ```bash
 curl -N http://127.0.0.1:7860/v1/chat/completions \
@@ -258,7 +292,7 @@ curl -N http://127.0.0.1:7860/v1/chat/completions \
   }'
 ```
 
-#### Python (OpenAI SDK)
+#### 2. 工具调用 / Function Calling (Python SDK)
 
 ```python
 from openai import OpenAI
@@ -268,18 +302,37 @@ client = OpenAI(
     api_key="none"  # 未设置 API_KEY 时可填任意字符串
 )
 
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "查询指定城市的天气温度",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "city": {"type": "string"}
+                },
+                "required": ["city"]
+            }
+        }
+    }
+]
+
 response = client.chat.completions.create(
     model="gemini-flash",
-    messages=[{"role": "user", "content": "你好，Gemini！"}],
-    stream=True
+    messages=[{"role": "user", "content": "查询东京的天气"}],
+    tools=tools,
+    tool_choice="auto"
 )
 
-for chunk in response:
-    content = chunk.choices[0].delta.content or ""
-    print(content, end="", flush=True)
+message = response.choices[0].message
+if message.tool_calls:
+    for tool_call in message.tool_calls:
+        print(f"触发工具: {tool_call.function.name}, 参数: {tool_call.function.arguments}")
 ```
 
-#### Node.js (OpenAI SDK)
+#### 3. Node.js 流式对话 (OpenAI SDK)
 
 ```javascript
 import OpenAI from "openai";