@rowger_go/chatu 0.1.3

package/docs/sdk/v2026.1.29-v2026.2.19.md

@@ -0,0 +1,630 @@
+# OpenClaw Channel Plugin SDK 变更报告
+
+**版本对比**：`v2026.1.29` → `v2026.2.19`  
+**生成日期**：2026-02-20  
+**分析范围**：Channel Plugin SDK 公共接口
+
+---
+
+## 概述
+
+本次版本升级是一次**纯增量式更新**，不含任何破坏性变更。主要新增了 6 个生命周期 Hook（包含 LLM 输入/输出观测、消息写入拦截、模型覆盖等能力），并在多个核心类型上补充了可选字段。`plugin-sdk/index.ts` 新增了大量工具函数导出（文件锁、Webhook 辅助、SSRF 防护等），大幅扩展了插件能力边界。整体变更规模较大，但对现有插件的升级代价极低。
+
+---
+
+## 破坏性变更（Breaking Changes）
+
+> ✅ **本次版本间不存在任何破坏性变更。** 所有变更均为向后兼容的新增或可选字段扩充。
+
+---
+
+## 新增功能（New Features）
+
+### 1. `before_model_resolve` Hook
+
+- **变更类型**：新增 Hook 及对应事件/结果类型
+- **定义**：
+  ```typescript
+  // 新增事件类型
+  export type PluginHookBeforeModelResolveEvent = {
+    /** 本次运行的用户提示词，此阶段尚无会话消息 */
+    prompt: string;
+  };
+
+  export type PluginHookBeforeModelResolveResult = {
+    /** 覆盖本次 agent 运行使用的模型，如 "llama3.3:8b" */
+    modelOverride?: string;
+    /** 覆盖本次 agent 运行使用的 provider，如 "ollama" */
+    providerOverride?: string;
+  };
+  ```
+- **用途说明**：在 agent 运行开始前、会话消息加载前触发，允许插件动态覆盖本次运行使用的模型或 provider。适用于按用户/渠道路由不同模型的场景。
+- **注册方式**：
+  ```typescript
+  api.on("before_model_resolve", (event, ctx) => {
+    if (ctx.channelId === "telegram") {
+      return { modelOverride: "gpt-4o" };
+    }
+  });
+  ```
+
+---
+
+### 2. `before_prompt_build` Hook
+
+- **变更类型**：新增 Hook 及对应事件/结果类型
+- **定义**：
+  ```typescript
+  export type PluginHookBeforePromptBuildEvent = {
+    prompt: string;
+    /** 本次运行准备好的会话消息列表 */
+    messages: unknown[];
+  };
+
+  export type PluginHookBeforePromptBuildResult = {
+    systemPrompt?: string;
+    prependContext?: string;
+  };
+  ```
+- **用途说明**：在 prompt 构建前触发，此阶段已可访问完整会话消息列表，可注入系统提示词或前置上下文。与旧版 `before_agent_start` 相比，信息更完整。
+
+---
+
+### 3. `llm_input` Hook
+
+- **变更类型**：新增 Hook（只读观测）
+- **定义**：
+  ```typescript
+  export type PluginHookLlmInputEvent = {
+    runId: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    systemPrompt: string;
+    prompt: string;
+    historyMessages: unknown[];
+    imagesCount: number;
+  };
+  ```
+- **用途说明**：在每次向 LLM 发送请求前触发（只读），可用于日志记录、计量、审计等。返回值被忽略（`void`）。
+
+---
+
+### 4. `llm_output` Hook
+
+- **变更类型**：新增 Hook（只读观测）
+- **定义**：
+  ```typescript
+  export type PluginHookLlmOutputEvent = {
+    runId: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    assistantTexts: string[];
+    lastAssistant?: unknown;
+    usage?: {
+      input?: number;
+      output?: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+      total?: number;
+    };
+  };
+  ```
+- **用途说明**：在 LLM 返回结果后触发（只读），可获取 token 用量、输出文本等信息，适用于计费统计、内容监控场景。
+
+---
+
+### 5. `before_reset` Hook
+
+- **变更类型**：新增 Hook
+- **定义**：
+  ```typescript
+  export type PluginHookBeforeResetEvent = {
+    sessionFile?: string;
+    messages?: unknown[];
+    reason?: string;
+  };
+  ```
+- **用途说明**：在用户执行 `/new` 或 `/reset` 清除会话时触发，插件可在会话被清除前读取会话内容（如存档、统计等）。
+
+---
+
+### 6. `before_message_write` Hook
+
+- **变更类型**：新增 Hook（支持阻断）
+- **定义**：
+  ```typescript
+  export type PluginHookBeforeMessageWriteEvent = {
+    message: AgentMessage;
+    sessionKey?: string;
+    agentId?: string;
+  };
+
+  export type PluginHookBeforeMessageWriteResult = {
+    block?: boolean;    // true 则阻止该消息写入 JSONL
+    message?: AgentMessage; // 可选：写入修改后的消息
+  };
+  ```
+- **注册签名**：
+  ```typescript
+  before_message_write: (
+    event: PluginHookBeforeMessageWriteEvent,
+    ctx: { agentId?: string; sessionKey?: string },
+  ) => PluginHookBeforeMessageWriteResult | void;
+  ```
+- **用途说明**：在消息写入会话 JSONL 文件前触发，插件可阻止特定消息落盘（如过滤大型 tool result），或对消息内容进行修改后再写入。**注意：此 Hook 不支持异步，必须同步返回。**
+
+---
+
+### 7. 新增类型：`BaseProbeResult` 和 `BaseTokenResolution`（`types.core.ts`）
+
+- **变更类型**：新增
+- **定义**：
+  ```typescript
+  /** 所有 channel probe 结果的最小基类，channel 专用 probe 可继承此类型 */
+  export type BaseProbeResult<TError = string | null> = {
+    ok: boolean;
+    error?: TError;
+  };
+
+  /** token 解析结果的最小基类 */
+  export type BaseTokenResolution = {
+    token: string;
+    source: string;
+  };
+  ```
+- **用途说明**：为各 channel 实现 probe/token 相关结果提供标准化的基础类型，便于统一处理和类型收窄。
+
+---
+
+### 8. `plugin-sdk/index.ts` 大量新增导出
+
+以下是本次新增的主要导出分类：
+
+#### 文件锁 API
+```typescript
+export type { FileLockHandle, FileLockOptions } from "./file-lock.js";
+export { acquireFileLock, withFileLock } from "./file-lock.js";
+```
+
+#### Webhook 辅助
+```typescript
+export { normalizeWebhookPath, resolveWebhookPath } from "./webhook-path.js";
+export {
+  registerWebhookTarget,
+  rejectNonPostWebhookRequest,
+  resolveWebhookTargets,
+} from "./webhook-targets.js";
+```
+
+#### Agent 媒体处理
+```typescript
+export type { AgentMediaPayload } from "./agent-media-payload.js";
+export { buildAgentMediaPayload } from "./agent-media-payload.js";
+```
+
+#### Channel 状态辅助
+```typescript
+export {
+  buildBaseChannelStatusSummary,
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
+} from "./status-helpers.js";
+```
+
+#### SSRF/网络防护
+```typescript
+export { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
+export {
+  SsrFBlockedError,
+  isBlockedHostname,
+  isBlockedHostnameOrIp,
+  isPrivateIpAddress,
+} from "../infra/net/ssrf.js";
+export type { LookupFn, SsrFPolicy } from "../infra/net/ssrf.js";
+```
+
+#### HTTP 请求体处理
+```typescript
+export {
+  DEFAULT_WEBHOOK_BODY_TIMEOUT_MS,
+  DEFAULT_WEBHOOK_MAX_BODY_BYTES,
+  RequestBodyLimitError,
+  installRequestBodyLimitGuard,
+  isRequestBodyLimitError,
+  readJsonBodyWithLimit,
+  readRequestBodyWithLimit,
+  requestBodyErrorToText,
+} from "../infra/http-body.js";
+```
+
+#### 去重缓存
+```typescript
+export { createDedupeCache } from "../infra/dedupe.js";
+export type { DedupeCache } from "../infra/dedupe.js";
+```
+
+#### 设备配对
+```typescript
+export {
+  approveDevicePairing,
+  listDevicePairing,
+  rejectDevicePairing,
+} from "../infra/device-pairing.js";
+```
+
+#### 工具函数
+```typescript
+export { clamp, escapeRegExp, normalizeE164, safeParseJson, sleep } from "../utils.js";
+export { stripAnsi } from "../terminal/ansi.js";
+export { formatErrorMessage } from "../infra/errors.js";
+export { isTruthyEnvValue } from "../infra/env.js";
+export { isWSLSync, isWSL2Sync, isWSLEnv } from "../infra/wsl.js";
+export { rawDataToString } from "../infra/ws.js";
+```
+
+#### 平台特定工具函数（新增）
+```typescript
+// iMessage 目标解析
+export {
+  parseChatAllowTargetPrefixes,
+  parseChatTargetPrefixesOrThrow,
+  resolveServicePrefixedAllowTarget,
+  resolveServicePrefixedTarget,
+} from "../imessage/target-parsing-helpers.js";
+
+// Slack 消息 actions
+export { extractSlackToolSend, listSlackMessageActions } from "../slack/message-actions.js";
+export { handleSlackMessageAction } from "./slack-message-actions.js";
+
+// Telegram 参数解析
+export {
+  parseTelegramReplyToMessageId,
+  parseTelegramThreadId,
+} from "../telegram/outbound-params.js";
+export { type TelegramProbe } from "../telegram/probe.js";
+
+// WhatsApp 出向目标
+export { resolveWhatsAppOutboundTarget } from "../whatsapp/resolve-outbound-target.js";
+
+// Discord
+export { normalizeDiscordOutboundTarget } from "...";
+```
+
+#### 其他新增
+```typescript
+export { createAccountListHelpers } from "../channels/plugins/account-helpers.js";
+export { buildOauthProviderAuthResult } from "./provider-auth-result.js";
+export { createReplyPrefixOptions } from "../channels/reply-prefix.js";  // replaceFromOnly
+export { resolveAllowlistMatchSimple } from "../channels/plugins/allowlist-match.js";
+export { mergeAllowFromEntries } from "../channels/plugins/onboarding/helpers.js";
+export { formatAllowFromLowercase, isAllowedParsedChatSender } from "./allow-from.js";
+export { resolveSenderCommandAuthorization } from "./command-auth.js";
+export { extractToolSend } from "./tool-send.js";
+export { resolveChannelAccountConfigBasePath } from "./config-paths.js";
+export { chunkTextForOutbound } from "./text-chunking.js";
+export { readJsonFileWithFallback, writeJsonFileAtomically } from "./json-store.js";
+export { buildRandomTempFilePath, withTempDownloadPath } from "./temp-path.js";
+
+// 类型别名（向后兼容）
+/** @deprecated Use OpenClawConfig instead */
+export type { OpenClawConfig as ClawdbotConfig } from "../config/config.js";
+/** @deprecated Use ChatType instead */
+export type { RoutePeerKind } from "../routing/resolve-route.js";
+export type { ChatType } from "../channels/chat-type.js";
+
+// RuntimeLogger
+export type { PluginRuntime, RuntimeLogger } from "../plugins/runtime/types.js";
+
+// TTS Schema
+export { TtsAutoSchema, TtsConfigSchema, TtsModeSchema, TtsProviderSchema };
+
+// Provider Auth
+export type { ProviderAuthContext, ProviderAuthResult };
+export type { AnyAgentTool } from "../agents/tools/common.js";
+```
+
+---
+
+## 非破坏性变更（Non-Breaking Changes）
+
+### `PluginHookName`（`plugins/types.ts`）
+
+- **变更类型**：Union 成员新增
+- **说明**：新增 6 个 hook 名称（`before_model_resolve`、`before_prompt_build`、`llm_input`、`llm_output`、`before_reset`、`before_message_write`），现有代码引用原有名称不受影响。
+
+---
+
+### `PluginHookAgentContext`（`plugins/types.ts`）
+
+- **变更类型**：字段新增（均为可选）
+- **说明**：
+  ```typescript
+  // 新增字段（均为可选）
+  sessionId?: string;         // 当前会话 ID
+  channelId?: ChannelId;      // Provider 渠道 ID (如 "telegram")
+  from?: string;              // 原始 "From" 值（渠道内 ID）
+  to?: string;                // 原始 "To" 值（渠道内 ID）
+  accountId?: string;         // 多账号渠道的账号 ID
+  messageThreadId?: number;   // 线程/话题 ID（如有）
+  ```
+
+---
+
+### `PluginHookBeforeCompactionEvent`（`plugins/types.ts`）
+
+- **变更类型**：字段新增（均为可选）
+- **说明**：
+  ```typescript
+  compactingCount?: number;  // 送入压缩 LLM 的消息数（经 history-limit 截断后）
+  messages?: unknown[];      // 当前会话全部消息
+  sessionFile?: string;      // 会话 JSONL 文件路径（可异步读取）
+  ```
+
+---
+
+### `PluginHookAfterCompactionEvent`（`plugins/types.ts`）
+
+- **变更类型**：字段新增（可选）
+- **说明**：
+  ```typescript
+  sessionFile?: string;  // 会话 JSONL 文件路径（压缩前所有消息均已落盘）
+  ```
+
+---
+
+### `PluginHookBeforeAgentStartResult`（`plugins/types.ts`）
+
+- **变更类型**：类型定义扩展（交叉类型，非破坏性）
+- **说明**：
+  ```typescript
+  // 旧定义（v2026.1.29）
+  export type PluginHookBeforeAgentStartResult = {
+    systemPrompt?: string;
+    prependContext?: string;
+  };
+
+  // 新定义（v2026.2.19）
+  export type PluginHookBeforeAgentStartResult =
+    PluginHookBeforePromptBuildResult & PluginHookBeforeModelResolveResult;
+  // 展开后等价于：
+  // { systemPrompt?: string; prependContext?: string; modelOverride?: string; providerOverride?: string; }
+  ```
+  原有字段均保留，新增了 `modelOverride?` 和 `providerOverride?` 可选字段，现有实现无需修改。
+
+---
+
+### `ChannelAgentTool`（`types.core.ts`）
+
+- **变更类型**：类型扩展（新增可选字段）
+- **说明**：
+  ```typescript
+  // 旧定义
+  export type ChannelAgentTool = AgentTool<TSchema, unknown>;
+
+  // 新定义
+  export type ChannelAgentTool = AgentTool<TSchema, unknown> & {
+    ownerOnly?: boolean;  // 若为 true，仅 owner 可调用此工具
+  };
+  ```
+
+---
+
+### `ChannelAccountSnapshot`（`types.core.ts`）
+
+- **变更类型**：字段新增（均为可选）
+- **说明**：新增以下可选字段，为更多 channel（如 LINE、公钥基础设施）提供通用快照存储：
+  ```typescript
+  secretSource?: string;
+  publicKey?: string | null;
+  profile?: unknown;
+  channelAccessToken?: string;
+  channelSecret?: string;
+  ```
+
+---
+
+### `ChannelCapabilities.chatTypes`（`types.core.ts`）
+
+- **变更类型**：依赖类型重命名（非破坏性，运行时无影响）
+- **说明**：
+  ```typescript
+  // 旧（v2026.1.29）
+  chatTypes: Array<NormalizedChatType | "thread">;
+
+  // 新（v2026.2.19）
+  chatTypes: Array<ChatType | "thread">;
+  ```
+  `NormalizedChatType` 被重命名为 `ChatType`（来自 `../channels/chat-type.js`），底层值不变。若插件代码直接使用了 `NormalizedChatType` 类型注解，需更新为 `ChatType`。
+
+---
+
+### `ChannelThreadingAdapter`（`types.core.ts`）
+
+- **变更类型**：字段新增（可选）
+- **说明**：
+  ```typescript
+  // 新增字段
+  allowExplicitReplyTagsWhenOff?: boolean;
+  // 同时：allowTagsWhenOff 被标注为 deprecated alias，但保留兼容性
+  ```
+
+---
+
+### `ChannelMessageActionContext`（`types.core.ts`）
+
+- **变更类型**：字段新增（可选）
+- **说明**：
+  ```typescript
+  /**
+   * Trusted sender id from inbound context. This is server-injected and must
+   * never be sourced from tool/model-controlled params.
+   */
+  requesterSenderId?: string | null;
+  ```
+
+---
+
+### `ChannelPollContext`（`types.core.ts`）
+
+- **变更类型**：字段新增（均为可选）
+- **说明**：
+  ```typescript
+  threadId?: string | null;
+  silent?: boolean;
+  isAnonymous?: boolean;
+  ```
+
+---
+
+### `ChannelPlugin<ResolvedAccount>`（`types.plugin.ts`）
+
+- **变更类型**：泛型参数扩展（新增带默认值的泛型，非破坏性）
+- **说明**：
+  ```typescript
+  // 旧定义
+  export type ChannelPlugin<ResolvedAccount = any> = { ... };
+
+  // 新定义
+  export type ChannelPlugin<ResolvedAccount = any, Probe = unknown, Audit = unknown> = { ... };
+  ```
+  新增 `Probe` 和 `Audit` 泛型参数，均有默认值 `unknown`，现有代码无需修改。`status` 字段类型更新为 `ChannelStatusAdapter<ResolvedAccount, Probe, Audit>`。
+
+---
+
+### `ChannelStatusAdapter<ResolvedAccount>`（`types.adapters.ts`）
+
+- **变更类型**：泛型参数扩展（新增带默认值的泛型，类型更精确）
+- **说明**：
+  ```typescript
+  // 旧定义
+  export type ChannelStatusAdapter<ResolvedAccount> = {
+    probeAccount?: (...) => Promise<unknown>;
+    auditAccount?: (..., probe?: unknown) => Promise<unknown>;
+    buildAccountSnapshot?: (..., probe?: unknown, audit?: unknown) => ...;
+  };
+
+  // 新定义
+  export type ChannelStatusAdapter<ResolvedAccount, Probe = unknown, Audit = unknown> = {
+    probeAccount?: (...) => Promise<Probe>;
+    auditAccount?: (..., probe?: Probe) => Promise<Audit>;
+    buildAccountSnapshot?: (..., probe?: Probe, audit?: Audit) => ...;
+  };
+  ```
+  默认值为 `unknown`，与旧版行为完全一致。类型参数允许 channel 实现提供更精确的类型推断。
+
+---
+
+### `ChannelOutboundContext`（`types.adapters.ts`）
+
+- **变更类型**：字段新增（均为可选）
+- **说明**：
+  ```typescript
+  mediaLocalRoots?: readonly string[];  // 媒体文件本地根路径列表
+  identity?: OutboundIdentity;          // 发送身份信息
+  silent?: boolean;                     // 静默发送（不触发通知）
+  ```
+
+---
+
+## 导出变更（Export Changes）
+
+| 导出名称 | 变更类型 | 说明 |
+|----------|----------|------|
+| `createAccountListHelpers` | 新增 | 账号列表辅助函数 |
+| `BaseProbeResult` | 新增 | channel probe 结果基类型 |
+| `BaseTokenResolution` | 新增 | token 解析结果基类型 |
+| `AnyAgentTool` | 新增 | agent 工具的 any 联合类型 |
+| `ProviderAuthContext` | 新增 | Provider 认证上下文 |
+| `ProviderAuthResult` | 新增 | Provider 认证结果 |
+| `RuntimeLogger` | 新增 | 运行时日志接口 |
+| `ClawdbotConfig` | 新增（deprecated） | `OpenClawConfig` 的弃用别名 |
+| `FileLockHandle` / `FileLockOptions` | 新增 | 文件锁类型 |
+| `acquireFileLock` / `withFileLock` | 新增 | 文件锁 API |
+| `normalizeWebhookPath` / `resolveWebhookPath` | 新增 | Webhook 路径辅助 |
+| `registerWebhookTarget` 等 3 个函数 | 新增 | Webhook 目标注册 |
+| `AgentMediaPayload` / `buildAgentMediaPayload` | 新增 | Agent 媒体载荷 |
+| `buildBaseChannelStatusSummary` 等 3 个函数 | 新增 | Channel 状态辅助 |
+| `buildOauthProviderAuthResult` | 新增 | OAuth Provider 认证结果构建 |
+| `TtsAutoSchema` / `TtsConfigSchema` 等 | 新增 | TTS 配置 Schema |
+| `formatAllowFromLowercase` / `isAllowedParsedChatSender` | 新增 | allowFrom 格式化与验证 |
+| `resolveSenderCommandAuthorization` | 新增 | 命令发送方授权解析 |
+| `handleSlackMessageAction` | 新增 | Slack 消息 action 处理 |
+| `extractToolSend` | 新增 | 提取工具发送信息 |
+| `resolveChannelAccountConfigBasePath` | 新增 | Channel 账号配置路径解析 |
+| `chunkTextForOutbound` | 新增 | 出向文本分块 |
+| `readJsonFileWithFallback` / `writeJsonFileAtomically` | 新增 | JSON 文件读写 |
+| `buildRandomTempFilePath` / `withTempDownloadPath` | 新增 | 临时文件路径 |
+| `ChatType` | 新增 | 聊天类型（替代 `NormalizedChatType`） |
+| `RoutePeerKind` | 新增（deprecated） | `ChatType` 的弃用别名 |
+| `createReplyPrefixOptions` | 新增 | reply prefix 选项创建（原有 `createReplyPrefixContext` 保留）|
+| `resolveAllowlistMatchSimple` | 新增 | 简化版 allowlist 匹配 |
+| `mergeAllowFromEntries` | 新增 | 合并 allowFrom 条目 |
+| `clamp` / `escapeRegExp` / `safeParseJson` / `sleep` | 新增 | 通用工具函数（原有 `normalizeE164` 保留）|
+| `stripAnsi` | 新增 | 去除 ANSI 转义字符 |
+| `normalizeDiscordOutboundTarget` | 新增 | Discord 出向目标规范化 |
+| `parseChatAllowTargetPrefixes` 等 4 个函数 | 新增 | iMessage 目标解析辅助 |
+| `extractSlackToolSend` / `listSlackMessageActions` | 新增 | Slack 工具发送与 action 列表 |
+| `parseTelegramReplyToMessageId` / `parseTelegramThreadId` | 新增 | Telegram 参数解析 |
+| `TelegramProbe` | 新增 | Telegram probe 类型 |
+| `resolveWhatsAppOutboundTarget` | 新增 | WhatsApp 出向目标解析 |
+| `approveDevicePairing` 等 3 个函数 | 新增 | 设备配对管理 |
+| `createDedupeCache` / `DedupeCache` | 新增 | 去重缓存 |
+| `formatErrorMessage` | 新增 | 错误信息格式化 |
+| 8 个 HTTP body 处理函数/类型 | 新增 | HTTP 请求体限制与解析 |
+| `fetchWithSsrFGuard` | 新增 | 带 SSRF 防护的 fetch |
+| `SsrFBlockedError` / `isBlockedHostname` 等 | 新增 | SSRF 防护 API |
+| `rawDataToString` | 新增 | WebSocket 原始数据转字符串 |
+| `isWSLSync` / `isWSL2Sync` / `isWSLEnv` | 新增 | WSL 环境检测 |
+| `isTruthyEnvValue` | 新增 | 环境变量布尔值解析 |
+
+---
+
+## 对 `openclaw-web-hub-channel` 插件的影响
+
+### 影响评估
+
+`openclaw-web-hub-channel` 插件（`src/index.ts`）目前使用 `api: any` 作为入参类型，**未直接导入 SDK 类型**，因此本次所有类型级变更对其**无直接影响**。
+
+### 需要修改的代码
+
+| 文件 | 位置 | 原因 |
+|------|------|------|
+| 无需修改 | — | 插件使用 `api: any`，与 SDK 类型解耦 |
+
+### 可选优化建议（非必须）
+
+以下是可以利用新功能改善插件能力的可选项：
+
+1. **利用 `before_model_resolve` Hook**：如果插件需要按渠道路由不同模型，可使用此 Hook 动态覆盖模型。
+
+2. **利用 `llm_input` / `llm_output` Hook**：可用于记录 token 使用量、计费统计或内容审计日志。
+
+3. **利用 `before_message_write` Hook**：如需过滤大型 tool result 以减少存储，可使用此 Hook 在消息落盘前处理。
+
+4. **利用新增 webhook 辅助函数**：`registerWebhookTarget`、`normalizeWebhookPath` 等函数可简化 webhook 处理逻辑。
+
+5. **利用 SSRF 防护 API**：若插件接受用户输入的 URL 并发起请求，建议使用 `fetchWithSsrFGuard` 替代原生 `fetch`。
+
+6. **使用 `writeJsonFileAtomically`**：替代自定义的 JSON 文件写入逻辑，确保原子性。
+
+### 建议升级步骤
+
+1. 将插件中 `openclaw` 依赖版本更新至 `v2026.2.19`。
+2. 运行 `pnpm install` 更新依赖。
+3. 运行 `pnpm build`（或 `tsc --noEmit`）验证编译通过。
+4. 无需修改任何现有代码。
+5. 按需采纳可选优化建议。
+
+---
+
+## 变更摘要表
+
+| 文件 | 新增 | 删除 | 修改 | 破坏性 |
+|------|------|------|------|--------|
+| `src/plugin-sdk/index.ts` | ~60+ 导出 | 0 | 3（路径/内容扩展） | 0 |
+| `src/plugins/types.ts` | 9 个新类型，6 个新 Hook | 0 | 3（`PluginHookName` 扩展、`PluginHookBeforeAgentStartResult` 扩展、`PluginHookAgentContext` 新增字段） | 0 |
+| `src/channels/plugins/types.core.ts` | 2 个新类型、多个可选字段 | 0 | 4（`ChannelAgentTool`、`ChannelAccountSnapshot`、`ChannelCapabilities`、`ChannelThreadingAdapter`、`ChannelMessageActionContext`、`ChannelPollContext`） | 0 |
+| `src/channels/plugins/types.plugin.ts` | 0 | 0 | 1（`ChannelPlugin` 新增泛型参数） | 0 |
+| `src/channels/plugins/types.adapters.ts` | 0 | 0 | 2（`ChannelStatusAdapter` 新增泛型参数、`ChannelOutboundContext` 新增字段） | 0 |

package/jest.config.js

@@ -0,0 +1,19 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.ts'],
+  moduleNameMapper: {
+    '^openclaw/plugin-sdk$': '<rootDir>/node_modules/openclaw/dist/plugin-sdk/index',
+  },
+  globals: {
+    'ts-jest': {
+      tsconfig: {
+        strict: true,
+        esModuleInterop: true,
+        moduleResolution: 'node',
+        paths: {},
+      },
+    },
+  },
+};