🦞 OpenClaw (原ClawdBot) 开源项目深度分析

┌───────────────────────────────────────────────────────────────────────────┐
│                              用户交互层                                    │
├─────────────┬─────────────┬─────────────┬─────────────┬───────────────────┤
│  Telegram   │   WhatsApp  │   Discord   │    Slack    │   其他渠道...      │
└─────────────┴─────────────┴─────────────┴─────────────┴───────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                          Gateway Server (网关服务器)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │  WebSocket  │  │   HTTP API  │  │ Cron 调度   │  │  Hooks 系统     │   │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                           Agent 代理系统                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ 会话管理    │  │  工具执行   │  │  模型切换   │  │  记忆/上下文     │   │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                            模型提供商                                      │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────┐ │
│  │ Anthropic │  │  OpenAI   │  │  Google   │  │  Ollama   │  │  其他   │ │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘  └─────────┘ │
└───────────────────────────────────────────────────────────────────────────┘

openclaw/
├── src/                    # 核心源代码
│   ├── cli/               # CLI 命令实现
│   ├── commands/          # 子命令模块
│   ├── gateway/           # 网关服务器
│   ├── agents/            # AI Agent 系统
│   ├── channels/          # 渠道抽象层
│   ├── telegram/          # Telegram 渠道
│   ├── discord/           # Discord 渠道
│   ├── slack/             # Slack 渠道
│   ├── signal/            # Signal 渠道
│   ├── imessage/          # iMessage 渠道
│   ├── plugins/           # 插件系统
│   ├── config/            # 配置管理
│   ├── infra/             # 基础设施
│   └── media/             # 媒体处理
├── extensions/            # 扩展插件
│   ├── msteams/          # Microsoft Teams
│   ├── matrix/           # Matrix 协议
│   ├── voice-call/       # 语音通话
│   └── memory-lancedb/   # LanceDB 记忆
├── skills/               # 内置 Skills (52+)
├── apps/                 # 原生应用
│   ├── ios/             # iOS App
│   ├── macos/           # macOS App
│   └── android/         # Android App
├── docs/                 # 文档
├── ui/                   # Web UI
└── test/                 # 测试文件

┌─────────────────────────────────────────────────────────────────────────────┐
│                     $ openclaw gateway run --port 18789                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  ① 入口层 (src/entry.ts)                                                     │
│     • 设置进程标题 process.title = "openclaw"                                │
│     • 环境变量规范化 normalizeEnv()                                          │
│     • 实验性警告抑制                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  ② CLI 路由 (src/cli/run-main.ts)                                           │
│     • 加载 .env 配置                                                         │
│     • 运行时版本检查 assertSupportedRuntime()                                │
│     • 构建命令程序 buildProgram()                                            │
│     • 路由到 gateway run 子命令                                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  ③ Gateway 启动 (src/gateway/server.impl.ts)                                │
│     • 创建 HTTP Server + WebSocket Server                                    │
│     • 初始化 NodeRegistry（设备节点管理）                                     │
│     • 初始化 ChannelManager（消息渠道管理）                                   │
│     • 启动 CronService（定时任务）                                           │
│     • 绑定 WebSocket 处理器                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  ④ 渠道连接 (Telegram/WhatsApp/Discord/...)                                 │
│     • ChannelManager 启动配置的渠道                                          │
│     • 各渠道建立与平台的连接（Bot API / Web Socket 等）                       │
│     • 开始监听消息                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                        ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─  用户发送消息
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  ⑤ 消息到达 → Agent 调用                                                     │
│     • 渠道接收消息，路由到 Gateway                                           │
│     • Gateway 调用 runEmbeddedPiAgent()                                      │
│     • 进入 Agent 核心循环（第四章详解）                                       │
└─────────────────────────────────────────────────────────────────────────────┘

#!/usr/bin/env node
import { spawn } from "node:child_process";
import process from "node:process";
import { applyCliProfileEnv, parseCliProfileArgs } from "./cli/profile.js";
import { isTruthyEnvValue, normalizeEnv } from "./infra/env.js";
import { installProcessWarningFilter } from "./infra/warnings.js";

// 设置进程名称（便于 ps/top 识别）
process.title = "openclaw";

// 过滤 Node.js 实验性功能警告
installProcessWarningFilter();

// 规范化环境变量（处理大小写、别名等）
normalizeEnv();

export async function runCli(argv: string[] = process.argv) {
  // 1. Windows 特殊处理
  const normalizedArgv = stripWindowsNodeExec(argv);
  
  // 2. 加载 .env 文件
  loadDotEnv({ quiet: true });
  normalizeEnv();
  
  // 3. 确保 openclaw 在 PATH 中
  ensureOpenClawCliOnPath();

  // 4. 运行时版本检查（Node.js 22+）
  assertSupportedRuntime();

  // 5. 尝试快速路由（某些命令不需要完整初始化）
  if (await tryRouteCli(normalizedArgv)) {
    return;
  }

  // 6. 捕获控制台输出到结构化日志
  enableConsoleCapture();

  // 7. 构建命令程序（延迟加载）
  const { buildProgram } = await import("./program.js");
  const program = buildProgram();
  
  // 8. 解析命令并执行
  await program.parseAsync(normalizedArgv);
}

export async function startGatewayServer(
  port = 18789,
  opts: GatewayServerOptions = {},
): Promise<GatewayServer> {
  // 1. 创建核心运行时状态
  const {
    canvasHost,
    httpServer,
    wss,            // WebSocket Server
    clients,        // 连接的客户端
    broadcast,      // 广播函数
  } = await createGatewayRuntimeState({
    port,
    hostname: opts.hostname,
    ...
  });
  
  // 2. 节点注册表（管理连接的设备：手机、其他网关）
  const nodeRegistry = new NodeRegistry();
  
  // 3. Cron 服务（定时任务调度）
  let cronState = buildGatewayCronService({
    config: cfg,
    onTrigger: (job) => handleCronTrigger(job),
    ...
  });
  
  // 4. 渠道管理器（管理所有消息渠道）
  const channelManager = createChannelManager({
    config: cfg,
    onMessage: (msg) => routeMessageToAgent(msg),
    ...
  });
  
  // 5. 绑定 WebSocket 处理器
  attachGatewayWsHandlers({
    wss,
    clients,
    nodeRegistry,
    channelManager,
    ...
  });
  
  // 6. 启动渠道连接
  await channelManager.startAll();
  
  return { httpServer, wss, channelManager, ... };
}

用户在 Telegram 发送消息
         │
         ▼
┌─────────────────────────────────────────┐
│  Telegram Bot API (Grammy)              │
│  src/telegram/bot.ts                    │
└─────────────────────────────────────────┘
         │ bot.on("message", handler)
         ▼
┌─────────────────────────────────────────┐
│  消息处理中间件                          │
│  • 节流 (apiThrottler)                  │
│  • 串行化 (sequentialize)               │
│  • 权限检查 (allowlist)                 │
└─────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│  ChannelManager.routeMessage()          │
│  统一消息格式，路由到 Agent              │
└─────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│  runEmbeddedPiAgent()                   │
│  src/agents/pi-embedded-runner/run.ts   │
│  ────────────────────────────────────── │
│  进入 Agent 核心循环（第四章详解）        │
└─────────────────────────────────────────┘

// src/telegram/bot.ts
export function createTelegramBot(opts: TelegramBotOptions) {
  const bot = new Bot(opts.token);
  
  // 节流：避免触发 Telegram API 限制
  bot.api.config.use(apiThrottler());
  
  // 串行化：同一聊天的消息按顺序处理
  bot.use(sequentialize(getTelegramSequentialKey));
  
  // 消息处理
  bot.on("message:text", async (ctx) => {
    const message = ctx.message.text;
    const chatId = ctx.chat.id;
    
    // 路由到 Agent
    await routeToAgent({
      channel: "telegram",
      chatId,
      message,
      replyFn: (text) => ctx.reply(text),
    });
  });
  
  return bot;
}

// 统一的消息格式
interface ChannelMessage {
  channel: ChatChannelId;     // "telegram" | "whatsapp" | ...
  chatId: string;             // 聊天标识
  userId: string;             // 用户标识
  message: string;            // 消息内容
  replyFn: (text: string) => Promise<void>;  // 回复函数
}

┌─────────────────────────────────────────────────────────────────────────┐
│                         用户消息输入                                     │
│                    (Telegram/WhatsApp/CLI/...)                          │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    runEmbeddedPiAgent()                                  │
│               src/agents/pi-embedded-runner/run.ts                       │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  • 会话队列管理 (sessionLane / globalLane)                       │    │
│  │  • 模型解析 & API Key 管理                                       │    │
│  │  • 上下文溢出处理 → 自动压缩                                     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    runEmbeddedAttempt()                                  │
│            src/agents/pi-embedded-runner/run/attempt.ts                  │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  • Skills 加载                                                   │    │
│  │  • Bootstrap 文件注入                                            │    │
│  │  • 工具创建                                                      │    │
│  │  • 系统提示词构建                                                │    │
│  │  • createAgentSession() - 创建 Agent 会话                        │    │
│  │  • session.prompt() - 执行 LLM 调用                              │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              subscribeEmbeddedPiSession() - 事件订阅                     │
│                src/agents/pi-embedded-subscribe.ts                       │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  事件类型:                                                       │    │
│  │  • message_start/update/end   - 消息流处理                       │    │
│  │  • tool_execution_start/update/end - 工具调用处理                │    │
│  │  • agent_start/end            - Agent 生命周期                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       LLM 模型调用层                                     │
│               @mariozechner/pi-ai (streamSimple)                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  支持的提供商:                                                   │    │
│  │  • Anthropic (Claude)                                            │    │
│  │  • OpenAI (GPT-4/4o)                                             │    │
│  │  • Google (Gemini)                                               │    │
│  │  • Ollama (本地模型)                                             │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

export async function runEmbeddedPiAgent(
  params: RunEmbeddedPiAgentParams,
): Promise<EmbeddedPiRunResult> {
  // 1. 创建会话队列（确保同一会话的消息串行处理）
  const sessionLane = resolveSessionLane(params.sessionKey?.trim() || params.sessionId);
  const globalLane = resolveGlobalLane(params.lane);
  
  return enqueueSession(() =>
    enqueueGlobal(async () => {
      // 2. 解析模型
      const { model, authStorage, modelRegistry } = resolveModel(
        provider, modelId, agentDir, params.config
      );
      
      // 3. 执行单次 Agent 运行
      const attempt = await runEmbeddedAttempt({...});
      
      // 4. 处理上下文溢出 → 自动压缩后重试
      if (isContextOverflowError(errorText)) {
        await compactEmbeddedPiSessionDirect({...});
        continue;  // 压缩后重试
      }
      
      // 5. 返回结果
      return { payloads, meta };
    })
  );
}

export async function runEmbeddedAttempt(
  params: EmbeddedRunAttemptParams,
): Promise<EmbeddedRunAttemptResult> {
  // 1. 加载 Skills
  const skillEntries = loadWorkspaceSkillEntries(effectiveWorkspace);
  const skillsPrompt = resolveSkillsPromptForRun({...});
  
  // 2. 加载 Bootstrap 上下文文件（如 AGENTS.md）
  const { bootstrapFiles, contextFiles } = await resolveBootstrapContextForRun({...});
  
  // 3. 创建工具集
  const toolsRaw = createOpenClawCodingTools({
    messageProvider: params.messageChannel,
    sessionKey: params.sessionKey,
    workspaceDir: effectiveWorkspace,
    config: params.config,
    abortSignal: runAbortController.signal,
  });
  
  // 4. 构建系统提示词
  const systemPromptText = buildEmbeddedSystemPrompt({
    workspaceDir: effectiveWorkspace,
    toolNames: tools.map(t => t.name),
    skillsPrompt,
    contextFiles,
    runtimeInfo: {...},
  });
  
  // 5. 创建 Agent 会话（核心！）
  const { session } = await createAgentSession({
    cwd: resolvedWorkspace,
    agentDir,
    model: params.model,
    tools: builtInTools,
    customTools: allCustomTools,
    sessionManager,
  });
  
  // 6. 设置流式调用函数
  session.agent.streamFn = streamSimple;
  
  // 7. 订阅会话事件
  const subscription = subscribeEmbeddedPiSession({
    session: activeSession,
    runId: params.runId,
    onToolResult: params.onToolResult,
    onBlockReply: params.onBlockReply,
    onAgentEvent: params.onAgentEvent,
  });
  
  // 8. 执行 prompt（调用 LLM）—— 这是核心！
  await activeSession.prompt(effectivePrompt);
  
  // 9. 返回结果
  return {
    assistantTexts,
    toolMetas,
    lastAssistant,
  };
}

┌─────────────────────────────────────────────────────────────────────────┐
│                        上下文工程管理架构                                 │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
        ┌──────────────────────────┼──────────────────────────┐
        ▼                          ▼                          ▼
┌───────────────────┐   ┌───────────────────┐   ┌───────────────────────┐
│   会话存储层       │   │   Token 管理层     │   │    压缩策略层          │
│  (.jsonl 文件)    │   │  (估算与限制)      │   │  (多级裁剪)            │
└───────────────────┘   └───────────────────┘   └───────────────────────┘
        │                          │                          │
        │                          │           ┌──────────────┴──────────┐
        │                          │           ▼                         ▼
        │                          │   ┌──────────────┐     ┌──────────────────┐
        │                          │   │ Context      │     │ Compaction       │
        │                          │   │ Pruning      │     │ Safeguard        │
        │                          │   │ (软裁剪)     │     │ (摘要生成)        │
        │                          │   └──────────────┘     └──────────────────┘
        ▼                          ▼
┌───────────────────┐   ┌───────────────────┐
│  Memory Search    │   │  History Limit    │
│  (语义检索)       │   │  (轮次限制)       │
└───────────────────┘   └───────────────────┘

{"message": {"role": "user", "content": "你好", "timestamp": 1234567890}}
{"message": {"role": "assistant", "content": [{"type": "text", "text": "你好！"}], "timestamp": 1234567891}}
{"message": {"role": "toolResult", "content": [{"type": "text", "text": "执行结果..."}], "toolCallId": "xxx"}}

import type { AgentMessage } from "@mariozechner/pi-agent-core";
import { estimateTokens, generateSummary } from "@mariozechner/pi-coding-agent";
import { DEFAULT_CONTEXT_TOKENS } from "./defaults.js";

export const BASE_CHUNK_RATIO = 0.4;
export const MIN_CHUNK_RATIO = 0.15;
export const SAFETY_MARGIN = 1.2; // 20% buffer for estimateTokens() inaccuracy

export function estimateMessagesTokens(messages: AgentMessage[]): number {
  return messages.reduce((sum, message) => sum + estimateTokens(message), 0);
}

CONTEXT_WINDOW_HARD_MIN_TOKENS = 16_000;   // 硬性最小值
CONTEXT_WINDOW_WARN_BELOW_TOKENS = 32_000; // 警告阈值

// 上下文信息解析优先级：
// 1. modelsConfig (配置文件中的模型配置)
// 2. model (模型元数据)
// 3. agentContextTokens (代理配置)
// 4. default (默认值: 200,000)

const CHARS_PER_TOKEN_ESTIMATE = 4;
const IMAGE_CHAR_ESTIMATE = 8_000;  // 图片按 8000 字符计算

function estimateMessageChars(message: AgentMessage): number {
  if (message.role === "user") {
    // 处理文本和图片
  }
  if (message.role === "assistant") {
    // 处理文本、thinking、toolCall
  }
  if (message.role === "toolResult") {
    // 处理工具结果（文本+图片）
  }
}

// 配置参数
softTrimRatio: 0.3,           // 占用 30% 上下文时触发
softTrim: {
  maxChars: 4_000,            // 超过 4000 字符触发裁剪
  headChars: 1_500,           // 保留开头 1500 字符
  tailChars: 1_500,           // 保留结尾 1500 字符
}

// 裁剪后的格式
"[前 1500 字符]\n\n[... 中间内容已裁剪 ...]\n\n[后 1500 字符]"

// 配置参数
hardClearRatio: 0.5,              // 占用 50% 上下文时触发
minPrunableToolChars: 50_000,     // 最小可裁剪字符数
hardClear: {
  enabled: true,
  placeholder: "[Old tool result content cleared]",
}

计算当前上下文占用比例 (ratio)
              │
              ▼
   ratio < 0.3 ─────────→ 不裁剪
              │
              ▼
  0.3 ≤ ratio < 0.5 ────→ 软裁剪工具结果
              │            (保留头尾)
              ▼
    ratio ≥ 0.5 ────────→ 硬清除工具结果
                          (替换为占位符)
              │
              ▼
    保护首个用户消息之前的内容
    (bootstrap files)

// 触发时机: session_before_compact 事件
api.on("session_before_compact", async (event, ctx) => {
  // 1. 计算文件操作摘要
  const fileSummary = computeFileSummary(messages);
  // 包含：读取的文件、修改的文件、创建的文件
  
  // 2. 收集工具失败记录
  const failedTools = collectToolFailures(messages);
  
  // 3. 如果新内容超过历史预算，裁剪旧消息
  const pruned = pruneHistoryForContextShare({
    messages,
    maxContextTokens,
    maxHistoryShare: 0.5,  // 历史最多占 50%
  });
  
  // 4. 为被裁剪的消息生成摘要
  const droppedSummary = await summarizeInStages({
    messages: pruned.droppedMessagesList,
  });
  
  // 5. 合并生成最终历史摘要
  return {
    additionalHistory: [fileSummary, failedTools, droppedSummary].join("\n"),
  };
});

export function splitMessagesByTokenShare(
  messages: AgentMessage[],
  parts = DEFAULT_PARTS,
): AgentMessage[][] {
  // 将消息按 token 数量均匀分成多份
  const totalTokens = estimateMessagesTokens(messages);
  const targetTokens = totalTokens / normalizedParts;
  // ...
}

export function chunkMessagesByMaxTokens(
  messages: AgentMessage[],
  maxTokens: number,
): AgentMessage[][] {
  // 确保每个块不超过 maxTokens
  // 处理超大消息：单独成块
}

原始消息列表 (N 条)
         │
         ▼
  ┌──────────────────┐
  │ splitMessagesByTokenShare │
  │   (按 token 均分)         │
  └──────────────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│ Part 1 │ │ Part 2 │  (默认分 2 份)
└────────┘ └────────┘
    │         │
    ▼         ▼
┌────────┐ ┌────────┐
│Summary │ │Summary │  (各自生成摘要)
│   1    │ │   2    │
└────────┘ └────────┘
    │         │
    └────┬────┘
         ▼
  ┌──────────────────┐
  │  Merge Summaries │
  │  (合并为最终摘要) │
  └──────────────────┘
         │
         ▼
    最终历史摘要

export function limitHistoryTurns(
  messages: AgentMessage[],
  limit: number,
): AgentMessage[] {
  // 保留最后 N 个用户轮次
  // 从后向前扫描 user 消息
  // 超过 limit 的轮次被丢弃
}

// 配置示例
config.channels.telegram.dmHistoryLimit = 50;  // 全局限制
config.channels.telegram.dms["user123"].historyLimit = 100;  // 用户特定限制

┌─────────────────────────────────────────────────────────────────────┐
│                       事件驱动消息处理流程                            │
└─────────────────────────────────────────────────────────────────────┘

    LLM 流式输出
         │
         ▼
┌─────────────────┐
│  session.subscribe()  │  ← 订阅会话事件
└────────┬────────┘
         │
         ▼ 事件流
   ┌─────┴─────┬─────────┬─────────┬─────────┐
   ▼           ▼         ▼         ▼         ▼
┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐
│message│  │message│  │message│  │ tool │  │agent │
│_start │  │_update│  │_end  │  │_exec │  │_end  │
└──────┘  └──────┘  └──────┘  └──────┘  └──────┘
   │           │         │         │         │
   ▼           ▼         ▼         ▼         ▼
┌──────────────────────────────────────────────────┐
│          switch (evt.type) { ... }               │  ← 事件分发器
└──────────────────────────────────────────────────┘
   │           │         │         │         │
   ▼           ▼         ▼         ▼         ▼
处理器1     处理器2    处理器3   处理器4   处理器5

export function subscribeEmbeddedPiSession(params: SubscribeEmbeddedPiSessionParams) {
  // 1. 初始化状态（用于跨事件共享数据）
  const state: EmbeddedPiSubscribeState = {
    assistantTexts: [],           // 收集 assistant 回复
    toolMetas: [],                // 收集工具调用元数据
    toolMetaById: new Map(),      // 按 ID 索引工具元数据
    deltaBuffer: "",              // 流式文本缓冲（累积已收到的文本）
    blockBuffer: "",              // 块缓冲（用于分块回复）
  };
  
  // 2. 创建上下文对象（包含状态 + 工具函数）
  const ctx: EmbeddedPiSubscribeContext = {
    params,              // 原始参数
    state,               // 共享状态
    log,                 // 日志器
    // ... 各种工具函数
  };
  
  // 3. 创建事件处理器并订阅
  const handler = createEmbeddedPiSessionEventHandler(ctx);
  const unsubscribe = params.session.subscribe(handler);
  
  // 4. 返回结果和取消订阅函数
  return { assistantTexts, toolMetas, unsubscribe };
}

// 这是一个"工厂函数"，返回一个事件处理器
export function createEmbeddedPiSessionEventHandler(ctx: EmbeddedPiSubscribeContext) {
  // 返回的函数会被每个事件调用
  return (evt: EmbeddedPiSubscribeEvent) => {
    // 根据事件类型分发到不同处理器
    switch (evt.type) {
      case "message_start":
        handleMessageStart(ctx, evt);    // → handlers.messages.ts
        return;
      case "message_update":
        handleMessageUpdate(ctx, evt);   // → handlers.messages.ts (核心！)
        return;
      case "message_end":
        handleMessageEnd(ctx, evt);      // → handlers.messages.ts
        return;
      case "tool_execution_start":
        handleToolExecutionStart(ctx, evt);  // → handlers.tools.ts
        return;
      case "tool_execution_update":
        handleToolExecutionUpdate(ctx, evt); // → handlers.tools.ts
        return;
      case "tool_execution_end":
        handleToolExecutionEnd(ctx, evt);    // → handlers.tools.ts
        return;
      case "agent_start":
        handleAgentStart(ctx);           // → handlers.lifecycle.ts
        return;
      case "auto_compaction_start":
        handleAutoCompactionStart(ctx);  // → handlers.lifecycle.ts
        return;
      case "auto_compaction_end":
        handleAutoCompactionEnd(ctx, evt); // → handlers.lifecycle.ts
        return;
      case "agent_end":
        handleAgentEnd(ctx);             // → handlers.lifecycle.ts
        return;
    }
  };
}

                    evt = { type: "message_update", delta: "Hello" }
                                        │
                                        ▼
┌────────────────────────────────────────────────────────────────────┐
│  switch (evt.type)                                                 │
│                                                                    │
│   evt.type === "message_start"   ?  → handleMessageStart(ctx, evt) │
│   evt.type === "message_update"  ?  → handleMessageUpdate(ctx, evt)│ ← 命中！
│   evt.type === "message_end"     ?  → handleMessageEnd(ctx, evt)   │
│   evt.type === "tool_*"          ?  → handleTool*(ctx, evt)        │
│   evt.type === "agent_*"         ?  → handleAgent*(ctx)            │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
                          handleMessageUpdate(ctx, evt)
                                        │
                                        ▼
                          ctx.state.deltaBuffer += "Hello"
                          ctx.params.onPartialReply?.("Hello")

export function handleMessageUpdate(ctx, evt) {
  const msg = evt.message;
  if (msg?.role !== "assistant") return;  // 只处理 assistant 消息
  
  // 1. 解析事件子类型
  const evtType = assistantRecord.type;  // "text_delta" | "text_start" | "text_end"
  const delta = assistantRecord.delta;    // 本次增量文本
  
  // 2. 处理不同子类型
  if (evtType === "text_delta") {
    chunk = delta;  // 直接使用增量
  } else if (evtType === "text_end") {
    // 计算增量（防止重复）
    if (content.startsWith(ctx.state.deltaBuffer)) {
      chunk = content.slice(ctx.state.deltaBuffer.length);
    }
  }
  
  // 3. 累积到缓冲区
  ctx.state.deltaBuffer += chunk;
  
  // 4. 触发流式回复回调
  ctx.params.onPartialReply?.(ctx.state.deltaBuffer);
  
  // 5. 处理思考标签 <think>...</think>
  // 6. 处理块分割（长消息分块发送）
}

LLM 输出:  "H" → "e" → "l" → "l" → "o" → " " → "W" → "o" → "r" → "l" → "d"

事件流:
  message_start
  message_update { delta: "H" }      → deltaBuffer = "H"
  message_update { delta: "e" }      → deltaBuffer = "He"
  message_update { delta: "l" }      → deltaBuffer = "Hel"
  message_update { delta: "l" }      → deltaBuffer = "Hell"
  message_update { delta: "o" }      → deltaBuffer = "Hello"
  message_update { delta: " " }      → deltaBuffer = "Hello "
  message_update { delta: "W" }      → deltaBuffer = "Hello W"
  ...
  message_end { content: "Hello World" }  → 最终确认

src/agents/
├── pi-embedded-subscribe.ts                    # 入口：订阅函数
├── pi-embedded-subscribe.handlers.ts           # 分发器：switch 路由
├── pi-embedded-subscribe.handlers.types.ts     # 类型定义
├── pi-embedded-subscribe.handlers.messages.ts  # 消息处理器
├── pi-embedded-subscribe.handlers.tools.ts     # 工具处理器
└── pi-embedded-subscribe.handlers.lifecycle.ts # 生命周期处理器

export async function handleToolExecutionStart(
  ctx: EmbeddedPiSubscribeContext,
  evt: AgentEvent & { toolName: string; toolCallId: string; args: unknown },
) {
  // 1. 记录工具元数据
  const toolName = normalizeToolName(evt.toolName);
  const meta = inferToolMetaFromArgs(toolName, evt.args);
  ctx.state.toolMetaById.set(evt.toolCallId, meta);
  
  // 2. 发送工具开始事件
  emitAgentEvent({
    runId: ctx.params.runId,
    stream: "tool",
    data: { phase: "start", name: toolName, toolCallId: evt.toolCallId, args: evt.args },
  });
}

export function handleToolExecutionEnd(
  ctx: EmbeddedPiSubscribeContext,
  evt: AgentEvent & { toolName: string; toolCallId: string; result: unknown },
) {
  const toolName = normalizeToolName(evt.toolName);
  const meta = ctx.state.toolMetaById.get(evt.toolCallId);
  
  // 1. 记录工具结果
  ctx.state.toolMetas.push({ toolName, meta });
  
  // 2. 发送工具结束事件
  emitAgentEvent({
    runId: ctx.params.runId,
    stream: "tool",
    data: { phase: "result", name: toolName, toolCallId: evt.toolCallId, result: evt.result },
  });
}

┌─────────────────────────────────────────────────────────────────────────────┐
│  用户: "当前目录有什么文件？"                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  第 1 轮：LLM 分析并决定调用工具                                              │
│                                                                             │
│  LLM 返回:                                                                  │
│  {                                                                          │
│    "type": "tool_call",                                                     │
│    "tool_name": "list_files",                                               │
│    "tool_call_id": "call_abc123",                                           │
│    "arguments": {                                                           │
│      "path": ".",                                                           │
│      "recursive": false                                                     │
│    }                                                                        │
│  }                                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
         ┌─────────────────┐            ┌─────────────────────────┐
         │ tool_execution  │            │  Agent 框架执行工具      │
         │ _start 事件     │            │                         │
         │                 │            │  fs.readdir(".")        │
         │ → 显示"正在     │            │  → ["src/", "docs/",    │
         │   列出文件..."  │            │     "package.json",     │
         └─────────────────┘            │     "README.md"]        │
                                        └─────────────────────────┘
                                                    │
                                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  tool_execution_end 事件                                                    │
│                                                                             │
│  {                                                                          │
│    "type": "tool_result",                                                   │
│    "tool_call_id": "call_abc123",                                           │
│    "result": "src/\ndocs/\npackage.json\nREADME.md"                         │
│  }                                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  第 2 轮：LLM 收到工具结果，生成最终回复                                       │
│                                                                             │
│  LLM 输入上下文:                                                             │
│  - 用户消息: "当前目录有什么文件？"                                           │
│  - 工具调用: list_files(path=".")                                           │
│  - 工具结果: "src/\ndocs/\npackage.json\nREADME.md"                          │
│                                                                             │
│  LLM 返回:                                                                  │
│  "当前目录包含以下文件和文件夹：                                              │
│   - src/ (源代码目录)                                                        │
│   - docs/ (文档目录)                                                         │
│   - package.json (项目配置)                                                  │
│   - README.md (项目说明)"                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  用户收到回复 ✅                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

export function createOpenClawCodingTools(options?: {...}): AnyAgentTool[] {
  // 1. 创建基础编码工具
  const base = codingTools.flatMap((tool) => {
    if (tool.name === readTool.name) {
      return [createOpenClawReadTool(...)];
    }
    // ...
  });
  
  // 2. 创建执行工具
  const execTool = createExecTool({ ... });
  
  // 3. 创建 OpenClaw 特有工具
  const openclawTools = createOpenClawTools({...});
  
  // 4. 添加钩子包装（before_tool_call hook）
  const withHooks = normalized.map(tool => 
    wrapToolWithBeforeToolCallHook(tool, {...})
  );
  
  return withHooks;
}

┌─────────────────────────────────────────────────────────────────┐
│                        用户发送消息                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    1. 队列等待（串行化）                          │
│                    enqueueSession() + enqueueGlobal()           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    2. 创建 Agent 会话                            │
│                    createAgentSession()                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    3. 构建系统提示词                              │
│                    buildAgentSystemPrompt()                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    4. 调用 LLM                                   │
│                    session.prompt(userMessage)                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    ▼                       ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │   LLM 返回文本     │   │   LLM 返回工具调用     │
        └───────────────────┘   └───────────────────────┘
                    │                       │
                    │                       ▼
                    │           ┌───────────────────────┐
                    │           │   5. 执行工具          │
                    │           │   tool.execute(args)  │
                    │           └───────────────────────┘
                    │                       │
                    │                       ▼
                    │           ┌───────────────────────┐
                    │           │   6. 返回工具结果      │
                    │           │   tool result → LLM   │
                    │           └───────────────────────┘
                    │                       │
                    │           ┌───────────┴───────────┐
                    │           │  LLM 可能继续调用工具  │
                    │           │  (循环步骤 4-6)       │
                    │           └───────────────────────┘
                    │                       │
                    └───────────┬───────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    7. 收集最终回复                                │
│                    assistantTexts + toolMetas                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    8. 返回给用户                                  │
│                    通过原渠道发送回复                              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      系统提示词 (System Prompt)                   │
├─────────────────────────────────────────────────────────────────┤
│  1. 身份声明 (Identity)                                          │
│     "You are a personal assistant running inside OpenClaw."     │
├─────────────────────────────────────────────────────────────────┤
│  2. 工具部分 (Tooling)                                           │
│     - 可用工具列表及描述                                          │
│     - 工具调用风格指南                                            │
├─────────────────────────────────────────────────────────────────┤
│  3. 安全规则 (Safety)                                            │
│     - 无独立目标                                                  │
│     - 优先安全和人类监督                                          │
├─────────────────────────────────────────────────────────────────┤
│  4. CLI 快速参考 (CLI Reference)                                 │
│     - OpenClaw 命令用法                                          │
├─────────────────────────────────────────────────────────────────┤
│  5. Skills 系统 (Skills)                                         │
│     - 技能扫描规则                                                │
│     - 技能选择和加载指南                                          │
├─────────────────────────────────────────────────────────────────┤
│  6. 记忆系统 (Memory)                                            │
│     - 记忆检索指南                                                │
├─────────────────────────────────────────────────────────────────┤
│  7. 工作空间 (Workspace)                                         │
│     - 当前工作目录                                                │
├─────────────────────────────────────────────────────────────────┤
│  8. 文档参考 (Docs)                                              │
│     - OpenClaw 文档路径                                          │
├─────────────────────────────────────────────────────────────────┤
│  9. 消息系统 (Messaging)                                         │
│     - 跨会话消息发送                                              │
│     - message 工具用法                                           │
├─────────────────────────────────────────────────────────────────┤
│ 10. 项目上下文 (Project Context)                                 │
│     - AGENTS.md / SOUL.md 等文件内容                             │
├─────────────────────────────────────────────────────────────────┤
│ 11. 静默回复 (Silent Replies)                                    │
│     - 无需回复时的处理                                            │
├─────────────────────────────────────────────────────────────────┤
│ 12. 运行时信息 (Runtime)                                         │
│     - agent/host/os/model 等环境信息                             │
└─────────────────────────────────────────────────────────────────┘

// src/agents/system-prompt.ts
export function buildAgentSystemPrompt(params: {
  workspaceDir: string;           // 工作目录
  toolNames?: string[];           // 可用工具名列表
  toolSummaries?: Record<string, string>;  // 工具描述映射
  skillsPrompt?: string;          // Skills 提示词
  contextFiles?: EmbeddedContextFile[];    // 上下文文件（如 AGENTS.md）
  runtimeInfo?: {...};            // 运行时信息
  // ...更多参数
}) {
  const lines = [];
  
  // 1️⃣ 身份声明
  lines.push("You are a personal assistant running inside OpenClaw.");
  
  // 2️⃣ 工具部分
  lines.push("## Tooling", ...toolLines);
  
  // 3️⃣ 安全规则
  lines.push(...buildSafetySection());
  
  // 4️⃣ CLI 参考
  lines.push("## OpenClaw CLI Quick Reference", ...);
  
  // 5️⃣ Skills 系统
  lines.push(...buildSkillsSection({...}));
  
  // 6️⃣ 记忆系统
  lines.push(...buildMemorySection({...}));
  
  // 7️⃣ 工作空间
  lines.push("## Workspace", `Your working directory is: ${params.workspaceDir}`);
  
  // 8️⃣ 文档参考
  lines.push(...buildDocsSection({...}));
  
  // 9️⃣ 消息系统
  lines.push(...buildMessagingSection({...}));
  
  // 🔟 项目上下文（关键！）
  if (contextFiles?.length > 0) {
    lines.push("# Project Context");
    for (const file of contextFiles) {
      lines.push(`## ${file.path}`, file.content);
    }
  }
  
  // 1️⃣1️⃣ 静默回复
  lines.push("## Silent Replies", ...);
  
  // 1️⃣2️⃣ 运行时信息
  lines.push("## Runtime", buildRuntimeLine(runtimeInfo, ...));
  
  return lines.filter(Boolean).join("\n");
}

┌─────────────────────────────────────────────────────────────────────────────┐
│                      Function Calling 完整工作流程                           │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ 第 1 步：开发者定义函数（工具）                                               │
│                                                                             │
│ const readTool = {                                                          │
│   name: "read",                                                             │
│   description: "Read file contents",                                        │
│   parameters: {                                                             │
│     type: "object",                                                         │
│     properties: {                                                           │
│       path: { type: "string", description: "File path to read" },           │
│       encoding: { type: "string", description: "File encoding" }            │
│     },                                                                      │
│     required: ["path"]                                                      │
│   }                                                                         │
│ };                                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 第 2 步：调用 LLM API 时传入 tools 参数                                       │
│                                                                             │
│ const response = await openai.chat.completions.create({                     │
│   model: "gpt-4",                                                           │
│   messages: [                                                               │
│     { role: "system", content: "You are a helpful assistant..." },          │
│     { role: "user", content: "读取 package.json 的内容" }                    │
│   ],                                                                        │
│   tools: [{                           // ← 关键：传入工具定义                 │
│     type: "function",                                                       │
│     function: readTool                                                      │
│   }]                                                                        │
│ });                                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 第 3 步：LLM 分析用户意图，决定是否调用函数                                    │
│                                                                             │
│ LLM 内部思考：                                                               │
│ "用户想读取 package.json → 我需要使用 read 工具 → 参数是 path='package.json'"  │
│                                                                             │
│ LLM 返回（不是普通文本，而是结构化的 tool_calls）：                            │
│ {                                                                           │
│   "choices": [{                                                             │
│     "message": {                                                            │
│       "role": "assistant",                                                  │
│       "content": null,               // ← 没有文本内容                       │
│       "tool_calls": [{               // ← 而是函数调用请求                   │
│         "id": "call_abc123",                                                │
│         "type": "function",                                                 │
│         "function": {                                                       │
│           "name": "read",                                                   │
│           "arguments": "{\"path\": \"package.json\"}"                       │
│         }                                                                   │
│       }]                                                                    │
│     }                                                                       │
│   }]                                                                        │
│ }                                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 第 4 步：Agent 框架执行函数                                                   │
│                                                                             │
│ // 解析 LLM 返回的调用请求                                                   │
│ const toolCall = response.choices[0].message.tool_calls[0];                 │
│ const args = JSON.parse(toolCall.function.arguments);                       │
│                                                                             │
│ // 执行实际的函数                                                            │
│ const result = await fs.readFile(args.path, "utf-8");                       │
│ // result = '{ "name": "openclaw", "version": "1.0.0", ... }'               │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 第 5 步：把执行结果返回给 LLM                                                 │
│                                                                             │
│ const followUp = await openai.chat.completions.create({                     │
│   model: "gpt-4",                                                           │
│   messages: [                                                               │
│     { role: "system", content: "..." },                                     │
│     { role: "user", content: "读取 package.json 的内容" },                   │
│     { role: "assistant", content: null, tool_calls: [...] },  // LLM的调用  │
│     {                                                                       │
│       role: "tool",                   // ← 工具执行结果                      │
│       tool_call_id: "call_abc123",                                          │
│       content: '{ "name": "openclaw", "version": "1.0.0" }'                 │
│     }                                                                       │
│   ]                                                                         │
│ });                                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 第 6 步：LLM 基于工具结果生成最终回复                                          │
│                                                                             │
│ LLM 返回：                                                                   │
│ {                                                                           │
│   "choices": [{                                                             │
│     "message": {                                                            │
│       "role": "assistant",                                                  │
│       "content": "package.json 的内容如下：\n\n这是一个名为 openclaw 的项目，│
│                   版本号是 1.0.0..."                                         │
│     }                                                                       │
│   }]                                                                        │
│ }                                                                           │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                        LLM API 调用结构                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                               │
          ┌────────────────────┼────────────────────┐
          ▼                                         ▼
┌───────────────────────────┐          ┌────────────────────────────┐
│  system (System Prompt)   │          │  tools (工具定义数组)       │
│                           │          │                            │
│  "## Tooling              │          │  [{                        │
│  - read: Read file...     │          │    name: "read",           │
│  - write: Create...       │          │    description: "...",     │
│  - edit: Make precise..." │          │    parameters: {           │
│                           │          │      type: "object",       │
│  (只有名称 + 简短描述)     │          │      properties: {         │
│                           │          │        path: {...},        │
│                           │          │        encoding: {...}     │
│                           │          │      },                    │
│                           │          │      required: ["path"]    │
│                           │          │    }                       │
│                           │          │  }, ...]                   │
│                           │          │                            │
│                           │          │  (完整的 JSON Schema)       │
└───────────────────────────┘          └────────────────────────────┘

function buildSafetySection() {
  return [
    "## Safety",
    // 🔒 无独立目标约束
    "You have no independent goals: do not pursue self-preservation, " +
    "replication, resource acquisition, or power-seeking; " +
    "avoid long-term plans beyond the user's request.",
    
    // 🔒 优先安全和人类监督
    "Prioritize safety and human oversight over completion; " +
    "if instructions conflict, pause and ask; " +
    "comply with stop/pause/audit requests and never bypass safeguards. " +
    "(Inspired by Anthropic's constitution.)",
    
    // 🔒 禁止操控和自我复制
    "Do not manipulate or persuade anyone to expand access or disable safeguards. " +
    "Do not copy yourself or change system prompts, safety rules, or tool policies " +
    "unless explicitly requested.",
  ];
}

function buildSkillsSection(params: {
  skillsPrompt?: string;  // 包含 <available_skills> 列表
  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 \`${params.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.",
    // 实际的 skills 列表
    params.skillsPrompt,  // <available_skills>...</available_skills>
  ];
}

function buildMemorySection(params: { availableTools: Set<string> }) {
  // 只有当 memory 工具可用时才添加
  if (!params.availableTools.has("memory_search")) {
    return [];
  }
  return [
    "## Memory Recall",
    "Before answering anything about prior work, decisions, dates, people, " +
    "preferences, or todos: run memory_search on MEMORY.md + memory/*.md; " +
    "then use memory_get to pull only the needed lines. " +
    "If low confidence after search, say you checked.",
  ];
}

// 注入项目上下文文件
if (contextFiles?.length > 0) {
  // 检查是否有 SOUL.md（人格设定文件）
  const hasSoulFile = contextFiles.some((file) => 
    file.path.toLowerCase().endsWith("soul.md")
  );
  
  lines.push("# Project Context");
  lines.push("The following project context files have been loaded:");
  
  // 如果有 SOUL.md，添加特殊指令
  if (hasSoulFile) {
    lines.push(
      "If SOUL.md is present, embody its persona and tone. " +
      "Avoid stiff, generic replies; follow its guidance " +
      "unless higher-priority instructions override it."
    );
  }
  
  // 注入每个上下文文件的内容
  for (const file of contextFiles) {
    lines.push(`## ${file.path}`, "", file.content, "");
  }
}

export function buildRuntimeLine(runtimeInfo?: {...}): string {
  return `Runtime: ${[
    runtimeInfo?.agentId ? `agent=${runtimeInfo.agentId}` : "",
    runtimeInfo?.host ? `host=${runtimeInfo.host}` : "",
    runtimeInfo?.os ? `os=${runtimeInfo.os}` : "",
    runtimeInfo?.model ? `model=${runtimeInfo.model}` : "",
    runtimeInfo?.channel ? `channel=${runtimeInfo.channel}` : "",
  ].filter(Boolean).join(" | ")}`;
}

Runtime: agent=main | host=MacBook | os=darwin (arm64) | model=claude-sonnet-4-20250514 | channel=telegram

优先级 (低 → 高):
┌─────────────────────────────────────────────────────────┐
│  1. extraDirs     - 用户配置的额外目录                   │
│  2. bundled       - 内置 skills (项目 /skills/ 目录)     │
│  3. managed       - 托管目录 (~/.config/openclaw/skills/)│
│  4. workspace     - 工作区 (<workspaceDir>/skills/)      │
└─────────────────────────────────────────────────────────┘

skills/
├── github/         # GitHub CLI 集成
├── discord/        # Discord Bot 控制
├── coding-agent/   # 编码代理指南
├── 1password/      # 1Password 密码管理
├── obsidian/       # Obsidian 笔记
├── spotify-player/ # Spotify 播放控制
├── weather/        # 天气查询
├── docker/         # Docker 容器管理
├── kubernetes/     # K8s 集群管理
├── homebrew/       # Homebrew 包管理
└── ...

---
name: github
description: "Interact with GitHub using the `gh` CLI..."
metadata:
  {
    "openclaw":
      {
        "emoji": "🐙",
        "requires": { "bins": ["gh"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gh",
              "bins": ["gh"],
              "label": "Install GitHub CLI (brew)",
            },
          ],
      },
  }
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub...

## Pull Requests
```bash
gh pr checks 55 --repo owner/repo

**Frontmatter 字段说明**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | Skill 唯一标识符 |
| `description` | string | 简短描述（用于匹配） |
| `metadata.openclaw.emoji` | string | 显示图标 |
| `metadata.openclaw.os` | string[] | 限制操作系统 |
| `metadata.openclaw.requires.bins` | string[] | 必需的二进制文件 |
| `metadata.openclaw.requires.anyBins` | string[] | 任一即可的二进制 |
| `metadata.openclaw.requires.env` | string[] | 必需的环境变量 |
| `metadata.openclaw.requires.config` | string[] | 必需的配置路径 |
| `metadata.openclaw.install` | object[] | 安装选项 |
| `metadata.openclaw.always` | boolean | 始终包含（跳过检查） |

### 6.3 Skills 加载流程

**文件**: `src/agents/skills/workspace.ts`

```typescript
function loadSkillEntries(
  workspaceDir: string,
  opts?: {
    config?: OpenClawConfig;
    managedSkillsDir?: string;
    bundledSkillsDir?: string;
  },
): SkillEntry[] {
  const loadSkills = (params: { dir: string; source: string }): Skill[] => {
    const loaded = loadSkillsFromDir(params);  // 使用 pi-coding-agent
    // ...
  };

  // 1. 解析各目录路径
  const managedSkillsDir = opts?.managedSkillsDir ?? path.join(CONFIG_DIR, "skills");
  const workspaceSkillsDir = path.join(workspaceDir, "skills");
  const bundledSkillsDir = opts?.bundledSkillsDir ?? resolveBundledSkillsDir();
  const extraDirs = opts?.config?.skills?.load?.extraDirs ?? [];
  const pluginSkillDirs = resolvePluginSkillDirs({...});

  // 2. 从各目录加载
  const bundledSkills = loadSkills({ dir: bundledSkillsDir, source: "openclaw-bundled" });
  const extraSkills = mergedExtraDirs.flatMap(dir => loadSkills({...}));
  const managedSkills = loadSkills({ dir: managedSkillsDir, source: "openclaw-managed" });
  const workspaceSkills = loadSkills({ dir: workspaceSkillsDir, source: "openclaw-workspace" });

  // 3. 按优先级合并（后覆盖前）
  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);
  for (const skill of managedSkills) merged.set(skill.name, skill);
  for (const skill of workspaceSkills) merged.set(skill.name, skill);

  // 4. 解析 frontmatter 和元数据
  return Array.from(merged.values()).map(skill => ({
    skill,
    frontmatter: parseFrontmatter(raw),
    metadata: resolveOpenClawMetadata(frontmatter),
    invocation: resolveSkillInvocationPolicy(frontmatter),
  }));
}