@soimy/dingtalk 3.4.2 → 3.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soimy/dingtalk",
-  "version": "3.4.2",
+  "version": "3.5.1",
   "description": "DingTalk (钉钉) channel plugin for OpenClaw",
   "keywords": [
     "bot",
@@ -25,6 +25,7 @@
     "clawbot.plugin.json"
   ],
   "type": "module",
+  "packageManager": "pnpm@10.33.0",
   "main": "index.ts",
   "publishConfig": {
     "access": "public",
@@ -35,6 +36,10 @@
     "format:check": "oxfmt --check package.json tsconfig.json index.ts src/*.ts",
     "lint": "oxlint --type-aware index.ts src",
     "lint:fix": "oxlint --type-aware --fix index.ts src && pnpm format",
+    "docs:dev": "vitepress dev docs --host 127.0.0.1 --port 8000",
+    "docs:serv": "vitepress dev docs --host 127.0.0.1 --port 8000",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs --host 127.0.0.1 --port 4173",
     "monitor:stream": "node scripts/dingtalk-stream-monitor.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
@@ -55,12 +60,19 @@
     "oxlint": "^1.49.0",
     "oxlint-tsgolint": "^0.15.0",
     "typescript": "^5.3.0",
+    "vitepress": "1.6.4",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.14"
+    "openclaw": ">=2026.3.24"
   },
   "openclaw": {
+    "compat": {
+      "pluginApi": ">=2026.3.24"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24"
+    },
     "extensions": [
       "./index.ts"
     ],
@@ -72,8 +84,8 @@
       "id": "dingtalk",
       "label": "DingTalk",
       "selectionLabel": "DingTalk (钉钉)",
-      "docsPath": "https://github.com/soimy/openclaw-channel-dingtalk",
-      "docsLabel": "plugin docs",
+      "docsPath": "https://soimy.github.io/openclaw-channel-dingtalk/",
+      "docsLabel": "documentation",
       "blurb": "钉钉企业内部机器人，使用 Stream 模式，无需公网 IP。",
       "order": 70,
       "aliases": [
@@ -82,6 +94,7 @@
       ]
     },
     "install": {
+      "minHostVersion": ">=2026.3.24",
       "npmSpec": "@soimy/dingtalk",
       "localPath": ".",
       "defaultChoice": "npm"

package/src/ack-reaction-service.ts

@@ -23,59 +23,69 @@ type AckReactionLogger = {
 type AckReactionTarget = {
   msgId: string;
   conversationId: string;
-  robotCode?: string;
   reactionName?: string;
 };
 
+type ResolvedAckReactionRequest = {
+  msgId: string;
+  conversationId: string;
+  robotCode: string;
+  reactionName: string;
+};
+
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
 }
 
-function formatAckReactionTarget(data: AckReactionTarget): string {
+function formatAckReactionTarget(data: {
+  msgId: string;
+  conversationId: string;
+  reactionName: string;
+}): string {
   return `msgId=${data.msgId || "-"} conversationId=${data.conversationId || "-"} reactionName=${data.reactionName || DINGTALK_NATIVE_ACK_REACTION}`;
 }
 
-function resolveAckReactionPayload(config: DingTalkConfig, data: AckReactionTarget): {
-  robotCode: string;
-  reactionName: string;
-} | null {
-  const robotCode = (data.robotCode || config.robotCode || config.clientId || "").trim();
+function resolveAckReactionRequest(
+  config: DingTalkConfig,
+  data: AckReactionTarget,
+): ResolvedAckReactionRequest | null {
+  const robotCode = (config.clientId || "").trim();
   const reactionName =
     (data.reactionName || DINGTALK_NATIVE_ACK_REACTION).trim() || DINGTALK_NATIVE_ACK_REACTION;
   if (!robotCode || !data.msgId || !data.conversationId) {
     return null;
   }
-  return { robotCode, reactionName };
+  return {
+    msgId: data.msgId,
+    conversationId: data.conversationId,
+    robotCode,
+    reactionName,
+  };
 }
 
 async function callEmotionApi(
   config: DingTalkConfig,
-  data: AckReactionTarget,
+  request: ResolvedAckReactionRequest,
   endpoint: "reply" | "recall",
   successLog: string,
   errorLogPrefix: string,
   errorPayloadKey: "inbound.ackReactionAttach" | "inbound.ackReactionRecall",
   log?: AckReactionLogger,
 ): Promise<{ ok: boolean; error?: unknown }> {
-  const payload = resolveAckReactionPayload(config, data);
-  if (!payload) {
-    return { ok: false };
-  }
-
   try {
     const token = await getAccessToken(config, log as any);
     await axios.post(
       `https://api.dingtalk.com/v1.0/robot/emotion/${endpoint}`,
       {
-        robotCode: payload.robotCode,
-        openMsgId: data.msgId,
-        openConversationId: data.conversationId,
+        robotCode: request.robotCode,
+        openMsgId: request.msgId,
+        openConversationId: request.conversationId,
         emotionType: 2,
-        emotionName: payload.reactionName,
+        emotionName: request.reactionName,
         textEmotion: {
           emotionId: THINKING_EMOTION_ID,
-          emotionName: payload.reactionName,
-          text: payload.reactionName,
+          emotionName: request.reactionName,
+          text: request.reactionName,
           backgroundId: THINKING_EMOTION_BACKGROUND_ID,
         },
       },
@@ -119,6 +129,10 @@ export async function attachNativeAckReaction(
   data: AckReactionTarget,
   log?: AckReactionLogger,
 ): Promise<boolean> {
+  const request = resolveAckReactionRequest(config, data);
+  if (!request) {
+    return false;
+  }
   for (let index = 0; index < THINKING_REACTION_ATTACH_DELAYS_MS.length; index += 1) {
     const delayMs = THINKING_REACTION_ATTACH_DELAYS_MS[index];
     if (delayMs > 0) {
@@ -128,10 +142,10 @@ export async function attachNativeAckReaction(
     const attemptLabel = `${attempt}/${THINKING_REACTION_ATTACH_DELAYS_MS.length}`;
     const result = await callEmotionApi(
       config,
-      data,
+      request,
       "reply",
-      `[DingTalk] Native ack reaction attach succeeded (${formatAckReactionTarget(data)} attempt=${attemptLabel})`,
-      `[DingTalk] Native ack reaction attach failed (${formatAckReactionTarget(data)} attempt=${attemptLabel})`,
+      `[DingTalk] Native ack reaction attach succeeded (${formatAckReactionTarget(request)} attempt=${attemptLabel})`,
+      `[DingTalk] Native ack reaction attach failed (${formatAckReactionTarget(request)} attempt=${attemptLabel})`,
       "inbound.ackReactionAttach",
       log,
     );
@@ -143,7 +157,7 @@ export async function attachNativeAckReaction(
       break;
     }
     log?.debug?.(
-      `[DingTalk] Retrying native ack reaction attach (${formatAckReactionTarget(data)} nextAttempt=${attempt + 1}/${THINKING_REACTION_ATTACH_DELAYS_MS.length})`,
+      `[DingTalk] Retrying native ack reaction attach (${formatAckReactionTarget(request)} nextAttempt=${attempt + 1}/${THINKING_REACTION_ATTACH_DELAYS_MS.length})`,
     );
   }
   return false;
@@ -151,12 +165,12 @@ export async function attachNativeAckReaction(
 
 async function recallNativeAckReaction(
   config: DingTalkConfig,
-  data: AckReactionTarget,
+  request: ResolvedAckReactionRequest,
   log?: AckReactionLogger,
 ): Promise<boolean> {
   const result = await callEmotionApi(
     config,
-    data,
+    request,
     "recall",
     "[DingTalk] Native ack reaction recall succeeded",
     "[DingTalk] Native ack reaction recall failed",
@@ -171,11 +185,15 @@ export async function recallNativeAckReactionWithRetry(
   data: AckReactionTarget,
   log?: AckReactionLogger,
 ): Promise<void> {
+  const request = resolveAckReactionRequest(config, data);
+  if (!request) {
+    return;
+  }
   for (const delayMs of THINKING_REACTION_RECALL_DELAYS_MS) {
     if (delayMs > 0) {
       await new Promise(resolve => setTimeout(resolve, delayMs));
     }
-    if (await recallNativeAckReaction(config, data, log)) {
+    if (await recallNativeAckReaction(config, request, log)) {
       return;
     }
   }

package/src/card/card-action-handler.ts

@@ -0,0 +1,62 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { CardCallbackAnalysis } from "../card-callback-service";
+import type { DingTalkConfig, Logger } from "../types";
+import { resolveCardRun } from "./card-run-registry";
+import { stopCardRun } from "./card-stop-handler";
+
+export interface CardActionResult {
+  handled: boolean;
+}
+
+export async function handleCardAction(params: {
+  analysis: CardCallbackAnalysis;
+  cfg: OpenClawConfig;
+  accountId: string;
+  config: DingTalkConfig;
+  log?: Logger;
+}): Promise<CardActionResult> {
+  if (params.analysis.actionId !== "btn_stop") {
+    return { handled: false };
+  }
+
+  const outTrackId = params.analysis.outTrackId;
+  if (!outTrackId) {
+    params.log?.warn?.(
+      `[${params.accountId}] [DingTalk][CardStop] stop callback missing outTrackId — cannot route stop request`,
+    );
+    return { handled: false };
+  }
+
+  // In group chats, only the user who initiated the conversation can stop it.
+  // Fail-closed: reject when clicker identity is missing but owner is known.
+  const clickerUserId = params.analysis.userId;
+  const record = resolveCardRun(outTrackId);
+  if (record?.ownerUserId) {
+    if (!clickerUserId || record.ownerUserId !== clickerUserId) {
+      params.log?.info?.(
+        `[${params.accountId}] [DingTalk][CardStop] rejected: clicker=${clickerUserId ?? "unknown"} owner=${record.ownerUserId}`,
+      );
+      return { handled: true };
+    }
+  }
+
+  const result = await stopCardRun({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    outTrackId,
+    config: params.config,
+    clickerUserId,
+    log: params.log,
+  });
+  if (!result.ok) {
+    params.log?.warn?.(
+      `[${params.accountId}] [DingTalk][CardStop] stop failed status=${result.status} reason=${result.reason ?? "unknown"}`,
+    );
+  } else {
+    params.log?.info?.(
+      `[${params.accountId}] [DingTalk][CardStop] stop succeeded outTrackId=${outTrackId}`,
+    );
+  }
+
+  return { handled: true };
+}

package/src/card/card-run-registry.ts

@@ -0,0 +1,118 @@
+/**
+ * In-process card run registry for tracking active AI card runs.
+ *
+ * DEPLOYMENT CONSTRAINT: This registry uses a process-local Map. In multi-process
+ * deployments (cluster/PM2), stop callbacks may route to a different worker than
+ * the one that created the card run, causing resolveCardRun to return null and
+ * the stop button to silently fail. Ensure single-process deployment or sticky
+ * routing per card callback when using the stop button feature.
+ */
+import type { CardDraftController } from "../card-draft-controller";
+import type { AICardInstance } from "../types";
+
+export interface CardRunRecord {
+  outTrackId: string;
+  accountId: string;
+  sessionKey: string;
+  /** OpenClaw agent ID resolved from the inbound route. */
+  agentId: string;
+  /** DingTalk userId of the user who initiated this card run. */
+  ownerUserId?: string;
+  card?: AICardInstance;
+  controller?: CardDraftController;
+  stopRequestedAt?: number;
+  registeredAt: number;
+}
+
+const CARD_RUN_TTL_MS = 30 * 60 * 1000;
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+const records = new Map<string, CardRunRecord>();
+
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+function ensureSweepTimer(): void {
+  if (sweepTimer) {
+    return;
+  }
+  sweepTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, record] of records) {
+      if (now - record.registeredAt > CARD_RUN_TTL_MS) {
+        records.delete(key);
+      }
+    }
+    if (records.size === 0 && sweepTimer) {
+      clearInterval(sweepTimer);
+      sweepTimer = null;
+    }
+  }, SWEEP_INTERVAL_MS);
+  // Allow the process to exit without waiting for this timer.
+  if (typeof sweepTimer === "object" && "unref" in sweepTimer) {
+    sweepTimer.unref();
+  }
+}
+
+export function registerCardRun(
+  outTrackId: string,
+  params: {
+    accountId: string;
+    sessionKey: string;
+    agentId: string;
+    ownerUserId?: string;
+    card?: AICardInstance;
+  },
+): void {
+  const trimmed = outTrackId.trim();
+  if (!trimmed) {
+    return;
+  }
+  records.set(trimmed, {
+    outTrackId: trimmed,
+    accountId: params.accountId,
+    sessionKey: params.sessionKey,
+    agentId: params.agentId,
+    ownerUserId: params.ownerUserId,
+    card: params.card,
+    registeredAt: Date.now(),
+  });
+  ensureSweepTimer();
+}
+
+export function attachCardRunController(outTrackId: string, controller: CardDraftController): void {
+  const record = records.get(outTrackId.trim());
+  if (record) {
+    record.controller = controller;
+  }
+}
+
+export function resolveCardRun(outTrackId: string): CardRunRecord | null {
+  return records.get(outTrackId.trim()) ?? null;
+}
+
+export function markCardRunStopRequested(outTrackId: string): void {
+  const record = records.get(outTrackId.trim());
+  if (record && !record.stopRequestedAt) {
+    record.stopRequestedAt = Date.now();
+  }
+}
+
+export function isCardRunStopRequested(outTrackId: string): boolean {
+  return Boolean(records.get(outTrackId.trim())?.stopRequestedAt);
+}
+
+export function removeCardRun(outTrackId: string): void {
+  records.delete(outTrackId.trim());
+  if (records.size === 0 && sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+}
+
+export function clearCardRunRegistryForTest(): void {
+  records.clear();
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+}

package/src/card/card-stop-handler.ts

@@ -0,0 +1,94 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { getAccessToken } from "../auth";
+import { finishStoppedAICard, hideCardStopButton } from "../card-service";
+import { dispatchDingTalkCardStopCommand } from "../command/card-stop-command";
+import type { DingTalkConfig, Logger } from "../types";
+import { AICardStatus } from "../types";
+import { markCardRunStopRequested, resolveCardRun } from "./card-run-registry";
+
+export interface StopCardRunResult {
+  ok: boolean;
+  status: string;
+  reason?: string;
+  /** Last streamed content before stop, so callback response can preserve it. */
+  lastContent?: string;
+}
+
+export async function stopCardRun(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  outTrackId: string;
+  config?: DingTalkConfig;
+  clickerUserId?: string;
+  log?: Logger;
+}): Promise<StopCardRunResult> {
+  const record = resolveCardRun(params.outTrackId);
+  if (!record) {
+    return { ok: false, status: "missing-run", reason: "No active card run registration found." };
+  }
+
+  if (record.stopRequestedAt || record.card?.state === AICardStatus.STOPPED) {
+    return { ok: true, status: "already-stopped", lastContent: record.card?.lastStreamedContent };
+  }
+
+  const lastContent = record.card?.lastStreamedContent;
+
+  markCardRunStopRequested(params.outTrackId);
+  record.controller?.stop();
+
+  // --- Phase 1: Abort agent execution via native /stop command ---
+  // Dispatch FIRST so that the current run is guaranteed to still be active
+  // on the session. If we finalized the card first, a new run could start on
+  // the same sessionKey in the async gap.
+  //
+  // Only abort when this card is actively dispatching (has a controller).
+  // Cards still queued behind session lock have no controller yet — the stop
+  // guard in inbound-handler will skip dispatch when the lock is acquired.
+  let nativeStopStatus: string | undefined;
+  if (record.controller) {
+    try {
+      await dispatchDingTalkCardStopCommand({
+        cfg: params.cfg,
+        accountId: params.accountId,
+        agentId: record.agentId,
+        targetSessionKey: record.sessionKey,
+        clickerUserId: params.clickerUserId ?? record.ownerUserId ?? "unknown",
+        log: params.log,
+      });
+      nativeStopStatus = "stopped";
+    } catch (error) {
+      params.log?.warn?.(
+        `[${params.accountId}] [DingTalk][CardStop] native stop dispatch failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      nativeStopStatus = "stopped-dispatch-error";
+    }
+  }
+
+  // --- Phase 2: Finalize card via streaming API (isFinalize=true) ---
+  if (record.card) {
+    const stoppedContent = lastContent
+      ? `${lastContent}\n\n---\n*⏹️ 已停止*`
+      : "⏹️ 已停止";
+    try {
+      await finishStoppedAICard(record.card, stoppedContent, params.log);
+    } catch (error) {
+      params.log?.warn?.(
+        `[${params.accountId}] [DingTalk][CardStop] failed to finalize stopped card: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  // --- Phase 3: Hide stop button (with retry, consistent with finishAICard path) ---
+  if (params.config) {
+    try {
+      const token = await getAccessToken(params.config, params.log);
+      await hideCardStopButton(params.outTrackId, token, params.config);
+    } catch (error) {
+      params.log?.debug?.(
+        `[${params.accountId}] [DingTalk][CardStop] non-critical: failed to hide stop button: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  return { ok: true, status: nativeStopStatus ?? "stopped-pending", lastContent };
+}

package/src/card/card-template.ts

@@ -0,0 +1,20 @@
+/** Card variable value that shows the stop button. */
+export const STOP_ACTION_VISIBLE = "true";
+/** Card variable value that hides the stop button. */
+export const STOP_ACTION_HIDDEN = "false";
+
+export const BUILTIN_DINGTALK_CARD_TEMPLATE_ID =
+  process.env.DINGTALK_CARD_TEMPLATE_ID || "51cd8c7e-0e7e-4464-a795-5b81499ada7a.schema";
+export const BUILTIN_DINGTALK_CARD_CONTENT_KEY = "content";
+
+export interface DingTalkCardTemplateContract {
+  templateId: string;
+  contentKey: string;
+}
+
+/** Frozen singleton — no allocation on every call. */
+export const DINGTALK_CARD_TEMPLATE: Readonly<DingTalkCardTemplateContract> = Object.freeze({
+  templateId: BUILTIN_DINGTALK_CARD_TEMPLATE_ID,
+  contentKey: BUILTIN_DINGTALK_CARD_CONTENT_KEY,
+});
+

package/src/card-callback-service.ts

@@ -1,10 +1,18 @@
+import axios from "axios";
+import { getProxyBypassOption } from "./utils";
+
+const DINGTALK_API = "https://api.dingtalk.com";
+
 export interface CardCallbackAnalysis {
   summary: string;
   actionId?: string;
   feedbackTarget?: string;
   feedbackAckText?: string;
   userId?: string;
+  spaceId?: string;
   processQueryKey?: string;
+  outTrackId?: string;
+  cardInstanceId?: string;
 }
 
 function stringifyCandidate(value: unknown): string {
@@ -89,20 +97,58 @@ export function analyzeCardCallback(data: unknown): CardCallbackAnalysis {
   const actionId = extractCardActionId(data);
   const embeddedValue = asRecord(parseEmbeddedJson(record?.value));
   const embeddedContent = asRecord(parseEmbeddedJson(record?.content));
+  const embeddedCardPrivateData = asRecord(parseEmbeddedJson(record?.cardPrivateData));
+  const embeddedValuePrivateData = asRecord(parseEmbeddedJson(embeddedValue?.cardPrivateData));
+  const embeddedContentPrivateData = asRecord(parseEmbeddedJson(embeddedContent?.cardPrivateData));
+  const candidateRecords = [
+    record,
+    embeddedValue,
+    embeddedContent,
+    embeddedCardPrivateData,
+    embeddedValuePrivateData,
+    embeddedContentPrivateData,
+  ].filter(Boolean) as Array<Record<string, unknown>>;
+  const pickString = (...keys: string[]): string | undefined => {
+    for (const source of candidateRecords) {
+      for (const key of keys) {
+        const value = source[key];
+        if (typeof value === "string" && value.trim()) {
+          return value.trim();
+        }
+      }
+    }
+    return undefined;
+  };
   const processQueryKey =
-    (typeof record?.processQueryKey === "string" && record.processQueryKey.trim()) ||
-    (typeof embeddedValue?.processQueryKey === "string" && embeddedValue.processQueryKey.trim()) ||
-    (typeof embeddedContent?.processQueryKey === "string" && embeddedContent.processQueryKey.trim()) ||
-    undefined;
+    pickString("processQueryKey");
+  const outTrackId = pickString("outTrackId");
+  const cardInstanceId = pickString("cardInstanceId");
+  // For non-feedback paths, pickString is fine for spaceId/userId (broad search).
+  // For feedback paths, use precise extraction from record to avoid picking a
+  // same-named but different-valued spaceId from nested embedded objects.
+  const spaceId = pickString("spaceId");
+  const userId = pickString("userId");
 
   if (actionId !== "feedback_up" && actionId !== "feedback_down") {
-    return { summary, actionId, processQueryKey };
+    return {
+      summary,
+      actionId,
+      userId,
+      spaceId,
+      processQueryKey,
+      outTrackId,
+      cardInstanceId,
+    };
   }
 
+  // Feedback path: use precise extraction for spaceId/userId to avoid misrouting
+  // feedbackTarget when nested objects contain same-named fields with different values.
+  const preciseSpaceId =
+    (typeof record?.spaceId === "string" && record.spaceId.trim()) || spaceId;
+  const preciseUserId =
+    (typeof record?.userId === "string" && record.userId.trim()) || userId;
   const spaceType = typeof record?.spaceType === "string" ? record.spaceType.trim().toLowerCase() : "";
-  const spaceId = typeof record?.spaceId === "string" ? record.spaceId.trim() : "";
-  const userId = typeof record?.userId === "string" ? record.userId.trim() : "";
-  const feedbackTarget = spaceType === "im" ? userId : spaceId;
+  const feedbackTarget = spaceType === "im" ? preciseUserId : preciseSpaceId;
   const feedbackAckText =
     actionId === "feedback_up"
       ? "✅ 已收到你的点赞（反馈已记录）"
@@ -114,6 +160,42 @@ export function analyzeCardCallback(data: unknown): CardCallbackAnalysis {
     feedbackTarget: feedbackTarget || undefined,
     feedbackAckText,
     userId: userId || undefined,
+    spaceId: spaceId || undefined,
     processQueryKey,
+    outTrackId,
+    cardInstanceId,
   };
 }
+
+/**
+ * Update card variables via PUT /v1.0/card/instances.
+ * Echoes params back into cardParamMap so the template can use conditional
+ * rendering (e.g. hiding buttons when a param is set).
+ */
+export async function updateCardVariables(
+  outTrackId: string,
+  params: Record<string, unknown>,
+  token: string,
+  config?: { bypassProxyForSend?: boolean },
+): Promise<number> {
+  const stringMap: Record<string, string> = {};
+  for (const [k, v] of Object.entries(params)) {
+    stringMap[k] = typeof v === "string" ? v : JSON.stringify(v);
+  }
+  const resp = await axios.put(
+    `${DINGTALK_API}/v1.0/card/instances`,
+    {
+      outTrackId,
+      cardData: { cardParamMap: stringMap },
+      cardUpdateOptions: { updateCardDataByKey: true, updatePrivateDataByKey: true },
+    },
+    {
+      headers: {
+        "Content-Type": "application/json",
+        "x-acs-dingtalk-access-token": token,
+      },
+      ...getProxyBypassOption(config),
+    },
+  );
+  return resp.status;
+}