@soimy/dingtalk 3.2.0 → 3.4.0

package/src/session-routing.ts

@@ -0,0 +1,33 @@
+import type { DingTalkConfig } from "./types";
+
+export interface ResolveDingTalkSessionPeerParams {
+  isDirect: boolean;
+  senderId: string;
+  conversationId: string;
+  peerIdOverride?: string;
+  config: DingTalkConfig;
+}
+
+export interface ResolvedDingTalkSessionPeer {
+  kind: "direct" | "group";
+  peerId: string;
+}
+
+// Keep DingTalk aligned with Feishu's explicit peerId -> sessionKey model:
+// resolve a stable peer identity first, then let OpenClaw build the final session key.
+export function resolveDingTalkSessionPeer(
+  params: ResolveDingTalkSessionPeerParams,
+): ResolvedDingTalkSessionPeer {
+  const normalizedPeerIdOverride = params.peerIdOverride?.trim();
+  if (params.isDirect) {
+    return {
+      kind: "direct",
+      peerId: normalizedPeerIdOverride || params.senderId,
+    };
+  }
+
+  return {
+    kind: "group",
+    peerId: normalizedPeerIdOverride || params.conversationId,
+  };
+}

package/src/targeting/agent-name-matcher.ts

@@ -0,0 +1,148 @@
+/**
+ * Agent name matcher for @sub-agent feature
+ *
+ * Matches @mentions to agent IDs based on name and id fields in agents.list config.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { AtMention, AgentNameMatch } from "../types";
+
+interface AgentConfig {
+  id: string;
+  name?: string;
+  default?: boolean;
+}
+
+/**
+ * Normalize name for case-insensitive matching
+ */
+function normalizeName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+/**
+ * Get main agent ID from agents.list
+ */
+export function getMainAgentId(agents: AgentConfig[] | undefined): string {
+  if (!agents || agents.length === 0) {
+    return "main";
+  }
+
+  const defaultAgent = agents.find((a) => a.default);
+  if (defaultAgent) {
+    return defaultAgent.id;
+  }
+
+  return agents[0].id;
+}
+
+/**
+ * Match a single @name to an agent
+ */
+function matchAtName(atName: string, agents: AgentConfig[]): AgentNameMatch | null {
+  const normalizedAtName = normalizeName(atName);
+
+  for (const agent of agents) {
+    // 1. Match by name field
+    if (agent.name && normalizeName(agent.name) === normalizedAtName) {
+      return {
+        agentId: agent.id,
+        matchSource: "name",
+        matchedName: agent.name,
+      };
+    }
+
+    // 2. Match by id field
+    if (normalizeName(agent.id) === normalizedAtName) {
+      return {
+        agentId: agent.id,
+        matchSource: "id",
+        matchedName: agent.id,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve @mentions to agent matches
+ *
+ * @param atMentions - List of @mentions extracted from message
+ * @param cfg - OpenClaw configuration
+ * @param atUserDingtalkIds - dingtalkIds from webhook atUsers field (real users selected via @picker)
+ * @returns Matched agents, unmatched names, main agent ID, and whether there are invalid agent names
+ *
+ * @remarks
+ * Exclusion logic for unmatched @mentions:
+ * - If mention.userId is set (from richText), it's a real user → excluded from unmatchedNames
+ * - In text mode, we cannot map dingtalkIds to specific @mention names
+ * - To avoid false positives (reporting real user names as missing agents),
+ *   we use a conservative heuristic:
+ *   - If realUserCount > 0, hasInvalidAgentNames is always false
+ *   - This means we never report "agent not found" in text mode when there are real users
+ * - In richText mode, mention.userId allows precise exclusion, so the heuristic is not needed
+ */
+export function resolveAtAgents(
+  atMentions: AtMention[],
+  cfg: OpenClawConfig,
+  atUserDingtalkIds?: string[],
+): {
+  matchedAgents: AgentNameMatch[];
+  unmatchedNames: string[];
+  mainAgentId: string;
+  /** Count of @mentions that are likely real users (from atUserDingtalkIds) */
+  realUserCount: number;
+  /** Whether there are invalid agent names (conservative: false if realUserCount > 0) */
+  hasInvalidAgentNames: boolean;
+} {
+  const agents = cfg?.agents?.list as AgentConfig[] | undefined;
+  const mainAgentId = getMainAgentId(agents);
+
+  if (!atMentions || atMentions.length === 0) {
+    return {
+      matchedAgents: [],
+      unmatchedNames: [],
+      mainAgentId,
+      realUserCount: 0,
+      hasInvalidAgentNames: false,
+    };
+  }
+
+  const matchedAgents: AgentNameMatch[] = [];
+  const unmatchedNames: string[] = [];
+
+  for (const mention of atMentions) {
+    const match = agents ? matchAtName(mention.name, agents) : null;
+
+    if (match) {
+      // Avoid duplicate agents
+      if (!matchedAgents.some((m) => m.agentId === match.agentId)) {
+        matchedAgents.push(match);
+      }
+    } else {
+      // Exclude @real users (those with userId are real users from richText)
+      if (!mention.userId) {
+        unmatchedNames.push(mention.name);
+      }
+    }
+  }
+
+  // Count real users from atUserDingtalkIds
+  // These are real DingTalk users selected via @picker, but we don't know which names they correspond to
+  const realUserCount = atUserDingtalkIds?.length || 0;
+
+  // Conservative heuristic: if there are real users, never report invalid agent names
+  // This avoids false positives where real user names are incorrectly reported as missing agents
+  // In text mode, we cannot distinguish which @mentions correspond to real users
+  // In richText mode, mention.userId provides precise exclusion, so this is just a safety net
+  const hasInvalidAgentNames = realUserCount === 0 && unmatchedNames.length > 0;
+
+  return {
+    matchedAgents,
+    unmatchedNames,
+    mainAgentId,
+    realUserCount,
+    hasInvalidAgentNames,
+  };
+}

package/src/targeting/agent-routing.ts

@@ -0,0 +1,181 @@
+/**
+ * Sub-agent routing for @mention-based multi-agent support.
+ *
+ * Extracts @mentions from inbound messages and resolves them to agent IDs
+ * using agents.list configuration. This is a plugin-layer routing mechanism
+ * because the framework's resolveAgentRoute only supports static matching
+ * (channel + accountId + peer), not content-based dynamic routing.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveAtAgents } from "./agent-name-matcher";
+import { parseLearnCommand } from "../learning-command-service";
+import { getDingTalkRuntime } from "../runtime";
+import { sendBySession } from "../send-service";
+import type { AgentNameMatch, DingTalkConfig, DingTalkInboundMessage, HandleDingTalkMessageParams, Logger, MessageContent } from "../types";
+
+/**
+ * Build a session key for a specific agent using the runtime API.
+ * Falls back to framework's resolveAgentRoute if buildAgentSessionKey is unavailable.
+ */
+export function buildAgentSessionKey(params: {
+  rt: ReturnType<typeof getDingTalkRuntime>;
+  cfg: OpenClawConfig;
+  accountId: string;
+  agentId: string;
+  peerKind: "direct" | "group";
+  peerId: string;
+}): string {
+  const { rt, cfg, accountId, agentId, peerKind, peerId } = params;
+  const routing = rt.channel.routing as Record<string, unknown>;
+  if (typeof routing.buildAgentSessionKey === "function") {
+    return (
+      (routing.buildAgentSessionKey as (p: unknown) => string)({
+        agentId,
+        channel: "dingtalk",
+        accountId,
+        peer: { kind: peerKind, id: peerId },
+        dmScope: cfg.session?.dmScope,
+        identityLinks: cfg.session?.identityLinks,
+      })
+    ).toLowerCase();
+  }
+  // Fallback: derive a session key with agentId suffix to ensure isolation.
+  // resolveAgentRoute routes to the default agent, so we append the target
+  // agentId to prevent session key collisions between sub-agents.
+  // @migration-note: When SDK exposes buildAgentSessionKey in type definitions,
+  // sessions created via this fallback path will become orphaned. Remove this
+  // fallback and the typeof check once the SDK is updated.
+  const fallbackRoute = rt.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "dingtalk",
+    accountId,
+    peer: { kind: peerKind, id: peerId },
+  });
+  return `${fallbackRoute.sessionKey}:subagent:${agentId}`;
+}
+
+/**
+ * Sanitize agent name for safe use in markdown prefix and context hints.
+ * Strips brackets, newlines, and control characters to prevent markdown
+ * breakage and prompt injection.
+ */
+function sanitizeAgentName(name: string): string {
+  return name.replace(/[[\]\r\n]/g, "").trim();
+}
+
+/**
+ * Resolve @mention-based sub-agent routing for a group message.
+ *
+ * Returns matched agents if any @mentions resolve to configured agents,
+ * or null if the message should be handled by the default agent.
+ */
+export async function resolveSubAgentRoute(params: {
+  extractedContent: MessageContent;
+  cfg: OpenClawConfig;
+  isGroup: boolean;
+  dingtalkConfig: DingTalkConfig;
+  sessionWebhook: string;
+  senderId: string;
+  log?: Logger;
+}): Promise<{
+  matchedAgents: AgentNameMatch[];
+  preDownloadedMedia?: { mediaPath?: string; mediaType?: string };
+} | null> {
+  const { extractedContent, cfg, isGroup, dingtalkConfig, sessionWebhook, senderId, log } = params;
+
+  const atMentions = extractedContent.atMentions || [];
+  const atUserDingtalkIds = extractedContent.atUserDingtalkIds;
+  // Strip quoted prefix before checking /learn to avoid false positives
+  // when the quoted message itself contains a /learn command.
+  const textForCommandCheck = extractedContent.text.replace(/^\[引用[^\]]*\]\s*/, "");
+  const isLearnCommand = parseLearnCommand(textForCommandCheck).scope !== "unknown";
+
+  if (
+    !isGroup ||
+    atMentions.length === 0 ||
+    !cfg.agents?.list ||
+    cfg.agents.list.length === 0 ||
+    isLearnCommand
+  ) {
+    return null;
+  }
+
+  const { matchedAgents, unmatchedNames, realUserCount, hasInvalidAgentNames } = resolveAtAgents(
+    atMentions,
+    cfg,
+    atUserDingtalkIds,
+  );
+  log?.info?.(
+    `[DingTalk] Sub-agent resolve: matched=${matchedAgents.map((a) => a.agentId).join(",")} unmatched=${unmatchedNames.join(",")} realUsers=${realUserCount}`,
+  );
+
+  // Send fallback notice for unmatched agent names
+  if (hasInvalidAgentNames) {
+    const fallbackReason = `未找到名为"${unmatchedNames.join("、")}"的助手`;
+    try {
+      await sendBySession(dingtalkConfig, sessionWebhook, `⚠️ ${fallbackReason}`, {
+        atUserId: senderId,
+        log,
+      });
+    } catch (err: any) {
+      log?.debug?.(`[DingTalk] Failed to send fallback notice: ${err.message}`);
+    }
+  }
+
+  if (matchedAgents.length === 0) {
+    return null;
+  }
+
+  return { matchedAgents };
+}
+
+/**
+ * Process matched sub-agents by dispatching each to handleDingTalkMessage.
+ */
+export async function dispatchSubAgents(params: {
+  matchedAgents: AgentNameMatch[];
+  cfg: OpenClawConfig;
+  accountId: string;
+  data: DingTalkInboundMessage;
+  dingtalkConfig: DingTalkConfig;
+  sessionWebhook: string;
+  extractedContent: MessageContent;
+  handleMessage: (params: HandleDingTalkMessageParams) => Promise<void>;
+  downloadMedia: (config: DingTalkConfig, mediaPath: string, log?: Logger) => Promise<{ path: string; mimeType: string } | null>;
+  log?: Logger;
+}): Promise<void> {
+  const { matchedAgents, cfg, accountId, data, dingtalkConfig, sessionWebhook, extractedContent, handleMessage, downloadMedia: download, log } = params;
+
+  // Pre-download media once to avoid duplication across sub-agents
+  let preDownloadedMedia: { mediaPath?: string; mediaType?: string } | undefined;
+  if (extractedContent.mediaPath && dingtalkConfig.robotCode) {
+    const media = await download(dingtalkConfig, extractedContent.mediaPath, log);
+    if (media) {
+      preDownloadedMedia = { mediaPath: media.path, mediaType: media.mimeType };
+    }
+  }
+
+  for (const agentMatch of matchedAgents) {
+    try {
+      await handleMessage({
+        cfg,
+        accountId,
+        data,
+        sessionWebhook,
+        log,
+        dingtalkConfig,
+        subAgentOptions: {
+          agentId: agentMatch.agentId,
+          responsePrefix: `[${sanitizeAgentName(agentMatch.matchedName)}] `,
+          matchedName: agentMatch.matchedName,
+        },
+        preDownloadedMedia,
+      });
+    } catch (error) {
+      log?.error?.(
+        `[DingTalk] Sub-agent ${agentMatch.agentId} failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}

package/src/targeting/target-directory-adapter.ts

@@ -0,0 +1,151 @@
+import type { ChannelDirectoryEntry, OpenClawConfig } from "openclaw/plugin-sdk";
+import { getConfig, stripTargetPrefix } from "../config";
+import { resolveOriginalPeerId } from "../peer-id-registry";
+import { getDingTalkRuntime } from "../runtime";
+import { listKnownGroupTargets, listKnownUserTargets } from "./target-directory-store";
+
+export type DirectoryListParams = {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  query?: string | null;
+  limit?: number | null;
+  runtime?: unknown;
+};
+
+type RuntimeSessionResolver = {
+  resolveStorePath?: (store: unknown, options: { agentId?: string | null | undefined }) => string;
+};
+
+function normalizeDirectoryAccountId(accountId?: string | null): string {
+  const resolved = String(accountId || "default").trim();
+  return resolved || "default";
+}
+
+function normalizeDirectoryLimit(limit?: number | null): number | undefined {
+  if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) {
+    return undefined;
+  }
+  return Math.floor(limit);
+}
+
+function resolveDirectoryStorePath(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  runtime?: unknown;
+}): string | undefined {
+  const normalizedAccountId = normalizeDirectoryAccountId(params.accountId);
+  const runtimeSession = (
+    params.runtime as { channel?: { session?: RuntimeSessionResolver } } | undefined
+  )?.channel?.session;
+  if (runtimeSession?.resolveStorePath) {
+    return runtimeSession.resolveStorePath(params.cfg.session?.store, {
+      agentId: normalizedAccountId,
+    });
+  }
+  try {
+    const rt = getDingTalkRuntime();
+    return rt.channel.session.resolveStorePath(params.cfg.session?.store, {
+      agentId: normalizedAccountId,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+function shouldFilterDirectoryByQuery(params: DirectoryListParams): boolean {
+  // OpenClaw target-resolver currently uses a query-insensitive cache key and
+  // always calls directory list APIs with limit=undefined. If we filter by
+  // query at this layer during resolver calls, one miss can poison cache for
+  // later different queries. Keep resolver reads query-agnostic.
+  return params.limit !== undefined;
+}
+
+function isDisplayNameResolutionEnabled(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): boolean {
+  const mode = getConfig(params.cfg, params.accountId ?? undefined).displayNameResolution;
+  // Current upstream target resolution does not pass requester owner/authz context into
+  // plugin targetResolver/directory callbacks, so owner-only resolution is not yet safe.
+  // Keep the config explicit: only "all" enables learned displayName resolution for now.
+  // TODO(upstream target-resolver): add a true owner-only mode once requester authorization
+  // is plumbed into plugin resolver and directory entry points.
+  return mode === "all";
+}
+
+export function listDingTalkDirectoryGroups(params: DirectoryListParams): ChannelDirectoryEntry[] {
+  if (!isDisplayNameResolutionEnabled(params)) {
+    return [];
+  }
+  const accountId = normalizeDirectoryAccountId(params.accountId);
+  const storePath = resolveDirectoryStorePath(params);
+  const filterByQuery = shouldFilterDirectoryByQuery(params);
+  const groups = listKnownGroupTargets({
+    storePath,
+    accountId,
+    query: filterByQuery ? (params.query ?? undefined) : undefined,
+    limit: filterByQuery ? normalizeDirectoryLimit(params.limit) : undefined,
+  });
+  const groupEntries: ChannelDirectoryEntry[] = groups.map((entry) => ({
+    kind: "group" as const,
+    id: resolveOriginalPeerId(entry.conversationId),
+    name: entry.currentTitle,
+    handle: entry.conversationId,
+    rank: entry.lastSeenAt,
+    raw: entry,
+  }));
+
+  if (filterByQuery) {
+    return groupEntries;
+  }
+
+  // TODO(upstream target-resolver): remove this fallback once bare user labels
+  // can be classified and routed to listPeers() instead of only listGroups().
+  // Temporary hack for the current upstream target-resolver flow: bare names
+  // are classified as "group" before directory lookup, so user displayName
+  // targets never reach listPeers(). Merge users into the resolver-only group
+  // lookup set so "displayName -> targetId" can still resolve for DingTalk.
+  const users = listKnownUserTargets({
+    storePath,
+    accountId,
+  });
+  const userEntries: ChannelDirectoryEntry[] = users.map((entry) => ({
+    kind: "user" as const,
+    id: entry.canonicalUserId,
+    name: entry.currentDisplayName,
+    handle: entry.staffId || entry.senderId,
+    rank: entry.lastSeenAt,
+    raw: entry,
+  }));
+
+  return [...groupEntries, ...userEntries].toSorted(
+    (left, right) => (right.rank || 0) - (left.rank || 0),
+  );
+}
+
+export function listDingTalkDirectoryUsers(params: DirectoryListParams): ChannelDirectoryEntry[] {
+  if (!isDisplayNameResolutionEnabled(params)) {
+    return [];
+  }
+  const accountId = normalizeDirectoryAccountId(params.accountId);
+  const storePath = resolveDirectoryStorePath(params);
+  const filterByQuery = shouldFilterDirectoryByQuery(params);
+  const users = listKnownUserTargets({
+    storePath,
+    accountId,
+    query: filterByQuery ? (params.query ?? undefined) : undefined,
+    limit: filterByQuery ? normalizeDirectoryLimit(params.limit) : undefined,
+  });
+  return users.map((entry) => ({
+    kind: "user",
+    id: entry.canonicalUserId,
+    name: entry.currentDisplayName,
+    handle: entry.staffId || entry.senderId,
+    rank: entry.lastSeenAt,
+    raw: entry,
+  }));
+}
+
+export function normalizeResolvedDingTalkTarget(raw: string): string {
+  return resolveOriginalPeerId(stripTargetPrefix(raw).targetId);
+}