@youdu/openclaw-youdu 2026.9.15 → 2026.9.16

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,52 @@ 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.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 +136,18 @@ openclaw gateway restart
   仍按现有命令权限执行。
 - 送进模型前会剥掉消息里的 `@账号(显示名)` 包装，避免模型看到 @ 前缀。
 - **未被 @ 的消息不会进入会话**：不研究、不下载附件、不发"思考中"占位消息。它们只按群进入一个
-  **内存中的 pending 窗口**（默认每个群保留最近 50 条，`channels.youdu.historyLimit` 可调，`0` 关闭；
-  窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会以
+  **内存中的 pending 窗口**（**默认每个群保留最近 50 条，无需配置**；`channels.youdu.historyLimit` 可调，
+  `0` 关闭；窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会以
   `[Chat messages since your last reply - for context]` 的形式随当次请求一起注入，让机器人知道群里刚才说了什么。
+- 窗口大小按 `账号级 historyLimit` → `channels.youdu.historyLimit` → `messages.groupChat.historyLimit`
+  （OpenClaw 全局群聊配置）→ 内置默认 50 依次取值，四层都不配就是 50；多账号模式下该值在通道级共享。
 - 判定能力缺失时（认证应答没有 `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 +205,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 +236,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-policy.d.ts

@@ -1,6 +1,6 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
-import type { ResolvedYouDuAccount } from "./utils.js";
+import type { ResolvedYouDuAccount, YouDuGroupConfig } from "./utils.js";
 /**
  * 群组策略检查结果
  */
@@ -15,11 +15,35 @@ export interface GroupPolicyCheckResult {
 export declare function checkGroupPolicy(params: {
     chatId: string;
     senderId: string;
+    /** 发送者昵称（`from.name`）；与账号名一样可写在白名单里。 */
+    senderName?: string;
     account: ResolvedYouDuAccount;
     config: OpenClawConfig;
     runtime: RuntimeEnv;
+    /** 账号 ID（多账号时用于读取该账号的别名表）。 */
+    accountId?: string | null;
+    /**
+     * 生效的 `groups` 配置表（已合并顶层与账号级、键可写群 ID 或群名）。
+     *
+     * 显式传入以免再按账号 ID 反查配置：测试与多账号场景下更可预测。
+     */
+    groups?: Record<string, YouDuGroupConfig>;
 }): GroupPolicyCheckResult;
 /**
- * 检查发送者是否在允许列表中（通用）
+ * 解析该群生效的 `requireMention`（`groups.<群 ID 或群名>` 优先，其次 `"*"`，默认 true）。
  */
-export declare function isSenderAllowed(senderId: string, allowFrom: string[]): boolean;
+export declare function resolveGroupRequireMentionFor(params: {
+    config: OpenClawConfig;
+    accountId?: string | null;
+    chatId: string;
+    /** 生效的 `groups` 配置表（已合并顶层与账号级）；省略时只读通道顶层配置。 */
+    groups?: Record<string, YouDuGroupConfig>;
+    fallback?: (groups: unknown, chatId: string) => boolean;
+}): boolean;
+/**
+ * 检查发送者是否在允许列表中（通用）。
+ *
+ * `senderId` 是发送者账号名，`senderName` 是昵称（姓名）——两者都是该发送者的可读标识，
+ * 所以 `allowFrom` 里写账号名或写昵称都命中；`*` 放行全部。
+ */
+export declare function isSenderAllowed(senderId: string, senderName?: string, allowFrom?: string[]): boolean;

package/dist/src/group-policy.js

@@ -1,4 +1,6 @@
 import { CHANNEL_ID } from './const.js';
+import { resolveYouDuAliases } from './utils.js';
+import { findGroupConfigEntry, isGroupIdShape, resolveGroupReference } from './group-resolve.js';
 
 /*
 * Licensed under the MIT License.
@@ -6,23 +8,62 @@ import { CHANNEL_ID } from './const.js';
 // ============================================================================
 // 内部辅助函数
 // ============================================================================
-function resolveWeComGroupConfig(params) {
-    const groups = params.cfg?.groups ?? {};
-    const wildcard = groups["*"];
-    const groupId = params.groupId?.trim();
-    if (!groupId) {
-        return undefined;
-    }
-    const direct = groups[groupId];
-    if (direct) {
-        return direct;
-    }
-    const lowered = groupId.toLowerCase();
-    const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
-    if (matchKey) {
-        return groups[matchKey];
-    }
-    return wildcard;
+function normalize(value) {
+    return String(value ?? "").trim();
+}
+function equalsIgnoreCase(left, right) {
+    return left.toLowerCase() === right.toLowerCase();
+}
+/**
+ * 一条发送者白名单条目是否命中该发送者。
+ *
+ * 可写：账号名、昵称（姓名）、数字 userId，也可加 `user:` / `account:` / `name:` 前缀消歧。
+ * 只做精确匹配（大小写不敏感回退），不做前缀/模糊匹配。
+ */
+function senderEntryMatches(entry, senderId, senderName) {
+    const normalized = normalize(entry)
+        .replace(new RegExp(`^${CHANNEL_ID}:`, "i"), "")
+        .trim();
+    if (!normalized)
+        return false;
+    const prefixed = /^(user|account|name):(.*)$/i.exec(normalized);
+    const kind = prefixed?.[1].toLowerCase();
+    const value = (prefixed ? prefixed[2] : normalized).trim();
+    if (!value)
+        return false;
+    const account = normalize(senderId);
+    const name = normalize(senderName);
+    if (kind === "name")
+        return Boolean(name) && equalsIgnoreCase(value, name);
+    if (kind === "user" || kind === "account")
+        return Boolean(account) && equalsIgnoreCase(value, account);
+    return (Boolean(account) && equalsIgnoreCase(value, account))
+        || (Boolean(name) && equalsIgnoreCase(value, name));
+}
+/**
+ * 一条白名单条目是否指向这个群。
+ *
+ * 条目可以是群 ID，也可以是群名/别名：先按 ID 形态直比，再做名称解析。
+ * 名称解析歧义（`ambiguous`）时视为**不匹配**——白名单是安全边界，宁可拒绝。
+ */
+function allowEntryMatchesGroup(params) {
+    const entry = normalize(params.entry);
+    const groupId = normalize(params.groupId);
+    if (!entry || !groupId)
+        return false;
+    if (entry === groupId)
+        return true;
+    if (entry.toLowerCase() === groupId.toLowerCase())
+        return true;
+    if (isGroupIdShape(entry))
+        return false;
+    const resolution = resolveGroupReference({
+        accountId: params.accountId,
+        target: entry,
+        aliases: params.aliases,
+        groups: params.groups,
+    });
+    return resolution.status === "resolved" && resolution.groupId === groupId;
 }
 /**
  * 检查群组是否在允许列表中
@@ -40,18 +81,34 @@ function isYouDuGroupAllowed(params) {
     if (normalizedAllowFrom.includes("*")) {
         return true;
     }
-    const normalizedGroupId = params.groupId.trim();
-    return normalizedAllowFrom.some((entry) => entry === normalizedGroupId || entry.toLowerCase() === normalizedGroupId.toLowerCase());
+    return normalizedAllowFrom.some((entry) => allowEntryMatchesGroup({
+        entry,
+        groupId: params.groupId,
+        accountId: params.accountId,
+        groups: params.groups,
+        aliases: params.aliases,
+    }));
 }
 /**
- * 检查群组内发送者是否在允许列表中
+ * 检查群组内发送者是否在允许列表中。
+ *
+ * 条目可以是发送者的账号名或昵称（姓名）；两者都是标识该发送者的名字，
+ * 所以白名单里写哪个都生效。只做精确匹配（大小写不敏感）。
  */
 function isGroupSenderAllowed(params) {
-    const { senderId, groupId, youduConfig } = params;
-    const groupConfig = resolveWeComGroupConfig({
-        cfg: youduConfig,
+    const { senderId, senderName, groupId, groups } = params;
+    const matched = findGroupConfigEntry({
         groupId,
+        accountId: params.accountId,
+        groups,
+        aliases: params.aliases,
     });
+    if (matched.ambiguous) {
+        // 两个群同名且都配了发送者白名单：无法判定该用哪一份，拒绝。
+        params.runtime?.log?.(`[youdu] Group ${groupId} matches multiple configured group names; denying sender check`);
+        return false;
+    }
+    const groupConfig = matched.entry ?? groups?.["*"];
     const perGroupSenderAllowFrom = (groupConfig?.allowFrom ?? []).map((v) => String(v));
     if (perGroupSenderAllowFrom.length === 0) {
         return true;
@@ -59,10 +116,7 @@ function isGroupSenderAllowed(params) {
     if (perGroupSenderAllowFrom.includes("*")) {
         return true;
     }
-    return perGroupSenderAllowFrom.some((entry) => {
-        const normalized = entry.replace(new RegExp(`^${CHANNEL_ID}:`, "i"), "").trim();
-        return normalized === senderId || normalized === `user:${senderId}`;
-    });
+    return perGroupSenderAllowFrom.some((entry) => senderEntryMatches(entry, senderId, senderName));
 }
 // ============================================================================
 // 公开 API
@@ -73,14 +127,25 @@ function isGroupSenderAllowed(params) {
  */
 function checkGroupPolicy(params) {
     const { chatId, senderId, account, config, runtime } = params;
+    const accountId = params.accountId ?? account.accountId;
     const youduConfig = (config.channels?.[CHANNEL_ID] ?? {});
+    const aliases = resolveYouDuAliases(config, accountId);
+    const groups = params.groups ?? (account.config.groups ?? youduConfig.groups ?? {});
     const defaultGroupPolicy = config.channels?.[CHANNEL_ID]?.groupPolicy;
     const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
-    const groupAllowFrom = youduConfig.groupAllowFrom ?? [];
+    // 账号级与通道级取并集：两者都配时不会因为"账号级优先"而丢掉通道级白名单，
+    // 同时账号级条目自然生效（与 README 的"账号级优先"不冲突——并集下账号级永远不会被挡住）。
+    const groupAllowFrom = [
+        ...(account.config.groupAllowFrom ?? []),
+        ...(youduConfig.groupAllowFrom ?? []),
+    ];
     const groupAllowed = isYouDuGroupAllowed({
         groupPolicy,
         allowFrom: groupAllowFrom,
         groupId: chatId,
+        accountId,
+        groups,
+        aliases,
     });
     if (!groupAllowed) {
         runtime.log?.(`[youdu] Group ${chatId} not allowed (groupPolicy=${groupPolicy})`);
@@ -88,8 +153,12 @@ function checkGroupPolicy(params) {
     }
     const senderAllowed = isGroupSenderAllowed({
         senderId,
+        senderName: params.senderName,
         groupId: chatId,
-        youduConfig,
+        accountId,
+        groups,
+        aliases,
+        runtime,
     });
     if (!senderAllowed) {
         runtime.log?.(`[youdu] Sender ${senderId} not in group ${chatId} sender allowlist`);
@@ -98,16 +167,39 @@ function checkGroupPolicy(params) {
     return { allowed: true };
 }
 /**
- * 检查发送者是否在允许列表中（通用）
+ * 解析该群生效的 `requireMention`（`groups.<群 ID 或群名>` 优先，其次 `"*"`，默认 true）。
  */
-function isSenderAllowed(senderId, allowFrom) {
+function resolveGroupRequireMentionFor(params) {
+    const resolvedAccountId = params.accountId ?? "";
+    const youduConfig = (params.config.channels?.[CHANNEL_ID] ?? {});
+    const groups = params.groups ?? youduConfig.groups ?? {};
+    const matched = findGroupConfigEntry({
+        groupId: params.chatId,
+        accountId: resolvedAccountId,
+        groups,
+        aliases: resolveYouDuAliases(params.config, resolvedAccountId),
+    });
+    if (matched.ambiguous)
+        return true;
+    if (matched.entry && typeof matched.entry === "object") {
+        const value = matched.entry.requireMention;
+        if (typeof value === "boolean")
+            return value;
+    }
+    // 没命中具体条目时按纯函数规则处理（`"*"` → 默认 true）。
+    return params.fallback ? params.fallback(groups, params.chatId) : true;
+}
+/**
+ * 检查发送者是否在允许列表中（通用）。
+ *
+ * `senderId` 是发送者账号名，`senderName` 是昵称（姓名）——两者都是该发送者的可读标识，
+ * 所以 `allowFrom` 里写账号名或写昵称都命中；`*` 放行全部。
+ */
+function isSenderAllowed(senderId, senderName, allowFrom = []) {
     if (allowFrom.includes("*")) {
         return true;
     }
-    return allowFrom.some((entry) => {
-        const normalized = entry.replace(new RegExp(`^${CHANNEL_ID}:`, "i"), "").trim();
-        return normalized === senderId || normalized === `user:${senderId}`;
-    });
+    return allowFrom.some((entry) => senderEntryMatches(entry, senderId, senderName));
 }
 
-export { checkGroupPolicy, isSenderAllowed };
+export { checkGroupPolicy, isSenderAllowed, resolveGroupRequireMentionFor };