@jpssff/vanor 0.1.0

package/base/llm/index.js

@@ -0,0 +1,119 @@
+// LLM 统一入口：模型解析、流式调用、重试与跨模型 failover。
+
+import { EVENTS } from "../events.js";
+import { sleep } from "../utils.js";
+import { streamOpenAI } from "./providers/openai.js";
+import { streamAnthropic } from "./providers/anthropic.js";
+import { createTracer } from "./trace.js";
+
+const PROVIDER_FNS = {
+  openai: streamOpenAI,
+  anthropic: streamAnthropic,
+};
+
+/**
+ * 解析 "<providerName>/<modelId...>"。providerName 取第一个 "/" 之前，
+ * 其余为 modelId（允许包含 "/"，如 deepseek/deepseek-v4-pro）。
+ */
+export function resolveModel(config, modelStr) {
+  const str = modelStr || config.llm.defaultModel;
+  if (!str) throw new Error("未指定模型，且 llm.defaultModel 为空");
+  const slash = str.indexOf("/");
+  if (slash < 0) throw new Error(`模型名需为 "<provider>/<model>" 形式：${str}`);
+  const providerName = str.slice(0, slash);
+  const modelId = str.slice(slash + 1);
+  const conf = config.llm.providers?.[providerName];
+  if (!conf) throw new Error(`未找到 provider "${providerName}"，请检查 llm.providers 配置`);
+  const type = conf.type || "openai";
+  const fn = PROVIDER_FNS[type];
+  if (!fn) throw new Error(`不支持的 provider 类型 "${type}"`);
+  return { providerName, modelId, type, conf, fn };
+}
+
+function backoff(attempt) {
+  return Math.min(8000, 300 * 2 ** attempt) + Math.floor(Math.random() * 200);
+}
+
+export function createLLM(config, logger) {
+  const maxRetries = 2;
+  const tracer = createTracer(config, logger);
+
+  /**
+   * 流式调用。req: { model?, messages, tools?, signal? }
+   * 产出 LLMChunk。失败时按模型列表 failover（仅在尚未产出任何 chunk 时）。
+   */
+  async function* stream(req) {
+    const candidates = [req.model || config.llm.defaultModel, ...(config.llm.fallback || [])]
+      .filter(Boolean);
+    let lastErr;
+
+    for (const modelStr of candidates) {
+      let resolved;
+      try {
+        resolved = resolveModel(config, modelStr);
+      } catch (e) {
+        lastErr = e;
+        continue;
+      }
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        let produced = false;
+        try {
+          logger.info(EVENTS.llm.request, { model: modelStr, attempt });
+          const iter = resolved.fn({
+            baseURL: resolved.conf.baseURL,
+            apiKey: resolved.conf.apiKey,
+            model: resolved.modelId,
+            messages: req.messages,
+            tools: req.tools,
+            signal: req.signal,
+            trace: tracer,
+            providerName: resolved.providerName,
+          });
+          for await (const chunk of iter) {
+            produced = true;
+            yield chunk;
+          }
+          logger.info(EVENTS.llm.response, { model: modelStr });
+          return; // 成功
+        } catch (e) {
+          lastErr = e;
+          if (e.name === "AbortError") throw e;
+          logger.warn(EVENTS.llm.error, {
+            model: modelStr,
+            attempt,
+            retriable: !!e.retriable,
+            produced,
+            error: e.message,
+          });
+          // 已产出部分内容：无法安全重放，交由上层处理
+          if (produced) throw e;
+          if (e.retriable && attempt < maxRetries) {
+            logger.info(EVENTS.llm.retry, { model: modelStr, attempt });
+            await sleep(backoff(attempt));
+            continue;
+          }
+          break; // 不可重试或已耗尽 → 尝试下一个候选模型
+        }
+      }
+    }
+    throw lastErr || new Error("LLM 调用失败");
+  }
+
+  /** 便捷：消费整个流，返回 { text, toolCalls, usage }。 */
+  async function gather(req) {
+    let text = "";
+    const toolCalls = [];
+    let usage = null;
+    let finishReason = "stop";
+    for await (const chunk of stream(req)) {
+      if (chunk.type === "text") text += chunk.delta;
+      else if (chunk.type === "tool_call") toolCalls.push(chunk.call);
+      else if (chunk.type === "usage") usage = chunk.usage;
+      else if (chunk.type === "done") finishReason = chunk.finishReason;
+    }
+    return { text, toolCalls, usage, finishReason };
+  }
+
+  return { stream, gather, resolveModel: (m) => resolveModel(config, m) };
+}

package/base/llm/providers/anthropic.js

@@ -0,0 +1,147 @@
+// Anthropic Messages API 适配。
+
+import { readLines } from "../sse.js";
+
+const DEFAULT_BASE = "https://api.anthropic.com";
+
+function toAnthropic(messages) {
+  let system = "";
+  const out = [];
+  for (const m of messages) {
+    if (m.role === "system") {
+      system += (system ? "\n\n" : "") + (m.content || "");
+      continue;
+    }
+    if (m.role === "tool") {
+      out.push({
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: m.toolCallId, content: m.content || "" },
+        ],
+      });
+      continue;
+    }
+    if (m.role === "assistant" && m.toolCalls?.length) {
+      const blocks = [];
+      if (m.content) blocks.push({ type: "text", text: m.content });
+      for (const tc of m.toolCalls) {
+        blocks.push({ type: "tool_use", id: tc.id, name: tc.name, input: tc.arguments ?? {} });
+      }
+      out.push({ role: "assistant", content: blocks });
+      continue;
+    }
+    out.push({ role: m.role, content: m.content || "" });
+  }
+  return { system, messages: out };
+}
+
+function toAnthropicTools(tools) {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.parameters,
+  }));
+}
+
+export async function* streamAnthropic({ baseURL, apiKey, model, messages, tools, signal, trace, providerName }) {
+  const url = `${(baseURL || DEFAULT_BASE).replace(/\/$/, "")}/v1/messages`;
+  const { system, messages: msgs } = toAnthropic(messages);
+  const body = {
+    model,
+    max_tokens: 4096,
+    stream: true,
+    messages: msgs,
+  };
+  if (system) body.system = system;
+  if (tools?.length) body.tools = toAnthropicTools(tools);
+
+  const headers = {
+    "Content-Type": "application/json",
+    "x-api-key": apiKey,
+    "anthropic-version": "2023-06-01",
+  };
+  const started = Date.now();
+  trace?.request({ provider: providerName, model, url, headers, body });
+
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal });
+  } catch (e) {
+    if (e.name === "AbortError") throw e;
+    trace?.response({ provider: providerName, model, ms: Date.now() - started, error: `网络错误: ${e.message}` });
+    throw Object.assign(new Error(`网络错误: ${e.message}`), { retriable: true });
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    trace?.response({ provider: providerName, model, status: res.status, ms: Date.now() - started, error: text.slice(0, 2000) });
+    const err = new Error(`Anthropic 接口 HTTP ${res.status}: ${text.slice(0, 300)}`);
+    err.retriable = res.status === 429 || res.status === 408 || res.status >= 500;
+    throw err;
+  }
+
+  const toolBlocks = new Map(); // index → { id, name, json }
+  let finishReason = "stop";
+  let fullText = "";
+  let lastUsage = null;
+
+  for await (const line of readLines(res)) {
+    if (!line.startsWith("data:")) continue;
+    const data = line.slice(5).trim();
+    if (!data) continue;
+    let ev;
+    try {
+      ev = JSON.parse(data);
+    } catch {
+      continue;
+    }
+
+    if (ev.type === "content_block_start" && ev.content_block?.type === "tool_use") {
+      toolBlocks.set(ev.index, { id: ev.content_block.id, name: ev.content_block.name, json: "" });
+    } else if (ev.type === "content_block_delta") {
+      if (ev.delta?.type === "text_delta") {
+        if (trace?.enabled) fullText += ev.delta.text;
+        yield { type: "text", delta: ev.delta.text };
+      } else if (ev.delta?.type === "input_json_delta") {
+        const acc = toolBlocks.get(ev.index);
+        if (acc) acc.json += ev.delta.partial_json || "";
+      }
+    } else if (ev.type === "message_delta") {
+      if (ev.usage) {
+        lastUsage = {
+          promptTokens: ev.usage.input_tokens ?? 0,
+          completionTokens: ev.usage.output_tokens ?? 0,
+          totalTokens: (ev.usage.input_tokens ?? 0) + (ev.usage.output_tokens ?? 0),
+        };
+        yield { type: "usage", usage: lastUsage };
+      }
+      if (ev.delta?.stop_reason) finishReason = ev.delta.stop_reason;
+    }
+  }
+
+  const calls = [];
+  for (const acc of toolBlocks.values()) {
+    let parsed = {};
+    try {
+      parsed = acc.json ? JSON.parse(acc.json) : {};
+    } catch {
+      parsed = { __raw: acc.json };
+    }
+    const call = { id: acc.id, name: acc.name, arguments: parsed };
+    calls.push(call);
+    yield { type: "tool_call", call };
+  }
+
+  trace?.response({
+    provider: providerName,
+    model,
+    status: res.status,
+    ms: Date.now() - started,
+    text: fullText,
+    toolCalls: calls,
+    usage: lastUsage,
+    finishReason,
+  });
+
+  yield { type: "done", finishReason };
+}

package/base/llm/providers/openai.js

@@ -0,0 +1,155 @@
+// OpenAI Chat Completions 兼容适配（OpenAI、兼容端点、多数国产/开源厂商）。
+
+import { readLines } from "../sse.js";
+
+function toOpenAIMessages(messages) {
+  return messages.map((m) => {
+    if (m.role === "assistant") {
+      const out = { role: "assistant", content: m.content || "" };
+      if (m.toolCalls?.length) {
+        out.content = m.content || null;
+        out.tool_calls = m.toolCalls.map((tc) => ({
+          id: tc.id,
+          type: "function",
+          function: { name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) },
+        }));
+      }
+      return out;
+    }
+    if (m.role === "tool") {
+      return { role: "tool", tool_call_id: m.toolCallId, content: m.content || "" };
+    }
+    return { role: m.role, content: m.content || "" };
+  });
+}
+
+function toOpenAITools(tools) {
+  return tools.map((t) => ({
+    type: "function",
+    function: { name: t.name, description: t.description, parameters: t.parameters },
+  }));
+}
+
+function httpError(status, body) {
+  const err = new Error(`OpenAI 接口 HTTP ${status}: ${String(body).slice(0, 300)}`);
+  // 429 / 5xx / 408 视为可重试
+  err.retriable = status === 429 || status === 408 || status >= 500;
+  err.status = status;
+  return err;
+}
+
+/**
+ * 流式调用，产出 LLMChunk：
+ *   { type:"text", delta } | { type:"tool_call", call } | { type:"usage", usage } | { type:"done", finishReason }
+ */
+export async function* streamOpenAI({ baseURL, apiKey, model, messages, tools, signal, trace, providerName }) {
+  const url = `${baseURL.replace(/\/$/, "")}/chat/completions`;
+  const body = {
+    model,
+    messages: toOpenAIMessages(messages),
+    stream: true,
+    stream_options: { include_usage: true },
+  };
+  if (tools?.length) {
+    body.tools = toOpenAITools(tools);
+    body.tool_choice = "auto";
+  }
+
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${apiKey}`,
+  };
+  const started = Date.now();
+  trace?.request({ provider: providerName, model, url, headers, body });
+
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal });
+  } catch (e) {
+    if (e.name === "AbortError") throw e;
+    trace?.response({ provider: providerName, model, ms: Date.now() - started, error: `网络错误: ${e.message}` });
+    throw Object.assign(new Error(`网络错误: ${e.message}`), { retriable: true });
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    trace?.response({ provider: providerName, model, status: res.status, ms: Date.now() - started, error: text.slice(0, 2000) });
+    throw httpError(res.status, text);
+  }
+
+  // 累积 tool_calls：按 index 收集 id/name/arguments(字符串拼接)
+  const toolAcc = new Map();
+  let finishReason = null;
+  let fullText = "";
+  let lastUsage = null;
+
+  for await (const line of readLines(res)) {
+    if (!line.startsWith("data:")) continue;
+    const data = line.slice(5).trim();
+    if (data === "[DONE]") break;
+    let json;
+    try {
+      json = JSON.parse(data);
+    } catch {
+      continue;
+    }
+
+    if (json.usage) {
+      lastUsage = {
+        promptTokens: json.usage.prompt_tokens ?? 0,
+        completionTokens: json.usage.completion_tokens ?? 0,
+        totalTokens: json.usage.total_tokens ?? 0,
+      };
+      yield { type: "usage", usage: lastUsage };
+    }
+
+    const choice = json.choices?.[0];
+    if (!choice) continue;
+    const delta = choice.delta || {};
+
+    if (delta.content) {
+      if (trace?.enabled) fullText += delta.content;
+      yield { type: "text", delta: delta.content };
+    }
+
+    if (delta.tool_calls) {
+      for (const tc of delta.tool_calls) {
+        const idx = tc.index ?? 0;
+        const acc = toolAcc.get(idx) || { id: tc.id, name: "", args: "" };
+        if (tc.id) acc.id = tc.id;
+        if (tc.function?.name) acc.name = tc.function.name;
+        if (tc.function?.arguments) acc.args += tc.function.arguments;
+        toolAcc.set(idx, acc);
+      }
+    }
+
+    if (choice.finish_reason) finishReason = choice.finish_reason;
+  }
+
+  // 流结束后产出完整 tool_call
+  const calls = [];
+  for (const acc of toolAcc.values()) {
+    let parsed = {};
+    try {
+      parsed = acc.args ? JSON.parse(acc.args) : {};
+    } catch {
+      parsed = { __raw: acc.args };
+    }
+    const call = { id: acc.id || `call_${acc.name}`, name: acc.name, arguments: parsed };
+    calls.push(call);
+    yield { type: "tool_call", call };
+  }
+
+  trace?.response({
+    provider: providerName,
+    model,
+    status: res.status,
+    ms: Date.now() - started,
+    text: fullText,
+    toolCalls: calls,
+    usage: lastUsage,
+    finishReason: finishReason || "stop",
+  });
+
+  yield { type: "done", finishReason: finishReason || "stop" };
+}

package/base/llm/sse.js

@@ -0,0 +1,27 @@
+// 原生 SSE / 流式行读取，零依赖。
+
+/** 逐行读取 fetch Response 的流式 body（已去除行尾 \r）。 */
+export async function* readLines(response) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buf.indexOf("\n")) >= 0) {
+        yield buf.slice(0, idx).replace(/\r$/, "");
+        buf = buf.slice(idx + 1);
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // 忽略
+    }
+  }
+  if (buf.trim()) yield buf.replace(/\r$/, "");
+}

package/base/llm/trace.js

@@ -0,0 +1,64 @@
+// LLM 完整请求/响应追踪。默认关闭；开启后将详情写入 JSONL 日志。
+
+import { EVENTS } from "../events.js";
+
+// 需要脱敏的 header（小写比较）
+const SENSITIVE_HEADERS = ["authorization", "x-api-key", "api-key", "cookie", "set-cookie"];
+
+/** 将敏感值掩码为 "前8位…后4位"，过短则整体打码。 */
+export function maskValue(v) {
+  const s = String(v ?? "");
+  if (s.length <= 12) return "***";
+  return `${s.slice(0, 8)}…${s.slice(-4)}`;
+}
+
+export function redactHeaders(headers, redact) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    out[k] = redact && SENSITIVE_HEADERS.includes(k.toLowerCase()) ? maskValue(v) : v;
+  }
+  return out;
+}
+
+/**
+ * 构造追踪器。
+ * @param {object} config 全量配置（读取 config.logging）
+ * @param {import('../logger.js').Logger} logger
+ */
+export function createTracer(config, logger) {
+  const cfg = config.logging || {};
+  const enabled = !!cfg.llmTrace;
+  const redact = cfg.llmTraceRedact !== false; // 默认脱敏
+
+  return {
+    enabled,
+
+    /** 记录请求详情。 */
+    request({ provider, model, url, headers, body }) {
+      if (!enabled) return;
+      logger.info(EVENTS.llm.requestDetail, {
+        provider,
+        model,
+        url,
+        headers: redactHeaders(headers, redact),
+        body,
+      });
+    },
+
+    /** 记录响应详情（聚合后的返回内容 / 错误）。 */
+    response({ provider, model, status, ms, text, toolCalls, usage, finishReason, error }) {
+      if (!enabled) return;
+      logger.info(EVENTS.llm.responseDetail, {
+        provider,
+        model,
+        status,
+        ms,
+        finishReason,
+        text,
+        toolCalls,
+        usage,
+        ...(error ? { error } : {}),
+      });
+    },
+  };
+}

package/base/logger.js

@@ -0,0 +1,57 @@
+// JSONL 结构化日志。每行：{ ts, level, event, detail }。
+
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, nowIso } from "./utils.js";
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+
+export class Logger {
+  /**
+   * @param {object} opts
+   * @param {string} opts.dir   日志目录
+   * @param {string} [opts.level] 最低记录级别
+   */
+  constructor({ dir, level = "info" } = {}) {
+    this.dir = dir;
+    this.threshold = LEVELS[level] ?? LEVELS.info;
+    if (dir) ensureDir(dir);
+  }
+
+  _file() {
+    const day = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    return path.join(this.dir, `vanor-${day}.jsonl`);
+  }
+
+  log(level, event, detail = {}) {
+    if ((LEVELS[level] ?? 0) < this.threshold) return;
+    const line = JSON.stringify({ ts: nowIso(), level, event, detail });
+    if (!this.dir) return;
+    try {
+      fs.appendFileSync(this._file(), line + "\n");
+    } catch {
+      // 日志失败不得影响主流程
+    }
+  }
+
+  debug(event, detail) {
+    this.log("debug", event, detail);
+  }
+  info(event, detail) {
+    this.log("info", event, detail);
+  }
+  warn(event, detail) {
+    this.log("warn", event, detail);
+  }
+  error(event, detail) {
+    this.log("error", event, detail);
+  }
+}
+
+/** 不写盘的空日志器，用于测试。 */
+export class NullLogger extends Logger {
+  constructor() {
+    super({ dir: null, level: "error" });
+  }
+  log() {}
+}