@soimy/dingtalk 3.4.1 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soimy/dingtalk",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "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",
@@ -51,15 +56,15 @@
   "devDependencies": {
     "@types/node": "^25.2.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "openclaw": "2026.3.22",
     "oxfmt": "0.34.0",
     "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": {
     "extensions": [
@@ -73,8 +78,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": [
@@ -83,6 +88,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-draft-controller.ts

@@ -1,61 +1,224 @@
 /**
  * Card draft controller for throttled AI Card streaming updates.
  *
- * Wraps {@link createDraftStreamLoop} with a phase-based state machine
- * (idle → reasoning → answer) that manages what content is sent to the
- * DingTalk AI Card during the reply lifecycle.
+ * The controller keeps a single rendered card timeline made of:
+ * - sealed process blocks (`thinking` / `tool`)
+ * - an optional live thinking block
+ * - accumulated answer turns rendered as plain markdown
  *
- * Responsibilities (and non-responsibilities):
- * - DOES manage throttled card preview updates via streamAICard
- * - DOES enforce single-flight, latest-wins, phase-gated semantics
- * - Does NOT handle tool append, finalize, or markdown fallback —
- *   those stay in inbound-handler's deliver callback.
+ * It delegates throttling and single-flight transport guarantees to
+ * {@link createDraftStreamLoop}.
  */
 
-import { formatContentForCard, streamAICard } from "./card-service";
+import { streamAICard } from "./card-service";
 import { createDraftStreamLoop } from "./draft-stream-loop";
 import type { AICardInstance, Logger } from "./types";
 
-export type CardDraftPhase = "idle" | "reasoning" | "answer";
+type TimelineEntryKind = "thinking" | "tool" | "answer";
+
+type TimelineEntry = {
+    kind: TimelineEntryKind;
+    text: string;
+};
 
 export interface CardDraftController {
-    updateAnswer: (text: string) => void;
-    updateReasoning: (text: string) => void;
+    updateAnswer: (text: string) => Promise<void>;
+    updateReasoning: (text: string) => Promise<void>;
+    updateThinking: (text: string) => Promise<void>;
+    updateTool: (text: string) => Promise<void>;
+    appendTool: (text: string) => Promise<void>;
     /** Signal that a new assistant turn has started (e.g. after a tool call). */
-    notifyNewAssistantTurn: () => void;
+    notifyNewAssistantTurn: () => Promise<void>;
+    startAssistantTurn: () => Promise<void>;
     flush: () => Promise<void>;
     waitForInFlight: () => Promise<void>;
     stop: () => void;
     isFailed: () => boolean;
-    /** Last content sent to card (reasoning or answer). */
+    /** Last content successfully sent to card. */
     getLastContent: () => string;
-    /** Last content sent to card during answer phase only. */
+    /** Last answer-only content successfully sent to card. */
     getLastAnswerContent: () => string;
+    /** Current answer-only content composed from all completed answer turns. */
+    getFinalAnswerContent: () => string;
+    /** Current rendered timeline, including process blocks and answer text. */
+    getRenderedContent: (options?: {
+        fallbackAnswer?: string;
+        overrideAnswer?: string;
+        compactProcessAnswerSpacing?: boolean;
+    }) => string;
+}
+
+function normalizeProcessText(text: string | undefined): string {
+    return typeof text === "string" ? text.trim() : "";
+}
+
+function normalizeAnswerText(text: string | undefined): string {
+    return typeof text === "string" ? text.trimStart() : "";
+}
+
+function quoteMarkdown(text: string): string {
+    return text
+        .split("\n")
+        .map((line) => line.trim() ? `> ${line.trim()}` : ">")
+        .join("\n");
+}
+
+function renderProcessBlock(_kind: "thinking" | "tool", text: string): string {
+    return quoteMarkdown(text);
 }
 
 export function createCardDraftController(params: {
     card: AICardInstance;
     throttleMs?: number;
+    /** Legacy compatibility: verbose mode previously lowered the throttle. */
+    verboseMode?: boolean;
     log?: Logger;
 }): CardDraftController {
-    let phase: CardDraftPhase = "idle";
     let failed = false;
     let stopped = false;
     let lastSentContent = "";
     let lastAnswerContent = "";
-    let answerPrefix = "";
-    let turnBoundaryPending = false;
+
+    let timelineEntries: TimelineEntry[] = [];
+    let activeThinkingIndex: number | null = null;
+    let activeAnswerIndex: number | null = null;
+    let pendingBoundaryPromise: Promise<void> | null = null;
+
+    const effectiveThrottleMs = params.throttleMs ?? (params.verboseMode ? 50 : 300);
+
+    const getFinalAnswerContent = (): string => {
+        return timelineEntries
+            .filter((entry) => entry.kind === "answer" && entry.text)
+            .map((entry) => entry.text)
+            .join("\n\n");
+    };
+
+    const removeTimelineEntry = (index: number) => {
+        timelineEntries.splice(index, 1);
+        if (activeThinkingIndex !== null) {
+            if (activeThinkingIndex === index) {
+                activeThinkingIndex = null;
+            } else if (activeThinkingIndex > index) {
+                activeThinkingIndex -= 1;
+            }
+        }
+        if (activeAnswerIndex !== null) {
+            if (activeAnswerIndex === index) {
+                activeAnswerIndex = null;
+            } else if (activeAnswerIndex > index) {
+                activeAnswerIndex -= 1;
+            }
+        }
+    };
+
+    const appendTimelineEntry = (kind: TimelineEntryKind, text: string): number => {
+        timelineEntries.push({ kind, text });
+        return timelineEntries.length - 1;
+    };
+
+    const renderTimeline = (options: {
+        fallbackAnswer?: string;
+        overrideAnswer?: string;
+        compactProcessAnswerSpacing?: boolean;
+    } = {}): string => {
+        const entries = timelineEntries.map((entry) => ({ ...entry }));
+
+        const overrideAnswer = normalizeAnswerText(options.overrideAnswer);
+        if (overrideAnswer) {
+            const lastAnswerIndex = [...entries]
+                .map((entry, index) => ({ entry, index }))
+                .toReversed()
+                .find(({ entry }) => entry.kind === "answer")?.index;
+            if (lastAnswerIndex !== undefined) {
+                entries[lastAnswerIndex] = { kind: "answer", text: overrideAnswer };
+            } else {
+                entries.push({ kind: "answer", text: overrideAnswer });
+            }
+        } else if (!entries.some((entry) => entry.kind === "answer" && entry.text)) {
+            const fallbackAnswer = normalizeAnswerText(options.fallbackAnswer);
+            if (fallbackAnswer) {
+                entries.push({ kind: "answer", text: fallbackAnswer });
+            }
+        }
+
+        let rendered = "";
+        const compactProcessAnswerSpacing = options.compactProcessAnswerSpacing === true;
+        for (let index = 0; index < entries.length; index += 1) {
+            const entry = entries[index];
+            if (!entry?.text) {
+                continue;
+            }
+            const part = entry.kind === "answer"
+                ? entry.text
+                : renderProcessBlock(entry.kind, entry.text);
+            if (!rendered) {
+                rendered = part;
+                continue;
+            }
+            const previousKind = entries[index - 1]?.kind;
+            const separator =
+                compactProcessAnswerSpacing && previousKind
+                    ? "\n"
+                    : "\n\n";
+            rendered += `${separator}${part}`;
+        }
+
+        return rendered;
+    };
+
+    const sealLiveThinking = () => {
+        activeThinkingIndex = null;
+    };
+
+    const sealCurrentAnswer = () => {
+        activeAnswerIndex = null;
+    };
+
+    const queueRender = () => {
+        const rendered = renderTimeline({ compactProcessAnswerSpacing: true });
+        if (rendered) {
+            loop.update(rendered);
+            return;
+        }
+        loop.resetPending();
+    };
+
+    const flushBoundaryFrame = async () => {
+        if (stopped || failed) {
+            return;
+        }
+        await loop.flush();
+        await loop.waitForInFlight();
+        loop.resetThrottleWindow();
+    };
+
+    const beginBoundaryFlush = () => {
+        if (pendingBoundaryPromise) {
+            return pendingBoundaryPromise;
+        }
+        const current = flushBoundaryFrame().finally(() => {
+            if (pendingBoundaryPromise === current) {
+                pendingBoundaryPromise = null;
+            }
+        });
+        pendingBoundaryPromise = current;
+        return current;
+    };
+
+    const waitForPendingBoundary = async () => {
+        if (pendingBoundaryPromise) {
+            await pendingBoundaryPromise;
+        }
+    };
 
     const loop = createDraftStreamLoop({
-        throttleMs: params.throttleMs ?? 300,
+        throttleMs: effectiveThrottleMs,
         isStopped: () => stopped || failed,
         sendOrEditStreamMessage: async (content: string) => {
             try {
                 await streamAICard(params.card, content, false, params.log);
                 lastSentContent = content;
-                if (phase === "answer") {
-                    lastAnswerContent = content;
-                }
+                lastAnswerContent = getFinalAnswerContent();
             } catch (err: unknown) {
                 failed = true;
                 const message = err instanceof Error ? err.message : String(err);
@@ -64,41 +227,94 @@ export function createCardDraftController(params: {
         },
     });
 
-    return {
-        updateReasoning: (text: string) => {
-            if (stopped || failed || phase === "answer") { return; }
-            phase = "reasoning";
-            const formatted = formatContentForCard(text, "thinking");
-            if (formatted) {
-                loop.update(formatted);
+    const updateReasoning = async (text: string) => {
+        await waitForPendingBoundary();
+        if (stopped || failed || activeAnswerIndex !== null) {
+            return;
+        }
+        const normalized = normalizeProcessText(text);
+        if (!normalized) {
+            return;
+        }
+        if (activeThinkingIndex === null && timelineEntries.length > 0) {
+            const lastKind = timelineEntries.at(-1)?.kind;
+            if (lastKind && lastKind !== "thinking") {
+                await flushBoundaryFrame();
             }
-        },
+        }
+        if (activeThinkingIndex !== null) {
+            timelineEntries[activeThinkingIndex] = { kind: "thinking", text: normalized };
+        } else {
+            activeThinkingIndex = appendTimelineEntry("thinking", normalized);
+        }
+        queueRender();
+    };
 
-        updateAnswer: (text: string) => {
-            if (stopped || failed) { return; }
-            if (phase !== "answer") {
-                params.log?.debug?.(`[DingTalk][Draft] phase ${phase} → answer`);
-                phase = "answer";
-                if (turnBoundaryPending && lastAnswerContent) {
-                    answerPrefix = lastAnswerContent + "\n\n";
-                }
-                turnBoundaryPending = false;
+    const updateAnswer = async (text: string) => {
+        await waitForPendingBoundary();
+        if (stopped || failed) {
+            return;
+        }
+        const normalized = normalizeAnswerText(text);
+        if (!normalized.trim()) {
+            return;
+        }
+        if (activeAnswerIndex === null && timelineEntries.length > 0) {
+            const lastKind = timelineEntries.at(-1)?.kind;
+            if (lastKind && lastKind !== "answer") {
+                await flushBoundaryFrame();
             }
-            const trimmed = text?.trimStart();
-            if (trimmed) {
-                loop.update(answerPrefix + trimmed);
-            }
-        },
+        }
+        sealLiveThinking();
+        if (activeAnswerIndex !== null) {
+            timelineEntries[activeAnswerIndex] = { kind: "answer", text: normalized };
+        } else {
+            activeAnswerIndex = appendTimelineEntry("answer", normalized);
+        }
+        queueRender();
+    };
 
-        notifyNewAssistantTurn: () => {
-            if (stopped || failed) { return; }
-            turnBoundaryPending = true;
-            if (phase === "reasoning") {
-                loop.resetPending();
-            }
-            phase = "idle";
-        },
+    const updateTool = async (text: string) => {
+        await waitForPendingBoundary();
+        if (stopped || failed) {
+            return;
+        }
+        const normalized = normalizeProcessText(text);
+        if (!normalized) {
+            return;
+        }
+        if (timelineEntries.length > 0) {
+            await flushBoundaryFrame();
+        }
+        sealLiveThinking();
+        sealCurrentAnswer();
+        appendTimelineEntry("tool", normalized);
+        queueRender();
+    };
 
+    const notifyNewAssistantTurn = async () => {
+        if (stopped || failed) {
+            return;
+        }
+        if (activeAnswerIndex !== null) {
+            sealCurrentAnswer();
+            await beginBoundaryFlush();
+            return;
+        }
+        if (activeThinkingIndex !== null) {
+            removeTimelineEntry(activeThinkingIndex);
+            loop.resetPending();
+        }
+    };
+
+    return {
+        updateAnswer,
+        updateReasoning,
+        updateThinking: updateReasoning,
+        updateTool,
+        appendTool: updateTool,
+        notifyNewAssistantTurn,
+        startAssistantTurn: notifyNewAssistantTurn,
         flush: () => loop.flush(),
         waitForInFlight: () => loop.waitForInFlight(),
 
@@ -110,5 +326,7 @@ export function createCardDraftController(params: {
         isFailed: () => failed,
         getLastContent: () => lastSentContent,
         getLastAnswerContent: () => lastAnswerContent,
+        getFinalAnswerContent,
+        getRenderedContent: renderTimeline,
     };
 }

package/src/card-service.ts

@@ -3,13 +3,15 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import axios from "axios";
 import { getAccessToken } from "./auth";
-import { stripTargetPrefix } from "./config";
+import { resolveRobotCode, stripTargetPrefix } from "./config";
 import { resolveOriginalPeerId } from "./peer-id-registry";
 import {
   createSyntheticOutboundMsgId,
   clearMessageContextCacheForTest,
   DEFAULT_CARD_CONTENT_TTL_MS,
   DEFAULT_CREATED_AT_MATCH_WINDOW_MS,
+  DEFAULT_OUTBOUND_SENDER,
+  inferConversationChatType,
   resolveByCreatedAtWindow,
   upsertOutboundMessageContext,
 } from "./message-context-store";
@@ -409,7 +411,7 @@ async function sendTemplateMismatchNotification(
 
     // Direct markdown fallback notification to user/group, without re-entering sendMessage card flow.
     const payload: Record<string, unknown> = {
-      robotCode: config.robotCode || config.clientId,
+      robotCode: resolveRobotCode(config),
       msgKey: "sampleMarkdown",
       msgParam: JSON.stringify({ title: "OpenClaw 提醒", text }),
     };
@@ -596,26 +598,19 @@ export async function createAICard(
       userIdType: 1,
       imGroupOpenDeliverModel: isGroup
         ? {
-            robotCode: config.robotCode || config.clientId,
+            robotCode: resolveRobotCode(config),
             extension: DYNAMIC_SUMMARY_EXTENSION,
           }
         : undefined,
       imRobotOpenDeliverModel: !isGroup
         ? {
             spaceType: "IM_ROBOT",
-            robotCode: config.robotCode || config.clientId,
+            robotCode: resolveRobotCode(config),
             extension: DYNAMIC_SUMMARY_EXTENSION,
           }
         : undefined,
     };
 
-    if (isGroup && !config.robotCode) {
-      log?.warn?.(
-        "[DingTalk][AICard] robotCode not configured, using clientId as fallback. " +
-          "For best compatibility, set robotCode explicitly in config.",
-      );
-    }
-
     log?.debug?.(
       `[DingTalk][AICard] POST /v1.0/card/instances/createAndDeliver body=${JSON.stringify(createAndDeliverBody)}`,
     );
@@ -895,6 +890,8 @@ function cacheCardContentByProcessQueryKey(
     createdAt: Date.now(),
     text: content,
     messageType: "card",
+    ...DEFAULT_OUTBOUND_SENDER,
+    chatType: inferConversationChatType(conversationId),
     ttlMs: DEFAULT_CARD_CONTENT_TTL_MS,
     topic: null,
     quotedRef,
@@ -932,6 +929,8 @@ export function cacheCardContent(
     createdAt,
     text: content,
     messageType: "card",
+    ...DEFAULT_OUTBOUND_SENDER,
+    chatType: inferConversationChatType(conversationId),
     ttlMs: DEFAULT_CARD_CONTENT_TTL_MS,
     topic: null,
   });