OpenClaw Gateway 源码解析

openclaw.mjs
  → src/entry.ts          # 进程初始化、环境变量、respawn 守护
    → src/cli/program.ts  # Commander.js CLI 框架
      → `openclaw gateway start`
        → src/gateway/server.impl.ts → startGatewayServer()

1. 加载 & 校验配置（loadConfig → readConfigFileSnapshot）
2. 自动迁移旧配置（migrateLegacyConfig）
3. 自动启用插件（applyPluginAutoEnable）
4. 激活 Secrets 运行时（密钥解析、引用替换）
5. 确保 Gateway Auth（token/password 自动生成）
6. 初始化子系统：
   ├── 子代理注册表（initSubagentRegistry）
   ├── 插件系统（loadGatewayPlugins）
   ├── Channel 管理器（createChannelManager）
   ├── 模型目录（loadGatewayModelCatalog）
   ├── Node 注册表（NodeRegistry）
   ├── Cron 服务（buildGatewayCronService）
   ├── 并发控制（applyGatewayLaneConcurrency）
   ├── Health Monitor
   └── Browser Control Server
7. 创建 HTTP/HTTPS 服务器
8. 挂载 WebSocket 处理器（attachGatewayWsHandlers）
9. 启动 Sidecar 服务：
   ├── Channel 连接（Telegram polling、Discord bot 等）
   ├── Hooks（Gmail watcher 等）
   ├── 浏览器控制服务
   ├── Plugin 服务
   └── Memory 后端
10. 启动 Discovery（Bonjour/mDNS）
11. 启动 Tailscale 暴露（可选）
12. 启动 Config Reloader（文件监听热重载）
13. 运行 BOOT.md（启动后一次性任务）
14. 启动 Heartbeat Runner
15. 启动 Maintenance Timers（清理过期媒体等）

┌─────────────────────────────────────────────────────────────┐
│                      OpenClaw Gateway                        │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
│  │ Telegram  │  │ Discord  │  │  Slack   │  │ WhatsApp/... │ │
│  │ Channel   │  │ Channel  │  │ Channel  │  │  Channels    │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬───────┘ │
│       │              │              │               │         │
│       └──────────────┼──────────────┼───────────────┘         │
│                      ▼                                        │
│              ┌───────────────┐                                │
│              │  Session Router │  ← sessionKey 路由           │
│              └───────┬───────┘                                │
│                      ▼                                        │
│  ┌───────────────────────────────────────────┐               │
│  │              Agent 子系统                   │               │
│  │  ┌─────────┐  ┌──────────┐  ┌──────────┐ │               │
│  │  │Pi Agent │  │ACP Agent │  │Subagent  │ │               │
│  │  │(内嵌)   │  │(外部)    │  │(子代理)  │ │               │
│  │  └────┬────┘  └────┬─────┘  └────┬─────┘ │               │
│  └───────┼────────────┼─────────────┼────────┘               │
│          └────────────┼─────────────┘                         │
│                       ▼                                       │
│              ┌───────────────┐                                │
│              │ LLM Providers  │  Anthropic / OpenAI / ...     │
│              └───────────────┘                                │
│                                                              │
│  ┌────────────────┐  ┌──────┐  ┌────────┐  ┌──────────────┐ │
│  │ Control UI (Web)│  │ Cron │  │ Hooks  │  │ Node Registry│ │
│  └────────────────┘  └──────┘  └────────┘  └──────────────┘ │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  ┌────────────┐  │
│  │ Secrets  │  │ Plugins  │  │  Browser  │  │  Memory    │  │
│  └──────────┘  └──────────┘  └───────────┘  └────────────┘  │
└─────────────────────────────────────────────────────────────┘
         ▲                              ▲
         │ WebSocket (JSON-RPC)         │ HTTP
         ▼                              ▼
  ┌──────────────┐              ┌──────────────┐
  │  CLI Client  │              │ OpenAI API   │
  │  Control UI  │              │ Compat       │
  │  Mobile Node │              │ (chat/compl) │
  └──────────────┘              └──────────────┘

Telegram Bot API (polling/webhook)
  → src/telegram/  (Channel 适配层)
    → 消息标准化（提取 sender、chat_id、text、attachments）
    → 构造 sessionKey: "agent:creator:telegram:5534067368"
    → 调用 agentCommand()  (src/commands/agent.ts)
      → Session 管理：加载/创建 session entry
      → 构建 System Prompt（SOUL.md + AGENTS.md + 工具定义）
      → 调用 Agent 运行时（Pi Agent 内嵌 / ACP 外部代理）
        → LLM 调用（Anthropic/OpenAI/...）
        → 工具调用循环（exec、read、write、web_search...）
        → 生成最终回复
      → 回复路由：通过 Channel 适配层回发到 Telegram

格式：agent:<agentId>:<rest>
示例：
  agent:creator:telegram:5534067368     # Telegram 私聊
  agent:creator:discord:guild:channel   # Discord 频道
  agent:worker:main                     # 主 session
  agent:creator:subagent:<uuid>         # 子代理 session
  agent:creator:cron:<jobId>            # Cron 任务 session
  agent:creator:acp:<sessionId>         # ACP 协议 session

// 简化示意
interface ChannelPlugin {
  id: ChannelId;           // "telegram" | "discord" | ...
  meta: { order: number }; // 排序权重
  status?: { defaultRuntime: ChannelAccountSnapshot };
  gatewayMethods?: string[];  // 额外的 Gateway 方法
  // 启动/停止、消息发送、动作处理...
}

openclaw/plugin-sdk       # 核心
openclaw/plugin-sdk/core  # 基础类型
openclaw/plugin-sdk/compat  # 兼容层
openclaw/plugin-sdk/telegram  # Telegram 专用
openclaw/plugin-sdk/discord   # Discord 专用

// src/process/lanes.ts — 4个车道，枚举值即 Map key
export const enum CommandLane {
  Main = "main",        // 用户主对话
  Cron = "cron",        // 定时任务
  Subagent = "subagent", // 子代理
  Nested = "nested",    // 嵌套调用
}

type LaneState = {
  lane: string;
  queue: QueueEntry[];           // 等待队列
  activeTaskIds: Set<number>;    // 正在执行的任务 ID 集合
  maxConcurrent: number;         // 最大并发数（Main 默认 1）
  draining: boolean;             // 是否正在泵送
  generation: number;            // 代际计数器（restart 时递增）
};

const pump = () => {
  try {
    // 只要活跃任务数 < 最大并发 且 队列非空，就继续取任务
    while (state.activeTaskIds.size < state.maxConcurrent && state.queue.length > 0) {
      const entry = state.queue.shift() as QueueEntry;
      // 检查等待时间，超阈值则触发 onWait 回调 + 诊断日志
      const waitedMs = Date.now() - entry.enqueuedAt;
      if (waitedMs >= entry.warnAfterMs) {
        entry.onWait?.(waitedMs, state.queue.length);
      }
      const taskId = queueState.nextTaskId++;
      const taskGeneration = state.generation;
      state.activeTaskIds.add(taskId);
      // 异步执行，完成后递归调用 pump() 泵送下一个
      void (async () => {
        try {
          const result = await entry.task();
          // generation 校验：如果中途 restart 了，旧任务的完成不影响新 generation
          const completedCurrentGeneration = completeTask(state, taskId, taskGeneration);
          if (completedCurrentGeneration) { pump(); }
          entry.resolve(result);
        } catch (err) {
          // ... 错误处理，同样 pump()
        }
      })();
    }
  } finally { state.draining = false; }
};

// src/gateway/server-lanes.ts
export function applyGatewayLaneConcurrency(cfg) {
  setCommandLaneConcurrency(CommandLane.Cron, cfg.cron?.maxConcurrentRuns ?? 1);
  setCommandLaneConcurrency(CommandLane.Main, resolveAgentMaxConcurrent(cfg));
  setCommandLaneConcurrency(CommandLane.Subagent, resolveSubagentMaxConcurrent(cfg));
}

// config-reload-plan.ts 中的 ReloadRule
type ReloadRule = {
  prefix: string;                    // 配置路径前缀
  kind: "restart" | "hot" | "none";  // restart=需要全量重启 | hot=热重载 | none=忽略
  actions?: ReloadAction[];          // hot 时执行的具体动作
};

// 递归比较两份配置的每个字段路径
export function diffConfigPaths(prev: unknown, next: unknown, prefix = ""): string[] {
  if (prev === next) return [];
  if (isPlainObject(prev) && isPlainObject(next)) {
    // 逐 key 递归，收集所有变更路径
    const keys = new Set([...Object.keys(prev), ...Object.keys(next)]);
    const paths: string[] = [];
    for (const key of keys) {
      const childPaths = diffConfigPaths(prev[key], next[key], `${prefix}.${key}`);
      paths.push(...childPaths);
    }
    return paths;
  }
  // 数组使用 deepStrictEqual 避免顺序相同但引用不同的误报
  if (Array.isArray(prev) && Array.isArray(next)) {
    if (isDeepStrictEqual(prev, next)) return [];
  }
  return [prefix || "<root>"];
}

export function buildGatewayReloadPlan(changedPaths: string[]): GatewayReloadPlan {
  // 对每个变更路径，匹配规则列表
  for (const path of changedPaths) {
    const rule = matchRule(path);
    if (!rule) {
      // 没有匹配的规则？安全起见，要求全量重启
      plan.restartGateway = true;
      continue;
    }
    if (rule.kind === "restart") { plan.restartGateway = true; }
    if (rule.kind === "hot") {
      // 执行对应的热重载动作
      for (const action of rule.actions ?? []) { applyAction(action); }
    }
    // rule.kind === "none" → 忽略
  }
  return plan;
}

type GatewayReloadPlan = {
  restartGateway: boolean;           // 是否需要全量重启
  restartReasons: string[];          // 导致全量重启的路径
  hotReasons: string[];              // 可以热重载的路径
  reloadHooks: boolean;              // 重载 Hook 配置
  restartGmailWatcher: boolean;      // 重启 Gmail 监听
  restartBrowserControl: boolean;    // 重启浏览器控制
  restartCron: boolean;              // 重启 Cron 服务
  restartHeartbeat: boolean;         // 重启心跳
  restartHealthMonitor: boolean;     // 重启健康监控
  restartChannels: Set<ChannelKind>; // 需要重启的通道（精确到单个通道）
  noopPaths: string[];               // 不需要任何操作的变更
};

const watcher = chokidar.watch(opts.watchPath, {
  ignoreInitial: true,
  awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
});
// 变更事件触发 300ms 防抖（可配置）后执行 reload
watcher.on("change", schedule);

mode: "off"     // 关闭自动重载
     | "restart" // 所有变更都触发全量重启
     | "hot"     // 尽量热重载，需要重启的变更被忽略
     | "hybrid"  // 默认：能热重载就热重载，否则全量重启

export async function prepareSecretsRuntimeSnapshot(params) {
  const sourceConfig = structuredClone(params.config);     // 原始配置（含 $ref）
  const resolvedConfig = structuredClone(params.config);   // 将被替换为真实值

  // 1. 收集配置中的所有密钥引用
  collectConfigAssignments({ config: resolvedConfig, context });

  // 2. 收集每个 Agent 的 Auth Profile Store 中的引用
  for (const agentDir of candidateDirs) {
    const store = structuredClone(loadAuthStore(agentDir));
    collectAuthStoreAssignments({ store, context, agentDir });
    authStores.push({ agentDir, store });
  }

  // 3. 批量解析所有引用（一次性调外部密钥源）
  if (context.assignments.length > 0) {
    const refs = context.assignments.map(a => a.ref);
    const resolved = await resolveSecretRefValues(refs, { config, env, cache });
    applyResolvedAssignments({ assignments: context.assignments, resolved });
  }

  return { sourceConfig, config: resolvedConfig, authStores, warnings, webTools };
}

export function activateSecretsRuntimeSnapshot(snapshot) {
  const next = cloneSnapshot(snapshot);  // 深拷贝，防止外部修改
  // 注入到全局运行时配置
  setRuntimeConfigSnapshot(next.config, next.sourceConfig);
  // 注入到所有 Agent 的 Auth Profile
  replaceRuntimeAuthProfileStoreSnapshots(next.authStores);
  activeSnapshot = next;

  // 注册刷新回调——config 变更时可重新解析密钥
  setRuntimeConfigSnapshotRefreshHandler({
    refresh: async ({ sourceConfig }) => {
      const refreshed = await prepareSecretsRuntimeSnapshot({
        config: sourceConfig, env, agentDirs, loadAuthStore,
      });
      activateSecretsRuntimeSnapshot(refreshed);
      return true;
    },
  });
}

// server.impl.ts 中的 activateRuntimeSecrets
try {
  const prepared = await prepareSecretsRuntimeSnapshot({ config });
  activateSecretsRuntimeSnapshot(prepared);
  // 如果之前降级过，现在恢复了
  if (secretsDegraded) {
    emitSecretsStateEvent("SECRETS_RELOADER_RECOVERED", ...);
  }
  secretsDegraded = false;
} catch (err) {
  if (!secretsDegraded) {
    // 第一次降级：告警
    emitSecretsStateEvent("SECRETS_RELOADER_DEGRADED",
      "Secret resolution failed; runtime remains on last-known-good snapshot.");
  }
  secretsDegraded = true;
  if (params.reason === "startup") {
    throw err;  // 启动时不能降级，直接挂掉
  }
  // 运行时降级：继续用旧快照
}

export async function runBootOnce(params) {
  // 1. 读取 BOOT.md
  const result = await loadBootFile(params.workspaceDir);
  if (result.status === "missing" || result.status === "empty") {
    return { status: "skipped", reason: result.status };
  }

  // 2. 快照当前 session mapping（保存主会话的 session 状态）
  const mappingSnapshot = snapshotMainSessionMapping({ cfg, sessionKey });

  // 3. 生成临时 session ID，执行 Agent
  const sessionId = generateBootSessionId();  // "boot-2026-03-13_10-00-00-a1b2c3d4"
  const message = buildBootPrompt(result.content);
  await agentCommand({
    message,
    sessionKey,
    sessionId,
    deliver: false,       // 不投递到通道
    senderIsOwner: true,  // 以 owner 身份执行
  });

  // 4. 恢复 session mapping（Boot 执行不应改变主会话的 session 指针）
  await restoreMainSessionMapping(mappingSnapshot);
}

type HeartbeatAgentState = {
  agentId: string;
  heartbeat?: HeartbeatConfig;
  intervalMs: number;
  lastRunMs?: number;
  nextDueMs: number;          // 下次应执行的时间
};
// state.agents = Map<agentId, HeartbeatAgentState>

const scheduleNext = () => {
  let nextDue = Number.POSITIVE_INFINITY;
  for (const agent of state.agents.values()) {
    if (agent.nextDueMs < nextDue) nextDue = agent.nextDueMs;
  }
  const delay = Math.max(0, nextDue - Date.now());
  state.timer = setTimeout(() => {
    requestHeartbeatNow({ reason: "interval", coalesceMs: 0 });
  }, delay);
  state.timer.unref?.();  // 不阻止进程退出
};

1. areHeartbeatsEnabled()            → 全局开关
2. isHeartbeatEnabledForAgent()      → 该 Agent 是否启用心跳
3. resolveHeartbeatIntervalMs()      → 间隔是否有效
4. isWithinActiveHours()             → 是否在活跃时段（可配安静时段）
5. getQueueSize(CommandLane.Main)    → 主车道是否有任务在跑（有则跳过，不打断用户对话）
6. HEARTBEAT.md 文件内容检查          → 文件为空/纯注释 → 跳过

function resolveHeartbeatReasonFlags(reason?: string) {
  return {
    isExecEventReason: ...,   // 子代理执行完成事件
    isCronEventReason: ...,   // Cron 任务完成事件
    isWakeReason: ...,        // 外部 wake 唤醒或 Hook 触发
  };
}

// 心跳前记录 transcript 文件大小
const transcriptState = await captureTranscriptState({ storePath, sessionKey, agentId });

// 心跳执行...

// 如果结果是 HEARTBEAT_OK，truncate 回原来的大小
if (shouldSkip) {
  await pruneHeartbeatTranscript(transcriptState);
  // 同时恢复 session 的 updatedAt 时间戳
  await restoreHeartbeatUpdatedAt({ storePath, sessionKey, updatedAt: previousUpdatedAt });
}

const isDuplicateMain =
  normalized.text.trim() === prevHeartbeatText.trim() &&   // 文本完全相同
  startedAt - prevHeartbeatAt < 24 * 60 * 60 * 1000;       // 且距离上次发送不到 24 小时
if (isDuplicateMain) {
  // 跳过发送，回滚 transcript
  await pruneHeartbeatTranscript(transcriptState);
  emitHeartbeatEvent({ status: "skipped", reason: "duplicate" });
}

const DEFAULT_CHECK_INTERVAL_MS = 5 * 60_000;       // 每 5 分钟检查一次
const DEFAULT_MONITOR_STARTUP_GRACE_MS = 60_000;     // 启动后 60s 宽限期
const DEFAULT_COOLDOWN_CYCLES = 2;                   // 重启后冷却 2 个周期
const DEFAULT_MAX_RESTARTS_PER_HOUR = 10;            // 每小时最多重启 10 次

// channel-health-policy.ts
export function evaluateChannelHealth(params): ChannelHealthPolicy {
  // 检查通道最后收到事件的时间
  // 如果超过 staleEventThresholdMs（默认 10 分钟），标记为 stale
  // 结合连接状态综合判断是否需要重启
}

// server-broadcast.ts
const EVENT_SCOPE_GUARDS: Record<string, string[]> = {
  "exec.approval.requested": [APPROVALS_SCOPE],  // 执行审批事件
  "exec.approval.resolved": [APPROVALS_SCOPE],
  "device.pair.requested": [PAIRING_SCOPE],       // 设备配对事件
  "device.pair.resolved": [PAIRING_SCOPE],
  "node.pair.requested": [PAIRING_SCOPE],
  "node.pair.resolved": [PAIRING_SCOPE],
};

function hasEventScope(client: GatewayWsClient, event: string): boolean {
  const required = EVENT_SCOPE_GUARDS[event];
  if (!required) return true;  // 没有限制的事件，所有人可见
  const scopes = client.connect.scopes ?? [];
  if (scopes.includes(ADMIN_SCOPE)) return true;  // admin 全权
  return required.some(scope => scopes.includes(scope));
}

用户消息（Telegram/Discord/...）
  │
  ▼
Channel 适配层（标准化消息、提取元数据）
  │
  ▼
agentCommand()                    ← src/commands/agent.ts（核心入口，~1200 行）
  │
  ├─ Session 解析 ← resolveSessionAgentId / loadSessionEntry
  ├─ 模型选择 ← resolveDefaultModelForAgent / Auth Profile 轮换
  ├─ 工具集构建 ← createOpenClawCodingTools()     ← 本章重点
  ├─ Skills 快照 ← buildWorkspaceSkillSnapshot()   ← 本章重点
  ├─ System Prompt 组装 ← buildSystemPrompt()
  │
  ▼
runEmbeddedPiAgent()              ← src/agents/pi-embedded-runner/run.ts
  │
  ├─ 入队 Lane（enqueueCommandInLane）
  ├─ Auth Profile 解析（API Key / OAuth）
  ├─ 重试循环（failover、context overflow compaction、rate limit）
  │
  ▼
Pi Agent SDK（@mariozechner/pi-coding-agent）
  │
  ├─ LLM 调用（Anthropic / OpenAI / Google / ...）
  ├─ 流式响应 ← pi-embedded-subscribe 事件处理
  │     ├─ tool_use 事件 → 工具调度
  │     ├─ text 事件 → 实时广播给 WS 客户端
  │     └─ error 事件 → failover 判断
  │
  ▼
工具调用循环（本章重点）
  │
  ├─ before_tool_call hook → 循环检测 / 插件拦截
  ├─ 工具执行 → 返回结果
  ├─ after_tool_call hook → 插件通知
  └─ 结果注入 → 继续 LLM 推理 → 直到无工具调用

┌─────────────────────────────────────────────────┐
│            createOpenClawCodingTools()            │
│                                                  │
│  ① 基础编码工具（Pi SDK 内置）                     │
│     read / write / edit / exec / process          │
│                                                  │
│  ② OpenClaw 平台工具（自研）                       │
│     browser / canvas / nodes / cron / message     │
│     gateway / tts / web_search / web_fetch        │
│     sessions_* / subagents / memory_* / image     │
│                                                  │
│  ③ 插件工具（Plugin SDK 第三方）                    │
│     由 resolvePluginTools() 从已注册插件中加载       │
│                                                  │
└─────────────────────────────────────────────────┘

const base = (codingTools as AnyAgentTool[]).flatMap((tool) => {
  if (tool.name === readTool.name) {
    if (sandboxRoot) {
      // 沙箱模式：文件读写通过 Docker 容器内的 fs bridge
      return [createSandboxedReadTool({ root: sandboxRoot, bridge: sandboxFsBridge })];
    }
    // 非沙箱模式：创建带 workspace root 感知的 read tool
    const freshReadTool = createReadTool(workspaceRoot);
    return [createOpenClawReadTool(freshReadTool, { modelContextWindowTokens, imageSanitization })];
  }
  if (tool.name === "bash" || tool.name === "exec") {
    return [];  // 不用原生 bash，用 OpenClaw 自己的 exec tool
  }
  if (tool.name === "write") {
    if (sandboxRoot) return [];  // 沙箱模式下用 SandboxedWriteTool
    return [createHostWorkspaceWriteTool(workspaceRoot, { workspaceOnly })];
  }
  // ... edit 同理
});

const tools: AnyAgentTool[] = [
  createBrowserTool({ ... }),        // 浏览器自动化（Playwright）
  createCanvasTool({ ... }),         // Canvas 渲染
  createNodesTool({ ... }),          // 移动设备控制
  createCronTool({ ... }),           // 定时任务管理
  createMessageTool({ ... }),        // 消息发送（跨通道）
  createTtsTool({ ... }),            // 文字转语音
  createGatewayTool({ ... }),        // Gateway 自管理
  createAgentsListTool({ ... }),     // 多 Agent 列表
  createSessionsListTool({ ... }),   // Session 列表
  createSessionsHistoryTool({ ... }),// Session 历史
  createSessionsSendTool({ ... }),   // 跨 Session 发送
  createSessionsSpawnTool({ ... }),  // 子代理 spawn
  createSubagentsTool({ ... }),      // 子代理管理
  createSessionStatusTool({ ... }),  // Session 状态
  createWebSearchTool({ ... }),      // Web 搜索（Brave / Tavily）
  createWebFetchTool({ ... }),       // Web 抓取（Firecrawl / 内置）
  createImageTool({ ... }),          // 图片生成
  createPdfTool({ ... }),            // PDF 解析
];

const pluginTools = resolvePluginTools({
  context: { config, workspaceDir, agentDir, sessionKey, ... },
  existingToolNames: new Set(tools.map(t => t.name)),  // 防止名称冲突
  toolAllowlist: pluginToolAllowlist,
});
return [...tools, ...pluginTools];

工具全集（~30+ 个）
  │
  ├─ ① applyMessageProviderToolPolicy   → 按消息来源过滤（如 voice 场景禁用 tts）
  ├─ ② applyModelProviderToolPolicy     → 按模型提供商过滤（如 xAI 有原生 web_search，禁用 OpenClaw 的）
  ├─ ③ applyOwnerOnlyToolPolicy         → Owner-only 工具检查（非 owner 用户不可用的工具）
  ├─ ④ applyToolPolicyPipeline          → 7 步策略管线（核心过滤）
  │     ├─ tools.profile (coding/minimal/full)
  │     ├─ tools.byProvider.profile
  │     ├─ tools.allow（全局白名单）
  │     ├─ tools.byProvider.allow
  │     ├─ agents.<id>.tools.allow（Agent 级白名单）
  │     ├─ agents.<id>.tools.byProvider.allow
  │     └─ group tools.allow（群聊级白名单）
  ├─ ⑤ sandbox.tools（沙箱工具策略）
  ├─ ⑥ subagentPolicy（子代理工具策略）
  ├─ ⑦ normalizeToolParameters          → JSON Schema 标准化（OpenAI 不接受 union schema）
  ├─ ⑧ wrapToolWithBeforeToolCallHook   → 注入 before_tool_call 钩子
  └─ ⑨ wrapToolWithAbortSignal          → 注入中止信号
  │
  ▼
最终工具列表 → 传给 Pi Agent SDK

// src/agents/tool-policy-pipeline.ts
export function applyToolPolicyPipeline(params) {
  // 区分核心工具和插件工具
  const coreToolNames = new Set(
    params.tools
      .filter(tool => !params.toolMeta(tool))  // 没有 pluginMeta 的是核心工具
      .map(tool => normalizeToolName(tool.name))
  );
  const pluginGroups = buildPluginToolGroups({ tools, toolMeta });

  let filtered = params.tools;
  for (const step of params.steps) {
    if (!step.policy) continue;
    let policy = step.policy;

    // 安全措施：如果 allowlist 只包含插件工具名（不含核心工具），
    // 说明用户可能只想启用某个插件，而不是禁用所有核心工具。
    // 此时剥离 allowlist，避免误杀核心工具。
    if (step.stripPluginOnlyAllowlist) {
      const resolved = stripPluginOnlyAllowlist(policy, pluginGroups, coreToolNames);
      if (resolved.unknownAllowlist.length > 0) {
        warn(`tools: ${step.label} allowlist contains unknown entries...`);
      }
      policy = resolved.policy ?? policy;
    }

    filtered = filterToolsByPolicy(filtered, policy);
  }
  return filtered;
}

// src/agents/pi-tools.before-tool-call.ts
export async function runBeforeToolCallHook(args) {
  // 1. 插件 Hook：让外部插件有机会拦截或修改参数
  const hookRunner = getGlobalHookRunner();
  if (hookRunner) {
    const hookResult = await hookRunner.runHook("before_tool_call", {
      toolName, params, toolCallId, agentId, sessionKey,
    });
    if (hookResult.blocked) {
      return { blocked: true, reason: hookResult.reason };
    }
    if (hookResult.adjustedParams) {
      // 插件可以修改工具参数（存入 Map，工具执行时取出）
      adjustedParamsByToolCallId.set(key, hookResult.adjustedParams);
      return { blocked: false, params: hookResult.adjustedParams };
    }
  }

  // 2. 循环检测：记录工具调用，检查是否陷入循环
  // （详见 8.5 节）
}

// pi-embedded-subscribe.handlers.tools.ts
// 工具完成后：
await hookRunner.runHook("after_tool_call", {
  toolName, args, result, durationMs, toolCallId, agentId, sessionKey,
});
// 同时记录到循环检测器
await recordLoopOutcome({ toolName, toolParams, result, error });

export type LoopDetectorKind =
  | "generic_repeat"           // 通用重复：同一工具+同一参数 hash 连续 N 次
  | "known_poll_no_progress"   // 已知轮询无进展：process poll 连续返回相同结果
  | "ping_pong";               // 乒乓循环：两个工具交替调用（如 read ↔ write）

WARNING_THRESHOLD = 10;                  // 10 次 → 注入警告到 Agent 上下文
CRITICAL_THRESHOLD = 20;                 // 20 次 → 强制返回错误
GLOBAL_CIRCUIT_BREAKER_THRESHOLD = 30;   // 30 次 → 全局熔断，终止整个 turn

// 每次工具调用后，记录 { toolName, paramsHash, resultHash }
// 滑动窗口（默认 30 条）内统计连续重复次数

// generic_repeat：对参数做 SHA-256 hash，连续相同 hash 计数
const paramsHash = createHash("sha256").update(stableStringify(params)).digest("hex").slice(0,16);

// ping_pong：检测 A→B→A→B 交替模式
// 倒序扫描历史，如果最近 N 次在两个工具间交替，判定为乒乓

// known_poll_no_progress：针对 process(action=poll) 等已知轮询模式，
// 比较连续结果的 hash，如果输出不变则计数

// src/agents/skills/workspace.ts → loadSkillEntries()

// 优先级从低到高（同名 skill 后者覆盖前者）：
const extraSkills = ...;           // 1. 额外目录（config skills.load.extraDirs）
const bundledSkills = ...;         // 2. 内置 skills（OpenClaw 自带，如 github、weather）
const managedSkills = ...;         // 3. 托管 skills（~/.openclaw/skills/，npm 安装的）
const personalAgentsSkills = ...;  // 4. 个人 agent skills（~/.agents/skills/）
const projectAgentsSkills = ...;   // 5. 项目 agent skills（workspace/.agents/skills/）
const workspaceSkills = ...;       // 6. 工作区 skills（workspace/skills/，最高优先级）

// 用 Map 按 name 去重，后者覆盖前者
const merged = new Map<string, Skill>();
for (const skill of extraSkills) merged.set(skill.name, skill);
for (const skill of bundledSkills) merged.set(skill.name, skill);
// ... 依次到 workspaceSkills

skills/
├── github/
│   └── SKILL.md       # 包含 frontmatter + 使用指令
├── weather/
│   └── SKILL.md
├── search/
│   ├── SKILL.md
│   └── scripts/
│       └── search.sh  # 可选的辅助脚本

type ParsedSkillFrontmatter = {
  name?: string;
  description?: string;
  requires?: { env?: string[] };  // 需要的环境变量
  primaryEnv?: string;            // 主要依赖的环境变量
  disableModelInvocation?: boolean; // 禁止 Agent 自动调用（仅通过 /command 触发）
  // ...
};

// src/agents/system-prompt.ts → buildSkillsSection()
function buildSkillsSection(params: { skillsPrompt?: string; readToolName: string }) {
  return [
    "## Skills (mandatory)",
    "Before replying: scan <available_skills> <description> entries.",
    `- If exactly one skill clearly applies: read its SKILL.md at <location> with \`${readToolName}\`, then follow it.`,
    "- If multiple could apply: choose the most specific one, then read/follow it.",
    "- If none clearly apply: do not read any SKILL.md.",
    "Constraints: never read more than one skill up front; only read after selecting.",
    trimmed,  // ← 这里是 formatSkillsForPrompt() 的输出（XML 格式的 skill 列表）
  ];
}

<available_skills>
  <skill>
    <name>github</name>
    <description>GitHub operations via `gh` CLI...</description>
    <location>~/.openclaw/skills/github/SKILL.md</location>
  </skill>
  <skill>
    <name>weather</name>
    <description>Get current weather...</description>
    <location>~/.openclaw/skills/weather/SKILL.md</location>
  </skill>
</available_skills>

function applySkillsPromptLimits(params) {
  if (!fits(skillsForPrompt)) {
    // 二分搜索最大前缀
    let lo = 0, hi = skillsForPrompt.length;
    while (lo < hi) {
      const mid = Math.ceil((lo + hi) / 2);
      if (fits(skillsForPrompt.slice(0, mid))) lo = mid;
      else hi = mid - 1;
    }
    skillsForPrompt = skillsForPrompt.slice(0, lo);
  }
}

while (iterations < maxRetryIterations) {
  │
  ├─ 解析 Auth Profile（API Key / OAuth）
  ├─ 调用 runEmbeddedAttempt()（单次 LLM + 工具循环）
  │
  ├─ 成功 → 返回结果
  │
  ├─ 认证失败 → markAuthProfileFailure() → 切换下一个 profile → 重试
  ├─ Rate Limit → 指数退避等待 → 重试
  ├─ Context Overflow → compaction（压缩上下文）→ 重试
  ├─ Billing 错误 → 切换模型/profile → 重试
  ├─ Timeout → 切换 profile → 重试
  │
  └─ 所有 profile 耗尽 → FailoverError
}

// src/agents/pi-embedded-subscribe.handlers.ts
// 事件类型：
// - assistant（文本输出） → 实时广播到 WS 客户端
// - tool_use（工具调用开始） → before_tool_call hook → 执行工具
// - tool_result（工具结果） → after_tool_call hook → 记录循环检测
// - error → failover 判断
// - usage → 累加到 usage accumulator

┌─────────────────────────────────────────────┐
│              System Prompt                   │
│                                              │
│  1. 身份行（"You are a personal assistant"）    │
│                                              │
│  2. ## Tooling（工具可用性说明）                 │
│     - 工具列表及使用约束                        │
│     - TOOLS.md 用户指南                        │
│                                              │
│  3. ## Tool Call Style（工具调用风格）           │
│                                              │
│  4. ## Safety（安全约束）                       │
│                                              │
│  5. ## Skills (mandatory)                    │
│     - <available_skills> XML 列表              │
│                                              │
│  6. ## Memory Recall（记忆检索指令）             │
│                                              │
│  7. ## Self-Update（自更新规则）                 │
│                                              │
│  8. ## Model Aliases（模型别名映射）             │
│                                              │
│  9. ## Workspace（工作目录路径）                 │
│                                              │
│  10. ## Documentation（文档路径）               │
│                                              │
│  11. ## Authorized Senders（授权发送者）         │
│                                              │
│  12. ## Current Date & Time                  │
│                                              │
│  13. ## Workspace Files（注入的项目文件）         │
│      AGENTS.md / SOUL.md / USER.md / ...      │
│                                              │
│  14. ## Silent Replies（NO_REPLY 规则）         │
│                                              │
│  15. ## Heartbeats（心跳响应规则）               │
│                                              │
│  16. ## Runtime（运行环境信息）                  │
│      agent / host / os / model / channel      │
│                                              │
│  17. ## Messaging（消息路由规则）                │
│                                              │
│  18. ## Group Chat Context（群聊上下文，可选）    │
│                                              │
│  19. ## Reactions（表情回复规则，可选）            │
│                                              │
│  20. ## Reply Tags（回复标签规则，可选）           │
└─────────────────────────────────────────────┘

启动时：
  loadGatewayPlugins()
    → loadOpenClawPlugins()（jiti 动态加载 JS/TS 插件文件）
      → 每个插件 export tools: ToolFactory[]
        → 运行时 resolvePluginTools() 实例化

Agent 执行时：
  createOpenClawCodingTools()
    → 核心工具（硬编码注册）
    → OpenClaw 平台工具（硬编码注册）
    → resolvePluginTools()（插件工具动态加载）
    → 9 层策略过滤
    → 最终工具列表

src/
├── entry.ts              # 进程入口
├── index.ts              # 库入口 + CLI
├── gateway/              # 🔴 Gateway 核心（~120 文件）
│   ├── server.impl.ts    #   启动函数 startGatewayServer
│   ├── server-methods.ts #   方法注册与路由
│   ├── server-http.ts    #   HTTP 请求处理
│   ├── server-ws-runtime.ts # WebSocket 运行时
│   ├── server-chat.ts    #   聊天流处理
│   ├── server-channels.ts#   Channel 生命周期管理
│   ├── server-cron.ts    #   Cron 服务集成
│   ├── server-plugins.ts #   插件加载与 dispatch
│   ├── boot.ts           #   BOOT.md 启动任务
│   ├── auth.ts           #   认证核心逻辑
│   ├── call.ts           #   Gateway RPC 调用客户端
│   └── protocol/         #   协议 schema 定义
├── agents/               # 🟠 Agent 子系统（~300 文件）
│   ├── agent-scope.ts    #   Agent 作用域解析
│   ├── cli-runner.ts     #   CLI Agent 运行器
│   ├── bash-tools.ts     #   Bash/Exec 工具实现
│   ├── model-selection.ts#   模型选择逻辑
│   └── pi-embedded*.ts   #   Pi Agent 内嵌运行
├── commands/             # 🟡 命令层
│   ├── agent.ts          #   核心对话命令（最重要）
│   └── agents.ts         #   多 Agent 管理
├── channels/             # 🟢 通道插件
│   └── plugins/          #   统一插件接口
├── config/               # 配置管理
├── cron/                 # 定时任务
├── sessions/             # 会话管理
├── providers/            # LLM 提供商
├── plugins/              # 插件系统
├── acp/                  # ACP 协议
├── infra/                # 基础设施
├── hooks/                # Hook 触发
├── secrets/              # 密钥管理
├── routing/              # 路由层
├── browser/              # 浏览器控制
├── telegram/             # Telegram 适配
├── discord/              # Discord 适配
├── slack/                # Slack 适配
├── whatsapp/             # WhatsApp 适配
├── signal/               # Signal 适配
├── imessage/             # iMessage 适配
├── line/                 # LINE 适配
└── ...

┌─────────────┐          stdio/NDJSON         ┌──────────────────┐
│  IDE 客户端   │ ◄═══════════════════════════► │  openclaw acp     │
│ (Zed/VS Code)│     ACP Protocol              │  (ACP Bridge)     │
└─────────────┘                                └────────┬─────────┘
                                                        │ WebSocket
                                                        │ (Gateway Protocol)
                                                        ▼
                                               ┌──────────────────┐
                                               │  OpenClaw Gateway  │
                                               │                    │
                                               │  ┌──────────────┐ │
                                               │  │ Agent 子系统   │ │
                                               │  │ (Pi Agent)    │ │
                                               │  └──────┬───────┘ │
                                               │         │         │
                                               │         ▼         │
                                               │  ┌──────────────┐ │
                                               │  │ LLM Provider  │ │
                                               │  └──────────────┘ │
                                               └──────────────────┘

另一条路径——ACP 作为子代理运行时：

┌──────────────┐    sessions_spawn     ┌─────────────────────┐
│ OpenClaw Agent│ ──(runtime="acp")──► │ ACP Control Plane    │
│ (主 Agent)    │                       │ (manager.core.ts)    │
└──────────────┘                       └──────────┬──────────┘
                                                   │
                                          ensureSession / runTurn
                                                   │
                                                   ▼
                                       ┌─────────────────────┐
                                       │ ACP Runtime Backend  │
                                       │ (Codex / Claude Code │
                                       │  / 其他 ACP Agent)    │
                                       └─────────────────────┘

export async function serveAcpGateway(opts: AcpServerOptions = {}): Promise<void> {
  // 1. 连接到 Gateway（WebSocket）
  const gateway = new GatewayClient({
    url: connection.url,
    token: creds.token,
    onEvent: (evt) => { agent?.handleGatewayEvent(evt); },
    onHelloOk: () => { agent?.handleGatewayReconnect(); },
  });
  gateway.start();
  await gatewayReady;

  // 2. 在 stdio 上建立 ACP 连接（NDJSON 流）
  const input = Writable.toWeb(process.stdout);
  const output = Readable.toWeb(process.stdin);
  const stream = ndJsonStream(input, output);

  // 3. 创建 ACP Agent 实例，开始处理请求
  new AgentSideConnection((conn) => {
    agent = new AcpGatewayAgent(conn, gateway, opts);
    agent.start();
    return agent;
  }, stream);
}

async prompt(params: PromptRequest): Promise<PromptResponse> {
  // 1. 提取文本（带 2MB 大小限制，防 DoS）
  const userText = extractTextFromPrompt(params.prompt, MAX_PROMPT_BYTES);
  // 2. 提取附件（图片等）
  const attachments = extractAttachmentsFromPrompt(params.prompt);
  // 3. 前缀工作目录（让 Agent 知道 IDE 在哪个目录下工作）
  const message = prefixCwd ? `[Working directory: ${displayCwd}]\n\n${userText}` : userText;
  // 4. 可选的来源追踪（provenance）
  const systemInputProvenance = provenanceMode !== "off"
    ? buildSystemInputProvenance(params.sessionId)  // { kind: "external_user", sourceChannel: "acp" }
    : undefined;

  // 5. 发送到 Gateway
  return new Promise((resolve, reject) => {
    this.pendingPrompts.set(sessionId, { sessionId, sessionKey, resolve, reject, ... });
    this.gateway.request("chat.send", {
      sessionKey, message, attachments, idempotencyKey: runId,
      thinking, deliver, timeoutMs, systemInputProvenance,
    });
  });
}

// 文本增量 → agent_message_chunk
async handleDeltaEvent(sessionId, messageData) {
  const fullText = content?.find(c => c.type === "text")?.text ?? "";
  const newText = fullText.slice(sentSoFar);
  await this.connection.sessionUpdate({
    sessionId,
    update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: newText } },
  });
}

// 工具调用 → tool_call / tool_call_update
async handleAgentEvent(evt) {
  if (phase === "start") {
    await this.connection.sessionUpdate({
      sessionId,
      update: { sessionUpdate: "tool_call", toolCallId, title, status: "in_progress", rawInput, kind, locations },
    });
  }
  if (phase === "result") {
    await this.connection.sessionUpdate({
      sessionId,
      update: { sessionUpdate: "tool_call_update", toolCallId, status: isError ? "failed" : "completed", rawOutput, content },
    });
  }
}

export class AcpSessionManager {
  private readonly actorQueue = new SessionActorQueue();   // 串行化同一 session 的操作
  private readonly runtimeCache = new RuntimeCache();       // 运行时句柄缓存（带 TTL 驱逐）
  private readonly activeTurnBySession = new Map();         // 活跃的 turn 追踪

  // 核心操作
  resolveSession(params)          // 查找 session 状态
  initializeSession(params)       // 创建/恢复 ACP session
  runTurn(params)                 // 执行一轮对话
  cancelTurn(params)              // 取消活跃 turn
  closeSession(params)            // 关闭 session
}

// src/acp/runtime/types.ts
export interface AcpRuntime {
  ensureSession(input: AcpRuntimeEnsureInput): Promise<AcpRuntimeHandle>;
  runTurn(input: AcpRuntimeTurnInput): AsyncIterable<AcpRuntimeEvent>;
  cancel(input: { handle: AcpRuntimeHandle; reason?: string }): Promise<void>;
  close(input: { handle: AcpRuntimeHandle; reason: string }): Promise<void>;
  // 可选
  getCapabilities?(input): Promise<AcpRuntimeCapabilities>;
  getStatus?(input): Promise<AcpRuntimeStatus>;
  setMode?(input): Promise<void>;
  setConfigOption?(input): Promise<void>;
  doctor?(): Promise<AcpRuntimeDoctorReport>;
}

// src/acp/runtime/registry.ts — 全局后端注册表
export function registerAcpRuntimeBackend(backend: AcpRuntimeBackend): void {
  ACP_BACKENDS_BY_ID.set(id, backend);
}

export function requireAcpRuntimeBackend(id?: string): AcpRuntimeBackend {
  // 如果指定了 id，精确匹配；否则返回第一个健康的后端
}

type AcpRuntimeEvent =
  | { type: "text_delta"; text: string; stream?: "output" | "thought" }
  | { type: "status"; text: string; used?: number; size?: number }
  | { type: "tool_call"; text: string; toolCallId?: string; status?: string }
  | { type: "done"; stopReason?: string }
  | { type: "error"; message: string; code?: string; retryable?: boolean };

// src/acp/policy.ts
isAcpEnabledByPolicy(cfg)         // acp.enabled !== false
isAcpDispatchEnabledByPolicy(cfg)  // acp.dispatch.enabled !== false
isAcpAgentAllowedByPolicy(cfg, agentId)  // acp.allowedAgents 白名单

ACP Bridge 模式：
  默认 key：  acp:<uuid>（每次 newSession 生成隔离 key）
  自定义 key：agent:creator:main（复用主会话）
  按 label：  通过 sessionLabel 元数据查找已有 session

ACP Dispatch 模式：
  key 格式：  agent:<agentId>:acp:<sessionId>
  session 元数据存储在 session store 的 `acp` 字段中：
    { backend, runtimeSessionName, agentSessionId, acpxRecordId, ... }

Agent A (sessions_spawn)
  → Gateway: "sessions.spawn" (创建子代理 session)
    → Agent B (子代理在独立 session 中运行)
      → 完成后通过 "subagent.completion" 事件通知
    → Agent A 收到通知，继续处理

Agent A (sessions_send)
  → Gateway: "sessions.send" (向另一个 session 发消息)
    → Agent B (收到消息，执行，返回结果)

方式 1：OpenClaw 作为 A2A Server
  外部 Agent → HTTP → A2A Adapter → Gateway chat.send → Agent 执行

方式 2：OpenClaw 作为 A2A Client
  Agent → A2A Client Tool → HTTP → 外部 A2A Agent
  （类似现在的 ACP Dispatch，但走 A2A 协议）

方式 3：Plugin 实现
  通过 Plugin SDK 注册一个 A2A Gateway Plugin
  暴露 /a2a 端点，翻译 A2A Task ↔ Gateway Session

                     ┌─────────────────┐
                     │    人 / IDE      │
                     └────────┬────────┘
                              │ ACP（stdio/NDJSON）
                              ▼
                     ┌─────────────────┐
                     │   OpenClaw Agent  │
                     │                   │
                     │  ┌─────────────┐ │
                     │  │ 工具调用     │ │ ← MCP（Agent 调工具）
                     │  │ web_search  │ │
                     │  │ exec / read │ │
                     │  └─────────────┘ │
                     │                   │
                     │  ┌─────────────┐ │
                     │  │ 子代理委托   │ │ ← ACP Dispatch（Agent 调 Agent，进程级）
                     │  │ Codex       │ │
                     │  │ Claude Code │ │
                     │  └─────────────┘ │
                     │                   │
                     │  ┌─────────────┐ │
                     │  │ sessions_*  │ │ ← Gateway 内部协议（Agent 间通信）
                     │  │ subagents   │ │
                     │  └─────────────┘ │
                     └────────┬────────┘
                              │
                  （A2A 尚未实现，但架构预留）
                              │
                              ▼
                     ┌─────────────────┐
                     │  外部 Agent       │ ← A2A（Agent 调 Agent，网络级）
                     │ （跨组织/跨框架） │
                     └─────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                     Memory 系统全景                            │
│                                                               │
│  数据源                    索引层                  查询层       │
│  ┌──────────┐        ┌──────────────┐       ┌──────────────┐ │
│  │MEMORY.md │──┐     │              │       │ memory_search│ │
│  │memory/   │  │     │   SQLite DB  │       │   (工具)     │ │
│  │*.md      │  ├────►│              │◄──────│              │ │
│  └──────────┘  │     │ ┌──────────┐ │       └──────────────┘ │
│  ┌──────────┐  │     │ │chunks_vec│ │  向量搜索               │
│  │ Session  │  │     │ │(sqlite-  │ │  ──────────►           │
│  │Transcripts│─┘     │ │ vec)     │ │                        │
│  │ *.jsonl  │        │ ├──────────┤ │  FTS 搜索              │
│  └──────────┘        │ │chunks_fts│ │  ──────────►           │
│                      │ │(FTS5)    │ │                        │
│  ┌──────────┐        │ ├──────────┤ │       ┌──────────────┐ │
│  │ Embedding│        │ │embedding │ │       │  混合排序     │ │
│  │ Provider │        │ │_cache    │ │       │  + 时间衰减   │ │
│  │ (6 种)   │        │ └──────────┘ │       │  + MMR 去重   │ │
│  └──────────┘        └──────────────┘       └──────────────┘ │
└──────────────────────────────────────────────────────────────┘

export type MemorySource = "memory" | "sessions";

// session-files.ts — 从 JSONL 提取可搜索文本
export function extractSessionText(content: unknown): string | null {
  if (typeof content === "string") return normalizeSessionText(content);
  if (Array.isArray(content)) {
    // 只取 type=text 的 block
    return parts.filter(b => b.type === "text").map(b => b.text).join(" ");
  }
}

// sqlite-vec.ts — 动态加载向量搜索扩展
export async function loadSqliteVecExtension(params) {
  // 尝试加载 sqlite-vec native 扩展
  // 支持自定义 extensionPath 或自动发现
  // 失败时记录 loadError，不阻塞启动
  db.exec("PRAGMA busy_timeout = 5000");  // 并发保护
}

// embeddings.ts
export type EmbeddingProviderId =
  | "openai"    // text-embedding-3-small/large
  | "local"     // node-llama-cpp（本地 GGUF 模型）
  | "gemini"    // Gemini embedding-2
  | "voyage"    // Voyage AI
  | "mistral"   // Mistral embed
  | "ollama";   // Ollama 本地服务

export type EmbeddingProviderRequest = EmbeddingProviderId | "auto";

1. 尝试 openai（有 API Key？）
2. 尝试 gemini（有 API Key？）
3. 尝试 voyage（有 API Key？）
4. 尝试 mistral（有 API Key？）
5. 尝试 local（本地模型文件存在？）
6. 全部失败 → provider = null，降级到 FTS-only 模式

// 三种触发方式：
1. 文件监听（chokidar）     → memory/ 目录变更时标记 dirty
2. Session 事件订阅          → transcript 更新时标记 sessionsDirty
3. 定时轮询                  → 配置的 intervalMs 周期同步
4. 搜索时检查（sync.onSearch） → 搜索前如果 dirty 则先同步
5. 会话开始时（sync.onSessionStart）→ warmSession()

对每个文件：
  1. 计算内容 hash
  2. 与 DB 中存储的 hash 比较
  3. 不同 → 删除旧 chunks → 重新切分 → 重新 embedding → 写入 DB
  4. 相同 → 跳过

protected sessionDeltas = new Map<string, {
  lastSize: number;      // 上次同步时的文件大小
  pendingBytes: number;  // 新增的字节数
  pendingMessages: number; // 新增的消息数
}>();

// 同一时间只有一个 sync 在运行
if (this.syncing) {
  // 如果有新的 session 文件变更，入队等待
  return this.enqueueTargetedSessionSync(params.sessionFiles);
}
this.syncing = this.runSyncWithReadonlyRecovery(params).finally(() => {
  this.syncing = null;
});

private isReadonlyDbError(err: unknown): boolean {
  return /attempt to write a readonly database|SQLITE_READONLY/i.test(message);
}
// 检测到 readonly → 关闭 DB → 重新 openDatabase() → 从旧 DB 迁移 embedding cache

用户查询 "上周讨论的网关方案"
          │
          ▼
    ┌─────────────────────────────┐
    │  1. 查询预处理               │
    │     extractKeywords()        │
    │     "上周" "讨论" "网关" "方案" │
    │     （去除停用词）             │
    └─────────┬───────────────────┘
              │
     ┌────────┼────────┐
     ▼                  ▼
┌──────────┐     ┌──────────┐
│ 向量搜索  │     │ FTS 搜索  │
│           │     │           │
│ query →   │     │ query →   │
│ embedding │     │ BM25 rank │
│ → cosine  │     │ → score   │
│ similarity│     │           │
└─────┬────┘     └─────┬────┘
      │                 │
      └────────┬────────┘
               ▼
    ┌─────────────────────────────┐
    │  2. 混合排序                  │
    │  score = vectorWeight × v    │
    │        + textWeight × t      │
    │  （默认 0.7 × vector + 0.3 × text）│
    └─────────┬───────────────────┘
              ▼
    ┌─────────────────────────────┐
    │  3. 时间衰减（可选）          │
    │  score × exp(-λ × ageDays)  │
    │  半衰期默认 30 天             │
    │  MEMORY.md 等常青文件不衰减   │
    └─────────┬───────────────────┘
              ▼
    ┌─────────────────────────────┐
    │  4. MMR 多样性重排（可选）     │
    │  MMR = λ×relevance          │
    │      - (1-λ)×maxSimilarity  │
    │  基于 Jaccard 相似度去冗余    │
    └─────────┬───────────────────┘
              ▼
    ┌─────────────────────────────┐
    │  5. minScore 过滤 + topK 截断│
    └─────────────────────────────┘
              │
              ▼
         搜索结果（path + startLine + endLine + score + snippet）

if (!this.provider) {
  // 提取关键词（中英文停用词过滤）
  const keywords = extractKeywords(cleaned);
  // 对每个关键词独立搜索，合并去重，取最高分
  const resultSets = await Promise.all(
    searchTerms.map(term => this.searchKeyword(term, candidates))
  );
  // 合并、去重、排序
}

// temporal-decay.ts
export function calculateTemporalDecayMultiplier(params) {
  const lambda = Math.LN2 / halfLifeDays;  // 半衰期转衰减系数
  return Math.exp(-lambda * ageInDays);     // 指数衰减
}

// mmr.ts — Carbonell & Goldstein (1998)
MMR_score = λ × relevance - (1-λ) × max_similarity_to_selected

// λ = 0.7（默认）：70% 权重给相关性，30% 给多样性
// 相似度计算：Jaccard 相似度（tokenize 后的集合交集/并集）

// auto-reply/reply/memory-flush.ts
export const DEFAULT_MEMORY_FLUSH_PROMPT = [
  "Pre-compaction memory flush.",
  "Store durable memories to disk.",
  "Target: memory/YYYY-MM-DD.md (append only).",
  "Treat MEMORY.md, SOUL.md, TOOLS.md as read-only.",
  "If nothing to store, reply with NO_REPLY.",
].join(" ");

// 两个阈值（满足任一）：
DEFAULT_MEMORY_FLUSH_SOFT_TOKENS = 4000;         // session token 超过 4000
DEFAULT_MEMORY_FLUSH_FORCE_TRANSCRIPT_BYTES = 2MB; // transcript 文件超过 2MB

// tools/memory-tool.ts
{
  name: "memory_search",
  description: "Mandatory recall step: semantically search MEMORY.md + memory/*.md...",
  parameters: { query: string, maxResults?: number, minScore?: number },
  execute: async (toolCallId, params) => {
    const manager = await getMemorySearchManager({ cfg, agentId });
    const results = await manager.search(query, { maxResults, minScore, sessionKey });
    // 返回 { results: [{ path, snippet, score, startLine, endLine, citation? }], ... }
  }
}

{
  name: "memory_get",
  description: "Safe snippet read from MEMORY.md or memory/*.md...",
  parameters: { path: string, from?: number, lines?: number },
  execute: async (toolCallId, params) => {
    const result = await manager.readFile({ relPath: path, from, lines });
    // 返回指定行范围的原文
  }
}

// search-manager.ts — 两种后端
if (resolved.backend === "qmd") {
  // QMD（外部后端，通过 HTTP 通信）
  const primary = await QmdMemoryManager.create({ cfg, agentId, resolved });
  // 带降级：QMD 失败时自动回退到内置后端
  return new FallbackMemoryManager({ primary, fallbackFactory: () => MemoryIndexManager.get(...) });
} else {
  // 内置后端（SQLite + sqlite-vec）
  return MemoryIndexManager.get({ cfg, agentId });
}

type ResolvedRoute = {
  agentId: string;           // 处理此消息的 Agent
  channel: string;           // 通道标识（telegram/discord/...）
  accountId: string;         // 通道账户标识
  sessionKey: string;        // 完整的 session key（路由键）
  mainSessionKey: string;    // Agent 的主 session key
  matchedBy: string;         // 匹配方式（调试用）
};

消息到达（Telegram / Discord / Slack / WhatsApp / ...）
  │
  ▼
Channel 适配层（标准化 InboundContext）
  │  提取：channel, accountId, peer{kind,id}, guildId, teamId, memberRoleIds
  │
  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    resolveAgentRoute()                           │
│                  src/routing/resolve-route.ts                    │
│                                                                 │
│  输入：                                                          │
│    cfg        ← 完整配置                                         │
│    channel    ← "telegram" / "discord" / ...                    │
│    accountId  ← 通道账户 ID                                      │
│    peer       ← { kind: "direct"|"group"|"channel", id: "..." }│
│    guildId    ← Discord guild ID（可选）                          │
│    teamId     ← Slack team ID（可选）                             │
│    memberRoleIds ← Discord 角色 ID 列表（可选）                    │
│    parentPeer ← 父级 peer（线程继承用）                            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────┐       │
│  │           7 层级联匹配（Tiered Matching）              │       │
│  │                                                      │       │
│  │  Tier 1: binding.peer        ← 精确 peer 匹配        │       │
│  │  Tier 2: binding.peer.parent ← 父 peer 匹配（线程）   │       │
│  │  Tier 3: binding.guild+roles ← Guild + 角色匹配      │       │
│  │  Tier 4: binding.guild       ← Guild 匹配            │       │
│  │  Tier 5: binding.team        ← Team 匹配             │       │
│  │  Tier 6: binding.account     ← 账户匹配              │       │
│  │  Tier 7: binding.channel     ← 通道级匹配            │       │
│  │  Fallback: default agent                             │       │
│  └─────────────────────────────────────────────────────┘       │
│                          │                                      │
│                          ▼                                      │
│  ┌─────────────────────────────────────────────────────┐       │
│  │         buildAgentSessionKey()                        │       │
│  │     根据 agentId + peer + dmScope 生成 sessionKey     │       │
│  └─────────────────────────────────────────────────────┘       │
│                                                                 │
│  输出：ResolvedRoute { agentId, sessionKey, mainSessionKey }    │
└─────────────────────────────────────────────────────────────────┘
  │
  ▼
agentCommand()  ← 使用 sessionKey 查找/创建会话，执行 Agent
  │
  ▼
回复路由  ← 通过 lastRoute 记录的 channel/accountId 回发到原通道

{
  bindings: [
    // 精确 peer 匹配：这个 Telegram 群 → 交给 worker agent
    {
      agentId: "worker",
      match: {
        channel: "telegram",
        peer: { kind: "group", id: "-1001234567890" }
      }
    },
    // 账户级匹配：alerts bot 的所有消息 → 交给 alerts agent
    {
      agentId: "alerts",
      match: { channel: "telegram", accountId: "alerts" }
    },
    // 通道级兜底：所有 Telegram 消息 → 交给 creator agent
    {
      agentId: "creator",
      match: { channel: "telegram", accountId: "*" }
    }
  ]
}

type NormalizedBindingMatch = {
  accountPattern: string;              // 账户匹配模式（"*" = 任意，"" = 默认账户）
  peer: {
    state: "none" | "valid" | "invalid";  // peer 约束状态
    kind?: "direct" | "group" | "channel";
    id?: string;
  };
  guildId: string | null;             // Discord guild ID
  teamId: string | null;              // Slack team ID
  roles: string[] | null;            // Discord 角色列表
};

const tiers = [
  // Tier 1: 精确 peer 匹配（最高优先级）
  {
    matchedBy: "binding.peer",
    enabled: Boolean(peer),              // 有 peer 信息时才启用
    scopePeer: peer,
    candidates: collectPeerIndexedBindings(bindingsIndex, peer),
    predicate: (c) => c.match.peer.state === "valid"
  },

  // Tier 2: 父级 peer 匹配（线程继承）
  {
    matchedBy: "binding.peer.parent",
    enabled: Boolean(parentPeer?.id),    // 有父 peer 时才启用
    scopePeer: parentPeer,
    candidates: collectPeerIndexedBindings(bindingsIndex, parentPeer),
    predicate: (c) => c.match.peer.state === "valid"
  },

  // Tier 3: Guild + 角色匹配（Discord 专属）
  {
    matchedBy: "binding.guild+roles",
    enabled: Boolean(guildId && memberRoleIds.length > 0),
    candidates: bindingsIndex.byGuildWithRoles.get(guildId) ?? [],
    predicate: (c) => hasGuildConstraint(c.match) && hasRolesConstraint(c.match)
  },

  // Tier 4: 纯 Guild 匹配（Discord）
  {
    matchedBy: "binding.guild",
    enabled: Boolean(guildId),
    candidates: bindingsIndex.byGuild.get(guildId) ?? [],
    predicate: (c) => hasGuildConstraint(c.match) && !hasRolesConstraint(c.match)
  },

  // Tier 5: Team 匹配（Slack）
  {
    matchedBy: "binding.team",
    enabled: Boolean(teamId),
    candidates: bindingsIndex.byTeam.get(teamId) ?? [],
    predicate: (c) => hasTeamConstraint(c.match)
  },

  // Tier 6: 账户匹配（具体 accountId）
  {
    matchedBy: "binding.account",
    enabled: true,
    candidates: bindingsIndex.byAccount,
    predicate: (c) => c.match.accountPattern !== "*"
  },

  // Tier 7: 通道级兜底（accountId: "*"）
  {
    matchedBy: "binding.channel",
    enabled: true,
    candidates: bindingsIndex.byChannel,
    predicate: (c) => c.match.accountPattern === "*"
  }
];

// 遍历每一层，第一个匹配的直接返回
for (const tier of tiers) {
  if (!tier.enabled) continue;
  const matched = tier.candidates.find(candidate =>
    tier.predicate(candidate) &&
    matchesBindingScope(candidate.match, { ...baseScope, peer: tier.scopePeer })
  );
  if (matched) return choose(matched.binding.agentId, tier.matchedBy);
}

// 所有层都没匹配 → 使用默认 Agent
return choose(resolveDefaultAgentId(cfg), "default");

4 个 Agent：墨白(creator) / 虾米(worker) / 二狗(aigw) / 铁面(commander)
4 个 Telegram Bot，每个绑定一个 accountId

消息来源                           │ 匹配层级              │ 路由到
───────────────────────────────────┼──────────────────────┼────────
@zhoujun_bot 私聊                  │ Tier 6: account      │ 墨白
@zhoujun88_bot 私聊                │ Tier 6: account      │ 虾米
军师联盟群 @aigw88_bot              │ Tier 1: peer(group)  │ 二狗
某群 @commander_bot                │ Tier 6: account      │ 铁面
未匹配的消息                        │ Fallback: default    │ 墨白

type EvaluatedBindingsIndex = {
  byPeer: Map<string, EvaluatedBinding[]>;           // peer key → bindings
  byGuildWithRoles: Map<string, EvaluatedBinding[]>;  // guildId → bindings
  byGuild: Map<string, EvaluatedBinding[]>;           // guildId → bindings
  byTeam: Map<string, EvaluatedBinding[]>;            // teamId → bindings
  byAccount: EvaluatedBinding[];                      // 账户级 bindings
  byChannel: EvaluatedBinding[];                      // 通道级 bindings
};

function buildEvaluatedBindingsIndex(bindings) {
  for (const binding of bindings) {
    // 有 peer 约束 → 放入 byPeer（O(1) 按 peer key 查找）
    if (binding.match.peer.state === "valid") {
      for (const key of peerLookupKeys(kind, id)) {
        pushToIndexMap(byPeer, key, binding);
      }
      continue;
    }
    // 有 guild + roles → 放入 byGuildWithRoles
    if (binding.match.guildId && binding.match.roles) {
      pushToIndexMap(byGuildWithRoles, binding.match.guildId, binding);
      continue;
    }
    // ... 以此类推
    // 最后：byAccount 或 byChannel
  }
}

Level 1: evaluatedBindingsCacheByCfg（WeakMap<Config, Map>）
  └─ Key: "telegram\tdefault"（channel + accountId）
  └─ Value: 预筛选后的 binding 列表 + 索引

Level 2: resolvedRouteCacheByCfg（WeakMap<Config, Map>）
  └─ Key: "telegram\tdefault\tgroup:123\t-\t-\t-\t-\tmain"
  └─ Value: 完整的 ResolvedRoute 对象

function buildAgentPeerSessionKey(params) {
  const peerKind = params.peerKind ?? "direct";

  if (peerKind === "direct") {
    // DM 消息：根据 dmScope 决定隔离策略
    const dmScope = params.dmScope ?? "main";

    switch (dmScope) {
      case "main":
        // 所有 DM 共享一个主会话
        return `agent:${agentId}:main`;

      case "per-peer":
        // 按发送者隔离（跨通道）
        return `agent:${agentId}:direct:${peerId}`;

      case "per-channel-peer":
        // 按通道+发送者隔离
        return `agent:${agentId}:${channel}:direct:${peerId}`;

      case "per-account-channel-peer":
        // 按账户+通道+发送者隔离（最细粒度）
        return `agent:${agentId}:${channel}:${accountId}:direct:${peerId}`;
    }
  }

  // 群聊/频道消息：始终隔离
  return `agent:${agentId}:${channel}:${peerKind}:${peerId}`;
  // 例：agent:creator:telegram:group:-1001234567890
}

{
  session: {
    dmScope: "per-peer",
    identityLinks: {
      "zhoujun": ["telegram:5534067368", "discord:123456789"]
    }
  }
}

function resolveLinkedPeerId(params) {
  // 把 "telegram:5534067368" 查找到 canonical name "zhoujun"
  for (const [canonical, ids] of Object.entries(identityLinks)) {
    for (const id of ids) {
      if (candidates.has(normalizeToken(id))) return canonical;
    }
  }
  return null;  // 未找到映射，使用原始 peerId
}

// Session Key 分类识别函数

isSubagentSessionKey(key)
  // "agent:creator:subagent:8d298b97-..." → true
  // 子代理会话，由 sessions_spawn 创建

isCronSessionKey(key)
  // "agent:creator:cron:job-123" → true
  // Cron 任务会话

isCronRunSessionKey(key)
  // "agent:creator:cron:job-123:run:abc" → true
  // Cron 单次执行的隔离会话

isAcpSessionKey(key)
  // "agent:creator:acp:session-456" → true
  // ACP 协议会话

getSubagentDepth(key)
  // "agent:creator:subagent:a:subagent:b" → 2
  // 子代理嵌套深度

resolveThreadParentSessionKey(key)
  // "agent:creator:telegram:group:123:thread:456"
  //   → "agent:creator:telegram:group:123"
  // 线程的父级 session key

function resolveThreadSessionKeys(params) {
  const threadId = params.threadId;
  if (!threadId) return { sessionKey: params.baseSessionKey };

  return {
    sessionKey: `${params.baseSessionKey}:thread:${threadId}`,
    parentSessionKey: params.parentSessionKey
  };
}
// Discord: agent:creator:discord:channel:123:thread:456
// Telegram forum: agent:creator:telegram:group:-100123:topic:42

sessionKey: "agent:creator:telegram:5534067368"
  │
  ├─ parseAgentSessionKey()
  │    → { agentId: "creator", rest: "telegram:5534067368" }
  │
  ├─ resolveAgentEntry(cfg, "creator")
  │    → 从 agents.list 中找到 { id: "creator", workspace: "~/.openclaw/workspace-creator", ... }
  │
  ├─ resolveAgentConfig(cfg, "creator")
  │    → { name, workspace, agentDir, model, skills, memorySearch,
  │        humanDelay, heartbeat, identity, groupChat, subagents, sandbox, tools }
  │
  ├─ resolveAgentWorkspaceDir(cfg, "creator")
  │    → "/Users/zhoujun24/.openclaw/workspace-creator"
  │    优先级：agent.workspace > agents.defaults.workspace > 默认路径
  │
  ├─ resolveAgentDir(cfg, "creator")
  │    → "/Users/zhoujun24/.openclaw/agents/creator/agent"
  │    Auth Profile、模型注册等 per-agent 状态存储在这里
  │
  └─ resolveAgentEffectiveModelPrimary(cfg, "creator")
       → "oneapi/Claude Opus 4.6"
       优先级：agent.model > agents.defaults.model > 全局默认

function resolveDefaultAgentId(cfg) {
  const agents = listAgentEntries(cfg);
  if (agents.length === 0) return "main";  // 无 agent 配置 → 默认 "main"

  // 找标记了 default: true 的 agent
  const defaults = agents.filter(agent => agent?.default);
  if (defaults.length > 1) {
    warn("Multiple agents marked default=true; using the first.");
  }

  // 有 default 标记 → 用第一个 default
  // 无 default 标记 → 用列表第一个
  const chosen = (defaults[0] ?? agents[0])?.id;
  return normalizeAgentId(chosen || "main");
}

function normalizeAgentId(value) {
  const trimmed = (value ?? "").trim();
  if (!trimmed) return "main";

  // 合法字符：a-z 0-9 _ -，最长 64 字符
  if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) {
    return trimmed.toLowerCase();
  }

  // 非法字符替换为 -，去除首尾 -
  return trimmed.toLowerCase()
    .replace(/[^a-z0-9_-]+/g, "-")
    .replace(/^-+/, "")
    .replace(/-+$/, "")
    .slice(0, 64) || "main";
}

① Telegram Bot API → 收到消息
     │
② Channel 适配层（src/telegram/）
     │  标准化为 InboundContext：
     │  {
     │    Body: "帮我分析一下这段代码",
     │    ChatType: "direct",
     │    Provider: "telegram",
     │    AccountId: "default",
     │    From: "5534067368",
     │    ChatId: "5534067368",
     │    ...
     │  }
     │
③ resolveAgentRoute()（src/routing/resolve-route.ts）
     │  输入：channel="telegram", accountId="default", peer={kind:"direct", id:"5534067368"}
     │  七层匹配 → Tier 6: binding.account → agentId="creator"
     │  生成 sessionKey → "agent:creator:main"（dmScope=main）
     │  输出：{ agentId: "creator", sessionKey: "agent:creator:main", ... }
     │
④ resolveAgentConfig()（src/agents/agent-scope.ts）
     │  解析 workspace、model、tools、skills 等配置
     │  workspace → /Users/zhoujun24/.openclaw/workspace-creator
     │  model → oneapi/Claude Opus 4.6
     │
⑤ enqueueCommandInLane(CommandLane.Main, ...)
     │  进入 Main Lane 队列等待执行（严格串行）
     │
⑥ agentCommand()（src/commands/agent.ts）
     │  Session 管理：加载/创建 session entry
     │  读取 workspace 文件（SOUL.md, AGENTS.md, USER.md, ...）
     │  构建 System Prompt
     │  构建工具集（createOpenClawCodingTools → 9 层策略过滤）
     │  构建 Skills 快照
     │
⑦ runEmbeddedPiAgent()（src/agents/pi-embedded-runner/run.ts）
     │  Auth Profile 解析 → API Key
     │  LLM 调用（Anthropic Claude Opus 4.6）
     │  工具调用循环（read/write/exec/web_search/...）
     │  生成最终回复
     │
⑧ 回复路由
     │  通过 session 记录的 lastRoute 信息
     │  → Channel 适配层 → Telegram Bot API → 用户收到回复

入站时：
  updateLastRoute(sessionKey, {
    channel: "telegram",
    accountId: "default",
    chatId: "5534067368",
    messageId: "465",
    ...
  })

回复时：
  getLastRoute(sessionKey)
  → { channel: "telegram", accountId: "default", chatId: "5534067368" }
  → 通过 Telegram Channel 适配层发送回复

配置：allowFrom: ["5534067368"]  ← 唯一用户 = pinned owner

用户 A (5534067368) 发消息 → 更新 lastRoute（是 owner）
用户 B (9999999999) 发消息 → 不更新 lastRoute（不是 owner）
Agent 回复 → 发到用户 A 的通道（lastRoute 未被 B 覆盖）

                     热路径性能分析
  ─────────────────────────────────────────────────
  步骤                        │ 耗时    │ 缓存命中
  ─────────────────────────────────────────────────
  Tier 匹配（命中 L2 缓存）   │ ~0.01ms │ 是
  Tier 匹配（命中 L1 缓存）   │ ~0.1ms  │ 部分
  Tier 匹配（冷启动/无缓存）   │ ~1ms    │ 否
  Session Key 生成             │ ~0.01ms │ -
  Agent Config 解析            │ ~0.05ms │ -
  Lane 入队                    │ ~0.01ms │ -
  ─────────────────────────────────────────────────
  总计（热路径）               │ <0.1ms  │
  ─────────────────────────────────────────────────

[routing] resolveAgentRoute: channel=telegram accountId=default
          peer=direct:5534067368 guildId=none teamId=none bindings=3
[routing] binding: agentId=creator accountPattern=default peer=none
          guildId=none teamId=none roles=0
[routing] binding: agentId=worker accountPattern=worker peer=none
          guildId=none teamId=none roles=0
[routing] match: matchedBy=binding.account agentId=creator

Session Router（路由层）           Agent 子系统（执行层）
──────────────────────            ──────────────────────
resolveAgentRoute()               agentCommand()
  → agentId                         → Session 管理
  → sessionKey                      → Prompt 构建
  → mainSessionKey                  → Model 选择
                                    → Tool 集构建
                                    → LLM 调用
                                    → Tool 调用循环
                                    → 回复投递

用户消息（Telegram/Discord/...） → CommandLane.Main    （默认并发 1）
Cron 定时任务                     → CommandLane.Cron    （可配并发）
子代理调用（sessions_spawn）      → CommandLane.Subagent （可配并发）
嵌套调用                          → CommandLane.Nested   （内部使用）

模型选择优先级（高 → 低）：
  1. Session 级别 override（/model 命令临时切换）
  2. Agent 级别配置（agents.list[].model）
  3. 全局默认（agents.defaults.model）
  4. 系统默认（anthropic/claude-sonnet-4-5）

function resolveAgentEffectiveModelPrimary(cfg, agentId) {
  // Agent 自己的 model 配置
  const agentModel = resolveAgentExplicitModelPrimary(cfg, agentId);
  if (agentModel) return agentModel;

  // 全局默认
  return resolveModelPrimary(cfg.agents?.defaults?.model);
}

模型 Failover 链：
  oneapi/Claude Opus 4.6  ← primary
    │ (认证失败 / Rate Limit / Timeout)
    ▼
  anthropic/claude-sonnet-4-5  ← fallback[0]
    │ (仍然失败)
    ▼
  openai/gpt-4o  ← fallback[1]
    │ (所有 fallback 耗尽)
    ▼
  FailoverError（最终失败）

主 Agent（agent:creator:main）
  │
  │  sessions_spawn({ task: "...", label: "start-my-day" })
  │
  ▼
Gateway 处理：
  1. 生成子代理 session key：agent:creator:subagent:<uuid>
  2. 入队 CommandLane.Subagent（不占 Main Lane 并发位）
  3. 创建子代理的执行上下文：
     - 继承父 Agent 的 workspace 和 agentDir
     - 使用 "minimal" prompt 模式（只含 Tooling + Workspace + Runtime）
     - 可以指定不同的 model
  4. 执行完成后，通过 subagent.completion 事件通知父会话
  │
  ▼
子代理（agent:creator:subagent:8d298b97-...）
  独立 session + 独立工具集 + 独立 LLM 调用

function getSubagentDepth(sessionKey) {
  return sessionKey.split(":subagent:").length - 1;
}
// "agent:creator:subagent:a:subagent:b" → depth=2
// 系统限制最大嵌套深度，防止无限递归