Core API

Полный справочник Core API Gemini CLI и руководство по использованию

Справочник API30 мин чтения

API модули

Основные API модули и методы

GeminiClient

Основной класс клиента Gemini API

src/core/gemini.ts

constructor

constructor(config: GeminiConfig)

Создать экземпляр клиента Gemini

Параметры:
configGeminiConfig

Объект конфигурации клиента

Пример:
const client = new GeminiClient({
  apiKey: process.env.GEMINI_API_KEY,
  model: 'gemini-pro',
  temperature: 0.7
})

chat

async chat(message: string, context?: Context): Promise<ChatResponse>

Отправить сообщение чата и получить ответ

Параметры:
messagestring

Входное сообщение пользователя

contextContext

Дополнительная контекстная информация

Возвращает:
Promise<ChatResponse>

Объект ответа чата

Пример:
const response = await client.chat('Hello, Gemini!', {
  files: ['src/index.ts'],
  history: previousMessages
})

stream

async stream(message: string, context?: Context): AsyncGenerator<string>

Потоковый ответ чата

Параметры:
messagestring

Входное сообщение пользователя

contextContext

Дополнительная контекстная информация

Возвращает:
AsyncGenerator<string>

Генератор потокового ответа

Пример:
for await (const chunk of client.stream('Explain this code')) {
  process.stdout.write(chunk)
}

SessionManager

Менеджер состояния сессии

src/core/session.ts

createSession

createSession(id?: string): Session

Создать новую сессию

Параметры:
idstring

Дополнительный ID сессии

Возвращает:
Session

Вновь созданный объект сессии

Пример:
const session = sessionManager.createSession('my-session')

getSession

getSession(id: string): Session | null

Получить указанную сессию

Параметры:
idstring

ID сессии

Возвращает:
Session | null

Объект сессии или null

Пример:
const session = sessionManager.getSession('my-session')

saveSession

async saveSession(session: Session): Promise<void>

Сохранить сессию в постоянное хранилище

Параметры:
sessionSession

Объект сессии для сохранения

Пример:
await sessionManager.saveSession(session)

ContextManager

Менеджер обработки контекста

src/core/context.ts

addFile

async addFile(filePath: string): Promise<void>

Добавить файл в контекст

Параметры:
filePathstring

Путь к файлу

Пример:
await contextManager.addFile('src/utils/helper.ts')

addDirectory

async addDirectory(dirPath: string, options?: DirOptions): Promise<void>

Добавить директорию в контекст

Параметры:
dirPathstring

Путь к директории

optionsDirOptions

Опции сканирования директории

Пример:
await contextManager.addDirectory('src/', {
  exclude: ['*.test.ts'],
  maxDepth: 3
})

getContext

getContext(): Context

Получить текущий контекст

Возвращает:
Context

Текущий объект контекста

Пример:
const context = contextManager.getContext()

Определения типов

Определения типов TypeScript для Core API

GeminiConfig

Интерфейс конфигурации клиента Gemini

apiKeystring
обязательно

Ключ API Google AI

modelstring

Имя модели для использования, по умолчанию "gemini-pro"

temperaturenumber

Температура генерации, между 0-1

maxTokensnumber

Максимальное количество токенов

timeoutnumber

Таймаут запроса в миллисекундах

ChatResponse

Интерфейс ответа чата

contentstring
обязательно

Содержимое ответа

usageTokenUsage
обязательно

Информация об использовании токенов

modelstring
обязательно

Используемая модель

finishReasonstring

Причина завершения

Context

Интерфейс контекстной информации

filesFileContext[]

Список файлового контекста

historyMessage[]

История сообщений

metadataRecord<string, any>

Метаданные

Session

Интерфейс сессии

idstring
обязательно

Уникальный идентификатор сессии

messagesMessage[]
обязательно

История сообщений

contextContext

Контекст сессии

createdAtDate
обязательно

Время создания

updatedAtDate
обязательно

Время обновления

Примеры использования

Распространенные сценарии использования API и примеры кода

Базовый чат

Пример простого чат-взаимодействия

import { GeminiClient } from '@gemini/core'

const client = new GeminiClient({
  apiKey: process.env.GEMINI_API_KEY,
  model: 'gemini-pro'
})

async function basicChat() {
  try {
    const response = await client.chat('Hello, how are you?')
    console.log('AI:', response.content)
  } catch (error) {
    console.error('Chat error:', error.message)
  }
}

Файловый контекст

Чат с включенным файловым контекстом

import { GeminiClient, ContextManager } from '@gemini/core'

const client = new GeminiClient({ apiKey: process.env.GEMINI_API_KEY })
const contextManager = new ContextManager()

async function chatWithFiles() {
  // Add files to context
  await contextManager.addFile('src/utils/helper.ts')
  await contextManager.addDirectory('src/components/')

  const context = contextManager.getContext()

  const response = await client.chat(
    'Explain the helper functions in this codebase',
    context
  )

  console.log(response.content)
}

Управление сессиями

Управление постоянными сессиями

import { SessionManager } from '@gemini/core'

const sessionManager = new SessionManager()

async function manageSessions() {
  // Create new session
  const session = sessionManager.createSession('project-review')

  // Add messages to session
  session.messages.push({
    role: 'user',
    content: 'Review this code for best practices'
  })

  // Save session
  await sessionManager.saveSession(session)

  // Restore session later
  const restored = sessionManager.getSession('project-review')
  console.log('Session messages:', restored?.messages.length)
}

Потоковый ответ

Потоковый вывод в реальном времени

import { GeminiClient } from '@gemini/core'

const client = new GeminiClient({ apiKey: process.env.GEMINI_API_KEY })

async function streamingChat() {
  console.log('AI: ')

  for await (const chunk of client.stream('Write a short story')) {
    process.stdout.write(chunk)
  }

  console.log('\n\nStream completed!')
}

Обработка ошибок

Типы ошибок API и методы обработки

AuthenticationError

Недействительный или истекший API ключ

GEMINI_AUTH_ERROR

Решение:

Проверьте, правильно ли установлен API ключ, убедитесь, что ключ действителен и не истек

RateLimitError

Частота запросов превышает лимиты

GEMINI_RATE_LIMIT

Решение:

Реализуйте механизм повторных попыток с экспоненциальной задержкой или обновитесь до плана с более высокой квотой

ContextTooLargeError

Содержимое контекста превышает лимиты модели

GEMINI_CONTEXT_TOO_LARGE

Решение:

Уменьшите количество контекстных файлов или используйте функцию суммаризации файлов

NetworkError

Проблемы с сетевым подключением

GEMINI_NETWORK_ERROR

Решение:

Проверьте сетевое подключение, настройте параметры прокси или увеличьте таймаут

Следующие шаги

Продолжите свой путь разработки с этими ресурсами

Настройка разработкиСтруктура проектаНазад к документации