@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/refactor/exec-host.md

@@ -0,0 +1,323 @@
+---
+read_when:
+  - 设计执行主机路由或执行审批
+  - 实现节点运行器 + UI IPC
+  - 添加执行主机安全模式和斜杠命令
+summary: 重构计划：执行主机路由、节点审批和无头运行器
+title: 执行主机重构
+x-i18n:
+  generated_at: "2026-02-01T21:36:56Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 53a9059cbeb1f3f1dbb48c2b5345f88ca92372654fef26f8481e651609e45e3a
+  source_path: refactor/exec-host.md
+  workflow: 15
+---
+
+# 执行主机重构计划
+
+## 目标
+
+- 添加 `exec.host` + `exec.security` 以在 **sandbox**、**gateway** 和 **node** 之间路由执行。
+- 保持默认值**安全**：除非明确启用，否则不进行跨主机执行。
+- 将执行拆分为**无头运行器服务**，并通过本地 IPC 提供可选 UI（macOS 应用）。
+- 提供**按智能体**的策略、允许列表、询问模式和节点绑定。
+- 支持与允许列表*配合*或*不配合*使用的**询问模式**。
+- 跨平台：Unix socket + token 认证（macOS/Linux/Windows 一致性）。
+
+## 非目标
+
+- 不进行旧版允许列表迁移或旧版 schema 支持。
+- 不为节点执行提供 PTY/流式输出（仅支持聚合输出）。
+- 不在现有 Bridge + Gateway网关之外新增网络层。
+
+## 决策（已锁定）
+
+- **配置键：**`exec.host` + `exec.security`（允许按智能体覆盖）。
+- **提权：**保留 `/elevated` 作为 gateway 完全访问的别名。
+- **询问默认值：**`on-miss`。
+- **审批存储：**`~/.openclaw/exec-approvals.json`（JSON，不迁移旧版）。
+- **运行器：**无头系统服务；UI 应用托管 Unix socket 用于审批。
+- **节点身份：**使用现有的 `nodeId`。
+- **Socket 认证：**Unix socket + token（跨平台）；后续需要时再拆分。
+- **节点主机状态：**`~/.openclaw/node.json`（节点 ID + 配对 token）。
+- **macOS 执行主机：**在 macOS 应用内运行 `system.run`；节点主机服务通过本地 IPC 转发请求。
+- **不使用 XPC helper：**坚持使用 Unix socket + token + 对端检查。
+
+## 核心概念
+
+### 主机
+
+- `sandbox`：Docker 执行（当前行为）。
+- `gateway`：在 gateway 主机上执行。
+- `node`：通过 Bridge 在节点运行器上执行（`system.run`）。
+
+### 安全模式
+
+- `deny`：始终阻止。
+- `allowlist`：仅允许匹配项。
+- `full`：允许所有（等同于提权模式）。
+
+### 询问模式
+
+- `off`：从不询问。
+- `on-miss`：仅在允许列表不匹配时询问。
+- `always`：每次都询问。
+
+询问与允许列表**相互独立**；允许列表可与 `always` 或 `on-miss` 配合使用。
+
+### 策略解析（每次执行）
+
+1. 解析 `exec.host`（工具参数 → 智能体覆盖 → 全局默认值）。
+2. 解析 `exec.security` 和 `exec.ask`（相同优先级）。
+3. 如果主机是 `sandbox`，使用本地沙箱执行。
+4. 如果主机是 `gateway` 或 `node`，在该主机上应用安全 + 询问策略。
+
+## 默认安全
+
+- 默认 `exec.host = sandbox`。
+- `gateway` 和 `node` 默认 `exec.security = deny`。
+- 默认 `exec.ask = on-miss`（仅在安全策略允许时相关）。
+- 如果未设置节点绑定，**智能体可以指向任何节点**，但仅在策略允许时。
+
+## 配置接口
+
+### 工具参数
+
+- `exec.host`（可选）：`sandbox | gateway | node`。
+- `exec.security`（可选）：`deny | allowlist | full`。
+- `exec.ask`（可选）：`off | on-miss | always`。
+- `exec.node`（可选）：当 `host=node` 时使用的节点 ID/名称。
+
+### 配置键（全局）
+
+- `tools.exec.host`
+- `tools.exec.security`
+- `tools.exec.ask`
+- `tools.exec.node`（默认节点绑定）
+
+### 配置键（按智能体）
+
+- `agents.list[].tools.exec.host`
+- `agents.list[].tools.exec.security`
+- `agents.list[].tools.exec.ask`
+- `agents.list[].tools.exec.node`
+
+### 别名
+
+- `/elevated on` = 为智能体会话设置 `tools.exec.host=gateway`、`tools.exec.security=full`。
+- `/elevated off` = 为智能体会话恢复之前的执行设置。
+
+## 审批存储（JSON）
+
+路径：`~/.openclaw/exec-approvals.json`
+
+用途：
+
+- **执行主机**（gateway 或节点运行器）的本地策略 + 允许列表。
+- 无 UI 可用时的询问回退。
+- UI 客户端的 IPC 凭据。
+
+建议的 schema（v1）：
+
+```json
+{
+  "version": 1,
+  "socket": {
+    "path": "~/.openclaw/exec-approvals.sock",
+    "token": "base64-opaque-token"
+  },
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss",
+    "askFallback": "deny"
+  },
+  "agents": {
+    "agent-id-1": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "allowlist": [
+        {
+          "pattern": "~/Projects/**/bin/rg",
+          "lastUsedAt": 0,
+          "lastUsedCommand": "rg -n TODO",
+          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
+        }
+      ]
+    }
+  }
+}
+```
+
+注意事项：
+
+- 不支持旧版允许列表格式。
+- `askFallback` 仅在需要询问但无 UI 可达时生效。
+- 文件权限：`0600`。
+
+## 运行器服务（无头）
+
+### 角色
+
+- 在本地强制执行 `exec.security` + `exec.ask`。
+- 执行系统命令并返回输出。
+- 发送 Bridge 事件用于执行生命周期（可选但建议启用）。
+
+### 服务生命周期
+
+- macOS 上为 Launchd/daemon；Linux/Windows 上为系统服务。
+- 审批 JSON 为执行主机本地文件。
+- UI 托管本地 Unix socket；运行器按需连接。
+
+## UI 集成（macOS 应用）
+
+### IPC
+
+- Unix socket 位于 `~/.openclaw/exec-approvals.sock`（0600）。
+- Token 存储在 `exec-approvals.json`（0600）中。
+- 对端检查：仅限相同 UID。
+- 质询/响应：nonce + HMAC(token, request-hash) 以防止重放。
+- 短 TTL（例如 10 秒）+ 最大负载 + 速率限制。
+
+### 询问流程（macOS 应用执行主机）
+
+1. 节点服务从 gateway 接收 `system.run`。
+2. 节点服务连接本地 socket 并发送提示/执行请求。
+3. 应用验证对端 + token + HMAC + TTL，然后在需要时显示对话框。
+4. 应用在 UI 上下文中执行命令并返回输出。
+5. 节点服务将输出返回给 gateway。
+
+如果 UI 不可用：
+
+- 应用 `askFallback`（`deny|allowlist|full`）。
+
+### 图示（SCI）
+
+```
+Agent -> Gateway网关 -> Bridge -> Node Service (TS)
+                         |  IPC (UDS + token + HMAC + TTL)
+                         v
+                     Mac App (UI + TCC + system.run)
+```
+
+## 节点身份 + 绑定
+
+- 使用 Bridge 配对中现有的 `nodeId`。
+- 绑定模型：
+  - `tools.exec.node` 将智能体限制到特定节点。
+  - 如果未设置，智能体可以选择任何节点（策略仍然强制执行默认值）。
+- 节点选择解析：
+  - `nodeId` 精确匹配
+  - `displayName`（规范化）
+  - `remoteIp`
+  - `nodeId` 前缀（>= 6 个字符）
+
+## 事件
+
+### 谁可以看到事件
+
+- 系统事件是**按会话**的，在下一个提示时展示给智能体。
+- 存储在 gateway 的内存队列中（`enqueueSystemEvent`）。
+
+### 事件文本
+
+- `Exec started (node=<id>, id=<runId>)`
+- `Exec finished (node=<id>, id=<runId>, code=<code>)` + 可选的输出尾部
+- `Exec denied (node=<id>, id=<runId>, <reason>)`
+
+### 传输
+
+方案 A（推荐）：
+
+- 运行器发送 Bridge `event` 帧 `exec.started` / `exec.finished`。
+- Gateway网关 `handleBridgeEvent` 将其映射为 `enqueueSystemEvent`。
+
+方案 B：
+
+- Gateway网关 `exec` 工具直接处理生命周期（仅同步）。
+
+## 执行流程
+
+### Sandbox 主机
+
+- 现有 `exec` 行为（Docker 或非沙箱时的主机执行）。
+- 仅在非沙箱模式下支持 PTY。
+
+### Gateway网关主机
+
+- Gateway网关进程在自身机器上执行。
+- 强制执行本地 `exec-approvals.json`（安全/询问/允许列表）。
+
+### Node 主机
+
+- Gateway网关通过 `node.invoke` 调用 `system.run`。
+- 运行器强制执行本地审批。
+- 运行器返回聚合的 stdout/stderr。
+- 可选的 Bridge 事件用于启动/完成/拒绝。
+
+## 输出限制
+
+- stdout+stderr 合计上限为 **200k**；事件保留**尾部 20k**。
+- 截断时添加明确后缀（例如 `"… (truncated)"`）。
+
+## 斜杠命令
+
+- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>`
+- 按智能体、按会话覆盖；除非通过配置保存，否则不持久化。
+- `/elevated on|off|ask|full` 仍作为 `host=gateway security=full` 的快捷方式（`full` 跳过审批）。
+
+## 跨平台方案
+
+- 运行器服务是可移植的执行目标。
+- UI 是可选的；如果不可用，则应用 `askFallback`。
+- Windows/Linux 支持相同的审批 JSON + socket 协议。
+
+## 实施阶段
+
+### 阶段 1：配置 + 执行路由
+
+- 添加 `exec.host`、`exec.security`、`exec.ask`、`exec.node` 的配置 schema。
+- 更新工具管道以遵循 `exec.host`。
+- 添加 `/exec` 斜杠命令并保留 `/elevated` 别名。
+
+### 阶段 2：审批存储 + gateway 强制执行
+
+- 实现 `exec-approvals.json` 读写器。
+- 为 `gateway` 主机强制执行允许列表 + 询问模式。
+- 添加输出限制。
+
+### 阶段 3：节点运行器强制执行
+
+- 更新节点运行器以强制执行允许列表 + 询问。
+- 添加 Unix socket 提示桥接到 macOS 应用 UI。
+- 接入 `askFallback`。
+
+### 阶段 4：事件
+
+- 添加节点 → gateway 的 Bridge 事件用于执行生命周期。
+- 映射到 `enqueueSystemEvent` 用于智能体提示。
+
+### 阶段 5：UI 完善
+
+- Mac 应用：允许列表编辑器、按智能体切换器、询问策略 UI。
+- 节点绑定控制（可选）。
+
+## 测试计划
+
+- 单元测试：允许列表匹配（glob + 大小写不敏感）。
+- 单元测试：策略解析优先级（工具参数 → 智能体覆盖 → 全局）。
+- 集成测试：节点运行器拒绝/允许/询问流程。
+- Bridge 事件测试：节点事件 → 系统事件路由。
+
+## 未解决风险
+
+- UI 不可用：确保 `askFallback` 被正确执行。
+- 长时间运行的命令：依赖超时 + 输出限制。
+- 多节点歧义：除非有节点绑定或明确的节点参数，否则报错。
+
+## 相关文档
+
+- [执行工具](/tools/exec)
+- [执行审批](/tools/exec-approvals)
+- [节点](/nodes)
+- [提权模式](/tools/elevated)

package/docs/zh-CN/refactor/outbound-session-mirroring.md

@@ -0,0 +1,92 @@
+---
+description: Track outbound session mirroring refactor notes, decisions, tests, and open items.
+title: 出站会话镜像重构（Issue
+x-i18n:
+  generated_at: "2026-02-01T21:36:30Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b88a72f36f7b6d8a71fde9d014c0a87e9a8b8b0d449b67119cf3b6f414fa2b81
+  source_path: refactor/outbound-session-mirroring.md
+  workflow: 15
+---
+
+# 出站会话镜像重构（Issue #1520）
+
+## 状态
+
+- 进行中。
+- 核心 + 插件渠道路由已针对出站镜像进行更新。
+- Gateway网关发送现在在省略 sessionKey 时自动推导目标会话。
+
+## 背景
+
+出站发送过去被镜像到*当前*智能体会话（工具会话键）而非目标渠道会话。入站路由使用渠道/对端会话键，因此出站响应落入了错误的会话，且首次联系的目标通常缺少会话条目。
+
+## 目标
+
+- 将出站消息镜像到目标渠道会话键。
+- 在缺少会话条目时，于出站时创建会话条目。
+- 保持线程/话题作用域与入站会话键对齐。
+- 覆盖核心渠道及捆绑扩展。
+
+## 实现摘要
+
+- 新增出站会话路由辅助模块：
+  - `src/infra/outbound/outbound-session.ts`
+  - `resolveOutboundSessionRoute` 使用 `buildAgentSessionKey`（dmScope + identityLinks）构建目标 sessionKey。
+  - `ensureOutboundSessionEntry` 通过 `recordSessionMetaFromInbound` 写入最小化的 `MsgContext`。
+- `runMessageAction`（发送）推导目标 sessionKey 并传递给 `executeSendAction` 用于镜像。
+- `message-tool` 不再直接镜像；它仅从当前会话键解析 agentId。
+- 插件发送路径使用推导的 sessionKey 通过 `appendAssistantMessageToSessionTranscript` 进行镜像。
+- Gateway网关发送在未提供 sessionKey 时推导目标会话键（默认智能体），并确保会话条目存在。
+
+## 线程/话题处理
+
+- Slack：replyTo/threadId -> `resolveThreadSessionKeys`（后缀）。
+- Discord：threadId/replyTo -> `resolveThreadSessionKeys`，`useSuffix=false` 以匹配入站（线程频道 ID 已限定会话作用域）。
+- Telegram：话题 ID 通过 `buildTelegramGroupPeerId` 映射为 `chatId:topic:<id>`。
+
+## 已覆盖的扩展
+
+- Matrix、MS Teams、Mattermost、BlueBubbles、Nextcloud Talk、Zalo、Zalo Personal、Nostr、Tlon。
+- 备注：
+  - Mattermost 目标现在为 私信 会话键路由去除 `@` 前缀。
+  - Zalo Personal 对 1:1 目标使用 私信 对端类型（仅在存在 `group:` 时使用群组）。
+  - BlueBubbles 群组目标去除 `chat_*` 前缀以匹配入站会话键。
+  - Slack 自动线程镜像不区分频道 ID 大小写进行匹配。
+  - Gateway网关发送在镜像前将提供的会话键转为小写。
+
+## 决策
+
+- **Gateway网关发送会话推导**：如果提供了 `sessionKey`，则直接使用。如果省略，则从目标 + 默认智能体推导 sessionKey 并镜像到该会话。
+- **会话条目创建**：始终使用 `recordSessionMetaFromInbound`，其 `Provider/From/To/ChatType/AccountId/Originating*` 与入站格式对齐。
+- **目标规范化**：出站路由在可用时使用已解析的目标（经过 `resolveChannelTarget` 处理后）。
+- **会话键大小写**：在写入和迁移时将会话键规范化为小写。
+
+## 新增/更新的测试
+
+- `src/infra/outbound/outbound-session.test.ts`
+  - Slack 线程会话键。
+  - Telegram 话题会话键。
+  - 使用 Discord 的 dmScope identityLinks。
+- `src/agents/tools/message-tool.test.ts`
+  - 从会话键推导 agentId（不传递 sessionKey）。
+- `src/gateway/server-methods/send.test.ts`
+  - 省略时推导会话键并创建会话条目。
+
+## 待办事项 / 后续跟进
+
+- 语音通话插件使用自定义 `voice:<phone>` 会话键。此处的出站映射尚未标准化；如果 message-tool 需要支持语音通话发送，需添加显式映射。
+- 确认是否有外部插件使用超出捆绑集合的非标准 `From/To` 格式。
+
+## 涉及的文件
+
+- `src/infra/outbound/outbound-session.ts`
+- `src/infra/outbound/outbound-send-service.ts`
+- `src/infra/outbound/message-action-runner.ts`
+- `src/agents/tools/message-tool.ts`
+- `src/gateway/server-methods/send.ts`
+- 测试文件：
+  - `src/infra/outbound/outbound-session.test.ts`
+  - `src/agents/tools/message-tool.test.ts`
+  - `src/gateway/server-methods/send.test.ts`

package/docs/zh-CN/refactor/plugin-sdk.md

@@ -0,0 +1,221 @@
+---
+read_when:
+  - 定义或重构插件架构
+  - 将渠道连接器迁移到插件 SDK/运行时
+summary: 计划：为所有消息连接器提供一套统一的插件 SDK + 运行时
+title: 插件 SDK 重构
+x-i18n:
+  generated_at: "2026-02-01T21:36:45Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d1964e2e47a19ee1d42ddaaa9cf1293c80bb0be463b049dc8468962f35bb6cb0
+  source_path: refactor/plugin-sdk.md
+  workflow: 15
+---
+
+# 插件 SDK + 运行时重构计划
+
+目标：每个消息连接器都是一个插件（内置或外部），使用统一稳定的 API。
+插件不直接从 `src/**` 导入任何内容。所有依赖项均通过 SDK 或运行时获取。
+
+## 为什么现在做
+
+- 当前连接器混用多种模式：直接导入核心模块、仅 dist 的桥接方式以及自定义辅助函数。
+- 这使得升级变得脆弱，并阻碍了干净的外部插件接口。
+
+## 目标架构（两层）
+
+### 1）插件 SDK（编译时，稳定，可发布）
+
+范围：类型、辅助函数和配置工具。无运行时状态，无副作用。
+
+内容（示例）：
+
+- 类型：`ChannelPlugin`、适配器、`ChannelMeta`、`ChannelCapabilities`、`ChannelDirectoryEntry`。
+- 配置辅助函数：`buildChannelConfigSchema`、`setAccountEnabledInConfigSection`、`deleteAccountFromConfigSection`、
+  `applyAccountNameToChannelSection`。
+- 配对辅助函数：`PAIRING_APPROVED_MESSAGE`、`formatPairingApproveHint`。
+- 新手引导辅助函数：`promptChannelAccessConfig`、`addWildcardAllowFrom`、新手引导类型。
+- 工具参数辅助函数：`createActionGate`、`readStringParam`、`readNumberParam`、`readReactionParams`、`jsonResult`。
+- 文档链接辅助函数：`formatDocsLink`。
+
+交付方式：
+
+- 以 `openclaw/plugin-sdk` 发布（或从核心以 `openclaw/plugin-sdk` 导出）。
+- 使用语义化版本控制，提供明确的稳定性保证。
+
+### 2）插件运行时（执行层，注入式）
+
+范围：所有涉及核心运行时行为的内容。
+通过 `OpenClawPluginApi.runtime` 访问，确保插件永远不会导入 `src/**`。
+
+建议的接口（最小但完整）：
+
+```ts
+export type PluginRuntime = {
+  channel: {
+    text: {
+      chunkMarkdownText(text: string, limit: number): string[];
+      resolveTextChunkLimit(cfg: OpenClawConfig, channel: string, accountId?: string): number;
+      hasControlCommand(text: string, cfg: OpenClawConfig): boolean;
+    };
+    reply: {
+      dispatchReplyWithBufferedBlockDispatcher(params: {
+        ctx: unknown;
+        cfg: unknown;
+        dispatcherOptions: {
+          deliver: (payload: {
+            text?: string;
+            mediaUrls?: string[];
+            mediaUrl?: string;
+          }) => void | Promise<void>;
+          onError?: (err: unknown, info: { kind: string }) => void;
+        };
+      }): Promise<void>;
+      createReplyDispatcherWithTyping?: unknown; // adapter for Teams-style flows
+    };
+    routing: {
+      resolveAgentRoute(params: {
+        cfg: unknown;
+        channel: string;
+        accountId: string;
+        peer: { kind: "dm" | "group" | "channel"; id: string };
+      }): { sessionKey: string; accountId: string };
+    };
+    pairing: {
+      buildPairingReply(params: { channel: string; idLine: string; code: string }): string;
+      readAllowFromStore(channel: string): Promise<string[]>;
+      upsertPairingRequest(params: {
+        channel: string;
+        id: string;
+        meta?: { name?: string };
+      }): Promise<{ code: string; created: boolean }>;
+    };
+    media: {
+      fetchRemoteMedia(params: { url: string }): Promise<{ buffer: Buffer; contentType?: string }>;
+      saveMediaBuffer(
+        buffer: Uint8Array,
+        contentType: string | undefined,
+        direction: "inbound" | "outbound",
+        maxBytes: number,
+      ): Promise<{ path: string; contentType?: string }>;
+    };
+    mentions: {
+      buildMentionRegexes(cfg: OpenClawConfig, agentId?: string): RegExp[];
+      matchesMentionPatterns(text: string, regexes: RegExp[]): boolean;
+    };
+    groups: {
+      resolveGroupPolicy(
+        cfg: OpenClawConfig,
+        channel: string,
+        accountId: string,
+        groupId: string,
+      ): {
+        allowlistEnabled: boolean;
+        allowed: boolean;
+        groupConfig?: unknown;
+        defaultConfig?: unknown;
+      };
+      resolveRequireMention(
+        cfg: OpenClawConfig,
+        channel: string,
+        accountId: string,
+        groupId: string,
+        override?: boolean,
+      ): boolean;
+    };
+    debounce: {
+      createInboundDebouncer<T>(opts: {
+        debounceMs: number;
+        buildKey: (v: T) => string | null;
+        shouldDebounce: (v: T) => boolean;
+        onFlush: (entries: T[]) => Promise<void>;
+        onError?: (err: unknown) => void;
+      }): { push: (v: T) => void; flush: () => Promise<void> };
+      resolveInboundDebounceMs(cfg: OpenClawConfig, channel: string): number;
+    };
+    commands: {
+      resolveCommandAuthorizedFromAuthorizers(params: {
+        useAccessGroups: boolean;
+        authorizers: Array<{ configured: boolean; allowed: boolean }>;
+      }): boolean;
+    };
+  };
+  logging: {
+    shouldLogVerbose(): boolean;
+    getChildLogger(name: string): PluginLogger;
+  };
+  state: {
+    resolveStateDir(cfg: OpenClawConfig): string;
+  };
+};
+```
+
+备注：
+
+- 运行时是访问核心行为的唯一方式。
+- SDK 故意保持小巧和稳定。
+- 每个运行时方法都映射到现有的核心实现（无重复代码）。
+
+## 迁移计划（分阶段，安全）
+
+### 阶段 0：基础搭建
+
+- 引入 `openclaw/plugin-sdk`。
+- 在 `OpenClawPluginApi` 中添加带有上述接口的 `api.runtime`。
+- 在过渡期内保留现有导入方式（添加弃用警告）。
+
+### 阶段 1：桥接清理（低风险）
+
+- 用 `api.runtime` 替换每个扩展中的 `core-bridge.ts`。
+- 优先迁移 BlueBubbles、Zalo、Zalo Personal（已经接近完成）。
+- 移除重复的桥接代码。
+
+### 阶段 2：轻度直接导入的插件
+
+- 将 Matrix 迁移到 SDK + 运行时。
+- 验证新手引导、目录、群组提及逻辑。
+
+### 阶段 3：重度直接导入的插件
+
+- 迁移 Microsoft Teams（使用运行时辅助函数最多的插件）。
+- 确保回复/正在输入的语义与当前行为一致。
+
+### 阶段 4：iMessage 插件化
+
+- 将 iMessage 移入 `extensions/imessage`。
+- 用 `api.runtime` 替换直接的核心调用。
+- 保持配置键、CLI 行为和文档不变。
+
+### 阶段 5：强制执行
+
+- 添加 lint 规则 / CI 检查：禁止 `extensions/**` 从 `src/**` 导入。
+- 添加插件 SDK/版本兼容性检查（运行时 + SDK 语义化版本）。
+
+## 兼容性与版本控制
+
+- SDK：语义化版本控制，已发布，变更有文档记录。
+- 运行时：按核心版本进行版本控制。添加 `api.runtime.version`。
+- 插件声明所需的运行时版本范围（例如 `openclawRuntime: ">=2026.2.0"`）。
+
+## 测试策略
+
+- 适配器级单元测试（使用真实核心实现验证运行时函数）。
+- 每个插件的黄金测试：确保行为无偏差（路由、配对、允许列表、提及过滤）。
+- CI 中使用单个端到端插件示例（安装 + 运行 + 冒烟测试）。
+
+## 待解决问题
+
+- SDK 类型托管在哪里：独立包还是核心导出？
+- 运行时类型分发：在 SDK 中（仅类型）还是在核心中？
+- 如何为内置插件与外部插件暴露文档链接？
+- 过渡期间是否允许仓库内插件有限地直接导入核心模块？
+
+## 成功标准
+
+- 所有渠道连接器都是使用 SDK + 运行时的插件。
+- `extensions/**` 不再从 `src/**` 导入。
+- 新连接器模板仅依赖 SDK + 运行时。
+- 外部插件可以在无需访问核心源码的情况下进行开发和更新。
+
+相关文档：[插件](/plugin)、[渠道](/channels/index)、[配置](/gateway/configuration)。