@xuanmiss-npm/dingtalk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 萧轩miss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @xuanmiss/dingtalk
+
+OpenClaw 钉钉 (DingTalk) 渠道插件 - 支持 Stream 模式接入。
+
+## 安装
+
+### 从 npm 安装
+
+```bash
+openclaw plugins install @xuanmiss/dingtalk
+```
+
+### 从本地源码安装
+
+```bash
+openclaw plugins install ./extensions/dingtalk
+# 或使用 link 模式（不复制文件，适合开发）
+openclaw plugins install -l ./extensions/dingtalk
+```
+
+## 前置条件
+
+1. 在 [钉钉开放平台](https://open.dingtalk.com/) 创建一个企业内部应用/机器人
+2. 获取以下凭证：
+   - **Client ID** (AppKey)
+   - **Client Secret** (AppSecret)
+   - **Robot Code** (机器人 Code，可选，默认使用 Client ID)
+
+## 配置
+
+### 使用环境变量（推荐用于默认账户）
+
+```bash
+export DINGTALK_CLIENT_ID="your-client-id"
+export DINGTALK_CLIENT_SECRET="your-client-secret"
+export DINGTALK_ROBOT_CODE="your-robot-code"  # 可选
+```
+
+### 使用配置文件
+
+在 OpenClaw 配置文件中添加：
+
+```json5
+{
+  channels: {
+    dingtalk: {
+      enabled: true,
+      clientId: "your-client-id",
+      clientSecret: "your-client-secret",
+      robotCode: "your-robot-code",  // 可选
+      dmPolicy: "pairing",  // "open" | "allowlist" | "pairing"
+      groupPolicy: "allowlist",  // "open" | "allowlist"
+    },
+  },
+}
+```
+
+## 消息策略
+
+### DM（私聊）策略
+
+- `pairing`（默认）：未知发送者需要通过配对码验证
+- `allowlist`：仅允许 `allowFrom` 列表中的用户
+- `open`：允许所有用户
+
+### Group（群聊）策略
+
+- `allowlist`（默认）：需要 @机器人 才会响应
+- `open`：响应所有消息（需要 @机器人）
+
+## 多账户配置
+
+支持配置多个钉钉机器人账户：
+
+```json5
+{
+  channels: {
+    dingtalk: {
+      accounts: {
+        default: {
+          name: "主机器人",
+          clientId: "client-id-1",
+          clientSecret: "secret-1",
+        },
+        alerts: {
+          name: "告警机器人",
+          clientId: "client-id-2",
+          clientSecret: "secret-2",
+        },
+      },
+    },
+  },
+}
+```
+
+## 配对验证
+
+默认情况下，新用户需要通过配对验证：
+
+```bash
+# 查看待验证的配对请求
+openclaw pairing list dingtalk
+
+# 批准配对请求
+openclaw pairing approve dingtalk <CODE>
+```
+
+## 发送消息
+
+通过 CLI 发送消息：
+
+```bash
+# 发送到用户
+openclaw message send dingtalk user:<userId> "Hello!"
+
+# 发送到群聊
+openclaw message send dingtalk <conversationId> "Hello group!"
+```
+
+## 故障排查
+
+### 常见问题
+
+1. **无法连接**
+   - 检查 Client ID 和 Client Secret 是否正确
+   - 确认机器人已在钉钉开放平台启用
+
+2. **群聊无响应**
+   - 确保机器人已被添加到群聊
+   - 确认消息中 @了机器人
+   - 检查 `groupPolicy` 配置
+
+3. **私聊无响应**
+   - 检查 `dmPolicy` 配置
+   - 如果是 `pairing` 模式，确认用户已完成配对验证
+
+## 相关链接
+
+- [钉钉开放平台](https://open.dingtalk.com/)
+- [OpenClaw 文档](https://openclaw.dev/)
+- [GitHub 仓库](https://github.com/xuanmiss/openclaw-dingtalk)
+- [问题反馈](https://github.com/xuanmiss/openclaw-dingtalk/issues)
+
+## 许可证
+
+MIT

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { dingtalkPlugin } from "./src/channel.js";
+import { setDingtalkRuntime } from "./src/runtime.js";
+
+const plugin = {
+    id: "dingtalk",
+    name: "DingTalk",
+    description: "DingTalk (钉钉) channel plugin - Stream mode",
+    configSchema: emptyPluginConfigSchema(),
+    register(api: OpenClawPluginApi) {
+        setDingtalkRuntime(api.runtime);
+        api.registerChannel({ plugin: dingtalkPlugin });
+    },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+    "id": "dingtalk",
+    "channels": [
+        "dingtalk"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {}
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@xuanmiss-npm/dingtalk",
+    "version": "0.1.0",
+    "description": "OpenClaw DingTalk (钉钉) channel plugin - Stream mode",
+    "type": "module",
+    "license": "MIT",
+    "author": "xuanmiss",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/xuanmiss/openclaw-dingtalk.git"
+    },
+    "homepage": "https://github.com/xuanmiss/openclaw-dingtalk#readme",
+    "bugs": {
+        "url": "https://github.com/xuanmiss/openclaw-dingtalk/issues"
+    },
+    "keywords": [
+        "openclaw",
+        "dingtalk",
+        "钉钉",
+        "chatbot",
+        "plugin"
+    ],
+    "dependencies": {
+        "dingtalk-stream": "^2.1.4"
+    },
+    "devDependencies": {
+        "openclaw": "2026.1.29"
+    },
+    "openclaw": {
+        "extensions": [
+            "./index.ts"
+        ],
+        "channel": {
+            "id": "dingtalk",
+            "label": "DingTalk",
+            "selectionLabel": "DingTalk (钉钉 Stream)",
+            "docsPath": "/channels/dingtalk",
+            "docsLabel": "dingtalk",
+            "blurb": "企业级即时通讯平台钉钉，支持Stream模式接入。",
+            "order": 20
+        },
+        "install": {
+            "npmSpec": "@xuanmiss/dingtalk",
+            "localPath": "extensions/dingtalk",
+            "defaultChoice": "npm"
+        }
+    }
+}

package/src/channel.ts

@@ -0,0 +1,386 @@
+import type { ChannelPlugin, ChannelMessageActionAdapter } from "openclaw/plugin-sdk";
+import {
+    buildChannelConfigSchema,
+    formatPairingApproveHint,
+    DmPolicySchema,
+    GroupPolicySchema,
+} from "openclaw/plugin-sdk";
+import { z } from "zod";
+import {
+    resolveDingtalkAccount,
+    listDingtalkAccountIds,
+    resolveDefaultDingtalkAccountId,
+    DEFAULT_ACCOUNT_ID,
+    type ResolvedDingtalkAccount,
+} from "./config.js";
+import { sendMessageDingtalk } from "./send.js";
+import { monitorDingtalkProvider, probeDingtalk, createOpenClawMessageHandler } from "./monitor.js";
+
+// ============================================================================
+// 配置Schema (使用 Zod)
+// ============================================================================
+
+const DingtalkGroupSchema = z
+    .object({
+        requireMention: z.boolean().optional(),
+        allowFrom: z.array(z.string()).optional(),
+    })
+    .strict();
+
+const DingtalkAccountSchema = z
+    .object({
+        enabled: z.boolean().optional(),
+        name: z.string().optional(),
+        clientId: z.string().optional(),
+        clientSecret: z.string().optional(),
+        robotCode: z.string().optional(),
+        dmPolicy: DmPolicySchema.optional(),
+        allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    })
+    .strict();
+
+export const DingtalkConfigSchema = z
+    .object({
+        enabled: z.boolean().optional(),
+        name: z.string().optional(),
+        clientId: z.string().optional(),
+        clientSecret: z.string().optional(),
+        robotCode: z.string().optional(),
+        dmPolicy: DmPolicySchema.optional().default("pairing"),
+        allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+        groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+        groups: z.record(z.string(), DingtalkGroupSchema.optional()).optional(),
+        historyLimit: z.number().int().min(0).optional(),
+        textChunkLimit: z.number().int().positive().optional(),
+        blockStreaming: z.boolean().optional(),
+        accounts: z.record(z.string(), DingtalkAccountSchema.optional()).optional(),
+    })
+    .strict();
+
+
+// ============================================================================
+// 渠道元数据
+// ============================================================================
+
+const meta = {
+    id: "dingtalk" as const,
+    label: "DingTalk",
+    selectionLabel: "DingTalk (钉钉 Stream)",
+    detailLabel: "钉钉机器人",
+    docsPath: "/channels/dingtalk",
+    docsLabel: "dingtalk",
+    blurb: "企业级即时通讯平台，支持Stream模式接入。",
+    systemImage: "message.badge.filled.fill",
+    order: 20,
+    aliases: ["dd", "dingding", "ding"],
+};
+
+// ============================================================================
+// 消息动作适配器
+// ============================================================================
+
+const dingtalkMessageActions: ChannelMessageActionAdapter = {
+    listActions: () => ["send"],
+
+    extractToolSend: ({ args }) => {
+        const to = args.to || args.target || args.conversationId || args.userId;
+        return to ? { to: String(to) } : null;
+    },
+
+    handleAction: async (ctx) => {
+        if (ctx.action === "send") {
+            const message = String(ctx.params.message || ctx.params.text || "");
+            const to = String(ctx.params.to || ctx.params.conversationId || ctx.params.userId || "");
+
+            if (!to) {
+                return {
+                    content: [{ type: "text", text: "Error: target (to/conversationId/userId) required" }],
+                    details: { error: "missing_target" },
+                };
+            }
+
+            if (!message) {
+                return {
+                    content: [{ type: "text", text: "Error: message required" }],
+                    details: { error: "missing_message" },
+                };
+            }
+
+            const atUsersRaw = ctx.params.atUsers || ctx.params.atUserIds || ctx.params.mentions;
+            const atUsers = Array.isArray(atUsersRaw)
+                ? atUsersRaw.map(String)
+                : typeof atUsersRaw === "string"
+                    ? atUsersRaw.split(",").map(s => s.trim())
+                    : undefined;
+
+            const result = await sendMessageDingtalk(to, message, {
+                cfg: ctx.cfg,
+                accountId: ctx.accountId ?? undefined,
+                atUsers,
+            });
+
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                details: result,
+            };
+        }
+
+        return {
+            content: [{ type: "text", text: `Unsupported action: ${ctx.action}` }],
+            details: { error: "unsupported_action", action: ctx.action },
+        };
+    },
+};
+
+// ============================================================================
+// 主渠道插件定义
+// ============================================================================
+
+export const dingtalkPlugin: ChannelPlugin<ResolvedDingtalkAccount> = {
+    id: "dingtalk",
+    meta,
+
+    // ---------------------------------------------------------------------------
+    // 能力声明
+    // ---------------------------------------------------------------------------
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        reactions: false, // 钉钉暂不支持reaction
+        threads: false, // 钉钉暂不支持线程
+        media: true, // 支持媒体消息
+        nativeCommands: false,
+        blockStreaming: true,
+    },
+
+    // ---------------------------------------------------------------------------
+    // 配置热重载
+    // ---------------------------------------------------------------------------
+    reload: { configPrefixes: ["channels.dingtalk"] },
+    configSchema: buildChannelConfigSchema(DingtalkConfigSchema),
+
+    // ---------------------------------------------------------------------------
+    // 配置适配器
+    // ---------------------------------------------------------------------------
+    config: {
+        listAccountIds: (cfg) => listDingtalkAccountIds(cfg),
+        resolveAccount: (cfg, accountId) => resolveDingtalkAccount({ cfg, accountId }),
+        defaultAccountId: (cfg) => resolveDefaultDingtalkAccountId(cfg),
+
+        isConfigured: (account) => Boolean(account.clientId?.trim() && account.clientSecret?.trim()),
+
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: Boolean(account.clientId?.trim() && account.clientSecret?.trim()),
+            tokenSource: account.tokenSource,
+        }),
+
+        resolveAllowFrom: ({ cfg, accountId }) =>
+            (resolveDingtalkAccount({ cfg, accountId }).config.allowFrom ?? []).map(String),
+
+        formatAllowFrom: ({ allowFrom }) =>
+            allowFrom
+                .map((entry) => String(entry).trim())
+                .filter(Boolean)
+                .map((entry) => entry.replace(/^dingtalk:/i, ""))
+                .map((entry) => entry.toLowerCase()),
+    },
+
+    // ---------------------------------------------------------------------------
+    // 安全适配器
+    // ---------------------------------------------------------------------------
+    security: {
+        resolveDmPolicy: ({ cfg, accountId, account }) => {
+            const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+            const dingtalkConfig = (cfg.channels as Record<string, unknown> | undefined)?.dingtalk as
+                | Record<string, unknown>
+                | undefined;
+            const useAccountPath = Boolean(
+                (dingtalkConfig?.accounts as Record<string, unknown> | undefined)?.[resolvedAccountId],
+            );
+            const basePath = useAccountPath
+                ? `channels.dingtalk.accounts.${resolvedAccountId}.`
+                : "channels.dingtalk.";
+
+            return {
+                policy: account.config.dmPolicy ?? "pairing",
+                allowFrom: account.config.allowFrom ?? [],
+                policyPath: `${basePath}dmPolicy`,
+                allowFromPath: basePath,
+                approveHint: formatPairingApproveHint("dingtalk"),
+                normalizeEntry: (raw: string) => raw.replace(/^dingtalk:/i, ""),
+            };
+        },
+
+        collectWarnings: ({ account, cfg }) => {
+            const warnings: string[] = [];
+            const defaultGroupPolicy = (
+                cfg.channels as { defaults?: { groupPolicy?: string } } | undefined
+            )?.defaults?.groupPolicy;
+            const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
+
+            if (groupPolicy === "open") {
+                warnings.push(
+                    `- DingTalk groups: groupPolicy="open" allows any group member to trigger the bot (mention-gated). ` +
+                    `Set channels.dingtalk.groupPolicy="allowlist" and configure channels.dingtalk.groups.`,
+                );
+            }
+
+            return warnings;
+        },
+    },
+
+    // ---------------------------------------------------------------------------
+    // 消息适配器
+    // ---------------------------------------------------------------------------
+    messaging: {
+        normalizeTarget: (raw) => {
+            const trimmed = raw.trim();
+            if (!trimmed) return undefined;
+            // 支持 dingtalk:userId 格式
+            return trimmed.replace(/^dingtalk:/i, "");
+        },
+        targetResolver: {
+            looksLikeId: (raw) => {
+                const trimmed = raw.trim();
+                // 钉钉用户ID格式检测
+                return /^[a-zA-Z0-9]{10,}$/.test(trimmed) || trimmed.startsWith("cid");
+            },
+            hint: "<userId|conversationId>",
+        },
+    },
+
+    // ---------------------------------------------------------------------------
+    // 配对适配器
+    // ---------------------------------------------------------------------------
+    pairing: {
+        idLabel: "dingtalkUserId",
+        normalizeAllowEntry: (entry) => entry.replace(/^dingtalk:/i, ""),
+        notifyApproval: async ({ id }) => {
+            await sendMessageDingtalk(id, "✅ 你已被授权与 OpenClaw 对话！", {});
+        },
+    },
+
+    // ---------------------------------------------------------------------------
+    // 消息动作
+    // ---------------------------------------------------------------------------
+    actions: dingtalkMessageActions,
+
+    // ---------------------------------------------------------------------------
+    // 出站消息适配器
+    // ---------------------------------------------------------------------------
+    outbound: {
+        deliveryMode: "direct",
+        chunker: null,
+        textChunkLimit: 4000,
+
+        sendText: async ({ cfg, to, text, accountId }) => {
+            const result = await sendMessageDingtalk(to, text, {
+                cfg,
+                accountId: accountId ?? undefined,
+            });
+            return { channel: "dingtalk", ...result };
+        },
+
+        sendMedia: async ({ cfg, to, text, mediaUrl, accountId }) => {
+            // 钉钉的媒体消息需要特殊处理
+            // 这里简化为发送文本+链接
+            const messageWithMedia = mediaUrl ? `${text}\n\n📎 ${mediaUrl}` : text;
+            const result = await sendMessageDingtalk(to, messageWithMedia, {
+                cfg,
+                accountId: accountId ?? undefined,
+            });
+            return { channel: "dingtalk", ...result };
+        },
+    },
+
+    // ---------------------------------------------------------------------------
+    // 状态适配器
+    // ---------------------------------------------------------------------------
+    status: {
+        defaultRuntime: {
+            accountId: DEFAULT_ACCOUNT_ID,
+            running: false,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+        },
+
+        probeAccount: async ({ account, timeoutMs }) =>
+            probeDingtalk(account.clientId, account.clientSecret, timeoutMs),
+
+        buildAccountSnapshot: ({ account, runtime, probe }) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: Boolean(account.clientId?.trim() && account.clientSecret?.trim()),
+            tokenSource: account.tokenSource,
+            running: runtime?.running ?? false,
+            lastStartAt: runtime?.lastStartAt ?? null,
+            lastStopAt: runtime?.lastStopAt ?? null,
+            lastError: runtime?.lastError ?? null,
+            probe,
+        }),
+
+        buildChannelSummary: ({ snapshot }) => ({
+            configured: snapshot.configured ?? false,
+            tokenSource: snapshot.tokenSource ?? "none",
+            running: snapshot.running ?? false,
+            lastStartAt: snapshot.lastStartAt ?? null,
+            lastStopAt: snapshot.lastStopAt ?? null,
+            lastError: snapshot.lastError ?? null,
+            probe: snapshot.probe,
+        }),
+    },
+
+    // ---------------------------------------------------------------------------
+    // Gateway适配器
+    // ---------------------------------------------------------------------------
+    gateway: {
+        startAccount: async (ctx) => {
+            const account = ctx.account;
+
+            // 先探测验证凭证
+            let probeLabel = "";
+            try {
+                const probe = await probeDingtalk(account.clientId, account.clientSecret, 3000);
+                if (probe.ok) {
+                    probeLabel = ` (${account.robotCode || account.clientId})`;
+                } else {
+                    ctx.log?.warn?.(`[${account.accountId}] Probe failed: ${probe.error}`);
+                }
+            } catch (err) {
+                ctx.log?.debug?.(`[${account.accountId}] Probe error: ${String(err)}`);
+            }
+
+            ctx.log?.info(`[${account.accountId}] Starting DingTalk Stream provider${probeLabel}`);
+
+            const onMessage = createOpenClawMessageHandler({
+                accountId: account.accountId,
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+            });
+
+            return monitorDingtalkProvider({
+                clientId: account.clientId,
+                clientSecret: account.clientSecret,
+                robotCode: account.robotCode,
+                accountId: account.accountId,
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+                abortSignal: ctx.abortSignal,
+                onMessage,
+            });
+        },
+    },
+
+    // ---------------------------------------------------------------------------
+    // 目录适配器
+    // ---------------------------------------------------------------------------
+    directory: {
+        self: async () => null,
+        listPeers: async () => [],
+        listGroups: async () => [],
+    },
+};

package/src/client-registry.ts

@@ -0,0 +1,27 @@
+import { DWClient } from "dingtalk-stream";
+
+/**
+ * 存放活跃的钉钉客户端实例
+ */
+const activeClients = new Map<string, DWClient>();
+
+/**
+ * 注册客户端
+ */
+export function registerDingtalkClient(accountId: string, client: DWClient) {
+    activeClients.set(accountId, client);
+}
+
+/**
+ * 获取客户端
+ */
+export function getDingtalkClient(accountId: string): DWClient | undefined {
+    return activeClients.get(accountId);
+}
+
+/**
+ * 移除客户端
+ */
+export function unregisterDingtalkClient(accountId: string) {
+    activeClients.delete(accountId);
+}