@downcity/agent 1.1.337 → 1.1.399

package/src/utils/logger/FormatShared.ts

@@ -1,258 +0,0 @@
-/**
- * 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 is_json_object(value: JsonValue | null | undefined): value is JsonObject {
-  return isJsonObjectLike(value);
-}
-
-export function get_string_field(
-  objectValue: JsonObject,
-  field: string,
-): string | undefined {
-  const value = objectValue[field];
-  return typeof value === "string" ? value : undefined;
-}
-
-export function get_object_field(
-  objectValue: JsonObject,
-  field: string,
-): JsonObject | undefined {
-  const value = objectValue[field];
-  return isJsonObjectLike(value) ? value : undefined;
-}
-
-export function get_array_field(
-  objectValue: JsonObject,
-  field: string,
-): JsonValue[] | undefined {
-  const value = objectValue[field];
-  return Array.isArray(value) ? value : undefined;
-}
-
-export function safe_json_parse(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 stringify_compact(
-  value: JsonValue | object | undefined,
-  maxChars: number,
-): string {
-  try {
-    return truncate(JSON.stringify(value), maxChars);
-  } catch {
-    return truncate(String(value), maxChars);
-  }
-}
-
-export function to_inline_log_value(value: string, maxChars: number): string {
-  return truncate(String(value || ""), maxChars).replace(/\r?\n/g, "\\n");
-}
-
-export function format_log_field(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 push_labeled_text_block(
-  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(format_log_field(headLabel, normalized || "-"));
-}
-
-export function parse_info_block_text(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 build_info_attrs(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 content_to_text(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 = get_string_field(part, "type");
-        // 关键点（中文）：OpenAI Responses 在 assistant 历史里常见 `output_text`，必须纳入日志提取，否则会显示为 `-`。
-        if (
-          partType === "text" ||
-          partType === "input_text" ||
-          partType === "output_text"
-        ) {
-          return String(get_string_field(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 stringify_compact(content, maxChars);
-  return truncate(String(content ?? ""), maxChars);
-}
-
-export function parse_possible_json_object(
-  value: JsonValue | undefined,
-): JsonObject | undefined {
-  if (isJsonObjectLike(value)) return value;
-  if (typeof value !== "string") return undefined;
-  const parsed = safe_json_parse(value);
-  return isJsonObjectLike(parsed) ? parsed : undefined;
-}
-
-export function extract_function_call_exec_command_cmd(
-  message: JsonObject,
-): string | undefined {
-  const itemType = get_string_field(message, "type");
-  if (itemType !== "function_call") return undefined;
-
-  const name = get_string_field(message, "name");
-  if (name !== "shell_session" && name !== "shell_exec") return undefined;
-
-  const argsObj = parse_possible_json_object(message.arguments);
-  if (!argsObj) return undefined;
-  return get_string_field(argsObj, "cmd");
-}
-
-export function extract_messages(payload: JsonObject): JsonObject[] | null {
-  const messages = get_array_field(payload, "messages");
-  if (Array.isArray(messages)) {
-    return messages.filter((item): item is JsonObject => isJsonObjectLike(item));
-  }
-  const input = get_array_field(payload, "input");
-  if (Array.isArray(input)) {
-    return input.filter((item): item is JsonObject => isJsonObjectLike(item));
-  }
-  return null;
-}
-
-export function extract_system_for_log(
-  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 = get_string_field(payload, "instructions");
-  if (typeof instructions === "string" && instructions.trim()) {
-    return instructions;
-  }
-
-  return system;
-}

package/src/utils/object/DeepMerge.ts

@@ -1,40 +0,0 @@
-/**
- * 通用深合并工具模块。
- *
- * 职责说明（中文）
- * - 提供对象递归合并能力，供配置装配等“层层覆盖”场景复用。
- * - 统一约束数组与标量的覆盖语义，避免不同模块出现不一致行为。
- * - 这里只负责结构合并，不负责字段合法性校验。
- */
-
-import { is_plain_object } from "@/utils/object/ObjectGuards.js";
-
-/**
- * 深合并两个未知值。
- *
- * 关键点（中文）
- * - 只有“对象 + 对象”会递归合并。
- * - 数组始终以 `override` 为准，不做拼接。
- * - 当 `override === undefined` 时保留 `base`，便于做配置层覆盖。
- */
-export function deep_merge(base: unknown, override: unknown): unknown {
-  if (!is_plain_object(base) || !is_plain_object(override)) {
-    return override === undefined ? base : override;
-  }
-
-  const out: Record<string, unknown> = { ...base };
-  for (const [key, overrideValue] of Object.entries(override)) {
-    const baseValue = base[key];
-    if (Array.isArray(overrideValue)) {
-      out[key] = overrideValue;
-      continue;
-    }
-    if (is_plain_object(overrideValue) && is_plain_object(baseValue)) {
-      out[key] = deep_merge(baseValue, overrideValue);
-      continue;
-    }
-    out[key] = overrideValue === undefined ? baseValue : overrideValue;
-  }
-
-  return out;
-}

package/src/utils/object/ObjectGuards.ts

@@ -1,19 +0,0 @@
-/**
- * 对象类型守卫工具模块。
- *
- * 职责说明（中文）
- * - 提供与“普通对象”判断相关的基础守卫函数。
- * - 供配置解析、CLI 输出、深合并等多个领域复用，避免每个模块各写一份。
- * - 这里只处理通用对象判断，不携带任何业务字段语义。
- */
-
-/**
- * 判断一个值是否为普通对象记录。
- *
- * 关键点（中文）
- * - 数组、`null`、函数都不会被视为普通对象。
- * - 当前只要求“可按键遍历的普通对象”，不强制校验原型链来源。
- */
-export function is_plain_object(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/utils/path/AncestorFiles.ts

@@ -1,40 +0,0 @@
-/**
- * 祖先目录文件收集工具模块。
- *
- * 职责说明（中文）
- * - 负责沿着目录树自下而上查找固定文件名，并按“根到叶子”顺序返回。
- * - 供配置继承、工作区约定查找等场景复用，避免把目录遍历逻辑散落到业务模块。
- * - 这里只处理文件路径收集，不解析文件内容。
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-
-/**
- * 收集当前目录及其所有祖先目录中的指定文件。
- *
- * 关键点（中文）
- * - 返回结果按“最上层目录 -> 当前项目目录”排序，适合做逐层覆盖合并。
- * - 若文件名为空，则直接返回空数组，避免调用方拼接出异常路径。
- */
-export function collect_ancestor_named_file_paths(
-  project_root: string,
-  filename: string,
-): string[] {
-  const normalizedFilename = String(filename || "").trim();
-  if (!normalizedFilename) return [];
-
-  const paths: string[] = [];
-  let dir = path.resolve(String(project_root || "").trim() || ".");
-  while (true) {
-    const candidate = path.join(dir, normalizedFilename);
-    if (fs.existsSync(candidate)) {
-      paths.push(candidate);
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-
-  return paths.reverse();
-}

package/src/utils/storage/index.ts

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

package/src/utils/string/EscapeRegExp.ts

@@ -1,19 +0,0 @@
-/**
- * 正则转义工具模块。
- *
- * 职责说明（中文）
- * - 提供把普通字符串安全嵌入 `RegExp` 模式中的基础能力。
- * - 避免各业务模块手写重复实现，并降低正则特殊字符导致的误匹配风险。
- * - 这里只做字面量转义，不负责拼装完整正则表达式。
- */
-
-/**
- * 转义字符串中的正则特殊字符。
- *
- * 关键点（中文）
- * - 返回值适合直接插入 `new RegExp(...)` 的模式字符串。
- * - 不会自动添加边界、分组或 flags。
- */
-export function escape_reg_exp(input: string): string {
-  return String(input || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}

package/src/workspace/LocalFileSystem.ts

@@ -1,209 +0,0 @@
-/**
- * LocalFileSystem：基于 Node.js 的本地 Workspace 文件能力。
- *
- * 职责说明（中文）
- * - 为 File/Search Tool 提供单一 rooted 文件边界。
- * - 复用统一路径策略、原子写入、符号链接校验与有界搜索实现。
- * - 不执行任意 Shell 命令，也不感知 Agent、Session 或 Store。
- */
-
-import type {
-  FileSystem,
-  WorkspaceDirectoryEntry,
-} from "@/types/workspace/FileSystem.js";
-import type {
-  FileToolActionRequest,
-  FileToolActionResult,
-} from "@/types/workspace/FileTool.js";
-import type {
-  SearchToolActionRequest,
-  SearchToolActionResult,
-} from "@/types/workspace/SearchTool.js";
-import { run_file_action } from "@/workspace/file/FileActionRuntime.js";
-import { run_search_action } from "@/workspace/search/SearchActionRuntime.js";
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-import {
-  access,
-  appendFile,
-  mkdir,
-  open,
-  readFile,
-  readdir,
-  rename,
-  rm,
-  stat,
-} from "node:fs/promises";
-import { write_file_atomically } from "@/workspace/file/FileAtomicWriter.js";
-
-const FILE_LOCK_STALE_MS = 120_000;
-const FILE_LOCK_TIMEOUT_MS = FILE_LOCK_STALE_MS * 2;
-const FILE_LOCK_RETRY_MS = 40;
-
-/** 等待指定毫秒数，避免争锁循环持续占用事件循环。 */
-async function wait_for_lock_retry(): Promise<void> {
-  await new Promise<void>((resolve) => {
-    setTimeout(resolve, FILE_LOCK_RETRY_MS);
-  });
-}
-
-/** Node.js 本地文件系统实现。 */
-export class LocalFileSystem implements FileSystem {
-  /** 已解析且不可变的项目根目录。 */
-  readonly root_path: string;
-
-  constructor(root_path: string) {
-    this.root_path = root_path;
-  }
-
-  /** 将相对路径安全解析到当前 Workspace 根目录。 */
-  resolve_path(...segments: string[]): string {
-    const resolved_path = path.resolve(this.root_path, ...segments);
-    const relative_path = path.relative(this.root_path, resolved_path);
-    if (
-      relative_path === ".." ||
-      relative_path.startsWith(`..${path.sep}`) ||
-      path.isAbsolute(relative_path)
-    ) {
-      throw new Error(`Path escapes Workspace: ${segments.join(path.sep)}`);
-    }
-    return resolved_path;
-  }
-
-  /** 判断 Workspace 路径是否存在。 */
-  async path_exists(file_path: string): Promise<boolean> {
-    return await access(this.resolve_path(file_path))
-      .then(() => true)
-      .catch(() => false);
-  }
-
-  /** 读取 Workspace 文件的完整字节内容。 */
-  async read_file(file_path: string): Promise<Buffer> {
-    return await readFile(this.resolve_path(file_path));
-  }
-
-  /** 读取普通文件的字节大小。 */
-  async file_size(file_path: string): Promise<number> {
-    return (await stat(this.resolve_path(file_path))).size;
-  }
-
-  /** 创建目录及缺失的父目录。 */
-  async ensure_directory(directory_path: string): Promise<void> {
-    await mkdir(this.resolve_path(directory_path), { recursive: true });
-  }
-
-  /** 递归删除文件或目录；不存在时保持幂等。 */
-  async remove_path(target_path: string): Promise<void> {
-    await rm(this.resolve_path(target_path), { recursive: true, force: true });
-  }
-
-  /** 使用同一 Workspace 文件系统内的 rename 原子移动路径。 */
-  async move_path(source_path: string, target_path: string): Promise<void> {
-    await rename(
-      this.resolve_path(source_path),
-      this.resolve_path(target_path),
-    );
-  }
-
-  /** 返回目录直接子项的最小稳定结构。 */
-  async read_directory(
-    directory_path: string,
-  ): Promise<WorkspaceDirectoryEntry[]> {
-    const entries = await readdir(this.resolve_path(directory_path), {
-      withFileTypes: true,
-    });
-    return entries.map((entry) => ({
-      name: entry.name,
-      is_directory: entry.isDirectory(),
-      is_file: entry.isFile(),
-    }));
-  }
-
-  /** 使用同目录临时文件与 fsync 原子覆盖 Workspace 文件。 */
-  async write_file_atomically(
-    file_path: string,
-    content: string | Buffer,
-  ): Promise<void> {
-    const resolved_path = this.resolve_path(file_path);
-    await mkdir(path.dirname(resolved_path), { recursive: true });
-    const mode = await stat(resolved_path)
-      .then((value) => value.mode)
-      .catch(() => undefined);
-    await write_file_atomically({
-      file_path: resolved_path,
-      content: Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8"),
-      overwrite: true,
-      ...(typeof mode === "number" ? { mode } : {}),
-    });
-  }
-
-  /** 串行调用方可使用的文件追加能力。 */
-  async append_file(file_path: string, content: string | Buffer): Promise<void> {
-    const resolved_path = this.resolve_path(file_path);
-    await mkdir(path.dirname(resolved_path), { recursive: true });
-    await appendFile(
-      resolved_path,
-      Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8"),
-    );
-  }
-
-  /** 使用跨进程锁文件串行执行 Workspace 文件事务。 */
-  async with_file_lock<T>(
-    lock_path: string,
-    action: () => Promise<T>,
-  ): Promise<T> {
-    const resolved_lock_path = this.resolve_path(lock_path);
-    await mkdir(path.dirname(resolved_lock_path), { recursive: true });
-    const token = `${process.pid}:${Date.now()}:${randomUUID()}`;
-    const started_at = Date.now();
-
-    while (true) {
-      try {
-        const lock_file = await open(resolved_lock_path, "wx");
-        await lock_file.writeFile(token, "utf8");
-        await lock_file.close();
-        break;
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-        try {
-          const lock_stat = await stat(resolved_lock_path);
-          if (Date.now() - lock_stat.mtimeMs > FILE_LOCK_STALE_MS) {
-            await rm(resolved_lock_path, { force: true });
-          }
-        } catch {
-          // 锁可能已由持有者释放，下一轮直接重新竞争。
-        }
-        if (Date.now() - started_at > FILE_LOCK_TIMEOUT_MS) {
-          throw new Error(`Workspace file lock timeout: ${resolved_lock_path}`);
-        }
-        await wait_for_lock_retry();
-      }
-    }
-
-    try {
-      return await action();
-    } finally {
-      try {
-        if ((await readFile(resolved_lock_path, "utf8")).trim() === token) {
-          await rm(resolved_lock_path, { force: true });
-        }
-      } catch {
-        // 锁已被清理时无需再次处理。
-      }
-    }
-  }
-
-  /** 执行一次结构化文件操作。 */
-  async run_file_action(
-    request: FileToolActionRequest,
-  ): Promise<FileToolActionResult> {
-    return await run_file_action({ rootPath: this.root_path }, request);
-  }
-
-  /** 执行一次结构化搜索操作。 */
-  async run_search_action(
-    request: SearchToolActionRequest,
-  ): Promise<SearchToolActionResult> {
-    return await run_search_action({ rootPath: this.root_path }, request);
-  }
-}