@spaceflow/core 0.1.1

package/src/shared/llm-proxy/llm-proxy.service.spec.ts

@@ -0,0 +1,303 @@
+import { vi, type Mocked } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { LlmProxyService, ChatOptions } from "./llm-proxy.service";
+import { ClaudeCodeAdapter } from "./adapters/claude-code.adapter";
+import { OpenAIAdapter } from "./adapters/openai.adapter";
+import { OpenCodeAdapter } from "./adapters/open-code.adapter";
+
+vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+  query: vi.fn(),
+}));
+
+describe("LlmProxyService", () => {
+  let service: LlmProxyService;
+  let claudeAdapter: Mocked<ClaudeCodeAdapter>;
+  let openaiAdapter: Mocked<OpenAIAdapter>;
+  let opencodeAdapter: Mocked<OpenCodeAdapter>;
+
+  const mockConfig = {
+    defaultAdapter: "claude-code" as const,
+  };
+
+  beforeEach(async () => {
+    const mockClaude = {
+      name: "claude-code",
+      chat: vi.fn(),
+      chatStream: vi.fn(),
+      isConfigured: vi.fn().mockReturnValue(true),
+      isSupportJsonSchema: vi.fn().mockReturnValue(true),
+    };
+    const mockOpenAI = {
+      name: "openai",
+      chat: vi.fn(),
+      chatStream: vi.fn(),
+      isConfigured: vi.fn().mockReturnValue(true),
+      isSupportJsonSchema: vi.fn().mockReturnValue(true),
+    };
+    const mockOpenCode = {
+      name: "open-code",
+      chat: vi.fn(),
+      chatStream: vi.fn(),
+      isConfigured: vi.fn().mockReturnValue(true),
+      isSupportJsonSchema: vi.fn().mockReturnValue(true),
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        LlmProxyService,
+        { provide: "LLM_PROXY_CONFIG", useValue: mockConfig },
+        { provide: ClaudeCodeAdapter, useValue: mockClaude },
+        { provide: OpenAIAdapter, useValue: mockOpenAI },
+        { provide: OpenCodeAdapter, useValue: mockOpenCode },
+      ],
+    }).compile();
+
+    service = module.get<LlmProxyService>(LlmProxyService);
+    claudeAdapter = module.get(ClaudeCodeAdapter);
+    openaiAdapter = module.get(OpenAIAdapter);
+    opencodeAdapter = module.get(OpenCodeAdapter);
+  });
+
+  it("should be defined", () => {
+    expect(service).toBeDefined();
+  });
+
+  describe("createSession", () => {
+    it("should create a session with default adapter", () => {
+      const session = service.createSession();
+      expect(session).toBeDefined();
+      expect(session.adapterName).toBe("claude-code");
+    });
+
+    it("should create a session with specified adapter", () => {
+      const session = service.createSession("openai");
+      expect(session).toBeDefined();
+      expect(session.adapterName).toBe("openai");
+    });
+
+    it("should throw error if adapter is not configured", () => {
+      claudeAdapter.isConfigured.mockReturnValue(false);
+      expect(() => service.createSession("claude-code")).toThrow('适配器 "claude-code" 未配置');
+    });
+  });
+
+  describe("chat", () => {
+    it("should call adapter.chat and return response", async () => {
+      const messages = [{ role: "user", content: "hello" }] as any;
+      const mockResponse = { content: "hi", role: "assistant" };
+      claudeAdapter.chat.mockResolvedValue(mockResponse as any);
+
+      const result = await service.chat(messages);
+
+      expect(claudeAdapter.chat).toHaveBeenCalledWith(messages, undefined);
+      expect(result).toEqual(mockResponse);
+    });
+
+    it("should use specified adapter", async () => {
+      const messages = [{ role: "user", content: "hello" }] as any;
+      const options: ChatOptions = { adapter: "openai" };
+      openaiAdapter.chat.mockResolvedValue({ content: "hi" } as any);
+
+      await service.chat(messages, options);
+
+      expect(openaiAdapter.chat).toHaveBeenCalled();
+      expect(claudeAdapter.chat).not.toHaveBeenCalled();
+    });
+
+    it("should handle jsonSchema and parse output", async () => {
+      const messages = [{ role: "user", content: "hello" }] as any;
+      const mockParsed = { foo: "bar" };
+      const mockJsonSchema = {
+        parse: vi.fn().mockResolvedValue(mockParsed),
+        getSchema: vi.fn().mockReturnValue({ type: "object" }),
+      };
+      const options = { jsonSchema: mockJsonSchema };
+      const mockResponse = { content: '{"foo":"bar"}', role: "assistant" };
+      claudeAdapter.chat.mockResolvedValue(mockResponse as any);
+
+      const result = await service.chat(messages, options as any);
+
+      expect(result.structuredOutput).toEqual(mockParsed);
+      expect(mockJsonSchema.parse).toHaveBeenCalledWith(mockResponse.content);
+    });
+  });
+
+  describe("chatStream", () => {
+    it("should delegate to adapter.chatStream", async () => {
+      const messages = [{ role: "user", content: "hello" }] as any;
+      const mockStream = (async function* () {
+        yield { type: "text", content: "hi" };
+      })();
+      claudeAdapter.chatStream.mockReturnValue(mockStream as any);
+
+      const stream = service.chatStream(messages);
+      const chunks: any[] = [];
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+
+      expect(chunks).toEqual([{ type: "text", content: "hi" }]);
+      expect(claudeAdapter.chatStream).toHaveBeenCalledWith(messages, undefined);
+    });
+  });
+
+  describe("chat with jsonSchema fallback", () => {
+    it("should append jsonSchema prompt when adapter does not support jsonSchema", async () => {
+      claudeAdapter.isSupportJsonSchema.mockReturnValue(false);
+      const mockJsonSchema = {
+        parse: vi.fn().mockResolvedValue({ foo: "bar" }),
+        getSchema: vi.fn(),
+        jsonFormatInstruction: "请返回 JSON",
+        isMatched: vi.fn().mockReturnValue(false),
+      };
+      const messages = [
+        { role: "system", content: "你是助手" },
+        { role: "user", content: "hello" },
+      ] as any;
+      claudeAdapter.chat.mockResolvedValue({ content: '{"foo":"bar"}' } as any);
+      const result = await service.chat(messages, { jsonSchema: mockJsonSchema } as any);
+      expect(messages[0].content).toContain("请返回 JSON");
+      expect(result.structuredOutput).toEqual({ foo: "bar" });
+    });
+
+    it("should not append jsonSchema prompt if already matched", async () => {
+      claudeAdapter.isSupportJsonSchema.mockReturnValue(false);
+      const mockJsonSchema = {
+        parse: vi.fn().mockResolvedValue({}),
+        getSchema: vi.fn(),
+        jsonFormatInstruction: "请返回 JSON",
+        isMatched: vi.fn().mockReturnValue(true),
+      };
+      const messages = [{ role: "system", content: "已包含 JSON 指令" }] as any;
+      claudeAdapter.chat.mockResolvedValue({ content: "{}" } as any);
+      await service.chat(messages, { jsonSchema: mockJsonSchema } as any);
+      expect(messages[0].content).toBe("已包含 JSON 指令");
+    });
+
+    it("should add system message if none exists", async () => {
+      claudeAdapter.isSupportJsonSchema.mockReturnValue(false);
+      const mockJsonSchema = {
+        parse: vi.fn().mockResolvedValue({}),
+        getSchema: vi.fn(),
+        jsonFormatInstruction: "请返回 JSON",
+        isMatched: vi.fn().mockReturnValue(false),
+      };
+      const messages = [{ role: "user", content: "hello" }] as any;
+      claudeAdapter.chat.mockResolvedValue({ content: "{}" } as any);
+      await service.chat(messages, { jsonSchema: mockJsonSchema } as any);
+      expect(messages[0].role).toBe("system");
+      expect(messages[0].content).toBe("请返回 JSON");
+    });
+
+    it("should not parse if response has no content", async () => {
+      const mockJsonSchema = {
+        parse: vi.fn(),
+        getSchema: vi.fn(),
+      };
+      claudeAdapter.chat.mockResolvedValue({ content: "" } as any);
+      const result = await service.chat(
+        [{ role: "user", content: "hello" }] as any,
+        { jsonSchema: mockJsonSchema } as any,
+      );
+      expect(mockJsonSchema.parse).not.toHaveBeenCalled();
+      expect(result.structuredOutput).toBeUndefined();
+    });
+
+    it("should not parse if structuredOutput already exists", async () => {
+      const mockJsonSchema = {
+        parse: vi.fn(),
+        getSchema: vi.fn(),
+      };
+      claudeAdapter.chat.mockResolvedValue({
+        content: "{}",
+        structuredOutput: { existing: true },
+      } as any);
+      const result = await service.chat(
+        [{ role: "user", content: "hello" }] as any,
+        { jsonSchema: mockJsonSchema } as any,
+      );
+      expect(mockJsonSchema.parse).not.toHaveBeenCalled();
+      expect(result.structuredOutput).toEqual({ existing: true });
+    });
+  });
+
+  describe("chatStream with jsonSchema", () => {
+    it("should parse jsonSchema on result event", async () => {
+      const mockJsonSchema = {
+        parse: vi.fn().mockResolvedValue({ parsed: true }),
+        getSchema: vi.fn(),
+      };
+      const mockStream = (async function* () {
+        yield { type: "result", response: { content: '{"parsed":true}' } };
+      })();
+      claudeAdapter.chatStream.mockReturnValue(mockStream as any);
+      const chunks: any[] = [];
+      for await (const chunk of service.chatStream(
+        [{ role: "user", content: "hello" }] as any,
+        { jsonSchema: mockJsonSchema } as any,
+      )) {
+        chunks.push(chunk);
+      }
+      expect(chunks[0].response.structuredOutput).toEqual({ parsed: true });
+    });
+
+    it("should handle jsonSchema parse error gracefully", async () => {
+      const mockJsonSchema = {
+        parse: vi.fn().mockRejectedValue(new Error("parse error")),
+        getSchema: vi.fn(),
+      };
+      const mockStream = (async function* () {
+        yield { type: "result", response: { content: "invalid json" } };
+      })();
+      claudeAdapter.chatStream.mockReturnValue(mockStream as any);
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const chunks: any[] = [];
+      for await (const chunk of service.chatStream(
+        [{ role: "user", content: "hello" }] as any,
+        { jsonSchema: mockJsonSchema } as any,
+      )) {
+        chunks.push(chunk);
+      }
+      expect(consoleSpy).toHaveBeenCalled();
+      expect(chunks[0].response.structuredOutput).toBeUndefined();
+      consoleSpy.mockRestore();
+    });
+
+    it("should use specified adapter for chatStream", async () => {
+      const mockStream = (async function* () {
+        yield { type: "text", content: "hi" };
+      })();
+      openaiAdapter.chatStream.mockReturnValue(mockStream as any);
+      const chunks: any[] = [];
+      for await (const chunk of service.chatStream([{ role: "user", content: "hello" }] as any, {
+        adapter: "openai",
+      })) {
+        chunks.push(chunk);
+      }
+      expect(openaiAdapter.chatStream).toHaveBeenCalled();
+    });
+  });
+
+  describe("getAvailableAdapters", () => {
+    it("should return list of configured adapters", () => {
+      claudeAdapter.isConfigured.mockReturnValue(true);
+      openaiAdapter.isConfigured.mockReturnValue(false);
+      opencodeAdapter.isConfigured.mockReturnValue(false);
+
+      const available = service.getAvailableAdapters();
+
+      expect(available).toEqual(["claude-code"]);
+    });
+
+    it("should return all adapters when all configured", () => {
+      const available = service.getAvailableAdapters();
+      expect(available).toEqual(["claude-code", "openai", "open-code"]);
+    });
+  });
+
+  describe("getAdapter errors", () => {
+    it("should throw for unsupported adapter type", () => {
+      expect(() => service.createSession("unknown" as any)).toThrow("不支持的 LLM 类型: unknown");
+    });
+  });
+});

package/src/shared/llm-proxy/llm-proxy.service.ts

@@ -0,0 +1,132 @@
+import { Injectable, Inject } from "@nestjs/common";
+import type { LlmAdapter } from "./adapters";
+import { ClaudeCodeAdapter } from "./adapters/claude-code.adapter";
+import { OpenAIAdapter } from "./adapters/openai.adapter";
+import { OpenCodeAdapter } from "./adapters/open-code.adapter";
+import { LlmSessionImpl } from "./llm-session";
+import type {
+  LlmMessage,
+  LlmRequestOptions,
+  LlmResponse,
+  LlmSession,
+  SessionOptions,
+  LlmProxyConfig,
+  LLMMode,
+} from "./interfaces";
+import type { LlmJsonPut } from "../llm-jsonput";
+
+export interface ChatOptions extends LlmRequestOptions {
+  adapter?: LLMMode;
+}
+
+@Injectable()
+export class LlmProxyService {
+  private adapters: Map<LLMMode, LlmAdapter> = new Map();
+
+  constructor(
+    @Inject("LLM_PROXY_CONFIG") private readonly config: LlmProxyConfig,
+    private readonly claudeCodeAdapter: ClaudeCodeAdapter,
+    private readonly openaiAdapter: OpenAIAdapter,
+    private readonly openCodeAdapter: OpenCodeAdapter,
+  ) {
+    this.adapters.set("claude-code", claudeCodeAdapter);
+    this.adapters.set("openai", openaiAdapter);
+    this.adapters.set("open-code", openCodeAdapter);
+  }
+
+  createSession(adapterType?: LLMMode, options?: SessionOptions): LlmSession {
+    const type = adapterType || this.getDefaultAdapterType();
+    const adapter = this.getAdapter(type);
+
+    return new LlmSessionImpl(adapter, options);
+  }
+
+  async chat(messages: LlmMessage[], options?: ChatOptions): Promise<LlmResponse> {
+    const adapterType = options?.adapter || this.getDefaultAdapterType();
+    const adapter = this.getAdapter(adapterType);
+
+    if (!adapter.isSupportJsonSchema() && options?.jsonSchema) {
+      messages = this.appendJsonSchemaSystemPrompt(messages, options.jsonSchema);
+    }
+
+    const response = await adapter.chat(messages, options);
+
+    if (options?.jsonSchema && response.content && !response.structuredOutput) {
+      response.structuredOutput = await options.jsonSchema.parse(response.content);
+    }
+
+    return response;
+  }
+
+  async *chatStream(
+    messages: LlmMessage[],
+    options?: ChatOptions,
+  ): AsyncIterable<import("./interfaces").LlmStreamEvent> {
+    const adapterType = options?.adapter || this.getDefaultAdapterType();
+    const adapter = this.getAdapter(adapterType);
+
+    if (!adapter.isSupportJsonSchema() && options?.jsonSchema) {
+      messages = this.appendJsonSchemaSystemPrompt(messages, options.jsonSchema);
+    }
+
+    for await (const event of adapter.chatStream(messages, options)) {
+      if (
+        event.type === "result" &&
+        options?.jsonSchema &&
+        event.response.content &&
+        !event.response.structuredOutput
+      ) {
+        try {
+          event.response.structuredOutput = await options.jsonSchema.parse(event.response.content);
+        } catch (error: any) {
+          // JSON 解析失败，保持 structuredOutput 为 undefined
+          console.error("[LLMProxyService.chatStream] JSON 解析失败:", error);
+        }
+      }
+      yield event;
+    }
+  }
+
+  appendJsonSchemaSystemPrompt(messages: LlmMessage[], jsonSchema: LlmJsonPut): LlmMessage[] {
+    const systemMsg = messages.find((msg) => msg.role === "system");
+    if (jsonSchema.isMatched(systemMsg?.content || "")) {
+      return messages;
+    }
+    if (systemMsg) {
+      systemMsg.content += `\n\n${jsonSchema.jsonFormatInstruction}`;
+    } else {
+      messages.unshift({ role: "system", content: jsonSchema.jsonFormatInstruction });
+    }
+    return messages;
+  }
+
+  getAvailableAdapters(): LLMMode[] {
+    const available: LLMMode[] = [];
+
+    for (const [type, adapter] of this.adapters) {
+      if (adapter.isConfigured()) {
+        available.push(type);
+      }
+    }
+
+    return available;
+  }
+
+  private getDefaultAdapterType(): LLMMode {
+    return this.config.defaultAdapter || "openai";
+  }
+
+  private getAdapter(type: LLMMode): LlmAdapter {
+    const adapter = this.adapters.get(type);
+
+    if (!adapter) {
+      throw new Error(`[LLMProxy.getAdapter] 不支持的 LLM 类型: ${type}`);
+    }
+
+    if (!adapter.isConfigured()) {
+      throw new Error(`[LLMProxy.getAdapter] 适配器 "${type}" 未配置`);
+    }
+
+    return adapter;
+  }
+}

package/src/shared/llm-proxy/llm-session.spec.ts

@@ -0,0 +1,111 @@
+import { vi, type Mocked } from "vitest";
+import { LlmSessionImpl } from "./llm-session";
+import { LlmAdapter } from "./adapters";
+import { LlmStreamEvent } from "./interfaces";
+
+describe("LlmSessionImpl", () => {
+  let adapter: Mocked<LlmAdapter>;
+  let session: LlmSessionImpl;
+
+  beforeEach(() => {
+    adapter = {
+      name: "test-adapter",
+      chat: vi.fn(),
+      chatStream: vi.fn(),
+      isConfigured: vi.fn().mockReturnValue(true),
+    } as any;
+
+    session = new LlmSessionImpl(adapter);
+  });
+
+  it("should initialize with a random UUID and adapter name", () => {
+    expect(session.id).toBeDefined();
+    expect(session.adapterName).toBe("test-adapter");
+  });
+
+  it("should initialize with session options", () => {
+    const options = {
+      systemPrompt: "You are a helper",
+      model: "gpt-4",
+      verbose: 1 as const,
+    };
+    const sessionWithOptions = new LlmSessionImpl(adapter, options);
+
+    // Testing private state via history building and chat
+    expect(sessionWithOptions.getHistory()).toEqual([]);
+  });
+
+  describe("send", () => {
+    it("should add messages to history and call adapter.chat", async () => {
+      const mockResponse = { content: "Hello there!", role: "assistant" };
+      adapter.chat.mockResolvedValue(mockResponse as any);
+
+      const response = await session.send("Hi");
+
+      expect(response).toEqual(mockResponse);
+      const history = session.getHistory();
+      expect(history).toHaveLength(2);
+      expect(history[0]).toEqual({ role: "user", content: "Hi" });
+      expect(history[1]).toEqual({ role: "assistant", content: "Hello there!" });
+
+      expect(adapter.chat).toHaveBeenCalledWith(
+        [{ role: "user", content: "Hi" }],
+        expect.objectContaining({ model: undefined, verbose: 0 }),
+      );
+    });
+
+    it("should include system prompt in messages sent to adapter", async () => {
+      session.setSystemPrompt("System instruction");
+      adapter.chat.mockResolvedValue({ content: "OK", role: "assistant" } as any);
+
+      await session.send("Hi");
+
+      expect(adapter.chat).toHaveBeenCalledWith(
+        [
+          { role: "system", content: "System instruction" },
+          { role: "user", content: "Hi" },
+        ],
+        expect.anything(),
+      );
+    });
+  });
+
+  describe("sendStream", () => {
+    it("should handle streaming events and update history", async () => {
+      const mockStream = (async function* () {
+        yield { type: "text", content: "Hello" } as LlmStreamEvent;
+        yield { type: "text", content: " world" } as LlmStreamEvent;
+        yield {
+          type: "result",
+          response: { content: "Hello world", role: "assistant" },
+        } as LlmStreamEvent;
+      })();
+      adapter.chatStream.mockReturnValue(mockStream as any);
+
+      const events: LlmStreamEvent[] = [];
+      for await (const event of session.sendStream("Hi")) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(3);
+      const history = session.getHistory();
+      expect(history).toHaveLength(2);
+      expect(history[1].content).toBe("Hello world");
+    });
+  });
+
+  describe("history management", () => {
+    it("should clear history", () => {
+      // Manually trigger a message (using send to populate)
+      // We'll mock it to be simple
+      session.clearHistory();
+      expect(session.getHistory()).toEqual([]);
+    });
+
+    it("should return a copy of history", () => {
+      const history = session.getHistory();
+      history.push({ role: "user", content: "modified" });
+      expect(session.getHistory()).toEqual([]);
+    });
+  });
+});

package/src/shared/llm-proxy/llm-session.ts

@@ -0,0 +1,109 @@
+import { randomUUID } from "crypto";
+import type { LlmAdapter } from "./adapters";
+import type {
+  LlmMessage,
+  LlmRequestOptions,
+  LlmResponse,
+  LlmStreamEvent,
+  LlmSession,
+  SessionOptions,
+} from "./interfaces";
+import { type VerboseLevel, normalizeVerbose } from "../verbose";
+
+export class LlmSessionImpl implements LlmSession {
+  readonly id: string;
+  readonly adapterName: string;
+
+  private history: LlmMessage[] = [];
+  private systemPrompt: string = "";
+  private defaultModel?: string;
+  private verbose: VerboseLevel = 0;
+
+  constructor(
+    private readonly adapter: LlmAdapter,
+    options?: SessionOptions,
+  ) {
+    this.id = randomUUID();
+    this.adapterName = adapter.name;
+
+    if (options?.systemPrompt) {
+      this.systemPrompt = options.systemPrompt;
+    }
+    if (options?.model) {
+      this.defaultModel = options.model;
+    }
+    if (options?.verbose !== undefined) {
+      this.verbose = normalizeVerbose(options.verbose);
+    }
+  }
+
+  async send(content: string, options?: LlmRequestOptions): Promise<LlmResponse> {
+    const userMessage: LlmMessage = { role: "user", content };
+    this.history.push(userMessage);
+
+    const messages = this.buildMessages();
+    const mergedOptions = this.mergeOptions(options);
+
+    const response = await this.adapter.chat(messages, mergedOptions);
+
+    const assistantMessage: LlmMessage = { role: "assistant", content: response.content };
+    this.history.push(assistantMessage);
+
+    return response;
+  }
+
+  async *sendStream(content: string, options?: LlmRequestOptions): AsyncIterable<LlmStreamEvent> {
+    const userMessage: LlmMessage = { role: "user", content };
+    this.history.push(userMessage);
+
+    const messages = this.buildMessages();
+    const mergedOptions = this.mergeOptions(options);
+
+    let fullContent = "";
+
+    for await (const event of this.adapter.chatStream(messages, mergedOptions)) {
+      yield event;
+
+      if (event.type === "text") {
+        fullContent += event.content;
+      } else if (event.type === "result") {
+        fullContent = event.response.content;
+      }
+    }
+
+    const assistantMessage: LlmMessage = { role: "assistant", content: fullContent };
+    this.history.push(assistantMessage);
+  }
+
+  getHistory(): LlmMessage[] {
+    return [...this.history];
+  }
+
+  clearHistory(): void {
+    this.history = [];
+  }
+
+  setSystemPrompt(prompt: string): void {
+    this.systemPrompt = prompt;
+  }
+
+  private buildMessages(): LlmMessage[] {
+    const messages: LlmMessage[] = [];
+
+    if (this.systemPrompt) {
+      messages.push({ role: "system", content: this.systemPrompt });
+    }
+
+    messages.push(...this.history);
+
+    return messages;
+  }
+
+  private mergeOptions(options?: LlmRequestOptions): LlmRequestOptions {
+    return {
+      model: options?.model || this.defaultModel,
+      verbose: options?.verbose ?? this.verbose,
+      ...options,
+    };
+  }
+}