@soimy/dingtalk 3.5.1 → 3.5.3

package/src/command/inbound-command-dispatch-service.ts

@@ -0,0 +1,464 @@
+import {
+  applyManualGlobalLearningRule,
+  applyManualSessionLearningNote,
+  applyManualTargetLearningRule,
+  applyManualTargetsLearningRule,
+  applyTargetSetLearningRule,
+  createOrUpdateTargetSet,
+  deleteManualRule,
+  disableManualRule,
+  listLearningTargetSets,
+  listScopedLearningRules,
+  resolveManualForcedReply,
+} from "../feedback-learning-service";
+import {
+  formatLearnAppliedReply,
+  formatLearnCommandHelp,
+  formatLearnDeletedReply,
+  formatLearnDisabledReply,
+  formatLearnListReply,
+  formatOwnerOnlyDeniedReply,
+  formatOwnerStatusReply,
+  formatTargetSetSavedReply,
+  formatWhereAmIReply,
+  formatWhoAmIReply,
+  isLearningOwner,
+  parseLearnCommand,
+} from "../learning-command-service";
+import {
+  formatSessionAliasBoundReply,
+  formatSessionAliasClearedReply,
+  formatSessionAliasReply,
+  formatSessionAliasSetReply,
+  formatSessionAliasUnboundReply,
+  formatSessionAliasValidationErrorReply,
+  parseSessionCommand,
+  validateSessionAlias,
+} from "../session-command-service";
+import type { SessionPeerSourceKind } from "../session-peer-store";
+import type { DingTalkConfig, HandleDingTalkMessageParams, MessageContent } from "../types";
+
+type InboundCommandDispatchParams = {
+  cfg: HandleDingTalkMessageParams["cfg"];
+  accountId: string;
+  dingtalkConfig: DingTalkConfig;
+  senderId: string;
+  isDirect: boolean;
+  extractedText: string;
+  messageType: MessageContent["messageType"];
+  data: {
+    conversationId: string;
+    senderId?: string;
+    senderStaffId?: string;
+  };
+  accountStorePath: string;
+  currentSessionSourceKind: SessionPeerSourceKind;
+  currentSessionSourceId: string;
+  peerIdOverride?: string;
+  sessionPeer: {
+    peerId: string;
+  };
+  sendReply: (text: string) => Promise<void>;
+  clearSessionPeerOverride: (params: {
+    storePath: string;
+    accountId: string;
+    sourceKind: SessionPeerSourceKind;
+    sourceId: string;
+  }) => boolean;
+  setSessionPeerOverride: (params: {
+    storePath: string;
+    accountId: string;
+    sourceKind: SessionPeerSourceKind;
+    sourceId: string;
+    peerId: string;
+  }) => void;
+};
+
+export async function handleInboundCommandDispatch(
+  params: InboundCommandDispatchParams,
+): Promise<boolean> {
+  const parsedLearnCommand = parseLearnCommand(params.extractedText);
+  const parsedSessionCommand = parseSessionCommand(params.extractedText);
+  const isOwner = isLearningOwner({
+    cfg: params.cfg,
+    config: params.dingtalkConfig,
+    senderId: params.senderId,
+    rawSenderId: params.data.senderId,
+  });
+
+  if (params.isDirect && parsedLearnCommand.scope === "whoami") {
+    await params.sendReply(
+      formatWhoAmIReply({
+        senderId: params.senderId,
+        rawSenderId: params.data.senderId,
+        senderStaffId: params.data.senderStaffId,
+        isOwner,
+      }),
+    );
+    return true;
+  }
+
+  if (parsedLearnCommand.scope === "whereami") {
+    await params.sendReply(
+      formatWhereAmIReply({
+        conversationId: params.data.conversationId,
+        conversationType: params.isDirect ? "dm" : "group",
+        peerId: params.sessionPeer.peerId,
+      }),
+    );
+    return true;
+  }
+
+  if (params.isDirect && parsedLearnCommand.scope === "owner-status") {
+    await params.sendReply(
+      formatOwnerStatusReply({
+        senderId: params.senderId,
+        rawSenderId: params.data.senderId,
+        isOwner,
+      }),
+    );
+    return true;
+  }
+
+  if (parsedLearnCommand.scope === "help") {
+    await params.sendReply(formatLearnCommandHelp());
+    return true;
+  }
+
+  if (
+    (parsedLearnCommand.scope === "global" ||
+      parsedLearnCommand.scope === "session" ||
+      parsedLearnCommand.scope === "here" ||
+      parsedLearnCommand.scope === "target" ||
+      parsedLearnCommand.scope === "targets" ||
+      parsedLearnCommand.scope === "list" ||
+      parsedLearnCommand.scope === "disable" ||
+      parsedLearnCommand.scope === "delete" ||
+      parsedLearnCommand.scope === "target-set-create" ||
+      parsedLearnCommand.scope === "target-set-apply" ||
+      parsedSessionCommand.scope === "session-alias-show" ||
+      parsedSessionCommand.scope === "session-alias-set" ||
+      parsedSessionCommand.scope === "session-alias-clear" ||
+      parsedSessionCommand.scope === "session-alias-bind" ||
+      parsedSessionCommand.scope === "session-alias-unbind") &&
+    !isOwner
+  ) {
+    await params.sendReply(formatOwnerOnlyDeniedReply());
+    return true;
+  }
+
+  if (isOwner) {
+    if (parsedSessionCommand.scope === "session-alias-show") {
+      await params.sendReply(
+        formatSessionAliasReply({
+          sourceKind: params.currentSessionSourceKind,
+          sourceId: params.currentSessionSourceId,
+          peerId: params.sessionPeer.peerId,
+          aliasSource: params.peerIdOverride ? "override" : "default",
+        }),
+      );
+      return true;
+    }
+
+    if (parsedSessionCommand.scope === "session-alias-set" && parsedSessionCommand.peerId) {
+      const aliasValidationError = validateSessionAlias(parsedSessionCommand.peerId);
+      if (aliasValidationError) {
+        await params.sendReply(formatSessionAliasValidationErrorReply(aliasValidationError));
+        return true;
+      }
+      params.setSessionPeerOverride({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        sourceKind: params.currentSessionSourceKind,
+        sourceId: params.currentSessionSourceId,
+        peerId: parsedSessionCommand.peerId,
+      });
+      await params.sendReply(
+        formatSessionAliasSetReply({
+          sourceKind: params.currentSessionSourceKind,
+          sourceId: params.currentSessionSourceId,
+          peerId: parsedSessionCommand.peerId,
+        }),
+      );
+      return true;
+    }
+
+    if (parsedSessionCommand.scope === "session-alias-clear") {
+      params.clearSessionPeerOverride({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        sourceKind: params.currentSessionSourceKind,
+        sourceId: params.currentSessionSourceId,
+      });
+      await params.sendReply(
+        formatSessionAliasClearedReply({
+          sourceKind: params.currentSessionSourceKind,
+          sourceId: params.currentSessionSourceId,
+        }),
+      );
+      return true;
+    }
+
+    if (
+      parsedSessionCommand.scope === "session-alias-bind" &&
+      parsedSessionCommand.sourceKind &&
+      parsedSessionCommand.sourceId &&
+      parsedSessionCommand.peerId
+    ) {
+      const aliasValidationError = validateSessionAlias(parsedSessionCommand.peerId);
+      if (aliasValidationError) {
+        await params.sendReply(formatSessionAliasValidationErrorReply(aliasValidationError));
+        return true;
+      }
+      params.setSessionPeerOverride({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        sourceKind: parsedSessionCommand.sourceKind,
+        sourceId: parsedSessionCommand.sourceId,
+        peerId: parsedSessionCommand.peerId,
+      });
+      await params.sendReply(
+        formatSessionAliasBoundReply({
+          sourceKind: parsedSessionCommand.sourceKind,
+          sourceId: parsedSessionCommand.sourceId,
+          peerId: parsedSessionCommand.peerId,
+        }),
+      );
+      return true;
+    }
+
+    if (
+      parsedSessionCommand.scope === "session-alias-unbind" &&
+      parsedSessionCommand.sourceKind &&
+      parsedSessionCommand.sourceId
+    ) {
+      const existed = params.clearSessionPeerOverride({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        sourceKind: parsedSessionCommand.sourceKind,
+        sourceId: parsedSessionCommand.sourceId,
+      });
+      await params.sendReply(
+        formatSessionAliasUnboundReply({
+          sourceKind: parsedSessionCommand.sourceKind,
+          sourceId: parsedSessionCommand.sourceId,
+          existed,
+        }),
+      );
+      return true;
+    }
+
+    if (parsedLearnCommand.scope === "global" && parsedLearnCommand.instruction) {
+      const applied = applyManualGlobalLearningRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await params.sendReply(
+        formatLearnAppliedReply({
+          scope: "global",
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied?.ruleId,
+        }),
+      );
+      return true;
+    }
+
+    if (parsedLearnCommand.scope === "session" && parsedLearnCommand.instruction) {
+      applyManualSessionLearningNote({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        targetId: params.data.conversationId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await params.sendReply(
+        formatLearnAppliedReply({
+          scope: "session",
+          instruction: parsedLearnCommand.instruction,
+        }),
+      );
+      return true;
+    }
+
+    if (parsedLearnCommand.scope === "here" && parsedLearnCommand.instruction) {
+      const applied = applyManualTargetLearningRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        targetId: params.data.conversationId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await params.sendReply(
+        formatLearnAppliedReply({
+          scope: "target",
+          targetId: params.data.conversationId,
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied?.ruleId,
+        }),
+      );
+      return true;
+    }
+
+    if (
+      parsedLearnCommand.scope === "target" &&
+      parsedLearnCommand.targetId &&
+      parsedLearnCommand.instruction
+    ) {
+      const applied = applyManualTargetLearningRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        targetId: parsedLearnCommand.targetId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await params.sendReply(
+        formatLearnAppliedReply({
+          scope: "target",
+          targetId: parsedLearnCommand.targetId,
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied?.ruleId,
+        }),
+      );
+      return true;
+    }
+
+    if (
+      parsedLearnCommand.scope === "targets" &&
+      parsedLearnCommand.targetIds?.length &&
+      parsedLearnCommand.instruction
+    ) {
+      const applied = applyManualTargetsLearningRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        targetIds: parsedLearnCommand.targetIds,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await params.sendReply(
+        formatLearnAppliedReply({
+          scope: "targets",
+          targetIds: parsedLearnCommand.targetIds,
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied[0]?.ruleId,
+        }),
+      );
+      return true;
+    }
+
+    if (
+      parsedLearnCommand.scope === "target-set-create" &&
+      parsedLearnCommand.setName &&
+      parsedLearnCommand.targetIds?.length
+    ) {
+      const saved = createOrUpdateTargetSet({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        name: parsedLearnCommand.setName,
+        targetIds: parsedLearnCommand.targetIds,
+      });
+      await params.sendReply(
+        saved
+          ? formatTargetSetSavedReply({
+              setName: parsedLearnCommand.setName,
+              targetIds: parsedLearnCommand.targetIds,
+            })
+          : "目标组保存失败，请检查名称和目标列表。",
+      );
+      return true;
+    }
+
+    if (
+      parsedLearnCommand.scope === "target-set-apply" &&
+      parsedLearnCommand.setName &&
+      parsedLearnCommand.instruction
+    ) {
+      const applied = applyTargetSetLearningRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        name: parsedLearnCommand.setName,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await params.sendReply(
+        applied.length > 0
+          ? formatLearnAppliedReply({
+              scope: "target-set",
+              setName: parsedLearnCommand.setName,
+              targetIds: applied.map((item) => item.targetId),
+              instruction: parsedLearnCommand.instruction,
+              ruleId: applied[0]?.ruleId,
+            })
+          : `未找到目标组 \`${parsedLearnCommand.setName}\`，或该目标组为空。`,
+      );
+      return true;
+    }
+
+    if (parsedLearnCommand.scope === "list") {
+      const rules = listScopedLearningRules({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+      })
+        .slice(0, 20)
+        .map((rule) => {
+          const scope = rule.scope === "target" ? `target(${rule.targetId})` : "global";
+          const status = rule.enabled ? "enabled" : "disabled";
+          return `- [${scope}] ${rule.ruleId} (${status}) => ${rule.instruction}`;
+        });
+      const targetSets = listLearningTargetSets({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+      })
+        .slice(0, 10)
+        .map((targetSet) => `- [target-set] ${targetSet.name} => ${targetSet.targetIds.join(", ")}`);
+      await params.sendReply(formatLearnListReply([...rules, ...targetSets]));
+      return true;
+    }
+
+    if (parsedLearnCommand.scope === "disable" && parsedLearnCommand.ruleId) {
+      const result = disableManualRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        ruleId: parsedLearnCommand.ruleId,
+      });
+      await params.sendReply(
+        formatLearnDisabledReply({
+          ruleId: parsedLearnCommand.ruleId,
+          existed: result.existed,
+          scope: result.scope,
+          targetId: result.targetId,
+        }),
+      );
+      return true;
+    }
+
+    if (parsedLearnCommand.scope === "delete" && parsedLearnCommand.ruleId) {
+      const result = deleteManualRule({
+        storePath: params.accountStorePath,
+        accountId: params.accountId,
+        ruleId: parsedLearnCommand.ruleId,
+      });
+      await params.sendReply(
+        formatLearnDeletedReply({
+          ruleId: parsedLearnCommand.ruleId,
+          existed: result.existed,
+          scope: result.scope,
+          targetId: result.targetId,
+        }),
+      );
+      return true;
+    }
+  }
+
+  const forcedContent: MessageContent = {
+    text: params.extractedText,
+    messageType: params.messageType,
+  };
+  const manualForcedReply = resolveManualForcedReply({
+    storePath: params.accountStorePath,
+    accountId: params.accountId,
+    targetId: params.data.conversationId,
+    content: forcedContent,
+  });
+  if (manualForcedReply) {
+    await params.sendReply(manualForcedReply);
+    return true;
+  }
+
+  return false;
+}

package/src/config-schema.ts

@@ -7,65 +7,78 @@ const AckReactionSchema = z.union([
   z.string().min(1),
 ]);
 
+const CardStreamingModeSchema = z.enum(["off", "answer", "all"]);
+const ContextVisibilitySchema = z.enum(["all", "allowlist", "allowlist_quote"]);
+
+/**
+ * Runtime-parsed DingTalk account config.
+ *
+ * Compatibility note:
+ * - `agentId`, `corpId`, `showThinkingStream`, and `asyncMode` are intentionally
+ *   not parsed here. They remain only in manifest metadata for legacy host/UI
+ *   compatibility and are ignored by the current runtime.
+ */
 const DingTalkAccountConfigShape = {
   /** Account name (optional display name) */
   name: z.string().optional(),
 
-  /** Whether this channel is enabled */
+  /** Enable or disable this DingTalk channel/account without deleting saved credentials. */
   enabled: z.boolean().optional().default(true),
 
-  /** DingTalk App Key (Client ID) - required for authentication */
+  /** DingTalk App Key (Client ID) used to authenticate API and Stream connections. */
   clientId: z.string().optional(),
 
-  /** DingTalk App Secret (Client Secret) - required for authentication */
+  /** DingTalk App Secret (Client Secret) used to obtain DingTalk access tokens. */
   clientSecret: z.string().optional(),
 
-  /** Direct message policy: open, pairing, or allowlist */
+  /** Direct-message access policy: open, pairing, or allowlist. */
   dmPolicy: z.enum(["open", "pairing", "allowlist"]).optional().default("open"),
 
-  /** Group message policy: open, allowlist, or disabled */
+  /** Group-message access policy: open, allowlist, or disabled. */
   groupPolicy: z.enum(["open", "allowlist", "disabled"]).optional().default("open"),
 
-  /** List of allowed user IDs for allowlist policy */
+  /** User IDs allowed when `dmPolicy` is `allowlist`. */
   allowFrom: z.array(z.string()).optional(),
 
-  /** List of allowed user IDs for group allowlist policy */
+  /** Sender IDs allowed when `groupPolicy` is `allowlist`. */
   groupAllowFrom: z.array(z.string()).optional(),
 
-  /** Default disabled. Enabling "all" allows learned displayName lookup but may misroute on stale/duplicate names and is available to all callers until upstream exposes requester authz context. */
+  /** Default disabled. Enabling `all` allows learned displayName lookup but may misroute on stale or duplicate names and is available to all callers until upstream exposes requester authz context. */
   displayNameResolution: z.enum(["disabled", "all"]).optional().default("disabled"),
 
+  /** Controls how much supplemental host context remains visible to the reply runtime. `allowlist_quote` is the safest advanced mode when only explicit quotes or replies should remain visible. */
+  contextVisibility: ContextVisibilitySchema.optional(),
+
+  /** Allowed remote media download hosts, IPs, or CIDRs for media fetches. */
   mediaUrlAllowlist: z.array(z.string()).optional(),
 
-  /** Native ack reaction mode: off, emoji, or kaomoji */
+  /** Native acknowledgement reaction mode: off, emoji, kaomoji, or a custom compatibility string. */
   ackReaction: AckReactionSchema.optional(),
 
+  /** Retention window in days for short-lived message context used by quoting and media recovery. */
   journalTTLDays: z.number().int().min(1).optional().default(DEFAULT_MESSAGE_CONTEXT_TTL_DAYS),
-  /** Enable debug logging */
+  /** Enable verbose DingTalk channel debug logging. */
   debug: z.boolean().optional().default(false),
 
-  /** Message type for replies: markdown or card */
+  /** Default reply delivery mode: markdown or card. */
   messageType: z.enum(["markdown", "card"]).optional().default("markdown"),
 
-  /** Card template ID for AI interactive cards
-   * obtain the template ID from DingTalk Developer Console.
-   * ref: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89
-   */
+  /** Deprecated and ignored. AI card replies now always use the built-in DingTalk template contract. Keep only for backward-compatible config parsing. */
   cardTemplateId: z.string().optional(),
 
-  /** Card template key for streaming updates
-   * Default: 'content' - maps to the content field in the card template
-   * This key is used in the streaming API to update specific fields in the card.
-   */
+  /** Deprecated and ignored. The built-in AI card contract owns the streaming field mapping. Keep only for backward-compatible config parsing. */
   cardTemplateKey: z.string().optional().default("content"),
 
-  /** Per-group configuration, keyed by conversationId (supports "*" wildcard) */
+  /** Per-group overrides keyed by conversationId. Supports `*` as a wildcard fallback. */
   groups: z
     .record(
       z.string(),
       z.object({
+        /** Additional system prompt appended for this group. */
         systemPrompt: z.string().optional(),
+        /** Require an explicit @mention before the bot answers in this group. */
         requireMention: z.boolean().optional(),
+        /** Optional per-group sender allowlist for tighter access control than the channel default. */
         groupAllowFrom: z.array(z.string()).optional(),
       }),
     )
@@ -73,59 +86,70 @@ const DingTalkAccountConfigShape = {
 
   /** Connection robustness configuration */
 
-  /** Maximum number of connection attempts before giving up (default: 10) */
+  /** Maximum connection attempts in a single reconnect cycle before backing off or giving up. */
   maxConnectionAttempts: z.number().int().min(1).optional().default(10),
 
-  /** Initial reconnection delay in milliseconds (default: 1000ms) */
+  /** Initial reconnect backoff delay in milliseconds. */
   initialReconnectDelay: z.number().int().min(100).optional().default(1000),
 
-  /** Maximum reconnection delay in milliseconds for exponential backoff (default: 60000ms = 1 minute) */
+  /** Upper bound for reconnect backoff delay in milliseconds. */
   maxReconnectDelay: z.number().int().min(1000).optional().default(60000),
 
-  /** Jitter factor for reconnection delay randomization (0-1, default: 0.3) */
+  /** Randomization factor added to reconnect backoff to avoid synchronized reconnect storms. */
   reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
 
-  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  /** Maximum reconnect cycles before the channel stops retrying and waits for the next lifecycle restart. */
   maxReconnectCycles: z.number().int().min(1).optional().default(10),
 
-  /** Maximum time (ms) for a single reconnect cycle before starting a new cycle (default: 50000) */
+  /** Time limit in milliseconds for one reconnect cycle before starting a fresh cycle. */
   reconnectDeadlineMs: z.number().int().min(5000).optional().default(50000),
 
-  /** Whether to use ConnectionManager (default: true). When false, rely on DWClient native keepAlive+autoReconnect. */
+  /** Enable the plugin connection manager. Disable only when you intentionally rely on DWClient native keepAlive plus autoReconnect behavior. */
   useConnectionManager: z.boolean().optional().default(true),
 
-  /** Maximum inbound media file size in MB (overrides runtime default when set) */
+  /** Maximum inbound media size in MB accepted by the plugin. When omitted, the runtime default is used. */
   mediaMaxMb: z.number().int().min(1).optional(),
 
-  /** Whether to enable underlying stream keepAlive heartbeat; defaults to !useConnectionManager when omitted */
+  /** Enable the underlying Stream client heartbeat. When omitted, runtime derives a default from `useConnectionManager`. */
   keepAlive: z.boolean().optional(),
-  /** Bypass system/global HTTP(S) proxy for DingTalk outbound send/card/upload APIs */
+  /** Bypass global or system HTTP(S) proxy settings for DingTalk send, upload, and card APIs. */
   bypassProxyForSend: z.boolean().optional().default(false),
+  /** Controls the proactive-send permission reminder shown when a conversation has not granted send rights yet. */
   proactivePermissionHint: z
     .object({
+      /** Show the proactive-send permission hint when the runtime detects missing DingTalk proactive permission. */
       enabled: z.boolean().optional().default(true),
+      /** Minimum cooldown in hours before the same proactive permission hint can be shown again. */
       cooldownHours: z.number().int().min(1).max(24 * 30).optional().default(24),
     })
     .optional()
     .default({ enabled: true, cooldownHours: 24 }),
 
-  /** Enable real-time card streaming (default: false).
-   *  When true, card updates are streamed per-token with 300ms throttle for a smoother experience, at the cost of more API calls. */
-  cardRealTimeStream: z.boolean().optional().default(false),
+  /** Deprecated compatibility flag. When true and `cardStreamingMode` is unset, runtime resolves to `cardStreamingMode: "all"`. Do not use in new configs. */
+  cardRealTimeStream: z.boolean().optional(),
+
+  /** Card streaming mode:
+   *  - off: disable incremental streaming
+   *  - answer: stream answer text
+   *  - all: stream answer + reasoning or thinking text */
+  cardStreamingMode: CardStreamingModeSchema.optional(),
+
+  /** Throttle interval in milliseconds between AI card streaming updates. */
+  cardStreamInterval: z.number().int().min(200).optional().default(1000),
 
-  /** AICard degrade duration in milliseconds after trigger errors (default: 30 minutes) */
+  /** Cooldown window in milliseconds after AI card trigger errors. Replies fall back to non-card delivery during this period. */
   aicardDegradeMs: z.number().int().min(60_000).optional().default(30 * 60 * 1000),
 
-  /** Enable local learning loop (default: false) */
+  /** Enable the local feedback-learning loop for notes, reflections, and command-assisted learning. */
   learningEnabled: z.boolean().optional(),
 
-  /** Auto-apply generated reflections into session notes/global rules (default: false) */
+  /** Automatically apply generated learning output into session notes or global rules when available. */
   learningAutoApply: z.boolean().optional(),
 
-  /** Session learning note TTL in milliseconds (default: 6 hours) */
+  /** Retention window in milliseconds for temporary learning notes. */
   learningNoteTtlMs: z.number().int().min(60_000).optional(),
 
-  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  /** Convert markdown tables to plain text before sending when you want more consistent DingTalk rendering. */
   convertMarkdownTables: z.boolean().optional().default(true),
 
   /** @mention the sender after card finalization in group chats.