@ai-setting/roy-agent-core 1.7.65 → 1.7.67

package/dist/shared/@ai-setting/{roy-agent-core-18am1h07.js → roy-agent-core-k4ps1hxp.js}

@@ -13,7 +13,7 @@ import {
   createPerTaskGroupChatPlugin,
   extractPerTaskChatId,
   extractPerTaskChatName
-} from "./roy-agent-core-f6c0nadn.js";
+} from "./roy-agent-core-b7jbqfsy.js";
 import {
   getSharedEventStore
 } from "./roy-agent-core-na18zwj0.js";
@@ -311,6 +311,88 @@ var SELF_REMINDER_MESSAGE = `[Timer Self-Reminder]
 
 请根据分析结果，创建 1-3 个有价值的任务并执行。`;
 var TIMER_OPTIONS_KEY_GET_MANAGER = "getBackgroundTaskManager";
+var SCHEDULE_TICK_INTERVAL_MS = 30 * 1000;
+var TIMER_OPTIONS_KEY_SCHEDULE = "schedule";
+var TIMER_OPTIONS_KEY_SESSION_ID = "sessionId";
+var TIMER_OPTIONS_KEY_SKIP_WHEN_RUNNING = "skipWhenRunning";
+var TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+function isValidScheduleTime(time) {
+  return typeof time === "string" && TIME_PATTERN.test(time);
+}
+function parseSchedule(raw) {
+  if (!Array.isArray(raw))
+    return [];
+  const result = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object")
+      continue;
+    const obj = item;
+    if (!isValidScheduleTime(obj.time))
+      continue;
+    if (typeof obj.prompt !== "string" || obj.prompt.trim().length === 0)
+      continue;
+    const entry = {
+      time: obj.time,
+      prompt: obj.prompt
+    };
+    if (typeof obj.label === "string" && obj.label.length > 0) {
+      entry.label = obj.label;
+    }
+    if (typeof obj.sessionId === "string" && obj.sessionId.length > 0) {
+      entry.sessionId = obj.sessionId;
+    }
+    result.push(entry);
+  }
+  return result;
+}
+function validateScheduleConfig(config) {
+  const errors = [];
+  const options = config.options ?? {};
+  const raw = options[TIMER_OPTIONS_KEY_SCHEDULE];
+  if (raw === undefined || raw === null)
+    return errors;
+  if (!Array.isArray(raw)) {
+    errors.push("Timer schedule must be an array of { time, prompt } entries");
+    return errors;
+  }
+  if (raw.length === 0) {
+    errors.push("Timer schedule must not be empty");
+    return errors;
+  }
+  raw.forEach((item, index) => {
+    if (!item || typeof item !== "object") {
+      errors.push(`Timer schedule[${index}] must be an object`);
+      return;
+    }
+    const obj = item;
+    if (!isValidScheduleTime(obj.time)) {
+      errors.push(`Timer schedule[${index}].time must be in HH:MM format (24-hour), got: ${String(obj.time)}`);
+    }
+    if (typeof obj.prompt !== "string" || obj.prompt.trim().length === 0) {
+      errors.push(`Timer schedule[${index}].prompt is required and must be a non-empty string`);
+    }
+  });
+  const seenTimes = new Set;
+  const duplicatedTimes = new Set;
+  for (const item of raw) {
+    if (!item || typeof item !== "object")
+      continue;
+    const time = item.time;
+    if (!isValidScheduleTime(time))
+      continue;
+    if (seenTimes.has(time)) {
+      duplicatedTimes.add(time);
+    }
+    seenTimes.add(time);
+  }
+  if (duplicatedTimes.size > 0) {
+    errors.push(`Timer schedule contains duplicate time entries: ${Array.from(duplicatedTimes).join(", ")}`);
+  }
+  if (config.interval !== undefined && config.interval !== null) {
+    errors.push("Timer schedule and interval are mutually exclusive: use schedule for fixed daily times, or interval for periodic triggering");
+  }
+  return errors;
+}
 
 class TimerInstance {
   config;
@@ -318,21 +400,38 @@ class TimerInstance {
   sessionId;
   getRunningTasks;
   customPrompt;
+  schedule;
+  scheduleMode;
+  invalidScheduleWarned = false;
+  scheduleSessionId;
+  skipWhenRunning;
+  firedKeys = new Set;
+  now;
   status = "created";
   timerId;
   eventHandler;
-  constructor(config, getRunningTasks) {
+  constructor(config, getRunningTasks, now) {
     this.config = config;
-    this.interval = typeof config.interval === "number" && config.interval > 0 ? config.interval : DEFAULT_TIMER_INTERVAL_MS;
+    this.now = now ?? (() => Date.now());
+    const options = config.options ?? {};
+    const rawSchedule = options[TIMER_OPTIONS_KEY_SCHEDULE];
+    const scheduleConfigured = rawSchedule !== undefined && rawSchedule !== null;
+    this.schedule = parseSchedule(rawSchedule);
+    this.scheduleMode = scheduleConfigured;
+    const isScheduleMode = this.scheduleMode;
+    this.interval = isScheduleMode ? SCHEDULE_TICK_INTERVAL_MS : typeof config.interval === "number" && config.interval > 0 ? config.interval : DEFAULT_TIMER_INTERVAL_MS;
     this.sessionId = `timer-${config.id}-${process.pid}`;
-    const optionsPrompt = config.options?.prompt;
+    const explicitSessionId = options[TIMER_OPTIONS_KEY_SESSION_ID];
+    this.scheduleSessionId = typeof explicitSessionId === "string" && explicitSessionId.length > 0 ? explicitSessionId : `timer-${config.id}`;
+    this.skipWhenRunning = options[TIMER_OPTIONS_KEY_SKIP_WHEN_RUNNING] === true;
+    const optionsPrompt = options.prompt;
     if (typeof optionsPrompt === "string" && optionsPrompt.trim().length > 0) {
       this.customPrompt = optionsPrompt;
     }
     if (getRunningTasks) {
       this.getRunningTasks = getRunningTasks;
     } else {
-      const factory = config.options?.[TIMER_OPTIONS_KEY_GET_MANAGER];
+      const factory = options[TIMER_OPTIONS_KEY_GET_MANAGER];
       if (typeof factory === "function") {
         const manager = factory();
         this.getRunningTasks = () => manager.listTasks();
@@ -341,6 +440,9 @@ class TimerInstance {
       }
     }
   }
+  get isScheduleMode() {
+    return this.scheduleMode;
+  }
   async start() {
     if (this.status === "running")
       return;
@@ -366,6 +468,10 @@ class TimerInstance {
     this.eventHandler = undefined;
   }
   tick() {
+    if (this.isScheduleMode) {
+      this.tickSchedule();
+      return;
+    }
     let allTasks;
     try {
       allTasks = this.getRunningTasks();
@@ -380,19 +486,81 @@ class TimerInstance {
     const event = this.buildSelfReminderEvent();
     this.eventHandler?.(event);
   }
-  buildSelfReminderEvent() {
-    const timestamp = Date.now();
-    const message = this.customPrompt ?? SELF_REMINDER_MESSAGE;
+  tickSchedule() {
+    if (this.schedule.length === 0) {
+      if (!this.invalidScheduleWarned) {
+        this.invalidScheduleWarned = true;
+        console.warn(`[TimerInstance] Timer ${this.config.id} has an invalid or empty schedule configuration; ` + `no events will be fired. Check options.schedule (expected [{ time: "HH:MM", prompt: "..." }]).`);
+      }
+      return;
+    }
+    const now = new Date(this.now());
+    const hh = String(now.getHours()).padStart(2, "0");
+    const mm = String(now.getMinutes()).padStart(2, "0");
+    const currentTime = `${hh}:${mm}`;
+    const dateKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+    for (const entry of this.schedule) {
+      if (entry.time !== currentTime)
+        continue;
+      const firedKey = `${dateKey}#${entry.time}`;
+      if (this.firedKeys.has(firedKey)) {
+        continue;
+      }
+      if (this.skipWhenRunning) {
+        let hasRunning = false;
+        try {
+          const allTasks = this.getRunningTasks();
+          hasRunning = Array.isArray(allTasks) && allTasks.some((t) => t.status === "running");
+        } catch (error) {
+          console.warn(`[TimerInstance] Failed to get running tasks, skipping tick: ${error}`);
+          return;
+        }
+        if (hasRunning) {
+          continue;
+        }
+      }
+      this.firedKeys.add(firedKey);
+      this.pruneFiredKeys(dateKey);
+      const event = this.buildSelfReminderEvent(entry);
+      this.eventHandler?.(event);
+      return;
+    }
+  }
+  pruneFiredKeys(currentDateKey) {
+    if (this.firedKeys.size <= 32)
+      return;
+    for (const key of this.firedKeys) {
+      const datePart = key.split("#")[0];
+      if (datePart !== currentDateKey) {
+        this.firedKeys.delete(key);
+      }
+    }
+  }
+  buildSelfReminderEvent(entry) {
+    const timestamp = this.now();
+    const message = entry?.prompt ?? this.customPrompt ?? SELF_REMINDER_MESSAGE;
+    const triggerSessionId = entry !== undefined ? entry.sessionId ?? this.scheduleSessionId : undefined;
+    const metadata = {
+      source: "event-source",
+      sourceId: this.config.id,
+      sourceMessageType: "timer.selfReminder",
+      sessionId: this.sessionId
+    };
+    if (triggerSessionId !== undefined) {
+      metadata.trigger_session_id = triggerSessionId;
+      metadata.createSessionIfMissing = true;
+    }
+    if (entry?.label !== undefined) {
+      metadata.scheduleLabel = entry.label;
+    }
+    if (entry !== undefined) {
+      metadata.scheduleTime = entry.time;
+    }
     return {
       id: `es-${this.config.id}-${timestamp}-${Math.random().toString(36).slice(2, 8)}`,
       type: "event-source.event.timer",
       timestamp,
-      metadata: {
-        source: "event-source",
-        sourceId: this.config.id,
-        sourceMessageType: "timer.selfReminder",
-        sessionId: this.sessionId
-      },
+      metadata,
       payload: {
         sourceId: this.config.id,
         sourceType: "timer",
@@ -415,6 +583,9 @@ class TimerInstance {
 __legacyDecorateClassTS([
   TracedAs("timer.tick", { recordParams: false, log: false })
 ], TimerInstance.prototype, "tick", null);
+__legacyDecorateClassTS([
+  TracedAs("timer.tickSchedule", { recordParams: false, log: false })
+], TimerInstance.prototype, "tickSchedule", null);
 __legacyDecorateClassTS([
   TracedAs("timer.buildSelfReminderEvent", { recordParams: false, log: false })
 ], TimerInstance.prototype, "buildSelfReminderEvent", null);
@@ -423,7 +594,9 @@ var timerHandler = {
   validateConfig(config) {
     const errors = [];
     const { interval } = config;
-    if (interval !== undefined && interval !== null) {
+    errors.push(...validateScheduleConfig(config));
+    const hasSchedule = config.options?.[TIMER_OPTIONS_KEY_SCHEDULE] !== undefined;
+    if (!hasSchedule && interval !== undefined && interval !== null) {
       if (typeof interval !== "number" || !Number.isFinite(interval)) {
         errors.push("Timer interval must be a finite number");
       } else if (interval <= 0) {
@@ -439,7 +612,7 @@ var timerHandler = {
     return [
       {
         name: "interval",
-        description: `Timer interval in milliseconds (default: ${DEFAULT_TIMER_INTERVAL_MS} = 10 minutes)`,
+        description: `Timer interval in milliseconds (default: ${DEFAULT_TIMER_INTERVAL_MS} = 10 minutes). Mutually exclusive with schedule.`,
         required: false,
         type: "number"
       },
@@ -448,6 +621,18 @@ var timerHandler = {
         description: "Custom prompt message for SelfReminder events (replaces default message)",
         required: false,
         type: "string"
+      },
+      {
+        name: TIMER_OPTIONS_KEY_SCHEDULE,
+        description: "JSON array of { time: 'HH:MM', prompt: string, label?: string, sessionId?: string } " + "for fixed daily trigger times (e.g. 10:00 / 17:00 / 20:00). Mutually exclusive with interval.",
+        required: false,
+        type: "string"
+      },
+      {
+        name: TIMER_OPTIONS_KEY_SESSION_ID,
+        description: "Explicit session ID for timer events (schedule mode). Events are routed to this " + "session instead of the main REPL session.",
+        required: false,
+        type: "string"
       }
     ];
   }
@@ -1083,10 +1268,658 @@ var bountyCliHandler = {
   }
 };
 
+// src/env/event-source/command-registry.ts
+init_logger();
+
+// src/env/event-source/fallback-model-command.ts
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { modify, applyEdits, parse as parseJSONCInternal } from "jsonc-parser";
+
+// src/env/event-source/command-cards.ts
+var THEME = {
+  primary: "blue",
+  success: "green",
+  warning: "orange"
+};
+var FALLBACK_MODEL_ACTION_NS = "fbmodel";
+var FALLBACK_MODEL_ACTIONS = {
+  add: `${FALLBACK_MODEL_ACTION_NS}_add`,
+  up: `${FALLBACK_MODEL_ACTION_NS}_up`,
+  down: `${FALLBACK_MODEL_ACTION_NS}_down`
+};
+function isFallbackModelCard(card) {
+  if (!card || typeof card !== "object")
+    return false;
+  const c = card;
+  const header = c.header;
+  const title = header?.title;
+  return title?.content === "⚙️ Fallback Model 列表";
+}
+function renderTextCard(title, content) {
+  return {
+    schema: "2.0",
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: "plain_text", content: title },
+      template: THEME.primary
+    },
+    body: {
+      direction: "vertical",
+      elements: [
+        {
+          tag: "markdown",
+          content
+        }
+      ]
+    }
+  };
+}
+function renderFallbackModelCard(list, primaryModel) {
+  const elements = [];
+  if (primaryModel) {
+    elements.push({
+      tag: "markdown",
+      content: `**主模型**：\`${primaryModel}\``
+    });
+  }
+  if (list.length === 0) {
+    elements.push({
+      tag: "markdown",
+      content: "**fallback 列表**：⚠️ 未配置。主模型失败时不会自动降级。"
+    });
+  } else {
+    elements.push({
+      tag: "markdown",
+      content: "**fallback 列表**（顺序 = 优先级，1 最高）："
+    });
+    list.forEach((model, i) => {
+      const row = [
+        {
+          tag: "markdown",
+          content: `${i + 1}. \`${model}\``
+        }
+      ];
+      if (i > 0) {
+        row.push({
+          tag: "button",
+          text: { tag: "plain_text", content: "↑" },
+          type: "default",
+          size: "small",
+          behaviors: [
+            {
+              type: "callback",
+              value: {
+                action: FALLBACK_MODEL_ACTIONS.up,
+                index: i + 1,
+                model
+              }
+            }
+          ]
+        });
+      }
+      if (i < list.length - 1) {
+        row.push({
+          tag: "button",
+          text: { tag: "plain_text", content: "↓" },
+          type: "default",
+          size: "small",
+          behaviors: [
+            {
+              type: "callback",
+              value: {
+                action: FALLBACK_MODEL_ACTIONS.down,
+                index: i + 1,
+                model
+              }
+            }
+          ]
+        });
+      }
+      elements.push({
+        tag: "column_set",
+        horizontal_spacing: "small",
+        columns: [
+          { tag: "column", width: "weighted", weight: 1, elements: row }
+        ]
+      });
+    });
+  }
+  elements.push({ tag: "hr" });
+  elements.push({
+    tag: "form",
+    name: "fbmodel_form",
+    elements: [
+      {
+        tag: "input",
+        name: "fbmodel_model",
+        placeholder: { tag: "plain_text", content: "provider/model，如 tong/GLM-5.3-Flash" },
+        required: true
+      },
+      {
+        tag: "button",
+        text: { tag: "plain_text", content: "新增到 fallback 列表" },
+        type: "primary_filled",
+        form_action_type: "submit",
+        name: FALLBACK_MODEL_ACTIONS.add
+      }
+    ]
+  });
+  elements.push({ tag: "hr" });
+  elements.push({
+    tag: "markdown",
+    content: [
+      "**文本指令**（按钮不可用时用这个）：",
+      "- 新增：`##command##: fallback-model add <provider/model>`",
+      "- 删除：`##command##: fallback-model remove <序号>`",
+      "- 调优先级：`##command##: fallback-model reorder <原序号> <新序号>`",
+      "- 查看：`##command##: list model`"
+    ].join(`
+`)
+  });
+  return {
+    schema: "2.0",
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: "plain_text", content: "⚙️ Fallback Model 列表" },
+      template: THEME.primary
+    },
+    body: {
+      direction: "vertical",
+      elements
+    }
+  };
+}
+
+// src/env/event-source/fallback-model-command.ts
+var DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".roy-agent", "config.jsonc");
+function readConfigFile(configPath) {
+  if (!fs.existsSync(configPath))
+    return {};
+  const text = fs.readFileSync(configPath, "utf-8");
+  const errors = [];
+  const parsed = parseJSONCInternal(text, errors, {
+    allowTrailingComma: true,
+    disallowComments: false
+  });
+  if (errors.length > 0 && parsed === undefined) {
+    throw new Error(`config.jsonc 解析失败：${configPath}`);
+  }
+  return parsed ?? {};
+}
+function assertObjectParent(configPath, parsed, dotPath) {
+  let cursor = parsed;
+  for (let i = 0;i < dotPath.length - 1; i++) {
+    if (cursor === undefined || cursor === null) {
+      return;
+    }
+    if (typeof cursor !== "object" || Array.isArray(cursor)) {
+      throw new Error(`config.jsonc 的「${dotPath.slice(0, i + 1).join(".")}」不是对象，` + `无法写入 ${dotPath.join(".")}（${configPath}）`);
+    }
+    cursor = cursor[dotPath[i]];
+  }
+  if (cursor === undefined)
+    return;
+  if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) {
+    throw new Error(`config.jsonc 的「${dotPath.slice(0, -1).join(".")}」不是对象，` + `无法写入 ${dotPath.join(".")}（${configPath}）`);
+  }
+}
+function writeConfigPath(configPath, dotPath, value) {
+  let text;
+  let parsedForCheck = {};
+  if (fs.existsSync(configPath)) {
+    text = fs.readFileSync(configPath, "utf-8");
+    const errors = [];
+    const parsed = parseJSONCInternal(text, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+      throw new Error(`config.jsonc 已损坏（解析失败），拒绝写入：${configPath}`);
+    }
+    parsedForCheck = parsed ?? {};
+  } else {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    text = "{}";
+  }
+  assertObjectParent(configPath, parsedForCheck, dotPath);
+  const edits = modify(text, dotPath, value, {
+    formattingOptions: {
+      tabSize: 2,
+      insertSpaces: true
+    }
+  });
+  const result = applyEdits(text, edits);
+  fs.writeFileSync(configPath, result, "utf-8");
+}
+function readFallbackModelList(configPath) {
+  const config = readConfigFile(configPath);
+  const llm = config.llm ?? {};
+  const arr = llm.fallbackModels;
+  if (Array.isArray(arr)) {
+    return arr.map((m) => typeof m === "string" ? m.trim() : "");
+  }
+  const single = llm.fallbackModel;
+  if (typeof single === "string" && single.trim() !== "") {
+    return [single.trim()];
+  }
+  return [];
+}
+function readRawFallbackModelArray(configPath) {
+  const config = readConfigFile(configPath);
+  const llm = config.llm ?? {};
+  const arr = llm.fallbackModels;
+  if (Array.isArray(arr))
+    return [...arr];
+  const single = llm.fallbackModel;
+  if (typeof single === "string" && single.trim() !== "") {
+    return [single.trim()];
+  }
+  return [];
+}
+function writeFallbackModelList(configPath, list) {
+  const raw = readRawFallbackModelArray(configPath);
+  const next = raw.slice(0, list.length);
+  for (let i = 0;i < list.length; i++) {
+    const existing = next[i];
+    if (typeof existing !== "string" && existing !== undefined)
+      continue;
+    next[i] = list[i];
+  }
+  while (next.length < list.length)
+    next.push(list[next.length]);
+  writeConfigPath(configPath, ["llm", "fallbackModels"], next);
+}
+var USAGE = [
+  "用法：##command##: fallback-model <子命令> [参数]",
+  "",
+  "子命令：",
+  "  list                     查看兜底模型列表（顺序 = 优先级）",
+  "  add <provider/model>     新增到列表末尾（最低优先级）",
+  "  remove <序号>            按序号删除（1-based）",
+  "  reorder <原序号> <新序号> 调整优先级（1-based）",
+  "  move <模型标识> <up|down>  按模型标识上下移动（卡片按钮用）"
+].join(`
+`);
+function effectiveList(configPath) {
+  return readFallbackModelList(configPath).filter((m) => m !== "");
+}
+function rawWithIndexMap(configPath) {
+  const raw = readRawFallbackModelArray(configPath);
+  const map = [];
+  raw.forEach((m, i) => {
+    if (typeof m === "string" && m.trim() !== "")
+      map.push(i);
+  });
+  return { raw, map };
+}
+function moveInRaw(raw, map, fromEff, toEff) {
+  const rawFrom = map[fromEff];
+  const [moved] = raw.splice(rawFrom, 1);
+  const rawTo = map[toEff] > rawFrom ? map[toEff] - 1 : map[toEff];
+  raw.splice(rawTo, 0, moved);
+}
+function dualResult(text, configPath) {
+  const list = effectiveList(configPath);
+  const config = readConfigFile(configPath);
+  const llm = config.llm ?? {};
+  const primary = typeof llm.defaultModel === "string" ? llm.defaultModel : undefined;
+  return {
+    ok: true,
+    output: {
+      kind: "card",
+      text,
+      card: renderFallbackModelCard(list, primary)
+    }
+  };
+}
+function parsePositiveIndex(raw) {
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1)
+    return null;
+  return n;
+}
+async function executeFallbackModel(ctx) {
+  const configPath = ctx.configPath ?? DEFAULT_CONFIG_PATH;
+  const [sub, ...rest] = ctx.args;
+  switch (sub) {
+    case "list":
+    case "show": {
+      const list = effectiveList(configPath);
+      const config = readConfigFile(configPath);
+      const llm = config.llm ?? {};
+      const primary = typeof llm.defaultModel === "string" ? llm.defaultModel : undefined;
+      const text = list.length ? `\uD83D\uDCCB 兜底模型列表（顺序 = 优先级，1 最高）：
+${list.map((m, i) => `   ${i + 1}. ${m}`).join(`
+`)}` : "⚠️ 兜底模型列表未配置（主模型失败时不会自动降级）";
+      return {
+        ok: true,
+        output: {
+          kind: "card",
+          text,
+          card: renderFallbackModelCard(list, primary)
+        }
+      };
+    }
+    case "add": {
+      const model = rest[0]?.trim();
+      if (!model) {
+        return { ok: false, error: `用法：##command##: fallback-model add <provider/model>
+${USAGE}` };
+      }
+      const list = effectiveList(configPath);
+      if (list.some((m) => m === model)) {
+        return { ok: false, error: `「${model}」已在 fallback 列表中（重复添加被拒绝）` };
+      }
+      const raw = readRawFallbackModelArray(configPath);
+      const next = [...raw, model];
+      writeConfigPath(configPath, ["llm", "fallbackModels"], next);
+      return dualResult(`✅ 已添加「${model}」到 fallback 列表末尾（当前 ${list.length + 1} 项：${list.join(" → ")} → ${model}）`, configPath);
+    }
+    case "remove":
+    case "rm": {
+      const idx = rest[0] !== undefined ? parsePositiveIndex(rest[0]) : null;
+      if (idx === null) {
+        return { ok: false, error: `用法：##command##: fallback-model remove <序号>（1-based）
+${USAGE}` };
+      }
+      const list = effectiveList(configPath);
+      if (idx > list.length) {
+        return {
+          ok: false,
+          error: `序号 ${idx} 越界（当前列表 ${list.length} 项：${list.map((m, i) => `${i + 1}.${m}`).join("，") || "空"}）`
+        };
+      }
+      const { raw, map } = rawWithIndexMap(configPath);
+      const rawIdx = map[idx - 1];
+      const removed = list[idx - 1];
+      raw.splice(rawIdx, 1);
+      writeConfigPath(configPath, ["llm", "fallbackModels"], raw);
+      return dualResult(`✅ 已删除「${removed}」（剩余 ${list.length - 1} 项${list.length > 1 ? `：${list.filter((_, i) => i !== idx - 1).join(" → ")}` : ""}）`, configPath);
+    }
+    case "move": {
+      const model = rest[0]?.trim();
+      const direction = rest[1]?.trim().toLowerCase();
+      if (!model || direction !== "up" && direction !== "down") {
+        return {
+          ok: false,
+          error: `用法：##command##: fallback-model move <模型标识> <up|down>
+${USAGE}`
+        };
+      }
+      const list = effectiveList(configPath);
+      const idx = list.findIndex((m) => m === model);
+      if (idx < 0) {
+        return {
+          ok: false,
+          error: `列表中找不到「${model}」（当前：${list.map((m, i) => `${i + 1}.${m}`).join("，") || "空"}）`
+        };
+      }
+      const targetIdx = direction === "up" ? idx - 1 : idx + 1;
+      if (targetIdx < 0 || targetIdx >= list.length) {
+        return {
+          ok: false,
+          error: `「${model}」已经在${direction === "up" ? "第 1 位" : "最后一位"}，无法再${direction === "up" ? "上移" : "下移"}`
+        };
+      }
+      const { raw, map } = rawWithIndexMap(configPath);
+      moveInRaw(raw, map, idx, targetIdx);
+      writeConfigPath(configPath, ["llm", "fallbackModels"], raw);
+      const nextOrder = effectiveList(configPath);
+      return dualResult(`✅ 已把「${model}」移到第 ${targetIdx + 1} 位（当前顺序：${nextOrder.join(" → ")}）`, configPath);
+    }
+    case "reorder":
+    case "move-index": {
+      const from = rest[0] !== undefined ? parsePositiveIndex(rest[0]) : null;
+      const to = rest[1] !== undefined ? parsePositiveIndex(rest[1]) : null;
+      if (from === null || to === null) {
+        return {
+          ok: false,
+          error: `用法：##command##: fallback-model reorder <原序号> <新序号>（1-based）
+${USAGE}`
+        };
+      }
+      const list = effectiveList(configPath);
+      if (from > list.length || to > list.length) {
+        return {
+          ok: false,
+          error: `序号越界（当前列表 ${list.length} 项：${list.map((m, i) => `${i + 1}.${m}`).join("，") || "空"}）`
+        };
+      }
+      const { raw, map } = rawWithIndexMap(configPath);
+      const moved = raw[map[from - 1]];
+      moveInRaw(raw, map, from - 1, to - 1);
+      writeConfigPath(configPath, ["llm", "fallbackModels"], raw);
+      const nextOrder = effectiveList(configPath);
+      return dualResult(`✅ 已把「${moved}」移到第 ${to} 位（当前顺序：${nextOrder.join(" → ")}）`, configPath);
+    }
+    case undefined:
+      return { ok: false, error: USAGE };
+    default:
+      return { ok: false, error: `未知子命令「${sub}」。
+${USAGE}` };
+  }
+}
+var fallbackModelCommand = {
+  name: "fallback-model",
+  description: "管理兜底模型列表（llm.fallbackModels，顺序 = 优先级）",
+  usage: "fallback-model list|add|remove|reorder [参数]",
+  execute: executeFallbackModel
+};
+var listCommand = {
+  name: "list",
+  description: "查看资源列表（list model = fallback-model list）",
+  usage: "list model",
+  execute: async (ctx) => {
+    const resource = ctx.args[0];
+    if (resource === "model") {
+      return executeFallbackModel({ ...ctx, args: ["list"] });
+    }
+    return {
+      ok: false,
+      error: `未知资源「${resource ?? "(空)"}」。可用：list model`
+    };
+  }
+};
+
+// src/env/event-source/command-registry.ts
+var logger2 = createLogger("command-registry");
+var COMMAND_PREFIX = "##command##:";
+var COMMAND_PREFIX_LOWER = COMMAND_PREFIX.toLowerCase();
+function stripLeadingMentions(text) {
+  let rest = text;
+  const atTagRe = /^\s*<at\s+user_id\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)\s*(?:\/>|>\s*<\/at\s*>|>[^<]*<\/at\s*>)/i;
+  for (;; ) {
+    const m = rest.match(atTagRe);
+    if (!m)
+      break;
+    rest = rest.slice(m[0].length);
+  }
+  const legacyAtRe = /^\s*@_(?:user_\d+|all)\b/i;
+  for (;; ) {
+    const m = rest.match(legacyAtRe);
+    if (!m)
+      break;
+    rest = rest.slice(m[0].length);
+  }
+  return rest;
+}
+function isCommandMessage(text) {
+  return stripLeadingMentions(text).trimStart().toLowerCase().startsWith(COMMAND_PREFIX_LOWER);
+}
+function extractCommandInvocation(text) {
+  const trimmed = stripLeadingMentions(text).trimStart();
+  if (!trimmed.toLowerCase().startsWith(COMMAND_PREFIX_LOWER))
+    return null;
+  const rest = trimmed.slice(COMMAND_PREFIX.length).trim();
+  if (!rest) {
+    return { subcommand: "", args: [] };
+  }
+  const tokens = rest.split(/\s+/).filter(Boolean);
+  return { subcommand: tokens[0], args: tokens.slice(1) };
+}
+
+class CommandRegistry {
+  commands = new Map;
+  register(def) {
+    if (this.commands.has(def.name)) {
+      throw new Error(`command "${def.name}" already registered`);
+    }
+    this.commands.set(def.name, def);
+  }
+  has(name) {
+    return this.commands.has(name);
+  }
+  list() {
+    return Array.from(this.commands.values());
+  }
+  async dispatch(subcommand, args, extra) {
+    if (!subcommand) {
+      return {
+        ok: false,
+        error: this.renderHelp()
+      };
+    }
+    const def = this.commands.get(subcommand);
+    if (!def) {
+      return {
+        ok: false,
+        error: `未知命令「${subcommand}」。
+${this.renderHelp()}`
+      };
+    }
+    try {
+      return await def.execute({
+        args,
+        rawText: extra?.rawText ?? "",
+        configPath: extra?.configPath
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger2.error(`[CommandRegistry] command "${subcommand}" failed: ${msg}`);
+      return { ok: false, error: `命令执行失败：${msg}` };
+    }
+  }
+  renderHelp() {
+    const lines = this.list().map((c) => `  ${c.usage.padEnd(40)} ${c.description}`);
+    return `可用命令：
+${lines.join(`
+`)}
+` + `（通过「##command##: <命令> [参数]」调用）`;
+  }
+}
+function getGlobalCommandRegistry() {
+  const g = globalThis;
+  if (!g.__royCommandRegistry) {
+    const registry = new CommandRegistry;
+    registry.register(fallbackModelCommand);
+    registry.register(listCommand);
+    g.__royCommandRegistry = registry;
+  }
+  return g.__royCommandRegistry;
+}
+async function handleCommandMessage(text, opts = {}) {
+  if (!isCommandMessage(text))
+    return null;
+  const invocation = extractCommandInvocation(text);
+  if (!invocation)
+    return null;
+  const registry = opts.registry ?? getGlobalCommandRegistry();
+  logger2.info(`[handleCommandMessage] dispatching "${invocation.subcommand}" args=${JSON.stringify(invocation.args)}`);
+  return registry.dispatch(invocation.subcommand, invocation.args, {
+    rawText: text,
+    configPath: opts.configPath
+  });
+}
+
+// src/env/event-source/command-card-action.ts
+init_logger();
+var logger3 = createLogger("command-card-action");
+function isCommandCardAction(event) {
+  const av = event.actionValue;
+  if (av && typeof av === "object") {
+    const action = av.action;
+    if (typeof action === "string" && action.startsWith(FALLBACK_MODEL_ACTION_NS)) {
+      return true;
+    }
+  }
+  if (typeof event.actionName === "string" && event.actionName.startsWith(FALLBACK_MODEL_ACTION_NS)) {
+    return true;
+  }
+  return false;
+}
+function translateCardActionToCommand(event) {
+  if (event.actionName === FALLBACK_MODEL_ACTIONS.add) {
+    const model2 = String(event.formValue?.["fbmodel_model"] ?? event.formValue?.model ?? "").trim();
+    if (!model2)
+      return null;
+    return { subcommand: "fallback-model", args: ["add", model2] };
+  }
+  const av = event.actionValue;
+  if (!av || typeof av !== "object")
+    return null;
+  const action = av.action;
+  const rawIndex = av.index;
+  if (action !== FALLBACK_MODEL_ACTIONS.up && action !== FALLBACK_MODEL_ACTIONS.down) {
+    return null;
+  }
+  const index = Number.parseInt(String(rawIndex ?? ""), 10);
+  if (!Number.isFinite(index) || index < 1)
+    return null;
+  const target = action === FALLBACK_MODEL_ACTIONS.up ? index - 1 : index + 1;
+  if (target < 1)
+    return null;
+  const model = av.model;
+  if (typeof model === "string" && model.trim() !== "") {
+    return {
+      subcommand: "fallback-model",
+      args: [
+        "move",
+        model.trim(),
+        action === FALLBACK_MODEL_ACTIONS.up ? "up" : "down"
+      ]
+    };
+  }
+  return {
+    subcommand: "fallback-model",
+    args: ["reorder", String(index), String(target)]
+  };
+}
+async function handleCommandCardAction(event, ports) {
+  const call = translateCardActionToCommand(event);
+  if (!call) {
+    return { ok: false, error: "无法识别的 command 卡片动作" };
+  }
+  const executed = `${call.subcommand} ${call.args.join(" ")}`;
+  logger3.info(`[handleCommandCardAction] 执行 ${executed}`);
+  let result;
+  try {
+    result = await ports.executeCommand(call.subcommand, call.args, {
+      configPath: ports.configPath
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger3.error(`[handleCommandCardAction] ${executed} 执行异常：${msg}`);
+    return { ok: false, executed, error: `命令执行异常：${msg}` };
+  }
+  if (!result.ok) {
+    return { ok: false, executed, error: result.error ?? "命令执行失败" };
+  }
+  const card = result.output?.card;
+  let patchError;
+  if (card && ports.patchCard && event.token) {
+    try {
+      await ports.patchCard(event.token, card, event.profile);
+    } catch (err) {
+      patchError = err.message;
+      logger3.error(`[handleCommandCardAction] patch 卡片失败：${patchError}`);
+    }
+  }
+  return { ok: true, executed, card, patchError };
+}
+
 // src/env/event-source/event-source-handlers.ts
 init_logger();
 var execAsync2 = promisify2(execSync);
-var logger2 = createLogger("lark-cli:event-source");
+var logger4 = createLogger("lark-cli:event-source");
 var CHILD_READY_TIMEOUT_MS = 5000;
 var GRACEFUL_STOP_TIMEOUT_MS = 5000;
 var CARD_ACTION_EVENT_TYPE = "card.action.trigger";
@@ -1315,8 +2148,8 @@ class LarkCliInstance {
   cardActionPorts;
   setCardActionPorts(ports) {
     this.cardActionPorts = ports;
-    if (typeof logger2 !== "undefined" && logger2?.debug) {
-      logger2.debug(`[LarkCliInstance] CardActionPorts injected: ` + `getTask=${typeof ports.getTask}, updateTaskContext=${typeof ports.updateTaskContext}, ` + `createGroupChat=${typeof ports.createGroupChat}, deleteGroupChat=${typeof ports.deleteGroupChat}, ` + `notifier=${typeof ports.notifier}`);
+    if (typeof logger4 !== "undefined" && logger4?.debug) {
+      logger4.debug(`[LarkCliInstance] CardActionPorts injected: ` + `getTask=${typeof ports.getTask}, updateTaskContext=${typeof ports.updateTaskContext}, ` + `createGroupChat=${typeof ports.createGroupChat}, deleteGroupChat=${typeof ports.deleteGroupChat}, ` + `notifier=${typeof ports.notifier}`);
     }
   }
   hasCardActionPorts() {
@@ -1343,7 +2176,7 @@ class LarkCliInstance {
     if (this.status === "running")
       return;
     if (this.starting) {
-      logger2.warn(`[LarkCliInstance] start() 已在执行中，忽略重复调用`);
+      logger4.warn(`[LarkCliInstance] start() 已在执行中，忽略重复调用`);
       return;
     }
     this.starting = true;
@@ -1373,9 +2206,9 @@ class LarkCliInstance {
     if (!consumesCardAction)
       return;
     if (this.config.eventTypes?.length && !matchEventType(CARD_ACTION_EVENT_TYPE, this.config.eventTypes)) {
-      logger2.warn(`[LarkCliInstance] eventKeys 含 ${CARD_ACTION_EVENT_TYPE}，但 eventTypes=` + `${JSON.stringify(this.config.eventTypes)} 不含它 → 卡片点击会被**静默丢弃**。` + `请把 ${CARD_ACTION_EVENT_TYPE} 加进 eventTypes，或清空 eventTypes。`);
+      logger4.warn(`[LarkCliInstance] eventKeys 含 ${CARD_ACTION_EVENT_TYPE}，但 eventTypes=` + `${JSON.stringify(this.config.eventTypes)} 不含它 → 卡片点击会被**静默丢弃**。` + `请把 ${CARD_ACTION_EVENT_TYPE} 加进 eventTypes，或清空 eventTypes。`);
     }
-    logger2.info(`[LarkCliInstance] 已监听 ${CARD_ACTION_EVENT_TYPE}。` + `⚠️ 若点击卡片无反应，先确认飞书开发者后台「事件与回调 → 回调配置」已开启该事件。`);
+    logger4.info(`[LarkCliInstance] 已监听 ${CARD_ACTION_EVENT_TYPE}。` + `⚠️ 若点击卡片无反应，先确认飞书开发者后台「事件与回调 → 回调配置」已开启该事件。`);
   }
   spawnConsumeChild(command) {
     return spawn2("exec " + command, [], {
@@ -1415,7 +2248,7 @@ class LarkCliInstance {
     const conflicts = keys.filter((k) => busy.has(k));
     if (conflicts.length > 0) {
       const profile = this.config.profile;
-      logger2.warn(`[LarkCliInstance] eventKey 已被其它 consumer 占用（lark-cli 一个 key 只允许一个 consumer）：` + `${conflicts.join(", ")}。本 event-source 启动后可能 exit 2。` + `用 \`lark-cli${profile ? ` --profile ${profile}` : ""} event status\` 查看，必要时 \`event stop\`。`);
+      logger4.warn(`[LarkCliInstance] eventKey 已被其它 consumer 占用（lark-cli 一个 key 只允许一个 consumer）：` + `${conflicts.join(", ")}。本 event-source 启动后可能 exit 2。` + `用 \`lark-cli${profile ? ` --profile ${profile}` : ""} event status\` 查看，必要时 \`event stop\`。`);
     }
   }
   async probeBusyEventKeys() {
@@ -1466,16 +2299,16 @@ class LarkCliInstance {
     });
     const handleExit = (code, source) => {
       if (code !== 0 && code !== null) {
-        logger2.warn(`[LarkCliInstance] consume 子进程异常退出 code=${code} (${source}) cmd="${command}"`);
+        logger4.warn(`[LarkCliInstance] consume 子进程异常退出 code=${code} (${source}) cmd="${command}"`);
         this.status = "error";
       } else {
-        logger2.info(`[LarkCliInstance] consume 子进程已退出 code=${code} (${source}) cmd="${command}"`);
+        logger4.info(`[LarkCliInstance] consume 子进程已退出 code=${code} (${source}) cmd="${command}"`);
       }
       settle();
       queueMicrotask(() => {
         if (this.children.length > 0 && this.children.every((c) => !isChildAlive(c))) {
           if (this.status !== "error") {
-            logger2.warn(`[LarkCliInstance] 所有 consume 子进程都已退出，状态从 running 改为 stopped`);
+            logger4.warn(`[LarkCliInstance] 所有 consume 子进程都已退出，状态从 running 改为 stopped`);
             this.status = "stopped";
           }
         }
@@ -1484,12 +2317,12 @@ class LarkCliInstance {
     child.on("exit", (code) => handleExit(code, "exit"));
     child.on("close", (code) => handleExit(code, "close"));
     child.on("error", (error) => {
-      logger2.error(`[LarkCliInstance] consume 子进程 error: ${error.message}`);
+      logger4.error(`[LarkCliInstance] consume 子进程 error: ${error.message}`);
       this.status = "error";
       settle();
     });
     const timer = setTimeout(() => {
-      logger2.warn(`[LarkCliInstance] consume 子进程 ${CHILD_READY_TIMEOUT_MS}ms 内未见 ready marker: cmd="${command}"`);
+      logger4.warn(`[LarkCliInstance] consume 子进程 ${CHILD_READY_TIMEOUT_MS}ms 内未见 ready marker: cmd="${command}"`);
       settle();
     }, CHILD_READY_TIMEOUT_MS);
     ready.then(() => clearTimeout(timer));
@@ -1512,7 +2345,7 @@ class LarkCliInstance {
       try {
         child.kill("SIGTERM");
       } catch (error) {
-        logger2.warn(`[LarkCliInstance] Error sending SIGTERM to ${child.pid}: ${error}`);
+        logger4.warn(`[LarkCliInstance] Error sending SIGTERM to ${child.pid}: ${error}`);
       }
     }
     const allExited = Promise.all(children.map((child) => new Promise((resolve) => {
@@ -1567,12 +2400,12 @@ class LarkCliInstance {
   }
   wireCardActionPorts() {
     if (this.cardActionPorts) {
-      logger2.debug("[LarkCliInstance] cardActionPorts 已由外部注入，跳过默认 cross-wire");
+      logger4.debug("[LarkCliInstance] cardActionPorts 已由外部注入，跳过默认 cross-wire");
       return;
     }
     const taskComponent = this.environment?.getComponent?.("task");
     if (!taskComponent?.getTask || !taskComponent?.updateTask) {
-      logger2.debug(`[LarkCliInstance] card.action.trigger 端口未注入：taskComponent 不可用` + `（getTask=${typeof taskComponent?.getTask}, updateTask=${typeof taskComponent?.updateTask}）。` + `卡片按钮点击会被跳过。`);
+      logger4.debug(`[LarkCliInstance] card.action.trigger 端口未注入：taskComponent 不可用` + `（getTask=${typeof taskComponent?.getTask}, updateTask=${typeof taskComponent?.updateTask}）。` + `卡片按钮点击会被跳过。`);
       return;
     }
     const sharedNotifier = this.pluginInstances.get("LarkCliTaskNotifyPlugin")?.cardNotifier ?? this.pluginInstances.get("PerTaskGroupChatPlugin")?.cardNotifier;
@@ -1601,7 +2434,7 @@ class LarkCliInstance {
       deleteGroupChat: (chatId, profile) => deleteGroupChatViaLarkCli(chatId, profile),
       notifier: sharedNotifier ?? new LarkCardPatchNotifier
     });
-    logger2.info(`[LarkCliInstance] card.action.trigger 端口已注入` + `（notifier ${sharedNotifier ? "复用插件共享实例" : "新建实例"}）`);
+    logger4.info(`[LarkCliInstance] card.action.trigger 端口已注入` + `（notifier ${sharedNotifier ? "复用插件共享实例" : "新建实例"}）`);
   }
   getPluginHookPoints(plugin) {
     if (Array.isArray(plugin.hooks)) {
@@ -1799,7 +2632,7 @@ class LarkCliInstance {
       }
       return null;
     } catch (err) {
-      logger2.warn(`[LarkCliInstance] resolveChatTaskBinding failed for chatId=${chatId}: ${err}. ` + `群消息将不会注入 parentTaskId。`);
+      logger4.warn(`[LarkCliInstance] resolveChatTaskBinding failed for chatId=${chatId}: ${err}. ` + `群消息将不会注入 parentTaskId。`);
       return null;
     }
   }
@@ -1821,7 +2654,7 @@ class LarkCliInstance {
   processStreamWith(data, buffer, opts = {}) {
     buffer.value += data;
     if (buffer.value.length > 2 * 1024 * 1024) {
-      logger2.warn(`[LarkCliInstance] stream 行缓冲超过 2MB 仍无换行，丢弃（疑似非 NDJSON 输出）`);
+      logger4.warn(`[LarkCliInstance] stream 行缓冲超过 2MB 仍无换行，丢弃（疑似非 NDJSON 输出）`);
       buffer.value = "";
       return;
     }
@@ -1857,12 +2690,12 @@ class LarkCliInstance {
       const now = Date.now();
       const lastShared = LarkCliInstance.SHARED_SEEN.get(dedupKey);
       if (lastShared !== undefined && now - lastShared < LarkCliInstance.SHARED_MSG_TTL_MS) {
-        logger2.warn(`[LarkCliInstance] duplicate lark-cli event suppressed across instances (event_id=${dedupKey}, ` + `lastSeen=${now - lastShared}ms ago). ` + `Task #4137: SHARED_SEEN 跨实例去重。`);
+        logger4.warn(`[LarkCliInstance] duplicate lark-cli event suppressed across instances (event_id=${dedupKey}, ` + `lastSeen=${now - lastShared}ms ago). ` + `Task #4137: SHARED_SEEN 跨实例去重。`);
         return;
       }
       const last = this.recentEventIds.get(dedupKey);
       if (last !== undefined && now - last < this.DEDUP_WINDOW_MS) {
-        logger2.warn(`[LarkCliInstance] duplicate lark-cli event suppressed (event_id=${dedupKey}, ` + `lastSeen=${now - last}ms ago). ` + `Task #3977/3978: 防止同一飞书事件触发两次任务创建。`);
+        logger4.warn(`[LarkCliInstance] duplicate lark-cli event suppressed (event_id=${dedupKey}, ` + `lastSeen=${now - last}ms ago). ` + `Task #3977/3978: 防止同一飞书事件触发两次任务创建。`);
         return;
       }
       LarkCliInstance.SHARED_SEEN.set(dedupKey, now);
@@ -1924,6 +2757,7 @@ class LarkCliInstance {
       };
       const { metadata, replyChannel, recommendedAction } = extractMetadata(enrichedEvent, eventType);
       failureReplyChannel = replyChannel;
+      const commandText = isCardAction ? undefined : extractCommandText(enrichedEvent);
       const parentTaskId = isCardAction ? null : await this.resolveChatTaskBinding(metadata?.chatId);
       const userId = this.extractUserId(rawEvent);
       let triggerEventId;
@@ -2021,6 +2855,10 @@ class LarkCliInstance {
           this.handleCardActionEvent(rawEvent, envReplyChannel?.profile);
           return;
         }
+        if (commandText !== undefined) {
+          this.handleCommandMessage(commandText, envReplyChannel?.profile, replyChannel?.messageId, replyChannel?.chatId);
+          return;
+        }
         this.eventHandler?.(evt);
       });
     } catch (error) {
@@ -2035,6 +2873,10 @@ class LarkCliInstance {
   async handleCardActionEvent(rawEvent, profile) {
     try {
       const event = rawEvent;
+      if (this.isCommandCardActionEvent(event)) {
+        await this.handleCommandCardActionEvent(event, profile);
+        return;
+      }
       const actionValueStr = event.action_value || "{}";
       const actionValue = JSON.parse(actionValueStr);
       const token = event.token || "";
@@ -2042,11 +2884,11 @@ class LarkCliInstance {
       const chatId = event.chat_id || "";
       const operatorId = event.operator_id?.open_id ?? event.operator_id ?? undefined;
       if (!token || !messageId || !chatId) {
-        logger2.warn(`[LarkCliInstance] handleCardActionEvent: missing token/messageId/chatId, skip`);
+        logger4.warn(`[LarkCliInstance] handleCardActionEvent: missing token/messageId/chatId, skip`);
         return;
       }
       if (!this.cardActionPorts) {
-        logger2.warn(`[LarkCliInstance] handleCardActionEvent: cardActionPorts 未注入，` + `card.action.trigger 事件被跳过。` + `调 instance.setCardActionPorts({getTask, updateTaskContext, createGroupChat, deleteGroupChat, notifier}) 注入。`);
+        logger4.warn(`[LarkCliInstance] handleCardActionEvent: cardActionPorts 未注入，` + `card.action.trigger 事件被跳过。` + `调 instance.setCardActionPorts({getTask, updateTaskContext, createGroupChat, deleteGroupChat, notifier}) 注入。`);
         return;
       }
       const result = await handleCardAction({
@@ -2061,12 +2903,179 @@ class LarkCliInstance {
         const patch = this.cardActionPorts.patchByToken ?? patchCardByLarkCli;
         await patch(token, result.cardUpdate, profile);
       } else {
-        logger2.warn(`[LarkCliInstance] handleCardActionEvent failed: ${result.error ?? "unknown"}`);
+        logger4.warn(`[LarkCliInstance] handleCardActionEvent failed: ${result.error ?? "unknown"}`);
       }
     } catch (err) {
-      logger2.error(`[LarkCliInstance] handleCardActionEvent error: ${err.message}`);
+      logger4.error(`[LarkCliInstance] handleCardActionEvent error: ${err.message}`);
     }
   }
+  isCommandCardActionEvent(event) {
+    let actionValue;
+    const raw = event.action_value;
+    if (typeof raw === "string") {
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+          actionValue = parsed;
+        }
+      } catch {
+        actionValue = undefined;
+      }
+    } else if (raw && typeof raw === "object") {
+      actionValue = raw;
+    }
+    let formValue;
+    const rawForm = event.form_value;
+    if (typeof rawForm === "string") {
+      try {
+        const parsed = JSON.parse(rawForm);
+        if (parsed && typeof parsed === "object") {
+          formValue = parsed;
+        }
+      } catch {
+        formValue = undefined;
+      }
+    } else if (rawForm && typeof rawForm === "object") {
+      formValue = rawForm;
+    }
+    return isCommandCardAction({
+      actionValue,
+      actionName: typeof event.action_name === "string" ? event.action_name : undefined
+    });
+  }
+  async handleCommandCardActionEvent(event, profile) {
+    let actionValue;
+    try {
+      actionValue = typeof event.action_value === "string" ? JSON.parse(event.action_value) : event.action_value;
+    } catch {
+      actionValue = undefined;
+    }
+    let formValue;
+    try {
+      formValue = typeof event.form_value === "string" ? JSON.parse(event.form_value) : event.form_value;
+    } catch {
+      formValue = undefined;
+    }
+    const result = await handleCommandCardAction({
+      actionValue,
+      formValue,
+      actionName: typeof event.action_name === "string" ? event.action_name : undefined,
+      chatId: typeof event.chat_id === "string" ? event.chat_id : undefined,
+      messageId: typeof event.message_id === "string" ? event.message_id : undefined,
+      token: typeof event.token === "string" ? event.token : undefined,
+      profile
+    }, {
+      executeCommand: async (subcommand, args, extra) => {
+        const registry = getGlobalCommandRegistry();
+        return registry.dispatch(subcommand, args, {
+          rawText: `##command##: ${subcommand} ${args.join(" ")}`,
+          configPath: extra?.configPath ?? this.resolveCommandConfigPath()
+        });
+      },
+      configPath: this.resolveCommandConfigPath(),
+      patchCard: async (token, card, prof) => {
+        await patchCardByLarkCli(token, card, prof);
+      }
+    });
+    if (!result.ok) {
+      const text = `⚠️ 命令卡片操作失败：${result.error ?? "未知错误"}`;
+      const messageId = typeof event.message_id === "string" ? event.message_id : undefined;
+      const chatId = typeof event.chat_id === "string" ? event.chat_id : undefined;
+      try {
+        await this.sendLarkText(text, profile, messageId, chatId);
+      } catch {}
+      return;
+    }
+    if (result.patchError) {
+      const text = `⚠️ 操作已生效（${result.executed ?? "命令"}），但卡片刷新失败：` + `${result.patchError}
+` + `（飞书卡片 token 有效期 30 分钟、最多刷新 2 次；可用 ` + `「##command##: list model」重新获取一张新卡片）`;
+      const messageId = typeof event.message_id === "string" ? event.message_id : undefined;
+      const chatId = typeof event.chat_id === "string" ? event.chat_id : undefined;
+      try {
+        await this.sendLarkText(text, profile, messageId, chatId);
+      } catch {}
+    }
+  }
+  async handleCommandMessage(text, profile, messageId, chatId) {
+    try {
+      const configPath = this.resolveCommandConfigPath();
+      const result = await handleCommandMessage(text, { configPath });
+      if (!result) {
+        const card = renderTextCard("⚠️ 命令无法识别", "这条消息没有被识别为有效命令。请用「##command##: <命令> [参数]」格式。");
+        await this.sendLarkCard(card, profile, messageId, chatId);
+        return;
+      }
+      if (!result.ok) {
+        const card = renderTextCard("⚠️ 命令执行失败", result.error ?? "未知错误");
+        await this.sendLarkCard(card, profile, messageId, chatId);
+        return;
+      }
+      const output = result.output;
+      if (!output) {
+        const card = renderTextCard("⚠️ 命令无输出", "命令执行成功但没有产生任何输出。");
+        await this.sendLarkCard(card, profile, messageId, chatId);
+        return;
+      }
+      if (output.card) {
+        await this.sendLarkCard(output.card, profile, messageId, chatId);
+        return;
+      }
+      await this.sendLarkText(output.text, profile, messageId, chatId);
+    } catch (err) {
+      logger4.error(`[LarkCliInstance] handleCommandMessage error: ${err.message}`);
+      try {
+        const card = renderTextCard("⚠️ 命令执行异常", `命令处理时发生异常：${err.message}`);
+        await this.sendLarkCard(card, profile, messageId, chatId);
+      } catch {}
+    }
+  }
+  resolveCommandConfigPath() {
+    const configured = this.config?.options?.configPath;
+    return typeof configured === "string" ? configured : undefined;
+  }
+  async sendLarkCard(card, profile, messageId, chatId) {
+    const content = JSON.stringify(card);
+    await this.spawnLarkCli(["im"], profile, messageId, chatId, [
+      "--msg-type",
+      "interactive",
+      "--content",
+      content
+    ]);
+  }
+  async sendLarkText(text, profile, messageId, chatId) {
+    await this.spawnLarkCli(["im"], profile, messageId, chatId, ["--markdown", text]);
+  }
+  async spawnLarkCli(baseArgs, profile, messageId, chatId, contentArgs) {
+    const args = [...baseArgs];
+    if (messageId) {
+      args.push("+messages-reply", "--message-id", messageId, "--as", "bot");
+    } else if (chatId) {
+      args.push("+messages-send", "--chat-id", chatId, "--as", "bot");
+    } else {
+      throw new Error("No target specified for sending message");
+    }
+    args.push(...contentArgs);
+    if (profile) {
+      args.unshift("--profile", profile);
+    }
+    await new Promise((resolve, reject) => {
+      const proc = spawn2("lark-cli", args, {
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      let stderr = "";
+      proc.stderr?.on("data", (d) => {
+        stderr += d.toString();
+      });
+      proc.on("close", (code) => {
+        if (code === 0)
+          resolve();
+        else
+          reject(new Error(`lark-cli exited with code ${code}: ${stderr}`));
+      });
+      proc.on("error", reject);
+    });
+  }
   async patchCardByToken(token, card, profile) {
     return patchCardByLarkCli(token, card, profile);
   }
@@ -2238,6 +3247,34 @@ function renderRuleNoticeSection(ruleNotice, headline) {
   return `❌ **回执未送达**（原因：${ruleNotice.error ?? "unknown"}）
 ` + `→ 用户目前**还不知道**「${headline}」这件事，必须由你在回复里讲清楚，` + `并且不要假装系统已经通知过。`;
 }
+function extractCommandText(rawEvent) {
+  const event = rawEvent;
+  const innerEvent = event.event;
+  const message = innerEvent?.message || event.message;
+  const rawContent = message?.content ?? event.content;
+  if (rawContent === undefined || rawContent === null)
+    return;
+  let contentText;
+  if (typeof rawContent === "string") {
+    try {
+      const parsed = JSON.parse(rawContent);
+      if (typeof parsed === "string") {
+        contentText = parsed;
+      } else if (parsed && typeof parsed === "object" && "text" in parsed) {
+        const t = parsed.text;
+        contentText = typeof t === "string" ? t : undefined;
+      }
+    } catch {
+      contentText = rawContent;
+    }
+  } else if (typeof rawContent === "object" && "text" in rawContent) {
+    const t = rawContent.text;
+    contentText = typeof t === "string" ? t : undefined;
+  }
+  if (!contentText)
+    return;
+  return isCommandMessage(contentText) ? contentText : undefined;
+}
 var larkCliHandler = {
   type: "lark-cli",
   validateConfig(config) {
@@ -2249,7 +3286,7 @@ var larkCliHandler = {
   },
   async emitTriggerEvent(payload, store) {
     const eventId = await store.insertTriggerEvent(payload, "lark-cli");
-    logger2.info(`[larkCliHandler] emitTriggerEvent: id=${eventId}`, {
+    logger4.info(`[larkCliHandler] emitTriggerEvent: id=${eventId}`, {
       chatId: payload.metadata?.chatId,
       senderId: payload.senderId
     });
@@ -2264,7 +3301,7 @@ var larkCliHandler = {
     try {
       const result = await runner.run(command);
       if (result.code !== 0) {
-        logger2.error(`[larkCliHandler] replyMessage non-zero exit`, {
+        logger4.error(`[larkCliHandler] replyMessage non-zero exit`, {
           code: result.code,
           stderr: result.stderr
         });
@@ -2278,7 +3315,7 @@ var larkCliHandler = {
       return { success: true, messageId: replyMessageId };
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
-      logger2.error(`[larkCliHandler] replyMessage spawn error`, { error: errMsg });
+      logger4.error(`[larkCliHandler] replyMessage spawn error`, { error: errMsg });
       return { success: false, error: errMsg };
     }
   },
@@ -2385,9 +3422,11 @@ async function patchCardByLarkCli(token, card, profile) {
   const cmd = `lark-cli ${profileFlag}api POST /open-apis/interactive/v1/card/update ` + `--data '${JSON.stringify({ token, card }).replace(/'/g, "'\\''")}' --as bot`;
   try {
     const { stdout } = await execAsync2(cmd, { timeout: 30000 });
-    logger2.debug(`patchCardByLarkCli ok: ${stdout?.slice(0, 200)}`);
+    logger4.debug(`patchCardByLarkCli ok: ${stdout?.slice(0, 200)}`);
   } catch (err) {
-    logger2.error(`patchCardByLarkCli failed: ${err.message}`);
+    const msg = err.message;
+    logger4.error(`patchCardByLarkCli failed: ${msg}`);
+    throw new Error(`卡片刷新失败：${msg}`);
   }
 }
 var builtInHandlers = [
@@ -2401,4 +3440,4 @@ function getBuiltInHandler(type) {
   return builtInHandlers.find((h) => h.type === type);
 }
 
-export { TimerInstance, timerHandler, buildDefaultBountyIMSystemPrompt, resolveBountyIMSystemPrompt, BountyIMInstance, bountyIMHandler, bountyCliHandler, buildLarkRecommendedAction, extractMetadata, LarkCliInstance, renderRuleNoticeSection, larkCliHandler, patchCardByLarkCli, builtInHandlers, getBuiltInHandler };
+export { TimerInstance, timerHandler, buildDefaultBountyIMSystemPrompt, resolveBountyIMSystemPrompt, BountyIMInstance, bountyIMHandler, bountyCliHandler, FALLBACK_MODEL_ACTION_NS, FALLBACK_MODEL_ACTIONS, isFallbackModelCard, renderTextCard, renderFallbackModelCard, DEFAULT_CONFIG_PATH, readFallbackModelList, readRawFallbackModelArray, writeFallbackModelList, fallbackModelCommand, listCommand, COMMAND_PREFIX, isCommandMessage, extractCommandInvocation, CommandRegistry, getGlobalCommandRegistry, handleCommandMessage, isCommandCardAction, translateCardActionToCommand, handleCommandCardAction, buildLarkRecommendedAction, extractMetadata, LarkCliInstance, renderRuleNoticeSection, extractCommandText, larkCliHandler, patchCardByLarkCli, builtInHandlers, getBuiltInHandler };