第2章 多模型适配——一套代码跑通三家 LLM

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "read_file",
        "arguments": "{\"file_path\": \"package.json\"}"
      }
    }
  ]
}

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Let me read that file for you." },
    {
      "type": "tool_use",
      "id": "toolu_abc123",
      "name": "read_file",
      "input": { "file_path": "package.json" }
    }
  ]
}

// src/providers/types.ts
 
/** 工具定义 */
export interface Tool {
  name: string;
  description: string;
  parameters: Record<string, unknown>; // JSON Schema
}
 
/** 工具调用请求 */
export interface ToolCall {
  id: string;
  name: string;
  arguments: string; // JSON 字符串
}
 
/** 统一消息格式 */
export type Message =
  | { role: "system"; content: string }
  | { role: "user"; content: string }
  | { role: "assistant"; content: string; toolCalls?: ToolCall[] }
  | { role: "tool"; toolCallId: string; content: string };
 
/** 模型返回的统一响应 */
export interface LLMResponse {
  content: string | null;
  toolCalls: ToolCall[];
  finishReason: "stop" | "tool_calls" | "length" | "unknown";
}

export interface LLMProvider {
  readonly name: string;
  chat(messages: Message[], tools?: Tool[]): Promise<LLMResponse>;
  stream(messages: Message[], tools?: Tool[]): AsyncIterableIterator<StreamChunk>;
}

// src/providers/volcano.ts
import OpenAI from "openai";
import type { LLMProvider, LLMResponse, Message, Tool, ToolCall } from "./types.js";
 
/** 把我们的统一 Tool 转成 OpenAI 格式 */
function toOpenAITools(tools: Tool[]): OpenAI.Chat.ChatCompletionTool[] {
  return tools.map((t) => ({
    type: "function" as const,
    function: {
      name: t.name,
      description: t.description,
      parameters: t.parameters,
    },
  }));
}
 
/** 把统一 Message 转成 OpenAI 格式 */
function toOpenAIMessages(messages: Message[]): OpenAI.Chat.ChatCompletionMessageParam[] {
  return messages.map((msg) => {
    switch (msg.role) {
      case "system":
        return { role: "system" as const, content: msg.content };
      case "user":
        return { role: "user" as const, content: msg.content };
      case "assistant":
        return {
          role: "assistant" as const,
          content: msg.content,
          tool_calls: msg.toolCalls?.map((tc) => ({
            id: tc.id,
            type: "function" as const,
            function: { name: tc.name, arguments: tc.arguments },
          })),
        };
      case "tool":
        return {
          role: "tool" as const,
          tool_call_id: msg.toolCallId,
          content: msg.content,
        };
    }
  });
}
 
/** 把 OpenAI 的 tool_calls 转成统一格式 */
function fromOpenAIToolCalls(
  toolCalls?: OpenAI.Chat.ChatCompletionMessageToolCall[],
): ToolCall[] {
  if (!toolCalls) return [];
  return toolCalls.map((tc) => ({
    id: tc.id,
    name: tc.function.name,
    arguments: tc.function.arguments,
  }));
}

export class VolcanoProvider implements LLMProvider {
  readonly name = "volcano";
  private client: OpenAI;
  private model: string;
 
  constructor(apiKey: string, model: string, baseURL?: string) {
    this.model = model;
    this.client = new OpenAI({
      apiKey,
      baseURL: baseURL || "https://ark.cn-beijing.volces.com/api/v3",
    });
  }
 
  async chat(messages: Message[], tools?: Tool[]): Promise<LLMResponse> {
    const res = await this.client.chat.completions.create({
      model: this.model,
      messages: toOpenAIMessages(messages),
      tools: tools?.length ? toOpenAITools(tools) : undefined,
    });
 
    const choice = res.choices[0];
    return {
      content: choice.message.content,
      toolCalls: fromOpenAIToolCalls(choice.message.tool_calls),
      finishReason: choice.finish_reason === "tool_calls" ? "tool_calls"
        : choice.finish_reason === "stop" ? "stop"
        : choice.finish_reason === "length" ? "length"
        : "unknown",
    };
  }
 
  // stream 方法类似，省略
}

// src/providers/claude.ts
import Anthropic from "@anthropic-ai/sdk";
import type { LLMProvider, LLMResponse, Message, Tool, ToolCall } from "./types.js";
 
/** 把统一 Tool 转成 Claude 格式 */
function toClaudeTools(tools: Tool[]): Anthropic.Tool[] {
  return tools.map((t) => ({
    name: t.name,
    description: t.description,
    input_schema: t.parameters as Anthropic.Tool.InputSchema,
  }));
}

function splitSystemAndMessages(messages: Message[]): {
  system: string | undefined;
  claudeMessages: Anthropic.MessageParam[];
} {
  let system: string | undefined;
  const claudeMessages: Anthropic.MessageParam[] = [];
 
  for (const msg of messages) {
    switch (msg.role) {
      case "system":
        system = system ? `${system}\n\n${msg.content}` : msg.content;
        break;
 
      case "user":
        claudeMessages.push({ role: "user", content: msg.content });
        break;
 
      case "assistant": {
        // Claude 的 assistant content 是数组，文本和工具调用混在一起
        const content: Anthropic.ContentBlockParam[] = [];
        if (msg.content) {
          content.push({ type: "text", text: msg.content });
        }
        if (msg.toolCalls) {
          for (const tc of msg.toolCalls) {
            content.push({
              type: "tool_use",
              id: tc.id,
              name: tc.name,
              input: JSON.parse(tc.arguments),  // 字符串 -> 对象
            });
          }
        }
        claudeMessages.push({ role: "assistant", content });
        break;
      }
 
      case "tool":
        // 工具结果放在 user 消息的 content 数组里
        claudeMessages.push({
          role: "user",
          content: [
            {
              type: "tool_result",
              tool_use_id: msg.toolCallId,
              content: msg.content,
            },
          ],
        });
        break;
    }
  }
 
  return { system, claudeMessages };
}

function extractToolCalls(content: Anthropic.ContentBlock[]): ToolCall[] {
  return content
    .filter((block): block is Anthropic.ToolUseBlock => block.type === "tool_use")
    .map((block) => ({
      id: block.id,
      name: block.name,
      arguments: JSON.stringify(block.input),  // 对象 -> 字符串
    }));
}
 
function extractText(content: Anthropic.ContentBlock[]): string | null {
  const texts = content
    .filter((block): block is Anthropic.TextBlock => block.type === "text")
    .map((block) => block.text);
  return texts.length > 0 ? texts.join("") : null;
}

export class ClaudeProvider implements LLMProvider {
  readonly name = "claude";
  private client: Anthropic;
  private model: string;
 
  constructor(apiKey: string, model: string) {
    this.model = model;
    this.client = new Anthropic({ apiKey });
  }
 
  async chat(messages: Message[], tools?: Tool[]): Promise<LLMResponse> {
    const { system, claudeMessages } = splitSystemAndMessages(messages);
 
    const res = await this.client.messages.create({
      model: this.model,
      max_tokens: 4096,
      system,
      messages: claudeMessages,
      tools: tools?.length ? toClaudeTools(tools) : undefined,
    });
 
    return {
      content: extractText(res.content),
      toolCalls: extractToolCalls(res.content),
      finishReason: res.stop_reason === "tool_use" ? "tool_calls"
        : res.stop_reason === "end_turn" ? "stop"
        : res.stop_reason === "max_tokens" ? "length"
        : "unknown",
    };
  }
}

this.client = new OpenAI({
  apiKey,
  baseURL: baseURL || "https://api.openai.com/v1",  // 唯一的区别
});

命令行参数 > 环境变量 > .ling.json > 默认值

// src/providers/factory.ts
 
export function resolveConfig(cliArgs?: Partial<ProviderConfig>): ProviderConfig {
  const fileConfig = loadConfigFile();  // 读 .ling.json
 
  const provider = cliArgs?.provider
    || (process.env.LING_PROVIDER as ProviderConfig["provider"])
    || fileConfig?.provider
    || "volcano";  // 默认用火山引擎
 
  const apiKey = cliArgs?.apiKey
    || process.env.LING_API_KEY
    || process.env.LLM_API_KEY  // 兼容 ch01 的环境变量
    || fileConfig?.apiKey
    || "";
 
  const defaultModels: Record<string, string> = {
    volcano: "doubao-1.5-pro-32k-250115",
    claude: "claude-sonnet-4-20250514",
    openai: "gpt-4o",
  };
 
  const model = cliArgs?.model
    || process.env.LING_MODEL
    || fileConfig?.model
    || defaultModels[provider];
 
  // ...
  return { provider, apiKey, model, baseURL };
}

export function createProvider(config: ProviderConfig): LLMProvider {
  switch (config.provider) {
    case "volcano":
      return new VolcanoProvider(config.apiKey, config.model, config.baseURL);
    case "claude":
      return new ClaudeProvider(config.apiKey, config.model);
    case "openai":
      return new OpenAIProvider(config.apiKey, config.model, config.baseURL);
    default:
      throw new Error(`Unknown provider: ${config.provider}`);
  }
}

# 默认用火山引擎
npx tsx src/ling.ts "帮我看看这个项目"
 
# 切换到 Claude
npx tsx src/ling.ts --provider claude "帮我看看这个项目"
 
# 用环境变量
LING_PROVIDER=openai LING_API_KEY=sk-xxx npx tsx src/ling.ts "帮我看看这个项目"

{
  "provider": "claude",
  "apiKey": "sk-ant-xxx",
  "model": "claude-sonnet-4-20250514"
}

// src/ling.ts
 
async function agent(query: string, config: Partial<ProviderConfig>) {
  const provider = initProvider(config);  // 一行搞定初始化
 
  const messages: Message[] = [
    { role: "system", content: "You are Ling, a helpful coding assistant." },
    { role: "user", content: query },
  ];
 
  const MAX_TURNS = 20;
  for (let turn = 0; turn < MAX_TURNS; turn++) {
    const res = await provider.chat(messages, tools);  // 统一接口调用
 
    messages.push({
      role: "assistant",
      content: res.content || "",
      toolCalls: res.toolCalls.length > 0 ? res.toolCalls : undefined,
    });
 
    if (res.finishReason !== "tool_calls" || res.toolCalls.length === 0) {
      console.log(res.content);
      return;
    }
 
    for (const tc of res.toolCalls) {
      const args = JSON.parse(tc.arguments);
      const result = executeTool(tc.name, args);
      console.log(`[tool] ${tc.name}(${JSON.stringify(args)}) -> ${result.slice(0, 100)}...`);
      messages.push({ role: "tool", toolCallId: tc.id, content: result });
    }
  }
}

await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 4096,
  system: "You are a helpful assistant.",  // 这里！
  messages: [
    { role: "user", content: "Hello" }
  ],
});

# 用 Bedrock
CLAUDE_CODE_USE_BEDROCK=1
 
# 用 Vertex
CLAUDE_CODE_USE_VERTEX=1
 
# 不设这两个就直接调 Anthropic

type ModelOption = "sonnet" | "opus" | "haiku"