@dingxiang-me/openclaw-wechat 1.4.1 → 1.7.2

package/src/wecom/command-handlers.js

@@ -9,6 +9,12 @@ export function createWecomCommandHandlers({
   resolveWecomVoiceTranscriptionConfig,
   resolveWecomCommandPolicy,
   resolveWecomAllowFromPolicy,
+  resolveWecomDmPolicy,
+  resolveWecomEventPolicy = () => ({
+    enabled: true,
+    enterAgentWelcomeEnabled: false,
+    enterAgentWelcomeText: "",
+  }),
   resolveWecomGroupChatPolicy,
   resolveWecomTextDebouncePolicy,
   resolveWecomReplyStreamingPolicy,
@@ -17,6 +23,7 @@ export function createWecomCommandHandlers({
   resolveWecomWebhookBotDeliveryPolicy,
   resolveWecomDynamicAgentPolicy,
   resolveWecomBotConfig,
+  getWecomObservabilityMetrics = () => ({}),
   pluginVersion,
 } = {}) {
   if (typeof sendWecomText !== "function") throw new Error("createWecomCommandHandlers: sendWecomText is required");
@@ -37,6 +44,12 @@ export function createWecomCommandHandlers({
   if (typeof resolveWecomAllowFromPolicy !== "function") {
     throw new Error("createWecomCommandHandlers: resolveWecomAllowFromPolicy is required");
   }
+  if (typeof resolveWecomDmPolicy !== "function") {
+    throw new Error("createWecomCommandHandlers: resolveWecomDmPolicy is required");
+  }
+  if (typeof resolveWecomEventPolicy !== "function") {
+    throw new Error("createWecomCommandHandlers: resolveWecomEventPolicy is required");
+  }
   if (typeof resolveWecomGroupChatPolicy !== "function") {
     throw new Error("createWecomCommandHandlers: resolveWecomGroupChatPolicy is required");
   }
@@ -67,6 +80,7 @@ export function createWecomCommandHandlers({
 
 可用命令：
 /help - 显示此帮助信息
+/new - 新建会话（兼容命令，等价于 /reset）
 /clear - 重置会话（等价于 /reset）
 /status - 查看系统状态
 
@@ -84,6 +98,8 @@ export function createWecomCommandHandlers({
     const voiceConfig = resolveWecomVoiceTranscriptionConfig(api);
     const commandPolicy = resolveWecomCommandPolicy(api);
     const allowFromPolicy = resolveWecomAllowFromPolicy(api, config?.accountId, config);
+    const dmPolicy = resolveWecomDmPolicy(api, config?.accountId, config);
+    const eventPolicy = resolveWecomEventPolicy(api, config?.accountId, config);
     const groupPolicy = resolveWecomGroupChatPolicy(api);
     const debouncePolicy = resolveWecomTextDebouncePolicy(api);
     const streamingPolicy = resolveWecomReplyStreamingPolicy(api);
@@ -91,6 +107,7 @@ export function createWecomCommandHandlers({
     const streamManagerPolicy = resolveWecomStreamManagerPolicy(api);
     const webhookBotPolicy = resolveWecomWebhookBotDeliveryPolicy(api);
     const dynamicAgentPolicy = resolveWecomDynamicAgentPolicy(api);
+    const observabilityMetrics = getWecomObservabilityMetrics();
 
     const statusText = buildAgentStatusText({
       fromUser,
@@ -101,6 +118,8 @@ export function createWecomCommandHandlers({
       voiceConfig,
       commandPolicy,
       allowFromPolicy,
+      dmPolicy,
+      eventPolicy,
       groupPolicy,
       debouncePolicy,
       streamingPolicy,
@@ -108,6 +127,7 @@ export function createWecomCommandHandlers({
       streamManagerPolicy,
       webhookBotPolicy,
       dynamicAgentPolicy,
+      observabilityMetrics,
     });
 
     await sendWecomText({
@@ -126,12 +146,15 @@ export function createWecomCommandHandlers({
     const allWebhookTargetAliases = listAllWebhookTargetAliases(api);
     const commandPolicy = resolveWecomCommandPolicy(api);
     const allowFromPolicy = resolveWecomAllowFromPolicy(api, "default", {});
+    const dmPolicy = resolveWecomDmPolicy(api, "default", {});
+    const eventPolicy = resolveWecomEventPolicy(api, "default", {});
     const groupPolicy = resolveWecomGroupChatPolicy(api);
     const botConfig = resolveWecomBotConfig(api);
     const deliveryFallbackPolicy = resolveWecomDeliveryFallbackPolicy(api);
     const streamManagerPolicy = resolveWecomStreamManagerPolicy(api);
     const webhookBotPolicy = resolveWecomWebhookBotDeliveryPolicy(api);
     const dynamicAgentPolicy = resolveWecomDynamicAgentPolicy(api);
+    const observabilityMetrics = getWecomObservabilityMetrics();
     return buildBotStatusText({
       fromUser,
       pluginVersion,
@@ -139,11 +162,14 @@ export function createWecomCommandHandlers({
       allWebhookTargetAliases,
       commandPolicy,
       allowFromPolicy,
+      dmPolicy,
+      eventPolicy,
       groupPolicy,
       deliveryFallbackPolicy,
       streamManagerPolicy,
       webhookBotPolicy,
       dynamicAgentPolicy,
+      observabilityMetrics,
     });
   }
 

package/src/wecom/command-status-text.js

@@ -8,6 +8,52 @@ function buildWebhookTargetStatusLine({ aliases, scope = "当前账户", maxPrev
   return `✅ 命名 Webhook 目标（${scope}）：${preview}${suffix}`;
 }
 
+function buildDmPolicyStatusLine(dmPolicy = {}) {
+  const mode = String(dmPolicy?.mode ?? "open").trim().toLowerCase() || "open";
+  if (mode === "deny") {
+    return "⚠️ 私聊策略：已关闭（deny）";
+  }
+  if (mode === "allowlist") {
+    const count = Array.isArray(dmPolicy?.allowFrom) ? dmPolicy.allowFrom.length : 0;
+    return `✅ 私聊策略：白名单（${count} 个用户）`;
+  }
+  return "ℹ️ 私聊策略：开放（open）";
+}
+
+function buildEventPolicyStatusLine(eventPolicy = {}) {
+  if (eventPolicy?.enabled === false) {
+    return "⚠️ 事件策略：已关闭";
+  }
+  if (eventPolicy?.enterAgentWelcomeEnabled) {
+    return "✅ 事件策略：enter_agent 自动欢迎语已启用";
+  }
+  return "ℹ️ 事件策略：已启用（enter_agent 欢迎语未启用）";
+}
+
+function buildObservabilityStatusLines(observabilityMetrics = {}) {
+  const inboundTotal = Number(observabilityMetrics?.inboundTotal || 0);
+  const deliveryTotal = Number(observabilityMetrics?.deliveryTotal || 0);
+  const deliverySuccess = Number(observabilityMetrics?.deliverySuccess || 0);
+  const deliveryFailed = Number(observabilityMetrics?.deliveryFailed || 0);
+  const errorsTotal = Number(observabilityMetrics?.errorsTotal || 0);
+  const successRate = deliveryTotal > 0 ? `${Math.round((deliverySuccess / deliveryTotal) * 100)}%` : "n/a";
+  const status = `📈 观测统计：入站 ${inboundTotal} / 回包 ${deliveryTotal}（成功 ${deliverySuccess}，失败 ${deliveryFailed}，成功率 ${successRate}） / 错误 ${errorsTotal}`;
+
+  const recent = Array.isArray(observabilityMetrics?.recentFailures)
+    ? observabilityMetrics.recentFailures.slice(-1)[0]
+    : null;
+  if (!recent) {
+    return {
+      status,
+      recent: "ℹ️ 最近失败：无",
+    };
+  }
+  return {
+    status,
+    recent: `⚠️ 最近失败：${recent.scope || "unknown"} ${recent.reason || "unknown"}`.slice(0, 140),
+  };
+}
+
 export function buildAgentStatusText({
   fromUser,
   config,
@@ -17,6 +63,8 @@ export function buildAgentStatusText({
   voiceConfig,
   commandPolicy,
   allowFromPolicy,
+  dmPolicy,
+  eventPolicy,
   groupPolicy,
   debouncePolicy,
   streamingPolicy,
@@ -24,6 +72,7 @@ export function buildAgentStatusText({
   streamManagerPolicy,
   webhookBotPolicy,
   dynamicAgentPolicy,
+  observabilityMetrics,
 } = {}) {
   const proxyEnabled = Boolean(config?.outboundProxy);
   const voiceStatusLine = voiceConfig.enabled
@@ -36,6 +85,8 @@ export function buildAgentStatusText({
     allowFromPolicy.allowFrom.length === 0 || allowFromPolicy.allowFrom.includes("*")
       ? "ℹ️ 发送者授权：未限制（allowFrom 未配置）"
       : `✅ 发送者授权：已限制 ${allowFromPolicy.allowFrom.length} 个用户`;
+  const dmPolicyLine = buildDmPolicyStatusLine(dmPolicy);
+  const eventPolicyLine = buildEventPolicyStatusLine(eventPolicy);
   const groupPolicyLine = groupPolicy.enabled
     ? groupPolicy.triggerMode === "mention"
       ? "✅ 群聊触发：仅 @ 命中后处理"
@@ -65,6 +116,8 @@ export function buildAgentStatusText({
   const dynamicAgentPolicyLine = dynamicAgentPolicy.enabled
     ? `✅ 动态 Agent 路由已启用（mode=${dynamicAgentPolicy.mode}，用户映射 ${Object.keys(dynamicAgentPolicy.userMap || {}).length}，群映射 ${Object.keys(dynamicAgentPolicy.groupMap || {}).length}）`
     : "ℹ️ 动态 Agent 路由未启用";
+  const entryVisibilityLine = "✅ 微信插件入口联系人：Agent 模式可见（自建应用）";
+  const observabilityLines = buildObservabilityStatusLines(observabilityMetrics);
 
   return `📊 系统状态
 
@@ -84,6 +137,8 @@ export function buildAgentStatusText({
 ✅ 多账户支持
 ${commandPolicyLine}
 ${allowFromPolicyLine}
+${dmPolicyLine}
+${eventPolicyLine}
 ${groupPolicyLine}
 ${debouncePolicyLine}
 ${streamingPolicyLine}
@@ -92,8 +147,11 @@ ${streamManagerPolicyLine}
 ${webhookBotPolicyLine}
 ${webhookTargetsLine}
 ${dynamicAgentPolicyLine}
+${entryVisibilityLine}
 ${proxyEnabled ? "✅ WeCom 出站代理已启用" : "ℹ️ WeCom 出站代理未启用"}
-${voiceStatusLine}`;
+${voiceStatusLine}
+${observabilityLines.status}
+${observabilityLines.recent}`;
 }
 
 export function buildBotStatusText({
@@ -103,11 +161,14 @@ export function buildBotStatusText({
   allWebhookTargetAliases,
   commandPolicy,
   allowFromPolicy,
+  dmPolicy,
+  eventPolicy,
   groupPolicy,
   deliveryFallbackPolicy,
   streamManagerPolicy,
   webhookBotPolicy,
   dynamicAgentPolicy,
+  observabilityMetrics,
 } = {}) {
   const commandPolicyLine = commandPolicy.enabled
     ? `✅ 指令白名单已启用（${commandPolicy.allowlist.length} 条，管理员 ${commandPolicy.adminUsers.length} 人）`
@@ -116,12 +177,10 @@ export function buildBotStatusText({
     allowFromPolicy.allowFrom.length === 0 || allowFromPolicy.allowFrom.includes("*")
       ? "ℹ️ 发送者授权：未限制（allowFrom 未配置）"
       : `✅ 发送者授权：已限制 ${allowFromPolicy.allowFrom.length} 个用户`;
+  const dmPolicyLine = buildDmPolicyStatusLine(dmPolicy);
+  const eventPolicyLine = buildEventPolicyStatusLine(eventPolicy);
   const groupPolicyLine = groupPolicy.enabled
-    ? groupPolicy.triggerMode === "mention"
-      ? "✅ 群聊触发：仅 @ 命中后处理"
-      : groupPolicy.triggerMode === "keyword"
-        ? `✅ 群聊触发：关键词模式（${(groupPolicy.triggerKeywords || []).join(" / ") || "未配置关键词"}）`
-        : "✅ 群聊触发：无需 @（全部处理）"
+    ? "✅ 群聊触发：仅 @ 机器人后处理（企业微信 Bot 平台限制）"
     : "⚠️ 群聊处理未启用";
   const fallbackPolicyLine = deliveryFallbackPolicy.enabled
     ? `✅ 回包兜底链路已启用（${deliveryFallbackPolicy.order.join(" > ")}）`
@@ -139,6 +198,8 @@ export function buildBotStatusText({
   const dynamicAgentPolicyLine = dynamicAgentPolicy.enabled
     ? `✅ 动态 Agent 路由已启用（mode=${dynamicAgentPolicy.mode}，用户映射 ${Object.keys(dynamicAgentPolicy.userMap || {}).length}，群映射 ${Object.keys(dynamicAgentPolicy.groupMap || {}).length}）`
     : "ℹ️ 动态 Agent 路由未启用";
+  const entryVisibilityLine = "ℹ️ 微信插件入口联系人：Bot 模式通常不显示（请通过机器人会话/群聊入口触发）";
+  const observabilityLines = buildObservabilityStatusLines(observabilityMetrics);
   return `📊 系统状态
 
 渠道：企业微信 AI 机器人 (Bot)
@@ -150,12 +211,17 @@ Bot Webhook：${botConfig.webhookPath}
 ✅ 原生流式回复（stream）
 ${commandPolicyLine}
 ${allowFromPolicyLine}
+${dmPolicyLine}
+${eventPolicyLine}
 ${groupPolicyLine}
 ${fallbackPolicyLine}
 ${streamManagerPolicyLine}
 ${webhookBotPolicyLine}
 ${webhookTargetsLine}
-${dynamicAgentPolicyLine}`;
+${dynamicAgentPolicyLine}
+${entryVisibilityLine}
+${observabilityLines.status}
+${observabilityLines.recent}`;
 }
 
 export function buildWecomBotHelpText() {
@@ -163,8 +229,11 @@ export function buildWecomBotHelpText() {
 
 可用命令：
 /help - 显示帮助信息
+/new - 新建会话（兼容命令，等价于 /reset）
 /status - 查看系统状态
 /clear - 重置会话（等价于 /reset）
 
+说明：企业微信 Bot 群聊通常仅对 @ 机器人消息触发回调。
+
 直接发送消息即可与 AI 对话。`;
 }

package/src/wecom/observability-metrics.js

@@ -0,0 +1,133 @@
+function incrementCounter(map, key, delta = 1) {
+  const normalizedKey = String(key ?? "").trim() || "unknown";
+  map[normalizedKey] = Number(map[normalizedKey] || 0) + Number(delta || 0);
+}
+
+function safeNow(nowFn) {
+  try {
+    return Number(nowFn?.() || Date.now());
+  } catch {
+    return Date.now();
+  }
+}
+
+export function createWecomObservabilityMetricsStore({
+  maxRecentFailures = 40,
+  now = () => Date.now(),
+} = {}) {
+  const state = {
+    inboundTotal: 0,
+    inboundByMode: { agent: 0, bot: 0 },
+    inboundByType: {},
+    inboundByAccount: {},
+    deliveryTotal: 0,
+    deliverySuccess: 0,
+    deliveryFailed: 0,
+    deliveryByLayer: {},
+    deliveryByStatus: {},
+    errorsTotal: 0,
+    errorsByScope: {},
+    recentFailures: [],
+  };
+
+  function pushRecentFailure(entry = {}) {
+    const row = {
+      at: safeNow(now),
+      scope: String(entry.scope ?? "unknown").trim() || "unknown",
+      reason: String(entry.reason ?? "unknown").trim().slice(0, 240) || "unknown",
+      accountId: String(entry.accountId ?? "").trim() || undefined,
+      layer: String(entry.layer ?? "").trim() || undefined,
+    };
+    state.recentFailures.push(row);
+    if (state.recentFailures.length > maxRecentFailures) {
+      state.recentFailures.splice(0, state.recentFailures.length - maxRecentFailures);
+    }
+  }
+
+  function recordInboundMetric({
+    mode = "agent",
+    msgType = "",
+    accountId = "default",
+  } = {}) {
+    const normalizedMode = String(mode ?? "agent").trim().toLowerCase() === "bot" ? "bot" : "agent";
+    const normalizedType = String(msgType ?? "").trim().toLowerCase() || "unknown";
+    const normalizedAccountId = String(accountId ?? "default").trim().toLowerCase() || "default";
+    state.inboundTotal += 1;
+    state.inboundByMode[normalizedMode] = Number(state.inboundByMode[normalizedMode] || 0) + 1;
+    incrementCounter(state.inboundByType, normalizedType, 1);
+    incrementCounter(state.inboundByAccount, normalizedAccountId, 1);
+  }
+
+  function recordDeliveryMetric({
+    layer = "",
+    ok = false,
+    finalStatus = "",
+    accountId = "default",
+    attempts = [],
+  } = {}) {
+    const normalizedLayer = String(layer ?? "").trim().toLowerCase() || "unknown";
+    const normalizedStatus = String(finalStatus ?? "").trim().toLowerCase() || (ok ? "ok" : "failed");
+    const normalizedAccountId = String(accountId ?? "default").trim().toLowerCase() || "default";
+    state.deliveryTotal += 1;
+    if (ok) state.deliverySuccess += 1;
+    else state.deliveryFailed += 1;
+    incrementCounter(state.deliveryByLayer, normalizedLayer, 1);
+    incrementCounter(state.deliveryByStatus, normalizedStatus, 1);
+    incrementCounter(state.inboundByAccount, normalizedAccountId, 0);
+
+    const normalizedAttempts = Array.isArray(attempts) ? attempts : [];
+    for (const attempt of normalizedAttempts) {
+      if (attempt?.status === "error") {
+        pushRecentFailure({
+          scope: "delivery",
+          reason: String(attempt?.reason ?? "unknown"),
+          accountId: normalizedAccountId,
+          layer: String(attempt?.layer ?? ""),
+        });
+      }
+    }
+  }
+
+  function recordRuntimeErrorMetric({
+    scope = "runtime",
+    reason = "",
+    accountId = "default",
+    layer = "",
+  } = {}) {
+    const normalizedScope = String(scope ?? "runtime").trim().toLowerCase() || "runtime";
+    const normalizedReason = String(reason ?? "").trim() || "unknown";
+    const normalizedAccountId = String(accountId ?? "default").trim().toLowerCase() || "default";
+    state.errorsTotal += 1;
+    incrementCounter(state.errorsByScope, normalizedScope, 1);
+    pushRecentFailure({
+      scope: normalizedScope,
+      reason: normalizedReason,
+      accountId: normalizedAccountId,
+      layer,
+    });
+  }
+
+  function getWecomObservabilityMetrics() {
+    return {
+      inboundTotal: state.inboundTotal,
+      inboundByMode: { ...state.inboundByMode },
+      inboundByType: { ...state.inboundByType },
+      inboundByAccount: { ...state.inboundByAccount },
+      deliveryTotal: state.deliveryTotal,
+      deliverySuccess: state.deliverySuccess,
+      deliveryFailed: state.deliveryFailed,
+      deliveryByLayer: { ...state.deliveryByLayer },
+      deliveryByStatus: { ...state.deliveryByStatus },
+      errorsTotal: state.errorsTotal,
+      errorsByScope: { ...state.errorsByScope },
+      recentFailures: state.recentFailures.slice(-10).map((item) => ({ ...item })),
+    };
+  }
+
+  return {
+    recordInboundMetric,
+    recordDeliveryMetric,
+    recordRuntimeErrorMetric,
+    getWecomObservabilityMetrics,
+  };
+}

package/src/wecom/outbound-agent-push.js

@@ -14,11 +14,12 @@ export function createWecomAgentPushDeliverer({
   return async function deliverAgentPushReply({
     api,
     fromUser,
+    accountId = "default",
     content = "",
     fallbackText = "",
     mediaFallbackSuffix = "",
   } = {}) {
-    const account = getWecomConfig(api, "default") ?? getWecomConfig(api);
+    const account = getWecomConfig(api, accountId) ?? getWecomConfig(api, "default") ?? getWecomConfig(api);
     if (!account?.corpId || !account?.corpSecret || !account?.agentId) {
       return { ok: false, reason: "agent-config-missing" };
     }

package/src/wecom/outbound-bot-card.js

@@ -0,0 +1,103 @@
+function clampCardContent(text, maxLength = 1400) {
+  const normalized = String(text ?? "").trim();
+  if (!normalized) return "";
+  const limit = Math.max(200, Number(maxLength) || 1400);
+  if (normalized.length <= limit) return normalized;
+  return `${normalized.slice(0, Math.max(0, limit - 3)).trim()}...`;
+}
+
+function buildMarkdownCardBody({
+  title,
+  subtitle,
+  content,
+  footer,
+} = {}) {
+  const sections = [];
+  const normalizedTitle = String(title ?? "").trim();
+  const normalizedSubtitle = String(subtitle ?? "").trim();
+  const normalizedFooter = String(footer ?? "").trim();
+  const normalizedContent = String(content ?? "").trim();
+
+  if (normalizedTitle) {
+    sections.push(`### ${normalizedTitle}`);
+  }
+  if (normalizedSubtitle) {
+    sections.push(`> ${normalizedSubtitle}`);
+  }
+  if (normalizedContent) {
+    sections.push(normalizedContent);
+  }
+  if (normalizedFooter) {
+    sections.push(`> ${normalizedFooter}`);
+  }
+  return sections.join("\n\n").trim();
+}
+
+function buildTemplateCardBody({
+  title,
+  subtitle,
+  content,
+  footer,
+} = {}) {
+  const normalizedTitle = String(title ?? "").trim() || "OpenClaw-Wechat";
+  const normalizedSubtitle = String(subtitle ?? "").trim();
+  const normalizedContent = String(content ?? "").trim();
+  const normalizedFooter = String(footer ?? "").trim();
+
+  const payload = {
+    msgtype: "template_card",
+    template_card: {
+      card_type: "text_notice",
+      main_title: {
+        title: normalizedTitle,
+      },
+      sub_title_text: normalizedContent,
+    },
+  };
+  if (normalizedSubtitle) {
+    payload.template_card.main_title.desc = normalizedSubtitle;
+  }
+  if (normalizedFooter) {
+    payload.template_card.quote_area = {
+      type: 0,
+      quote_text: normalizedFooter,
+    };
+  }
+  return payload;
+}
+
+export function buildWecomBotCardPayload({
+  text = "",
+  cardPolicy = {},
+  hasMedia = false,
+} = {}) {
+  const enabled = cardPolicy?.enabled === true;
+  if (!enabled || hasMedia) return null;
+
+  const content = clampCardContent(text, cardPolicy?.maxContentLength);
+  if (!content) return null;
+
+  const mode = String(cardPolicy?.mode ?? "markdown").trim().toLowerCase();
+  if (mode === "template_card") {
+    return buildTemplateCardBody({
+      title: cardPolicy?.title,
+      subtitle: cardPolicy?.subtitle,
+      content,
+      footer: cardPolicy?.footer,
+    });
+  }
+
+  const markdownContent = buildMarkdownCardBody({
+    title: cardPolicy?.title,
+    subtitle: cardPolicy?.subtitle,
+    content,
+    footer: cardPolicy?.footer,
+  });
+  if (!markdownContent) return null;
+  return {
+    msgtype: "markdown",
+    markdown: {
+      content: markdownContent,
+    },
+  };
+}