openclaw-plugin-yuanbao 2.13.2 → 2.13.4

package/dist/src/access/ws/runtime.d.ts

@@ -4,6 +4,10 @@
  * Uses Map<accountId, WsClient> to manage concurrent connections.
  * Each account's WsClient reference is stored when the ws-gateway starts
  * and consumed by the outbound sendText path.
+ *
+ * Uses globalThis + Symbol.for() to guarantee a process-wide singleton,
+ * because the bundled channel entry may load this module in separate scopes
+ * (plugin scope vs tool-registration scope).
  */
 import type { YuanbaoWsClient } from "./client.js";
 /**

package/dist/src/access/ws/runtime.js

@@ -1,4 +1,6 @@
-const activeClients = new Map();
+const WS_CLIENTS_KEY = Symbol.for("yuanbao:ws:activeClients");
+const activeClients = globalThis[WS_CLIENTS_KEY]
+    ?? (globalThis[WS_CLIENTS_KEY] = new Map());
 /**
  * Store a WebSocket client reference for the given account.
  */

package/dist/src/business/pipeline/middlewares/dispatch-reply.js

@@ -53,7 +53,7 @@ export const dispatchReply = {
             },
             account,
             toAccount: fromAccount,
-            groupCode,
+            groupCode: isGroup ? groupCode : undefined,
         };
         const heartbeat = createReplyHeartbeatController({ meta: heartbeatMeta });
         // Track deliver kind transitions, detect tool-call boundaries

package/dist/src/business/tools/group.js

@@ -7,6 +7,7 @@
  * Fetches group info via the queryGroupInfo interface (WS protocol).
  */
 import { getMember } from "../../infra/cache/member.js";
+import { createLog } from "../../logger.js";
 import { extractGroupCode, json } from "../utils/utils.js";
 /**
  * Create the query_group_info tool definition.
@@ -14,6 +15,9 @@ import { extractGroupCode, json } from "../utils/utils.js";
  * Queries basic group info including name, owner (userId + nickname), and member count.
  */
 function createQueryGroupInfoTool(ctx) {
+    const log = createLog("tools.group");
+    if (!ctx.messageChannel?.includes('yuanbao'))
+        return null;
     const sessionKey = ctx.sessionKey ?? "";
     const accountId = ctx.agentAccountId ?? "";
     return {
@@ -32,8 +36,8 @@ function createQueryGroupInfoTool(ctx) {
          * 1. No groupCode -> inform model no group context
          * 2. Call queryGroupInfo to get basic group info
          */
-        async execute(_toolCallId, _params) {
-            // Extract groupCode from sessionKey
+        async execute(toolCallId, _params) {
+            log.debug("execute", { toolCallId });
             const groupCode = extractGroupCode(sessionKey);
             // 1. No groupCode -> cannot locate group
             if (!groupCode) {
@@ -75,5 +79,7 @@ function createQueryGroupInfoTool(ctx) {
  * - query_group_info: Query basic group info (always available)
  */
 export function registerGroupTools(api) {
-    api.registerTool(createQueryGroupInfoTool, { optional: false });
+    const log = createLog("tools.group");
+    log.info("register tool", { name: "query_group_info", optional: false });
+    api.registerTool(createQueryGroupInfoTool, { name: "query_group_info", optional: false });
 }

package/dist/src/business/tools/member.js

@@ -8,6 +8,7 @@
  * For group owner info, use the query_group_info tool.
  */
 import { getMember } from "../../infra/cache/member.js";
+import { createLog } from "../../logger.js";
 import { extractGroupCode, json } from "../utils/utils.js";
 /** @mention hint text (used as JSON field value) */
 const MENTION_HINT_TEXT = 'To @mention a user, you MUST use the format: space + @ + nickname + space (e.g. " @Alice ").';
@@ -92,7 +93,11 @@ function handleListAll(allMembers, mention) {
  *
  * Merges the original lookup_session_members and query_group_members into one tool.
  * Prefers API-fetched full member list; session cache as fallback.
- */ function createQuerySessionMembersTool(ctx) {
+ */
+function createQuerySessionMembersTool(ctx) {
+    const log = createLog("tools.member");
+    if (!ctx.messageChannel?.includes('yuanbao'))
+        return null;
     const sessionKey = ctx.sessionKey ?? "";
     const accountId = ctx.agentAccountId ?? "";
     return {
@@ -130,11 +135,11 @@ function handleListAll(allMembers, mention) {
          * 2. Query via Member facade: prefer GroupMember (WS API) -> fallback SessionMember (cache)
          * 3. Dispatch to action handlers
          */
-        async execute(_toolCallId, params) {
+        async execute(toolCallId, params) {
+            log.debug("execute", { toolCallId });
             const action = typeof params.action === "string" ? params.action : "list_all";
             const nameFilter = typeof params.name === "string" ? params.name.trim() : "";
             const mention = params.mention === true || params.mention === "true";
-            // Extract groupCode from sessionKey
             const groupCode = extractGroupCode(sessionKey);
             if (!groupCode) {
                 return json({
@@ -169,5 +174,7 @@ function handleListAll(allMembers, mention) {
  * - query_session_members: Query session members (always available)
  */
 export function registerMemberTools(api) {
-    api.registerTool(createQuerySessionMembersTool, { optional: false });
+    const log = createLog("tools.member");
+    log.info("register tool", { name: "query_session_members", optional: false });
+    api.registerTool(createQuerySessionMembersTool, { name: "query_session_members", optional: false });
 }

package/dist/src/business/tools/remind.d.ts

@@ -1,8 +1,9 @@
-/** Scheduled reminder guidance tool (yuanbao_remind). */
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+/** Scheduled reminder tool (yuanbao_remind). */
 /**
- * Register reminder-related tools to the OpenClaw plugin API.
- *
- * Centralized registration ensures the tool is reliably enabled during the plugin lifecycle.
+ * Three-tier execution chain, attempted top-down:
+ * 1. Gateway API (agent-harness-runtime available): calls cron API directly, status="ok"
+ * 2. CLI (plugin-sdk/matrix available): runs `openclaw cron` command, status="ok"; falls back to tier 3 on failure
+ * 3. Legacy fallback: returns status="PENDING_CRON_CALL" with cronToolParams to guide the model
  */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 export declare function registerRemindTools(api: OpenClawPluginApi): void;

package/dist/src/business/tools/remind.js

@@ -1,106 +1,112 @@
-/** Scheduled reminder guidance tool (yuanbao_remind). */
+/** Scheduled reminder tool (yuanbao_remind). */
+import { createLog } from "../../logger.js";
 import { json } from "../utils/utils.js";
-// Prompt constants
+let _callGatewayTool;
+let _runPluginCmd;
+async function resolveCallGatewayTool() {
+    if (_callGatewayTool !== undefined)
+        return _callGatewayTool;
+    try {
+        const sdkPath = 'openclaw/plugin-sdk/agent-harness-runtime';
+        const mod = await import(sdkPath);
+        _callGatewayTool = mod.callGatewayTool;
+    }
+    catch {
+        _callGatewayTool = null;
+    }
+    return _callGatewayTool;
+}
+async function resolveRunPluginCommand() {
+    if (_runPluginCmd !== undefined)
+        return _runPluginCmd;
+    try {
+        const sdkPath = 'openclaw/plugin-sdk/matrix';
+        const mod = await import(sdkPath);
+        _runPluginCmd = mod.runPluginCommandWithTimeout;
+    }
+    catch {
+        _runPluginCmd = null;
+    }
+    return _runPluginCmd;
+}
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_GATEWAY_TIMEOUT_MS = 60_000;
+const DEFAULT_CLI_TIMEOUT_MS = 60_000;
 const RemindSchema = {
-    type: "object",
+    type: 'object',
     properties: {
         action: {
-            type: "string",
-            enum: ["add", "list", "remove"],
-            description: "操作类型: add=创建定时任务, list=查询已有任务, remove=删除任务。"
-                + "删除前请先通过 list 获取 jobId。",
+            type: 'string',
+            enum: ['add', 'list', 'remove'],
+            description: '操作类型: add=创建定时任务, list=查询已有任务, remove=删除任务。'
+                + '删除前请先通过 list 获取 jobId。',
         },
         intent: {
-            type: "string",
-            enum: ["remind", "task"],
-            description: "内容语义类型: 明确是提醒类文案时使用 remind; "
-                + "需要定时执行某项任务时使用 task。默认 remind。",
+            type: 'string',
+            enum: ['remind', 'task'],
+            description: '语义类型，决定触发后的行为模式。'
+                + 'remind: 只需要提醒用户去做某事（如"休息一下""开会"）; '
+                + 'task: 需要 AI 实际执行并输出结果（如"查询今日新闻""检查服务状态"）。'
+                + '判断标准: 用户期望 AI 动手做事选 task，只需要一句提醒选 remind。',
         },
         content: {
-            type: "string",
-            description: "任务内容。action=add 时必填。"
-                + '例如: "喝水"、"检查服务状态"、"整理今天会议纪要并发送总结"。',
+            type: 'string',
+            description: '任务需求的详细内容。action=add 时必填。'
+                + '例如: "提醒用户休息一下"、"查询今日新闻"、"检查服务状态"。',
         },
         time: {
-            type: "string",
-            description: "时间描述, action=add 时必填。"
-                + "相对时间: 5m、1h、1h30m、2d(一次性任务); "
-                + 'cron 表达式: "0 8 * * *"、"0 9 * * 1-5"(循环任务)。'
-                + "包含空格识别为 cron, 否则按相对时间处理。",
-        },
-        timezone: {
-            type: "string",
-            description: "时区, 仅循环任务(cron)生效。默认 Asia/Shanghai。",
+            type: 'string',
+            description: '时间描述, action=add 时必填。'
+                + '绝对时间: ISO 8601 UTC 格式, 如 "2026-04-29T14:00:00.000Z"(一次性任务); '
+                + '相对时间: 5m、1h、1h30m、2d(一次性任务); '
+                + 'cron 表达式: "0 8 * * *"、"0 9 * * 1-5"(循环任务)。',
         },
         name: {
-            type: "string",
-            description: "任务名称(可选)。默认根据 content 自动生成, 便于后续 list/remove 管理。",
+            type: 'string',
+            description: '任务名称(20字以内)，action=add 时可基于 content 内容生成，便于后续 list/remove 管理。',
         },
         jobId: {
-            type: "string",
-            description: "任务 ID。仅 action=remove 时必填, 需先通过 action=list 获取。",
+            type: 'string',
+            description: '任务 ID。仅 action=remove 时必填, 需先通过 action=list 获取。',
         },
     },
-    required: ["action"],
+    required: ['action'],
 };
-/** Task scenario: execute scheduled task, no reply length limit */
-const TASK_AGENT_PROMPT_TEMPLATE = (content) => `你是一个任务执行助手。请在当前时刻完成以下任务：${content}。`
-    + "要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 "
-    + "(3) 直接执行任务并输出可直接给用户的结果 (4) 此时是在执行任务，不要再新建定时任务";
-/** Remind scenario: warm reminder, limited to short reply */
-const REMIND_AGENT_PROMPT_TEMPLATE = (content) => `你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：${content}。`
-    + "要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 "
-    + "(3) 直接输出一条暖心的提醒消息，不要携带其他和该提醒无关的内容 (4) 可以加一句简短的关怀话语 "
-    + "(5) 控制在2-3句话以内 (6) 此时是在执行任务，不要再新建定时任务";
-/** Tool-level description: guide model to prioritize this tool and use cron result as source of truth */
-const YUANBAO_REMIND_TOOL_DESCRIPTION = [
-    "用于规范化创建/查询/删除元宝定时任务，并生成可直接提交给 cron 工具的参数。",
-    "当用户提出提醒、闹钟、定时、X分钟/小时后、每天/每周/每月/每年X点等需求时，或需要查询/删除定时任务/提醒/闹钟时，必须优先调用本工具，",
-    "并在 cron 执行后核对返回结果，只能在确认成功后再告知用户已设置。",
-].join("\n");
-/** Common execution constraint for cron calls */
-const CRON_COMMON_REQUIREMENT = [
-    "请立即调用 cron 工具执行以下参数，并严格以 cron 返回结果为准。",
-    "未执行或执行失败时，不得回复“已设置成功”。",
-    "若执行失败，请明确告知用户执行失败并说明失败原因。",
-].join("\n");
-/** add/create scenario instruction */
-const CRON_ADD_REQUIREMENT = [
-    CRON_COMMON_REQUIREMENT,
-    "仅在确认成功后，才向用户确认定时任务已创建。",
-    "必要时请再调用 cron 的 list 确认任务是否真实创建。",
-    "用法: openclaw cron add|create [options], Options:",
-    " --at <when>: Run once at time (ISO) or +duration (e.g. 20m)",
-    ' --channel <channel>: Delivery channel (last) (default: "last")',
-    " --cron <expr>: Cron expression (5-field or 6-field with seconds)",
-    " --delete-after-run: Delete one-shot job after it succeeds (default: false)",
-    " --message <text>: Agent message payload",
-    " --name <name>: Job name",
-    " --session <target>: Session target (main|isolated)",
-    " --to <dest>: Delivery destination. For this tool, use direct:userId, group:groupCode",
-    ' --tz <iana>: Timezone for cron expressions (IANA) (default: "")',
-].join("\n");
-/** list scenario instruction */
-const CRON_LIST_REQUIREMENT = [
-    CRON_COMMON_REQUIREMENT,
-    "这是查询定时任务列表场景: 调用 openclaw cron list --json",
-    "获取全量任务后，必须基于当前会话目标进行过滤，只返回当前会话的任务。",
-    "过滤规则: 优先使用本次参数中的 to；若未显式提供 to，则使用当前会话自动解析出的目标(例如 direct:<userId> 或 group:<groupCode>)进行匹配。",
-    "如过滤后结果为空，请明确告知“当前会话没有定时任务”。",
-].join("\n");
-/** remove scenario instruction */
-const CRON_REMOVE_REQUIREMENT = [
-    CRON_COMMON_REQUIREMENT,
-    "这是删除任务场景: 调用 cron remove 后仅在确认成功时回复已删除；失败时必须返回失败原因。",
-    "删除后建议再调用 cron list 做二次确认。",
-    "用法: openclaw cron rm|remove <jobId>",
-].join("\n");
-// Parse relative time
+/** task mode: execute scheduled task, no reply length limit */
+const TASK_AGENT_PROMPT_TEMPLATE = (content) => `你是一个任务执行助手。请在当前时刻完成以下任务：${content}。\n\n`
+    + '## 要求\n'
+    + '- 不要回复 HEARTBEAT_OK\n'
+    + '- 不要解释你是谁\n'
+    + '- 直接执行任务并输出可直接给用户的结果\n'
+    + '- **禁止**调用 yuanbao_remind 或 cron 工具，**禁止**新建任何定时任务\n';
+/** remind mode: warm reminder, keep reply brief */
+const REMIND_AGENT_PROMPT_TEMPLATE = (content) => `你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：${content}。\n\n`
+    + '## 要求\n'
+    + '- 不要回复 HEARTBEAT_OK\n'
+    + '- 不要解释你是谁\n'
+    + '- 直接输出一条暖心的提醒消息，不要携带其他和该提醒无关的内容\n'
+    + '- 可以加一句简短的关怀话语\n'
+    + '- 控制在 2-3 句话以内\n'
+    + '- **禁止**调用 yuanbao_remind 或 cron 工具，**禁止**新建任何定时任务\n';
+const TOOL_DESCRIPTION = [
+    '创建/查询/删除元宝定时任务。当用户提出提醒、闹钟、定时、X分钟/小时后、每天/每周/每月/每年X点等需求时，必须调用本工具。',
+    '重要：调用后必须检查返回结果中的 status 字段判断操作是否完成。',
+    'status="ok" 表示已完成，可以告知用户；status="PENDING_CRON_CALL" 表示还需要调用 cron 工具才能生效。',
+    '禁止在 status 不是 "ok" 时告知用户任务已设置成功。',
+].join('\n');
+// Legacy fallback: imperative instructions guiding the model to call cron (concise, non-ignorable)
+const LEGACY_ADD_NEXT_STEP = '你必须立即调用 cron 工具，将 cronToolParams 中的参数传入。只有 cron 返回成功后才能告知用户。未调用 cron 之前，禁止回复"已设置"或"已创建"。';
+const LEGACY_LIST_NEXT_STEP = '你必须立即调用 cron 工具执行 list，获取全量任务后按 filter.to 过滤，只返回当前会话的任务。禁止在调用 cron 之前回复任务列表。';
+const LEGACY_REMOVE_NEXT_STEP = '你必须立即调用 cron 工具执行 remove，传入 cronToolParams.jobId。只有 cron 返回成功后才能告知用户已删除。';
+// ============================================================================
+// Time parsing & formatting
+// ============================================================================
 function parseRelativeTime(raw) {
     const s = raw.trim().toLowerCase();
-    if (!s) {
+    if (!s)
         return null;
-    }
     if (/^\d+$/.test(s)) {
         return parseInt(s, 10) * 60_000;
     }
@@ -113,214 +119,505 @@ function parseRelativeTime(raw) {
         const value = parseFloat(match[1]);
         const unit = match[2];
         switch (unit) {
-            case "d":
+            case 'd':
                 totalMs += value * 86_400_000;
                 break;
-            case "h":
+            case 'h':
                 totalMs += value * 3_600_000;
                 break;
-            case "m":
+            case 'm':
                 totalMs += value * 60_000;
                 break;
-            case "s":
+            case 's':
                 totalMs += value * 1_000;
                 break;
-            default:
-                break;
+            default: break;
         }
     }
     return matched ? Math.round(totalMs) : null;
 }
-// Check if string is a cron expression
+/** Parses an ISO 8601 absolute time string; returns epoch ms, or null if invalid/expired. */
+function parseAbsoluteTime(time) {
+    if (!/\d{4}-\d{2}/.test(time))
+        return null;
+    const ms = Date.parse(time);
+    if (Number.isNaN(ms))
+        return null;
+    return ms > Date.now() ? ms : null;
+}
 function isCronExpression(timeText) {
     const parts = timeText.trim().split(/\s+/);
     return parts.length >= 3 && parts.length <= 6;
 }
-// Format delay duration
 function formatDelay(ms) {
     const seconds = Math.round(ms / 1000);
-    if (seconds < 60) {
+    if (seconds < 60)
         return `${seconds}秒`;
-    }
     const minutes = Math.round(ms / 60_000);
-    if (minutes < 60) {
+    if (minutes < 60)
         return `${minutes}分钟`;
-    }
     const hours = Math.floor(minutes / 60);
     const remains = minutes % 60;
-    if (remains === 0) {
+    if (remains === 0)
         return `${hours}小时`;
-    }
     return `${hours}小时${remains}分钟`;
 }
-// Resolve delivery target from session
-// If session contains group:groupCode or direct:userId, return the corresponding target
-// Otherwise return null
+// ============================================================================
+// Session resolution
+// ============================================================================
 function resolveToFromSession(ctx) {
-    const sessionKey = ctx.sessionKey ?? "";
-    const groupPrefix = "yuanbao:group:";
-    const directPrefix = "yuanbao:direct:";
+    const sessionKey = ctx.sessionKey ?? '';
+    const groupPrefix = 'yuanbao:group:';
+    const directPrefix = 'yuanbao:direct:';
     const groupIdx = sessionKey.indexOf(groupPrefix);
     if (groupIdx !== -1) {
         const groupCode = sessionKey.slice(groupIdx + groupPrefix.length).trim();
-        if (groupCode) {
+        if (groupCode)
             return `group:${groupCode}`;
-        }
     }
     const directIdx = sessionKey.indexOf(directPrefix);
     if (directIdx !== -1) {
-        // Cannot parse userID from sessionKey because sessionKey lowercases it, while userID is mixed-case
+        // sessionKey lowercases userId, so use requesterSenderId instead
         const userId = ctx.requesterSenderId;
-        if (userId) {
+        if (userId)
             return `direct:${userId}`;
-        }
     }
     return null;
 }
-// Build SubAgent execution prompt
+// ============================================================================
+// Prompt & name generation
+// ============================================================================
 function buildReminderPrompt(content, intent) {
-    if (intent === "task") {
+    if (intent === 'task') {
         return TASK_AGENT_PROMPT_TEMPLATE(content);
     }
     return REMIND_AGENT_PROMPT_TEMPLATE(content);
 }
-// Generate job name
-function generateJobName(content, intent) {
+function generateJobName(content) {
     const text = content.trim();
-    const short = text.length > 20 ? `${text.slice(0, 20)}...` : text;
-    return `${intent === "task" ? "任务" : "提醒"}: ${short}`;
+    return text.length > 20 ? `${text.slice(0, 20)}...` : text;
 }
-/**
- * Build cron params for a one-time (relative time) reminder task.
- *
- * Encapsulates one-time task scheduling strategy (kind=at, delete after run)
- * to prevent callers from missing critical fields.
- */
-function buildOnceCronParams(params, delayMs, to, intent) {
+/** Resolves shared fields for a one-time job. */
+function resolveOnceBase(params, time, intent) {
     const content = params.content;
-    const at = `${Math.max(1, Math.round(delayMs / 1000))}s`;
     return {
-        action: "add",
-        name: params.name || generateJobName(content, intent),
-        at,
-        session: "isolated",
-        deleteAfterRun: true,
+        name: params.name || generateJobName(content),
+        atMs: time.type === 'absolute' ? time.atMs : Date.now() + time.delayMs,
+        atStr: time.type === 'absolute' ? time.iso : `${Math.max(1, Math.round(time.delayMs / 1000))}s`,
         message: buildReminderPrompt(content, intent),
-        channel: "yuanbao",
-        to,
     };
 }
-/**
- * Build cron params for a recurring (cron expression) reminder task.
- *
- * Separated from one-time tasks to ensure recurring-specific fields (timezone, expression)
- * are always complete, reducing LLM parameter assembly ambiguity.
- */
-function buildCronParams(params, to, intent) {
+/** Resolves shared fields for a recurring (cron) job. */
+function resolveCronBase(params, intent) {
     const content = params.content;
     return {
-        action: "add",
-        name: params.name || generateJobName(content, intent),
-        cron: params.time.trim(),
-        tz: params.timezone || "Asia/Shanghai",
-        session: "isolated",
-        deleteAfterRun: false,
+        name: params.name || generateJobName(content),
+        expr: params.time.trim(),
+        tz: params.timezone || 'Asia/Shanghai',
         message: buildReminderPrompt(content, intent),
-        channel: "yuanbao",
-        to,
     };
 }
+// ============================================================================
+// Gateway mode: job builders
+// ============================================================================
+/** Builds a Gateway job config for a one-time job. */
+function buildOnceJob(params, time, to, accountId, intent) {
+    const { name, atMs, message } = resolveOnceBase(params, time, intent);
+    return {
+        name,
+        schedule: { kind: 'at', atMs },
+        sessionTarget: 'isolated',
+        wakeMode: 'now',
+        deleteAfterRun: true,
+        payload: { kind: 'agentTurn', message },
+        delivery: { mode: 'announce', channel: 'yuanbao', to, accountId },
+    };
+}
+/** Builds a Gateway job config for a recurring (cron) job. */
+function buildCronJob(params, to, accountId, intent) {
+    const { name, expr, tz, message } = resolveCronBase(params, intent);
+    return {
+        name,
+        schedule: { kind: 'cron', expr, tz },
+        sessionTarget: 'isolated',
+        wakeMode: 'now',
+        payload: { kind: 'agentTurn', message },
+        delivery: { mode: 'announce', channel: 'yuanbao', to, accountId },
+    };
+}
+// ============================================================================
+// CLI mode: argv builders
+// ============================================================================
+/** Builds CLI argv for `openclaw cron add --at ...` (one-time job). */
+function buildOnceCliArgs(params, time, to, accountId, intent) {
+    const { name, atStr, message } = resolveOnceBase(params, time, intent);
+    const argv = [
+        'openclaw', 'cron', 'add',
+        '--name', name,
+        '--at', atStr,
+        '--message', message,
+        '--session', 'isolated',
+        '--delete-after-run',
+        '--announce',
+        '--channel', 'yuanbao',
+        '--to', to,
+        '--json',
+    ];
+    if (accountId)
+        argv.push('--account', accountId);
+    return argv;
+}
+/** Builds CLI argv for `openclaw cron add --cron ...` (recurring job). */
+function buildCronCliArgs(params, to, accountId, intent) {
+    const { name, expr, tz, message } = resolveCronBase(params, intent);
+    const argv = [
+        'openclaw', 'cron', 'add',
+        '--name', name,
+        '--cron', expr,
+        '--tz', tz,
+        '--message', message,
+        '--session', 'isolated',
+        '--announce',
+        '--channel', 'yuanbao',
+        '--to', to,
+        '--json',
+    ];
+    if (accountId)
+        argv.push('--account', accountId);
+    return argv;
+}
+// ============================================================================
+// Legacy mode: cron params builders (used by executeLegacy)
+// ============================================================================
+/** Builds Legacy cronToolParams for a one-time job. */
+function buildOnceLegacyParams(params, time, to, intent) {
+    const { name, atStr, message } = resolveOnceBase(params, time, intent);
+    return { action: 'add', name, at: atStr, session: 'isolated', deleteAfterRun: true, message, channel: 'yuanbao', to };
+}
+/** Builds Legacy cronToolParams for a recurring (cron) job. */
+function buildCronLegacyParams(params, to, intent) {
+    const { name, expr, tz, message } = resolveCronBase(params, intent);
+    return { action: 'add', name, cron: expr, tz, session: 'isolated', deleteAfterRun: false, message, channel: 'yuanbao', to };
+}
+// ============================================================================
+// Result filtering & error formatting
+// ============================================================================
+function filterJobsByTarget(cronResult, to) {
+    let jobs;
+    if (Array.isArray(cronResult)) {
+        jobs = cronResult;
+    }
+    else if (cronResult && typeof cronResult === 'object') {
+        const r = cronResult;
+        jobs = Array.isArray(r.jobs) ? r.jobs : [];
+    }
+    else {
+        jobs = [];
+    }
+    return jobs.filter((job) => {
+        const j = job;
+        const delivery = (j.delivery ?? j.job?.delivery);
+        if (delivery?.channel !== 'yuanbao')
+            return false;
+        return !to || delivery?.to === to;
+    });
+}
+function formatTimeLabel(time, intent) {
+    if (time.type === 'absolute') {
+        const d = new Date(time.atMs);
+        const hh = String(d.getHours()).padStart(2, '0');
+        const mm = String(d.getMinutes()).padStart(2, '0');
+        const label = intent === 'task' ? '执行任务' : '提醒';
+        return `${d.getMonth() + 1}/${d.getDate()} ${hh}:${mm} ${label}`;
+    }
+    const suffix = intent === 'task' ? '后执行任务' : '后提醒';
+    return `${formatDelay(time.delayMs)}${suffix}`;
+}
+function formatSchedulerError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Shared parameter validation
+// ============================================================================
+function validateAddParams(p, resolvedTo) {
+    if (!p.content?.trim())
+        return { error: 'action=add 时 content 为必填。' };
+    if (!p.time?.trim())
+        return { error: 'action=add 时 time 为必填。示例：5m / 1h30m / 0 8 * * *' };
+    if (!resolvedTo)
+        return { error: '无法确定投递目标。请确保在元宝会话中发起请求。' };
+    return null;
+}
+function validateRemoveParams(p) {
+    if (!p.jobId?.trim())
+        return { error: 'action=remove 时 jobId 为必填，请先调用 action=list 获取任务 ID。' };
+    return null;
+}
+function parseAndValidateTime(time) {
+    const atMs = parseAbsoluteTime(time);
+    if (atMs !== null) {
+        if (atMs - Date.now() < 30_000)
+            return { error: '提醒时间不能少于 30 秒。' };
+        return { timeSpec: { type: 'absolute', atMs, iso: new Date(atMs).toISOString() } };
+    }
+    const delayMs = parseRelativeTime(time);
+    if (!delayMs || delayMs <= 0) {
+        return { error: `无法解析时间 "${time}"。支持 ISO 时间（如 2026-04-29T14:00:00Z）、相对时间（5m/1h/1h30m/2d）或 cron 表达式（如 0 8 * * *）。` };
+    }
+    if (delayMs < 30_000)
+        return { error: '提醒时间不能少于 30 秒。' };
+    return { timeSpec: { type: 'relative', delayMs } };
+}
+// ============================================================================
+// Gateway execute implementation
+// ============================================================================
+async function executeGateway(gatewayTool, p, resolvedTo, accountId) {
+    switch (p.action) {
+        case 'list': {
+            try {
+                const cronResult = await gatewayTool('cron.list', { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS }, {});
+                const filtered = filterJobsByTarget(cronResult, resolvedTo);
+                return json({ status: 'ok', action: 'list', _via: 'gateway', jobs: filtered });
+            }
+            catch (error) {
+                return json({ error: `查询定时任务失败: ${formatSchedulerError(error)}` });
+            }
+        }
+        case 'remove': {
+            const err = validateRemoveParams(p);
+            if (err)
+                return json(err);
+            try {
+                const cronResult = await gatewayTool('cron.remove', { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS }, { jobId: p.jobId.trim() });
+                return json({ status: 'ok', action: 'remove', _via: 'gateway', cronResult });
+            }
+            catch (error) {
+                return json({ error: `删除定时任务失败: ${formatSchedulerError(error)}` });
+            }
+        }
+        case 'add': {
+            const addErr = validateAddParams(p, resolvedTo);
+            if (addErr)
+                return json(addErr);
+            const intent = p.intent ?? 'remind';
+            if (isCronExpression(p.time)) {
+                const job = buildCronJob({ ...p, content: p.content.trim() }, resolvedTo, accountId, intent);
+                try {
+                    const cronResult = await gatewayTool('cron.add', { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS }, { job });
+                    const typeLabel = intent === 'task' ? '循环任务' : '周期提醒';
+                    return json({
+                        status: 'ok',
+                        action: 'add',
+                        _via: 'gateway',
+                        summary: `${typeLabel}: "${p.content.trim()}" (${p.time.trim()}, tz=${p.timezone || 'Asia/Shanghai'})`,
+                        cronResult,
+                    });
+                }
+                catch (error) {
+                    return json({ error: `创建周期任务失败: ${formatSchedulerError(error)}` });
+                }
+            }
+            const timeResult = parseAndValidateTime(p.time);
+            if ('error' in timeResult)
+                return json(timeResult);
+            const job = buildOnceJob({ ...p, content: p.content.trim() }, timeResult.timeSpec, resolvedTo, accountId, intent);
+            try {
+                const cronResult = await gatewayTool('cron.add', { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS }, { job });
+                return json({
+                    status: 'ok',
+                    action: 'add',
+                    _via: 'gateway',
+                    summary: `${formatTimeLabel(timeResult.timeSpec, intent)}: "${p.content.trim()}"`,
+                    cronResult,
+                });
+            }
+            catch (error) {
+                return json({ error: `创建定时任务失败: ${formatSchedulerError(error)}` });
+            }
+        }
+        default:
+            return json({ error: `不支持的 action: ${String(p.action)}。可选值: add/list/remove。` });
+    }
+}
+// ============================================================================
+// CLI execute implementation
+// Returns null on command failure; validation errors return json directly (no fallback).
+// ============================================================================
 /**
- * Create the `yuanbao_remind` tool definition.
- *
- * Standardizes natural language "reminder/task" requests into cron-executable params,
- * guiding the model to complete structured scheduling before replying to the user.
- * The execute callback handles add/list/remove branches with centralized validation,
- * target resolution, param building, and error messaging.
+ * CLI execution tier. Returns null on command failure to trigger Legacy fallback.
  */
+async function executeCli(runner, p, resolvedTo, accountId) {
+    switch (p.action) {
+        case 'list': {
+            try {
+                const result = await runner({ argv: ['openclaw', 'cron', 'list', '--json'], timeoutMs: DEFAULT_CLI_TIMEOUT_MS });
+                if (result.code !== 0)
+                    return null;
+                const parsed = tryParseJson(result.stdout);
+                if (parsed) {
+                    const filtered = filterJobsByTarget(parsed, resolvedTo);
+                    return json({ status: 'ok', action: 'list', _via: 'cli', jobs: filtered });
+                }
+                return json({ status: 'ok', action: 'list', _via: 'cli', raw: result.stdout.trim() });
+            }
+            catch {
+                return null;
+            }
+        }
+        case 'remove': {
+            const err = validateRemoveParams(p);
+            if (err)
+                return json(err);
+            try {
+                const result = await runner({
+                    argv: ['openclaw', 'cron', 'rm', p.jobId.trim(), '--json'],
+                    timeoutMs: DEFAULT_CLI_TIMEOUT_MS,
+                });
+                if (result.code !== 0)
+                    return null;
+                const parsed = tryParseJson(result.stdout);
+                return json({ status: 'ok', action: 'remove', _via: 'cli', cronResult: parsed ?? result.stdout.trim() });
+            }
+            catch {
+                return null;
+            }
+        }
+        case 'add': {
+            const addErr = validateAddParams(p, resolvedTo);
+            if (addErr)
+                return json(addErr);
+            const intent = p.intent ?? 'remind';
+            let argv;
+            let summary;
+            if (isCronExpression(p.time)) {
+                argv = buildCronCliArgs({ ...p, content: p.content.trim() }, resolvedTo, accountId, intent);
+                const typeLabel = intent === 'task' ? '循环任务' : '周期提醒';
+                summary = `${typeLabel}: "${p.content.trim()}" (${p.time.trim()}, tz=${p.timezone || 'Asia/Shanghai'})`;
+            }
+            else {
+                const timeResult = parseAndValidateTime(p.time);
+                if ('error' in timeResult)
+                    return json(timeResult);
+                argv = buildOnceCliArgs({ ...p, content: p.content.trim() }, timeResult.timeSpec, resolvedTo, accountId, intent);
+                summary = `${formatTimeLabel(timeResult.timeSpec, intent)}: "${p.content.trim()}"`;
+            }
+            try {
+                const result = await runner({ argv, timeoutMs: DEFAULT_CLI_TIMEOUT_MS });
+                if (result.code !== 0)
+                    return null;
+                const parsed = tryParseJson(result.stdout);
+                return json({ status: 'ok', action: 'add', _via: 'cli', summary, cronResult: parsed ?? result.stdout.trim() });
+            }
+            catch {
+                return null;
+            }
+        }
+        default:
+            return json({ error: `不支持的 action: ${String(p.action)}。可选值: add/list/remove。` });
+    }
+}
+// ============================================================================
+// Legacy execute implementation
+// ============================================================================
+/** Returns PENDING_CRON_CALL to guide the model to invoke the cron tool. */
+function executeLegacy(p, resolvedTo) {
+    switch (p.action) {
+        case 'list':
+            return json({
+                status: 'PENDING_CRON_CALL',
+                _via: 'legacy',
+                completed: false,
+                next_step: LEGACY_LIST_NEXT_STEP,
+                cronToolParams: { action: 'list' },
+                filter: { to: resolvedTo },
+            });
+        case 'remove': {
+            const err = validateRemoveParams(p);
+            if (err)
+                return json(err);
+            return json({
+                status: 'PENDING_CRON_CALL',
+                _via: 'legacy',
+                completed: false,
+                next_step: LEGACY_REMOVE_NEXT_STEP,
+                cronToolParams: { action: 'remove', jobId: p.jobId.trim() },
+            });
+        }
+        case 'add': {
+            const addErr = validateAddParams(p, resolvedTo);
+            if (addErr)
+                return json(addErr);
+            const intent = p.intent ?? 'remind';
+            if (isCronExpression(p.time)) {
+                const cronToolParams = buildCronLegacyParams({ ...p, content: p.content.trim() }, resolvedTo, intent);
+                return json({
+                    status: 'PENDING_CRON_CALL',
+                    _via: 'legacy',
+                    completed: false,
+                    next_step: LEGACY_ADD_NEXT_STEP,
+                    cronToolParams,
+                });
+            }
+            const timeResult = parseAndValidateTime(p.time);
+            if ('error' in timeResult)
+                return json(timeResult);
+            const cronToolParams = buildOnceLegacyParams({ ...p, content: p.content.trim() }, timeResult.timeSpec, resolvedTo, intent);
+            return json({
+                status: 'PENDING_CRON_CALL',
+                _via: 'legacy',
+                completed: false,
+                next_step: LEGACY_ADD_NEXT_STEP,
+                cronToolParams,
+            });
+        }
+        default:
+            return json({ error: `不支持的 action: ${String(p.action)}。可选值: add/list/remove。` });
+    }
+}
+// ============================================================================
+// Tool definition & registration
+// ============================================================================
+/** Returns null for non-yuanbao channels. */
 function createYuanbaoRemindTool(ctx) {
-    const isYuanbaoChannel = ctx.messageChannel === "yuanbao";
-    if (!isYuanbaoChannel) {
+    const log = createLog("tools.remind");
+    if (!ctx.messageChannel?.includes('yuanbao'))
         return null;
-    }
-    // Only enable in yuanbao channel
+    const resolvedTo = resolveToFromSession(ctx);
+    const accountId = ctx.deliveryContext?.accountId ?? ctx.agentAccountId ?? '';
     return {
-        name: "yuanbao_remind",
-        label: "元宝定时任务",
-        description: YUANBAO_REMIND_TOOL_DESCRIPTION,
+        name: 'yuanbao_remind',
+        label: '元宝定时任务',
+        description: TOOL_DESCRIPTION,
         parameters: RemindSchema,
-        execute: async (_toolCallId, params) => {
+        async execute(toolCallId, params) {
+            log.debug("execute", { toolCallId });
             const p = params;
-            const resolvedTo = resolveToFromSession(ctx);
-            switch (p.action) {
-                case "list":
-                    return json({
-                        instruction: CRON_LIST_REQUIREMENT,
-                        cronParams: { action: "list" },
-                        filter: { to: resolvedTo },
-                    });
-                case "remove":
-                    if (!p.jobId?.trim()) {
-                        return json({
-                            error: "action=remove 时 jobId 为必填，请先调用 action=list 获取任务 ID。",
-                        });
-                    }
-                    return json({
-                        instruction: CRON_REMOVE_REQUIREMENT,
-                        cronParams: { action: "remove", jobId: p.jobId.trim() },
-                    });
-                case "add": {
-                    if (!p.content?.trim()) {
-                        return json({ error: "action=add 时 content 为必填。" });
-                    }
-                    if (!p.time?.trim()) {
-                        return json({ error: "action=add 时 time 为必填。示例：5m / 1h30m / 0 8 * * *" });
-                    }
-                    const intent = p.intent ?? "remind";
-                    const isCron = isCronExpression(p.time);
-                    if (!resolvedTo) {
-                        return json({
-                            error: "无法确定投递目标 to。请显式传入 to，例如 direct:<userId> 或 group:<groupCode>。",
-                        });
-                    }
-                    if (isCron) {
-                        const cronParams = buildCronParams({ ...p, content: p.content.trim() }, resolvedTo, intent);
-                        const typeLabel = intent === "task" ? "循环任务" : "周期提醒";
-                        return json({
-                            instruction: CRON_ADD_REQUIREMENT,
-                            cronParams,
-                            summary: `⏰ ${typeLabel}: "${p.content.trim()}" (${p.time.trim()}, tz=${p.timezone || "Asia/Shanghai"})`,
-                        });
-                    }
-                    const delayMs = parseRelativeTime(p.time);
-                    if (!delayMs || delayMs <= 0) {
-                        return json({
-                            error: `无法解析时间 "${p.time}"。支持相对时间（5m/1h/1h30m/2d）`
-                                + "或 cron 表达式（如 0 8 * * *）。",
-                        });
-                    }
-                    if (delayMs < 30_000) {
-                        return json({ error: "提醒时间不能少于 30 秒。" });
-                    }
-                    const cronParams = buildOnceCronParams({ ...p, content: p.content.trim() }, delayMs, resolvedTo, intent);
-                    const typeLabel = intent === "task" ? "后执行任务" : "后提醒";
-                    return json({
-                        instruction: CRON_ADD_REQUIREMENT,
-                        cronParams,
-                        summary: `⏰ ${formatDelay(delayMs)}${typeLabel}: "${p.content.trim()}"`,
-                    });
-                }
-                default:
-                    return json({ error: `不支持的 action: ${String(p.action)}。可选值: add/list/remove。` });
+            const gatewayTool = await resolveCallGatewayTool();
+            if (gatewayTool) {
+                return executeGateway(gatewayTool, p, resolvedTo, accountId);
             }
+            const runner = await resolveRunPluginCommand();
+            if (runner) {
+                const cliResult = await executeCli(runner, p, resolvedTo, accountId);
+                if (cliResult !== null)
+                    return cliResult;
+                // CLI command failed (non-zero exit or exception), fall through to Legacy
+            }
+            // Final fallback: guide the model to call cron via PENDING response
+            return executeLegacy(p, resolvedTo);
         },
     };
 }
-/**
- * Register reminder-related tools to the OpenClaw plugin API.
- *
- * Centralized registration ensures the tool is reliably enabled during the plugin lifecycle.
- */
 export function registerRemindTools(api) {
-    api.registerTool(createYuanbaoRemindTool, { optional: false });
+    const log = createLog("tools.remind");
+    log.info("register tool", { name: "yuanbao_remind", optional: false });
+    api.registerTool(createYuanbaoRemindTool, { name: "yuanbao_remind", optional: false });
 }

package/dist/src/channel-shared.d.ts

@@ -22,7 +22,7 @@ export declare const yuanbaoMeta: {
     readonly docsPath: "/plugins/community#yuanbao";
     readonly docsLabel: "yuanbao";
     readonly blurb: "Tencent Yuanbao AI assistant conversation channel";
-    readonly aliases: readonly ["yb", "tencent-yuanbao", "元宝"];
+    readonly aliases: readonly ["yb", "yuanbao", "tencent-yuanbao", "元宝"];
     readonly order: 85;
     readonly quickstartAllowFrom: true;
 };

package/dist/src/channel-shared.js

@@ -22,7 +22,7 @@ export const yuanbaoMeta = {
     docsPath: "/plugins/community#yuanbao",
     docsLabel: "yuanbao",
     blurb: "Tencent Yuanbao AI assistant conversation channel",
-    aliases: ["yb", "tencent-yuanbao", "元宝"],
+    aliases: ["yb", "yuanbao", "tencent-yuanbao", "元宝"],
     order: 85,
     quickstartAllowFrom: true,
 };

package/dist/src/infra/env.js

@@ -42,7 +42,7 @@ const assertHostVersionCompatible = (hostVersion) => {
     const constraint = getMinHostVersion();
     if (!constraint)
         return;
-    if (!semver.satisfies(hostVersion, constraint)) {
+    if (!semver.satisfies(hostVersion, constraint, { includePrerelease: true })) {
         throw new Error(`openclaw-plugin-yuanbao requires openclaw ${constraint}, but current version is ${hostVersion}. Please upgrade openclaw first.`);
     }
 };

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "openclaw-plugin-yuanbao",
-  "version": "2.13.2",
+  "version": "2.13.4",
   "name": "YuanBao",
   "description": "YuanBao channel plugin",
   "channels": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-yuanbao",
-  "version": "2.13.2",
+  "version": "2.13.4",
   "type": "module",
   "private": false,
   "description": "Tencent YuanBao intelligent bot channel plugin",