@downcity/agent 1.1.8 → 1.1.11

package/src/utils/logger/FormatResponse.ts

@@ -0,0 +1,265 @@
+/**
+ * LLM 响应日志格式化。
+ *
+ * 关键点（中文）
+ * - JSON 响应和 SSE 响应走不同摘要逻辑。
+ * - 日志里保留状态、内容类型、函数调用摘要，方便定位 provider 行为。
+ */
+
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import {
+  formatLogField,
+  getArrayField,
+  getObjectField,
+  getStringField,
+  isJsonObject,
+  safeJsonParse,
+  toInlineLogValue,
+} from "./FormatShared.js";
+
+interface ProviderResponseLike {
+  /**
+   * HTTP 状态码。
+   */
+  status: number;
+  /**
+   * 是否为成功响应。
+   */
+  ok: boolean;
+  /**
+   * 响应头访问器。
+   */
+  headers: {
+    /**
+     * 根据头名获取值。
+     */
+    get(name: string): string | null;
+  };
+  /**
+   * 将响应体读取为文本。
+   */
+  text(): Promise<string>;
+}
+
+function pickOutputTypes(output: JsonValue[] | undefined): string[] {
+  if (!Array.isArray(output)) return [];
+  return output
+    .map((item) => {
+      if (!isJsonObject(item)) return "";
+      return getStringField(item, "type") || "";
+    })
+    .filter((type) => Boolean(type))
+    .slice(0, 16);
+}
+
+function pickFunctionCallNames(output: JsonValue[] | undefined): string[] {
+  if (!Array.isArray(output)) return [];
+  return output
+    .map((item) => {
+      if (!isJsonObject(item)) return "";
+      if (getStringField(item, "type") !== "function_call") return "";
+      return getStringField(item, "name") || "";
+    })
+    .filter((name) => Boolean(name))
+    .slice(0, 8);
+}
+
+function summarizeResponseObjectForLog(
+  responseObject: JsonObject | undefined,
+): JsonObject {
+  if (!responseObject) return {};
+
+  const output = getArrayField(responseObject, "output");
+  const incompleteDetails =
+    getObjectField(responseObject, "incomplete_details") ||
+    getObjectField(responseObject, "incompleteDetails");
+  const finishReason =
+    getStringField(responseObject, "finish_reason") ||
+    getStringField(responseObject, "finishReason");
+
+  return {
+    responseId: getStringField(responseObject, "id") || null,
+    responseObjectType: getStringField(responseObject, "object") || null,
+    responseFinishReason: finishReason || null,
+    responseIncompleteReason:
+      getStringField(incompleteDetails || {}, "reason") || null,
+    responseOutputCount: Array.isArray(output) ? output.length : 0,
+    responseOutputTypes: pickOutputTypes(output),
+    responseFunctionCallNames: pickFunctionCallNames(output),
+  };
+}
+
+function summarizeSseBodyForLog(bodyText: string): JsonObject {
+  const eventTypes: string[] = [];
+  const streamedOutputTypes: string[] = [];
+  const functionCallNames: string[] = [];
+  let lastResponseObject: JsonObject | undefined;
+
+  let currentEvent = "";
+  let currentDataLines: string[] = [];
+
+  const flushEvent = (): void => {
+    const rawData = currentDataLines.join("\n").trim();
+    currentDataLines = [];
+    if (!rawData) {
+      currentEvent = "";
+      return;
+    }
+    if (rawData === "[DONE]") {
+      eventTypes.push(currentEvent || "done");
+      currentEvent = "";
+      return;
+    }
+
+    const parsed = safeJsonParse(rawData);
+    if (parsed && isJsonObject(parsed)) {
+      const explicitType = getStringField(parsed, "type");
+      const eventLabel = currentEvent || explicitType || "message";
+      eventTypes.push(eventLabel);
+
+      const nestedResponse = getObjectField(parsed, "response");
+      if (nestedResponse) {
+        lastResponseObject = nestedResponse;
+      }
+
+      const nestedItem = getObjectField(parsed, "item");
+      const itemType = getStringField(nestedItem || {}, "type");
+      if (itemType && !streamedOutputTypes.includes(itemType)) {
+        streamedOutputTypes.push(itemType);
+      }
+      const functionName = getStringField(nestedItem || {}, "name");
+      if (
+        itemType === "function_call" &&
+        functionName &&
+        !functionCallNames.includes(functionName)
+      ) {
+        functionCallNames.push(functionName);
+      }
+
+      const directOutput = getArrayField(parsed, "output");
+      for (const outputType of pickOutputTypes(directOutput)) {
+        if (!streamedOutputTypes.includes(outputType)) {
+          streamedOutputTypes.push(outputType);
+        }
+      }
+      for (const functionCallName of pickFunctionCallNames(directOutput)) {
+        if (!functionCallNames.includes(functionCallName)) {
+          functionCallNames.push(functionCallName);
+        }
+      }
+    } else {
+      eventTypes.push(currentEvent || "message");
+    }
+    currentEvent = "";
+  };
+
+  for (const rawLine of String(bodyText || "").split(/\r?\n/)) {
+    const line = String(rawLine || "");
+    if (!line.trim()) {
+      flushEvent();
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      currentEvent = line.slice("event:".length).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      currentDataLines.push(line.slice("data:".length).trim());
+    }
+  }
+  flushEvent();
+
+  const responseSummary = summarizeResponseObjectForLog(lastResponseObject);
+  return {
+    responseEventTypes: eventTypes.slice(0, 20),
+    streamedOutputTypes: streamedOutputTypes.slice(0, 16),
+    streamedFunctionCallNames: functionCallNames.slice(0, 8),
+    ...responseSummary,
+  };
+}
+
+export async function parseFetchResponseForLog(
+  response: ProviderResponseLike,
+  opts?: {
+    /**
+     * 原始请求 URL。
+     */
+    url?: string;
+    /**
+     * 原始请求方法。
+     */
+    method?: string;
+  },
+): Promise<{
+  responseText: string;
+  meta: JsonObject;
+}> {
+  const maxBodyPreviewChars = 2000;
+  const contentType = String(response.headers.get("content-type") || "").trim();
+  let bodyText = "";
+
+  try {
+    bodyText = await response.text();
+  } catch (error) {
+    const errorText = String(error || "unknown_error");
+    return {
+      responseText: formatLogField(
+        "agent",
+        toInlineLogValue(
+          `llm.response status=${response.status} ok=${response.ok} contentType=${contentType || "-"} body_read_error=${errorText}`,
+          maxBodyPreviewChars,
+        ),
+      ),
+      meta: {
+        kind: "llm_response",
+        status: response.status,
+        ok: response.ok,
+        ...(contentType ? { contentType } : {}),
+        ...(opts?.url ? { url: opts.url } : {}),
+        ...(opts?.method ? { method: opts.method } : {}),
+        bodyReadError: errorText,
+      },
+    };
+  }
+
+  let responseSummary: JsonObject = {};
+  if (contentType.includes("application/json")) {
+    const parsed = safeJsonParse(bodyText);
+    if (parsed && isJsonObject(parsed)) {
+      const nestedResponse = getObjectField(parsed, "response");
+      responseSummary = summarizeResponseObjectForLog(
+        nestedResponse || parsed,
+      );
+    }
+  } else if (contentType.includes("text/event-stream")) {
+    responseSummary = summarizeSseBodyForLog(bodyText);
+  }
+
+  const preview = toInlineLogValue(bodyText, maxBodyPreviewChars);
+  const responseTextParts = [
+    formatLogField(
+      "agent",
+      toInlineLogValue(
+        `llm.response status=${response.status} ok=${response.ok} contentType=${contentType || "-"}`,
+        maxBodyPreviewChars,
+      ),
+    ),
+  ];
+  if (preview) {
+    responseTextParts.push(formatLogField("response_body", preview));
+  }
+
+  return {
+    responseText: responseTextParts.join("\n\n"),
+    meta: {
+      kind: "llm_response",
+      status: response.status,
+      ok: response.ok,
+      ...(contentType ? { contentType } : {}),
+      ...(opts?.url ? { url: opts.url } : {}),
+      ...(opts?.method ? { method: opts.method } : {}),
+      responseBodyLength: bodyText.length,
+      ...responseSummary,
+    },
+  };
+}

package/src/utils/logger/FormatShared.ts

@@ -0,0 +1,258 @@
+/**
+ * LLM 请求/响应日志格式化的共享基础能力。
+ *
+ * 关键点（中文）
+ * - 这里只放与 provider 无关的 JSON/文本抽取能力。
+ * - 请求侧和响应侧各自的业务规则放到独立模块，避免继续堆成单文件巨石。
+ */
+
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 允许被识别为日志 payload 的解析结果。
+ */
+export type ParsedPayload = JsonObject | JsonValue[];
+
+function isJsonObjectLike(value: JsonValue | null | undefined): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isJsonObject(value: JsonValue | null | undefined): value is JsonObject {
+  return isJsonObjectLike(value);
+}
+
+export function getStringField(
+  objectValue: JsonObject,
+  field: string,
+): string | undefined {
+  const value = objectValue[field];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function getObjectField(
+  objectValue: JsonObject,
+  field: string,
+): JsonObject | undefined {
+  const value = objectValue[field];
+  return isJsonObjectLike(value) ? value : undefined;
+}
+
+export function getArrayField(
+  objectValue: JsonObject,
+  field: string,
+): JsonValue[] | undefined {
+  const value = objectValue[field];
+  return Array.isArray(value) ? value : undefined;
+}
+
+export function safeJsonParse(input: string | undefined): ParsedPayload | null {
+  if (typeof input !== "string") return null;
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return null;
+  try {
+    const parsed = JSON.parse(trimmed) as JsonValue;
+    return isJsonObjectLike(parsed) || Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return text.slice(0, maxChars) + `…(truncated, ${text.length} chars total)`;
+}
+
+export function stringifyCompact(
+  value: JsonValue | object | undefined,
+  maxChars: number,
+): string {
+  try {
+    return truncate(JSON.stringify(value), maxChars);
+  } catch {
+    return truncate(String(value), maxChars);
+  }
+}
+
+export function toInlineLogValue(value: string, maxChars: number): string {
+  return truncate(String(value || ""), maxChars).replace(/\r?\n/g, "\\n");
+}
+
+export function formatLogField(key: string, value: string): string {
+  return `[${key}] ${value}`;
+}
+
+function normalizeAttrKey(input: string): string {
+  return String(input || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, "_");
+}
+
+function normalizeAttrValue(input: string): string {
+  return String(input || "")
+    .trim()
+    .replace(/\s+/g, "_")
+    .replace(/[\]\[]/g, "");
+}
+
+export function pushLabeledTextBlock(
+  out: string[],
+  label: "system" | "user" | "assistant" | "tool" | "tool_result",
+  text: string,
+  maxChars: number,
+  attrs?: string[],
+): void {
+  // 关键点（中文）：日志按“每条消息一段”输出，段内换行转义为字面量 `\n`，保证紧凑且可分段。
+  const normalized = truncate(String(text || "-"), maxChars)
+    .replace(/\r\n/g, "\n")
+    .replace(/\n/g, "\\n");
+  const headLabel =
+    Array.isArray(attrs) && attrs.length > 0 ? `${label} ${attrs.join(" ")}` : label;
+  out.push(formatLogField(headLabel, normalized || "-"));
+}
+
+export function parseInfoBlockText(value: string): {
+  info: Record<string, string>;
+  body: string;
+} | null {
+  const normalized = String(value || "").replace(/\r\n/g, "\n").trim();
+  if (!normalized.startsWith("<info>\n")) return null;
+  const matched = normalized.match(/^<info>\n([\s\S]*?)\n<\/info>(?:\n\n([\s\S]*))?$/);
+  if (!matched) return null;
+
+  const info: Record<string, string> = {};
+  for (const rawLine of String(matched[1] || "").split("\n")) {
+    const line = String(rawLine || "").trim();
+    const index = line.indexOf(":");
+    if (index <= 0) continue;
+    const key = normalizeAttrKey(line.slice(0, index));
+    const fieldValue = normalizeAttrValue(line.slice(index + 1));
+    if (!key || !fieldValue) continue;
+    info[key] = fieldValue;
+  }
+
+  return {
+    info,
+    body: String(matched[2] || "").trim(),
+  };
+}
+
+export function buildInfoAttrs(info: Record<string, string>): string[] {
+  const preferredOrder = [
+    "message_id",
+    "user_id",
+    "username",
+    "role_id",
+    "permissions",
+    "received_at",
+    "user_timezone",
+    "channel",
+    "session_id",
+    "context_id",
+    "chat_key",
+    "chat_id",
+    "chat_type",
+    "thread_id",
+  ];
+
+  const attrs: string[] = [];
+  for (const key of preferredOrder) {
+    const value = String(info[key] || "").trim();
+    if (!value || value === "unknown" || value === "none") continue;
+    attrs.push(`${key}=${value}`);
+  }
+  for (const [key, raw] of Object.entries(info)) {
+    if (preferredOrder.includes(key)) continue;
+    const value = String(raw || "").trim();
+    if (!value) continue;
+    attrs.push(`${key}=${value}`);
+  }
+  return attrs;
+}
+
+export function contentToText(content: JsonValue | undefined, maxChars: number): string {
+  if (typeof content === "string") return truncate(content, maxChars);
+  if (Array.isArray(content)) {
+    const parts = content
+      .map((part) => {
+        if (!isJsonObjectLike(part)) return "";
+        const partType = getStringField(part, "type");
+        // 关键点（中文）：OpenAI Responses 在 assistant 历史里常见 `output_text`，必须纳入日志提取，否则会显示为 `-`。
+        if (
+          partType === "text" ||
+          partType === "input_text" ||
+          partType === "output_text"
+        ) {
+          return String(getStringField(part, "text") ?? "");
+        }
+        // 关键点（中文）：tool 事件由请求侧单独输出为 [tool]/[tool_result]，这里不混入文本。
+        if (
+          partType === "tool-approval-request" ||
+          partType === "tool-call" ||
+          partType === "tool-result" ||
+          partType === "tool-error"
+        ) {
+          return "";
+        }
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+    return truncate(parts, maxChars);
+  }
+  if (isJsonObjectLike(content)) return stringifyCompact(content, maxChars);
+  return truncate(String(content ?? ""), maxChars);
+}
+
+export function parsePossibleJsonObject(
+  value: JsonValue | undefined,
+): JsonObject | undefined {
+  if (isJsonObjectLike(value)) return value;
+  if (typeof value !== "string") return undefined;
+  const parsed = safeJsonParse(value);
+  return isJsonObjectLike(parsed) ? parsed : undefined;
+}
+
+export function extractFunctionCallExecCommandCmd(
+  message: JsonObject,
+): string | undefined {
+  const itemType = getStringField(message, "type");
+  if (itemType !== "function_call") return undefined;
+
+  const name = getStringField(message, "name");
+  if (name !== "shell_start" && name !== "shell_exec") return undefined;
+
+  const argsObj = parsePossibleJsonObject(message.arguments);
+  if (!argsObj) return undefined;
+  return getStringField(argsObj, "cmd");
+}
+
+export function extractMessages(payload: JsonObject): JsonObject[] | null {
+  const messages = getArrayField(payload, "messages");
+  if (Array.isArray(messages)) {
+    return messages.filter((item): item is JsonObject => isJsonObjectLike(item));
+  }
+  const input = getArrayField(payload, "input");
+  if (Array.isArray(input)) {
+    return input.filter((item): item is JsonObject => isJsonObjectLike(item));
+  }
+  return null;
+}
+
+export function extractSystemForLog(
+  payload: JsonObject | undefined,
+): JsonValue | undefined {
+  if (!payload) return undefined;
+
+  const system = payload.system;
+  if (typeof system === "string" && system.trim()) return system;
+
+  // 关键点（中文）：OpenAI Responses 请求把 system prompt 放在 `instructions` 字段。
+  const instructions = getStringField(payload, "instructions");
+  if (typeof instructions === "string" && instructions.trim()) {
+    return instructions;
+  }
+
+  return system;
+}