shengsuanyun-gemini-api 1.38.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,424 @@
+# 胜算云 Gemini API（适用于 TypeScript 和 JavaScript）
+
+[![NPM 下载量](https://img.shields.io/npm/dw/shengsuanyun-gemini-api)](https://www.npmjs.com/package/shengsuanyun-gemini-api)  
+[![Node 当前版本](https://img.shields.io/node/v/shengsuanyun-gemini-api)](https://www.npmjs.com/package/shengsuanyun-gemini-api)
+
+----------------------
+
+胜算云 Gemini API JavaScript SDK 专为 TypeScript 和 JavaScript 开发者设计，用于构建由 Gemini 驱动的应用程序。
+
+> [!CAUTION]  
+> **API 密钥安全提示：** 切勿在客户端代码中暴露 API 密钥。  
+> 在生产环境中，请使用服务端实现。
+
+## 安装
+
+要安装 SDK，请运行以下命令：
+
+```shell
+npm install shengsuanyun-gemini-api
+```
+
+## 快速入门
+
+最简单的入门方式是使用从 [胜算云]() 获取的 API 密钥：
+
+```typescript
+import { GoogleGenAI } from 'shengsuanyun-gemini-api';
+const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
+
+const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });
+
+async function main() {
+  const response = await ai.models.generateContent({
+    model: 'google/gemini-2.5-flash',
+    contents: '为什么天空是蓝色的？',
+  });
+  console.log(response.text);
+}
+
+main();
+```
+
+### 查询 API Key 额度与使用情况
+
+```typescript
+import { GoogleGenAI } from 'shengsuanyun-gemini-api';
+
+const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
+// 自动使用 Bearer Token 请求 /v1/key
+const quota = await client.quota.getQuota();
+console.log(quota);
+```
+
+## GoogleGenAI 概览
+
+所有 API 功能都通过 `GoogleGenAI` 类的实例访问。子模块将相关 API 方法分组如下：
+
+- [`ai.models`](https://googleapis.github.io/js-genai/release_docs/classes/models.Models.html)：  
+  用于查询模型（`generateContent`、`generateImages` 等）或查看其元数据。
+- [`ai.caches`](https://googleapis.github.io/js-genai/release_docs/classes/caches.Caches.html)：  
+  创建和管理 `caches`，在重复使用相同大型提示前缀时降低成本。
+- [`ai.chats`](https://googleapis.github.io/js-genai/release_docs/classes/chats.Chats.html)：  
+  创建本地有状态的 `chat` 对象，简化多轮对话交互。
+- [`ai.files`](https://googleapis.github.io/js-genai/release_docs/classes/files.Files.html)：  
+  将 `files` 上传到 API 并在提示中引用，减少带宽消耗（尤其适用于多次使用的大文件）。
+- [`ai.live`](https://googleapis.github.io/js-genai/release_docs/classes/live.Live.html)：  
+  启动 `live` 会话进行实时交互，支持文本 + 音频 + 视频输入，以及文本或音频输出。
+
+### 流式响应
+
+为获得更快、更响应式的 API 交互，可使用 `generateContentStream` 方法，它会在生成时逐块返回内容：
+
+```typescript
+import { GoogleGenAI } from '@google/genai';
+const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
+
+const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });
+
+async function main() {
+  const response = await ai.models.generateContentStream({
+    model: 'google/gemini-2.5-flash',
+    contents: '写一首 100 字的诗。',
+  });
+  for await (const chunk of response) {
+    console.log(chunk.text);
+  }
+}
+
+main();
+```
+
+### 函数调用
+
+要让 Gemini 与外部系统交互，您可以提供 `functionDeclaration` 对象作为 `tools`。使用这些工具需遵循以下四步流程：
+
+1. **声明函数名称、描述和参数 JSON Schema**
+2. **调用 `generateContent` 并启用函数调用**
+3. **使用返回的 `FunctionCall` 参数调用实际函数**
+4. **将结果作为 `FunctionResponse` 发回给模型（推荐在 `ai.chat` 中使用历史记录）**
+
+```typescript
+import { GoogleGenAI, FunctionCallingConfigMode, FunctionDeclaration, Type } from '@google/genai';
+const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
+
+async function main() {
+  const controlLightDeclaration: FunctionDeclaration = {
+    name: 'controlLight',
+    parametersJsonSchema: {
+      type: 'object',
+      properties: {
+        brightness: { type: 'number' },
+        colorTemperature: { type: 'string' },
+      },
+      required: ['brightness', 'colorTemperature'],
+    },
+  };
+
+  const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });
+  const response = await ai.models.generateContent({
+    model: 'google/gemini-2.5-flash',
+    contents: '把灯调暗一点，让房间感觉温馨又温暖。',
+    config: {
+      toolConfig: {
+        functionCallingConfig: {
+          mode: FunctionCallingConfigMode.ANY,
+          allowedFunctionNames: ['controlLight'],
+        }
+      },
+      tools: [{ functionDeclarations: [controlLightDeclaration] }]
+    }
+  });
+
+  console.log(response.functionCalls);
+}
+
+main();
+```
+
+#### 模型上下文协议（MCP）支持（实验性）
+
+内置 [MCP](https://modelcontextprotocol.io/introduction) 支持是一项实验性功能。您可以直接将本地 MCP 服务器作为工具传入。
+
+```javascript
+import { GoogleGenAI, FunctionCallingConfigMode, mcpToTool } from '@google/genai';
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+// 创建 stdio 连接的服务器参数
+const serverParams = new StdioClientTransport({
+  command: "npx",
+  args: ["-y", "@philschmid/weather-mcp"] // MCP 服务器
+});
+
+const client = new Client({ name: "example-client", version: "1.0.0" });
+
+// 配置客户端
+const ai = new GoogleGenAI({});
+
+// 初始化客户端与服务器的连接
+await client.connect(serverParams);
+
+// 使用 MCP 工具向模型发送请求
+const response = await ai.models.generateContent({
+  model: "google/gemini-2.5-flash",
+  contents: `今天 ${new Date().toLocaleDateString()} 伦敦的天气如何？`,
+  config: {
+    tools: [mcpToTool(client)], // 使用会话，将自动调用工具
+  },
+});
+console.log(response.text);
+
+// 关闭连接
+await client.close();
+```
+
+### 内容生成
+
+#### 如何构造 `generateContent` 的 `contents` 参数
+
+SDK 允许您在 `contents` 参数中指定以下类型：
+
+##### Content 类型
+- `Content`：SDK 会将单个 `Content` 实例包装为仅包含该实例的数组。
+- `Content[]`：不做任何转换。
+
+##### Part 类型
+
+Part 会被聚合到一个角色为 `'user'` 的 `Content` 中：
+- `Part | string`：SDK 会将 `string` 或 `Part` 包装为角色为 `'user'` 的 `Content` 实例。
+- `Part[] | string[]`：SDK 会将整个列表包装为一个角色为 `'user'` 的 `Content`。
+
+**_注意：_** 此规则不适用于 `FunctionCall` 和 `FunctionResponse` 类型的 Part。如果您使用这些类型，必须显式提供完整的 `Content[]` 结构，明确指出哪些 Part 是由模型或用户“说出”的。否则 SDK 会抛出异常。
+
+## 错误处理
+
+为处理 API 抛出的错误，SDK 提供了 [ApiError](https://github.com/googleapis/js-genai/blob/main/src/errors.ts) 类。
+
+```typescript
+import { GoogleGenAI } from '@google/genai';
+const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
+
+const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });
+
+async function main() {
+  await ai.models.generateContent({
+    model: 'non-existent-model',
+    contents: '写一首 100 字的诗。',
+  }).catch((e) => {
+    console.error('错误名称：', e.name);
+    console.error('错误信息：', e.message);
+    console.error('HTTP 状态码：', e.status);
+  });
+}
+
+main();
+```
+
+## Interactions（交互）（预览版）
+
+> **警告：** Interactions API 目前处于 **Beta 阶段**。这是一个实验性功能的预览版，其功能和结构可能随时发生 **破坏性变更**。
+
+Interactions API 是与 Gemini 模型和智能体交互的统一接口，简化了状态管理、工具编排和长时间运行任务。
+
+更多详情请参见 [官方文档](https://ai.google.dev/gemini-api/docs/interactions)。
+
+### 基础交互
+
+```typescript
+const interaction = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: '你好，你怎么样？',
+});
+console.debug(interaction);
+```
+
+### 有状态对话
+
+Interactions API 支持服务端状态管理。您可以通过引用 `previous_interaction_id` 继续对话。
+
+```typescript
+// 第一轮
+const interaction1 = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: '你好，我叫 Amir。',
+});
+console.debug(interaction1);
+
+// 第二轮（传入 previous_interaction_id）
+const interaction2 = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: '我叫什么名字？',
+  previous_interaction_id: interaction1.id,
+});
+console.debug(interaction2);
+```
+
+### 智能体（深度研究）
+
+您可以使用如 `deep-research-pro-preview-12-2025` 等专用智能体执行复杂任务。
+
+```typescript
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// 1. 启动深度研究智能体
+const initialInteraction = await ai.interactions.create({
+  input: '研究 Google TPU 的历史，重点关注 2025 和 2026 年。',
+  agent: 'deep-research-pro-preview-12-2025',
+  background: true,
+});
+
+console.log(`研究已启动。交互 ID：${initialInteraction.id}`);
+
+// 2. 轮询结果
+while (true) {
+  const interaction = await ai.interactions.get(initialInteraction.id);
+  console.log(`状态：${interaction.status}`);
+
+  if (interaction.status === 'completed') {
+    console.debug('\n最终报告：\n', interaction.outputs);
+    break;
+  } else if (['failed', 'cancelled'].includes(interaction.status)) {
+    console.log(`失败，状态：${interaction.status}`);
+    break;
+  }
+
+  await sleep(10000); // 等待 10 秒
+}
+```
+
+### 多模态输入
+
+您可以在输入列表中提供多模态数据（文本、图像、音频等）。
+
+```typescript
+// 假设您有一个 base64 字符串
+// const base64Image = ...;
+
+const interaction = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: [
+    { type: 'text', text: '描述这张图片。' },
+    { type: 'image', data: base64Image, mime_type: 'image/png' },
+  ],
+});
+
+console.debug(interaction);
+```
+
+### 函数调用
+
+您可以定义自定义函数供模型使用。Interactions API 负责工具选择，您只需将执行结果返回给模型。
+
+```typescript
+// 1. 定义工具
+const getWeather = (location: string) => {
+  /* 获取指定位置的天气 */
+  return `目前 ${location} 的天气是晴天。`;
+};
+
+// 2. 带工具发送请求
+let interaction = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: 'Mountain View, CA 的天气如何？',
+  tools: [
+    {
+      type: 'function',
+      name: 'get_weather',
+      description: '获取指定位置的天气。',
+      parameters: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'string',
+            description: '城市和州，例如 San Francisco, CA',
+          },
+        },
+        required: ['location'],
+      },
+    },
+  ],
+});
+
+// 3. 处理工具调用
+for (const output of interaction.outputs!) {
+  if (output.type === 'function_call') {
+    console.log(`工具调用：${output.name}(${JSON.stringify(output.arguments)})`);
+
+    // 在此处执行实际函数
+    const result = getWeather(output.arguments.location);
+
+    // 将结果发回模型
+    interaction = await ai.interactions.create({
+      model: 'google/gemini-2.5-flash',
+      previous_interaction_id: interaction.id,
+      input: [
+        {
+          type: 'function_result',
+          name: output.name,
+          call_id: output.id,
+          result: result,
+        },
+      ],
+    });
+
+    console.debug(`响应：${JSON.stringify(interaction)}`);
+  }
+}
+```
+
+### 内置工具
+
+您也可以使用 Google 的内置工具，如 **Google 搜索** 或 **代码执行**。
+
+#### 使用 Google 搜索进行事实核查
+
+```typescript
+const interaction = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: '上一届超级碗谁赢了？',
+  tools: [{ type: 'google_search' }],
+});
+
+console.debug(interaction);
+```
+
+#### 代码执行
+
+```typescript
+const interaction = await ai.interactions.create({
+  model: 'google/gemini-2.5-flash',
+  input: '计算第 50 个斐波那契数。',
+  tools: [{ type: 'code_execution' }],
+});
+
+console.debug(interaction);
+```
+
+### 多模态输出
+
+Interactions API 可生成多模态输出（如图像），但您必须指定 `response_modalities`。
+
+```typescript
+import * as fs from 'fs';
+
+const interaction = await ai.interactions.create({
+  model: 'google/gemini-3-pro-image-preview',
+  input: '生成一张未来城市的图像。',
+  response_modalities: ['image'],
+});
+
+for (const output of interaction.outputs!) {
+  if (output.type === 'image') {
+    console.log(`已生成图像，MIME 类型：${output.mime_type}`);
+    // 保存图像
+    fs.writeFileSync(
+      'generated_city.png',
+      Buffer.from(output.data!, 'base64')
+    );
+  }
+}
+```
+