# @gajae-code/ai 中文文档

规范地址：https://npmcn.com/package/%40gajae-code/ai/

版本：0\.21\.0
npm 元数据更新时间：2026-11-16T05:10:59.436Z
中文译文更新时间：2026-11-16T05:13:20.471Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gajae-code/ai
原文对照：https://npmcn.com/package/%40gajae-code/ai/?lang=original
项目主页：https://gajae-code.com/
源码仓库：https://github.com/Yeachan-Heo/gajae-code

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：9.1 MB，568 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2026-05-27T18:45:28.020Z
- 最新版本发布：2026-11-16T05:10:59.081Z
- 近 30 天下载量：8891（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：158（近 12 个月 158 个）

## 中文简介

具有自动模型发现和提供者配置的统一LLM API

## 安装

```sh
npm install @gajae-code/ai
```

也可以使用：`pnpm add @gajae-code/ai`、`yarn add @gajae-code/ai`、`bun add @gajae-code/ai`

## README

# @gajae-code/ai (英语)

统一LLM API,具有自动模型发现,提供商配置,信使和成本跟踪,以及简单的上下文持久性并交接到其他模型的会中.

**说明**: 此库只包含支持调用工具( 函数调用) 的模型, 因为这对于代理工作流程至关重要 .

## 目录

-   [支持供应商](https://npmcn.com/package/%40gajae-code/ai/#readme-supported-providers)
-   [安装](https://npmcn.com/package/%40gajae-code/ai/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40gajae-code/ai/#readme-quick-start)
-   [工具](https://npmcn.com/package/%40gajae-code/ai/#readme-tools)
    -   [定义工具](https://npmcn.com/package/%40gajae-code/ai/#readme-defining-tools)
    -   [处理工具呼叫](https://npmcn.com/package/%40gajae-code/ai/#readme-handling-tool-calls)
    -   [带部分 JSON 的流动工具调用](https://npmcn.com/package/%40gajae-code/ai/#readme-streaming-tool-calls-with-partial-json)
    -   [验证工具参数](https://npmcn.com/package/%40gajae-code/ai/#readme-validating-tool-arguments)
    -   [完整事件](https://npmcn.com/package/%40gajae-code/ai/#readme-complete-event-reference)
-   [图像输入](https://npmcn.com/package/%40gajae-code/ai/#readme-image-input)
-   [思考/反思](https://npmcn.com/package/%40gajae-code/ai/#readme-thinkingreasoning)
    -   [统一接口](https://npmcn.com/package/%40gajae-code/ai/#readme-unified-interface-streamsimplecompletesimple)
    -   [提供者特定选项](https://npmcn.com/package/%40gajae-code/ai/#readme-provider-specific-options-streamcomplete)
    -   [流出思维内容](https://npmcn.com/package/%40gajae-code/ai/#readme-streaming-thinking-content)
-   [停止原因](https://npmcn.com/package/%40gajae-code/ai/#readme-stop-reasons)
-   [处理错误](https://npmcn.com/package/%40gajae-code/ai/#readme-error-handling)
    -   [中止请求](https://npmcn.com/package/%40gajae-code/ai/#readme-aborting-requests)
    -   [中止后继续](https://npmcn.com/package/%40gajae-code/ai/#readme-continuing-after-abort)
-   [API、模型和供应商](https://npmcn.com/package/%40gajae-code/ai/#readme-apis-models-and-providers)
    -   [供应商和模式](https://npmcn.com/package/%40gajae-code/ai/#readme-providers-and-models)
    -   [查询供应商和模式](https://npmcn.com/package/%40gajae-code/ai/#readme-querying-providers-and-models)
    -   [自定义模型](https://npmcn.com/package/%40gajae-code/ai/#readme-custom-models)
    -   [OpenAI 兼容性设置](https://npmcn.com/package/%40gajae-code/ai/#readme-openai-compatibility-settings)
    -   [类型安全](https://npmcn.com/package/%40gajae-code/ai/#readme-type-safety)
-   [交叉处理](https://npmcn.com/package/%40gajae-code/ai/#readme-cross-provider-handoffs)
-   [背景序列化](https://npmcn.com/package/%40gajae-code/ai/#readme-context-serialization)
-   [浏览器使用](https://npmcn.com/package/%40gajae-code/ai/#readme-browser-usage)
    -   [环境变量](https://npmcn.com/package/%40gajae-code/ai/#readme-environment-variables-nodejs-only)
    -   [正在检查环境变量](https://npmcn.com/package/%40gajae-code/ai/#readme-checking-environment-variables)
-   [OAuth 供应商](https://npmcn.com/package/%40gajae-code/ai/#readme-oauth-providers)
    -   [Vertex AI (ADC) (英语)](https://npmcn.com/package/%40gajae-code/ai/#readme-vertex-ai-adc)
    -   [CLI 登录](https://npmcn.com/package/%40gajae-code/ai/#readme-cli-login)
    -   [程序操作](https://npmcn.com/package/%40gajae-code/ai/#readme-programmatic-oauth)
    -   [登录流程示例](https://npmcn.com/package/%40gajae-code/ai/#readme-login-flow-example)
    -   [使用 OAuth 键](https://npmcn.com/package/%40gajae-code/ai/#readme-using-oauth-tokens)
    -   [提供方说明](https://npmcn.com/package/%40gajae-code/ai/#readme-provider-notes)
-   [许可证](https://npmcn.com/package/%40gajae-code/ai/#readme-license)

## 支持供应商

-   **开放AI**
-   **OpenAI 代码提供者** (ChatGPT Plus/Pro订阅,需要OAuth,见下文)
-   **安东尼**
-   **谷歌**
-   **Vertex 大赦国际** (Gemini通过Vertex AI)
-   **迷雾**
-   **格罗克**
-   **心管**
-   **一起来**
-   **月光拍摄** (所需经费) `MOONSHOT_API_KEY`(中文(简体) )
-   **钱范** (所需经费) `QIANFAN_API_KEY`(中文(简体) )
-   **纳米比亚** (所需经费) `NVIDIA_API_KEY`(中文(简体) )
-   **纳诺GPT** (所需经费) `NANO_GPT_API_KEY`(中文(简体) )
-   **拥抱面部推论**
-   **页:1 大赦国际**
-   **威尼斯语** (所需经费) `VENICE_API_KEY`(中文(简体) )
-   **打开路透社**
-   **Kilo 网关** (支持奥奥特) `/login kilo` 或者说 `KILO_API_KEY`(中文(简体) )
-   **列表** (所需经费) `LITELLM_API_KEY`(中文(简体) )
-   **扎西岛** (所需经费) `ZAI_API_KEY`(中文(简体) )
-   **迷你Max 编码计划** (所需经费) `MINIMAX_CODE_API_KEY` 或者说 `MINIMAX_CODE_CN_API_KEY`(中文(简体) )
-   **小美,小美,小美** (所需经费) `XIAOMI_API_KEY`(中文(简体) )
-   **禅穆** (所需经费) `ZENMUX_API_KEY`(中文(简体) )
-   **由 Sionic AI 制作的 OpenGateway** (所需经费) `OPENGATEWAY_API_KEY`(中文(简体) )
-   **毕斯鲁特** (所需经费) `BIZROUTER_API_KEY`(中文(简体) )
-   **玛拉云** (所需经费) `MARA_API_KEY`(中文(简体) )
-   **Quen 门户网站** (支助) `QWEN_OAUTH_TOKEN` 或者说 `QWEN_PORTAL_API_KEY`(中文(简体) )
-   **Cloudflare AI 网关** (所需经费) `CLOUDFLARE_AI_GATEWAY_API_KEY` 和供应商专用网关基址)
-   **奥拉玛** (本地 OpenAI 兼容运行时间; 可选) `OLLAMA_API_KEY`(中文(简体) )
-   **奥巴马云** (主办当地Ollama API;要求) `OLLAMA_CLOUD_API_KEY`(中文(简体) )
-   **拉玛.cpp** (本地 OpenAI 和 Anthropic 兼容推论服务器)
-   **vLLM 数据** (OpenAI兼容服务器; `VLLM_API_KEY` (用于安全部署)
-   **GitHub 副驾驶** (要求OAuth,见下文)
-   **谷歌双子座CLI** (要求OAuth,见下文)
-   **反重力** (要求OAuth,见下文)
-   **任意 OpenAI 兼容的 API**: LM Studio,自定义代理等.

## 安装

```bash
npm install @gajae-code/ai
```

## 快速启动

```typescript
import { z, getModel, stream, complete, Context, Tool } from "@gajae-code/ai";

// Fully typed with auto-complete support for both providers and models
const model = getModel("openai", "gpt-4o-mini");

// Define tools with Zod schemas for type safety and validation
const tools: Tool[] = [
    {
        name: "get_time",
        description: "Get the current time",
        parameters: z.object({
            timezone: z
                .string()
                .optional()
                .describe("Optional timezone (e.g., America/New_York)"),
        }),
    },
];

// Build a conversation context (easily serializable and transferable between models)
const context: Context = {
    systemPrompt: ["You are a helpful assistant."],
    messages: [{ role: "user", content: "What time is it?" }],
    tools,
};

// Option 1: Streaming with all event types
const s = stream(model, context);

for await (const event of s) {
    switch (event.type) {
        case "start":
            console.log(`Starting with ${event.partial.model}`);
            break;
        case "text_start":
            console.log("\n[Text started]");
            break;
        case "text_delta":
            process.stdout.write(event.delta);
            break;
        case "text_end":
            console.log("\n[Text ended]");
            break;
        case "thinking_start":
            console.log("[Model is thinking...]");
            break;
        case "thinking_delta":
            process.stdout.write(event.delta);
            break;
        case "thinking_end":
            console.log("[Thinking complete]");
            break;
        case "toolcall_start":
            console.log(`\n[Tool call started: index ${event.contentIndex}]`);
            break;
        case "toolcall_delta":
            // Partial tool arguments are being streamed
            const partialCall = event.partial.content[event.contentIndex];
            if (partialCall.type === "toolCall") {
                console.log(`[Streaming args for ${partialCall.name}]`);
            }
            break;
        case "toolcall_end":
            console.log(`\nTool called: ${event.toolCall.name}`);
            console.log(`Arguments: ${JSON.stringify(event.toolCall.arguments)}`);
            break;
        case "done":
            console.log(`\nFinished: ${event.reason}`);
            break;
        case "error":
            console.error(`Error: ${event.error}`);
            break;
    }
}

// Get the final message after streaming, add it to the context
const finalMessage = await s.result();
context.messages.push(finalMessage);

// Handle tool calls if any
const toolCalls = finalMessage.content.filter((b) => b.type === "toolCall");
for (const call of toolCalls) {
    // Execute the tool
    const result =
        call.name === "get_time"
            ? new Date().toLocaleString("en-US", {
                    timeZone: call.arguments.timezone || "UTC",
                    dateStyle: "full",
                    timeStyle: "long",
                })
            : "Unknown tool";

    // Add tool result to context (supports text and images)
    context.messages.push({
        role: "toolResult",
        toolCallId: call.id,
        toolName: call.name,
        content: [{ type: "text", text: result }],
        isError: false,
        timestamp: Date.now(),
    });
}

// Continue if there were tool calls
if (toolCalls.length > 0) {
    const continuation = await complete(model, context);
    context.messages.push(continuation);
    console.log("After tool execution:", continuation.content);
}

console.log(`Total tokens: ${finalMessage.usage.input} in, ${finalMessage.usage.output} out`);
console.log(`Cost: $${finalMessage.usage.cost.total.toFixed(4)}`);

// Option 2: Get complete response without streaming
const response = await complete(model, context);

for (const block of response.content) {
    if (block.type === "text") {
        console.log(block.text);
    } else if (block.type === "toolCall") {
        console.log(`Tool: ${block.name}(${JSON.stringify(block.arguments)})`);
    }
}
```

## 工具

工具使LLMs能够与外部系统交互. 此库使用 **佐德语Name** 具有自动验证功能的类型安全工具定义计划。 Schemas根据需要转换为JSON Schema供供应商使用.

### 定义工具

```typescript
import { z, Tool } from "@gajae-code/ai";

// Define tool parameters with Zod
const weatherTool: Tool = {
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: z.object({
        location: z.string().describe("City name or coordinates"),
        units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
    }),
};

const bookMeetingTool: Tool = {
    name: "book_meeting",
    description: "Schedule a meeting",
    parameters: z.object({
        title: z.string().min(1),
        startTime: z.string().describe("ISO 8601 date-time"),
        endTime: z.string().describe("ISO 8601 date-time"),
        attendees: z.array(z.email()).min(1),
    }),
};
```

### 处理工具呼叫

工具结果使用内容块,可以包括文本和图像:

```typescript
import * as fs from "node:fs";

const context: Context = {
    messages: [{ role: "user", content: "What is the weather in London?" }],
    tools: [weatherTool],
};

const response = await complete(model, context);

// Check for tool calls in the response
for (const block of response.content) {
    if (block.type === "toolCall") {
        // Execute your tool with the arguments
        // See "Validating Tool Arguments" section for validation
        const result = await executeWeatherApi(block.arguments);

        // Add tool result with text content
        context.messages.push({
            role: "toolResult",
            toolCallId: block.id,
            toolName: block.name,
            content: [{ type: "text", text: JSON.stringify(result) }],
            isError: false,
            timestamp: Date.now(),
        });
    }
}

// Tool results can also include images (for vision-capable models)
const imageBuffer = fs.readFileSync("chart.png");
context.messages.push({
    role: "toolResult",
    toolCallId: "tool_xyz",
    toolName: "generate_chart",
    content: [
        { type: "text", text: "Generated chart showing temperature trends" },
        { type: "image", data: imageBuffer.toBase64(), mimeType: "image/png" },
    ],
    isError: false,
    timestamp: Date.now(),
});
```

### 带部分 JSON 的流动工具调用

在流化过程中,工具调用参数在到达时逐渐被解析. 这使得可以在完整参数可用前实时 UI 更新 :

```typescript
const s = stream(model, context);

for await (const event of s) {
    if (event.type === "toolcall_delta") {
        const toolCall = event.partial.content[event.contentIndex];

        // toolCall.arguments contains partially parsed JSON during streaming
        // This allows for progressive UI updates
        if (toolCall.type === "toolCall" && toolCall.arguments) {
            // BE DEFENSIVE: arguments may be incomplete
            // Example: Show file path being written even before content is complete
            if (toolCall.name === "write_file" && toolCall.arguments.path) {
                console.log(`Writing to: ${toolCall.arguments.path}`);

                // Content might be partial or missing
                if (toolCall.arguments.content) {
                    console.log(`Content preview: ${toolCall.arguments.content.substring(0, 100)}...`);
                }
            }
        }
    }

    if (event.type === "toolcall_end") {
        // Here toolCall.arguments is complete (but not yet validated)
        const toolCall = event.toolCall;
        console.log(`Tool completed: ${toolCall.name}`, toolCall.arguments);
    }
}
```

**关于部分工具参数的重要说明 :**

-   期间 `toolcall_delta` 事件, `arguments` 包含部分 JSON 的最佳解析
-   字段可能缺失或不完整 - 在使用前总是检查是否存在
-   字符串值可切入中字
-   阵列可能不完整
-   嵌入物可能部分被填入
-   起码, `arguments` 将是一个空对象 `{}`永远 `undefined`
-   Google供应商不支持函数调用流线. 相反,你会得到一个单身 `toolcall_delta` 带有全部参数的事件.

### 验证工具参数

使用时 `agentLoop`,工具参数在执行前会自动验证您的 Zod 参数计划。 如果验证失败,错误会作为工具结果返回到模型中,使其可以重试.

当执行您自己的工具执行循环时 `stream()` 或者说 `complete()`,使用时 `validateToolCall` 以验证参数,然后将其传递给工具:

```typescript
import { stream, validateToolCall, Tool } from "@gajae-code/ai";

const tools: Tool[] = [weatherTool, calculatorTool];
const s = stream(model, { messages, tools });

for await (const event of s) {
    if (event.type === "toolcall_end") {
        const toolCall = event.toolCall;

        try {
            // Validate arguments against the tool's schema (throws on invalid args)
            const validatedArgs = validateToolCall(tools, toolCall);
            const result = await executeMyTool(toolCall.name, validatedArgs);
            // ... add tool result to context
        } catch (error) {
            // Validation failed - return error as tool result so model can retry
            context.messages.push({
                role: "toolResult",
                toolCallId: toolCall.id,
                toolName: toolCall.name,
                content: [{ type: "text", text: error.message }],
                isError: true,
                timestamp: Date.now(),
            });
        }
    }
}
```

### 完整事件

在助理信件生成过程中释放出的所有流动事件 :

| 事件类型 | 说明 | 密钥属性 |
| --- | --- | --- |
| `start` | 流线开始 | `partial`: 初始助理信件结构 |
| `text_start` | 文本块开始 | `contentIndex`: 内容阵列中的位置 |
| `text_delta` | 收到文本块 | `delta`: 新文本, (中文(简体) ), `contentIndex`页:1 |
| `text_end` | 文本块完成 | `content`:全文, `contentIndex`页:1 |
| `thinking_start` | 思维障碍开始 | `contentIndex`: 内容阵列中的位置 |
| `thinking_delta` | 思维块收到 | `delta`: 新文本, (中文(简体) ), `contentIndex`页:1 |
| `thinking_end` | 思维区块完成 | `content`: 充分思考, `contentIndex`页:1 |
| `toolcall_start` | 工具调用开始 | `contentIndex`: 内容阵列中的位置 |
| `toolcall_delta` | 工具参数流 | `delta`JSON块, `partial.content[contentIndex].arguments`: 部分解析参数 |
| `toolcall_end` | 工具调用完成 | `toolCall`: 完全验证的工具调用 `id`, (中文(简体) ), `name`, (中文(简体) ), `arguments` |
| `done` | 流线完成 | `reason`:停止理性("停止","长度","工具使用"), `message`页:1 |
| `error` | 发生错误 | `reason`: 出错类型 ("错误"或"被放弃"), `error`: 有部分内容的助理信息 |

## 图像输入

有视觉能力的模型可以处理图像. 您可以检查模型是否通过 `input` 属性。 如果将图像传递给非视觉模型,它们会被默默地忽略.

```typescript
import * as fs from "node:fs";
import { getModel, complete } from "@gajae-code/ai";

const model = getModel("openai", "gpt-4o-mini");

// Check if model supports images
if (model.input.includes("image")) {
    console.log("Model supports vision");
}

const imageBuffer = fs.readFileSync("image.png");
const base64Image = imageBuffer.toBase64();

const response = await complete(model, {
    messages: [
        {
            role: "user",
            content: [
                { type: "text", text: "What is in this image?" },
                { type: "image", data: base64Image, mimeType: "image/png" },
            ],
        },
    ],
});

// Access the response
for (const block of response.content) {
    if (block.type === "text") {
        console.log(block.text);
    }
}
```

## 思考/反思

许多模型支持思考/推理能力,在这种能力中,它们可以显示其内部思考过程。 您可以检查模型是否通过 `reasoning` 属性。 如果将推理选项传递给非理性模式,则被默默地忽略.

### 统一接口(流程简便/完整简便)

```typescript
import { getModel, streamSimple, completeSimple } from "@gajae-code/ai";

// Many models across providers support thinking/reasoning
const model = getModel("anthropic", "anthropic-model-sonnet-4-20250514");
// or getModel('openai', 'gpt-5-mini');
// or getModel('google', 'gemini-2.5-flash');
// or getModel('xai', 'grok-code-fast-1');
// or getModel('groq', 'openai/gpt-oss-20b');
// or getModel('cerebras', 'gpt-oss-120b');
// or getModel('openrouter', 'z-ai/glm-4.5v');

// Check if model supports reasoning
if (model.reasoning) {
    console.log("Model supports reasoning/thinking");
}

// Use the simplified reasoning option
const response = await completeSimple(
    model,
    {
        messages: [{ role: "user", content: "Solve: 2x + 5 = 13" }],
    },
    {
        reasoning: "medium", // 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' (xhigh maps to high on non-OpenAI providers)
    }
);

// Access thinking and text blocks
for (const block of response.content) {
    if (block.type === "thinking") {
        console.log("Thinking:", block.thinking);
    } else if (block.type === "text") {
        console.log("Response:", block.text);
    }
}
```

### 供应商 -- -- 特定选项(流程/完成)

对于精细的控件,使用特定提供者选项:

```typescript
import { getModel, complete } from "@gajae-code/ai";

// OpenAI Reasoning (o1, o3, gpt-5)
const openaiModel = getModel("openai", "gpt-5-mini");
await complete(openaiModel, context, {
    reasoningEffort: "medium",
    reasoningSummary: "detailed", // OpenAI Responses API only
});

// Anthropic Thinking (Anthropic model Sonnet 4)
const anthropicModel = getModel("anthropic", "anthropic-model-sonnet-4-20250514");
await complete(anthropicModel, context, {
    thinkingEnabled: true,
    thinkingBudgetTokens: 8192, // Optional token limit
});

// Google Gemini Thinking
const googleModel = getModel("google", "gemini-2.5-flash");
await complete(googleModel, context, {
    thinking: {
        enabled: true,
        budgetTokens: 8192, // -1 for dynamic, 0 to disable
    },
});
```

### 流出思维内容

当流出时,思考内容通过特定事件传递:

```typescript
const s = streamSimple(model, context, { reasoning: "high" });

for await (const event of s) {
    switch (event.type) {
        case "thinking_start":
            console.log("[Model started thinking]");
            break;
        case "thinking_delta":
            process.stdout.write(event.delta); // Stream thinking content
            break;
        case "thinking_end":
            console.log("\n[Thinking complete]");
            break;
    }
}
```

## 停止原因

每个 `AssistantMessage` 包含a `stopReason` 字段,表示该世代如何结束:

-   `"stop"` - 正常完成,模型完成反应
-   `"length"` - 输出达到最高值
-   `"toolUse"` - 模型调用工具并期望工具结果
-   `"error"` - 生成时发生错误
-   `"aborted"` - 请求通过中止信号被取消

## 处理错误

当请求以出错(包括中止和工具调用错误)而结束时,流出 API 释放出出一个出错事件 :

```typescript
// In streaming
for await (const event of stream) {
    if (event.type === "error") {
        // event.reason is either "error" or "aborted"
        // event.error is the AssistantMessage with partial content
        console.error(`Error (${event.reason}):`, event.error.errorMessage);
        console.log("Partial content:", event.error.content);
    }
}

// The final message will have the error details
const message = await stream.result();
if (message.stopReason === "error" || message.stopReason === "aborted") {
    console.error("Request failed:", message.errorMessage);
    // message.content contains any partial content received before the error
    // message.usage contains partial token counts and costs
}
```

### 中止请求

中止信号允许您取消进行中的请求 。 中止的请求已 `stopReason === 'aborted'`数字 :

```typescript
import { getModel, stream } from "@gajae-code/ai";

const model = getModel("openai", "gpt-4o-mini");

// Abort after 2 seconds
const signal = AbortSignal.timeout(2000);

const s = stream(
    model,
    {
        messages: [{ role: "user", content: "Write a long story" }],
    },
    {
        signal,
    }
);

for await (const event of s) {
    if (event.type === "text_delta") {
        process.stdout.write(event.delta);
    } else if (event.type === "error") {
        // event.reason tells you if it was "error" or "aborted"
        console.log(`${event.reason === "aborted" ? "Aborted" : "Error"}:`, event.error.errorMessage);
    }
}

// Get results (may be partial if aborted)
const response = await s.result();
if (response.stopReason === "aborted") {
    console.log("Request was aborted:", response.errorMessage);
    console.log("Partial content received:", response.content);
    console.log("Tokens used:", response.usage);
}
```

### 中止后继续

中止的消息可以添加到对话上下文中,并在后续请求中继续:

```typescript
const context = {
    messages: [{ role: "user", content: "Explain quantum computing in detail" }],
};

// First request gets aborted after 2 seconds
const controller1 = new AbortController();
setTimeout(() => controller1.abort(), 2000);

const partial = await complete(model, context, { signal: controller1.signal });

// Add the partial response to context
context.messages.push(partial);
context.messages.push({ role: "user", content: "Please continue" });

// Continue the conversation
const continuation = await complete(model, context);
```

### 常见流选项

所有提供者接受基准 `StreamOptions` (除特定供应商选项外):

-   `apiKey`: 覆盖提供者 API 密钥
-   `headers`: 将额外请求头合并到模型定义头上
-   `sessionId`: 供应商专用会话标识符(即时缓存/路由)
-   `signal`: 中止飞行请求
-   `onPayload`: 在发送前立即与供应商一起请求有效载荷

示例

```typescript
const response = await complete(model, context, {
    apiKey: "sk-live",
    headers: { "X-Debug-Trace": "true" },
    onPayload: (payload) => {
        console.log("request payload", payload);
    },
});
```

## API、模型和供应商

库执行4个API接口,每个接口都有自己的流式功能和选项:

-   **`anthropic-messages`**: Anthropic 信件 API (英语:`streamAnthropic`, (中文(简体) ), `AnthropicOptions`(中文(简体) )
-   **`google-generative-ai`**: Google的Generative AI API (英语:`streamGoogle`, (中文(简体) ), `GoogleOptions`(中文(简体) )
-   **`openai-completions`**: OpenAI的聊天补全API(`streamOpenAICompletions`, (中文(简体) ), `OpenAICompletionsOptions`(中文(简体) )
-   **`openai-responses`**: OpenAI 的回复 API(`streamOpenAIResponses`, (中文(简体) ), `OpenAIResponsesOptions`(中文(简体) )

### 供应商和模式

A 类 **提供者** 通过特定的API提供模型. 例如:

-   **安东尼** 模型使用 `anthropic-messages` API 密码
-   **谷歌** 模型使用 `google-generative-ai` API 密码
-   **开放AI** 模型使用 `openai-responses` API 密码
-   **米斯特拉尔,xAI, Cerebras, Groq等.** 模型使用 `openai-completions` API( 开放AI 兼容)

### 查询供应商和模式

```typescript
import { getProviders, getModels, getModel } from "@gajae-code/ai";

// Get all available providers
const providers = getProviders();
console.log(providers); // ['openai', 'anthropic', 'google', 'xai', 'groq', ...]

// Get all models from a provider (fully typed)
const anthropicModels = getModels("anthropic");
for (const model of anthropicModels) {
    console.log(`${model.id}: ${model.name}`);
    console.log(`  API: ${model.api}`); // 'anthropic-messages'
    console.log(`  Context: ${model.contextWindow} tokens`);
    console.log(`  Vision: ${model.input.includes("image")}`);
    console.log(`  Reasoning: ${model.reasoning}`);
}

// Get a specific model (both provider and model ID are auto-completed in IDEs)
const model = getModel("openai", "gpt-4o-mini");
console.log(`Using ${model.name} via ${model.api} API`);
```

### 自定义模型

您可以为本地推论服务器或自定义端点创建自定义模型.

对于当地的奥拉玛, `OLLAMA_API_KEY` 是可选的,主要用于认证/自我托管的网关. `ollama` 仍然是本地的 OpenAI 兼容运行时间整合 .

```typescript
import { Model, stream } from "@gajae-code/ai";

// Example: local Ollama using the OpenAI-compatible API
const ollamaModel: Model<"openai-completions"> = {
    id: "llama-3.1-8b",
    name: "Llama 3.1 8B (Ollama)",
    api: "openai-completions",
    provider: "ollama",
    baseUrl: "http://localhost:11434/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 32000,
};

const localResponse = await stream(ollamaModel, context, {
    apiKey: process.env.OLLAMA_API_KEY, // Optional; local Ollama usually runs without auth
});

// Example: Ollama Cloud using the native /api/chat transport
const ollamaCloudModel: Model<"ollama-chat"> = {
    id: "gpt-oss:120b",
    name: "GPT OSS 120B (Ollama Cloud)",
    api: "ollama-chat",
    provider: "ollama-cloud",
    baseUrl: "https://ollama.com",
    reasoning: true,
    input: ["text", "image"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 262144,
    maxTokens: 8192,
};

const cloudResponse = await stream(ollamaCloudModel, context, {
    apiKey: process.env.OLLAMA_CLOUD_API_KEY,
});

// Example: LiteLLM proxy with explicit compat settings
const litellmModel: Model<"openai-completions"> = {
    id: "gpt-4o",
    name: "GPT-4o (via LiteLLM)",
    api: "openai-completions",
    provider: "litellm",
    baseUrl: "http://localhost:4000/v1",
    reasoning: false,
    input: ["text", "image"],
    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 16384,
    compat: {
        supportsStore: false, // LiteLLM doesn't support the store field
    },
};

// Example: Custom endpoint with headers (bypassing Cloudflare bot detection)
const proxyModel: Model<"anthropic-messages"> = {
    id: "anthropic-model-sonnet-4",
    name: "Anthropic model Sonnet 4 (Proxied)",
    api: "anthropic-messages",
    provider: "custom-proxy",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: true,
    input: ["text", "image"],
    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
    contextWindow: 200000,
    maxTokens: 8192,
    headers: {
        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        "X-Custom-Auth": "bearer-token-here",
    },
};
```

### OpenAI 兼容性设置

这个 `openai-completions` API由许多提供商实施,两者差别不大. 默认情况下,基于 `baseUrl` 用于已知供应商(Cerebras、xAI、Mistral、Chutes等)。 对于自定义代理或未知的端点,您可以通过 `compat` 字段 :

```typescript
interface OpenAICompat {
    supportsStore?: boolean; // Whether provider supports the `store` field (default: true)
    supportsDeveloperRole?: boolean; // Whether provider supports `developer` role vs `system` (default: true)
    sendSessionHeaders?: boolean; // Forward the session id as `session_id`/`x-session-id` headers for relay session-affinity & prompt-cache reuse (default: false)
    supportsResponsesSessionAffinity?: boolean; // Opt in to session-affinity headers for custom openai-responses relays; canonical OpenAI routing and loopback-hostname relays are automatic (default: false for remote relays)
    supportsReasoningEffort?: boolean; // Whether provider supports `reasoning_effort` (default: true)
    maxTokensField?: "max_completion_tokens" | "max_tokens"; // Which field name to use (default: max_completion_tokens)
    extraBody?: Record<string, unknown>; // Extra request-body fields for custom proxy routing or provider-specific options
}
```

若为 `compat` 未设置,库会返回基于 URL 的检测。 若为 `compat` 未指定字段使用检测到的默认值。 这对于:

-   **LiteLLM 代词**: 可能不支持 `store` 字段
-   **自定义推断服务器**: 可使用非标准字段名称
-   **自办终点**: 可能有不同的特性支持

### 类型安全

模型按其API打入,确保类型安全选项:

```typescript
// TypeScript knows this is an Anthropic model
const anthropic-model = getModel("anthropic", "anthropic-model-sonnet-4-20250514");

// So these options are type-checked for AnthropicOptions
await stream(anthropic-model, context, {
    thinkingEnabled: true, // ✓ Valid for anthropic-messages
    thinkingBudgetTokens: 2048, // ✓ Valid for anthropic-messages
    // reasoningEffort: 'high'  // ✗ TypeScript error: not valid for anthropic-messages
});
```

## 交叉处理

库支持不同LLM提供者在同一对话中进行无缝的交接. 这使得您可以在保存上下文的同时切换模型中的对话,包括思维块,工具调用,以及工具结果.

### 如何运作

当一个提供者发送到另一个提供者的邮件时,库会自动变换,以便兼容:

-   **用户和工具结果信息** 转经未变
-   **同一供应商/API的助理信息** 保存为
-   **来自不同供应商的助理信息** 将思维块转换为文本 `<thinking>` 标记
-   **工具和正则文本** 保持不变

### 示例:多服务商对话

```typescript
import { getModel, complete, Context } from "@gajae-code/ai";

// Start with Anthropic model
const anthropic-model = getModel("anthropic", "anthropic-model-sonnet-4-20250514");
const context: Context = {
    messages: [],
};

context.messages.push({ role: "user", content: "What is 25 * 18?" });
const anthropic-modelResponse = await complete(anthropic-model, context, {
    thinkingEnabled: true,
});
context.messages.push(anthropic-modelResponse);

// Switch to GPT-5 - it will see Anthropic model's thinking as <thinking> tagged text
const gpt5 = getModel("openai", "gpt-5-mini");
context.messages.push({ role: "user", content: "Is that calculation correct?" });
const gptResponse = await complete(gpt5, context);
context.messages.push(gptResponse);

// Switch to Gemini
const gemini = getModel("google", "gemini-2.5-flash");
context.messages.push({ role: "user", content: "What was the original question?" });
const geminiResponse = await complete(gemini, context);
```

### 提供者兼容性

所有提供者可以处理其他提供者发来的信息,包括:

-   文本内容
-   工具调用和工具结果(包括工具结果中的图像)
-   思考/推理块(转换为标有标签的文本,以便交叉提供者兼容)
-   有部分内容的中止信件

这使得工作流程灵活,可以:

-   以快速模式启动初始响应
-   切换到更有能力的复杂推理模型
-   为特定任务使用专门模型
-   在供应商停电期间保持对话连续性

## 背景序列化

这个 `Context` 对象可以很容易地使用标准的JSON方法进行序列化和去序列化,使得持续对话,执行聊天历史,或者在服务间传输上下文变得简单:

```typescript
import { Context, getModel, complete } from "@gajae-code/ai";

// Create and use a context
const context: Context = {
    systemPrompt: ["You are a helpful assistant."],
    messages: [{ role: "user", content: "What is TypeScript?" }],
};

const model = getModel("openai", "gpt-4o-mini");
const response = await complete(model, context);
context.messages.push(response);

// Serialize the entire context
const serialized = JSON.stringify(context);
console.log("Serialized context size:", serialized.length, "bytes");

// Save to database, localStorage, file, etc.
localStorage.setItem("conversation", serialized);

// Later: deserialize and continue the conversation
const restored: Context = JSON.parse(localStorage.getItem("conversation")!);
restored.messages.push({ role: "user", content: "Tell me more about its type system" });

// Continue with any model
const newModel = getModel("anthropic", "anthropic-model-haiku-4-5-20251001");
const continuation = await complete(newModel, restored);
```

> **说明**:如果上下文包含图像(如图像输入部分所示被编码为base64),这些图像也会被序列化.

## 浏览器使用

库支持浏览器环境. 您必须明确通过 API 密钥, 因为浏览器中没有环境变量 :

```typescript
import { getModel, complete } from "@gajae-code/ai";

// API key must be passed explicitly in browser
const model = getModel("anthropic", "anthropic-model-haiku-4-5-20251001");

const response = await complete(
    model,
    {
        messages: [{ role: "user", content: "Hello!" }],
    },
    {
        apiKey: "your-api-key",
    }
);
```

> **安全警告**:在前端代码中曝光API密钥是危险的. 任何人都可以提取和滥用你的钥匙。 仅用于内部工具或演示。 对于生产应用程序,使用一个后端代理来保证您的API密钥的安全.

### 环境变量(仅节点.js)

在Node.js环境中,可以设置环境变量来避免通过API密钥:

| 提供者 | 环境变量 |
| --- | --- |
| 开放AI | `OPENAI_API_KEY` |
| 安东尼 | `ANTHROPIC_API_KEY` 或者说 `ANTHROPIC_OAUTH_TOKEN` (或 `ANTHROPIC_FOUNDRY_API_KEY` 何时 `ANTHROPIC_MODEL_CODE_USE_FOUNDRY=true`(中文(简体) ) |
| 谷歌 | `GEMINI_API_KEY` |
| Vertex 大赦国际 | `GOOGLE_CLOUD_PROJECT` (或 `GCLOUD_PROJECT`页:1 `GOOGLE_CLOUD_LOCATION` + ADC 组合键 |
| 迷雾 | `MISTRAL_API_KEY` |
| 格罗克 | `GROQ_API_KEY` |
| 心管 | `CEREBRAS_API_KEY` |
| 一起来 | `TOGETHER_API_KEY` |
| 钱范 | `QIANFAN_API_KEY` |
| 拥抱相貌 | `HUGGINGFACE_HUB_TOKEN` 或者说 `HF_TOKEN` |
| 合成 | `SYNTHETIC_API_KEY` |
| 纳米比亚 | `NVIDIA_API_KEY` |
| 纳诺GPT | `NANO_GPT_API_KEY` |
| 威尼斯语 | `VENICE_API_KEY` |
| 月光拍摄 | `MOONSHOT_API_KEY` |
| 页:1 大赦国际 | `XAI_API_KEY` |
| 打开路透社 | `OPENROUTER_API_KEY` |
| 列表 | `LITELLM_API_KEY` |
| 奥拉玛 | `OLLAMA_API_KEY` (当地部署可选) |
| 奥巴马云 | `OLLAMA_CLOUD_API_KEY` |
| Quen 门户网站 | `QWEN_OAUTH_TOKEN` 或者说 `QWEN_PORTAL_API_KEY` |
| 扎西岛 | `ZAI_API_KEY` |
| 迷你麦克斯码 | `MINIMAX_CODE_API_KEY` (国际)或 `MINIMAX_CODE_CN_API_KEY` (中国) |
| 小美,小美,小美 | `XIAOMI_API_KEY` |
| 禅穆 | `ZENMUX_API_KEY` |
| 打开网路 | `OPENGATEWAY_API_KEY` |
| 毕斯鲁特 | `BIZROUTER_API_KEY` |
| 玛拉云 | `MARA_API_KEY` |
| vLLM 数据 | `VLLM_API_KEY` |
| Cloudflare AI 网关 | `CLOUDFLARE_AI_GATEWAY_API_KEY` |
| GitHub 副驾驶 | `COPILOT_GITHUB_TOKEN` 或者说 `GH_TOKEN` 或者说 `GITHUB_TOKEN` |

对于 Cloudflare AI 网关模型,使用提供者基础 URL 格式 `https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic`。 。 。 .

用于Anthropic 创始路线,设置 `ANTHROPIC_MODEL_CODE_USE_FOUNDRY=true` 加: `FOUNDRY_BASE_URL`, (中文(简体) ), `ANTHROPIC_FOUNDRY_API_KEY`选项 `ANTHROPIC_CUSTOM_HEADERS`, (中文(简体) ), 和可选mTLS材料(`ANTHROPIC_MODEL_CODE_CLIENT_CERT`, (中文(简体) ), `ANTHROPIC_MODEL_CODE_CLIENT_KEY`, (中文(简体) ), `NODE_EXTRA_CA_CERTS`) (中文(简体) ).

当前 OpenAI 兼容集成的提供者端点默认 :

-   一起来: `https://api.together.xyz/v1`
-   月光拍摄: `https://api.moonshot.ai/v1`
-   Q: `https://qianfan.baidubce.com/v2`
-   尼维迪娅: `https://integrate.api.nvidia.com/v1`
-   纳诺GPT: `https://nano-gpt.com/api/v1`
-   拥抱相貌推论 : `https://router.huggingface.co/v1`
-   威尼斯语: `https://api.venice.ai/api/v1`
-   晓美美摩: `https://api.xiaomimimo.com/anthropic`
-   ZenMux(开放AI): `https://zenmux.ai/api/v1`
-   ZenMux( 人类模型): `https://zenmux.ai/api/anthropic`
-   OpenGateway by Sionic AI: 互联网档案馆的存檔,存档日期2013-12-22 `https://apis.opengateway.ai/v1`
-   比兹鲁特: `https://api.bizrouter.ai/v1`
-   玛拉云: `https://api.cloud.mara.com/v1`
-   vLLM : (英语) `http://127.0.0.1:8000/v1`
-   Ollama: 本地 OpenAI 兼容运行时间(`http://127.0.0.1:11434/v1`(中文(简体) )
-   Ollama Cloud:当地Ollama API主机(英语:`https://ollama.com/api`,在此配置为基础 URL `https://ollama.com`(中文(简体) )
-   文学LM: `http://localhost:4000/v1`
-   Cloudflare AI网关: `https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic`
-   Quen门户网站: `https://portal.qwen.ai/v1` 设定时,库会自动使用这些密钥:

```typescript
// Uses OPENAI_API_KEY from environment
const model = getModel("openai", "gpt-4o-mini");
const response = await complete(model, context);

// Or override with explicit key
const response = await complete(model, context, {
    apiKey: "sk-different-key",
});
```

### 正在检查环境变量

```typescript
import { getEnvApiKey } from "@gajae-code/ai";

// Check if an API key is set in environment variables
const key = getEnvApiKey("openai"); // checks OPENAI_API_KEY
```

## OAuth 供应商

多个提供者支持 OAuth 认证( 有的还支持静态 API 密钥):

-   **安东尼** (Anthropic 型号 Pro/ Max订阅)
-   **OpenAI 代码提供者** (ChatGPT Plus/Pro订阅,访问GPT-5.x OpenAI 代码模型)
-   **GitHub 副驾驶** (飞行员订阅)
-   **谷歌双子座CLI** (Gemini 2.0/2.5通过 Google Cloud Code Assistance;免费分级或付费订阅)
-   **反重力** (自由双子座3,Anthropic模型,GPT-OSS通过Google Cloud)
-   **Quen 门户网站** (Quen OAuth 令牌或 API 密钥)
-   **页:1 大赦国际** (Grok OAuth通过xAI账户登录)

对于付费的云码 协助订阅,设置 `GOOGLE_CLOUD_PROJECT` 或者说 `GOOGLE_CLOUD_PROJECT_ID` 到您的项目标识.

### Vertex AI (ADC) (英语)

Vertex AI模型使用应用程序默认证书(ADC):

-   **地方发展**运行 `gcloud auth application-default login`
-   **CI/生产**设置 `GOOGLE_APPLICATION_CREDENTIALS` 指向服务账户 JSON 密钥文件

也设定 `GOOGLE_CLOUD_PROJECT` (或 `GCLOUD_PROJECT`和 `GOOGLE_CLOUD_LOCATION`。也可以通过 `project`编号 :`location` 在呼叫选项中.

示例

```bash
# Local (uses your user credentials)
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="my-project"
export GOOGLE_CLOUD_LOCATION="us-central1"

# CI/Production (service account key file)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
```

```typescript
import { getModel, complete } from "@gajae-code/ai";

(async () => {
    const model = getModel("google-vertex", "gemini-2.5-flash");
    const response = await complete(model, {
        messages: [{ role: "user", content: "Hello from Vertex AI" }],
    });

    for (const block of response.content) {
        if (block.type === "text") console.log(block.text);
    }
})().catch(console.error);
```

官方文件: [应用程序默认证书](https://cloud.google.com/docs/authentication/application-default-credentials)

### CLI 登录

最快速的认证方式:

```bash
bunx @gajae-code/ai login              # interactive provider selection
bunx @gajae-code/ai login anthropic    # login to specific provider
bunx @gajae-code/ai login vllm         # store vLLM API key (local no-auth servers are discovered automatically)
bunx @gajae-code/ai login xai          # sign in with xAI/Grok OAuth
bunx @gajae-code/ai list               # list available providers
```

证书保存到 `agent.db` 在代理目录中. `/login qianfan` 打开Qianfan控制台并存储被粘贴的 API 密钥; `/login xai` 打开 xAI/Grok OAuth 登录并存储可刷新的 OAuth 证书.

`login` 支持OAuth提供商(Anthropic,OpenAI代码提供商,GitHub Copilot,双子座CLI,Antigravity,xAI)和API键入载流.

对于目前的API-键入上机流,库内覆盖了"同心","月光","仙花","NVIDIA","纳米GPT","哈格格面","威尼斯","小米","vLLM","LiteLLM","云浮"AI Gateways","Quen门户网站","奥拉玛云"等. Ollama 仍然是本地运行时间整合;设置 `OLLAMA_API_KEY` 只有在您的本地或自我托管的部署执行持证人授权时.

### 程序操作

库提供登录和令牌刷新功能. 信用存储是呼叫者的责任.

```typescript
import {
    // Login functions (return credentials, do not store)
    loginAnthropic,
    loginOpenAIOpenAI code,
    loginGitHubCopilot,
    loginGeminiCli,
    loginAntigravity,
    loginCloudflareAiGateway,
    loginHuggingface,
    loginLiteLLM,
    loginMoonshot,
    loginNvidia,
    loginNanoGPT,
    loginQianfan,
    loginQwenPortal,
    loginTogether,
    loginVenice,
    loginVllm,
    loginXiaomi,

    // Token management
    refreshOAuthToken, // (provider, credentials) => new credentials
    getOAuthApiKey, // (provider, credentialsMap) => { newCredentials, apiKey } | null

    // Types
    type OAuthProvider, // includes 'anthropic', 'openai-code', 'github-copilot', 'google-gemini-cli', 'google-antigravity', 'together', 'moonshot', 'qianfan', 'nvidia', 'nanogpt', 'huggingface', 'venice', 'xiaomi', 'vllm', 'litellm', 'cloudflare-ai-gateway', 'qwen-portal', ...
    type OAuthCredentials,
} from "@gajae-code/ai";
```

`loginOpenAIOpenAI code` 接受可选选项 `originator` oAuth 流中使用的值 :

```typescript
await loginOpenAIOpenAI code({
    onAuth: ({ url }) => console.log(url),
    originator: "my-cli",
});
```

### 登录流程示例

```typescript
import { loginGitHubCopilot } from "@gajae-code/ai";
import * as fs from "node:fs";

const credentials = await loginGitHubCopilot({
    onAuth: (url, instructions) => {
        console.log(`Open: ${url}`);
        if (instructions) console.log(instructions);
    },
    onPrompt: async (prompt) => {
        return await getUserInput(prompt.message);
    },
    onProgress: (message) => console.log(message),
});

// Store credentials yourself
const auth = { "github-copilot": { type: "oauth", ...credentials } };
fs.writeFileSync("credentials.json", JSON.stringify(auth, null, 2));
```

### 使用 OAuth 键

使用 `getOAuthApiKey()` 以获取 API 密钥,如果过期,则自动刷新 :

```typescript
import { getModel, complete, getOAuthApiKey } from "@gajae-code/ai";
import * as fs from "node:fs";

// Load your stored credentials
const auth = JSON.parse(fs.readFileSync("credentials.json", "utf-8"));

// Get API key (refreshes if expired)
const result = await getOAuthApiKey("github-copilot", auth);
if (!result) throw new Error("Not logged in");

// Save refreshed credentials
auth["github-copilot"] = { type: "oauth", ...result.newCredentials };
fs.writeFileSync("credentials.json", JSON.stringify(auth, null, 2));

// Use the API key
const model = getModel("github-copilot", "gpt-4o");
const response = await complete(
    model,
    {
        messages: [{ role: "user", content: "Hello!" }],
    },
    { apiKey: result.apiKey }
);
```

### 提供方说明

**OpenAI 代码提供者**:需要ChatGPT Plus或Pro订阅. 提供GPT-5.x OpenAI代码模型的访问权限,具有扩展上下文窗口和推理能力. 库自动处理基于会话的快速缓存 `sessionId` 以流选项提供.

**GitHub 副驾驶**:如果得到"请求的模型不支持"错误,则在VS代码中手动启用模型:打开Copilot Chat,点击模型选择器,选择模型(警告图标),并点击"Enable".

**谷歌双子座 CLI / 反重力**:这些使用Google Cloud OAuth. 这个 `apiKey` 返回时间 `getOAuthApiKey()` 是一个 JSON 字符串,既包含符号,又包含项目ID,由库自动处理.

## 许可证

麻省理工学院

## 常见问题

### @gajae-code/ai 是什么？

具有自动模型发现和提供者配置的统一LLM API

### 如何安装 @gajae-code/ai？

在项目目录运行 npm install @gajae-code/ai，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pi-ai，可以用 npx pi-ai 直接运行。

### @gajae-code/ai 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gajae-code/ai 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gajae-code/ai 可以商用吗？

@gajae-code/ai 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gajae-code/ai 的下载量有多少？

根据 npm 官方下载统计，@gajae-code/ai 在 2026/10/16 – 2026/11/14 这 30 天内被下载 8,891 次，日均约 296 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gajae-code/ai 还在维护吗？

最新版本 0\.21\.0 发布于 2026/11/16（今天）；至今共发布 158 个版本，其中过去 12 个月发布了 158 个；首次发布于 2026/05/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

