src/infra/warning-filter.ts

src/infra/warning-filter.ts 文件的功能是实现一个全局的 Node.js 进程警告过滤器。它通过以下方式工作：

1. 定义全局唯一标识符：使用 Symbol.for("openclaw.warning-filter") 创建一个全局共享的 Symbol，用于在 globalThis 上存储过滤器的安装状态，确保过滤器只安装一次。

const warningFilterKey = Symbol.for("openclaw.warning-filter");

关于Symbol.for：

Symbol.for(key) 是 TypeScript 中一个非常实用的方法，它允许你在全局的 Symbol 注册表中查找或创建一个与给定字符串 key 相关联的 Symbol。

ECMAScript 规范定义了一个全局 Symbol 注册表（Global Symbol Registry），它是一个键值对存储结构：

• 键（key） ：一个字符串。
• 值（value） ：一个 Symbol 值。

这个注册表是全局共享的，意味着在同一个 JavaScript 运行环境（如一个浏览器页面、一个 Node.js 进程）中，所有代码（包括不同的模块、不同的 realm，如 iframe 或 worker）都可以通过 Symbol.for(key) 访问到同一个注册表。

1. 核心概念：全局 Symbol 注册表

ECMAScript 规范定义了一个全局 Symbol 注册表（Global Symbol Registry），它是一个键值对存储结构：

• 键（key） ：一个字符串。
• 值（value） ：一个 Symbol 值。

这个注册表是全局共享的，意味着在同一个 JavaScript 运行环境（如一个浏览器页面、一个 Node.js 进程）中，所有代码（包括不同的模块、不同的 realm，如 iframe 或 worker）都可以通过 Symbol.for(key) 访问到同一个注册表。

---

2. Symbol.for(key) 的工作步骤

当你调用 Symbol.for(key) 时，引擎会执行以下逻辑：

1. 查找：在全局注册表中，以给定的字符串 key 为键进行搜索。

2. 如果找到：直接返回该键对应的已存在的 Symbol 值。

3. 如果未找到：

   • 创建一个新的 Symbol 值（这个 Symbol 与 Symbol() 创建的 Symbol 在本质上相同，但多了一个关联的 key）。
   • 将 key 和新创建的 Symbol 的映射关系存入全局注册表。
   • 返回这个新创建的 Symbol。

这个过程中，key 必须是一个字符串（如果传入非字符串，会被强制转换为字符串）。返回的 Symbol 可以被任何地方的代码使用，只要它们使用相同的 key 调用 Symbol.for，就会得到完全相同的 Symbol 值。

---

3. 跨 realm（领域）共享

JavaScript 中的 realm 指的是一个独立的全局环境，比如：

• 浏览器中的主页面与 <iframe> 拥有不同的全局对象。
• Node.js 中的 vm 模块创建的沙箱上下文。
• 同一个页面中的多个 web worker。

Symbol.for 的关键特性：它的注册表是跨 realm 共享的！这意味着：

• 在主页面中通过 Symbol.for("foo") 创建的 Symbol，可以在同一个页面内的 iframe 中通过 Symbol.for("foo") 获取到同一个 Symbol 值（尽管两个 realm 的全局对象不同）。
• 这是因为 JavaScript 引擎维护了一个进程级别（或 agent 级别） 的全局注册表，所有 realm 共享这一份数据。

1. 核心函数 installProcessWarningFilter：

   • 检查全局状态中是否已安装过滤器，若已安装则直接返回。
   • 保存原始的 process.emitWarning 方法。
   • 创建一个包装函数，在每次调用警告时，先通过辅助函数 normalizeWarningArgs 标准化参数，再调用 shouldIgnoreWarning 判断该警告是否应被忽略。
   • 如果应忽略，则直接返回；否则通过 Reflect.apply 调用原始 emitWarning。
   • 将包装函数赋值给 process.emitWarning，实现全局拦截。
   • 在全局状态中标记 installed: true。

export function installProcessWarningFilter(): void {
  const globalState = globalThis as typeof globalThis & {
    [warningFilterKey]?: ProcessWarningInstallState;
  };
  if (globalState[warningFilterKey]?.installed) {
    return;
  }

  const originalEmitWarning = process.emitWarning.bind(process);
  const wrappedEmitWarning: typeof process.emitWarning = ((...args: unknown[]) => {
    if (shouldIgnoreWarning(normalizeWarningArgs(args))) {
      return;
    }
    return Reflect.apply(originalEmitWarning, process, args);
  }) as typeof process.emitWarning;

  process.emitWarning = wrappedEmitWarning;
  globalState[warningFilterKey] = {
    installed: true,
  };
}

该文件旨在净化控制台输出，过滤掉用户不关心的警告（如实验性特性警告、第三方库冗余提示），同时保持与原始 API 的完全兼容，且不会影响应用的其他行为。它通过模块化设计将过滤逻辑与引导代码分离，便于维护和扩展

关于globalThis:

globalThis 是 JavaScript 中的一个标准全局对象，无论在浏览器、Node.js 还是其他 JavaScript 运行环境中，它都指向当前环境的全局对象（浏览器中是 window，Node.js 中是 global，Web Worker 中是 self）

关于const originalEmitWarning = process.emitWarning.bind(process);

在 JavaScript 中，函数的 this 值取决于调用方式。如果直接保存 process.emitWarning 到一个变量，然后调用这个变量，this 可能会丢失

Function.prototype.bind 创建一个新函数，其 this 被永久绑定到指定的对象（这里是 process），并且可以预设部分参数（这里未预设）。