Live2D AI角色

Quick Start

This snippet runs entirely in the browser with no server — paste it in, drop in an OpenAI API key, and it works. It uses the direct browser clients (@charivo/llm/openai, @charivo/tts/openai), which are for local development and demos only. They expose your API key in the browser, so for production use the server-mediated path instead (see Choosing Packages).

pnpm add \
  @charivo/core \
  @charivo/llm \
  @charivo/tts \
  @charivo/render @charivo/render-live2d

import { Charivo, CharivoError } from "@charivo/core";
import { createLLMManager } from "@charivo/llm";
import { createOpenAILLMClient } from "@charivo/llm/openai";
import { createTTSManager } from "@charivo/tts";
import { createOpenAITTSPlayer } from "@charivo/tts/openai";
import { createRenderManager } from "@charivo/render";
import { createLive2DRenderer } from "@charivo/render-live2d";

// Dev/demo only: this key is shipped to the browser. Never do this in production.
const OPENAI_API_KEY = "sk-...";

const canvas = document.querySelector("canvas")!;

const charivo = new Charivo();

const renderer = createLive2DRenderer({ canvas });
const renderManager = createRenderManager(renderer, {
  canvas,
  mouseTracking: "document",
});
await renderManager.initialize();
await renderManager.loadModel("/live2d/Hiyori/Hiyori.model3.json");

charivo.attachRenderer(renderManager);
charivo.attachLLM(
  createLLMManager(createOpenAILLMClient({ apiKey: OPENAI_API_KEY })),
);
charivo.attachTTS(
  createTTSManager(createOpenAITTSPlayer({ apiKey: OPENAI_API_KEY })),
);

charivo.setCharacter({
  id: "hiyori",
  name: "Hiyori",
  personality: "Cheerful and helpful assistant",
  voice: { voiceId: "marin" },
});

try {
  await charivo.userSay("Hello");
} catch (error) {
  if (error instanceof CharivoError) {
    console.error(error.code, error.message);
  }
  throw error;
}

await charivo.dispose();

For a complete app with the production server-mediated path, see examples/web.

No-server dev quick start

For local development you can skip the server route entirely. Swap the remote client for the direct Agents transport client and pass an OpenAI API key — it mints a short-lived realtime client secret in the browser (the same dev pattern as the Quick Start LLM/TTS clients). The rest of the wiring (renderer, character, startSession) is identical to the example above.

import { createRealtimeManager } from "@charivo/realtime";
import { createOpenAIRealtimeAgentsClient } from "@charivo/realtime/openai-agents";

// Dev/demo only: this key is exposed in the browser. Never ship it to production.
charivo.attachRealtime(
  createRealtimeManager(
    createOpenAIRealtimeAgentsClient({ apiKey: "sk-..." }),
  ),
);

This path is dev/testing only — the key is exposed in the browser. It also requires microphone permission, a secure context (localhost or https), and a user gesture (e.g. a button click) to start the session; the minted client secret is short-lived, so a fresh one is requested per session. For production, use the server-mediated @charivo/realtime/remote path shown above.

Choosing Packages

Use the remote/server-mediated path by default:

• LLM: @charivo/llm/remote + a server route using a provider package such as @charivo/server/openai or @charivo/server/openclaw
• TTS: @charivo/tts/remote + @charivo/server/openai
• STT: @charivo/stt/remote + @charivo/server/openai
• Realtime: @charivo/realtime/remote + a server route using a provider package such as @charivo/server/openai

Direct browser packages are for local development, demos, and testing only:

• @charivo/llm/openai
• @charivo/llm/openclaw
• @charivo/realtime/openai
• @charivo/realtime/openai-agents (dev apiKey mints the client secret in-browser)
• @charivo/tts/openai
• @charivo/stt/openai

Browser-native packages are useful when you explicitly want no server dependency:

• @charivo/tts/web
• @charivo/stt/web

Package Map

Core:

• @charivo/core: orchestrator, event bus, domain types

LLM:

• @charivo/llm: stateful conversation manager
• @charivo/llm/remote: browser client for server API routes
• @charivo/llm/openai: direct OpenAI browser client, dev/testing only
• @charivo/llm/openclaw: direct OpenClaw browser client, dev/testing only
• @charivo/llm/stub: canned responses for tests and demos
• @charivo/server/openai: server-side OpenAI provider exports
• @charivo/server/openclaw: server-side OpenClaw provider exports

TTS:

• @charivo/tts: TTS session manager and lip-sync coordination
• @charivo/tts/remote: browser player for server TTS routes
• @charivo/tts/openai: direct OpenAI browser player, dev/testing only
• @charivo/tts/web: Web Speech API player
• @charivo/server/openai: exports createOpenAITTSProvider(...)

STT:

• @charivo/stt: STT session manager and recording helper
• @charivo/stt/remote: browser transcriber for server STT routes
• @charivo/stt/openai: direct OpenAI browser transcriber, dev/testing only
• @charivo/stt/web: Web Speech API transcriber
• @charivo/server/openai: exports createOpenAISTTProvider(...)

Realtime:

- @charivo/realtime: provider-agnostic realtime manager, tool registry, typed state, and session config helpers Supports explicit updateSession(...) session patching without a reconnect. - @charivo/realtime-avatar: optional avatar tool definitions and result projector bridge - @charivo/realtime/remote: adapter-dispatched browser client for server realtime routes - @charivo/realtime/openai-agents: OpenAI Agents SDK realtime transport client and adapter - @charivo/realtime/openai: legacy low-level OpenAI realtime transport client and adapter - @charivo/server/openai: exports createOpenAIRealtimeProvider(...)

Rendering:

• @charivo/render: render manager, mouse tracking, lip-sync bridge
• @charivo/render-live2d: Live2D Cubism renderer
• @charivo/render/stub: console renderer for tests and demos