@soimy/dingtalk 3.5.0 → 3.5.2

package/README.md

@@ -10,6 +10,7 @@
   <a href="https://www.npmjs.com/package/@soimy/dingtalk"><img alt="npm downloads" src="https://img.shields.io/npm/dm/%40soimy%2Fdingtalk"></a>
   <a href="https://github.com/soimy/openclaw-channel-dingtalk/actions/workflows/docs-pages.yml"><img alt="Docs" src="https://img.shields.io/github/actions/workflow/status/soimy/openclaw-channel-dingtalk/docs-pages.yml?branch=main&label=Docs"></a>
   <a href="https://github.com/soimy/openclaw-channel-dingtalk/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/soimy/openclaw-channel-dingtalk"></a>
+  <a href="https://github.com/soimy/openclaw-channel-dingtalk/blob/main/CITATION.cff"><img alt="Citation" src="https://img.shields.io/badge/Citation-CITATION.cff-1277B5"></a>
 </p>
 
 针对 OpenClaw 的钉钉企业内部机器人 Channel 渠道插件，使用 Stream 模式，无需公网 IP。
@@ -33,6 +34,11 @@
 - 发布记录：[docs/releases/index.md](docs/releases/index.md)
 - 英文入口：[docs/en/index.md](docs/en/index.md)
 
+## 引用与署名
+
+- GitHub / 机器可读引用元数据：[CITATION.cff](https://github.com/soimy/openclaw-channel-dingtalk/blob/main/CITATION.cff)
+- 维护者对复用、引用与 AI 协作场景的署名请求：[docs/contributor/citation-and-attribution.md](docs/contributor/citation-and-attribution.md)
+
 ## 安装
 
 > [!IMPORTANT]
@@ -180,4 +186,4 @@ pnpm test
 
 ## 许可
 
-[MIT](LICENSE)
+[MIT](https://github.com/soimy/openclaw-channel-dingtalk/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soimy/dingtalk",
-  "version": "3.5.0",
+  "version": "3.5.2",
   "description": "DingTalk (钉钉) channel plugin for OpenClaw",
   "keywords": [
     "bot",
@@ -46,7 +46,7 @@
     "type-check": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "axios": "^1.6.0",
+    "axios": "1.13.6",
     "dingtalk-stream": "^2.1.4",
     "form-data": "^4.0.0",
     "mammoth": "^1.12.0",
@@ -58,7 +58,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "oxfmt": "0.34.0",
     "oxlint": "^1.49.0",
-    "oxlint-tsgolint": "^0.15.0",
+    "oxlint-tsgolint": "^0.18.0",
     "typescript": "^5.3.0",
     "vitepress": "1.6.4",
     "vitest": "^3.2.4"
@@ -66,7 +66,18 @@
   "peerDependencies": {
     "openclaw": ">=2026.3.24"
   },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
   "openclaw": {
+    "compat": {
+      "pluginApi": ">=2026.3.24"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24"
+    },
     "extensions": [
       "./index.ts"
     ],

package/src/ack-reaction-service.ts

@@ -1,4 +1,4 @@
-import axios from "axios";
+import axios from "./http-client";
 import { getAccessToken } from "./auth";
 import type { DingTalkConfig } from "./types";
 import { formatDingTalkErrorPayloadLog, getErrorMessage, getProxyBypassOption } from "./utils";

package/src/auth.ts

@@ -1,4 +1,4 @@
-import axios from "axios";
+import axios from "./http-client";
 import type { DingTalkConfig, Logger, TokenInfo } from "./types";
 import { retryWithBackoff } from "./utils";
 

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

@@ -0,0 +1,62 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+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/core";
+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/reasoning-block-assembler.ts

@@ -0,0 +1,157 @@
+export interface ReasoningBlockAssembler {
+    ingestSnapshot: (text: string | undefined) => string[];
+    flushPendingAtBoundary: () => string[];
+    reset: () => void;
+}
+
+function stripReasoningPrefix(text: string): string {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("Reasoning:")) {
+        return trimmed.slice("Reasoning:".length).trimStart();
+    }
+    return trimmed;
+}
+
+function cleanReasoningLine(line: string): string {
+    return line.trim().replace(/^_/, "").replace(/_$/, "").trim();
+}
+
+function isClosedReasoningLine(line: string): boolean {
+    const trimmed = line.trim();
+    return trimmed.startsWith("_") && trimmed.endsWith("_") && trimmed.length >= 2;
+}
+
+function startsReasonBlock(line: string): boolean {
+    return cleanReasoningLine(line).startsWith("Reason:");
+}
+
+function blocksStartWithPrefix(blocks: string[], prefix: string[]): boolean {
+    if (prefix.length > blocks.length) {
+        return false;
+    }
+    return prefix.every((entry, index) => blocks[index] === entry);
+}
+
+function parseReasoningSnapshot(text: string | undefined): {
+    completeBlocks: string[];
+    pendingBlock: string;
+} {
+    const normalized = typeof text === "string" ? stripReasoningPrefix(text) : "";
+    if (!normalized.trim()) {
+        return {
+            completeBlocks: [],
+            pendingBlock: "",
+        };
+    }
+
+    const lines = normalized
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+
+    const completeBlocks: string[] = [];
+    let currentLines: string[] = [];
+    let currentMode: "explicit" | "implicit" | null = null;
+    let currentComplete = true;
+
+    const finalizeCurrent = () => {
+        if (currentLines.length === 0) {
+            return;
+        }
+        if (currentMode === "explicit" && currentComplete) {
+            completeBlocks.push(currentLines.join("\n"));
+        }
+    };
+
+    for (const line of lines) {
+        if (startsReasonBlock(line)) {
+            finalizeCurrent();
+            currentLines = [cleanReasoningLine(line)];
+            currentMode = "explicit";
+            currentComplete = isClosedReasoningLine(line);
+            continue;
+        }
+
+        if (currentLines.length === 0) {
+            const trimmedLine = line.trim();
+            const cleanedLine = cleanReasoningLine(line);
+            if (!cleanedLine) {
+                continue;
+            }
+            if (!trimmedLine.startsWith("_")) {
+                continue;
+            }
+            currentLines = [cleanedLine];
+            currentMode = "implicit";
+            currentComplete = false;
+            continue;
+        }
+
+        currentLines.push(cleanReasoningLine(line));
+        currentComplete = currentMode === "explicit"
+            ? currentComplete && isClosedReasoningLine(line)
+            : false;
+    }
+
+    if (currentLines.length === 0) {
+        return {
+            completeBlocks,
+            pendingBlock: "",
+        };
+    }
+
+    if (currentMode === "explicit" && currentComplete) {
+        completeBlocks.push(currentLines.join("\n"));
+        return {
+            completeBlocks,
+            pendingBlock: "",
+        };
+    }
+
+    return {
+        completeBlocks,
+        pendingBlock: currentLines.join("\n").trim(),
+    };
+}
+
+export function createReasoningBlockAssembler(): ReasoningBlockAssembler {
+    let emittedBlocks: string[] = [];
+    let pendingBlock = "";
+
+    return {
+        ingestSnapshot(text: string | undefined): string[] {
+            const parsed = parseReasoningSnapshot(text);
+            pendingBlock = parsed.pendingBlock;
+
+            if (parsed.completeBlocks.length === 0) {
+                return [];
+            }
+
+            if (blocksStartWithPrefix(parsed.completeBlocks, emittedBlocks)) {
+                const nextBlocks = parsed.completeBlocks.slice(emittedBlocks.length);
+                emittedBlocks = [...parsed.completeBlocks];
+                return nextBlocks;
+            }
+
+            if (blocksStartWithPrefix(emittedBlocks, parsed.completeBlocks)) {
+                return [];
+            }
+
+            return [];
+        },
+
+        flushPendingAtBoundary(): string[] {
+            if (!pendingBlock.trim()) {
+                return [];
+            }
+            const flushed = pendingBlock;
+            pendingBlock = "";
+            return [flushed];
+        },
+
+        reset(): void {
+            emittedBlocks = [];
+            pendingBlock = "";
+        },
+    };
+}

package/src/card-callback-service.ts

@@ -1,10 +1,18 @@
+import axios from "./http-client";
+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;
+}