@downcity/agent 1.1.8 → 1.1.10

package/src/utils/logger/FormatShared.ts

@@ -0,0 +1,258 @@
+/**
+ * LLM 请求/响应日志格式化的共享基础能力。
+ *
+ * 关键点（中文）
+ * - 这里只放与 provider 无关的 JSON/文本抽取能力。
+ * - 请求侧和响应侧各自的业务规则放到独立模块，避免继续堆成单文件巨石。
+ */
+
+import type { JsonObject, JsonValue } from "@/utils/types/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;
+}

package/src/utils/logger/Logger.ts

@@ -0,0 +1,372 @@
+/**
+ * 统一日志实现（控制台 + JSONL 落盘）。
+ *
+ * 关键点（中文）
+ * - 支持按项目根目录动态绑定日志目录。
+ * - 结构化字段写入 JSONL，便于后续检索与审计。
+ */
+
+import fs from "fs-extra";
+import path from "path";
+import { getLogsDirPath } from "@/config/Paths.js";
+import { getTimestamp } from "@/utils/Time.js";
+import type { JsonObject } from "@/utils/types/Json.js";
+
+type LogDetails = {
+  [key: string]: JsonObject[keyof JsonObject] | undefined;
+};
+
+const ANSI_RESET = "\x1b[0m";
+const ANSI_BOLD = "\x1b[1m";
+const TASK_BRACKET_COLOR = "\x1b[95m"; // bright magenta
+const ALLOWED_MESSAGE_LABELS = new Set([
+  "main",
+  "system",
+  "user",
+  "assistant",
+  "tool",
+  "tool_result",
+  "agent",
+]);
+const FIXED_BRACKET_COLORS: Record<string, string> = {
+  INFO: "\x1b[36m", // cyan
+  WARN: "\x1b[33m", // yellow
+  ERROR: "\x1b[31m", // red
+  DEBUG: "\x1b[90m", // gray
+  ACTION: "\x1b[96m", // bright cyan
+  SYSTEM: "\x1b[90m", // gray
+  USER: "\x1b[33m", // yellow
+  ASSISTANT: "\x1b[32m", // green
+  TOOL: "\x1b[95m", // bright magenta
+  TOOL_RESULT: "\x1b[34m", // blue
+  AGENT: "\x1b[36m", // cyan
+  MAIN: "\x1b[90m", // gray
+};
+const BRACKET_COLOR_PALETTE = [
+  "\x1b[36m", // cyan
+  "\x1b[32m", // green
+  "\x1b[35m", // magenta
+  "\x1b[34m", // blue
+  "\x1b[33m", // yellow
+  "\x1b[96m", // bright cyan
+];
+
+function normalizeLogDetails(details?: LogDetails): JsonObject | undefined {
+  if (!details) return undefined;
+  const normalized: JsonObject = {};
+  for (const [key, value] of Object.entries(details)) {
+    if (value !== undefined) {
+      normalized[key] = value;
+    }
+  }
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function hashText(input: string): number {
+  let hash = 0;
+  for (let index = 0; index < input.length; index += 1) {
+    hash = (hash * 31 + input.charCodeAt(index)) >>> 0;
+  }
+  return hash;
+}
+
+function colorizeBracketedPrefix(label: string): string {
+  const normalized = String(label || "").trim().toUpperCase();
+  const baseLabel = normalized.split(/[.\s]+/)[0].replace(/[^A-Z0-9_]/g, "");
+  // 关键点（中文）：task 日志标签使用固定高可见色，避免随机色导致辨识度不稳定。
+  if (normalized === "TASK") {
+    return `${TASK_BRACKET_COLOR}[${label}]${ANSI_RESET}`;
+  }
+  const fixedColor = FIXED_BRACKET_COLORS[normalized] || FIXED_BRACKET_COLORS[baseLabel];
+  if (fixedColor) {
+    return `${fixedColor}[${label}]${ANSI_RESET}`;
+  }
+  const color = BRACKET_COLOR_PALETTE[hashText(label) % BRACKET_COLOR_PALETTE.length];
+  return `${color}[${label}]${ANSI_RESET}`;
+}
+
+function colorizeMessageBracketPrefixes(message: string): string {
+  // 关键点（中文）：紧凑单行展示时，给消息中的标签 token 着色，正文保持原样。
+  return String(message || "").replace(/\[([^\]\n]+)\]/g, (full, label: string) => {
+    const normalized = String(label || "").trim();
+    const base = normalized
+      .toUpperCase()
+      .split(/[.\s:]+/)[0]
+      .replace(/[^A-Z0-9_]/g, "");
+    if (!base || !/[A-Z]/.test(base)) return full;
+    return colorizeBracketedPrefix(normalized);
+  });
+}
+
+/**
+ * 压缩日志为“可分段的紧凑展示”。
+ *
+ * 关键点（中文）
+ * - 段内换行转义为字面量 `\n`，避免一条消息占多行。
+ * - 段与段之间保留真实换行，确保不同 message 可清晰区分。
+ */
+function compactMessageForConsole(message: string): string {
+  const normalized = String(message || "").replace(/\r\n/g, "\n");
+  const blocks = normalized
+    .split(/\n{2,}/)
+    .map((block) => String(block || "").replace(/\n/g, "\\n").trim())
+    .filter(Boolean);
+  if (blocks.length === 0) return "";
+  return blocks.join("\n");
+}
+
+function normalizeToAllowedMessageLabels(message: string): string {
+  const normalizedLines: string[] = [];
+  let activeLabel: string | null = null;
+
+  for (const rawLine of String(message || "").split("\n")) {
+    const line = String(rawLine || "");
+    const trimmed = line.trim();
+    if (!trimmed) {
+      normalizedLines.push("");
+      continue;
+    }
+
+    const matched = trimmed.match(/^\[([^\]]+)\]\s*:?\s*(.*)$/);
+    if (matched) {
+      const rawLabel = String(matched[1] || "").trim();
+      const lowerLabel = rawLabel.toLowerCase();
+      const labelToken = lowerLabel.split(/\s+/)[0] || "";
+      const baseLabel = labelToken.split(".")[0];
+      const content = String(matched[2] || "").trim();
+      if (ALLOWED_MESSAGE_LABELS.has(baseLabel)) {
+        activeLabel = baseLabel;
+        const attrsRaw = rawLabel.slice(labelToken.length).trim();
+        const normalizedLabel = attrsRaw ? `${baseLabel} ${attrsRaw}` : baseLabel;
+        normalizedLines.push(`[${normalizedLabel}]${content ? ` ${content}` : ""}`);
+      } else {
+        activeLabel = "main";
+        normalizedLines.push(`[main] ${content || trimmed}`);
+      }
+      continue;
+    }
+
+    if (activeLabel) {
+      // 关键点（中文）：同一消息块的续行不重复打标签。
+      normalizedLines.push(line);
+      continue;
+    }
+    normalizedLines.push(`[main] ${trimmed}`);
+  }
+  if (normalizedLines.length === 0) return "[main] -";
+  return normalizedLines.join("\n");
+}
+
+/**
+ * Unified runtime logger for Downcity.
+ *
+ * Design goals:
+ * - Provide a single logger interface usable by both:
+ *   - system/runtime components (server, scheduler, tool executor, etc.)
+ *   - agent/LLM execution (LLM request/response logging expects `logger.log(...)`)
+ * - Persist logs as JSONL to `.downcity/logs/<YYYY-MM-DD>.jsonl` (one line per entry).
+ * - Keep console output human-friendly, but make disk logs machine-friendly.
+ *
+ * Notes:
+ * - `log(level, ...)` is async because it may write to disk.
+ * - Convenience methods (`info/warn/...`) are sync and fire-and-forget.
+ * - A small in-memory ring buffer is kept for debugging, but persistence is append-only.
+ */
+export interface LogEntry {
+  id: string;
+  timestamp: string;
+  type: "info" | "warn" | "error" | "debug" | "action";
+  message: string;
+  details?: JsonObject;
+  duration?: number;
+  /** Back-compat: kept for older code that expects a `level` field. */
+  level?: string;
+}
+
+/**
+ * Logger：项目级日志器。
+ *
+ * 关键职责（中文）
+ * - 控制台可读输出（开发期）
+ * - JSONL 持久化输出（排障 / 审计）
+ */
+export class Logger {
+  private logs: LogEntry[] = [];
+  private logLevel: string = "info";
+  private writeChain: Promise<void> = Promise.resolve();
+  private readonly maxInMemoryEntries = 2000;
+  private projectRoot: string | null = null;
+
+  constructor(logLevel: string = "info") {
+    this.logLevel = logLevel;
+  }
+
+  /**
+   * 绑定进程级 projectRoot。
+   *
+   * 关键点（中文）
+   * - 我们约束“一个进程只服务一个 projectRoot”。
+   * - Logger 作为单例存在，但落盘目录必须在启动入口初始化后才能确定。
+   * - 未绑定 projectRoot 时，只打印到 console，不写入 `.downcity/logs/*`。
+   */
+  bindProjectRoot(projectRoot: string): void {
+    const root = String(projectRoot || "").trim();
+    this.projectRoot = root || null;
+  }
+
+  /**
+   * Generic async logger used by agent / LLM logging.
+   * Accepts `info|warn|error|debug|action` (case-insensitive).
+   */
+  async log(
+    level: string,
+    message: string,
+    details?: LogDetails,
+  ): Promise<void> {
+    const type = this.normalizeType(level);
+    await this.emit(type, message, details);
+  }
+
+  info(message: string, details?: LogDetails): void {
+    void this.emit("info", message, details);
+  }
+
+  warn(message: string, details?: LogDetails): void {
+    void this.emit("warn", message, details);
+  }
+
+  error(message: string, details?: LogDetails): void {
+    void this.emit("error", message, details);
+  }
+
+  debug(message: string, details?: LogDetails): void {
+    void this.emit("debug", message, details);
+  }
+
+  action(message: string, details?: LogDetails): void {
+    void this.emit("action", message, details);
+  }
+
+  private normalizeType(level: string): LogEntry["type"] {
+    const s = String(level || "")
+      .trim()
+      .toLowerCase();
+    if (s === "warn" || s === "warning") return "warn";
+    if (s === "error" || s === "err") return "error";
+    if (s === "debug" || s === "trace") return "debug";
+    if (s === "action") return "action";
+    return "info";
+  }
+
+  /**
+   * 写入策略（中文）
+   * - 先写内存与控制台，再串行追加到 JSONL，避免并发写乱序。
+   */
+  private async emit(
+    type: LogEntry["type"],
+    message: string,
+    details?: LogDetails,
+  ): Promise<void> {
+    const entry: LogEntry = {
+      id: this.generateId(),
+      timestamp: getTimestamp(),
+      type,
+      message: normalizeToAllowedMessageLabels(message),
+      details: normalizeLogDetails(details),
+      level: type,
+    };
+
+    this.logs.push(entry);
+    if (this.logs.length > this.maxInMemoryEntries) {
+      this.logs.splice(0, this.logs.length - this.maxInMemoryEntries);
+    }
+    this.printLog(entry);
+
+    this.writeChain = this.writeChain
+      .catch(() => {})
+      .then(() => this.saveToFile(entry))
+      .catch(() => {});
+    await this.writeChain;
+  }
+
+  private printLog(entry: LogEntry): void {
+    // 关键点（中文）：控制台输出不展示前置时间戳，减少聊天链路日志噪音。
+    // 时间信息仍保存在 JSONL 落盘字段 `timestamp` 中。
+    const compactBody = compactMessageForConsole(entry.message);
+    const body = colorizeMessageBracketPrefixes(compactBody);
+    const message = body;
+
+    switch (entry.type) {
+      case "error":
+        console.error(message);
+        break;
+      case "warn":
+        console.warn(message);
+        break;
+      case "debug":
+        if (this.logLevel === "debug") {
+          console.log(message);
+        }
+        break;
+      case "action":
+        console.log(message);
+        break;
+      default:
+        console.log(message);
+    }
+  }
+
+  /**
+   * 落盘算法（中文）
+   * - 日志按自然日分片：`.downcity/logs/YYYY-MM-DD.jsonl`。
+   * - 每条日志一行 JSON，便于 grep / 流式消费。
+   */
+  private async saveToFile(entry: LogEntry): Promise<void> {
+    if (!this.projectRoot) return;
+    const logsDir = getLogsDirPath(this.projectRoot);
+    const date = String(entry.timestamp || "").slice(0, 10) || new Date().toISOString().slice(0, 10);
+    const logFile = path.join(logsDir, `${date}.jsonl`);
+
+    const logLine = JSON.stringify(entry) + "\n";
+    await fs.ensureDir(logsDir);
+    await fs.appendFile(logFile, logLine);
+  }
+
+  private generateId(): string {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  }
+
+  async saveAllLogs(): Promise<void> {
+    await this.writeChain.catch(() => {});
+  }
+
+  getLogs(): LogEntry[] {
+    return this.logs;
+  }
+
+  getLogsByType(type: LogEntry["type"]): LogEntry[] {
+    return this.logs.filter((log) => log.type === type);
+  }
+
+  getRecentLogs(count: number = 10): LogEntry[] {
+    return this.logs.slice(-count);
+  }
+
+  clearLogs(): void {
+    this.logs = [];
+  }
+}
+
+export const logger = new Logger();
+
+/**
+ * 获取统一 logger。
+ *
+ * 说明（中文）
+ * - 当前实现是“进程级单例 logger”（落盘路径依赖 runtime root）。
+ * - 参数保留是为了兼容上层调用习惯：有些代码会传入 projectRoot / logLevel。
+ * - 若未来需要“多实例 logger”，可以在这里集中改，不影响调用方。
+ */
+export function getLogger(_projectRoot?: string, _logLevel?: string): Logger {
+  return logger;
+}

package/src/utils/storage/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 存储读写工具模块。
+ *
+ * 职责说明：
+ * 1. 提供目录创建、JSON 读写等基础能力。
+ * 2. 统一封装 fs-extra 的常用行为，减少业务层重复判断。
+ */
+import fs from "fs-extra";
+import type { JsonValue } from "@/utils/types/Json.js";
+
+export async function ensureDir(dir: string): Promise<void> {
+  if (!fs.existsSync(dir)) {
+    await fs.mkdir(dir, { recursive: true });
+  }
+}
+
+export async function saveJson(filePath: string, data: JsonValue | object): Promise<void> {
+  await fs.writeJson(filePath, data, { spaces: 2 });
+}
+
+export async function loadJson<T>(filePath: string): Promise<T | null> {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return fs.readJson(filePath) as Promise<T>;
+}

package/tsconfig.json

@@ -9,8 +9,7 @@
     "paths": {
       "@/*": ["./src/*"],
       "@session/*": ["./src/session/*"],
-      "@services/*": ["./src/service/builtins/*"],
-      "@shared/*": ["./src/shared/*"]
+      "@services/*": ["./src/service/builtins/*"]
     },
     "strict": true,
     "noImplicitAny": false,