@soimy/dingtalk 3.3.0 → 3.4.1

package/src/types.ts

@@ -10,22 +10,21 @@
  */
 
 import type {
+  ChannelPlugin as SDKChannelPlugin,
   OpenClawConfig,
-  OpenClawPluginApi,
-  ChannelLogSink as SDKChannelLogSink,
+} from "openclaw/plugin-sdk/core";
+import type {
   ChannelAccountSnapshot as SDKChannelAccountSnapshot,
   ChannelGatewayContext as SDKChannelGatewayContext,
-  ChannelPlugin as SDKChannelPlugin,
-} from "openclaw/plugin-sdk";
+  ChannelLogSink as SDKChannelLogSink,
+} from "openclaw/plugin-sdk/channel-runtime";
+import type { ChannelSetupWizard } from "openclaw/plugin-sdk/setup";
 import { mergeAccountWithDefaults } from "./config";
 
-export interface DingtalkPluginModule {
-  id: string;
-  name: string;
-  description?: string;
-  configSchema?: unknown;
-  register?: (api: OpenClawPluginApi) => void | Promise<void>;
-}
+export type AckReactionMode = "off" | "emoji" | "kaomoji";
+// Accept arbitrary strings for backward compatibility; the recommended
+// explicit modes remain: "off" | "emoji" | "kaomoji".
+export type AckReactionConfigValue = string;
 
 /**
  * DingTalk channel configuration (extends base OpenClaw config)
@@ -39,16 +38,18 @@ export interface DingTalkConfig extends OpenClawConfig {
   name?: string;
   enabled?: boolean;
   dmPolicy?: "open" | "pairing" | "allowlist";
-  groupPolicy?: "open" | "allowlist";
+  groupPolicy?: "open" | "allowlist" | "disabled";
   allowFrom?: string[];
+  groupAllowFrom?: string[];
+  displayNameResolution?: "disabled" | "all";
   mediaUrlAllowlist?: string[];
   journalTTLDays?: number;
-  ackReaction?: string;
+  ackReaction?: AckReactionConfigValue;
   debug?: boolean;
   messageType?: "markdown" | "card";
   cardTemplateId?: string;
   cardTemplateKey?: string;
-  groups?: Record<string, { systemPrompt?: string }>;
+  groups?: Record<string, { systemPrompt?: string; requireMention?: boolean; groupAllowFrom?: string[] }>;
   accounts?: Record<string, DingTalkConfig>;
   // Connection robustness configuration
   maxConnectionAttempts?: number;
@@ -87,6 +88,10 @@ export interface DingTalkConfig extends OpenClawConfig {
   feedbackLearningAutoApply?: boolean;
   /** @deprecated Use learningNoteTtlMs */
   feedbackLearningNoteTtlMs?: number;
+  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  convertMarkdownTables?: boolean;
+  /** @mention the sender after card finalization in group chats; value is the message text */
+  cardAtSender?: string;
 }
 
 /**
@@ -101,16 +106,18 @@ export interface DingTalkChannelConfig {
   agentId?: string;
   name?: string;
   dmPolicy?: "open" | "pairing" | "allowlist";
-  groupPolicy?: "open" | "allowlist";
+  groupPolicy?: "open" | "allowlist" | "disabled";
   allowFrom?: string[];
+  groupAllowFrom?: string[];
+  displayNameResolution?: "disabled" | "all";
   mediaUrlAllowlist?: string[];
   journalTTLDays?: number;
-  ackReaction?: string;
+  ackReaction?: AckReactionConfigValue;
   debug?: boolean;
   messageType?: "markdown" | "card";
   cardTemplateId?: string;
   cardTemplateKey?: string;
-  groups?: Record<string, { systemPrompt?: string }>;
+  groups?: Record<string, { systemPrompt?: string; requireMention?: boolean; groupAllowFrom?: string[] }>;
   accounts?: Record<string, DingTalkConfig>;
   maxConnectionAttempts?: number;
   initialReconnectDelay?: number;
@@ -148,6 +155,10 @@ export interface DingTalkChannelConfig {
   feedbackLearningAutoApply?: boolean;
   /** @deprecated Use learningNoteTtlMs */
   feedbackLearningNoteTtlMs?: number;
+  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  convertMarkdownTables?: boolean;
+  /** @mention the sender after card finalization in group chats; value is the message text */
+  cardAtSender?: string;
 }
 
 /**
@@ -207,6 +218,14 @@ export interface DingTalkInboundMessage {
   msgId: string;
   msgtype: string;
   createAt: number;
+  /**
+   * @ 提及的用户列表（消息顶层，与 text 同级）
+   * 包含通过 @picker 选中的所有真实钉钉用户和机器人
+   * 格式: [{ dingtalkId: "$:LWCP_v1:$xxx" }]
+   */
+  atUsers?: Array<{
+    dingtalkId: string;
+  }>;
   text?: {
     content: string;
     isReplyMsg?: boolean; // 是否是回复消息
@@ -218,6 +237,7 @@ export interface DingTalkInboundMessage {
       content?: {
         text?: string;
         downloadCode?: string;
+        fileName?: string;
         biz_custom_action_url?: string;
         richText?: Array<{
           msgType?: string;
@@ -242,6 +262,7 @@ export interface DingTalkInboundMessage {
       type: string;
       text?: string;
       atName?: string;
+      atUserId?: string;
       downloadCode?: string;
     }>;
     quoteContent?: string;
@@ -267,24 +288,58 @@ export interface DingTalkInboundMessage {
   sessionWebhook: string;
 }
 
+export type QuotedRefKey = "msgId" | "processQueryKey" | "messageId" | "outTrackId" | "cardInstanceId";
+
+export type AttachmentTextSource = "text" | "html" | "pdf" | "docx";
+
+export interface QuotedRef {
+  targetDirection: "inbound" | "outbound";
+  key?: QuotedRefKey;
+  value?: string;
+  fallbackCreatedAt?: number;
+}
+
 /**
  * Quoted/reply message metadata extracted from repliedMsg.
  * Populated when isReplyMsg is true; downstream handlers use these fields
  * to download quoted media or look up cached card content.
  */
 export interface QuotedInfo {
-  prefix: string;
   mediaDownloadCode?: string;
   mediaType?: string;
   isQuotedFile?: boolean;
   isQuotedCard?: boolean;
   isQuotedDocCard?: boolean;
-  docSpaceId?: string;
-  docFileId?: string;
   cardCreatedAt?: number;
   processQueryKey?: string;
   fileCreatedAt?: number;
   msgId?: string;
+  previewText?: string;
+  previewMessageType?: string;
+  previewFileName?: string;
+  previewSenderId?: string;
+}
+
+/**
+ * @ 提及信息
+ */
+export interface AtMention {
+  /** @ 显示的名字（去除 @ 前缀） */
+  name: string;
+  /** 钉钉用户 ID（如果是 @ 真人） */
+  userId?: string;
+}
+
+/**
+ * Agent 名字匹配结果
+ */
+export interface AgentNameMatch {
+  /** 匹配到的 agent ID */
+  agentId: string;
+  /** 匹配来源：'name' | 'id' */
+  matchSource: "name" | "id";
+  /** 匹配到的名字 */
+  matchedName: string;
 }
 
 /**
@@ -300,6 +355,16 @@ export interface MessageContent {
   docSpaceId?: string;
   docFileId?: string;
   quoted?: QuotedInfo;
+  /** @ 提及列表（从文本或 richText 提取的名字） */
+  atMentions?: AtMention[];
+  /**
+   * 通过 @picker 选中的真实钉钉用户的 dingtalkId 列表
+   * - 仅包含真实钉钉用户和机器人，不包含 agent 名
+   * - 用于排除真人：如果 atMentions 中的名字匹配到 agent，说明是 agent；
+   *   如果没匹配到 agent 且有 atUserDingtalkIds，则可能是真人
+   * - 注意：无法将 dingtalkId 映射到具体名字，因为 webhook 不提供此映射
+   */
+  atUserDingtalkIds?: string[];
 }
 
 /**
@@ -318,6 +383,12 @@ export interface SendMessageOptions {
   accountId?: string;
   storePath?: string;
   cardUpdateMode?: "append";
+  quotedRef?: QuotedRef;
+  /** Force markdown/text delivery even when messageType is "card". Bypasses card
+   *  creation while preserving journal writes and other side-effects. */
+  forceMarkdown?: boolean;
+  /** Allowed local roots for sandbox/container media path resolution. */
+  mediaLocalRoots?: string[];
 }
 
 export interface DingTalkTrackingMetadata {
@@ -344,6 +415,18 @@ export interface SessionWebhookResponse {
   };
 }
 
+/**
+ * Sub-agent routing options for parameterized message handling
+ */
+export interface SubAgentOptions {
+  /** The agent ID to route to */
+  agentId: string;
+  /** Prefix to add to response messages (e.g., "[AgentName] ") */
+  responsePrefix: string;
+  /** The matched agent name */
+  matchedName: string;
+}
+
 /**
  * Message handler parameters
  */
@@ -354,6 +437,19 @@ export interface HandleDingTalkMessageParams {
   sessionWebhook: string;
   log?: Logger;
   dingtalkConfig: DingTalkConfig;
+  /**
+   * When set, routes message to the specified sub-agent instead of main agent.
+   * This enables reuse of the main message handling logic for sub-agents.
+   */
+  subAgentOptions?: SubAgentOptions;
+  /**
+   * Pre-downloaded media for sub-agent calls.
+   * When set, skips media download to avoid duplication in recursive calls.
+   */
+  preDownloadedMedia?: {
+    mediaPath?: string;
+    mediaType?: string;
+  };
 }
 
 /**
@@ -479,7 +575,9 @@ export interface GatewayStopResult {
 /**
  * DingTalk channel plugin definition
  */
-export type DingTalkChannelPlugin = SDKChannelPlugin<ResolvedAccount & { configured: boolean }>;
+export type DingTalkChannelPlugin = SDKChannelPlugin<ResolvedAccount & { configured: boolean }> & {
+  setupWizard?: ChannelSetupWizard;
+};
 
 /**
  * Result of target resolution validation
@@ -553,6 +651,7 @@ export interface AICardInstance {
   processQueryKey?: string;
   accessToken: string;
   conversationId: string;
+  contextConversationId?: string;
   accountId?: string;
   storePath?: string;
   createdAt: number;
@@ -680,6 +779,8 @@ export function resolveDingTalkAccount(
       dmPolicy: dingtalk?.dmPolicy,
       groupPolicy: dingtalk?.groupPolicy,
       allowFrom: dingtalk?.allowFrom,
+      groupAllowFrom: dingtalk?.groupAllowFrom,
+      displayNameResolution: dingtalk?.displayNameResolution,
       journalTTLDays: dingtalk?.journalTTLDays,
       ackReaction: dingtalk?.ackReaction,
       debug: dingtalk?.debug,
@@ -707,6 +808,8 @@ export function resolveDingTalkAccount(
       feedbackLearningEnabled: dingtalk?.feedbackLearningEnabled,
       feedbackLearningAutoApply: dingtalk?.feedbackLearningAutoApply,
       feedbackLearningNoteTtlMs: dingtalk?.feedbackLearningNoteTtlMs,
+      convertMarkdownTables: dingtalk?.convertMarkdownTables,
+      cardAtSender: dingtalk?.cardAtSender,
     };
     return {
       ...config,

package/src/quote-journal.ts

@@ -1,242 +0,0 @@
-import { readNamespaceJson, writeNamespaceJsonAtomic } from "./persistence-store";
-
-const QUOTE_JOURNAL_NAMESPACE = "quoted.msg-journal";
-const QUOTE_JOURNAL_VERSION = 1;
-export const DEFAULT_JOURNAL_TTL_DAYS = 7;
-const MAX_RECORDS_PER_SCOPE = 1000;
-
-type JournalEntry = {
-  msgId: string;
-  messageType: string;
-  text?: string;
-  createdAt: number;
-};
-
-type QuoteJournalState = {
-  version: number;
-  updatedAt: number;
-  records: JournalEntry[];
-};
-
-const stateCache = new Map<string, QuoteJournalState>();
-
-function getScopeKey(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-}): string {
-  return JSON.stringify([
-    params.storePath,
-    params.accountId,
-    params.conversationId || null,
-  ]);
-}
-
-function fallbackState(): QuoteJournalState {
-  return {
-    version: QUOTE_JOURNAL_VERSION,
-    updatedAt: Date.now(),
-    records: [],
-  };
-}
-
-function normalizeEntry(entry: unknown): JournalEntry | null {
-  if (!entry || typeof entry !== "object") {
-    return null;
-  }
-  const candidate = entry as Partial<JournalEntry>;
-  if (typeof candidate.msgId !== "string" || typeof candidate.createdAt !== "number") {
-    return null;
-  }
-  return {
-    msgId: candidate.msgId,
-    messageType: typeof candidate.messageType === "string" ? candidate.messageType : "text",
-    text: typeof candidate.text === "string" ? candidate.text : undefined,
-    createdAt: candidate.createdAt,
-  };
-}
-
-function normalizeState(parsed: Partial<QuoteJournalState>): QuoteJournalState {
-  const records = Array.isArray(parsed.records)
-    ? parsed.records.map((entry) => normalizeEntry(entry)).filter((entry): entry is JournalEntry => entry !== null)
-    : [];
-  return {
-    version: typeof parsed.version === "number" ? parsed.version : QUOTE_JOURNAL_VERSION,
-    updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : Date.now(),
-    records,
-  };
-}
-
-function loadState(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-}): QuoteJournalState {
-  const scopeKey = getScopeKey(params);
-  const cached = stateCache.get(scopeKey);
-  if (cached) {
-    return cached;
-  }
-
-  const persisted = readNamespaceJson<Partial<QuoteJournalState>>(QUOTE_JOURNAL_NAMESPACE, {
-    storePath: params.storePath,
-    scope: { accountId: params.accountId, conversationId: params.conversationId || undefined },
-    format: "json",
-    fallback: fallbackState(),
-  });
-  const normalized = normalizeState(persisted);
-  stateCache.set(scopeKey, normalized);
-  return normalized;
-}
-
-function writeState(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-  state: QuoteJournalState;
-}): void {
-  stateCache.set(getScopeKey(params), params.state);
-  writeNamespaceJsonAtomic(QUOTE_JOURNAL_NAMESPACE, {
-    storePath: params.storePath,
-    scope: { accountId: params.accountId, conversationId: params.conversationId || undefined },
-    format: "json",
-    data: params.state,
-  });
-}
-
-function pruneByTtl(records: JournalEntry[], ttlDays: number, nowMs: number): JournalEntry[] {
-  if (!ttlDays || ttlDays <= 0) {
-    return records;
-  }
-  const cutoff = nowMs - ttlDays * 24 * 60 * 60 * 1000;
-  return records.filter((entry) => entry.createdAt >= cutoff);
-}
-
-function capRecords(records: JournalEntry[]): JournalEntry[] {
-  if (records.length <= MAX_RECORDS_PER_SCOPE) {
-    return records;
-  }
-  return records.slice(-MAX_RECORDS_PER_SCOPE);
-}
-
-export function appendQuoteJournalEntry(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-  msgId: string;
-  messageType: string;
-  text?: string;
-  createdAt: number;
-  ttlDays?: number;
-  nowMs?: number;
-}): void {
-  const now = params.nowMs ?? Date.now();
-  const ttlDays = params.ttlDays ?? DEFAULT_JOURNAL_TTL_DAYS;
-  const state = loadState(params);
-  const records = pruneByTtl(state.records, ttlDays, now);
-  records.push({
-    msgId: params.msgId,
-    messageType: params.messageType,
-    text: params.text,
-    createdAt: params.createdAt,
-  });
-  const cappedRecords = capRecords(records);
-  writeState({
-    storePath: params.storePath,
-    accountId: params.accountId,
-    conversationId: params.conversationId,
-    state: {
-      version: QUOTE_JOURNAL_VERSION,
-      updatedAt: now,
-      records: cappedRecords,
-    },
-  });
-}
-
-export function cleanupExpiredQuoteJournalEntries(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-  ttlDays: number;
-  nowMs?: number;
-}): number {
-  const now = params.nowMs ?? Date.now();
-  const state = loadState(params);
-  const kept = pruneByTtl(state.records, params.ttlDays, now);
-  const removed = state.records.length - kept.length;
-  if (removed > 0) {
-    writeState({
-      storePath: params.storePath,
-      accountId: params.accountId,
-      conversationId: params.conversationId,
-      state: {
-        version: QUOTE_JOURNAL_VERSION,
-        updatedAt: now,
-        records: kept,
-      },
-    });
-  }
-  return removed;
-}
-
-export function resolveQuotedMessageById(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-  originalMsgId: string;
-  ttlDays?: number;
-  nowMs?: number;
-}): { msgId: string; text?: string; createdAt: number } | null {
-  const state = loadState(params);
-  const now = params.nowMs ?? Date.now();
-  const ttlDays = params.ttlDays ?? DEFAULT_JOURNAL_TTL_DAYS;
-  const records = capRecords(pruneByTtl(state.records, ttlDays, now));
-  for (let i = records.length - 1; i >= 0; i--) {
-    const entry = records[i];
-    if (entry.msgId === params.originalMsgId) {
-      return { msgId: entry.msgId, text: entry.text, createdAt: entry.createdAt };
-    }
-  }
-  return null;
-}
-
-export async function appendOutboundToQuoteJournal(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-  messageId?: string;
-  text?: string;
-  messageType?: string;
-  log?: unknown;
-}): Promise<void> {
-  try {
-    if (!params.messageId) {
-      return;
-    }
-    appendQuoteJournalEntry({
-      storePath: params.storePath,
-      accountId: params.accountId,
-      conversationId: params.conversationId || null,
-      msgId: params.messageId,
-      messageType: params.messageType || "outbound",
-      text: params.text,
-      createdAt: Date.now(),
-    });
-  } catch (err) {
-    (params.log as { debug?: (message: string) => void } | undefined)?.debug?.(
-      `[quote-journal] appendOutbound failed: ${String(err)}`,
-    );
-  }
-}
-
-export async function appendProactiveOutboundJournal(params: {
-  storePath: string;
-  accountId: string;
-  conversationId: string | null;
-  messageId?: string;
-  text?: string;
-  messageType?: string;
-  log?: unknown;
-}): Promise<void> {
-  return appendOutboundToQuoteJournal(params);
-}