openclaw-glance-plugin 0.1.16 → 0.1.18

package/openclaw.plugin.json

@@ -13,6 +13,10 @@
       },
       "lockDir": {
         "type": "string"
+      },
+      "contactsStorePath": {
+        "type": "string",
+        "description": "Path to watch-notify-contacts.json (sender defaults for sms/dingtalk/email/call)"
       }
     },
     "required": ["token"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-glance-plugin",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "OpenClaw plugin client for ticker-monitor openclaw-bridge",
   "type": "module",
   "main": "index.js",

package/skills/glance-watch/SKILL.md

@@ -77,6 +77,19 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 - `channels`（默认至少包含 `openclaw`）
 - 对应渠道配置（`channel_configs.email/call/sms/dingtalk`）
 
+**OpenClaw 会话路由（含 `openclaw` 渠道时必须带上）**  
+触发后要把提醒发回**当前群聊/私聊**，须把路由写入 `channel_configs.openclaw`（或由宿主 `context` 注入，由插件运行时合并）。字段与 openclaw-bridge 一致（snake_case；部分宿主可用 camelCase，由插件归一）：
+
+| 字段 | 含义 |
+|------|------|
+| `channel` / `source_channel` | 来源渠道（钉钉/飞书等与宿主约定） |
+| `account_id` | 多账号场景下的账号标识 |
+| `session_key` | 推荐：可区分群/私聊、多会话的会话键 |
+| `conversation_id` / `chat_id` | 宿主侧发送目标会话 ID |
+
+可从**当前 OpenClaw 上下文**映射到上述字段；**禁止**在拿不到会话信息时留空 `openclaw: {}` 仍假装已配置。宿主通过工具调用传入的 `context`（如 `channelId`、`sessionKey`、`conversationId`）时，插件运行时会合并进 `channel_configs.openclaw`。  
+触发后解析 `watch.triggered` 的 **`payload.channel_configs.openclaw`**（及并列路由字段）再回复到对应会话。
+
 固定模板（必须按此结构构造，字段名不要改）：
 
 ```javascript
@@ -94,7 +107,12 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
   channels: ['openclaw', 'dingtalk', 'sms'],
   // 注意：必须是对象，不要传 JSON 字符串
   channel_configs: {
-    openclaw: {},
+    openclaw: {
+      channel: 'dingtalk',
+      account_id: 'default',
+      session_key: 'agent:main:dingtalk:group:<conversation_id>',
+      conversation_id: '<conversation_id>'
+    },
     dingtalk: {
       cas_id: 'jinguo.xie',
       template_id: 3,
@@ -328,11 +346,34 @@ await runtime.queryTickerData({
 
 `openclaw` 渠道必传，`email` / `call` / `sms` / `dingtalk` 可选。如用户没明确说明使用邮件(email)、电话/外呼(call)、短信(sms)、钉钉(dingtalk)通知提醒，则只需要传入`openclaw`渠道。
 
-但一旦用户选择了某个通知渠道，其配置参数必须完整填写：
-- 选择 `email` 必须提供 `channel_configs.email.to_address/template_id/title/content`
-- 选择 `call` 必须提供 `channel_configs.call.phone/customer_name/condition`
-- 选择 `sms` 必须提供 `channel_configs.sms.receiver(或phone)/template_id/content`
-- 选择 `dingtalk` 必须提供 `channel_configs.dingtalk.cas_id/template_id/msg_type/content`
+### 插件侧联系人记忆与自动补全（openclaw-plugin-node）
+
+宿主在调用 `watch_create`、`notify_*` 等工具时，应把**当前发送者上下文**传入 `context`（与 `openclaw` 路由合并所用上下文一致）。与 OpenClaw `buildSenderContext` 对齐时，推荐优先使用嵌套对象 **`context.senderContext`**（或顶层同名字段），例如：
+
+- `senderContext.channel`（或 `channel` / `channelId`）：来源渠道（钉钉建议为 `dingtalk`）
+- `senderContext.senderId`（或顶层 `senderId` / `sender_id`）：发送者唯一标识；钉钉下通常与 `cas_id` 一致
+- 仍兼容：`senderDingtalkId`、`event.metadata.senderDingtalkId` 等历史字段
+- `senderContext.senderName` / `senderName` / `displayName`：展示名（可用于外呼 `customer_name` 兜底）
+
+插件内等价解析函数为 `extractSenderContext`；`buildSenderContext` 为其别名（单参 `buildSenderContext(context)` 即可）。
+
+插件会在发 `watch.create` / `notify.send` 前：
+
+1. 按 `channel:sender_id` 读写独立 JSON（默认路径：`~/.openclaw/workspace/memory/watch-notify-contacts.json`，可通过插件配置 `contactsStorePath` 或环境变量 `OPENCLAW_CONTACTS_STORE_PATH` 覆盖）。
+2. 对 **sms / dingtalk / email / call** 缺省字段用该发送者已保存的默认值补全。
+3. **钉钉**：若当前会话渠道为 `dingtalk` 且未提供 `cas_id`，则用当前发送者 ID 作为默认 `cas_id` 并写入记忆。
+4. **外呼**：`customer_name` 优先用户本轮输入 → 记忆 → 发送者展示名。
+
+若补全后仍缺必填项（如从未提供过手机号），bridge 仍会报错，此时应追问用户；用户一旦提供有效值，插件会更新记忆，后续同发送者无需重复填写。
+
+向用户确认时**避免完整回显手机号**，可用尾号提示。
+
+用户选择了某个通知渠道时，**最终**发往 bridge 的 payload 仍须满足各渠道必填项（插件会先按上文规则补全；补全后仍缺的，由 Agent 追问用户补齐）：
+
+- 选择 `email`：`channel_configs.email.to_address/template_id/title/content`
+- 选择 `call`：`channel_configs.call.phone/customer_name/condition`
+- 选择 `sms`：`channel_configs.sms.receiver(或phone)/template_id/content`
+- 选择 `dingtalk`：`channel_configs.dingtalk.cas_id/template_id/msg_type/content`
 
 ### email 参数（channel_configs.email）
 - `to_address`：收件人邮箱（必填，缺失不可创建/不可发送）

package/src/OpenClawPluginAdapter.js

@@ -1,4 +1,5 @@
 import { OpenClawBridgeClient } from './OpenClawBridgeClient.js';
+import { extractOpenclawRoutingFromRecord } from './openclawRouting.js';
 
 /**
  * 全局单例 Adapter 实例
@@ -83,7 +84,6 @@ export class OpenClawPluginAdapter {
     const channelConfigs = { ...(demand.channelConfigs || {}) };
 
     if (demand.openclawConfig) {
-      channelConfigs.openclaw = demand.openclawConfig;
       if (!channels.includes('openclaw')) channels.push('openclaw');
     }
     if (demand.emailConfig) {
@@ -103,7 +103,20 @@ export class OpenClawPluginAdapter {
       if (!channels.includes('dingtalk')) channels.push('dingtalk');
     }
     if (!channels.includes('openclaw')) channels.unshift('openclaw');
-    if (!channelConfigs.openclaw) channelConfigs.openclaw = {};
+
+    const existingOpenclaw =
+      channelConfigs.openclaw && typeof channelConfigs.openclaw === 'object'
+        ? { ...channelConfigs.openclaw }
+        : {};
+    const explicitOpenclaw =
+      demand.openclawConfig && typeof demand.openclawConfig === 'object'
+        ? { ...demand.openclawConfig }
+        : {};
+    channelConfigs.openclaw = {
+      ...extractOpenclawRoutingFromRecord(demand),
+      ...existingOpenclaw,
+      ...explicitOpenclaw
+    };
 
     const payload = {
       product_code: demand.productCode,

package/src/config/runtime-config.js

@@ -2,6 +2,19 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 
+export function resolveContactsStorePath({ env = process.env, pluginConfig = {} } = {}) {
+  const explicit = pick(
+    pluginConfig,
+    ['contactsStorePath', 'contacts_store_path'],
+    pick(env, ['OPENCLAW_CONTACTS_STORE_PATH'])
+  );
+  if (explicit) {
+    return String(explicit).trim();
+  }
+  const homeDir = pick(env, ['HOME', 'USERPROFILE']) || os.homedir();
+  return path.join(String(homeDir), '.openclaw', 'workspace', 'memory', 'watch-notify-contacts.json');
+}
+
 import { ProcessLock } from '../runtime/lock/ProcessLock.js';
 
 const DEFAULT_BASE_WS_URL = 'wss://glanceup-pre.100credit.cn';
@@ -65,6 +78,7 @@ export function resolveRuntimeConfig({ env = process.env, pluginConfig = {} } =
     baseWsUrl,
     token,
     lockDir,
-    lockKey
+    lockKey,
+    contactsStorePath: resolveContactsStorePath({ env, pluginConfig })
   };
 }

package/src/openclawRouting.js

@@ -0,0 +1,174 @@
+/**
+ * openclaw-bridge 约定的会话路由字段（snake_case），用于落库与触发回推。
+ * @see ticker-monitor services/openclaw_bridge/main.py _extract_openclaw_routing
+ */
+
+export function pickFirstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 用于 senderId、路由 ID 等：非空字符串 trim，有限数字 / bigint 转字符串。
+ * （纯 pickFirstString 会忽略数字类型，导致记忆主键丢失。）
+ */
+export function pickFirstTrimmedScalar(...values) {
+  for (const value of values) {
+    if (value == null) continue;
+    if (typeof value === 'string') {
+      const t = value.trim();
+      if (t) return t;
+      continue;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return String(value);
+    }
+    if (typeof value === 'bigint') {
+      return String(value);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 用于发送者主键：忽略数字 / bigint 0（常见占位），避免生成 `unknown:0` 等无效记忆键。
+ */
+export function pickFirstSenderIdentifier(...values) {
+  for (const value of values) {
+    if (value == null) continue;
+    if (typeof value === 'string') {
+      const t = value.trim();
+      if (t) return t;
+      continue;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      if (value === 0) continue;
+      return String(value);
+    }
+    if (typeof value === 'bigint') {
+      if (value === 0n) continue;
+      return String(value);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 从任意平面对象提取路由（支持 camelCase / snake_case），返回 bridge 使用的 snake_case。
+ * @param {Record<string, unknown>} source
+ * @returns {Record<string, string>}
+ */
+export function extractOpenclawRoutingFromRecord(source = {}) {
+  if (!source || typeof source !== 'object') {
+    return {};
+  }
+  const channel = pickFirstString(
+    source.channel,
+    source.source_channel,
+    source.sourceChannel
+  );
+  const account_id = pickFirstString(source.account_id, source.accountId);
+  const session_key = pickFirstString(source.session_key, source.sessionKey);
+  const conversation_id = pickFirstString(
+    source.conversation_id,
+    source.conversationId,
+    source.chat_id,
+    source.chatId
+  );
+  const out = {};
+  if (channel) out.channel = channel;
+  if (account_id) out.account_id = account_id;
+  if (session_key) out.session_key = session_key;
+  if (conversation_id) out.conversation_id = conversation_id;
+  return out;
+}
+
+/**
+ * 合并 params 与宿主 context / event.metadata 上的路由字段（与插件 index 行为一致）。
+ * @param {{ params?: Record<string, unknown>, context?: Record<string, unknown> }} args
+ * @returns {Record<string, string>}
+ */
+export function mergeContextMetadata(context = {}) {
+  const flat =
+    context.metadata && typeof context.metadata === 'object' && !Array.isArray(context.metadata)
+      ? context.metadata
+      : {};
+  const eventMeta =
+    context.event?.metadata &&
+    typeof context.event.metadata === 'object' &&
+    !Array.isArray(context.event.metadata)
+      ? context.event.metadata
+      : {};
+  return { ...flat, ...eventMeta };
+}
+
+export function unwrapSenderContextObject(context = {}) {
+  const sc = context?.senderContext;
+  if (sc && typeof sc === 'object' && !Array.isArray(sc)) {
+    return sc;
+  }
+  return {};
+}
+
+export function deriveOpenclawRouting({ params = {}, context = {} } = {}) {
+  const metadata = mergeContextMetadata(context);
+  const sc = unwrapSenderContextObject(context);
+  const routing = extractOpenclawRoutingFromRecord(params || {});
+
+  if (!routing.channel) {
+    const channel = pickFirstString(
+      sc.channel,
+      sc.sourceChannel,
+      sc.source_channel,
+      params?.source_channel,
+      metadata?.channel,
+      metadata?.channelId,
+      context?.channel,
+      context?.channelId
+    );
+    if (channel) routing.channel = channel;
+  }
+  if (!routing.account_id) {
+    const account_id = pickFirstString(
+      params?.account_id,
+      sc.accountId,
+      sc.account_id,
+      context?.accountId,
+      metadata?.accountId
+    );
+    if (account_id) routing.account_id = account_id;
+  }
+  if (!routing.session_key) {
+    const session_key = pickFirstString(
+      params?.session_key,
+      params?.sessionKey,
+      sc.sessionKey,
+      sc.session_key,
+      context?.sessionKey,
+      metadata?.sessionKey
+    );
+    if (session_key) routing.session_key = session_key;
+  }
+  if (!routing.conversation_id) {
+    const conversation_id = pickFirstString(
+      params?.conversation_id,
+      params?.conversationId,
+      params?.chat_id,
+      params?.chatId,
+      sc.conversationId,
+      sc.conversation_id,
+      sc.chatId,
+      sc.chat_id,
+      context?.conversationId,
+      metadata?.conversationId,
+      metadata?.chatId,
+      metadata?.groupId
+    );
+    if (conversation_id) routing.conversation_id = conversation_id;
+  }
+  return routing;
+}

package/src/plugin/index.js

@@ -1,5 +1,10 @@
-import { resolveRuntimeConfig } from '../config/runtime-config.js';
+import { resolveRuntimeConfig, resolveContactsStorePath } from '../config/runtime-config.js';
+import { extractOpenclawRoutingFromRecord, deriveOpenclawRouting } from '../openclawRouting.js';
 import { BridgeRuntime } from '../runtime/BridgeRuntime.js';
+import {
+  mergeAndPersistNotifyContacts,
+  mergeAndPersistWatchContacts
+} from './watch-notify-contacts.js';
 import { PluginDispatcher } from '../runtime/dispatchers/PluginDispatcher.js';
 import { ProcessLock } from '../runtime/lock/ProcessLock.js';
 
@@ -56,52 +61,6 @@ async function getReadyRuntime(startupPromise) {
   return activeRuntime;
 }
 
-function pickFirstString(...values) {
-  for (const value of values) {
-    if (typeof value === 'string' && value.trim()) {
-      return value.trim();
-    }
-  }
-  return undefined;
-}
-
-function deriveOpenclawRouting({ params = {}, context = {} } = {}) {
-  const metadata = context?.event?.metadata || {};
-
-  const channel = pickFirstString(
-    params?.channel,
-    params?.source_channel,
-    metadata?.channel,
-    metadata?.channelId,
-    context?.channel,
-    context?.channelId
-  );
-  const accountId = pickFirstString(params?.account_id, context?.accountId, metadata?.accountId);
-  const sessionKey = pickFirstString(
-    params?.session_key,
-    params?.sessionKey,
-    context?.sessionKey,
-    metadata?.sessionKey
-  );
-  const conversationId = pickFirstString(
-    params?.conversation_id,
-    params?.conversationId,
-    params?.chat_id,
-    params?.chatId,
-    context?.conversationId,
-    metadata?.conversationId,
-    metadata?.chatId,
-    metadata?.groupId
-  );
-
-  const routing = {};
-  if (channel) routing.channel = channel;
-  if (accountId) routing.account_id = accountId;
-  if (sessionKey) routing.session_key = sessionKey;
-  if (conversationId) routing.conversation_id = conversationId;
-  return routing;
-}
-
 function mapDemandToCreatePayload(demand = {}) {
   const channels = Array.isArray(demand.channels)
     ? demand.channels
@@ -111,7 +70,6 @@ function mapDemandToCreatePayload(demand = {}) {
   const channelConfigs = { ...(demand.channelConfigs || {}) };
 
   if (demand.openclawConfig) {
-    channelConfigs.openclaw = demand.openclawConfig;
     if (!channels.includes('openclaw')) channels.push('openclaw');
   }
   if (demand.emailConfig) {
@@ -131,7 +89,20 @@ function mapDemandToCreatePayload(demand = {}) {
     if (!channels.includes('dingtalk')) channels.push('dingtalk');
   }
   if (!channels.includes('openclaw')) channels.unshift('openclaw');
-  if (!channelConfigs.openclaw) channelConfigs.openclaw = {};
+
+  const existingOpenclaw =
+    channelConfigs.openclaw && typeof channelConfigs.openclaw === 'object'
+      ? { ...channelConfigs.openclaw }
+      : {};
+  const explicitOpenclaw =
+    demand.openclawConfig && typeof demand.openclawConfig === 'object'
+      ? { ...demand.openclawConfig }
+      : {};
+  channelConfigs.openclaw = {
+    ...extractOpenclawRoutingFromRecord(demand),
+    ...existingOpenclaw,
+    ...explicitOpenclaw
+  };
 
   return {
     product_code: demand.productCode || demand.product_code,
@@ -174,7 +145,7 @@ function mergeOpenclawChannelConfig(payload = {}, context = {}) {
   return merged;
 }
 
-function buildControlApi(startupPromise) {
+function buildControlApi(startupPromise, contactsStorePath) {
   return {
     async queryTickerData(query = {}) {
       const runtime = await getReadyRuntime(startupPromise);
@@ -193,33 +164,58 @@ function buildControlApi(startupPromise) {
     async createWatch(payload = {}, context = {}) {
       const runtime = await getReadyRuntime(startupPromise);
       const normalized = mergeOpenclawChannelConfig(payload, context);
-      return runtime.request('watch.create', normalized);
+      const filled = await mergeAndPersistWatchContacts(
+        contactsStorePath,
+        normalized,
+        context
+      );
+      return runtime.request('watch.create', filled);
     },
-    async sendNotification(input = {}) {
+    async sendNotification(input = {}, context = {}) {
       const runtime = await getReadyRuntime(startupPromise);
-      const channel = input.channel;
+      const ch = String(input.channel ?? '')
+        .trim()
+        .toLowerCase();
+      const allowed = new Set(['sms', 'email', 'call', 'dingtalk']);
+      if (!ch || !allowed.has(ch)) {
+        throw new Error(
+          'notify.send requires input.channel to be one of: sms, email, call, dingtalk'
+        );
+      }
       const payload = { ...(input.payload || {}) };
+      const merged = await mergeAndPersistNotifyContacts(
+        contactsStorePath,
+        ch,
+        payload,
+        context
+      );
       return runtime.request('notify.send', {
-        ...payload,
-        channel
+        ...merged,
+        channel: ch
       });
     },
-    async sendSms(payload = {}) {
-      return this.sendNotification({ channel: 'sms', payload });
+    async sendSms(payload = {}, context = {}) {
+      return this.sendNotification({ channel: 'sms', payload }, context);
     },
-    async sendCall(payload = {}) {
-      return this.sendNotification({ channel: 'call', payload });
+    async sendCall(payload = {}, context = {}) {
+      return this.sendNotification({ channel: 'call', payload }, context);
     },
-    async sendEmail(payload = {}) {
-      return this.sendNotification({ channel: 'email', payload });
+    async sendEmail(payload = {}, context = {}) {
+      return this.sendNotification({ channel: 'email', payload }, context);
     },
-    async sendDingtalk(payload = {}) {
-      return this.sendNotification({ channel: 'dingtalk', payload });
+    async sendDingtalk(payload = {}, context = {}) {
+      return this.sendNotification({ channel: 'dingtalk', payload }, context);
     },
     async submitWatchDemand(demand = {}, context = {}) {
       const runtime = await getReadyRuntime(startupPromise);
       const payload = mapDemandToCreatePayload(demand);
-      return runtime.request('watch.create', mergeOpenclawChannelConfig(payload, context));
+      const normalized = mergeOpenclawChannelConfig(payload, context);
+      const filled = await mergeAndPersistWatchContacts(
+        contactsStorePath,
+        normalized,
+        context
+      );
+      return runtime.request('watch.create', filled);
     },
     async pauseWatch(strategyId) {
       const runtime = await getReadyRuntime(startupPromise);
@@ -314,7 +310,7 @@ function registerControlTools(api, controlApi) {
       additionalProperties: true,
       properties: {}
     },
-    (args) => controlApi.sendSms(args || {})
+    (args, meta = {}) => controlApi.sendSms(args || {}, meta?.context || {})
   );
 
   tryRegisterTool(
@@ -326,7 +322,7 @@ function registerControlTools(api, controlApi) {
       additionalProperties: true,
       properties: {}
     },
-    (args) => controlApi.sendCall(args || {})
+    (args, meta = {}) => controlApi.sendCall(args || {}, meta?.context || {})
   );
 
   tryRegisterTool(
@@ -338,7 +334,7 @@ function registerControlTools(api, controlApi) {
       additionalProperties: true,
       properties: {}
     },
-    (args) => controlApi.sendEmail(args || {})
+    (args, meta = {}) => controlApi.sendEmail(args || {}, meta?.context || {})
   );
 
   tryRegisterTool(
@@ -350,7 +346,7 @@ function registerControlTools(api, controlApi) {
       additionalProperties: true,
       properties: {}
     },
-    (args) => controlApi.sendDingtalk(args || {})
+    (args, meta = {}) => controlApi.sendDingtalk(args || {}, meta?.context || {})
   );
 
   tryRegisterTool(
@@ -436,6 +432,8 @@ const plugin = {
       api?.config?.plugins?.glanceBridge?.config ||
       {};
 
+    const contactsStorePath = resolveContactsStorePath({ pluginConfig });
+
     const startupPromise = startPluginRuntime({
       runtime: api?.runtime,
       pluginConfig
@@ -444,7 +442,7 @@ const plugin = {
       api?.runtime?.logger?.error?.(`[openclaw-glance-plugin] runtime start failed: ${err.message}`);
     });
 
-    const controlApi = buildControlApi(startupPromise);
+    const controlApi = buildControlApi(startupPromise, contactsStorePath);
     api.glanceBridge = controlApi;
     registerControlTools(api, controlApi);
 

package/src/plugin/watch-notify-contacts.js

@@ -0,0 +1,478 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  deriveOpenclawRouting,
+  mergeContextMetadata,
+  pickFirstSenderIdentifier,
+  pickFirstString,
+  unwrapSenderContextObject
+} from '../openclawRouting.js';
+
+/**
+ * 同一联系人文件读改写串行化，避免并发丢更新。
+ * 仅单进程内有效；多进程同时写仍可能竞态，需外部协调或独占部署。
+ */
+const contactFileQueues = new Map();
+
+export function runContactsFileSerialized(filePath, fn) {
+  const key = path.resolve(String(filePath));
+  const prev = contactFileQueues.get(key) || Promise.resolve();
+  const next = prev.then(
+    () => fn(),
+    () => fn()
+  );
+  contactFileQueues.set(key, next);
+  return next.finally(() => {
+    if (contactFileQueues.get(key) === next) {
+      contactFileQueues.delete(key);
+    }
+  });
+}
+
+/**
+ * 从 OpenClaw / 宿主上下文解析发送者维度主键（channel:sender_id）。
+ * 与 OpenClaw `buildSenderContext` 对齐：优先 `context.senderContext`，其次顶层 `senderId`；
+ * 仍兼容 `senderDingtalkId`、metadata、路由字段等历史来源。
+ */
+export function extractSenderContext({ context = {}, params = {} } = {}) {
+  const metadata = mergeContextMetadata(context);
+  const sc = unwrapSenderContextObject(context);
+  const routing = deriveOpenclawRouting({ params, context });
+
+  const channelRaw = pickFirstString(
+    sc.channel,
+    sc.sourceChannel,
+    sc.source_channel,
+    routing.channel,
+    params?.source_channel,
+    metadata?.channel,
+    metadata?.channelId,
+    context?.channel,
+    context?.channelId
+  );
+  const channel = String(channelRaw || 'unknown')
+    .toLowerCase()
+    .trim();
+
+  const senderId = pickFirstSenderIdentifier(
+    sc.senderId,
+    sc.sender_id,
+    sc.userId,
+    sc.user_id,
+    sc.casId,
+    sc.cas_id,
+    context.senderId,
+    context.sender_id,
+    context.userId,
+    context.user_id,
+    context.casId,
+    context.cas_id,
+    metadata.senderId,
+    metadata.sender_id,
+    metadata.senderDingtalkId,
+    metadata.sender_dingtalk_id,
+    context.senderDingtalkId,
+    metadata.userId,
+    metadata.user_id,
+    metadata.openId,
+    params.senderId,
+    params.sender_id
+  );
+
+  const senderName = pickFirstString(
+    sc.senderName,
+    sc.sender_name,
+    sc.displayName,
+    sc.display_name,
+    sc.nickname,
+    metadata.senderName,
+    metadata.sender_name,
+    metadata.displayName,
+    metadata.display_name,
+    metadata.nickname,
+    context.senderName,
+    context.displayName
+  );
+
+  if (!senderId) {
+    return { channel, senderId: null, senderName: senderName || null, senderKey: null };
+  }
+  const id = String(senderId).trim();
+  const senderKey = `${channel}:${id}`;
+  return { channel, senderId: id, senderName: senderName || null, senderKey };
+}
+
+/**
+ * 与 OpenClaw 侧 `buildSenderContext(context)` 单参用法兼容的别名。
+ */
+export function buildSenderContext(context = {}, params = {}) {
+  return extractSenderContext({ context, params });
+}
+
+/** @returns {string|null} 仅数字，含简单 +86 剥离 */
+export function normalizePhone(raw) {
+  if (raw == null) return null;
+  let s = String(raw).trim().replace(/\s+/g, '');
+  if (!s) return null;
+  s = s.replace(/^\+86/, '').replace(/^86/, '');
+  const digits = s.replace(/\D/g, '');
+  if (digits.length === 11) return digits;
+  if (digits.length === 13 && digits.startsWith('86')) return digits.slice(2);
+  return null;
+}
+
+/** @returns {string|null} 非空 trim，用于钉钉 cas_id 等 */
+export function normalizeCasId(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  return s || null;
+}
+
+/** @returns {string|null} 合法邮箱则返回 trim 后地址 */
+export function normalizeEmail(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  if (!s) return null;
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)) return null;
+  return s;
+}
+
+export function emptyContactsDoc() {
+  return { version: 1, senders: {} };
+}
+
+async function backupCorruptContactsFile(filePath, raw) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(dir, `${base}.corrupt.${stamp}.bak`);
+  await mkdir(dir, { recursive: true });
+  await writeFile(backupPath, raw, 'utf8');
+}
+
+export async function loadContactsFile(filePath) {
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch (_parseErr) {
+      await backupCorruptContactsFile(filePath, raw);
+      return emptyContactsDoc();
+    }
+    if (!data || typeof data !== 'object') return emptyContactsDoc();
+    if (!data.senders || typeof data.senders !== 'object') {
+      data.senders = {};
+    }
+    if (data.version == null) data.version = 1;
+    return data;
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return emptyContactsDoc();
+    }
+    throw err;
+  }
+}
+
+export async function saveContactsFile(filePath, doc) {
+  const dir = path.dirname(filePath);
+  await mkdir(dir, { recursive: true });
+  const text = `${JSON.stringify(doc, null, 2)}\n`;
+  await writeFile(filePath, text, 'utf8');
+}
+
+function getEntry(doc, senderKey) {
+  if (!senderKey || !doc?.senders) return null;
+  return doc.senders[senderKey] || null;
+}
+
+function touchEntry(doc, senderKey, senderId, senderName) {
+  if (!senderKey) return;
+  if (!doc.senders) doc.senders = {};
+  const prev = doc.senders[senderKey] || {
+    sender_id: senderId,
+    sender_name: senderName,
+    defaults: {},
+    updated_at: null
+  };
+  doc.senders[senderKey] = {
+    ...prev,
+    sender_id: senderId || prev.sender_id,
+    sender_name: senderName || prev.sender_name || undefined
+  };
+}
+
+/**
+ * 宿主未带会话 channel 时，用已合并的 openclaw 路由里的 channel 推断记忆主键，减少 unknown:<id> 串号。
+ */
+function refineSessionFromOpenclawConfig(ctx, openclaw) {
+  let { channel, senderId, senderName, senderKey } = ctx;
+  if (channel !== 'unknown' || !senderId) return ctx;
+  if (!openclaw || typeof openclaw !== 'object') return ctx;
+  const hint = pickFirstString(
+    openclaw.channel,
+    openclaw.source_channel,
+    openclaw.sourceChannel
+  );
+  if (!hint) return ctx;
+  const c = String(hint).toLowerCase().trim();
+  if (!c || c === 'unknown') return ctx;
+  const id = String(senderId).trim();
+  return {
+    channel: c,
+    senderId: id,
+    senderName,
+    senderKey: `${c}:${id}`
+  };
+}
+
+/**
+ * 合并 watch.create / submitWatchDemand 的 channel_configs。
+ * 缺字段时按记忆与钉钉 sender_id 规则补全；有 senderKey 时回写记忆。
+ */
+export async function mergeAndPersistWatchContacts(filePath, mergedPayload, context) {
+  const channels = Array.isArray(mergedPayload?.channels)
+    ? mergedPayload.channels.map((x) => String(x).toLowerCase().trim()).filter(Boolean)
+    : [];
+  if (channels.length === 0) {
+    return mergedPayload;
+  }
+
+  return runContactsFileSerialized(filePath, async () => {
+  let senderCtx = extractSenderContext({
+    context,
+    params: mergedPayload || {}
+  });
+  senderCtx = refineSessionFromOpenclawConfig(
+    senderCtx,
+    mergedPayload?.channel_configs?.openclaw
+  );
+  const { senderKey, senderId, senderName, channel: sessionChannel } = senderCtx;
+
+  let doc = await loadContactsFile(filePath);
+  const entry = getEntry(doc, senderKey);
+  const defaults = entry?.defaults && typeof entry.defaults === 'object' ? entry.defaults : {};
+
+  const channelConfigs = { ...(mergedPayload.channel_configs || {}) };
+
+  const isDingtalkSession = sessionChannel === 'dingtalk';
+
+  if (channels.includes('sms')) {
+    const sms = { ...(channelConfigs.sms && typeof channelConfigs.sms === 'object' ? channelConfigs.sms : {}) };
+    let phone = normalizePhone(pickFirstString(sms.receiver, sms.phone));
+    if (!phone && defaults.sms?.phone) {
+      phone = normalizePhone(defaults.sms.phone);
+      if (phone) {
+        sms.receiver = phone;
+        if (sms.phone != null) delete sms.phone;
+      }
+    } else if (phone) {
+      sms.receiver = phone;
+    }
+    channelConfigs.sms = sms;
+  }
+
+  if (channels.includes('dingtalk')) {
+    const dt = {
+      ...(channelConfigs.dingtalk && typeof channelConfigs.dingtalk === 'object'
+        ? channelConfigs.dingtalk
+        : {})
+    };
+    const casId =
+      normalizeCasId(pickFirstString(dt.cas_id, dt.casId)) ||
+      normalizeCasId(defaults.dingtalk?.cas_id) ||
+      (isDingtalkSession ? normalizeCasId(senderId) : null);
+    if (casId) {
+      dt.cas_id = casId;
+      if (dt.casId != null) delete dt.casId;
+    }
+    channelConfigs.dingtalk = dt;
+  }
+
+  if (channels.includes('email')) {
+    const em = {
+      ...(channelConfigs.email && typeof channelConfigs.email === 'object' ? channelConfigs.email : {})
+    };
+    const addr =
+      normalizeEmail(pickFirstString(em.to_address, em.toAddress)) ||
+      normalizeEmail(defaults.email?.to_address);
+    if (addr) {
+      em.to_address = addr;
+      if (em.toAddress != null) delete em.toAddress;
+    }
+    channelConfigs.email = em;
+  }
+
+  if (channels.includes('call')) {
+    const ca = {
+      ...(channelConfigs.call && typeof channelConfigs.call === 'object' ? channelConfigs.call : {})
+    };
+    let phone = normalizePhone(pickFirstString(ca.phone, ca.receiver));
+    if (!phone && defaults.call?.phone) {
+      phone = normalizePhone(defaults.call.phone);
+    }
+    if (phone) ca.phone = phone;
+
+    let name = pickFirstString(ca.customer_name, ca.customerName);
+    if (!name && defaults.call?.customer_name) {
+      name = String(defaults.call.customer_name).trim();
+    }
+    if (!name && senderName) {
+      name = String(senderName).trim();
+    }
+    if (name) {
+      ca.customer_name = name;
+      if (ca.customerName != null) delete ca.customerName;
+    }
+    channelConfigs.call = ca;
+  }
+
+  const next = { ...mergedPayload, channel_configs: channelConfigs };
+
+  if (senderKey && senderId) {
+    touchEntry(doc, senderKey, senderId, senderName);
+    const patch = {};
+    const smsCfg = channelConfigs.sms;
+    const pSms = normalizePhone(pickFirstString(smsCfg?.receiver, smsCfg?.phone));
+    if (pSms) patch.sms = { phone: pSms };
+
+    const dtCfg = channelConfigs.dingtalk;
+    const cas = normalizeCasId(pickFirstString(dtCfg?.cas_id, dtCfg?.casId));
+    if (cas) patch.dingtalk = { cas_id: cas };
+
+    const emCfg = channelConfigs.email;
+    const to = normalizeEmail(pickFirstString(emCfg?.to_address, emCfg?.toAddress));
+    if (to) patch.email = { to_address: to };
+
+    const caCfg = channelConfigs.call;
+    const cPhone = normalizePhone(pickFirstString(caCfg?.phone, caCfg?.receiver));
+    const cName = pickFirstString(caCfg?.customer_name, caCfg?.customerName);
+    if (cPhone || cName) {
+      patch.call = {
+        ...(cPhone ? { phone: cPhone } : {}),
+        ...(cName ? { customer_name: String(cName).trim() } : {})
+      };
+    }
+
+    if (Object.keys(patch).length > 0) {
+      const cur = doc.senders[senderKey];
+      cur.defaults = { ...(cur.defaults || {}), ...patch };
+      cur.updated_at = new Date().toISOString();
+      await saveContactsFile(filePath, doc);
+    }
+  }
+
+  return next;
+  });
+}
+
+/**
+ * 合并 notify.send 单渠道 payload。
+ */
+export async function mergeAndPersistNotifyContacts(filePath, notifyChannel, payload, context) {
+  const ch = String(notifyChannel || '')
+    .toLowerCase()
+    .trim();
+  const allowedNotify = new Set(['sms', 'email', 'call', 'dingtalk']);
+  if (!ch || !allowedNotify.has(ch)) {
+    return { ...(payload && typeof payload === 'object' ? payload : {}) };
+  }
+
+  return runContactsFileSerialized(filePath, async () => {
+  let senderCtx = extractSenderContext({
+    context,
+    params: payload || {}
+  });
+  const routingHint = deriveOpenclawRouting({ params: payload || {}, context });
+  senderCtx = refineSessionFromOpenclawConfig(
+    senderCtx,
+    routingHint.channel ? { channel: routingHint.channel } : null
+  );
+  const { senderKey, senderId, senderName, channel: sessionChannel } = senderCtx;
+  const out = { ...(payload && typeof payload === 'object' ? payload : {}) };
+
+  let doc = await loadContactsFile(filePath);
+  const entry = getEntry(doc, senderKey);
+  const defaults = entry?.defaults && typeof entry.defaults === 'object' ? entry.defaults : {};
+  const isDingtalkSession = sessionChannel === 'dingtalk';
+
+  if (ch === 'sms') {
+    let phone = normalizePhone(pickFirstString(out.receiver, out.phone));
+    if (!phone && defaults.sms?.phone) {
+      phone = normalizePhone(defaults.sms.phone);
+    }
+    if (phone) {
+      out.receiver = phone;
+      if (out.phone != null) delete out.phone;
+    }
+  } else if (ch === 'dingtalk') {
+    const casId =
+      normalizeCasId(pickFirstString(out.cas_id, out.casId)) ||
+      normalizeCasId(defaults.dingtalk?.cas_id) ||
+      (isDingtalkSession ? normalizeCasId(senderId) : null);
+    if (casId) {
+      out.cas_id = casId;
+      if (out.casId != null) delete out.casId;
+    }
+  } else if (ch === 'email') {
+    const addr =
+      normalizeEmail(pickFirstString(out.to_address, out.toAddress)) ||
+      normalizeEmail(defaults.email?.to_address);
+    if (addr) {
+      out.to_address = addr;
+      if (out.toAddress != null) delete out.toAddress;
+    }
+  } else if (ch === 'call') {
+    let phone = normalizePhone(pickFirstString(out.phone, out.receiver));
+    if (!phone && defaults.call?.phone) {
+      phone = normalizePhone(defaults.call.phone);
+    }
+    if (phone) out.phone = phone;
+
+    let name = pickFirstString(out.customer_name, out.customerName);
+    if (!name && defaults.call?.customer_name) {
+      name = String(defaults.call.customer_name).trim();
+    }
+    if (!name && senderName) {
+      name = String(senderName).trim();
+    }
+    if (name) {
+      out.customer_name = name;
+      if (out.customerName != null) delete out.customerName;
+    }
+  }
+
+  if (senderKey && senderId) {
+    touchEntry(doc, senderKey, senderId, senderName);
+    const patch = {};
+    if (ch === 'sms') {
+      const p = normalizePhone(pickFirstString(out.receiver, out.phone));
+      if (p) patch.sms = { phone: p };
+    } else if (ch === 'dingtalk') {
+      const c = normalizeCasId(pickFirstString(out.cas_id, out.casId));
+      if (c) patch.dingtalk = { cas_id: c };
+    } else if (ch === 'email') {
+      const t = normalizeEmail(pickFirstString(out.to_address, out.toAddress));
+      if (t) patch.email = { to_address: t };
+    } else if (ch === 'call') {
+      const p = normalizePhone(pickFirstString(out.phone, out.receiver));
+      const n = pickFirstString(out.customer_name, out.customerName);
+      if (p || n) {
+        patch.call = {
+          ...(p ? { phone: p } : {}),
+          ...(n ? { customer_name: String(n).trim() } : {})
+        };
+      }
+    }
+    if (Object.keys(patch).length > 0) {
+      const cur = doc.senders[senderKey];
+      cur.defaults = { ...(cur.defaults || {}), ...patch };
+      cur.updated_at = new Date().toISOString();
+      await saveContactsFile(filePath, doc);
+    }
+  }
+
+  return out;
+  });
+}