openclaw-server 0.1.0

package/src/core/reply-engine.test.ts

@@ -0,0 +1,76 @@
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { normalizeFreeText } from "./normalizer.js";
+import { loadPack } from "./pack-loader.js";
+import { ReplyEngine } from "./reply-engine.js";
+import { SessionStore } from "./session-store.js";
+
+describe("ReplyEngine FAQ matching", () => {
+  let engine: ReplyEngine;
+
+  beforeAll(async () => {
+    const packDir = fileURLToPath(new URL("../../packs/default", import.meta.url));
+    const pack = await loadPack(packDir);
+    engine = new ReplyEngine(pack, new SessionStore());
+  });
+
+  it("matches faq prompts across spacing and punctuation variants", () => {
+    for (const prompt of [
+      "\u4f60\u662f\u771f AI \u5417",
+      "\u4f60\u662f\u771f AI \u5417\uff1f",
+      "\u4f60\u662f\u771fAI\u5417",
+      "Are you a real AI?",
+    ]) {
+      const result = engine.respond({
+        sessionId: `faq-test:${prompt}`,
+        locale: "mixed",
+        model: "default-assistant",
+        stream: false,
+        systemPrompts: [],
+        history: [{ role: "user", text: prompt }],
+        userText: prompt,
+        normalizedUserText: normalizeFreeText(prompt),
+        tools: [],
+        toolChoice: undefined,
+      });
+
+      expect(result.templateId).toBe("faq.real-ai");
+      expect(result.text).toContain("\u4e0d\u4f1a\u8c03\u7528\u771f\u5b9e AI API");
+    }
+  });
+
+  it("matches fuzzy intent wording without overmatching unrelated prompts", () => {
+    const capabilitiesResult = engine.respond({
+      sessionId: "intent-test:capabilities",
+      locale: "zh-CN",
+      model: "default-assistant",
+      stream: false,
+      systemPrompts: [],
+      history: [{ role: "user", text: "你会做什么" }],
+      userText: "你会做什么",
+      normalizedUserText: normalizeFreeText("你会做什么"),
+      tools: [],
+      toolChoice: undefined,
+    });
+    expect(capabilitiesResult.templateId).toBe("capabilities.help");
+    expect(capabilitiesResult.text).toContain("任务和提醒");
+    expect(capabilitiesResult.text).toContain("天气查询");
+
+    const fallbackResult = engine.respond({
+      sessionId: "intent-test:fallback",
+      locale: "zh-CN",
+      model: "default-assistant",
+      stream: false,
+      systemPrompts: [],
+      history: [{ role: "user", text: "随便说点啥" }],
+      userText: "随便说点啥",
+      normalizedUserText: normalizeFreeText("随便说点啥"),
+      tools: [],
+      toolChoice: undefined,
+    });
+    expect(fallbackResult.templateId).toBe("fallback.default");
+    expect(fallbackResult.text).toContain("我有哪些任务");
+    expect(fallbackResult.text).toContain("天津明天天气如何");
+    expect(fallbackResult.text).not.toContain("网关日志");
+  });
+});

package/src/core/reply-engine.ts

@@ -0,0 +1,256 @@
+import type {
+  EngineResult,
+  LoadedPack,
+  NormalizedTurn,
+  ScenarioDefinition,
+  ScenarioNodeDefinition,
+  SessionState,
+} from "../types.js";
+import { compileFaqs, compileIntents, findBestFaq, findBestIntent } from "./matcher.js";
+import { normalizeFreeText } from "./normalizer.js";
+import { SessionStore } from "./session-store.js";
+import { selectToolCall } from "./tool-engine.js";
+
+function renderTemplate(text: string, context: Record<string, string>): string {
+  return text.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (_match, key: string) => context[key] ?? "");
+}
+
+function chooseTemplateVariant(variants: string[], seed: string): string {
+  if (variants.length === 1) {
+    return variants[0];
+  }
+  let sum = 0;
+  for (const char of seed) {
+    sum += char.charCodeAt(0);
+  }
+  return variants[sum % variants.length];
+}
+
+function getTemplateText(
+  pack: LoadedPack,
+  templateId: string,
+  seed: string,
+  context: Record<string, string>,
+): string {
+  const template = pack.templatesById.get(templateId);
+  if (!template) {
+    throw new Error(`Template not found: ${templateId}`);
+  }
+  return renderTemplate(chooseTemplateVariant(template.variants, seed), context).trim();
+}
+
+function buildContext(
+  turn: NormalizedTurn,
+  session: SessionState,
+  matchedIntentId?: string,
+): Record<string, string> {
+  return {
+    locale: turn.locale,
+    modelId: turn.model,
+    sessionId: session.sessionId,
+    matchedIntent: matchedIntentId ?? "",
+    userText: turn.userText,
+  };
+}
+
+function nextNodeForScenario(
+  scenario: ScenarioDefinition,
+  currentNode: ScenarioNodeDefinition,
+): ScenarioNodeDefinition | undefined {
+  if (currentNode.nextId) {
+    return scenario.nodes.find((node) => node.id === currentNode.nextId);
+  }
+  const index = scenario.nodes.findIndex((node) => node.id === currentNode.id);
+  if (index < 0) {
+    return undefined;
+  }
+  return scenario.nodes[index + 1];
+}
+
+export class ReplyEngine {
+  private readonly compiledIntents: ReturnType<typeof compileIntents>;
+  private readonly compiledFaqs: ReturnType<typeof compileFaqs>;
+
+  constructor(
+    private readonly pack: LoadedPack,
+    private readonly sessionStore: SessionStore,
+  ) {
+    this.compiledIntents = compileIntents(pack.intents);
+    this.compiledFaqs = compileFaqs(pack.faqs);
+  }
+
+  respond(turn: NormalizedTurn): EngineResult {
+    const session = this.sessionStore.get(turn.sessionId, turn.locale);
+    session.turnCount += 1;
+
+    const continued = this.tryContinueScenario(turn, session);
+    if (continued) {
+      return continued;
+    }
+
+    const matchedFaq = findBestFaq(this.compiledFaqs, turn.userText);
+    if (matchedFaq) {
+      return this.replyWithTemplate(turn, session, matchedFaq.responseTemplateId, matchedFaq.id);
+    }
+
+    const matchedIntent = findBestIntent(this.compiledIntents, turn.userText);
+    if (!matchedIntent) {
+      return this.replyWithTemplate(turn, session, this.pack.manifest.fallbackTemplateId);
+    }
+
+    session.lastIntentId = matchedIntent.id;
+
+    const toolCall = selectToolCall({
+      turn,
+      intent: matchedIntent,
+      pack: this.pack,
+    });
+    if (toolCall) {
+      this.sessionStore.clearScenario(session);
+      this.sessionStore.save(session, {
+        kind: "tool_call",
+        matchedIntentId: matchedIntent.id,
+        toolName: toolCall.function.name,
+      });
+      return {
+        model: turn.model,
+        sessionId: turn.sessionId,
+        text: null,
+        finishReason: "tool_calls",
+        matchedIntentId: matchedIntent.id,
+        toolCalls: [toolCall],
+      };
+    }
+
+    if (matchedIntent.scenarioId) {
+      const scenario = this.pack.scenariosById.get(matchedIntent.scenarioId);
+      if (scenario) {
+        return this.replyFromScenarioNode(
+          turn,
+          session,
+          scenario,
+          scenario.nodes[0],
+          matchedIntent.id,
+        );
+      }
+    }
+
+    const templateId = matchedIntent.responseTemplateId ?? this.pack.manifest.fallbackTemplateId;
+    return this.replyWithTemplate(turn, session, templateId, matchedIntent.id);
+  }
+
+  private tryContinueScenario(
+    turn: NormalizedTurn,
+    session: SessionState,
+  ): EngineResult | undefined {
+    if (!session.activeScenarioId || !session.activeNodeId) {
+      return undefined;
+    }
+
+    const scenario = this.pack.scenariosById.get(session.activeScenarioId);
+    if (!scenario) {
+      this.sessionStore.clearScenario(session);
+      this.sessionStore.save(session, { kind: "scenario_missing" });
+      return undefined;
+    }
+
+    const currentNode = scenario.nodes.find((node) => node.id === session.activeNodeId);
+    if (!currentNode) {
+      this.sessionStore.clearScenario(session);
+      this.sessionStore.save(session, { kind: "scenario_node_missing", scenarioId: scenario.id });
+      return undefined;
+    }
+
+    const continueKeywords = new Set(
+      [...this.pack.manifest.continueKeywords, ...currentNode.continueKeywords].map((item) =>
+        normalizeFreeText(item),
+      ),
+    );
+    if (!continueKeywords.has(turn.normalizedUserText)) {
+      return undefined;
+    }
+
+    const nextNode = nextNodeForScenario(scenario, currentNode);
+    if (!nextNode) {
+      this.sessionStore.clearScenario(session);
+      this.sessionStore.save(session, { kind: "scenario_completed", scenarioId: scenario.id });
+      return this.replyWithTemplate(
+        turn,
+        session,
+        this.pack.manifest.fallbackTemplateId,
+        session.lastIntentId,
+      );
+    }
+
+    return this.replyFromScenarioNode(turn, session, scenario, nextNode, session.lastIntentId);
+  }
+
+  private replyFromScenarioNode(
+    turn: NormalizedTurn,
+    session: SessionState,
+    scenario: ScenarioDefinition,
+    node: ScenarioNodeDefinition,
+    matchedIntentId?: string,
+  ): EngineResult {
+    const text = getTemplateText(
+      this.pack,
+      node.responseTemplateId,
+      `${session.sessionId}:${node.responseTemplateId}:${session.turnCount}`,
+      buildContext(turn, session, matchedIntentId),
+    );
+
+    session.activeScenarioId = scenario.id;
+    session.activeNodeId = node.id;
+    session.lastTemplateId = node.responseTemplateId;
+
+    if (node.end || !nextNodeForScenario(scenario, node)) {
+      this.sessionStore.clearScenario(session);
+    }
+
+    this.sessionStore.save(session, {
+      kind: "scenario_reply",
+      scenarioId: scenario.id,
+      nodeId: node.id,
+      matchedIntentId,
+    });
+
+    return {
+      model: turn.model,
+      sessionId: turn.sessionId,
+      text,
+      finishReason: "stop",
+      matchedIntentId,
+      templateId: node.responseTemplateId,
+    };
+  }
+
+  private replyWithTemplate(
+    turn: NormalizedTurn,
+    session: SessionState,
+    templateId: string,
+    matchedIntentId?: string,
+  ): EngineResult {
+    const text = getTemplateText(
+      this.pack,
+      templateId,
+      `${session.sessionId}:${templateId}:${session.turnCount}`,
+      buildContext(turn, session, matchedIntentId),
+    );
+    session.lastTemplateId = templateId;
+    this.sessionStore.clearScenario(session);
+    this.sessionStore.save(session, {
+      kind: "text_reply",
+      matchedIntentId,
+      templateId,
+    });
+
+    return {
+      model: turn.model,
+      sessionId: turn.sessionId,
+      text,
+      finishReason: "stop",
+      matchedIntentId,
+      templateId,
+    };
+  }
+}

package/src/core/request-adapter.ts

@@ -0,0 +1,65 @@
+import type {
+  ChatCompletionsRequest,
+  ChatMessage,
+  ResponsesInputItem,
+  ResponsesRequest,
+} from "../types.js";
+
+function appendMessage(messages: ChatMessage[], role: string, content: unknown): void {
+  if (typeof content === "string") {
+    const text = content.trim();
+    if (!text) {
+      return;
+    }
+    messages.push({ role, content: text });
+    return;
+  }
+  if (Array.isArray(content) && content.length === 0) {
+    return;
+  }
+  if (content === undefined || content === null) {
+    return;
+  }
+  messages.push({ role, content });
+}
+
+function appendResponsesInput(messages: ChatMessage[], item: ResponsesInputItem): void {
+  if (typeof item === "string") {
+    appendMessage(messages, "user", item);
+    return;
+  }
+
+  if (item.type === "input_text") {
+    appendMessage(messages, "user", item.text);
+    return;
+  }
+
+  const role = typeof item.role === "string" && item.role.trim() ? item.role.trim() : "user";
+  appendMessage(messages, role, item.content ?? item.text ?? "");
+}
+
+function normalizeResponsesInput(input: ResponsesRequest["input"]): ResponsesInputItem[] {
+  return Array.isArray(input) ? input : [input];
+}
+
+export function responseRequestToChatRequest(request: ResponsesRequest): ChatCompletionsRequest {
+  const messages: ChatMessage[] = [];
+  const instructions = request.instructions?.trim();
+  if (instructions) {
+    messages.push({ role: "system", content: instructions });
+  }
+
+  for (const item of normalizeResponsesInput(request.input)) {
+    appendResponsesInput(messages, item);
+  }
+
+  return {
+    model: request.model,
+    stream: request.stream,
+    user: request.user,
+    messages,
+    tools: request.tools,
+    tool_choice: request.tool_choice,
+    max_tokens: request.max_output_tokens,
+  };
+}

package/src/core/session-store.ts

@@ -0,0 +1,48 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { SessionState } from "../types.js";
+
+export class SessionStore {
+  private readonly sessions = new Map<string, SessionState>();
+  private logWrite = Promise.resolve();
+
+  constructor(private readonly sessionLogPath?: string) {}
+
+  get(sessionId: string, locale: string): SessionState {
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      return existing;
+    }
+
+    const created: SessionState = {
+      sessionId,
+      locale,
+      turnCount: 0,
+    };
+    this.sessions.set(sessionId, created);
+    return created;
+  }
+
+  size(): number {
+    return this.sessions.size;
+  }
+
+  save(state: SessionState, event?: Record<string, unknown>): void {
+    this.sessions.set(state.sessionId, state);
+    if (!this.sessionLogPath) {
+      return;
+    }
+
+    const payload = JSON.stringify({ ts: Date.now(), ...event, state }) + "\n";
+    this.logWrite = this.logWrite.then(async () => {
+      const dir = path.dirname(this.sessionLogPath as string);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.appendFile(this.sessionLogPath as string, payload, "utf8");
+    });
+  }
+
+  clearScenario(state: SessionState): void {
+    delete state.activeScenarioId;
+    delete state.activeNodeId;
+  }
+}

package/src/core/stream-renderer.ts

@@ -0,0 +1,237 @@
+import type { Response } from "express";
+import {
+  buildResponseFunctionCallItem,
+  buildResponsesInProgressResponse,
+  buildResponsesResponse,
+} from "../response-api.js";
+import type { ChatToolCall, EngineResult } from "../types.js";
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function writeChunk(res: Response, payload: Record<string, unknown>): void {
+  res.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+
+function writeEvent(res: Response, event: string, payload: Record<string, unknown>): void {
+  res.write(`event: ${event}\n`);
+  res.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+
+function writeDone(res: Response): void {
+  res.write("data: [DONE]\n\n");
+}
+
+function splitIntoChunks(text: string, chunkChars: number): string[] {
+  const chunks: string[] = [];
+  let buffer = "";
+
+  for (const char of text) {
+    buffer += char;
+    if (buffer.length < chunkChars && !/[.!?,;:，。！？；：\n]/u.test(char)) {
+      continue;
+    }
+    chunks.push(buffer);
+    buffer = "";
+  }
+
+  if (buffer) {
+    chunks.push(buffer);
+  }
+  return chunks.length > 0 ? chunks : [text];
+}
+
+export function setSseHeaders(res: Response): void {
+  res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+  res.setHeader("Cache-Control", "no-cache, no-transform");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders();
+}
+
+export async function streamTextCompletion(params: {
+  res: Response;
+  id: string;
+  model: string;
+  text: string;
+  initialDelayMs: number;
+  chunkChars: number;
+}): Promise<void> {
+  setSseHeaders(params.res);
+  writeChunk(params.res, {
+    id: params.id,
+    object: "chat.completion.chunk",
+    created: Math.floor(Date.now() / 1000),
+    model: params.model,
+    choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }],
+  });
+
+  await delay(params.initialDelayMs);
+
+  for (const chunk of splitIntoChunks(params.text, params.chunkChars)) {
+    writeChunk(params.res, {
+      id: params.id,
+      object: "chat.completion.chunk",
+      created: Math.floor(Date.now() / 1000),
+      model: params.model,
+      choices: [{ index: 0, delta: { content: chunk }, finish_reason: null }],
+    });
+    await delay(30);
+  }
+
+  writeChunk(params.res, {
+    id: params.id,
+    object: "chat.completion.chunk",
+    created: Math.floor(Date.now() / 1000),
+    model: params.model,
+    choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+  });
+  writeDone(params.res);
+  params.res.end();
+}
+
+export async function streamToolCallCompletion(params: {
+  res: Response;
+  id: string;
+  model: string;
+  toolCall: ChatToolCall;
+}): Promise<void> {
+  setSseHeaders(params.res);
+  writeChunk(params.res, {
+    id: params.id,
+    object: "chat.completion.chunk",
+    created: Math.floor(Date.now() / 1000),
+    model: params.model,
+    choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }],
+  });
+
+  writeChunk(params.res, {
+    id: params.id,
+    object: "chat.completion.chunk",
+    created: Math.floor(Date.now() / 1000),
+    model: params.model,
+    choices: [
+      {
+        index: 0,
+        delta: {
+          tool_calls: [
+            {
+              index: 0,
+              id: params.toolCall.id,
+              type: params.toolCall.type,
+              function: params.toolCall.function,
+            },
+          ],
+        },
+        finish_reason: null,
+      },
+    ],
+  });
+
+  writeChunk(params.res, {
+    id: params.id,
+    object: "chat.completion.chunk",
+    created: Math.floor(Date.now() / 1000),
+    model: params.model,
+    choices: [{ index: 0, delta: {}, finish_reason: "tool_calls" }],
+  });
+  writeDone(params.res);
+  params.res.end();
+}
+
+export async function streamResponsesText(params: {
+  res: Response;
+  id: string;
+  result: EngineResult;
+  outputItemId: string;
+  initialDelayMs: number;
+  chunkChars: number;
+}): Promise<void> {
+  const createdAt = Math.floor(Date.now() / 1000);
+  const text = params.result.text ?? "No response available.";
+  const finalResponse = buildResponsesResponse({
+    id: params.id,
+    result: params.result,
+    createdAt,
+    outputItemId: params.outputItemId,
+  });
+
+  setSseHeaders(params.res);
+  writeEvent(params.res, "response.created", {
+    type: "response.created",
+    response: buildResponsesInProgressResponse({
+      id: params.id,
+      model: params.result.model,
+      createdAt,
+    }),
+  });
+
+  await delay(params.initialDelayMs);
+
+  for (const chunk of splitIntoChunks(text, params.chunkChars)) {
+    writeEvent(params.res, "response.output_text.delta", {
+      type: "response.output_text.delta",
+      response_id: params.id,
+      item_id: params.outputItemId,
+      output_index: 0,
+      content_index: 0,
+      delta: chunk,
+    });
+    await delay(30);
+  }
+
+  writeEvent(params.res, "response.output_text.done", {
+    type: "response.output_text.done",
+    response_id: params.id,
+    item_id: params.outputItemId,
+    output_index: 0,
+    content_index: 0,
+    text,
+  });
+  writeEvent(params.res, "response.completed", {
+    type: "response.completed",
+    response: finalResponse,
+  });
+  params.res.end();
+}
+
+export async function streamResponsesToolCall(params: {
+  res: Response;
+  id: string;
+  result: EngineResult;
+  outputItemId: string;
+}): Promise<void> {
+  const toolCall = params.result.toolCalls?.[0];
+  if (!toolCall) {
+    throw new Error("Missing tool call for Responses API stream.");
+  }
+
+  const createdAt = Math.floor(Date.now() / 1000);
+  const finalResponse = buildResponsesResponse({
+    id: params.id,
+    result: params.result,
+    createdAt,
+    outputItemId: params.outputItemId,
+  });
+
+  setSseHeaders(params.res);
+  writeEvent(params.res, "response.created", {
+    type: "response.created",
+    response: buildResponsesInProgressResponse({
+      id: params.id,
+      model: params.result.model,
+      createdAt,
+    }),
+  });
+  writeEvent(params.res, "response.output_item.added", {
+    type: "response.output_item.added",
+    response_id: params.id,
+    output_index: 0,
+    item: buildResponseFunctionCallItem(toolCall, params.outputItemId),
+  });
+  writeEvent(params.res, "response.completed", {
+    type: "response.completed",
+    response: finalResponse,
+  });
+  params.res.end();
+}