@downcity/agent 1.1.287 → 1.1.310

package/src/utils/logger/FormatShared.ts

@@ -17,11 +17,11 @@ function isJsonObjectLike(value: JsonValue | null | undefined): value is JsonObj
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-export function isJsonObject(value: JsonValue | null | undefined): value is JsonObject {
+export function is_json_object(value: JsonValue | null | undefined): value is JsonObject {
   return isJsonObjectLike(value);
 }
 
-export function getStringField(
+export function get_string_field(
   objectValue: JsonObject,
   field: string,
 ): string | undefined {
@@ -29,7 +29,7 @@ export function getStringField(
   return typeof value === "string" ? value : undefined;
 }
 
-export function getObjectField(
+export function get_object_field(
   objectValue: JsonObject,
   field: string,
 ): JsonObject | undefined {
@@ -37,7 +37,7 @@ export function getObjectField(
   return isJsonObjectLike(value) ? value : undefined;
 }
 
-export function getArrayField(
+export function get_array_field(
   objectValue: JsonObject,
   field: string,
 ): JsonValue[] | undefined {
@@ -45,7 +45,7 @@ export function getArrayField(
   return Array.isArray(value) ? value : undefined;
 }
 
-export function safeJsonParse(input: string | undefined): ParsedPayload | null {
+export function safe_json_parse(input: string | undefined): ParsedPayload | null {
   if (typeof input !== "string") return null;
   const trimmed = input.trim();
   if (!trimmed) return null;
@@ -63,7 +63,7 @@ export function truncate(text: string, maxChars: number): string {
   return text.slice(0, maxChars) + `…(truncated, ${text.length} chars total)`;
 }
 
-export function stringifyCompact(
+export function stringify_compact(
   value: JsonValue | object | undefined,
   maxChars: number,
 ): string {
@@ -74,11 +74,11 @@ export function stringifyCompact(
   }
 }
 
-export function toInlineLogValue(value: string, maxChars: number): string {
+export function to_inline_log_value(value: string, maxChars: number): string {
   return truncate(String(value || ""), maxChars).replace(/\r?\n/g, "\\n");
 }
 
-export function formatLogField(key: string, value: string): string {
+export function format_log_field(key: string, value: string): string {
   return `[${key}] ${value}`;
 }
 
@@ -96,7 +96,7 @@ function normalizeAttrValue(input: string): string {
     .replace(/[\]\[]/g, "");
 }
 
-export function pushLabeledTextBlock(
+export function push_labeled_text_block(
   out: string[],
   label: "system" | "user" | "assistant" | "tool" | "tool_result",
   text: string,
@@ -109,10 +109,10 @@ export function pushLabeledTextBlock(
     .replace(/\n/g, "\\n");
   const headLabel =
     Array.isArray(attrs) && attrs.length > 0 ? `${label} ${attrs.join(" ")}` : label;
-  out.push(formatLogField(headLabel, normalized || "-"));
+  out.push(format_log_field(headLabel, normalized || "-"));
 }
 
-export function parseInfoBlockText(value: string): {
+export function parse_info_block_text(value: string): {
   info: Record<string, string>;
   body: string;
 } | null {
@@ -138,7 +138,7 @@ export function parseInfoBlockText(value: string): {
   };
 }
 
-export function buildInfoAttrs(info: Record<string, string>): string[] {
+export function build_info_attrs(info: Record<string, string>): string[] {
   const preferredOrder = [
     "message_id",
     "user_id",
@@ -171,20 +171,20 @@ export function buildInfoAttrs(info: Record<string, string>): string[] {
   return attrs;
 }
 
-export function contentToText(content: JsonValue | undefined, maxChars: number): string {
+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 = getStringField(part, "type");
+        const partType = get_string_field(part, "type");
         // 关键点（中文）：OpenAI Responses 在 assistant 历史里常见 `output_text`，必须纳入日志提取，否则会显示为 `-`。
         if (
           partType === "text" ||
           partType === "input_text" ||
           partType === "output_text"
         ) {
-          return String(getStringField(part, "text") ?? "");
+          return String(get_string_field(part, "text") ?? "");
         }
         // 关键点（中文）：tool 事件由请求侧单独输出为 [tool]/[tool_result]，这里不混入文本。
         if (
@@ -201,46 +201,46 @@ export function contentToText(content: JsonValue | undefined, maxChars: number):
       .join("\n");
     return truncate(parts, maxChars);
   }
-  if (isJsonObjectLike(content)) return stringifyCompact(content, maxChars);
+  if (isJsonObjectLike(content)) return stringify_compact(content, maxChars);
   return truncate(String(content ?? ""), maxChars);
 }
 
-export function parsePossibleJsonObject(
+export function parse_possible_json_object(
   value: JsonValue | undefined,
 ): JsonObject | undefined {
   if (isJsonObjectLike(value)) return value;
   if (typeof value !== "string") return undefined;
-  const parsed = safeJsonParse(value);
+  const parsed = safe_json_parse(value);
   return isJsonObjectLike(parsed) ? parsed : undefined;
 }
 
-export function extractFunctionCallExecCommandCmd(
+export function extract_function_call_exec_command_cmd(
   message: JsonObject,
 ): string | undefined {
-  const itemType = getStringField(message, "type");
+  const itemType = get_string_field(message, "type");
   if (itemType !== "function_call") return undefined;
 
-  const name = getStringField(message, "name");
+  const name = get_string_field(message, "name");
   if (name !== "shell_session" && name !== "shell_exec") return undefined;
 
-  const argsObj = parsePossibleJsonObject(message.arguments);
+  const argsObj = parse_possible_json_object(message.arguments);
   if (!argsObj) return undefined;
-  return getStringField(argsObj, "cmd");
+  return get_string_field(argsObj, "cmd");
 }
 
-export function extractMessages(payload: JsonObject): JsonObject[] | null {
-  const messages = getArrayField(payload, "messages");
+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 = getArrayField(payload, "input");
+  const input = get_array_field(payload, "input");
   if (Array.isArray(input)) {
     return input.filter((item): item is JsonObject => isJsonObjectLike(item));
   }
   return null;
 }
 
-export function extractSystemForLog(
+export function extract_system_for_log(
   payload: JsonObject | undefined,
 ): JsonValue | undefined {
   if (!payload) return undefined;
@@ -249,7 +249,7 @@ export function extractSystemForLog(
   if (typeof system === "string" && system.trim()) return system;
 
   // 关键点（中文）：OpenAI Responses 请求把 system prompt 放在 `instructions` 字段。
-  const instructions = getStringField(payload, "instructions");
+  const instructions = get_string_field(payload, "instructions");
   if (typeof instructions === "string" && instructions.trim()) {
     return instructions;
   }

package/src/utils/logger/Logger.ts

@@ -6,11 +6,11 @@
  * - 结构化字段写入 JSONL，便于后续检索与审计。
  */
 
-import fs from "fs-extra";
-import path from "path";
-import { getLogsDirPath } from "@/config/Paths.js";
-import { getTimestamp } from "@/utils/Time.js";
+import { get_logs_dir_path } from "@/workspace/WorkspacePaths.js";
+import { get_timestamp } from "@/utils/Time.js";
 import type { JsonObject } from "@/types/common/Json.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import { LocalFileSystem } from "@/workspace/LocalFileSystem.js";
 
 type LogDetails = {
   [key: string]: JsonObject[keyof JsonObject] | undefined;
@@ -195,23 +195,28 @@ export class Logger {
   private logLevel: string = "info";
   private writeChain: Promise<void> = Promise.resolve();
   private readonly maxInMemoryEntries = 2000;
-  private projectRoot: string | null = null;
+  private workspace_files: FileSystem | null = null;
 
   constructor(logLevel: string = "info") {
     this.logLevel = logLevel;
   }
 
   /**
-   * 绑定当前 logger 实例的 projectRoot。
+   * 绑定当前 logger 实例的 project_root。
    *
    * 关键点（中文）
    * - 每个 Agent / workspace 持有独立 Logger，绑定只影响当前实例。
    * - 落盘目录必须在实例初始化后明确指定。
-   * - 未绑定 projectRoot 时，只打印到 console，不写入 `.downcity/logs/*`。
+   * - 未绑定 project_root 时，只打印到 console，不写入 `.downcity/logs/*`。
    */
-  bindProjectRoot(projectRoot: string): void {
-    const root = String(projectRoot || "").trim();
-    this.projectRoot = root || null;
+  bind_project_root(project_root: string): void {
+    const root = String(project_root || "").trim();
+    this.workspace_files = root ? new LocalFileSystem(root) : null;
+  }
+
+  /** 绑定现有 Workspace FileSystem，避免创建第二套文件入口。 */
+  bind_workspace(files: FileSystem): void {
+    this.workspace_files = files;
   }
 
   /**
@@ -268,8 +273,8 @@ export class Logger {
     details?: LogDetails,
   ): Promise<void> {
     const entry: LogEntry = {
-      id: this.generateId(),
-      timestamp: getTimestamp(),
+      id: this.generate_id(),
+      timestamp: get_timestamp(),
       type,
       message: normalizeToAllowedMessageLabels(message),
       details: normalizeLogDetails(details),
@@ -322,37 +327,36 @@ export class Logger {
    * - 每条日志一行 JSON，便于 grep / 流式消费。
    */
   private async saveToFile(entry: LogEntry): Promise<void> {
-    if (!this.projectRoot) return;
-    const logsDir = getLogsDirPath(this.projectRoot);
+    if (!this.workspace_files) return;
+    const logsDir = get_logs_dir_path(this.workspace_files.root_path);
     const date = String(entry.timestamp || "").slice(0, 10) || new Date().toISOString().slice(0, 10);
-    const logFile = path.join(logsDir, `${date}.jsonl`);
+    const logFile = this.workspace_files.resolve_path(logsDir, `${date}.jsonl`);
 
     const logLine = JSON.stringify(entry) + "\n";
-    await fs.ensureDir(logsDir);
-    await fs.appendFile(logFile, logLine);
+    await this.workspace_files.append_file(logFile, logLine);
   }
 
-  private generateId(): string {
+  private generate_id(): string {
     return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
   }
 
-  async saveAllLogs(): Promise<void> {
+  async save_all_logs(): Promise<void> {
     await this.writeChain.catch(() => {});
   }
 
-  getLogs(): LogEntry[] {
+  get_logs(): LogEntry[] {
     return this.logs;
   }
 
-  getLogsByType(type: LogEntry["type"]): LogEntry[] {
+  get_logs_by_type(type: LogEntry["type"]): LogEntry[] {
     return this.logs.filter((log) => log.type === type);
   }
 
-  getRecentLogs(count: number = 10): LogEntry[] {
+  get_recent_logs(count: number = 10): LogEntry[] {
     return this.logs.slice(-count);
   }
 
-  clearLogs(): void {
+  clear_logs(): void {
     this.logs = [];
   }
 }
@@ -362,11 +366,11 @@ export class Logger {
  *
  * 说明（中文）
  * - 每次调用都返回独立实例，避免不同 Agent / workspace 互相覆盖落盘目录。
- * - 提供 projectRoot 时立即绑定日志目录；未提供时仅输出到 console。
+ * - 提供 project_root 时立即绑定日志目录；未提供时仅输出到 console。
  */
-export function getLogger(project_root?: string, log_level?: string): Logger {
+export function get_logger(project_root?: string, log_level?: string): Logger {
   const logger = new Logger(log_level);
   const root = String(project_root || "").trim();
-  if (root) logger.bindProjectRoot(root);
+  if (root) logger.bind_project_root(root);
   return logger;
 }

package/src/utils/object/DeepMerge.ts

@@ -7,7 +7,7 @@
  * - 这里只负责结构合并，不负责字段合法性校验。
  */
 
-import { isPlainObject } from "@/utils/object/ObjectGuards.js";
+import { is_plain_object } from "@/utils/object/ObjectGuards.js";
 
 /**
  * 深合并两个未知值。
@@ -17,8 +17,8 @@ import { isPlainObject } from "@/utils/object/ObjectGuards.js";
  * - 数组始终以 `override` 为准，不做拼接。
  * - 当 `override === undefined` 时保留 `base`，便于做配置层覆盖。
  */
-export function deepMerge(base: unknown, override: unknown): unknown {
-  if (!isPlainObject(base) || !isPlainObject(override)) {
+export function deep_merge(base: unknown, override: unknown): unknown {
+  if (!is_plain_object(base) || !is_plain_object(override)) {
     return override === undefined ? base : override;
   }
 
@@ -29,8 +29,8 @@ export function deepMerge(base: unknown, override: unknown): unknown {
       out[key] = overrideValue;
       continue;
     }
-    if (isPlainObject(overrideValue) && isPlainObject(baseValue)) {
-      out[key] = deepMerge(baseValue, overrideValue);
+    if (is_plain_object(overrideValue) && is_plain_object(baseValue)) {
+      out[key] = deep_merge(baseValue, overrideValue);
       continue;
     }
     out[key] = overrideValue === undefined ? baseValue : overrideValue;

package/src/utils/object/ObjectGuards.ts

@@ -14,6 +14,6 @@
  * - 数组、`null`、函数都不会被视为普通对象。
  * - 当前只要求“可按键遍历的普通对象”，不强制校验原型链来源。
  */
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
+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

@@ -17,15 +17,15 @@ import path from "node:path";
  * - 返回结果按“最上层目录 -> 当前项目目录”排序，适合做逐层覆盖合并。
  * - 若文件名为空，则直接返回空数组，避免调用方拼接出异常路径。
  */
-export function collectAncestorNamedFilePaths(
-  projectRoot: string,
+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(projectRoot || "").trim() || ".");
+  let dir = path.resolve(String(project_root || "").trim() || ".");
   while (true) {
     const candidate = path.join(dir, normalizedFilename);
     if (fs.existsSync(candidate)) {

package/src/utils/storage/index.ts

@@ -8,12 +8,12 @@
 import fs from "fs-extra";
 import type { JsonValue } from "@/types/common/Json.js";
 
-export async function ensureDir(dir: string): Promise<void> {
+export async function ensure_dir(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> {
+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

@@ -14,6 +14,6 @@
  * - 返回值适合直接插入 `new RegExp(...)` 的模式字符串。
  * - 不会自动添加边界、分组或 flags。
  */
-export function escapeRegExp(input: string): string {
+export function escape_reg_exp(input: string): string {
   return String(input || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/src/workspace/LocalFileSystem.ts

@@ -0,0 +1,209 @@
+/**
+ * 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);
+  }
+}