重构世界模拟器为模块化配方架构，完善创作编排、会话运行时与 Web UI，并清理过时技能。

Co-authored-by: Cursor <cursoragent@cursor.com>

src/llm/client.ts

@@ -1,5 +1,6 @@
 import type { LlmConfig } from "../config/env.js";
 import type { GenerationParameters } from "../types/preset.js";
+import { consumeOpenAiToolStream } from "./stream-complete.js";
 
 export type ToolCallPayload = {
   id: string;
@@ -71,21 +72,36 @@ export type CompleteWithToolsResult = {
   model?: string;
 };
 
+export type StreamCallbacks = {
+  onReasoningDelta?: (delta: string) => void;
+  onContentDelta?: (delta: string) => void;
+};
+
 export type LlmProvider = {
   complete(
     messages: ChatMessage[],
     options?: CompleteOptions,
   ): Promise<CompleteResult>;
+  completeStream?(
+    messages: ChatMessage[],
+    options?: CompleteOptions,
+    callbacks?: StreamCallbacks,
+  ): Promise<CompleteResult>;
   completeWithTools(
     messages: ChatMessage[],
     options: CompleteWithToolsOptions,
   ): Promise<CompleteWithToolsResult>;
+  completeWithToolsStream?(
+    messages: ChatMessage[],
+    options: CompleteWithToolsOptions,
+    callbacks: StreamCallbacks,
+  ): Promise<CompleteWithToolsResult>;
 };
 
 function buildRequestBody(
   config: LlmConfig,
   messages: ChatMessage[],
-  options?: CompleteOptions & { tools?: ToolDefinition[] },
+  options?: CompleteOptions & { tools?: ToolDefinition[]; stream?: boolean },
 ): Record<string, unknown> {
   const gen = options?.generation ?? {};
   const body: Record<string, unknown> = {
@@ -125,6 +141,11 @@ function buildRequestBody(
     body.response_format = { type: "json_object" };
   }
 
+  if (options?.stream) {
+    body.stream = true;
+    body.stream_options = { include_usage: true };
+  }
+
   return body;
 }
 
@@ -255,6 +276,44 @@ export class OpenAiCompatibleProvider implements LlmProvider {
     };
   }
 
+  async completeStream(
+    messages: ChatMessage[],
+    options?: CompleteOptions,
+    callbacks: StreamCallbacks = {},
+  ): Promise<CompleteResult> {
+    const url = `${this.config.baseUrl.replace(/\/$/, "")}/chat/completions`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`,
+      },
+      body: JSON.stringify(
+        buildRequestBody(this.config, messages, { ...options, stream: true }),
+      ),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`LLM request failed (${response.status}): ${body}`);
+    }
+
+    if (!response.body) {
+      throw new Error("LLM stream response has no body");
+    }
+
+    const parts = await consumeOpenAiToolStream(response.body, callbacks);
+    if (!parts.content && !parts.reasoning) {
+      throw new Error("LLM stream returned empty content");
+    }
+    return {
+      content: parts.content ?? parts.reasoning ?? "",
+      reasoning: parts.reasoning || undefined,
+      usage: parts.usage,
+      model: parts.model ?? this.config.model,
+    };
+  }
+
   async completeWithTools(
     messages: ChatMessage[],
     options: CompleteWithToolsOptions,
@@ -296,6 +355,49 @@ export class OpenAiCompatibleProvider implements LlmProvider {
       model: data.model ?? this.config.model,
     };
   }
+
+  async completeWithToolsStream(
+    messages: ChatMessage[],
+    options: CompleteWithToolsOptions,
+    callbacks: StreamCallbacks,
+  ): Promise<CompleteWithToolsResult> {
+    const url = `${this.config.baseUrl.replace(/\/$/, "")}/chat/completions`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`,
+      },
+      body: JSON.stringify(
+        buildRequestBody(this.config, messages, {
+          ...options,
+          tools: options.tools,
+          stream: true,
+        }),
+      ),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`LLM request failed (${response.status}): ${body}`);
+    }
+
+    if (!response.body) {
+      throw new Error("LLM stream response has no body");
+    }
+
+    const parts = await consumeOpenAiToolStream(response.body, callbacks);
+    if (!parts.content && parts.toolCalls.length === 0 && !parts.reasoning) {
+      throw new Error("LLM stream returned empty content and no tool calls");
+    }
+    return {
+      content: parts.content,
+      toolCalls: parts.toolCalls,
+      reasoning: parts.reasoning || undefined,
+      usage: parts.usage,
+      model: parts.model ?? this.config.model,
+    };
+  }
 }
 
 export type MockLlmStep =
@@ -341,6 +443,39 @@ export class MockLlmProvider implements LlmProvider {
     };
   }
 
+  async completeStream(
+    _messages: ChatMessage[],
+    options?: CompleteOptions,
+    callbacks: StreamCallbacks = {},
+  ): Promise<CompleteResult> {
+    const step = this.nextStep();
+    const response =
+      typeof step === "string"
+        ? step
+        : (step.content ?? JSON.stringify({ action: "ask_user", reason: "mock" }));
+    const reasoning = "用户需要明确分工 → 调用 design-intake 产出 worker 集。";
+    for (const ch of reasoning) {
+      callbacks.onReasoningDelta?.(ch);
+      await new Promise((r) => setTimeout(r, 0));
+    }
+    for (const ch of response) {
+      callbacks.onContentDelta?.(ch);
+      await new Promise((r) => setTimeout(r, 0));
+    }
+    const approx = Math.max(1, Math.ceil(response.length / 4));
+    return {
+      content: response,
+      reasoning,
+      usage: {
+        promptTokens: approx,
+        completionTokens: approx,
+        totalTokens: approx * 2,
+      },
+      model: "mock",
+      ...(options?.caller ? {} : {}),
+    };
+  }
+
   async completeWithTools(
     _messages: ChatMessage[],
     _options: CompleteWithToolsOptions,
@@ -366,6 +501,20 @@ export class MockLlmProvider implements LlmProvider {
       model: "mock",
     };
   }
+
+  async completeWithToolsStream(
+    _messages: ChatMessage[],
+    _options: CompleteWithToolsOptions,
+    callbacks: StreamCallbacks,
+  ): Promise<CompleteWithToolsResult> {
+    const reasoning =
+      "用户需要明确 Worker 分工 → 先读取黑板与 worker 列表 → 调用 design-intake 产出 worker 集。";
+    for (const ch of reasoning) {
+      callbacks.onReasoningDelta?.(ch);
+      await new Promise((r) => setTimeout(r, 0));
+    }
+    return this.completeWithTools(_messages, _options);
+  }
 }
 
 export function createMockMainAgentResponse(

src/llm/preset-wrapper.ts

@@ -7,6 +7,7 @@ import type {
   CompleteWithToolsOptions,
   CompleteWithToolsResult,
   LlmProvider,
+  StreamCallbacks,
 } from "./client.js";
 
 /**
@@ -55,4 +56,23 @@ export class PresetLlmProvider implements LlmProvider {
       generation,
     });
   }
+
+  async completeWithToolsStream(
+    messages: ChatMessage[],
+    options: CompleteWithToolsOptions,
+    callbacks: StreamCallbacks,
+  ): Promise<CompleteWithToolsResult> {
+    const preset = this.getPreset();
+    if (!this.inner.completeWithToolsStream) {
+      return this.completeWithTools(messages, options);
+    }
+    const presetMessages = preset ? assemblePresetMessages(preset) : [];
+    const merged = preset ? mergeMessages(presetMessages, messages) : messages;
+    const generation = options.generation ?? preset?.generation;
+
+    return this.inner.completeWithToolsStream(merged, {
+      ...options,
+      generation,
+    }, callbacks);
+  }
 }

src/llm/stream-complete.ts

@@ -0,0 +1,149 @@
+import type {
+  ChatMessage,
+  CompleteWithToolsOptions,
+  CompleteWithToolsResult,
+  ParsedToolCall,
+  StreamCallbacks,
+  TokenUsage,
+} from "./client.js";
+import { parseUsage } from "./client.js";
+
+type ToolCallAccumulator = Map<
+  number,
+  { id?: string; name?: string; arguments: string }
+>;
+
+function applyToolCallDelta(
+  acc: ToolCallAccumulator,
+  raw: unknown,
+): void {
+  if (!Array.isArray(raw)) return;
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const row = item as Record<string, unknown>;
+    const index = Number(row.index ?? 0);
+    const entry = acc.get(index) ?? { arguments: "" };
+    if (typeof row.id === "string") entry.id = row.id;
+    const fn = row.function;
+    if (fn && typeof fn === "object") {
+      const f = fn as Record<string, unknown>;
+      if (typeof f.name === "string") entry.name = f.name;
+      if (typeof f.arguments === "string") entry.arguments += f.arguments;
+    }
+    acc.set(index, entry);
+  }
+}
+
+function toolCallsFromAccumulator(acc: ToolCallAccumulator): ParsedToolCall[] {
+  const out: ParsedToolCall[] = [];
+  for (const [, entry] of [...acc.entries()].sort((a, b) => a[0] - b[0])) {
+    const name = entry.name?.trim();
+    const id = entry.id?.trim();
+    if (!name || !id) continue;
+    out.push({ id, name, arguments: entry.arguments || "{}" });
+  }
+  return out;
+}
+
+/** 解析 OpenAI 兼容 SSE 流，累积 reasoning / content / tool_calls */
+export async function consumeOpenAiToolStream(
+  body: ReadableStream<Uint8Array>,
+  callbacks: StreamCallbacks,
+): Promise<{
+  content: string | null;
+  reasoning: string;
+  toolCalls: ParsedToolCall[];
+  usage?: TokenUsage;
+  model?: string;
+}> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let content = "";
+  let reasoning = "";
+  const toolAcc: ToolCallAccumulator = new Map();
+  let usage: TokenUsage | undefined;
+  let model: string | undefined;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("data:")) continue;
+      const payload = trimmed.slice(5).trim();
+      if (!payload || payload === "[DONE]") continue;
+
+      let parsed: Record<string, unknown>;
+      try {
+        parsed = JSON.parse(payload) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+
+      if (typeof parsed.model === "string") model = parsed.model;
+      const u = parseUsage(parsed.usage);
+      if (u) usage = u;
+
+      const choice = (parsed.choices as unknown[])?.[0];
+      if (!choice || typeof choice !== "object") continue;
+      const delta = (choice as Record<string, unknown>).delta;
+      if (!delta || typeof delta !== "object") continue;
+      const d = delta as Record<string, unknown>;
+
+      if (typeof d.reasoning_content === "string" && d.reasoning_content) {
+        reasoning += d.reasoning_content;
+        callbacks.onReasoningDelta?.(d.reasoning_content);
+      }
+      if (typeof d.content === "string" && d.content) {
+        content += d.content;
+        callbacks.onContentDelta?.(d.content);
+      }
+      if (d.tool_calls) applyToolCallDelta(toolAcc, d.tool_calls);
+    }
+  }
+
+  return {
+    content: content.trim() || null,
+    reasoning: reasoning.trim(),
+    toolCalls: toolCallsFromAccumulator(toolAcc),
+    usage,
+    model,
+  };
+}
+
+export type StreamableLlm = {
+  completeWithToolsStream?(
+    messages: ChatMessage[],
+    options: CompleteWithToolsOptions,
+    callbacks: StreamCallbacks,
+  ): Promise<CompleteWithToolsResult>;
+};
+
+export function supportsToolStream(llm: unknown): llm is StreamableLlm {
+  return (
+    typeof llm === "object" &&
+    llm != null &&
+    typeof (llm as StreamableLlm).completeWithToolsStream === "function"
+  );
+}
+
+export type ContentStreamableLlm = {
+  completeStream?(
+    messages: ChatMessage[],
+    options?: import("./client.js").CompleteOptions,
+    callbacks?: StreamCallbacks,
+  ): Promise<import("./client.js").CompleteResult>;
+};
+
+export function supportsContentStream(llm: unknown): llm is ContentStreamableLlm {
+  return (
+    typeof llm === "object" &&
+    llm != null &&
+    typeof (llm as ContentStreamableLlm).completeStream === "function"
+  );
+}

src/llm/token-tracker.ts

@@ -4,12 +4,17 @@ import type {
   CompleteWithToolsOptions,
   CompleteWithToolsResult,
   LlmProvider,
+  StreamCallbacks,
 } from "./client.js";
 import {
   recordTokenUsage,
   toMessageTokenUsage,
   type MessageTokenUsage,
 } from "../stats/token-store.js";
+import {
+  buildContextTrace,
+  type LlmContextTrace,
+} from "../types/context-trace.js";
 
 export type LlmTrackingContext = {
   sessionId?: string;
@@ -19,8 +24,23 @@ export type LlmTrackingContext = {
   /** Set after each LLM call; consumed when the next system chat message is created */
   pendingUsage?: MessageTokenUsage;
   pendingReasoning?: string;
+  /** 全量请求上下文；挂到下一条「结果向」系统消息 */
+  pendingContextTrace?: LlmContextTrace;
 };
 
+function capturePendingTrace(
+  ctx: LlmTrackingContext,
+  messages: Array<{ role: string; content: string }>,
+  caller: string | undefined,
+  model?: string,
+): void {
+  ctx.pendingContextTrace = buildContextTrace({
+    caller: caller ?? "unknown",
+    messages,
+    model,
+  });
+}
+
 export class TokenTrackingProvider implements LlmProvider {
   constructor(
     private readonly inner: LlmProvider,
@@ -33,6 +53,53 @@ export class TokenTrackingProvider implements LlmProvider {
   ): Promise<CompleteResult> {
     const result = await this.inner.complete(messages, options);
     const ctx = this.getContext();
+    capturePendingTrace(ctx, messages, options?.caller, result.model);
+    if (result.usage) {
+      const record = recordTokenUsage({
+        sessionId: ctx.sessionId,
+        bookId: ctx.bookId,
+        bookTitle: ctx.bookTitle,
+        orchestratorId: ctx.orchestratorId,
+        caller: options?.caller ?? "unknown",
+        model: result.model ?? "unknown",
+        promptTokens: result.usage.promptTokens,
+        completionTokens: result.usage.completionTokens,
+        totalTokens: result.usage.totalTokens,
+        cachedTokens: result.usage.cachedTokens,
+        cacheMissTokens: result.usage.cacheMissTokens,
+      });
+      ctx.pendingUsage = toMessageTokenUsage(record);
+    }
+    if (result.reasoning?.trim()) {
+      ctx.pendingReasoning = result.reasoning.trim();
+    }
+    return result;
+  }
+
+  async completeStream(
+    messages: Parameters<LlmProvider["complete"]>[0],
+    options?: CompleteOptions,
+    callbacks: StreamCallbacks = {},
+  ): Promise<CompleteResult> {
+    const inner = this.inner;
+    if (!inner.completeStream) {
+      const result = await this.complete(messages, options);
+      if (result.reasoning) callbacks.onReasoningDelta?.(result.reasoning);
+      if (result.content) callbacks.onContentDelta?.(result.content);
+      return result;
+    }
+    let reasoningBuf = "";
+    const result = await inner.completeStream(messages, options, {
+      onReasoningDelta: (delta) => {
+        reasoningBuf += delta;
+        const ctx = this.getContext();
+        ctx.pendingReasoning = reasoningBuf;
+        callbacks.onReasoningDelta?.(delta);
+      },
+      onContentDelta: callbacks.onContentDelta,
+    });
+    const ctx = this.getContext();
+    capturePendingTrace(ctx, messages, options?.caller, result.model);
     if (result.usage) {
       const record = recordTokenUsage({
         sessionId: ctx.sessionId,
@@ -61,6 +128,50 @@ export class TokenTrackingProvider implements LlmProvider {
   ): Promise<CompleteWithToolsResult> {
     const result = await this.inner.completeWithTools(messages, options);
     const ctx = this.getContext();
+    capturePendingTrace(ctx, messages, options.caller, result.model);
+    if (result.usage) {
+      const record = recordTokenUsage({
+        sessionId: ctx.sessionId,
+        bookId: ctx.bookId,
+        bookTitle: ctx.bookTitle,
+        orchestratorId: ctx.orchestratorId,
+        caller: options.caller ?? "unknown",
+        model: result.model ?? "unknown",
+        promptTokens: result.usage.promptTokens,
+        completionTokens: result.usage.completionTokens,
+        totalTokens: result.usage.totalTokens,
+        cachedTokens: result.usage.cachedTokens,
+        cacheMissTokens: result.usage.cacheMissTokens,
+      });
+      ctx.pendingUsage = toMessageTokenUsage(record);
+    }
+    if (result.reasoning?.trim()) {
+      ctx.pendingReasoning = result.reasoning.trim();
+    }
+    return result;
+  }
+
+  async completeWithToolsStream(
+    messages: Parameters<LlmProvider["completeWithTools"]>[0],
+    options: CompleteWithToolsOptions,
+    callbacks: StreamCallbacks,
+  ): Promise<CompleteWithToolsResult> {
+    const inner = this.inner;
+    if (!inner.completeWithToolsStream) {
+      return this.completeWithTools(messages, options);
+    }
+    let reasoningBuf = "";
+    const result = await inner.completeWithToolsStream(messages, options, {
+      onReasoningDelta: (delta) => {
+        reasoningBuf += delta;
+        const ctx = this.getContext();
+        ctx.pendingReasoning = reasoningBuf;
+        callbacks.onReasoningDelta?.(delta);
+      },
+      onContentDelta: callbacks.onContentDelta,
+    });
+    const ctx = this.getContext();
+    capturePendingTrace(ctx, messages, options.caller, result.model);
     if (result.usage) {
       const record = recordTokenUsage({
         sessionId: ctx.sessionId,