@a2hmarket/a2hmarket 0.2.0

package/plugin-mechanism-report.md

@@ -0,0 +1,1323 @@
+# OpenClaw Plugin 机制深度研究报告
+
+> 生成日期：2026-03-24
+> 基于 `main` 分支 commit `17c1ee7716` 的代码分析
+
+---
+
+## 目录
+
+- [一、通信机制](#一通信机制)
+  - [1.1 架构总览](#11-架构总览)
+  - [1.2 消息入站流程](#12-消息入站流程)
+  - [1.3 访问控制前置检查](#13-访问控制前置检查)
+  - [1.4 消息上下文构建](#14-消息上下文构建)
+  - [1.5 路由解析与派发](#15-路由解析与派发)
+  - [1.6 出站投递与跨 Channel 转发](#16-出站投递与跨-channel-转发)
+  - [1.7 核心通信 API 参考](#17-核心通信-api-参考)
+  - [1.8 消息缓存与去重](#18-消息缓存与去重)
+- [二、Plugin SDK 能力全景](#二plugin-sdk-能力全景)
+  - [2.1 Plugin 注册入口](#21-plugin-注册入口)
+  - [2.2 可实现的 Plugin 类型](#22-可实现的-plugin-类型)
+  - [2.3 Hook 生命周期事件](#23-hook-生命周期事件)
+  - [2.4 SDK 工具库](#24-sdk-工具库)
+  - [2.5 Plugin 清单格式](#25-plugin-清单格式)
+  - [2.6 导入边界规则](#26-导入边界规则)
+  - [2.7 二次开发路径指南](#27-二次开发路径指南)
+- [三、Skill 运行机制与记忆系统](#三skill-运行机制与记忆系统)
+  - [3.1 Skill 定义格式](#31-skill-定义格式)
+  - [3.2 发现与加载管线](#32-发现与加载管线)
+  - [3.3 运行时执行流程](#33-运行时执行流程)
+  - [3.4 Skill 快照与缓存](#34-skill-快照与缓存)
+  - [3.5 记忆与持久化系统](#35-记忆与持久化系统)
+  - [3.6 调试 Skill 的方法](#36-调试-skill-的方法)
+  - [3.7 安全限制与保护机制](#37-安全限制与保护机制)
+- [四、关键源码索引](#四关键源码索引)
+
+---
+
+## 一、通信机制
+
+### 1.1 架构总览
+
+OpenClaw 的 Plugin 通信架构是**同进程、回调驱动**的设计。Plugin 与 Core 运行在同一个 Node.js 进程中，不存在 IPC 或跨进程通信。通信通过三种方式实现：
+
+| 通信方式 | 方向 | 说明 |
+|----------|------|------|
+| **Webhook HTTP POST** | 外部 → Plugin | 外部平台（如 BlueBubbles Server）向 Gateway 发送 webhook |
+| **函数调用** | Plugin → Core | Plugin 调用 `core.channel.reply.*`、`core.channel.routing.*` 等 SDK 方法 |
+| **回调函数** | Core → Plugin | Core 通过 Plugin 注册的 `deliver()` 回调将回复交还给 Plugin |
+
+**端到端消息流向图：**
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                     外部平台 (Telegram / Discord / ...)                   │
+└────────────┬─────────────────────────────────────────────────┬───────────┘
+             │ HTTP Webhook POST                               ▲
+             ▼                                                 │ 原生 API 发送
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          PLUGIN 层                                       │
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  ┌─────────────┐ │
+│  │ 认证 & 解析  │→│ 访问控制检查  │→│ 上下文构建     │→│ deliver()   │ │
+│  │ (webhook)   │  │ (allowlist)  │  │ (envelope)    │  │ (回调发送)  │ │
+│  └─────────────┘  └──────────────┘  └───────────────┘  └─────────────┘ │
+└────────────────────────────┬─────────────────────────────────▲──────────┘
+                             │ dispatchReply...()              │ deliver()
+                             ▼                                 │
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          CORE 层                                         │
+│  ┌──────────────┐  ┌───────────────┐  ┌──────────────┐  ┌───────────┐  │
+│  │ 路由解析      │→│ Session 记录   │→│ Agent 推理    │→│ Reply 管线 │  │
+│  │ (agentRoute) │  │ (store)       │  │ (LLM 调用)   │  │ (stream)  │  │
+│  └──────────────┘  └───────────────┘  └──────────────┘  └───────────┘  │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 消息入站流程
+
+以 BlueBubbles Plugin (`extensions/bluebubbles/`) 为例，完整流程分为六个阶段：
+
+#### 阶段 1：Webhook 接收与认证
+
+```typescript
+// extensions/bluebubbles/src/monitor.ts
+registerBlueBubblesWebhookTarget(target: WebhookTarget)
+```
+
+- Gateway 在注册的路径上监听 HTTP POST 请求
+- 使用 `timingSafeEqual` 进行常量时间认证（防止时序攻击）
+- 支持 JSON 和 URL-encoded 两种 payload 格式
+- 认证方式为 "plugin" auth mode（Plugin 特有的 webhook 路由）
+
+#### 阶段 2：消息标准化
+
+```typescript
+// extensions/bluebubbles/src/monitor.ts
+parseBlueBubblesWebhookPayload()    // 解析原始 payload
+normalizeWebhookMessage()            // 标准化为 NormalizedWebhookMessage
+normalizeWebhookReaction()           // 处理表情回应
+```
+
+每个 Channel Plugin 负责将平台特定的消息格式转换为统一的 `NormalizedWebhookMessage` 结构。
+
+#### 阶段 3：访问控制（详见 1.3）
+
+#### 阶段 4：上下文构建（详见 1.4）
+
+#### 阶段 5：路由解析（详见 1.5）
+
+#### 阶段 6：派发到 Core Reply Engine
+
+```typescript
+// extensions/bluebubbles/src/monitor-processing.ts (lines 1264-1450+)
+await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+  ctx: ctxPayload,           // 构建好的消息上下文
+  cfg: config,               // OpenClaw 配置
+  dispatcherOptions: {
+    ...replyPipeline,        // typing indicator + send handler
+    deliver: async (payload, info) => {
+      // Plugin 自定义的投递函数
+      await sendBlueBubblesMedia(...) // 或
+      await sendMessageBlueBubbles(...)
+    }
+  }
+});
+```
+
+Core Reply Engine 处理流程：
+1. `recordInboundSession()` — 写入 session store
+2. `dispatchReplyFromConfig()` — Agent 处理消息（LLM 推理 + 工具调用）
+3. 流式回复通过 `deliver()` 回调交还给 Plugin
+4. Plugin 通过平台原生 API 发送到终端用户
+
+### 1.3 访问控制前置检查
+
+**关键设计：安全检查在 Plugin 层完成，在消息到达 Core 之前。**
+
+```typescript
+// extensions/bluebubbles/src/monitor-processing.ts:processMessage() (lines 568-696)
+
+// 1. 确定策略
+const dmPolicy = account.config.dmPolicy ?? "pairing";      // DM 默认需要配对
+const groupPolicy = account.config.groupPolicy ?? "allowlist"; // 群组默认走白名单
+
+// 2. 执行访问判断
+const accessDecision = resolveDmGroupAccessWithLists({
+  isGroup,
+  dmPolicy,           // "open" | "pairing" | "allowlist" | "block"
+  groupPolicy,        // "open" | "allowlist" | "block"
+  allowFrom,          // 配置的白名单
+  storeAllowFrom,     // 动态存储的白名单
+  isSenderAllowed: (allowFrom) => isAllowedBlueBubblesSender({...})
+});
+
+// 3. 根据判断结果处理
+switch (accessDecision.decision) {
+  case "allow":   break;                           // 继续处理
+  case "block":   return;                          // 静默丢弃
+  case "pairing": await issuePairingChallenge();   // 发起配对挑战
+}
+```
+
+**访问策略矩阵：**
+
+| 场景 | DM Policy | Group Policy | 行为 |
+|------|-----------|-------------|------|
+| 私信，白名单内 | `allowlist` | — | 允许 |
+| 私信，白名单外 | `allowlist` | — | 阻止 |
+| 私信，任意 | `open` | — | 允许 |
+| 私信，需配对 | `pairing` | — | 发起配对挑战 |
+| 群组，白名单内 | — | `allowlist` | 允许（可能还需要 @mention） |
+| 群组，白名单外 | — | `allowlist` | 阻止 |
+| 群组，任意 | — | `open` | 允许 |
+
+群组消息还有额外的 **Mention Gating**（`core.channel.groups.resolveRequireMention()`），即使通过白名单也可能需要 @mention 才响应。
+
+### 1.4 消息上下文构建
+
+Plugin 负责构建完整的消息上下文，供 Core 的 Agent 使用：
+
+```typescript
+// extensions/bluebubbles/src/monitor-processing.ts (lines 1159-1197)
+const ctxPayload = core.channel.reply.finalizeInboundContext({
+  // === 消息本体 ===
+  Body: body,                          // 带信封格式的消息（含元数据）
+  BodyForAgent: rawBody,               // 纯文本（供 Agent 直接读取）
+
+  // === 路由信息 ===
+  From: `bluebubbles:${message.senderId}`,
+  To: `bluebubbles:${outboundTarget}`,
+  SessionKey: route.sessionKey,
+
+  // === 聊天类型 ===
+  ChatType: isGroup ? "group" : "direct",
+
+  // === 回复上下文 ===
+  ReplyToId,                           // 被回复消息的 ID
+  ReplyToBody,                         // 被回复消息的内容
+  ReplyToSender,                       // 被回复消息的发送者
+
+  // === 群组信息 ===
+  GroupMembers,                        // 群成员列表
+  GroupSubject,                        // 群名称/主题
+
+  // === 附件 ===
+  // 下载附件并保存到 media buffer
+  // 支持图片、视频、音频、文档
+});
+```
+
+**消息信封格式**会包含 channel 元数据、时间戳等，让 Agent 能理解消息来源。
+
+### 1.5 路由解析与派发
+
+```typescript
+// 路由解析
+const route = core.channel.routing.resolveAgentRoute({
+  channel: "bluebubbles",
+  peer: { kind: "direct" | "group", id: peerId },
+  accountId,
+  config
+});
+
+// 返回值
+{
+  agentId: string,          // 目标 Agent ID
+  sessionKey: string,       // 会话键（决定对话上下文隔离）
+  mainSessionKey: string,   // 主会话键
+  matchedBy: string         // 匹配方式（路由规则 / 默认）
+}
+```
+
+路由规则在 OpenClaw 配置中定义，支持：
+- 按 channel + peer 精确匹配
+- 按 channel 通配
+- 按 Agent ID 指定
+- 默认 Agent 回退
+
+### 1.6 出站投递与跨 Channel 转发
+
+#### 同 Channel 回复
+
+最常见的场景：消息从哪个 Channel 进来，就从哪个 Channel 回复。回复通过 Plugin 注册的 `deliver()` 回调完成。
+
+#### 跨 Channel 转发
+
+当 Agent 使用 `message.send()` 工具并指定不同的 `channel` 参数时，触发跨 Channel 路由：
+
+```typescript
+// src/infra/outbound/channel-selection.ts
+const { channel, source } = await resolveMessageChannelSelection({
+  cfg: config,
+  channel: "telegram",          // 显式指定目标 channel
+  fallbackChannel: null
+});
+
+// 优先级：显式指定 > 工具上下文推断 > 唯一已配置 channel
+```
+
+**跨 Channel 投递管线：**
+
+```typescript
+// src/infra/outbound/message.ts
+async function sendMessage(params) {
+  // 1. 解析目标 channel
+  const selection = await resolveMessageChannelSelection(params);
+
+  // 2. 获取目标 channel 的 Plugin
+  const plugin = await resolveOutboundChannelPlugin(selection.channel);
+
+  // 3. 标准化投递 payload
+  const payloads = normalizeReplyPayloadsForDelivery(message, media);
+
+  // 4. 执行投递
+  await deliverOutboundPayloads(plugin, payloads);
+}
+```
+
+**具体示例：**
+
+```
+BlueBubbles 收到消息 "帮我发个 Telegram 消息给 Alice"
+  → Agent 推理后调用 message.send({ channel: "telegram", to: "alice", body: "..." })
+  → resolveMessageChannelSelection() 选择 Telegram Plugin
+  → resolveOutboundChannelPlugin("telegram") 获取 Telegram adapter
+  → Telegram Plugin.outbound.sendText({ to: "alice", body: "..." })
+  → Telegram Bot API 发送消息
+```
+
+### 1.7 核心通信 API 参考
+
+#### Plugin → Core（入站方向）
+
+| API | 源文件 | 用途 |
+|-----|--------|------|
+| `core.channel.routing.resolveAgentRoute()` | `src/plugin-sdk/resolve-route` | 将消息路由到指定 Agent |
+| `core.channel.reply.dispatchReplyWithBufferedBlockDispatcher()` | `src/channels/reply/provider-dispatcher` | 通过 Reply 管线派发消息 |
+| `core.channel.reply.finalizeInboundContext()` | `src/auto-reply/templating` | 构建标准化消息上下文 |
+| `core.channel.session.recordInboundSession()` | `src/channels/session` | 记录会话历史 |
+| `core.channel.mentions.buildMentionRegexes()` | `src/channels/mention-gating` | 构建 @mention 匹配规则 |
+| `core.channel.groups.resolveRequireMention()` | `src/channels/plugins/group-policy` | 判断群组是否需要 @mention |
+| `core.system.enqueueSystemEvent()` | `src/system` | 记录系统级事件 |
+
+#### Core → Channel（出站方向）
+
+| API | 源文件 | 用途 |
+|-----|--------|------|
+| `resolveMessageChannelSelection()` | `src/infra/outbound/channel-selection.ts` | 选择目标 channel |
+| `resolveOutboundChannelPlugin()` | `src/infra/outbound/channel-resolution.ts` | 获取 channel adapter |
+| `deliverOutboundPayloads()` | `src/infra/outbound/deliver.ts` | 执行出站投递 |
+| `sendMessage()` / `sendMedia()` / `sendPoll()` | `src/infra/outbound/message.ts` | 高级发送接口 |
+
+### 1.8 消息缓存与去重
+
+Plugin 内部维护多级缓存以确保消息正确性：
+
+| 缓存类型 | 用途 |
+|----------|------|
+| **Reply Cache** | 缓存消息 ID，用于解析回复引用关系 |
+| **Self-Chat Cache** | 检测并去重 Plugin 自身发出的消息（防止回环） |
+| **Pending Outbound** | 追踪已发出的消息 ID，用于回声检测 |
+| **History Buffer** | 滚动的内存消息历史，支持 API 回填重试 |
+| **Debounce Registry** | `createBlueBubblesDebounceRegistry()` — 防止重复处理 |
+| **Channel Inbound Debouncer** | `createChannelInboundDebouncer()` — 每 channel 去抖策略 |
+
+---
+
+## 二、Plugin SDK 能力全景
+
+### 2.1 Plugin 注册入口
+
+每个 Plugin 通过导出一个入口定义来注册：
+
+```typescript
+// 非 Channel Plugin（Provider / Tool / Service 等）
+import { definePluginEntry } from "openclaw/plugin-sdk/core";
+
+export default definePluginEntry({
+  id: "my-provider",
+  name: "My Provider",
+  description: "A custom LLM provider",
+  kind: "memory",                       // 可选：排他性插槽
+  configSchema: { /* JSON Schema */ },   // 或 () => schema（延迟加载）
+
+  register: (api: OpenClawPluginApi) => {
+    // 在这里注册各种能力
+  }
+});
+
+// Channel Plugin（包含 channel 能力的完整接线）
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+
+export default defineChannelPluginEntry({
+  id: "my-channel",
+  name: "My Channel",
+  // ... channel 特有的配置
+});
+```
+
+`api: OpenClawPluginApi` 提供以下所有注册方法：
+
+```typescript
+interface OpenClawPluginApi {
+  // === Channel & Messaging ===
+  registerChannel(registration: ChannelPlugin)
+
+  // === AI Provider ===
+  registerProvider(provider: ProviderPlugin)
+  registerSpeechProvider(provider: SpeechProviderPlugin)
+  registerMediaUnderstandingProvider(provider: MediaUnderstandingProviderPlugin)
+  registerImageGenerationProvider(provider: ImageGenerationProviderPlugin)
+  registerWebSearchProvider(provider: WebSearchProviderPlugin)
+
+  // === Agent Capabilities ===
+  registerTool(tool: AnyAgentTool | OpenClawPluginToolFactory, opts?)
+  registerCommand(command: OpenClawPluginCommandDefinition)
+  registerContextEngine(id: string, factory: ContextEngineFactory)
+  registerMemoryPromptSection(builder: MemoryPromptSectionBuilder)
+
+  // === Infrastructure ===
+  registerHook(events: string[], handler: InternalHookHandler, opts?)
+  registerHttpRoute(params: OpenClawPluginHttpRouteParams)
+  registerService(service: OpenClawPluginService)
+  registerGatewayMethod(method: string, handler)
+  registerCli(registrar: OpenClawPluginCliRegistrar, opts?)
+
+  // === Event Hooks ===
+  on(hookName: PluginHookName, handler, opts?)
+}
+```
+
+### 2.2 可实现的 Plugin 类型
+
+#### 2.2.1 Channel Plugin（消息渠道）
+
+实现新消息平台的接入（如 Telegram、Discord、Slack、Matrix 等）。
+
+```typescript
+interface ChannelPlugin<Account = any> {
+  id: string;
+  label: string;
+  capabilities: ChannelCapabilities;
+  docsPath?: string;
+
+  // 适配器接口
+  config: ChannelConfigAdapter<Account>;         // 账户配置解析
+  outbound: ChannelOutboundAdapter<Account>;     // 消息发送
+  security: ChannelSecurityAdapter<Account>;     // 白名单 & DM 策略
+  pairing: ChannelPairingAdapter<Account>;       // 配对认证
+  status: ChannelStatusAdapter<Account>;         // 健康检查 & 探针
+}
+```
+
+**参考实现：** `extensions/bluebubbles/src/channel.ts`, `extensions/twitch/src/plugin.ts`, `extensions/matrix/`
+
+#### 2.2.2 Provider Plugin（LLM 推理提供者）
+
+接入新的 LLM 模型服务。
+
+```typescript
+interface ProviderPlugin {
+  id: string;
+  label: string;
+  auth: ProviderAuthMethod[];                    // 认证方式（API Key / OAuth）
+
+  catalog: {
+    run: (ctx) => Promise<ModelCatalogEntry[]>;  // 模型目录发现
+  };
+
+  // 运行时钩子
+  prepareRuntimeAuth?: (ctx) => Promise<AuthResult>;
+  augmentModelCatalog?: (ctx) => Promise<ModelEntry[]>;
+  resolveUsageAuth?: (ctx) => Promise<UsageAuth>;
+}
+```
+
+**参考实现：** `extensions/moonshot/`, `extensions/openai/`（如存在）
+
+#### 2.2.3 Speech Provider（语音合成）
+
+```typescript
+interface SpeechProviderPlugin {
+  id: string;
+  label: string;
+  listVoices: () => Promise<Voice[]>;
+  synthesize: (text: string, voice: Voice, opts?) => Promise<AudioBuffer>;
+}
+```
+
+#### 2.2.4 Image Generation Provider（图像生成）
+
+```typescript
+interface ImageGenerationProvider {
+  id: string;
+  label: string;
+  generate: (prompt: string, params: ImageGenParams) => Promise<ImageResult>;
+}
+```
+
+#### 2.2.5 Web Search Provider（网页搜索）
+
+```typescript
+interface WebSearchProviderPlugin {
+  id: string;
+  label: string;
+  search: (query: string, opts?) => Promise<SearchResult[]>;
+}
+```
+
+#### 2.2.6 Memory Plugin（记忆/向量检索）
+
+```typescript
+// 排他性插槽 — 同时只能有一个活跃
+{
+  kind: "memory",
+  // 方法：capture（记忆写入）、recall（记忆召回）、maintenance（维护）
+}
+```
+
+**参考实现：** `extensions/memory-lancedb/`
+
+#### 2.2.7 Context Engine（上下文引擎）
+
+```typescript
+// 排他性插槽 — 同时只能有一个活跃
+{
+  kind: "context-engine",
+  // 自定义 transcript 改写和上下文注入
+}
+```
+
+#### 2.2.8 Tool（Agent 工具）
+
+```typescript
+api.registerTool({
+  name: "my_tool",
+  description: "Tool description for the agent",
+  parameters: { /* JSON Schema */ },
+  execute: async (params, ctx) => {
+    return { result: "..." };
+  }
+});
+
+// 或使用工厂模式动态创建
+api.registerTool((ctx) => ({
+  name: "dynamic_tool",
+  // ...
+}));
+```
+
+#### 2.2.9 Command（CLI 命令）
+
+绕过 LLM Agent 的直接命令执行：
+
+```typescript
+api.registerCommand({
+  name: "my-command",
+  description: "Description",
+  execute: async (args, ctx) => {
+    // 直接执行逻辑，不经过 Agent
+  }
+});
+```
+
+#### 2.2.10 Service（后台服务）
+
+长期运行的后台进程：
+
+```typescript
+api.registerService({
+  id: "my-background-service",
+  start: async (ctx) => { /* 启动逻辑 */ },
+  stop: async () => { /* 停止逻辑 */ }
+});
+```
+
+### 2.3 Hook 生命周期事件
+
+OpenClaw 提供了覆盖 Agent 全生命周期的 Hook 事件：
+
+#### 模型与提示词
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `before_model_resolve` | 模型选择前 | 覆盖模型/Provider 选择 |
+| `before_prompt_build` | System Prompt 构建前 | 注入自定义系统提示 |
+| `before_agent_start` | Agent 启动前 | 最终的前置修改 |
+
+```typescript
+// 示例：覆盖模型选择
+api.on('before_model_resolve', (ctx, event) => {
+  return {
+    modelOverride: 'claude-opus-4.6',
+    providerOverride: 'anthropic'
+  };
+}, { priority: 100 });
+```
+
+#### 执行过程
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `llm_input` | 发送到模型前 | 拦截/修改输入 |
+| `llm_output` | 模型返回后 | 拦截/修改输出 |
+| `agent_end` | Agent 运行结束 | 后处理、统计 |
+
+#### 会话管理
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `session_start` | 新会话开始 | 初始化会话状态 |
+| `session_end` | 会话结束 | 清理、归档 |
+| `before_compaction` | Transcript 压缩前 | 保留关键信息 |
+| `after_compaction` | 压缩完成后 | 后处理 |
+| `before_reset` | 会话重置前 | 保存状态 |
+
+#### 消息处理
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `inbound_claim` | 入站消息到达 | 路由/抢占消息 |
+| `message_received` | 消息已接收 | 日志、分析 |
+| `message_sending` | 消息即将发送 | 修改发送内容 |
+| `message_sent` | 消息已发送 | 确认、回执 |
+| `before_message_write` | 写入历史前 | 过滤、转换 |
+
+#### 工具调用
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `before_tool_call` | 工具执行前 | 拦截、授权检查 |
+| `after_tool_call` | 工具执行后 | 结果修改、审计 |
+| `tool_result_persist` | 结果持久化前 | 转换存储格式 |
+
+#### 子代理
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `subagent_spawning` | 子代理生成前 | 修改配置 |
+| `subagent_delivery_target` | 确定投递目标 | 路由子代理输出 |
+| `subagent_spawned` | 子代理已创建 | 追踪 |
+| `subagent_ended` | 子代理结束 | 收集结果 |
+
+#### 网关
+
+| 事件 | 触发时机 | 典型用途 |
+|------|----------|----------|
+| `gateway_start` | Gateway 启动 | 初始化全局资源 |
+| `gateway_stop` | Gateway 停止 | 清理 |
+
+### 2.4 SDK 工具库
+
+SDK 通过 160+ 子路径导出，以下按功能分类列举核心模块：
+
+#### 配置与存储
+
+| 模块路径 | 核心导出 | 用途 |
+|----------|----------|------|
+| `openclaw/plugin-sdk/config-runtime` | `loadConfig()`, `writeConfigFile()` | 配置读写 |
+| `openclaw/plugin-sdk/runtime-store` | `createPluginRuntimeStore<T>()` | Plugin 作用域的运行时状态 |
+| `openclaw/plugin-sdk/json-store` | `readJsonFileWithFallback()`, `writeJsonFileAtomically()` | JSON 文件持久化 |
+| `openclaw/plugin-sdk/runtime-env` | 运行时环境变量 | 环境探测 |
+
+#### 认证
+
+| 模块路径 | 核心导出 | 用途 |
+|----------|----------|------|
+| `openclaw/plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod()` | API Key 认证流程 |
+| `openclaw/plugin-sdk/provider-auth` | `buildOauthProviderAuthResult()` | OAuth 认证处理 |
+| `openclaw/plugin-sdk/provider-auth` | `resolveApiKeyForProvider()` | 凭据解析 |
+| `openclaw/plugin-sdk/provider-auth` | `ensureAuthProfileStore()` | 认证 Profile 管理 |
+
+#### 日志与文本
+
+| 模块路径 | 核心导出 | 用途 |
+|----------|----------|------|
+| `openclaw/plugin-sdk/text-runtime` | `PluginLogger` (info/warn/error/debug) | 结构化日志 |
+| `openclaw/plugin-sdk/text-runtime` | Markdown 渲染、文本格式化 | 内容处理 |
+| `openclaw/plugin-sdk/runtime` | `createLoggerBackedRuntime()` | 日志运行时适配 |
+
+#### Channel 工具
+
+| 模块路径 | 核心导出 | 用途 |
+|----------|----------|------|
+| `openclaw/plugin-sdk/channel-pairing` | `createTextPairingAdapter()` | 配对流程帮助器 |
+| `openclaw/plugin-sdk/channel-status` | `describeAccountSnapshot()` | 账户状态描述 |
+| `openclaw/plugin-sdk/channel-lifecycle` | `runPassiveAccountLifecycle()` | 生命周期管理 |
+| `openclaw/plugin-sdk/channel-inbound` | 入站消息解析 & 派发 | 消息处理 |
+| `openclaw/plugin-sdk/channel-config-*` | 配置 schema & 帮助器 | 配置管理 |
+| `openclaw/plugin-sdk/direct-dm` | DM 访问控制 | 安全 |
+| `openclaw/plugin-sdk/security-runtime` | DM 策略、信任逻辑 | 安全 |
+
+#### Agent & 模型
+
+| 模块路径 | 核心导出 | 用途 |
+|----------|----------|------|
+| `openclaw/plugin-sdk/agent-runtime` | Agent/模型帮助器 | Agent 操作 |
+| `openclaw/plugin-sdk/provider-catalog` | 模型目录发现 | Provider 集成 |
+| `openclaw/plugin-sdk/provider-models` | 运行时模型处理 | 模型操作 |
+| `openclaw/plugin-sdk/speech` | TTS/语音合成帮助器 | 语音 |
+
+#### 基础设施
+
+| 模块路径 | 核心导出 | 用途 |
+|----------|----------|------|
+| `openclaw/plugin-sdk/gateway-runtime` | Gateway/服务器上下文 | 基础设施 |
+| `openclaw/plugin-sdk/cli-runtime` | CLI 命令注册 | CLI 扩展 |
+| `openclaw/plugin-sdk/ssrf-runtime` | SSRF 策略 | 安全 |
+| `openclaw/plugin-sdk/hook-runtime` | 内部 Hook 基础设施 | 事件系统 |
+| `openclaw/plugin-sdk/infra-runtime` | 基础设施工具 | 通用 |
+
+#### 通用工具
+
+| 功能 | 函数/类型 | 用途 |
+|------|-----------|------|
+| Promise 延迟 | `createDeferred<T>()` | 异步控制流 |
+| 信号等待 | `waitUntilAbort()` | AbortSignal 处理 |
+| HTTP 服务 | `keepHttpServerTaskAlive()` | 服务器生命周期 |
+| 安全正则 | Safe regex utilities | 防 ReDoS |
+| Web 请求 | `fetch` wrappers + SSRF guard | 安全 HTTP 请求 |
+
+### 2.5 Plugin 清单格式
+
+每个 Plugin 根目录的 `openclaw.plugin.json`：
+
+```jsonc
+{
+  // === 必填 ===
+  "id": "my-plugin",                            // 全局唯一标识
+  "configSchema": {                              // JSON Schema 格式
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": { "type": "string" },
+      "model": { "type": "string", "default": "gpt-5.4" }
+    },
+    "required": ["apiKey"]
+  },
+
+  // === 可选：类型 ===
+  "kind": "memory",                              // 或 "context-engine"（排他性插槽）
+
+  // === 可选：能力声明 ===
+  "channels": ["my-channel"],                    // 提供的 Channel ID 列表
+  "providers": ["my-provider"],                  // 提供的 Provider ID 列表
+  "skills": ["my-skill"],                        // 关联的 Skill 列表
+
+  // === 可选：认证 ===
+  "providerAuthEnvVars": {
+    "my-provider": ["MY_API_KEY", "MY_ORG_ID"]
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "my-provider",
+      "method": "api-key",
+      "choiceId": "my-api-key",
+      "choiceLabel": "My API Key",
+      "groupId": "my-group",
+      "groupLabel": "My Service",
+      "optionKey": "apiKey",
+      "cliFlag": "--api-key",
+      "cliOption": "--api-key <key>",
+      "cliDescription": "API key for My Service",
+      "onboardingScopes": ["text-inference"]
+    }
+  ],
+
+  // === 可选：UI ===
+  "uiHints": {
+    "apiKey": {
+      "label": "API Key",
+      "sensitive": true,                         // 输入时遮蔽
+      "placeholder": "sk-...",
+      "help": "Your API key",
+      "advanced": false                          // true 则默认折叠
+    }
+  },
+
+  // === 可选：元数据 ===
+  "name": "My Plugin",
+  "description": "Plugin description",
+  "version": "1.0.0",
+  "enabledByDefault": true
+}
+```
+
+### 2.6 导入边界规则
+
+```
+✅ 允许的导入路径：
+   import { ... } from "openclaw/plugin-sdk/<subpath>"
+   import { ... } from "./api"           // 本地 barrel
+   import { ... } from "./runtime-api"   // 本地 barrel
+
+❌ 禁止的导入路径：
+   import { ... } from "../../src/**"                    // 不得引用 Core 内部
+   import { ... } from "../../src/plugin-sdk-internal/**" // 不得引用 SDK 内部实现
+   import { ... } from "../other-extension/src/**"       // 不得跨 extension 引用
+   import { ... } from "openclaw/plugin-sdk/my-extension" // 不得在 extension 内自引用
+```
+
+### 2.7 二次开发路径指南
+
+| 开发目标 | 注册方式 | 需要实现的接口 | 参考实现 |
+|----------|----------|---------------|----------|
+| 接入新消息平台 | `api.registerChannel()` | outbound / inbound / pairing / status / config / security adapter | `extensions/bluebubbles/`, `extensions/twitch/` |
+| 接入新 LLM | `api.registerProvider()` | auth / catalog / runtime hooks | `extensions/moonshot/` |
+| 添加 Agent 工具 | `api.registerTool()` | name / description / parameters / execute | SDK 工具定义 |
+| 消息拦截/修改 | `api.on('message_received')` | hook handler | — |
+| 覆盖模型选择 | `api.on('before_model_resolve')` | hook handler returning override | — |
+| 注入系统提示 | `api.on('before_prompt_build')` | hook handler | — |
+| 自定义记忆后端 | `kind: "memory"` | capture / recall / maintenance | `extensions/memory-lancedb/` |
+| 添加后台任务 | `api.registerService()` | start / stop | — |
+| 扩展 CLI | `api.registerCli()` | CLI registrar | — |
+| 添加 HTTP 端点 | `api.registerHttpRoute()` | route handler | — |
+| 自定义语音 | `api.registerSpeechProvider()` | listVoices / synthesize | — |
+| 自定义搜索 | `api.registerWebSearchProvider()` | search | `extensions/moonshot/` |
+
+---
+
+## 三、Skill 运行机制与记忆系统
+
+### 3.1 Skill 定义格式
+
+Skill 是 **Markdown 文件 + YAML frontmatter** 的组合，不是可执行代码。Skill 的"执行"本质上是**提示注入** — 其内容被注入到 Agent 的系统提示中，Agent "阅读并遵循"指令。
+
+#### 文件结构
+
+```
+.agents/skills/
+  └── my-skill/
+      └── SKILL.md
+```
+
+#### SKILL.md 格式
+
+```markdown
+---
+# === 基础字段 ===
+name: my-skill                              # 必填：技能标识
+description: Does something useful           # 必填：描述（用于判断是否适用）
+user-invocable: true                         # 可选：用户能否直接调用（默认 true）
+disable-model-invocation: false              # 可选：禁止模型主动调用（默认 false）
+
+# === 命令派发（可选）===
+command-dispatch: tool                       # 派发到工具
+command-tool: my_tool_name                   # 目标工具名
+command-arg-mode: raw                        # 参数传递模式
+
+# === OpenClaw 特有元数据（可选）===
+openclaw:
+  always: false                              # 始终加载，不检查可用性
+  skillKey: my-skill                         # 配置查找的替代键
+  primaryEnv: MY_API_KEY                     # 主要环境变量
+  emoji: "🔧"                               # 视觉标识
+  homepage: https://example.com              # 文档链接
+
+  # 运行平台限制
+  os: [darwin, linux, win32]
+
+  # 依赖声明
+  requires:
+    bins: [my-binary]                        # 必须全部存在
+    anyBins: [binary-a, binary-b]            # 至少一个存在
+    env: [MY_API_KEY, MY_SECRET]             # 必须的环境变量
+    config: [some.config.path]               # 必须的配置路径
+
+  # 安装方式
+  install:
+    - kind: brew
+      formula: my-binary
+    - kind: node
+      package: my-npm-package
+    - kind: go
+      module: github.com/user/repo
+    - kind: uv
+      package: my-python-package
+    - kind: download
+      url: https://example.com/binary
+      extract: true
+---
+
+# Skill 内容
+
+这里是 Agent 将阅读和遵循的指令。支持完整的 Markdown 格式。
+
+## 步骤
+1. 首先做 X
+2. 然后做 Y
+3. 最后做 Z
+
+## 注意事项
+- 不要做 A
+- 始终确认 B
+```
+
+### 3.2 发现与加载管线
+
+#### 发现优先级
+
+Skill 从多个目录加载，**后者覆盖前者**：
+
+```
+优先级 1 (最低)：extensions/**/skills/         ← Plugin 提供的 Skill
+优先级 2：       内置 bundled skills             ← OpenClaw 自带的
+优先级 3：       ~/.openclaw/skills/             ← 全局安装的
+优先级 4：       ~/.agents/skills/               ← 个人 Agent 级
+优先级 5：       <workspace>/.agents/skills/     ← 项目级（本仓库使用此级）
+优先级 6 (最高)：<workspace>/skills/             ← 工作区级
+额外：          config skills.load.extraDirs     ← 配置中指定的额外目录
+```
+
+**同名 Skill 的合并规则：** 高优先级来源的同名 Skill 完全覆盖低优先级的。
+
+#### 加载管线
+
+核心实现位于 `src/agents/skills/workspace.ts` — `loadSkillEntries()`：
+
+```
+1. 目录扫描
+   ├── 遍历所有配置的 skill root 目录
+   ├── 自动检测嵌套的 skills/ 子目录
+   ├── 执行大小限制（默认 256KB/SKILL.md）
+   └── 验证符号链接的包含性（防止目录逃逸）
+
+2. Frontmatter 解析
+   ├── parseFrontmatter()（src/agents/skills/frontmatter.ts）
+   ├── 解析 YAML frontmatter（--- 分隔）
+   ├── 类型验证各字段
+   └── 清理包名、formula、URL、路径
+
+3. 合并去重
+   ├── 按名称分组
+   ├── 按优先级覆盖
+   └── 输出最终的 SkillEntry[]
+```
+
+#### 核心类型定义
+
+```typescript
+type SkillEntry = {
+  skill: Skill;                              // 底层 Skill 对象
+  frontmatter: ParsedSkillFrontmatter;       // 原始解析的 YAML
+  metadata?: OpenClawSkillMetadata;          // 解析验证后的 OpenClaw 元数据
+  invocation?: SkillInvocationPolicy;        // 用户/模型调用资格
+};
+```
+
+### 3.3 运行时执行流程
+
+```
+Session Start
+  │
+  ▼
+resolveEmbeddedRunSkillEntries()              ← 加载所有 SkillEntry
+  │
+  ▼
+shouldIncludeSkill()                          ← 逐个过滤
+  ├── 检查 OS 兼容性
+  ├── 检查二进制可用性
+  ├── 验证环境变量
+  ├── 检查配置路径
+  ├── 应用 allowlist/denylist
+  └── 应用 skill 级别的 disable 标志
+  │
+  ▼
+buildWorkspaceSkillSnapshot()                 ← 构建快照
+  │
+  ▼
+buildWorkspaceSkillsPrompt()                  ← 渲染 Markdown 目录
+  ├── compactSkillPaths()                     ← 压缩路径（~/... 代替完整路径）
+  ├── 字符预算：默认 30,000 字符
+  ├── 数量限制：默认 150 个 Skill
+  ├── 全量格式：name + description
+  ├── 紧凑格式：name + location（超预算时降级）
+  └── 截断警告（如果需要）
+  │
+  ▼
+buildSkillsSection()                          ← 注入 System Prompt
+  │
+  ▼
+注入为 System Prompt 的一部分：
+
+  ## Skills (mandatory)
+  Before replying: scan <available_skills> <description> entries.
+  - If exactly one skill clearly applies: read its SKILL.md at <location>
+  - If multiple could apply: choose most specific, then read/follow it
+  - If none clearly apply: do not read any SKILL.md
+
+  <available_skills>
+  - my-skill: Does something useful (at ~/.agents/skills/my-skill/SKILL.md)
+  - another-skill: Another description (at .agents/skills/another/SKILL.md)
+  </available_skills>
+  │
+  ▼
+Agent 根据用户请求，使用 Read 工具读取 SKILL.md
+  │
+  ▼
+Agent 遵循 SKILL.md 中的指令执行任务
+```
+
+**关键理解：Skill 本身不是代码执行。** Skill 是通过 System Prompt 注入的指令模板，Agent 读取后自主遵循。这意味着：
+- Skill 的"执行"完全依赖 Agent 的理解和遵从能力
+- Skill 可以包含任意复杂的指令流程
+- Skill 无法直接调用 API 或执行代码（只能指导 Agent 使用工具）
+
+### 3.4 Skill 快照与缓存
+
+为避免每次 Agent 调用都重新扫描文件系统，Skill 系统使用快照机制：
+
+```typescript
+type SkillSnapshot = {
+  prompt: string;               // 预渲染的 Markdown 目录
+  skills: Array<{
+    name: string;
+    primaryEnv?: string;
+    requiredEnv?: string[];
+  }>;
+  skillFilter?: string[];       // 应用的过滤器
+  resolvedSkills?: Skill[];     // 完整 Skill 对象（供运行时使用）
+  version?: number;             // Schema 版本（迁移用）
+};
+```
+
+快照在 session 开始时构建（`buildWorkspaceSkillSnapshot()`），在同一 session 的所有工具调用中复用。
+
+### 3.5 记忆与持久化系统
+
+#### 架构概览
+
+```
+┌───────────────────────────────────────────────┐
+│              Agent 运行时                       │
+│  ┌─────────────┐    ┌──────────────────────┐  │
+│  │ memory_search│    │ memory_get           │  │
+│  │ (语义搜索)   │    │ (文件读取)            │  │
+│  └──────┬──────┘    └──────────┬───────────┘  │
+└─────────┼──────────────────────┼──────────────┘
+          ▼                      ▼
+┌───────────────────────────────────────────────┐
+│              记忆存储层                         │
+│  ┌─────────────────────────────────────────┐  │
+│  │ MEMORY.md (索引文件)                      │  │
+│  │ memory/*.md (各记忆文件)                   │  │
+│  └─────────────────────────────────────────┘  │
+│  ┌─────────────────────────────────────────┐  │
+│  │ memory.db (SQLite)                       │  │
+│  │  ├── meta      (元数据)                   │  │
+│  │  ├── files     (文件索引)                  │  │
+│  │  ├── chunks    (文本块 + embedding)       │  │
+│  │  ├── embedding_cache (向量缓存)           │  │
+│  │  └── fts5_index (全文搜索索引)            │  │
+│  └─────────────────────────────────────────┘  │
+└───────────────────────────────────────────────┘
+```
+
+#### 存储位置
+
+```
+~/.openclaw/agents/<agentId>/
+  ├── MEMORY.md                 # 记忆索引（Markdown，始终加载到上下文）
+  ├── memory/                   # 记忆内容目录
+  │   ├── user_role.md          # 用户信息记忆
+  │   ├── feedback_testing.md   # 反馈记忆
+  │   └── project_auth.md      # 项目记忆
+  ├── memory.db                 # SQLite 索引数据库
+  └── sessions/                 # 会话日志
+      └── *.jsonl               # JSON Lines 格式
+```
+
+#### SQLite Schema
+
+```sql
+-- 元数据表
+CREATE TABLE meta (
+  key TEXT PRIMARY KEY,
+  value TEXT
+);
+
+-- 文件索引
+CREATE TABLE files (
+  path TEXT PRIMARY KEY,        -- 相对路径
+  source TEXT,                  -- 来源类型
+  hash TEXT,                    -- 内容哈希
+  mtime INTEGER,                -- 修改时间
+  size INTEGER                  -- 文件大小
+);
+
+-- 文本块（含向量嵌入）
+CREATE TABLE chunks (
+  id TEXT,
+  path TEXT,                    -- 所属文件
+  source TEXT,
+  start_line INTEGER,
+  end_line INTEGER,
+  hash TEXT,
+  model TEXT,                   -- 嵌入模型
+  text TEXT,                    -- 原始文本
+  embedding BLOB,               -- 向量嵌入
+  updated_at INTEGER
+);
+
+-- 嵌入缓存（避免重复计算）
+CREATE TABLE embedding_cache (
+  provider TEXT,
+  model TEXT,
+  provider_key TEXT,
+  hash TEXT,
+  embedding BLOB,
+  dims INTEGER,
+  updated_at INTEGER
+);
+
+-- FTS5 全文搜索索引
+CREATE VIRTUAL TABLE fts5_index USING fts5(
+  text,
+  id UNINDEXED,
+  path UNINDEXED,
+  source UNINDEXED,
+  model,
+  start_line,
+  end_line
+);
+```
+
+#### Agent 可用的记忆工具
+
+| 工具名 | 参数 | 返回 |
+|--------|------|------|
+| `memory_search` | `query: string` (语义搜索) | 匹配片段 + 路径 + 行号 + 相关度分数 |
+| `memory_get` | `path: string`, `lines?: range` | 指定文件/行范围的内容 |
+
+**搜索策略：** 先向量语义搜索，再 FTS5 关键词搜索，合并去重排序。
+
+#### 可选后端：qmd (Quantum Markdown)
+
+```typescript
+memory: {
+  backend: "qmd",              // 切换到 qmd 后端
+  qmd: {
+    command: "qmd",            // 外部命令
+    searchMode: "vsearch",     // query | search | vsearch
+    paths: [...],              // 索引路径
+    sessions: {
+      enabled: true,
+      exportDir: "...",
+      retentionDays: 30
+    },
+    update: {
+      interval: "1h",
+      debounceMs: 5000,
+      onBoot: true
+    },
+    limits: {
+      maxResults: 20,
+      maxSnippetChars: 2000,
+      maxInjectedChars: 10000
+    }
+  }
+}
+```
+
+### 3.6 调试 Skill 的方法
+
+#### 步骤 1：检查 Skill 加载状态
+
+```bash
+# 完整状态报告（每个 skill 的详细信息）
+openclaw skills check
+
+# 输出包含：
+# - name, description, source
+# - bundled 状态
+# - 文件路径和根目录
+# - eligible 状态（是否通过所有检查）
+# - 缺失的依赖明细
+# - 可用的安装选项
+# - 配置覆盖
+```
+
+#### 步骤 2：快速状态摘要
+
+```bash
+openclaw skills status
+```
+
+#### 步骤 3：安装缺失依赖
+
+```bash
+openclaw skills install
+```
+
+#### 步骤 4：验证 Frontmatter 语法
+
+直接读取 SKILL.md 文件，检查：
+- YAML 块语法正确（`---` 分隔符）
+- 必填字段（`name`、`description`）存在
+- `openclaw.requires` 中的路径/环境变量拼写正确
+- `openclaw.install` 中的 formula/package 名有效
+
+#### 步骤 5：查看运行时日志
+
+```bash
+# Agent 会话日志（最详细，包含 Agent 的工具调用和推理过程）
+cat ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
+
+# Gateway 日志中的 skill 相关信息
+tail -f ~/.openclaw/gateway.log | grep -i skill
+
+# macOS 统一日志
+./scripts/clawlog.sh
+```
+
+#### 步骤 6：验证 Skill 在 Prompt 中的呈现
+
+通过 Agent 会话日志中的 system prompt 部分，确认：
+- Skill 是否出现在 `<available_skills>` 列表中
+- 描述是否完整（还是被截断为紧凑格式）
+- 路径是否正确
+
+#### 步骤 7：测试记忆系统
+
+```bash
+# 搜索记忆
+openclaw memory search "query terms"
+
+# 读取特定记忆文件
+openclaw memory get "MEMORY.md"
+openclaw memory get "memory/user_role.md"
+```
+
+#### 步骤 8：配置覆盖调试
+
+```typescript
+// 在 OpenClaw 配置中为特定 skill 设置覆盖
+{
+  skills: {
+    "my-skill": {
+      enabled: true,               // 强制启用/禁用
+      env: {
+        MY_API_KEY: "test-key"     // 覆盖环境变量
+      }
+    }
+  }
+}
+```
+
+#### 常见问题排查
+
+| 现象 | 可能原因 | 排查方法 |
+|------|----------|----------|
+| Skill 不出现在列表中 | 目录结构错误 | 确认路径为 `skills/<name>/SKILL.md` |
+| Skill 标记为 ineligible | 依赖不满足 | `openclaw skills check` 查看 missing 部分 |
+| Skill 被截断 | 超出字符/数量预算 | 检查 `skills.limits` 配置 |
+| Agent 不遵循 Skill | 描述不够精准 | 优化 `description` 字段使其更具区分性 |
+| SKILL.md 加载失败 | 文件过大 | 检查是否超过 256KB 限制 |
+| Skill 被覆盖 | 同名 skill 在更高优先级目录 | `openclaw skills check` 查看 source |
+
+### 3.7 安全限制与保护机制
+
+| 限制项 | 默认值 | 配置路径 |
+|--------|--------|----------|
+| 单个 SKILL.md 最大大小 | 256 KB | `skills.limits.maxSkillFileBytes` |
+| 每个根目录最大 skill 数 | 200 | `skills.limits.maxSkillsLoadedPerSource` |
+| 每个根目录最大扫描候选数 | 300 | `skills.limits.maxCandidatesPerRoot` |
+| Prompt 中最大 skill 数 | 150 | `skills.limits.maxSkillsInPrompt` |
+| Prompt 中最大字符数 | 30,000 | `skills.limits.maxSkillsPromptChars` |
+
+**额外安全机制：**
+
+| 机制 | 说明 |
+|------|------|
+| **符号链接包含性检查** | 所有符号链接必须解析到其根目录内 |
+| **路径逃逸检测** | 如果 skill 路径解析到配置根目录外，发出警告 |
+| **目录截断** | 根目录下子目录数量过多时停止扫描 |
+| **Prompt 预算强制** | 使用二分查找将 skill 适配到 token 预算内 |
+| **格式降级** | 超预算时自动从全量格式降级为紧凑格式 |
+| **必填字段验证** | 拒绝缺少必填字段的安装规格 |
+| **安装规格清理** | 验证并清理包名、formula、URL |
+
+---
+
+## 四、关键源码索引
+
+### Plugin 通信层
+
+| 文件 | 职责 |
+|------|------|
+| `src/channels/plugins/types.plugin.ts` | ChannelPlugin 接口定义 |
+| `src/channels/plugins/types.core.ts` | 核心适配器类型 |
+| `src/channels/plugins/types.adapters.ts` | 适配器定义 |
+| `src/channels/plugins/catalog.ts` | Channel 注册表 |
+| `src/channels/plugins/load.ts` | Plugin 加载器 |
+| `src/channels/session.ts` | 会话记录 |
+| `src/channels/routing/` | 消息路由 |
+| `src/auto-reply/dispatch.ts` | `dispatchInboundMessage()` |
+| `src/auto-reply/reply/reply-dispatcher.ts` | ReplyDispatcher 实现 |
+| `src/auto-reply/reply/dispatch-from-config.ts` | 回复生成 |
+| `src/infra/outbound/channel-selection.ts` | 出站 channel 选择 |
+| `src/infra/outbound/channel-resolution.ts` | Plugin adapter 解析 |
+| `src/infra/outbound/deliver.ts` | `deliverOutboundPayloads()` |
+| `src/infra/outbound/message.ts` | 高级发送接口 |
+
+### Plugin SDK
+
+| 文件 | 职责 |
+|------|------|
+| `src/plugin-sdk/index.ts` | 主导出入口 |
+| `src/plugin-sdk/core.ts` | ChannelPlugin 接口 & 帮助器 |
+| `src/plugin-sdk/channel-inbound.ts` | 入站消息处理 |
+| `src/plugin-sdk/direct-dm.ts` | DM 访问控制 |
+| `src/plugin-sdk/inbound-reply-dispatch.ts` | 记录 session + 派发 |
+| `src/plugins/types.ts` | 核心 Plugin 类型定义（1500+ 行） |
+| `src/plugins/manifest.ts` | Plugin 清单加载/验证 |
+
+### Skill 系统
+
+| 文件 | 职责 |
+|------|------|
+| `src/agents/skills/workspace.ts` | Skill 加载、过滤、Prompt 构建（主文件） |
+| `src/agents/skills/frontmatter.ts` | Frontmatter 解析与验证 |
+| `src/agents/skills/types.ts` | 类型定义 |
+| `src/agents/skills/config.ts` | 配置解析 |
+| `src/agents/skills/filter.ts` | 资格过滤 |
+| `src/agents/skills/plugin-skills.ts` | Plugin 提供的 Skill |
+| `src/agents/skills/bundled-dir.ts` | 内置 Skill 发现 |
+| `src/agents/skills/env-overrides.ts` | 环境变量处理 |
+| `src/agents/skills/refresh.ts` | Skill 刷新/重载 |
+| `src/agents/pi-embedded-runner/skills-runtime.ts` | 运行时 Skill 加载 |
+| `src/agents/system-prompt.ts` | System Prompt 注入 |
+
+### 记忆系统
+
+| 文件 | 职责 |
+|------|------|
+| `src/memory/memory-schema.ts` | SQLite Schema 定义 |
+| `src/agents/tools/memory-tool.ts` | Agent 记忆工具（search/get） |
+| `src/agents/memory-search.ts` | 搜索协调 |
+
+### CLI 调试
+
+| 文件 | 职责 |
+|------|------|
+| `src/cli/skills-cli.ts` | Skill CLI 命令 |
+| `src/agents/skills-status.ts` | 状态报告 |
+| `src/agents/skills-install.ts` | 安装执行 |
+
+### 参考实现
+
+| Plugin | 路径 | 类型 |
+|--------|------|------|
+| BlueBubbles | `extensions/bluebubbles/` | Channel (iMessage 桥接) |
+| Twitch | `extensions/twitch/` | Channel (直播聊天) |
+| Matrix | `extensions/matrix/` | Channel (Matrix 协议) |
+| Moonshot | `extensions/moonshot/` | Provider (LLM + Web Search) |
+| Memory LanceDB | `extensions/memory-lancedb/` | Memory (向量检索) |
+| MS Teams | `extensions/msteams/` | Channel |
+| Zalo | `extensions/zalo/` | Channel |
+| Voice Call | `extensions/voice-call/` | Channel (语音) |
+
+---
+
+> **总结：** OpenClaw 的 Plugin 机制采用**同进程回调驱动**架构，Plugin 通过 webhook 接收外部消息，经安全前置检查后通过 SDK 函数派发到 Core Reply Engine，Core 处理后通过回调让 Plugin 发送回复。SDK 提供 160+ 子路径模块，支持 Channel、Provider、Tool、Hook 等全场景二次开发。Skill 本质上是**提示注入**而非代码执行，通过 YAML frontmatter 管理元数据和依赖，记忆系统基于 SQLite + 向量嵌入 + FTS5 实现语义和关键词双路检索。