@youdu/openclaw-youdu 2026.9.15 → 2026.10.9

package/README.md

@@ -2,9 +2,30 @@
 
 有度机器人接入插件，基于 WebSocket 长连接实现消息收发。
 
-知识库 Tool 需要 OpenClaw `2026.7.1-2` 或更高版本；旧版本不提供本插件所需的 Tool hook 参数调整能力。可信有度 IM 上下文由插件按 OpenClaw `runId` 短期保存，并在本轮 dispatch 结束时清理；插件不会在注册结束后调用注册期 API。
+## 版本要求
 
-安全边界：知识库调用的短期 `invocationToken` 只由插件 hook 注入并一次性消费，不进入 CLI 请求、stdin、Tool 返回值或插件日志。OpenClaw `2026.7.1-2` 会在进程内保存调整后的参数，并将其提供给 `after_tool_call`；同时完整调整参数可能出现在宿主受控的 private diagnostic payload 和 loop-tracking 内存中。该 token 不写入模型会话 transcript，也不作为模型工具 schema 字段。宿主诊断的可见范围由 OpenClaw 控制，部署时应按受控诊断数据处理。
+| 项 | 要求 | 说明 |
+| --- | --- | --- |
+| OpenClaw | **>= 2026.7.1-2** | 与 `peerDependencies` 一致，也是插件实际开发/测试的版本（开发依赖用 2026.9.4）。本插件在旧版宿主上仍可用（见下）。 |
+| Node.js | **>=20** | 插件的 `engines`。宿主 OpenClaw 2026.9.4 自身要求 `>=24.16.0 <25 \|\| >=26.1.0`，实际部署按宿主口径；实测本插件产物在 Node 22.23.2 下也能正常加载。 |
+
+### 跨 OpenClaw 版本兼容
+
+OpenClaw 2026.9.x 调整了入站 @ 门控 API：`resolveMentionGatingWithBypass`（扁平入参）被移除，改为 `resolveInboundMentionDecision`（`{ facts, policy }` 两段式），两者**判定结果字段相同**。
+
+插件通过 `src/mention-gate.ts` 做运行时探测：优先用新 API，旧宿主回落到旧 API，两者都没有才报错。因此**升级插件不会让旧版 OpenClaw 用户失效**：
+
+| 宿主 OpenClaw | `resolveInboundMentionDecision` | `resolveMentionGatingWithBypass` | 插件行为 |
+| --- | --- | --- | --- |
+| 2026.7.1-2（实测） | 有 | 有 | 走新 API；与宿主原生判定**逐字段一致**（15/15 项对照通过） |
+| 2026.9.4（实测） | 有 | 已移除 | 走新 API |
+| 更早版本（未实测） | 未知 | 未知 | 两者都缺时报明确错误，不会静默放行或静默丢弃 |
+
+> 说明：插件对 `openclaw/plugin-sdk/*` 一律使用 `import type` 或命名空间导入 + 运行时取值，避免"宿主缺少某个导出"变成 `import` 阶段的链接失败。
+
+知识库 Tool 需要 OpenClaw 提供 Tool hook 参数调整能力（`before_tool_call` 可返回调整后的 `params`），该能力自 `2026.7.1-2` 起具备。可信有度 IM 上下文由插件按 OpenClaw `runId` 短期保存，并在本轮 dispatch 结束时清理；插件不会在注册结束后调用注册期 API。
+
+安全边界：知识库调用的短期 `invocationToken` 只由插件 hook 注入并一次性消费，不进入 CLI 请求、stdin、Tool 返回值或插件日志。OpenClaw 会在进程内保存调整后的参数，并将其提供给 `after_tool_call`；同时完整调整参数可能出现在宿主受控的 private diagnostic payload 和 loop-tracking 内存中。该 token 不写入模型会话 transcript，也不作为模型工具 schema 字段。宿主诊断的可见范围由 OpenClaw 控制，部署时应按受控诊断数据处理。
 
 ## 功能特性
 
@@ -60,13 +81,54 @@ openclaw gateway restart
 | `channels.youdu.enabled`        | 启用频道       | true / false                          | false   |
 | `channels.youdu.url`            | 有度服务器地址（纯主机名） | —                       | —       |
 | `channels.youdu.dmPolicy`       | 私聊访问策略   | pairing / open / allowlist / disabled | pairing |
-| `channels.youdu.allowFrom`      | 私聊允许列表   | —                                     | []      |
-| `channels.youdu.groups.<群ID>.requireMention` | 该群是否必须 @ 机器人 | true / false         | true    |
+| `channels.youdu.allowFrom`      | 私聊允许列表（账号名、昵称或数字 userId） | —                       | []      |
+| `channels.youdu.groupPolicy`    | 群访问策略     | open / allowlist / disabled           | open    |
+| `channels.youdu.groupAllowFrom` | 群白名单（仅 `groupPolicy=allowlist` 时生效） | 群 ID、群名或别名，`*` 表示全部 | [] |
+| `channels.youdu.aliases.groups` | 群名 → 群 ID 的显式别名 | 名称 → `{GUID}`              | —       |
+| `channels.youdu.aliases.users`  | 昵称 → 账号名/userId 的显式别名 | 名称 → 账号名或数字 userId | —    |
+| `channels.youdu.groups.<群ID或群名>.title` | 群标题（老群兜底；也用于按群名发送） | —              | —       |
+| `channels.youdu.groups.<群ID或群名>.allowFrom` | 该群内允许触发的发送者 | 账号名或昵称列表（**不接受数字 userId**），`*` 表示全部 | 全部 |
+| `channels.youdu.groups.<群ID或群名>.requireMention` | 该群是否必须 @ 机器人 | true / false         | true    |
 | `channels.youdu.groups."*".requireMention`    | 所有群的默认 @ 要求   | true / false         | true    |
-| `channels.youdu.historyLimit`   | 未被 @ 的群消息保留条数（作为下次被 @ 时的上下文） | 数字，0 表示关闭 | 50 |
+| `channels.youdu.historyLimit`   | 未被 @ 的群消息保留条数（作为下次被 @ 时的上下文）；**不配置即默认 50**，`0` 关闭 | 数字（≥0） | 50 |
+| `channels.youdu.historyMediaLimit` | 被 @ 时最多补带几张群历史**图片**（作为本轮附件交给模型，进 vision 输入）；只取 30 分钟内的，`0` 关闭 | 数字（≥0） | 4 |
+| `channels.youdu.historyFileLimit`  | 被 @ 时最多补带几个群历史**文件**（含语音/视频）作为本轮附件；`0` 关闭 | 数字（≥0） | 2 |
 | `channels.youdu.defaultAccount` | 默认账号 ID    | 任意账号 ID                            | —       |
 | `channels.youdu.accounts`       | 多账号配置     | 账号 ID → 账号级字段的映射            | —       |
 
+### 名称与别名（群 ID / 账号 与「群名 / 昵称」的对应关系）
+
+有度回调里，**用户**会同时带上账号名（`from.account`，如 `lewis.liu`）和昵称（`from.name`，如 `刘钟泽`）；
+**群**的 `msg_callback` 只有会话 ID（`{GUID}`），群名只在 `event_callback` 会话事件里下发（`data.title`）。
+插件因此维护这样一张对应关系：
+
+| 对象 | 可寻址的名字 | 权威标识 | 来源 |
+| --- | --- | --- | --- |
+| 用户 | 账号名 `lewis.liu`、昵称 `刘钟泽`、`aliases.users` 里的别名 | 单聊 chatId（= 数字 userId） | `msg_callback.from` |
+| 群 | 会话标题、`groups.<id>.title`、`aliases.groups` 里的别名 | 群会话 ID `{GUID}` | `event_callback` / 配置 |
+
+- **群名自动学习**：收到 `session_create` / `session_update` / `session_destroy` 事件时记录 `data.title`，
+  持久化后可显示（`群名 (群 ID)`）、可按群名发送、也可用于 `groupAllowFrom` 与 `groups.<群名>` 配置键。
+- **老群兜底**：机器人入群前就存在、且之后没有改名/建群事件的群，拿不到标题，用配置补：
+
+  ```bash
+  openclaw config set channels.youdu.groups.'{0798E01E-CD68-42BB-813C-EB51593BB0F5}'.title "研发讨论组"
+  # 或用别名（别名还支持与群名不同的叫法）
+  openclaw config set channels.youdu.aliases.groups.项目群 '{0798E01E-CD68-42BB-813C-EB51593BB0F5}'
+  openclaw config set channels.youdu.aliases.users.老板 boss.account
+  ```
+
+- **不做模糊匹配**：只认精确名字（大小写不敏感回退）；账号名优先于同名昵称；重名一律报错要求用 ID/账号名。
+  这是刻意的——飞书 `receive_id`、企业微信 `touser`/`chatid` 也都是 ID 优先，姓名不保证唯一。
+- **群白名单接受群名**：`groupAllowFrom` 与 `groups.<键>` 的键都可写群名或别名，群名歧义时按**拒绝**处理。
+  账号级与通道级的 `groupAllowFrom` 取**并集**，两边都不会因为另一边存在而失效。
+- **发送者白名单接受昵称**：`allowFrom`（私聊）与 `groups.<键>.allowFrom`（群内发送者）里既可以写账号名
+  （`lewis`），也可以写昵称/姓名（`刘钟泽`），还可以用 `user:` / `account:` / `name:` 前缀消歧；
+  同样是精确匹配（大小写不敏感），不做模糊匹配。账号名与昵称相同时按命中处理，无需二选一。
+  - 私聊还额外接受**数字 userId**：有度单聊的 `chatId` 就是对方 userId，`allowFrom: ["1001"]` 生效。
+  - 群内发送者白名单**只认账号名与昵称**：入站消息里群成员的标识就是账号名（`from.account`），
+    `groups.<键>.allowFrom: ["1001"]` 不会命中——要按人放行请写账号名或昵称。
+
 ### 群聊 @ 回复（默认）
 
 从本版本起，**群聊里只有 @ 了机器人的消息才会触发回复**。行为对齐 OpenClaw 其它渠道的 mention gating：
@@ -76,15 +138,24 @@ openclaw gateway restart
   仍按现有命令权限执行。
 - 送进模型前会剥掉消息里的 `@账号(显示名)` 包装，避免模型看到 @ 前缀。
 - **未被 @ 的消息不会进入会话**：不研究、不下载附件、不发"思考中"占位消息。它们只按群进入一个
-  **内存中的 pending 窗口**（默认每个群保留最近 50 条，`channels.youdu.historyLimit` 可调，`0` 关闭；
-  窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会以
-  `[Chat messages since your last reply - for context]` 的形式随当次请求一起注入，让机器人知道群里刚才说了什么。
+  **内存中的 pending 窗口**（**默认每个群保留最近 50 条，无需配置**；`channels.youdu.historyLimit` 可调，
+  `0` 关闭；窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会作为结构化历史
+  （OpenClaw 的 `InboundHistory`）随当次请求一起注入，让机器人知道群里刚才说了什么。
+- **窗口里的文件/图片会在被 @ 时补带**（只记事实、不提前下载）：被 @ 前 30 分钟内的图片最多补
+  `channels.youdu.historyMediaLimit` 张（默认 4）、文件/语音/视频最多补 `channels.youdu.historyFileLimit`
+  个（默认 2），都作为**本轮附件**交给模型（图片进 vision 输入，文件作为附件）。
+  超出时间窗口或下载失败的媒体只保留文本历史，不会拖垮这一轮回复。
+  （`requireMention: false` 的群不产生这个窗口——它每条消息都会触发一轮，会话自身就带上下文。）
+- 窗口大小按 `账号级 historyLimit` → `channels.youdu.historyLimit` → `messages.groupChat.historyLimit`
+  （OpenClaw 全局群聊配置）→ 内置默认 50 依次取值，四层都不配就是 50；多账号模式下该值在通道级共享。
+  媒体上限按 `账号级` → `通道级` → 默认（图片 4、文件 2）取值。
 - 判定能力缺失时（认证应答没有 `gid`，也没有配置 `mentionPatterns`）**宁可不回**：会记录一条错误日志并丢弃
   该消息，而不会退化成"群里全回"。
-- 想让某个群恢复"全部回复"，在该群配置里显式关闭即可：
+- 想让某个群恢复"全部回复"，在该群配置里显式关闭即可（键可以写群 ID，也可以写群名）：
 
   ```bash
   openclaw config set channels.youdu.groups.'{0798E01E-CD68-42BB-813C-EB51593BB0F5}'.requireMention false
+  openclaw config set channels.youdu.groups.'研发讨论组'.requireMention false
   ```
 
 - 群访问仍然先由 `channels.youdu.groupPolicy`（open / allowlist / disabled）控制，@ 判定在其后。
@@ -142,7 +213,7 @@ openclaw gateway restart
 - 顶层字段作为默认值：账号级未配置的字段（如 `dmPolicy`、`allowFrom`、`groupPolicy`）会继承顶层值
 - `defaultAccount` 指定默认账号；未指定时优先使用 `default` 账号，否则取第一个账号
 - 若顶层同时配置了 `botId`/`secret`/`url`，顶层凭据会作为一个独立的 `default` 账号保留（除非某个命名账号的 botId 与之重复）
-- 账号级可用字段与顶层一致：`botId`、`secret`、`url`、`enabled`、`name`、`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`sendThinkingMessage`、`mediaMaxMb`、`mediaLocalRoots`
+- 账号级可用字段与顶层一致：`botId`、`secret`、`url`、`enabled`、`name`、`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`aliases`、`sendThinkingMessage`、`mediaMaxMb`、`mediaLocalRoots`
 - 查看多账号运行状态：`openclaw channels status youdu`
 - 仅配置顶层凭据（不配置 `accounts`）时行为与之前完全一致，即为单账号模式
 
@@ -173,29 +244,46 @@ openclaw channels status youdu
 # 私聊：数字 userId 直接可用（有度单聊的 chatId 就是对方 userId）
 openclaw message send --channel youdu --to 6463894 --message "早上好"
 
-# 私聊：用账号名（需该账号先私聊过机器人，插件会记住映射）
+# 私聊：账号名，或该账号的昵称（需该账号先私聊过机器人，插件会记住映射）
 openclaw message send --channel youdu --to lewis.liu --message "早上好"
+openclaw message send --channel youdu --to 刘钟泽 --message "早上好"
+
+# 群聊：群名（会话标题 / groups.<id>.title / aliases.groups 里的名字）
+openclaw message send --channel youdu --to 研发讨论组 --message "群公告"
 
-# 群聊：直接填群 ID，或显式声明类型
+# 群聊：群 ID，或显式声明类型
 openclaw message send --channel youdu --to "group:{0798E01E-CD68-42BB-813C-EB51593BB0F5}" --message "群公告"
 ```
 
 目标解析顺序（`src/message-sender.ts` 的 `resolveOutboundTarget`）：
 
 1. 去掉 `youdu:` 前缀，以及可选的显式类型前缀 `group:` / `user:`（`single:` 亦可）；
-2. 已学到的私聊账号名 → 该账号的 chatId（单聊）；
-3. 已学到的群 ID，或形如 `{GUID}` 的群 ID → 群聊；
-4. 纯数字 → 单聊；
-5. 其余报错，并提示可用写法。
+2. 形如 `{GUID}` 的群 ID 直接按群处理（ID 是权威标识，不做名称解析）；
+3. 配置别名 `channels.youdu.aliases.users`；
+4. 已学到的私聊账号名 → 该账号的 chatId（单聊）；
+5. 群名（`aliases.groups` → 已学到的会话标题 → `groups.<id>.title`）→ 群聊；
+6. 已学到的昵称（精确匹配）→ 单聊；
+7. 纯数字 → 单聊；
+8. 其余报错，并提示可用写法。
+
+**名称撞车怎么办**（群名/昵称在服务端都不保证唯一，因此不做模糊匹配）：
+
+- 账号名优先于同名昵称：`lewis.liu` 永远解析到本人，不会被别人的同名昵称抢走；
+- 昵称重名（两个「张伟」）→ 报错并列出候选账号名，请改用账号名或数字 userId；
+- 群名重名（两个「项目群」）→ 报错并列出候选群 ID，请改用群 ID 或加 `aliases.groups` 消歧；
+- 只做精确匹配：`刘` 不会匹配 `刘钟泽`。
 
 学习与持久化（`src/target-store.ts`）：
 
-- 收到私聊消息时记录 `账号名 → chatId` 与昵称，收到群消息时记录群 ID；
+- 收到私聊消息时记录 `账号名 → chatId` 与昵称；收到群消息时记录群 ID；
+- 消费 `event_callback` 会话事件，把 `data.title` 记为群名（`session_update` 的新标题为空时回退 `oldSession.title`），
+  因此群在 `directory` 里显示为 `群名 (群 ID)`，也能直接按群名发送；
+- 老群（机器人入群前就存在、拿不到会话事件）用 `channels.youdu.groups."<群 ID>".title` 或 `aliases.groups` 兜底；
 - 记录写入 `~/.openclaw/youdu-targets.json`（权限 0600、先写临时文件再 rename、变更后去抖落盘），
   **进程重启后仍然可用**；
 - 账号从配置中移除时会一并清掉该账号的目标；
 - `openclaw channels directory youdu`（`directory.listPeers` / `listGroups`）会列出这些已聊过的联系人与群，
-  方便确认可投递目标；有度回调不下发群名，因此群只显示 ID。
+  方便确认可投递目标。
 
 > 注意：`send_msg` 必须带 `chatType`（`single`/`group`）。有度服务端只在 `chatType === 'group'`
 > 时按群会话投递，其余值一律按单聊处理，漏传会把群 ID 当成用户 ID 发成私聊。

package/dist/src/channel.js

@@ -226,22 +226,23 @@ function createYouDuPlugin(policy, monitor = monitorYouDuProvider, lifecycleObse
                     const trimmed = id?.trim();
                     return Boolean(trimmed);
                 },
-                hint: '<userId|groupId|group:<chatId>|user:<account>>',
+                hint: '<userId|account|userName|groupId|groupName|group:<chatId>|user:<account>>',
             },
         },
         directory: {
             self: async () => null,
             // 已聊过的联系人（id 就是主动发送用的 chatId；有度单聊 chatId = 对方 userId）。
             listPeers: async ({ accountId, query, limit }) => listPeers({ accountId, query, limit }),
-            // 见过消息的群；有度回调不下发群名，因此只有 ID。
+            // 见过的群：有标题时显示 `群名 (ID)`；标题来自 event_callback 或配置 groups.<id>.title。
             listGroups: async ({ accountId, query, limit }) => listGroups({ accountId, query, limit }),
         },
         outbound: {
             deliveryMode: "gateway",
             chunker: (text, limit) => getYouDuRuntime().channel.text.chunkMarkdownText(text, limit),
             textChunkLimit: TEXT_CHUNK_LIMIT,
-            sendText: async ({ to, text, accountId }) => {
+            sendText: async ({ cfg, to, text, accountId }) => {
                 return sendYouDuTextMessage({
+                    cfg,
                     to,
                     text,
                     accountId,

package/dist/src/dm-policy.d.ts

@@ -16,6 +16,8 @@ export interface DmPolicyCheckResult {
  */
 export declare function checkDmPolicy(params: {
     senderId: string;
+    /** 发送者昵称（`from.name`）：白名单里写昵称同样生效。 */
+    senderName?: string;
     isGroup: boolean;
     account: ResolvedYouDuAccount;
     wsClient: WSClient;

package/dist/src/dm-policy.js

@@ -14,7 +14,7 @@ import { sendYouDuReply } from './message-sender.js';
  * @returns 检查结果，包含是否允许继续处理
  */
 async function checkDmPolicy(params) {
-    const { senderId, isGroup, account, wsClient, frame, runtime } = params;
+    const { senderId, senderName, isGroup, account, wsClient, frame, runtime } = params;
     const core = getYouDuRuntime();
     // 群聊消息不检查 DM Policy
     if (isGroup) {
@@ -35,7 +35,7 @@ async function checkDmPolicy(params) {
         .readAllowFromStore({ channel: CHANNEL_ID, accountId: account.accountId })
         .catch(() => []);
     const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom];
-    const senderAllowedResult = isSenderAllowed(senderId, effectiveAllowFrom);
+    const senderAllowedResult = isSenderAllowed(senderId, senderName, effectiveAllowFrom);
     if (senderAllowedResult) {
         return { allowed: true };
     }

package/dist/src/event-callback.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 有度 `event_callback` 会话事件解析。
+ *
+ * 群名只在会话事件里下发（`msg_callback` 只有 chatId/sessionId），所以插件必须消费
+ * 这一路：`session_create` / `session_destroy` / `session_update` 的 `data.title`。
+ *
+ * 服务端历史版本用 snake_case（`event_type` / `sessionid`），当前版本用 camelCase
+ * （`eventType` / `sessionId`），协议明确不再兼容旧字段名，但事件是**推送**的，
+ * 插件跨版本在线时两种都可能收到，所以这里两种都读。
+ */
+/** 我们需要的一小段事实：哪个会话、标题是什么、是群还是单聊。 */
+export interface YouduSessionEventInfo {
+    sessionId: string;
+    title: string;
+    /**
+     * `data.type`（服务端下发 `group` / `direct`）。
+     *
+     * 有度的「讨论组」也是多人会话，但它是 direct 语义、标题形如 `xxx创建的讨论组`；
+     * 只有真正按群会话投递（`chatType=group`）的会话才该进群存储，否则单聊的数字会话
+     * ID 会被误判成群，回复走错通道。
+     */
+    chatType: "group" | "direct";
+}
+/**
+ * 会话事件的排序戳：优先 `version`（服务端按版本单调递增，重命名后递增），
+ * 其次 `createTime`。两者都没有时返回 0，由调用方回落到本地时间。
+ */
+export declare function sessionEventStamp(body: unknown): number;
+/**
+ * 解析一帧 `event_callback` 的 `body`。
+ *
+ * 返回 `null` 表示这条事件与群标题无关（未知事件类型、缺 sessionId），调用方直接忽略。
+ */
+export declare function parseSessionEvent(body: unknown, onUnknownEventType?: (eventType: string) => void): YouduSessionEventInfo | null;

package/dist/src/event-callback.js

@@ -0,0 +1,105 @@
+/*
+* Licensed under the MIT License.
+*/
+const SESSION_EVENT_TYPES = new Set(["session_create", "session_destroy", "session_update"]);
+/**
+ * 事件类型归一化。
+ *
+ * 服务端 `ng_bot` 实际下发小写下划线（`session_create` / `session_update` / `session_destroy`，
+ * 见 `nsq_msg_consumer.go` 的 `makeSessionEventEnvelope`），但仓库的协议文档示例写的是
+ * `sessionUpdated` 这类 camelCase。两种都接受，避免文档变更时插件静默失效。
+ */
+function normalizeEventType(value) {
+    const raw = value.trim();
+    if (!raw)
+        return "";
+    const snake = raw
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[\s-]+/g, "_")
+        .toLowerCase();
+    const aliases = {
+        // 下划线形态
+        session_create: "session_create",
+        session_destroy: "session_destroy",
+        session_update: "session_update",
+        // camelCase 形态（转换后为 session_created / session_updated）
+        session_created: "session_create",
+        session_destroyed: "session_destroy",
+        session_updated: "session_update",
+    };
+    return aliases[snake] ?? snake;
+}
+/** `data.type` 只有明确是群时才当群，其余（含缺失）按 direct。 */
+function normalizeSessionChatType(value) {
+    return value.toLowerCase() === "group" ? "group" : "direct";
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+/** 读第一个非空字符串字段（键名区分大小写，按传入顺序）。 */
+function readString(source, ...keys) {
+    for (const key of keys) {
+        const value = source[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return "";
+}
+/**
+ * 会话事件的排序戳：优先 `version`（服务端按版本单调递增，重命名后递增），
+ * 其次 `createTime`。两者都没有时返回 0，由调用方回落到本地时间。
+ */
+function sessionEventStamp(body) {
+    const record = asRecord(body);
+    if (!record)
+        return 0;
+    for (const key of ["version", "createTime", "create_time"]) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value) && value > 0)
+            return value;
+        if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) {
+            const parsed = Number(value);
+            if (parsed > 0)
+                return parsed;
+        }
+    }
+    return 0;
+}
+/**
+ * 解析一帧 `event_callback` 的 `body`。
+ *
+ * 返回 `null` 表示这条事件与群标题无关（未知事件类型、缺 sessionId），调用方直接忽略。
+ */
+function parseSessionEvent(body, onUnknownEventType) {
+    const record = asRecord(body);
+    if (!record)
+        return null;
+    const rawEventType = readString(record, "eventType", "event_type");
+    const eventType = normalizeEventType(rawEventType);
+    if (!SESSION_EVENT_TYPES.has(eventType)) {
+        // 未知事件类型静默丢弃会掩盖协议漂移（例如服务端改名、文档示例与实现不一致）。
+        if (rawEventType)
+            onUnknownEventType?.(rawEventType);
+        return null;
+    }
+    const sessionId = readString(record, "sessionId", "sessionid", "session_id");
+    if (!sessionId)
+        return null;
+    const data = asRecord(record.data);
+    let title = data ? readString(data, "title") : "";
+    if (!title && data) {
+        // session_update 重命名时新标题可能为空，回退到变更前的标题，避免标题被清掉。
+        const oldSession = asRecord(data.oldSession) ?? asRecord(data.old_session);
+        if (oldSession)
+            title = readString(oldSession, "title");
+    }
+    return {
+        sessionId,
+        title,
+        chatType: normalizeSessionChatType(data ? readString(data, "type") : ""),
+    };
+}
+
+export { parseSessionEvent, sessionEventStamp };

package/dist/src/group-history.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 群聊 pending 历史窗口：未被 @ 的群消息在这里排队，等下一次被 @ 时作为上下文交给模型。
+ *
+ * 两条通道，各管一件事：
+ * - **文本历史**走宿主的 `InboundHistory`：宿主渲染成 "Chat history since last reply:" 块（含
+ *   "把人类写的名字/群名/引用/历史当不可信内容" 的说明），并保留条目里的媒体类型标注。
+ * - **媒体本体**走**当前轮** `ctx.media`：图片和文件一样，都必须在这里，宿主才会读。
+ *   注意宿主的"最近历史图片"通道（`InboundHistory[].media` + 本地 path）**默认回复链路是关的**
+ *   （`current-turn-images` 显式传 `includeRecentHistoryImages: false`，只有 ACP 绑定会话才开），
+ *   所以不能把图片塞进历史条目就指望它到模型。
+ *
+ * 记录时**不下载**：跳过消息可能在群里刷很久而机器人一次都没被 @，下载全部媒体是纯浪费。
+ * 只有真正触发一轮时，才按时间窗口和上限把这几条媒体拉下来，作为本轮附件附上。
+ */
+import { type HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { Youdu } from './media.js';
+/**
+ * 补带历史媒体的时间窗口：只把"刚刚发的"算作本轮上下文。
+ *
+ * 这是插件自己的策略（不是宿主常量）：群里半小时前的图不该冒充当前这句 @ 的附件。
+ */
+export declare const HISTORY_MEDIA_TTL_MS: number;
+/** 被 @ 时最多补带几张历史图片。 */
+export declare const DEFAULT_HISTORY_IMAGE_LIMIT = 4;
+/** 被 @ 时最多补带几个历史文件（含语音/视频）。 */
+export declare const DEFAULT_HISTORY_FILE_LIMIT = 2;
+/** 宿主的 `MediaKind`（openclaw dist/constants）。有度没有 sticker/unknown，文件在宿主口径里叫 document。 */
+export type HostMediaKind = 'image' | 'audio' | 'video' | 'document' | 'sticker' | 'unknown';
+/** 一条跳过消息带过的媒体事实：记录时不下载，只记够下载用的东西。 */
+export interface PendingMediaFact {
+    mediaId: string;
+    /** 宿主口径的媒体类型；下载时再用 `toYouduDownloadKind` 换回有度的 `kind` 参数。 */
+    kind: HostMediaKind;
+    name?: string;
+    contentType?: string;
+    /** 下载完成后回填；宿主的 history 图片通道只认本地 path。 */
+    path?: string;
+}
+/** One skipped group message kept for the next addressed turn. */
+export interface PendingGroupEntry {
+    sender: string;
+    body: string;
+    timestamp?: number;
+    messageId?: string;
+    /** 这条消息带的媒体（未下载）。 */
+    media?: PendingMediaFact[];
+}
+/** 从窗口里挑出的一条待下载媒体。 */
+export interface PendingMediaSelection {
+    entryIndex: number;
+    factIndex: number;
+    fact: PendingMediaFact;
+}
+/**
+ * Pending-window size: account → channel → `messages.groupChat` → fallback, clamped at 0.
+ * A resolved 0 disables recording, injection, and clearing in the shared helpers.
+ */
+export declare function resolveHistoryLimit(params: {
+    accountHistoryLimit?: unknown;
+    channelHistoryLimit?: unknown;
+    globalHistoryLimit?: unknown;
+    fallback: number;
+}): number;
+/** One pending entry, or null when the message carries nothing worth replaying. */
+export declare function pendingHistoryEntry(params: {
+    messageId?: string;
+    sender?: string;
+    body?: string;
+    timestamp?: number;
+    media?: readonly PendingMediaFact[];
+}): PendingGroupEntry | null;
+/** A redelivered frame must not fill the window with duplicates of the same message. */
+export declare function shouldRecordPendingEntry(entries: readonly PendingGroupEntry[] | undefined, messageId?: string): boolean;
+/**
+ * 取走窗口里当前这批条目：**注入即认领**。
+ *
+ * 比"run 结束再整段清空"更准：这一轮跑着的时候群里新到的消息属于下一次触发，不会被收尾顺手清掉；
+ * 同一批也不会被并发的两轮各注入一次。窗口本身就是内存态（进程重启即丢），所以"认领后这一轮
+ * 挂了就少了这批上下文"与原来"run 结束一律清空"的后果相同。
+ */
+export declare function claimPendingEntries(params: {
+    historyMap: Map<string, PendingGroupEntry[]>;
+    historyKey: string;
+}): PendingGroupEntry[];
+/**
+ * 把解析出的入站媒体变成窗口里的事实，只保留能下载的（有 mediaId）。
+ */
+export declare function mediaFactsForAttachments(attachments: readonly Youdu.InboundMediaAttachment[] | undefined): PendingMediaFact[];
+/** 有度的 `file` 在宿主里是 `document`，其余同名。 */
+export declare function toHostMediaKind(kind: Youdu.InboundMediaAttachment['kind']): HostMediaKind;
+/** 下载 URL 的 `kind` 参数只认有度自己的取值（`GET /cgi/bot/file/download?kind=…`）。 */
+export declare function toYouduDownloadKind(kind: HostMediaKind): Youdu.InboundMediaAttachment['kind'];
+/**
+ * 挑出要补带的历史媒体：最新优先，图片和文件各自计数，条目时间必须落在补带窗口内。
+ *
+ * 时间用 `Math.abs` 比较，和宿主处理"最近历史"时的口径一致：服务端时钟略快、条目时间比当前消息
+ * 晚几秒时，不该把它判成过期。
+ */
+export declare function selectPendingMedia(params: {
+    entries: readonly PendingGroupEntry[];
+    nowMs: number;
+    ttlMs?: number;
+    imageLimit: number;
+    fileLimit: number;
+}): {
+    images: PendingMediaSelection[];
+    files: PendingMediaSelection[];
+};
+/** 下载成功的一条历史媒体。 */
+export interface DownloadedHistoryMedia {
+    selection: PendingMediaSelection;
+    path: string;
+    contentType?: string;
+}
+/** 作为**当前轮**媒体附上的 canonical fact（宿主的 `ctx.media` 口径）。 */
+export interface TurnMediaFact {
+    path: string;
+    contentType?: string;
+    kind: HostMediaKind;
+    fileName?: string;
+}
+/** 下载结果 → 当前轮媒体 fact（图片和文件都走这里，宿主只读 `ctx.media`）。 */
+export declare function turnMediaFacts(downloads: readonly DownloadedHistoryMedia[]): TurnMediaFact[];
+/**
+ * 一轮投递要用的群上下文：把窗口里该带的媒体下载下来，产出
+ * `InboundHistory`（文本历史）和 `turnMedia`（本轮附件，图片+文件）。
+ *
+ * 下载函数由调用方注入（真实实现走有度 HTTP 下载），单条失败不抛：历史文本仍然保留，
+ * 模型至少知道谁在什么时候发过东西。
+ */
+export declare function resolveHistoryForTurn(params: {
+    entries: readonly PendingGroupEntry[];
+    nowMs: number;
+    imageLimit: number;
+    fileLimit: number;
+    ttlMs?: number;
+    download: (fact: PendingMediaFact) => Promise<{
+        path: string;
+        contentType?: string;
+    }>;
+}): Promise<{
+    inboundHistory: HistoryEntry[] | undefined;
+    turnMedia: TurnMediaFact[];
+}>;