@downcity/agent 1.1.1

package/src/shared/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 "@shared/utils/Time.js";
+import type { JsonObject } from "@/shared/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/shared/utils/storage/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 存储读写工具模块。
+ *
+ * 职责说明：
+ * 1. 提供目录创建、JSON 读写等基础能力。
+ * 2. 统一封装 fs-extra 的常用行为，减少业务层重复判断。
+ */
+import fs from "fs-extra";
+import type { JsonValue } from "@/shared/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/src/shared/utils/store/StoreChannelAccountRepository.ts

@@ -0,0 +1,269 @@
+/**
+ * ConsoleStore 渠道账号仓储。
+ *
+ * 关键点（中文）
+ * - 统一管理 `channel_accounts` 表。
+ * - 负责敏感字段解密/加密与 channel account 的语义化组装。
+ */
+
+import type {
+  StoredChannelAccount,
+  UpsertChannelAccountInput,
+} from "@/shared/types/Store.js";
+import { decryptText, decryptTextSync, encryptText } from "./crypto.js";
+import type { ConsoleStoreContext } from "./StoreShared.js";
+import {
+  normalizeChannelAccountChannel,
+  normalizeNonEmptyText,
+  nowIso,
+  optionalTrimmedText,
+} from "./StoreShared.js";
+
+/**
+ * 同步列出 channel accounts。
+ */
+export function listChannelAccountsSync(
+  context: ConsoleStoreContext,
+  channelInput?: string,
+): StoredChannelAccount[] {
+  const maybeChannel = optionalTrimmedText(channelInput);
+  const rows = maybeChannel
+    ? context.sqlite.prepare(
+        `
+        SELECT
+          id, channel, name, identity, owner, creator,
+          bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+          domain, sandbox, created_at, updated_at
+        FROM channel_accounts
+        WHERE channel = ?
+        ORDER BY name ASC, id ASC;
+        `,
+      ).all(maybeChannel)
+    : context.sqlite.prepare(
+        `
+        SELECT
+          id, channel, name, identity, owner, creator,
+          bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+          domain, sandbox, created_at, updated_at
+        FROM channel_accounts
+        ORDER BY channel ASC, name ASC, id ASC;
+        `,
+      ).all();
+  const out: StoredChannelAccount[] = [];
+  for (const row of rows as Array<Record<string, unknown>>) {
+    const entry = buildChannelAccountFromRowSync(row);
+    if (entry) out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * 同步按 ID 获取 channel account。
+ */
+export function getChannelAccountSync(
+  context: ConsoleStoreContext,
+  accountIdInput: string,
+): StoredChannelAccount | null {
+  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  const rows = listChannelAccountsSync(context);
+  return rows.find((item) => item.id === accountId) || null;
+}
+
+/**
+ * 异步列出 channel accounts。
+ */
+export async function listChannelAccounts(
+  context: ConsoleStoreContext,
+  channelInput?: string,
+): Promise<StoredChannelAccount[]> {
+  const maybeChannel = optionalTrimmedText(channelInput);
+  const rows = maybeChannel
+    ? context.sqlite.prepare(
+        `
+        SELECT
+          id, channel, name, identity, owner, creator,
+          bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+          domain, sandbox, created_at, updated_at
+        FROM channel_accounts
+        WHERE channel = ?
+        ORDER BY name ASC, id ASC;
+        `,
+      ).all(maybeChannel)
+    : context.sqlite.prepare(
+        `
+        SELECT
+          id, channel, name, identity, owner, creator,
+          bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+          domain, sandbox, created_at, updated_at
+        FROM channel_accounts
+        ORDER BY channel ASC, name ASC, id ASC;
+        `,
+      ).all();
+  const out: StoredChannelAccount[] = [];
+  for (const row of rows as Array<Record<string, unknown>>) {
+    const entry = await buildChannelAccountFromRow(row);
+    if (entry) out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * 异步按 ID 获取 channel account。
+ */
+export async function getChannelAccount(
+  context: ConsoleStoreContext,
+  accountIdInput: string,
+): Promise<StoredChannelAccount | null> {
+  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  const rows = await listChannelAccounts(context);
+  return rows.find((item) => item.id === accountId) || null;
+}
+
+/**
+ * 新增或更新 channel account。
+ */
+export async function upsertChannelAccount(
+  context: ConsoleStoreContext,
+  input: UpsertChannelAccountInput,
+): Promise<void> {
+  const id = normalizeNonEmptyText(input.id, "channel account id");
+  const channel = normalizeChannelAccountChannel(input.channel);
+  const name = normalizeNonEmptyText(input.name, "channel account name");
+  const existing = await getChannelAccount(context, id);
+  const createdAt = existing?.createdAt || nowIso();
+  const updatedAt = nowIso();
+
+  const nextBotToken =
+    Object.prototype.hasOwnProperty.call(input, "botToken")
+      ? optionalTrimmedText(input.botToken)
+      : existing?.botToken;
+  const nextAppId =
+    Object.prototype.hasOwnProperty.call(input, "appId")
+      ? optionalTrimmedText(input.appId)
+      : existing?.appId;
+  const nextAppSecret =
+    Object.prototype.hasOwnProperty.call(input, "appSecret")
+      ? optionalTrimmedText(input.appSecret)
+      : existing?.appSecret;
+  const botTokenEncrypted = nextBotToken ? await encryptText(nextBotToken) : null;
+  const appIdEncrypted = nextAppId ? await encryptText(nextAppId) : null;
+  const appSecretEncrypted = nextAppSecret ? await encryptText(nextAppSecret) : null;
+
+  context.sqlite.prepare(
+    `
+    INSERT INTO channel_accounts (
+      id, channel, name, identity, owner, creator,
+      bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+      domain, sandbox, created_at, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      channel = excluded.channel,
+      name = excluded.name,
+      identity = excluded.identity,
+      owner = excluded.owner,
+      creator = excluded.creator,
+      bot_token_encrypted = excluded.bot_token_encrypted,
+      app_id_encrypted = excluded.app_id_encrypted,
+      app_secret_encrypted = excluded.app_secret_encrypted,
+      domain = excluded.domain,
+      sandbox = excluded.sandbox,
+      updated_at = excluded.updated_at;
+    `,
+  ).run(
+    id,
+    channel,
+    name,
+    optionalTrimmedText(input.identity) || null,
+    optionalTrimmedText(input.owner) || null,
+    optionalTrimmedText(input.creator) || null,
+    botTokenEncrypted,
+    appIdEncrypted,
+    appSecretEncrypted,
+    optionalTrimmedText(input.domain) || null,
+    input.sandbox === true ? 1 : 0,
+    createdAt,
+    updatedAt,
+  );
+}
+
+/**
+ * 删除 channel account。
+ */
+export function removeChannelAccount(
+  context: ConsoleStoreContext,
+  accountIdInput: string,
+): void {
+  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  context.sqlite.prepare("DELETE FROM channel_accounts WHERE id = ?;").run(accountId);
+}
+
+/**
+ * 同步构造 channel account。
+ */
+function buildChannelAccountFromRowSync(
+  row: Record<string, unknown>,
+): StoredChannelAccount | null {
+  const id = String(row.id || "").trim();
+  if (!id) return null;
+  const channel = normalizeChannelAccountChannel(String(row.channel || ""));
+  const botTokenEncrypted =
+    typeof row.bot_token_encrypted === "string" ? row.bot_token_encrypted : "";
+  const appIdEncrypted =
+    typeof row.app_id_encrypted === "string" ? row.app_id_encrypted : "";
+  const appSecretEncrypted =
+    typeof row.app_secret_encrypted === "string" ? row.app_secret_encrypted : "";
+  const botToken = botTokenEncrypted ? decryptTextSync(botTokenEncrypted) : undefined;
+  const appId = appIdEncrypted ? decryptTextSync(appIdEncrypted) : undefined;
+  const appSecret = appSecretEncrypted ? decryptTextSync(appSecretEncrypted) : undefined;
+  return {
+    id,
+    channel,
+    name: String(row.name || "").trim() || id,
+    identity: optionalTrimmedText(String(row.identity || "")),
+    owner: optionalTrimmedText(String(row.owner || "")),
+    creator: optionalTrimmedText(String(row.creator || "")),
+    botToken: optionalTrimmedText(botToken),
+    appId: optionalTrimmedText(appId),
+    appSecret: optionalTrimmedText(appSecret),
+    domain: optionalTrimmedText(String(row.domain || "")),
+    sandbox: Number(row.sandbox || 0) === 1,
+    createdAt: String(row.created_at || ""),
+    updatedAt: String(row.updated_at || ""),
+  };
+}
+
+/**
+ * 异步构造 channel account。
+ */
+async function buildChannelAccountFromRow(
+  row: Record<string, unknown>,
+): Promise<StoredChannelAccount | null> {
+  const id = String(row.id || "").trim();
+  if (!id) return null;
+  const channel = normalizeChannelAccountChannel(String(row.channel || ""));
+  const botTokenEncrypted =
+    typeof row.bot_token_encrypted === "string" ? row.bot_token_encrypted : "";
+  const appIdEncrypted =
+    typeof row.app_id_encrypted === "string" ? row.app_id_encrypted : "";
+  const appSecretEncrypted =
+    typeof row.app_secret_encrypted === "string" ? row.app_secret_encrypted : "";
+  const botToken = botTokenEncrypted ? await decryptText(botTokenEncrypted) : undefined;
+  const appId = appIdEncrypted ? await decryptText(appIdEncrypted) : undefined;
+  const appSecret = appSecretEncrypted ? await decryptText(appSecretEncrypted) : undefined;
+  return {
+    id,
+    channel,
+    name: String(row.name || "").trim() || id,
+    identity: optionalTrimmedText(String(row.identity || "")),
+    owner: optionalTrimmedText(String(row.owner || "")),
+    creator: optionalTrimmedText(String(row.creator || "")),
+    botToken: optionalTrimmedText(botToken),
+    appId: optionalTrimmedText(appId),
+    appSecret: optionalTrimmedText(appSecret),
+    domain: optionalTrimmedText(String(row.domain || "")),
+    sandbox: Number(row.sandbox || 0) === 1,
+    createdAt: String(row.created_at || ""),
+    updatedAt: String(row.updated_at || ""),
+  };
+}