@largezhou/ddingtalk 1.3.2 → 1.4.0-beta.0

package/README.md

@@ -1,18 +1,22 @@
 # @largezhou/ddingtalk
 
+[English](README.en.md)
+
 OpenClaw 钉钉（DingTalk）渠道插件，使用 Stream 模式接入企业机器人。
 
 ## 功能特点
 
 - ✅ **Stream 模式**：无需公网 IP 和域名，开箱即用
+- ✅ **多账号支持**：可同时接入多个钉钉机器人，分别配置凭证和权限
+- ✅ **多 Agent 路由**：支持将不同账号、群聊、私聊绑定到不同的 Agent
 - ✅ **私聊/群聊**：支持私聊，群聊（仅@机器人）
 - ✅ **文本消息收发**：接收和发送文本消息
-- ✅ **Markdown回复**：机器人回复 Markdown 格式
+- ✅ **Markdown 回复**：机器人回复 Markdown 格式
 - ✅ **图片消息收发**：接收用户发送的图片，支持发送本地/远程图片
 - ✅ **语音、视频、文件、图文混排**：接收用户发送语音、视频、文件、图文混排消息
-- ✅ **回复文件**：支持回复文件，音频、视频等统一按文件发送（按语音、视频发送，需要获取时长、视频封面，以后再支持）
+- ✅ **回复文件**：支持回复文件，音频、视频等统一按文件发送
 - ✅ **主动推送消息**：支持主动推送消息，可以配置提醒或定时任务
-- ✅ **支持OpenClaw命令**：支持 /new、/compact 等 OpenClaw 官方命令
+- ✅ **支持 OpenClaw 命令**：支持 /new、/compact 等 OpenClaw 官方命令
 
 ## 安装
 
@@ -20,53 +24,126 @@ OpenClaw 钉钉（DingTalk）渠道插件，使用 Stream 模式接入企业机
 openclaw plugins install @largezhou/ddingtalk
 ```
 
-## 前置准备
+---
+
+## 快速开始
+
+添加钉钉渠道有两种方式：
+
+### 方式一：通过安装向导添加（推荐）
+
+如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加钉钉：
+
+```bash
+openclaw onboard
+```
+
+向导会引导您完成：
+
+1. 创建钉钉应用机器人并获取凭证
+2. 配置应用凭证
+3. 启动网关
+
+**完成配置后**，您可以使用以下命令检查网关状态：
+
+- `openclaw gateway status` - 查看网关运行状态
+- `openclaw logs --follow` - 查看实时日志
+
+### 方式二：通过命令行添加
+
+如果您已经完成了初始安装，可以用以下命令添加钉钉渠道：
+
+```bash
+openclaw channels add
+```
+
+然后根据交互式提示选择 DingTalk，输入 AppKey (Client ID) 和 AppSecret (Client Secret) 即可。
+
+**完成配置后**，您可以使用以下命令管理网关：
+
+- `openclaw gateway status` - 查看网关运行状态
+- `openclaw gateway restart` - 重启网关以应用新配置
+- `openclaw logs --follow` - 查看实时日志
+
+---
+
+## 第一步：创建钉钉应用
+
+### 1. 打开钉钉开发者平台
+
+访问 [钉钉开发者平台](https://open-dev.dingtalk.com/fe/app)，使用钉钉账号登录，选择组织进入。
+
+### 2. 创建应用
 
-### 1. 创建钉钉企业内部应用
+1. 点击右上角 **创建应用**
+2. 填写应用名称和描述，上传图片（可选）
 
-1. 登录 [钉钉开发者后台](https://open-dev.dingtalk.com/fe/app)
-2. 创建应用
-3. 记录 **AppKey** (ClientID) 和 **AppSecret** (ClientSecret)
+![创建应用](docs/images/dingtalk/dingtalk-create-app.png)
 
-### 2. 开通机器人能力
+### 3. 获取应用凭证
 
-1. 在应用详情页，点击 **应用能力** -> **添加应用能力**
-2. 选择 **机器人**
-3. 填写机器人基本信息
-4. **重要**: 消息接收模式选择 **Stream 模式**
-5. 发布应用
+在应用的 **凭证与基础信息** 页面，复制：
 
-### 3. 配置应用权限
+- **Client ID**（格式如 `dingxxxx`）
+- **Client Secret**
+
+❗ **重要**：请妥善保管 Client Secret，不要分享给他人。
+
+![获取应用凭证](docs/images/dingtalk/dingtalk-credentials.png)
+
+### 4. 添加应用机器人
+
+1. 在应用的 **添加应用能力** 页面，选择 **机器人**，点击添加
+
+![添加机器人](docs/images/dingtalk/dingtalk-create-robot.png)
+
+2. 输入机器人相关信息，**消息接收模式** 选择 **Stream 模式**，然后保存
+
+![配置机器人](docs/images/dingtalk/dingtalk-robot-config.png)
+
+![配置机器人消息接收模式](docs/images/dingtalk/dingtalk-robot-config-stream.png)
+
+### 5. 配置应用权限
 
 在应用的权限管理中，确保开通以下权限：
 
 - 企业内机器人发送消息权限
 - 根据 downloadCode 获取机器人接收消息的下载链接（用于接收图片）
 
-## 配置
+### 6. 发布机器人
+
+创建机器人版本，填入版本号、描述、应用可用范围，点击保存，点击确认发布。
+
+![创建机器人版本](docs/images/dingtalk/dingtalk-create-version.png)
+
+![编辑版本](docs/images/dingtalk/dingtalk-edit-version.png)
+
+---
 
-### 方式一：交互式配置（推荐）
+## 第二步：配置 OpenClaw
+
+### 通过向导配置（推荐）
+
+运行以下命令，根据提示选择 DingTalk，粘贴 AppKey (Client ID) 和 AppSecret (Client Secret)：
 
 ```bash
 openclaw channels add
 ```
 
-选择 DingTalk，按提示输入 AppKey 和 AppSecret 即可。
+### 通过配置文件配置
 
-### 方式二：手动配置
-
-在 OpenClaw 配置文件 `~/.openclaw/openclaw.json` 中添加：
+编辑 `~/.openclaw/openclaw.json`：
 
 ```json
 {
-   "channels": {
-     "ddingtalk": {
-        "enabled": true,
-        "clientId": "your_app_key",
-        "clientSecret": "your_app_secret",
-        "allowFrom": ["*"]
-     }
-   }
+  "channels": {
+    "ddingtalk": {
+      "enabled": true,
+      "clientId": "your_app_key",
+      "clientSecret": "your_app_secret",
+      "allowFrom": ["*"]
+    }
+  }
 }
 ```
 
@@ -84,31 +161,197 @@ openclaw channels add
 }
 ```
 
-## Demo
+---
+
+## 多账号配置
+
+支持同时接入多个钉钉机器人，每个机器人对应一个独立的账号（account）。适用场景：
+
+- 不同部门使用不同的机器人
+- 同一个 OpenClaw 实例服务多个钉钉组织
+- 不同机器人配置不同的权限策略
+
+### 添加新账号
 
-项目包含独立的 demo 示例，可以脱离 OpenClaw 框架单独测试钉钉机器人
+通过向导添加新账号，会交互式地提示输入账号 ID 和凭证：
 
 ```bash
-# 配置环境变量
-cp .env.example .env
-# 编辑 .env 填入 CLIENT_ID 和 CLIENT_SECRET
+openclaw channels add
+```
+
+### 配置文件示例
 
-# 运行 demo
-npm run demo
+编辑 `~/.openclaw/openclaw.json`：
+
+```json
+{
+  "channels": {
+    "ddingtalk": {
+      "enabled": true,
+      "accounts": {
+        "bot-hr": {
+          "name": "HR助手",
+          "clientId": "dingxxxxxxxx",
+          "clientSecret": "secret_1"
+        },
+        "bot-tech": {
+          "name": "技术支持",
+          "clientId": "dingyyyyyyyy",
+          "clientSecret": "secret_2"
+        }
+      },
+      "defaultAccount": "bot-hr"
+    }
+  }
+}
+```
+
+### 群组独立配置
+
+可以为特定群聊设置独立的权限和行为：
+
+```json
+{
+  "accounts": {
+    "bot-hr": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxx",
+      "clientSecret": "secret_1"
+    }
+  }
+}
+```
+
+### 单账号兼容
+
+如果只有一个机器人，无需使用 `accounts`，直接在顶层配置即可（兼容旧版格式）：
+
+```json
+{
+  "channels": {
+    "ddingtalk": {
+      "enabled": true,
+      "clientId": "your_app_key",
+      "clientSecret": "your_app_secret"
+    }
+  }
+}
+```
+
+---
+
+## 多 Agent 路由
+
+通过 OpenClaw 的路由绑定（bindings）机制，可以将不同的账号、群聊、私聊分配给不同的 Agent 处理。
+
+> 更多关于多 Agent 的概念和用法，请参阅 [OpenClaw 官方文档 - 多 Agent](https://docs.openclaw.ai/zh-CN/concepts/multi-agent)。
+
+### 按账号绑定 Agent
+
+使用命令行将不同钉钉账号绑定到不同的 Agent：
+
+```bash
+# 将 bot-hr 账号绑定到 hr-agent
+openclaw agents bind --agent hr-agent --bind ddingtalk:bot-hr
+
+# 将 bot-tech 账号绑定到 tech-agent
+openclaw agents bind --agent tech-agent --bind ddingtalk:bot-tech
+
+# 将整个钉钉渠道（所有账号）绑定到默认 agent
+openclaw agents bind --agent default-agent --bind ddingtalk
 ```
 
+查看当前绑定：
+
+```bash
+openclaw agents bindings
+```
+
+解除绑定：
+
+```bash
+openclaw agents unbind --agent hr-agent --bind ddingtalk:bot-hr
+```
+
+### 按群聊/私聊绑定 Agent
+
+CLI 命令目前仅支持 `channel[:accountId]` 级别的绑定。如需将特定群聊或私聊绑定到不同 Agent，需要手动编辑 `~/.openclaw/openclaw.json` 的 `bindings` 配置：
+
+```json
+{
+  "agents": {
+    "list": [
+      { "id": "hr-agent", "name": "HR助手" },
+      { "id": "tech-agent", "name": "技术支持" },
+      { "id": "general-agent", "name": "通用助手" }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "tech-agent",
+      "comment": "技术交流群走技术支持 Agent",
+      "match": {
+        "channel": "ddingtalk",
+        "peer": {
+          "kind": "group",
+          "id": "cidTechGroup001"
+        }
+      }
+    },
+    {
+      "agentId": "hr-agent",
+      "comment": "张三的私聊走HR助手",
+      "match": {
+        "channel": "ddingtalk",
+        "peer": {
+          "kind": "direct",
+          "id": "user_zhangsan_staffId"
+        }
+      }
+    },
+    {
+      "agentId": "general-agent",
+      "comment": "bot-hr 账号的其他消息走通用助手",
+      "match": {
+        "channel": "ddingtalk",
+        "accountId": "bot-hr"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 第三步：启动并测试
+
+### 1. 启动网关
+
+```bash
+openclaw gateway --verbose
+```
+
+### 2. 发送测试消息
+
+在钉钉中找到您创建的机器人，即可正常对话。
+
+![钉钉对话](docs/images/dingtalk/dingtalk-chat.jpg)
+
+---
+
 ## 开发
 
 ```bash
 # 安装依赖
-npm install
+pnpm install
 
 # 打包
-npm pack
+pnpm pack
 ```
 
 ## 参考文档
 
+- [OpenClaw 多 Agent 文档](https://docs.openclaw.ai/zh-CN/concepts/multi-agent)
 - [钉钉开放平台 - Stream 模式说明](https://opensource.dingtalk.com/developerpedia/docs/learn/stream/overview)
 - [钉钉开放平台 - 机器人接收消息](https://open.dingtalk.com/document/orgapp/robot-receive-message)
 - [钉钉开放平台 - 机器人发送消息](https://open.dingtalk.com/document/orgapp/robot-send-message)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@largezhou/ddingtalk",
-  "version": "1.3.2",
+  "version": "1.4.0-beta.0",
   "description": "OpenClaw DingTalk (钉钉) channel plugin",
   "main": "index.ts",
   "type": "module",
@@ -18,9 +18,7 @@
     "openclaw.plugin.json",
     "README.md"
   ],
-  "scripts": {
-    "demo": "npx tsx demo/demo.ts"
-  },
+  "scripts": {},
   "keywords": [
     "dingtalk",
     "openclaw",
@@ -31,16 +29,15 @@
   "author": "largezhou",
   "license": "MIT",
   "dependencies": {
-    "@alicloud/dingtalk": "^2.2.38",
-    "@alicloud/openapi-client": "^0.4.15",
-    "@alicloud/tea-util": "^1.4.11",
     "dingtalk-stream": "^2.1.4"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "dotenv": "^17.3.1",
     "openclaw": "*",
     "tsx": "^4.6.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "openclaw": "*",

package/src/accounts.ts

@@ -1,82 +1,167 @@
-import { DEFAULT_ACCOUNT_ID, type OpenClawConfig } from "openclaw/plugin-sdk";
-import type { DingTalkConfig, ResolvedDingTalkAccount } from "./types.js";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import type {
+  DingTalkConfig,
+  DingTalkAccountConfig,
+  ResolvedDingTalkAccount,
+} from "./types.js";
 import { PLUGIN_ID } from "./constants.js";
 
+// ======================= Account List Helpers =======================
+
+export { normalizeAccountId };
+
+/**
+ * 列出所有钉钉账号 ID
+ *
+ * 方案 3 策略：顶层配置和 accounts 字典共存，不做迁移。
+ * - 顶层有 clientId → 视为 "default" 账号
+ * - accounts 字典中的 key → 各自独立的账号
+ * - 两者合并去重
+ */
+export function listDingTalkAccountIds(cfg: OpenClawConfig): string[] {
+  const dingtalkConfig = cfg.channels?.[PLUGIN_ID] as DingTalkConfig | undefined;
+  if (!dingtalkConfig) return [DEFAULT_ACCOUNT_ID];
+
+  const accountKeys = Object.keys(dingtalkConfig.accounts ?? {}).filter(Boolean);
+
+  // 顶层有凭据时，确保 "default" 在列表中
+  const hasTopLevel = Boolean(dingtalkConfig.clientId?.trim());
+  if (hasTopLevel && !accountKeys.includes(DEFAULT_ACCOUNT_ID)) {
+    accountKeys.push(DEFAULT_ACCOUNT_ID);
+  }
+
+  if (accountKeys.length === 0) {
+    return [DEFAULT_ACCOUNT_ID];
+  }
+
+  return accountKeys.slice().sort((a, b) => a.localeCompare(b));
+}
+
 /**
- * 规范化账户 ID（始终返回默认账户 ID）
+ * 解析默认账号 ID
+ *
+ * 优先使用 defaultAccount 配置，否则返回 "default"
  */
-export function normalizeAccountId(_accountId?: string | null): string {
-  return DEFAULT_ACCOUNT_ID;
+export function resolveDefaultDingTalkAccountId(cfg: OpenClawConfig): string {
+  const dingtalkConfig = cfg.channels?.[PLUGIN_ID] as DingTalkConfig | undefined;
+  return dingtalkConfig?.defaultAccount?.trim() || DEFAULT_ACCOUNT_ID;
 }
 
+// ======================= Account Config Resolution =======================
+
 /**
- * 列出所有钉钉账户 ID（单账户，只返回默认账户）
+ * 获取指定 accountId 的账户级配置（从 accounts 字典中查找）
  */
-export function listDingTalkAccountIds(cfg: OpenClawConfig): string[] {
+function resolveAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): DingTalkAccountConfig | undefined {
   const dingtalkConfig = cfg.channels?.[PLUGIN_ID] as DingTalkConfig | undefined;
-  if (!dingtalkConfig?.clientId) {
-    return [];
+  const accounts = dingtalkConfig?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return undefined;
   }
-  return [DEFAULT_ACCOUNT_ID];
+  const normalized = normalizeAccountId(accountId);
+  // 精确匹配或大小写不敏感匹配
+  const key = Object.keys(accounts).find(
+    (k) => normalizeAccountId(k) === normalized,
+  );
+  return key ? accounts[key] : undefined;
 }
 
 /**
- * 解析默认钉钉账户 ID
+ * 合并顶层配置（作为默认值）和账户级配置
+ *
+ * 配置优先级：账户级 > 顶层
+ * 顶层的 accounts / defaultAccount 字段会被排除
  */
-export function resolveDefaultDingTalkAccountId(_cfg: OpenClawConfig): string {
-  return DEFAULT_ACCOUNT_ID;
+function mergeDingTalkAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): DingTalkAccountConfig {
+  const dingtalkConfig = cfg.channels?.[PLUGIN_ID] as DingTalkConfig | undefined;
+  if (!dingtalkConfig) {
+    return {};
+  }
+
+  // 顶层字段作为 base（排除 accounts 和 defaultAccount）
+  const {
+    accounts: _accounts,
+    defaultAccount: _defaultAccount,
+    groups: channelGroups,
+    ...base
+  } = dingtalkConfig;
+
+  // 获取账户级配置
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+
+  // 多账户模式下，groups 不从顶层继承（每个账户应有自己的 groups）
+  const configuredAccountIds = Object.keys(dingtalkConfig.accounts ?? {});
+  const isMultiAccount = configuredAccountIds.length > 1;
+  const groups = account.groups ?? (isMultiAccount ? undefined : channelGroups);
+
+  return { ...base, ...account, groups };
 }
 
+// ======================= Account Resolution =======================
+
 /**
- * 解析钉钉账户配置（单账户模式）
+ * 解析钉钉账户配置
+ *
+ * 支持两种模式：
+ * 1. 单账户（旧版兼容）：顶层 clientId/clientSecret → accountId = "default"
+ * 2. 多账户：accounts 字典 → 顶层字段作为默认值，账户级字段覆盖
  */
 export function resolveDingTalkAccount(params: {
   cfg: OpenClawConfig;
-  accountId?: string;
+  accountId?: string | null;
 }): ResolvedDingTalkAccount {
-  const { cfg } = params;
-  const dingtalkConfig = cfg.channels?.[PLUGIN_ID] as DingTalkConfig | undefined;
+  const accountId = normalizeAccountId(params.accountId);
+  const dingtalkConfig = params.cfg.channels?.[PLUGIN_ID] as DingTalkConfig | undefined;
+  const baseEnabled = dingtalkConfig?.enabled !== false;
 
-  // 默认返回值
-  const defaultResult: ResolvedDingTalkAccount = {
-    accountId: DEFAULT_ACCOUNT_ID,
-    enabled: false,
-    clientId: "",
-    clientSecret: "",
-    tokenSource: "none",
-    allowFrom: ["*"],
-    groupPolicy: "open",
-    groupAllowFrom: [],
-    groups: {},
-  };
-
-  if (!dingtalkConfig) {
-    return defaultResult;
-  }
+  // 合并顶层 + 账户级配置
+  const merged = mergeDingTalkAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
 
   let clientId = "";
   let clientSecret = "";
   let tokenSource: ResolvedDingTalkAccount["tokenSource"] = "none";
 
-  if (dingtalkConfig.clientId?.trim()) {
-    clientId = dingtalkConfig.clientId.trim();
+  if (merged.clientId?.trim()) {
+    clientId = merged.clientId.trim();
     tokenSource = "config";
   }
-
-  if (dingtalkConfig.clientSecret?.trim()) {
-    clientSecret = dingtalkConfig.clientSecret.trim();
+  if (merged.clientSecret?.trim()) {
+    clientSecret = merged.clientSecret.trim();
   }
 
   return {
-    accountId: DEFAULT_ACCOUNT_ID,
-    name: dingtalkConfig.name,
-    enabled: dingtalkConfig.enabled ?? true,
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
     clientId,
     clientSecret,
     tokenSource,
-    allowFrom: dingtalkConfig.allowFrom ?? ["*"],
-    groupPolicy: dingtalkConfig.groupPolicy ?? "open",
-    groupAllowFrom: dingtalkConfig.groupAllowFrom ?? [],
-    groups: dingtalkConfig.groups ?? {},
+    allowFrom: merged.allowFrom ?? ["*"],
+    groupPolicy: merged.groupPolicy ?? "open",
+    groupAllowFrom: merged.groupAllowFrom ?? [],
+    groups: merged.groups ?? {},
   };
 }
+
+/**
+ * 列出所有已启用的钉钉账户
+ */
+export function listEnabledDingTalkAccounts(
+  cfg: OpenClawConfig,
+): ResolvedDingTalkAccount[] {
+  return listDingTalkAccountIds(cfg)
+    .map((accountId) => resolveDingTalkAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}