逐模块还原 OpenClaw 的内核

// entry.ts:92-94
const entryFile = fileURLToPath(import.meta.url);
const installRoot = resolveEntryInstallRoot(entryFile);

// entry.ts:285
async function runMainOrRootHelp(argv: string[]): Promise<void> {
    const { runCli } = await gatewayEntryStartupTrace.measure("cli", async () => {
        const parsed = parseCliProfileArgs(parsedContainer.argv);
        // ...profile env applied
        await runCli({ argv: parsed.argv });
    });
}

import { getAcpSessionManager } from "../acp/control-plane/manager.js";
import {
  cleanupFailedAcpSpawn,
  type AcpSpawnRuntimeCloseHandle,
} from "../acp/control-plane/spawn.js";
import { isAcpEnabledByPolicy, resolveAcpAgentPolicyError } from "../acp/policy.js";
import { readAcpSessionMeta } from "../acp/runtime/session-meta.js";
import { resolveAcpSessionCwd, resolveAcpThreadSessionDetailLines }
  from "@openclaw/acp-core/runtime/session-identifiers";
import type { AcpRuntimeSessionMode } from "@openclaw/acp-core/runtime/types";

DEFAULT_SUBAGENT_MAX_CHILDREN_PER_AGENT  // 每个 agent 最大子会话数
DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH         // 最大 spawn 深度（防止嵌套失控）

export type AgentHarness = AgentHarnessRunCapability &
  AgentHarnessSideQuestionCapability &
  AgentHarnessClassificationCapability &
  AgentHarnessCompactionCapability &
  AgentHarnessSessionLifecycleCapability;

// 核心能力：
export type AgentHarnessRunCapability = {
  run(params: AgentHarnessAttemptParams): Promise<AgentHarnessAttemptResult>;
};

export type AgentHarnessSideQuestionCapability = {
  sideQuestion(params: AgentHarnessSideQuestionParams): Promise<AgentHarnessSideQuestionResult>;
};

export type AgentHarnessClassificationCapability = {
  classify?(input: unknown): Promise<AgentHarnessResultClassification>;
};

export type AgentHarnessCompactionCapability = {
  compact(params: AgentHarnessCompactParams): Promise<AgentHarnessCompactResult>;
};

export type AgentHarnessSessionLifecycleCapability = {
  reset?(params: AgentHarnessResetParams): Promise<void>;
};

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";

// Session-scoped MCP session 结构
type BundleMcpSession = {
  serverName: string;
  client: Client;
  transport: Transport;
  transportType: "stdio" | "sse" | "streamable-http";
  requestTimeoutMs: number;
  supportsParallelToolCalls: boolean;
  detachStderr?: () => void;
};

// 全局 session manager 符号（保证每个进程只有一个 manager 实例）
const SESSION_MCP_RUNTIME_MANAGER_KEY = Symbol.for("openclaw.sessionMcpRuntimeManager");

export function createBundleMcpJsonSchemaValidator(): jsonSchemaValidator;
export function resolveSessionMcpConfigSummary(params: {...}): {...};
export function resolveSessionMcpConfigFingerprint(params: {...}): string;
function resolveSessionMcpRuntimeIdleTtlMs(cfg?: OpenClawConfig): number;
  // 默认值：10 分钟 idle TTL

export type BuildPluginApiParams = {
  id: string;
  name: string;
  version?: string;
  source: string;
  registrationMode: OpenClawPluginApi["registrationMode"];
  config: OpenClawConfig;
  runtime: PluginRuntime;
  logger: PluginLogger;
  handlers?: Partial<Pick<OpenClawPluginApi,
    | "registerTool"          // 注册工具
    | "registerHook"          // 注册生命周期钩子
    | "registerHttpRoute"     // 注册 HTTP 路由
    | "registerChannel"       // 注册消息渠道
    | "registerGatewayMethod" // 注册 Gateway 方法
    | "registerCli"           // 注册 CLI 命令
    | "registerProvider"      // 注册 Provider（模型/语音/图像等）
    | "registerAgentHarness"  // 注册外部 Agent Harness（ACP）
    | "registerMcpServer"     // 注册 MCP 服务器
    | ...（共 30+ 项）
  >>;
};

export const PLUGIN_MANIFEST_FILENAME = "openclaw.plugin.json";
export const MAX_PLUGIN_MANIFEST_BYTES = 256 * 1024;

// manifest 解析缓存（SLRU，512 条目）
const pluginManifestLoadCache = new PluginLruCache<PluginManifestLoadCacheEntry>(
  MAX_PLUGIN_MANIFEST_LOAD_CACHE_ENTRIES,
);

// 缓存 key 生成
export function createPluginCacheKey(...): PluginCacheKey;

// 清除缓存（测试用）
export function clearPluginManifestLoadCache(): void;

// runtime.ts — 全局 RegistryState 保存在 globalThis 上
const state: RegistryState = (() => {
  const globalState = globalThis as typeof globalThis & {
    [PLUGIN_REGISTRY_STATE]?: RegistryState;
  };
  let registryState = globalState[PLUGIN_REGISTRY_STATE];
  if (!registryState) {
    registryState = {
      activeRegistry: null,
      activeVersion: 0,
      httpRoute: { registry: null, pinned: false, version: 0 },
      channel: { registry: null, pinned: false, version: 0 },
      importedPluginIds: new Set<string>(),
      runtimeSubagentMode: "default",
    };
    globalState[PLUGIN_REGISTRY_STATE] = registryState;
  }
  return registryState;
})();

// 关键函数：
function asPluginRegistry(registry: RegistryState["activeRegistry"]): PluginRegistry | null;
async function cleanupPreviousPluginHostRegistry(params: {...}): Promise<void>;
function isRegistryLive(registry: PluginRegistry): boolean;
function isRegistryPinned(registry: PluginRegistry): boolean;

function shouldSandboxSession(
  cfg: SandboxConfig,
  sessionKey: string,
  mainSessionKey: string,
) {
  if (cfg.mode === "off") return false;   // 关闭沙箱
  if (cfg.mode === "all") return true;    // 所有 session 都沙箱
  // 默认：main session 不沙箱，其他沙箱
  return sessionKey.trim() !== mainSessionKey.trim();
}

export function resolveSandboxRuntimeStatus(params: {
  cfg?: OpenClawConfig;
  sessionKey?: string;
  agentId: string;
}): SandboxRuntimeStatus;

openclaw/src/
├── entry.ts                  # CLI 入口，runMainOrRootHelp()
├── entry.compile-cache.ts    # 编译缓存管理
├── entry.respawn.ts          # 进程重 spawn 逻辑
│
├── agents/                   # Agent 运行时核心
│   ├── acp-spawn.ts         # ACP 会话生成（1708 行）
│   ├── acp-runtime-overlay.ts
│   ├── agent-bundle-mcp-runtime.ts   # MCP Client 实现
│   ├── agent-bundle-mcp-tools.ts    # MCP 工具封装
│   ├── agent-command.ts      # Agent 命令处理
│   ├── harness/types.ts     # AgentHarness 接口定义
│   ├── sandbox/
│   │   ├── runtime-status.ts    # 沙箱模式判断
│   │   ├── config.ts           # 沙箱配置
│   │   └── tool-policy.ts      # 工具策略分类
│   └── agent-scope.ts       # Session / Agent 作用域解析
│
├── plugins/                  # 插件系统
│   ├── types.ts             # OpenClawPluginApi 公共接口
│   ├── manifest.ts          # openclaw.plugin.json 解析
│   ├── api-builder.ts       # PluginApi 构建器
│   ├── runtime.ts           # PluginRegistry 运行时协调器
│   ├── registry-types.ts    # Registry 类型定义
│   ├── registry-lifecycle.ts # Registry 生命周期管理
│   ├── host-hook-runtime.ts  # 钩子运行时分发
│   └── hook-types.ts        # 钩子类型定义
│
├── channels/                 # 消息渠道接入
│   ├── plugins/
│   │   ├── types.plugin.ts  # ChannelPlugin 接口
│   │   └── types.core.ts   # 核心 channel 类型
│   ├── route-projection.ts  # 消息路由映射
│   └── thread-bindings-*.ts # 线程/话题绑定
│
├── config/
│   ├── sessions/
│   │   ├── store.ts        # Session 存储
│   │   └── paths.ts        # 路径解析
│   ├── agent-limits.ts     # 子 agent 限制
│   └── types.openclaw.ts   # OpenClaw 配置类型
│
├── acp/                     # ACP 协议实现
│   ├── control-plane/
│   │   ├── manager.ts      # ACP Session 管理器
│   │   └── spawn.ts        # ACP Spawn 逻辑
│   └── policy.ts           # ACP 策略检查
│
├── cli/                     # CLI 相关
│   ├── argv.ts             # 参数解析
│   ├── profile.ts          # Profile 环境变量
│   └── program/            # CLI 程序结构
│
├── gateway/                 # Gateway WebSocket API
│   ├── server-methods/     # Gateway 方法处理
│   └── call.ts             # Gateway 调用封装
│
└── packages/                # 内部共享包
    ├── acp-core/           # ACP 核心类型与工具
    ├── agent-core/         # Agent 核心逻辑
    ├── plugin-sdk/         # 插件 SDK（public）
    ├── gateway-protocol/   # Gateway 协议定义
    ├── llm-core/           # LLM 接口
    ├── memory-host-sdk/    # MemorySearchManager 记忆契约
    └── model-catalog-core/ # 模型目录

extensions/                 # 141 个可插拔扩展（与 src/ 同级）
├── memory-lancedb/         # 向量嵌入检索（L2 距离）
├── memory-wiki/            # Markdown vault + 全文检索
└── active-memory/          # 会话滑动窗口即时上下文