@soimy/dingtalk 3.3.0 → 3.4.1

package/README.md

@@ -39,6 +39,7 @@
 - [使用示例](#使用示例)
 - [故障排除](#故障排除)
 - [开发指南](#开发指南)
+- [架构与职责边界](#架构与职责边界)
 - [测试](#测试)
 - [许可](#许可)
 
@@ -54,6 +55,54 @@
 - ✅ **Markdown 表格兼容** — 自动把 Markdown 表格转换为钉钉更稳定的可读文本
 - ✅ **互动卡片** — 支持流式更新，适用于 AI 实时输出
 - ✅ **完整 AI 对话** — 接入 Clawdbot 消息处理管道
+- ✅ **@多助手路由** — 在群聊中通过 `@助手名` 路由到不同的 agent（实验性功能）
+
+### @多助手路由（实验性）
+
+> ⚠️ **实验性功能**：此功能使用框架层 `agents.list` 配置实现，与框架的 `bindings` 机制独立运作。
+
+在群聊中，用户可以通过 `@助手名` 来指定要对话的 agent。每个 agent 拥有独立的 session。
+
+```
+用户: @frontend 帮我看看这个组件的问题
+[frontend] 好的，请贴出代码...
+
+用户: @dba 数据库慢查询怎么处理？
+[dba] 从数据库角度分析...
+```
+
+#### 配置方式
+
+在 OpenClaw 配置文件中配置 `agents.list`：
+
+```json
+{
+  "agents": {
+    "list": [
+      { "id": "main", "name": "助手", "default": true },
+      { "id": "frontend", "name": "前端专家" },
+      { "id": "dba", "name": "DBA" }
+    ]
+  }
+}
+```
+
+#### 当前功能范围
+
+- @mention 解析 → agent 名匹配（支持 `name` 和 `id`）
+- 路由到独立 agent session
+- 回复自动添加 `[助手名]` 前缀
+
+#### 后续迭代计划
+
+- 群聊历史上下文注入（被 @ 的 agent 能看到近期对话）
+- 多专家协作讨论（专家间链式 @mention、讨论记录共享）
+- `/agents` 命令列出可用专家
+
+#### 已知限制
+
+- sub-agent 路由使用框架的 `buildAgentSessionKey` API，不通过 `bindings` 配置匹配
+- 与框架顶层的 `bindings` 配置**独立运作**，同时配置两者可能导致混淆
 
 ### 进程级（memory-only）运行态说明
 
@@ -374,6 +423,7 @@ openclaw configure --section channels
       "agentId": "123456789",
       "dmPolicy": "open",
       "groupPolicy": "open",
+      "displayNameResolution": "disabled", // 或 "all"；启用后可能因重名/旧名称/权限边界限制导致误解析
       "journalTTLDays": 7,
       "ackReaction": "🤔思考中", // 给原消息贴处理中的表情反馈；设为 "" 可关闭
       "debug": false,
@@ -409,8 +459,11 @@ openclaw gateway restart
 | `corpId`                | string   | -            | 企业 ID                                     |
 | `agentId`               | string   | -            | 应用 ID                                     |
 | `dmPolicy`              | string   | `"open"`     | 私聊策略：open/pairing/allowlist            |
-| `groupPolicy`           | string   | `"open"`     | 群聊策略：open/allowlist                    |
-| `allowFrom`             | string[] | `[]`         | 允许的发送者 ID 列表                        |
+| `groupPolicy`           | string   | `"open"`     | 群聊策略：open/allowlist/disabled           |
+| `allowFrom`             | string[] | `[]`         | 允许的发送者 ID 列表（仅私聊）              |
+| `groupAllowFrom`        | string[] | -            | 群聊发送者白名单（全局）                    |
+| `groups`                | object   | -            | 按 conversationId 的群级配置，详见[群聊策略](#群聊策略-grouppolicy) |
+| `displayNameResolution` | string   | `"disabled"` | 基于本地通讯录存储的显示名/群名解析开关：disabled/all |
 | `bypassProxyForSend`    | boolean  | `false`      | 发送链路直连，不走全局代理                  |
 | `learningEnabled`       | boolean  | `false`      | 开启学习信号采集与学习提示注入              |
 | `learningAutoApply`     | boolean  | `false`      | 自动将学习笔记注入当前会话                  |
@@ -430,6 +483,16 @@ openclaw gateway restart
 | `maxReconnectDelay`     | number   | `60000`      | 最大重连延迟（毫秒）                        |
 | `reconnectJitter`       | number   | `0.3`        | 重连延迟抖动因子（0-1）                     |
 
+关于 `displayNameResolution`：
+
+- `disabled`：默认值。发送目标必须使用显式 ID，例如 `conversationId`、`staffId`、`user:manager8031`
+- `all`：允许插件使用本地通讯录存储做群显示名/用户显示名解析
+- learned directory 数据来自入站消息观测，并按 `accountId` 落盘到 `targets.directory`
+- 当前上游 target resolver 还没有把 requester owner/authz 上下文传到插件，因此暂不提供 owner-only 模式
+- 开启后存在误投风险：显示名可能重名、后来改名，或本地目录还停留在旧观测值
+- 开启后存在权限扩散风险：当前 `all` 会对所有能进入发送链路的调用方生效，不是 owner-only
+- 对敏感通知、不可撤回消息或高风险自动化，建议继续使用显式 ID 而不是显示名
+
 ### 钉钉原生“思考中”表情反馈
 
 当 `ackReaction` 为非空字符串时，插件会在处理开始时给用户原消息添加一条钉钉原生文本表情反馈，并在处理结束后自动撤回。该增强不会阻断主流程：贴表情或撤表情失败时只记录日志，仍继续正常回复。
@@ -443,9 +506,12 @@ openclaw gateway restart
 - 该反馈作用于用户原消息，不会额外发送一条“思考中”消息
 - 解析顺序与官方一致：`channels.dingtalk.accounts.<accountId>.ackReaction` -> `channels.dingtalk.ackReaction` -> `messages.ackReaction` -> `agents.list[].identity.emoji`
 - 若上述路径都未配置，则不发送 ack reaction
-- 当最终解析值为 `emoji` 时，钉钉插件会按当前输入语气自动选择一条颜文字 reaction
+- 当最终解析值为 `emoji` 时，钉钉插件会贴固定的 `🤔思考中` 原生 reaction，并允许后续 tool-progress 流程动态切换
+- 当最终解析值为 `kaomoji` 时，钉钉插件会先按输入语气选一条颜文字作为初始 reaction；若后续进入 `read/search/bash/write` 等工具阶段，仍会临时切换到对应的 tool-progress reaction
+- 为兼容历史配置，`ackReaction: ""` 仍然表示关闭该能力；若你此前把 `ackReaction: "emoji"` 当作“按语气选颜文字”，升级后请改成 `ackReaction: "kaomoji"`
 - 当前钉钉实现底层走 `emotion/reply` / `emotion/recall`，会把解析出的 `ackReaction` 文本原样写入 `emotionName` / `textEmotion.emotionName`
 - 若配置值为 `🤔思考中`，效果与钉钉原生“思考中”反馈一致；配置为其他文本时，会按该文本发送对应的 ack reaction
+- 钉钉 `emotion/reply` 对部分 kaomoji 存在兼容性限制。当前候选集已按真实 API 多轮复测做过筛选，并移除了会稳定触发 `500 system.err` 的字符串，例如 `٩(๑>◡<๑)۶`、`(•̀へ •́ ╮ )`、`(´• ω •`)`、`(づ｡◕‿‿◕｡)づ`、`(⁄ ⁄•⁄ω⁄•⁄ ⁄)`、`┌（┌ *｀д´）┐`
 
 示例：
 
@@ -453,7 +519,7 @@ openclaw gateway restart
 {
   "channels": {
     "dingtalk": {
-      "ackReaction": "emoji"
+      "ackReaction": "kaomoji"
     }
   }
 }
@@ -725,7 +791,53 @@ node scripts/feedback-learning-debug.mjs --storePath /path/to/session-store.json
 ### 群聊策略 (groupPolicy)
 
 - `open` — 任何群都可以 @机器人
-- `allowlist` — 只有配置的群可以使用
+- `allowlist` — 只有配置的群可以使用（见下方详细说明）
+- `disabled` — 完全禁用群聊消息（消息静默丢弃，不会发送拒绝提示）
+
+#### allowlist 模式详解
+
+当 `groupPolicy` 设为 `"allowlist"` 时，群聊准入按以下顺序判定：
+
+1. **群 ID 检查**：`groups` 中存在该 `conversationId` 的配置 → 放行
+2. **通配符**：`groups` 中存在 `"*"` 配置 → 放行
+3. **旧版兜底**：`allowFrom` 中包含该群 ID → 放行（已弃用，会输出迁移提示）
+4. 以上均不匹配 → 拒绝
+
+##### 发送者白名单 (groupAllowFrom)
+
+群准入通过后，还可以限制允许发言的用户。优先级：
+
+1. `groups[conversationId].groupAllowFrom` — 群级白名单（最高优先）
+2. `groups["*"].groupAllowFrom` — 通配符级白名单
+3. 顶层 `groupAllowFrom` — 全局白名单
+4. 以上均未配置 → 不限制发送者
+
+##### 每群 requireMention
+
+可在 `groups` 中为每个群单独配置是否需要 @机器人才响应：
+
+```jsonc
+{
+  "groupPolicy": "allowlist",
+  "groupAllowFrom": ["user-001", "user-002"],  // 全局群聊发送者白名单
+  "groups": {
+    "cidXXX": {
+      "systemPrompt": "你是客服机器人",  // 群级 system prompt
+      "requireMention": false,           // 不需要 @，直接响应
+      "groupAllowFrom": ["user-003"]     // 群级发送者白名单（覆盖全局）
+    },
+    "*": {
+      "requireMention": true             // 其他群默认需要 @
+    }
+  }
+}
+```
+
+> 注意：钉钉群聊中不 @机器人时不会推送消息，因此 `requireMention: false` 在钉钉群聊中实际不生效。
+
+> **迁移提示**：如果你目前使用 `allowFrom` 同时控制私聊用户和群聊群 ID，
+> 建议将群 ID 迁移到 `groups` 配置中，将群聊发送者 ID 迁移到 `groupAllowFrom`。
+> 旧的 `allowFrom` 群 ID 兜底机制仍可工作，但会在日志中输出弃用警告。
 
 ## 消息类型支持
 
@@ -928,6 +1040,10 @@ node scripts/feedback-learning-debug.mjs --storePath /path/to/session-store.json
 2. 使用 `/v1.0/card/streaming` 实现流式更新
 3. 自动状态管理（PROCESSING → INPUTING → FINISHED）
 4. 内置 300ms 节流 + 单航班（single-flight）保护，避免 API 过载
+5. 默认为 AI Card 投递开启 `dynamicSummary`，改善钉钉会话列表 `lastmsg` 预览随卡片正文更新的表现
+
+> `dynamicSummary` 这项接入思路参考自 `DingTalk-Real-AI/dingtalk-openclaw-connector` 的 MIT 许可实现：
+> <https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/commit/7aff25b1f77f4dbd5dd64673d4e726ca938f5498>
 
 **卡片流式模式 (`cardRealTimeStream`)：**
 
@@ -1343,15 +1459,28 @@ await sendProactiveMedia(config, 'cidxxxxxxxx', '/absolute/path/to/photo.png', '
 });
 ```
 
-### 架构
+## 架构与职责边界
+
+仓库整体架构、模块职责边界、增量迁移策略和新功能落位建议，以 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 为准。
+中文版本见 [`docs/ARCHITECTURE.zh-CN.md`](docs/ARCHITECTURE.zh-CN.md)。
+
+协作时建议优先把握这些总原则：
+
+- 先遵守逻辑功能分区，再做物理目录迁移
+- `src/channel.ts` 保持为装配层，避免继续堆积业务逻辑
+- 新功能应优先落到清晰的业务域，而不是继续平铺到 `src/` 根目录
+- 结构重排尽量与行为改动拆分，降低进行中 PR 的冲突面
+- 对存量代码采用渐进迁移策略，不要求一次性整体搬迁
 
-插件遵循 Telegram 参考实现的架构模式：
+计划中的目录分区摘要：
 
-- **index.ts**: 最小化插件注册入口
-- **src/channel.ts**: 所有 DingTalk 特定的逻辑（API、消息处理、配置等）
-- **src/runtime.ts**: 运行时管理（getter/setter）
-- **src/types.ts**: 类型定义
-- **utils.ts**: 通用工具函数
+- `gateway/`: Stream 连接、回调注册、入站事件入口与启停时序
+- `targeting/`: `conversationId`、peer、session alias、目标解析与群目录能力
+- `messaging/`: 入站内容提取、reply strategy、文本/markdown/media 发送与消息上下文
+- `card/`: AI Card 创建、流式更新、结束态、恢复与缓存
+- `command/`: slash 命令、feedback learning、target rule 与后续扩展命令能力
+- `platform/`: config、auth、runtime、logger、types 等底层平台能力
+- `shared/`: 跨领域复用的持久化原语、dedup 与通用工具
 
 ## 测试
 

package/index.ts

@@ -1,80 +1,85 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import * as pluginSdk from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { defineChannelPluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { readStringParam } from "openclaw/plugin-sdk/param-readers";
 import { dingtalkPlugin } from "./src/channel";
 import { getConfig } from "./src/config";
 import { appendToDoc, createDoc, DocCreateAppendError, listDocs, searchDocs } from "./src/docs-service";
 import { setDingTalkRuntime } from "./src/runtime";
-import type { DingtalkPluginModule } from "./src/types";
 
 type GatewayMethodContext = Pick<
   Parameters<Parameters<OpenClawPluginApi["registerGatewayMethod"]>[1]>[0],
   "params" | "respond"
 >;
 
-const plugin: DingtalkPluginModule = {
+function registerDingTalkDocsGatewayMethods(api: OpenClawPluginApi): void {
+  api.registerGatewayMethod("dingtalk.docs.create", async ({ respond, params }: GatewayMethodContext) => {
+    const accountId = readStringParam(params, "accountId");
+    const spaceId = readStringParam(params, "spaceId", { required: true });
+    const title = readStringParam(params, "title", { required: true });
+    const content = readStringParam(params, "content", { allowEmpty: true });
+    const parentId = readStringParam(params, "parentId");
+    const config = getConfig(api.config, accountId ?? undefined);
+    try {
+      const doc = await createDoc(
+        config,
+        spaceId,
+        title,
+        content ?? undefined,
+        api.logger,
+        parentId ?? undefined,
+      );
+      return respond(true, doc);
+    } catch (error) {
+      if (error instanceof DocCreateAppendError) {
+        return respond(true, {
+          partialSuccess: true,
+          initContentAppended: false,
+          docId: error.doc.docId,
+          doc: error.doc,
+          appendError: error.message,
+        });
+      }
+      throw error;
+    }
+  });
+
+  api.registerGatewayMethod("dingtalk.docs.append", async ({ respond, params }: GatewayMethodContext) => {
+    const accountId = readStringParam(params, "accountId");
+    const docId = readStringParam(params, "docId", { required: true });
+    const content = readStringParam(params, "content", { required: true, allowEmpty: false });
+    const config = getConfig(api.config, accountId ?? undefined);
+    const result = await appendToDoc(config, docId, content, api.logger);
+    return respond(true, result);
+  });
+
+  api.registerGatewayMethod("dingtalk.docs.search", async ({ respond, params }: GatewayMethodContext) => {
+    const accountId = readStringParam(params, "accountId");
+    const keyword = readStringParam(params, "keyword", { required: true });
+    const spaceId = readStringParam(params, "spaceId");
+    const config = getConfig(api.config, accountId ?? undefined);
+    const docs = await searchDocs(config, keyword, spaceId, api.logger);
+    return respond(true, { docs });
+  });
+
+  api.registerGatewayMethod("dingtalk.docs.list", async ({ respond, params }: GatewayMethodContext) => {
+    const accountId = readStringParam(params, "accountId");
+    const spaceId = readStringParam(params, "spaceId", { required: true });
+    const parentId = readStringParam(params, "parentId");
+    const config = getConfig(api.config, accountId ?? undefined);
+    const docs = await listDocs(config, spaceId, parentId, api.logger);
+    return respond(true, { docs });
+  });
+}
+
+export { dingtalkPlugin } from "./src/channel";
+export { setDingTalkRuntime } from "./src/runtime";
+
+export default defineChannelPluginEntry({
   id: "dingtalk",
   name: "DingTalk Channel",
   description: "DingTalk (钉钉) messaging channel via Stream mode",
-  configSchema: emptyPluginConfigSchema(),
-  register(api: OpenClawPluginApi): void {
-    setDingTalkRuntime(api.runtime);
-    api.registerChannel({ plugin: dingtalkPlugin });
-    api.registerGatewayMethod("dingtalk.docs.create", async ({ respond, params }: GatewayMethodContext) => {
-      const accountId = pluginSdk.readStringParam(params, "accountId");
-      const spaceId = pluginSdk.readStringParam(params, "spaceId", { required: true });
-      const title = pluginSdk.readStringParam(params, "title", { required: true });
-      const content = pluginSdk.readStringParam(params, "content", { allowEmpty: true });
-      const parentId = pluginSdk.readStringParam(params, "parentId");
-      const config = getConfig(api.config, accountId ?? undefined);
-      try {
-        const doc = await createDoc(
-          config,
-          spaceId,
-          title,
-          content ?? undefined,
-          api.logger,
-          parentId ?? undefined,
-        );
-        return respond(true, doc);
-      } catch (error) {
-        if (error instanceof DocCreateAppendError) {
-          return respond(true, {
-            partialSuccess: true,
-            initContentAppended: false,
-            docId: error.doc.docId,
-            doc: error.doc,
-            appendError: error.message,
-          });
-        }
-        throw error;
-      }
-    });
-    api.registerGatewayMethod("dingtalk.docs.append", async ({ respond, params }: GatewayMethodContext) => {
-      const accountId = pluginSdk.readStringParam(params, "accountId");
-      const docId = pluginSdk.readStringParam(params, "docId", { required: true });
-      const content = pluginSdk.readStringParam(params, "content", { required: true, allowEmpty: false });
-      const config = getConfig(api.config, accountId ?? undefined);
-      const result = await appendToDoc(config, docId, content, api.logger);
-      return respond(true, result);
-    });
-    api.registerGatewayMethod("dingtalk.docs.search", async ({ respond, params }: GatewayMethodContext) => {
-      const accountId = pluginSdk.readStringParam(params, "accountId");
-      const keyword = pluginSdk.readStringParam(params, "keyword", { required: true });
-      const spaceId = pluginSdk.readStringParam(params, "spaceId");
-      const config = getConfig(api.config, accountId ?? undefined);
-      const docs = await searchDocs(config, keyword, spaceId, api.logger);
-      return respond(true, { docs });
-    });
-    api.registerGatewayMethod("dingtalk.docs.list", async ({ respond, params }: GatewayMethodContext) => {
-      const accountId = pluginSdk.readStringParam(params, "accountId");
-      const spaceId = pluginSdk.readStringParam(params, "spaceId", { required: true });
-      const parentId = pluginSdk.readStringParam(params, "parentId");
-      const config = getConfig(api.config, accountId ?? undefined);
-      const docs = await listDocs(config, spaceId, parentId, api.logger);
-      return respond(true, { docs });
-    });
+  plugin: dingtalkPlugin,
+  setRuntime: setDingTalkRuntime,
+  registerFull(api) {
+    registerDingTalkDocsGatewayMethods(api);
   },
-};
-
-export default plugin;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soimy/dingtalk",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "DingTalk (钉钉) channel plugin for OpenClaw",
   "keywords": [
     "bot",
@@ -20,7 +20,7 @@
   },
   "files": [
     "index.ts",
-    "src/*.ts",
+    "src/**/*.ts",
     "openclaw.plugin.json",
     "clawbot.plugin.json"
   ],
@@ -51,6 +51,7 @@
   "devDependencies": {
     "@types/node": "^25.2.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "openclaw": "2026.3.22",
     "oxfmt": "0.34.0",
     "oxlint": "^1.49.0",
     "oxlint-tsgolint": "^0.15.0",
@@ -58,7 +59,7 @@
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.2.13"
+    "openclaw": ">=2026.3.14"
   },
   "openclaw": {
     "extensions": [
@@ -72,8 +73,8 @@
       "id": "dingtalk",
       "label": "DingTalk",
       "selectionLabel": "DingTalk (钉钉)",
-      "docsPath": "/channels/dingtalk",
-      "docsLabel": "dingtalk",
+      "docsPath": "https://github.com/soimy/openclaw-channel-dingtalk",
+      "docsLabel": "plugin docs",
       "blurb": "钉钉企业内部机器人，使用 Stream 模式，无需公网 IP。",
       "order": 70,
       "aliases": [

package/src/access-control.ts

@@ -54,6 +54,71 @@ export function isSenderGroupAllowed(params: {
   return false;
 }
 
+export type GroupAccessResult = {
+  allowed: boolean;
+  reason?: "disabled" | "group_not_allowed" | "sender_not_allowed";
+  legacyFallback?: boolean;
+};
+
+export type GroupAccessParams = {
+  groupPolicy: "open" | "allowlist" | "disabled";
+  groupId: string;
+  senderId: string;
+  groups?: Record<string, { groupAllowFrom?: string[] }>;
+  groupAllowFrom?: string[];
+  allowFrom?: string[]; // legacy fallback
+};
+
+export function resolveGroupAccess(params: GroupAccessParams): GroupAccessResult {
+  const { groupPolicy, groupId, senderId, groups, groupAllowFrom, allowFrom } = params;
+
+  // Step 1: disabled → block all
+  if (groupPolicy === "disabled") {
+    return { allowed: false, reason: "disabled" };
+  }
+
+  // Step 2: allowlist → group ID check
+  let legacyFallback = false;
+  if (groupPolicy === "allowlist") {
+    const groupConfig = groups?.[groupId];
+    const wildcardConfig = groups?.["*"];
+    const groupInConfig = groupConfig !== undefined || wildcardConfig !== undefined;
+
+    if (!groupInConfig) {
+      // Legacy fallback: check allowFrom for group ID
+      const legacyAllow = normalizeAllowFrom(allowFrom);
+      if (isSenderGroupAllowed({ allow: legacyAllow, groupId })) {
+        legacyFallback = true;
+        // Continue to sender check below
+      } else {
+        return { allowed: false, reason: "group_not_allowed" };
+      }
+    }
+  }
+
+  // Step 3: Sender check
+  // Priority: per-group > wildcard > top-level
+  const perGroupAllowFrom = groups?.[groupId]?.groupAllowFrom;
+  const wildcardAllowFrom = groups?.["*"]?.groupAllowFrom;
+  const effectiveAllowFrom = perGroupAllowFrom ?? wildcardAllowFrom ?? groupAllowFrom;
+
+  if (effectiveAllowFrom == null) {
+    return { allowed: true, legacyFallback: legacyFallback || undefined };
+  }
+
+  // Empty array = block all senders (fail-closed per official design)
+  if (effectiveAllowFrom.length === 0) {
+    return { allowed: false, reason: "sender_not_allowed" };
+  }
+
+  const normalized = normalizeAllowFrom(effectiveAllowFrom);
+  if (isSenderAllowed({ allow: normalized, senderId })) {
+    return { allowed: true, legacyFallback: legacyFallback || undefined };
+  }
+
+  return { allowed: false, reason: "sender_not_allowed" };
+}
+
 export function isSenderOwner(params: {
   allow: NormalizedAllowFrom;
   senderId?: string;