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

package/dist/env/agent/agent-component.d.ts

@@ -174,6 +174,15 @@ export interface AgentComponentOptions {
     envPrefix?: string;
     /** 直接传入的配置对象（可选，优先级最高） */
     config?: Partial<AgentComponentConfig>;
+    /**
+     * Task #4794 — onStop() 时是否跳过 abort 所有运行中的 agent run。
+     *
+     * CLI `act` 一次性命令收尾时传 true：后台子 agent 是有意留下
+     * 继续跑的，onStop 无条件 abort 会中断其 LLM 调用（finishReason=aborted）。
+     * 子 agent 的存活由 TaskComponent.stop 的 waitForRunningTasks 保证。
+     * REPL / ESC cascade 等用户主动退出场景保持默认 false（abort 全部）。
+     */
+    skipAbortRunningTasksOnStop?: boolean;
 }
 /**
  * 按 agent 的 `allowedAgentTypes` 工具级可见性过滤工具列表。
@@ -246,6 +255,11 @@ export declare class AgentComponent extends BaseComponent {
     private fallbackState;
     /** ConfigComponent 用于配置管理 */
     private configComponent?;
+    /**
+     * Task #4794 — onStop() 时是否跳过 abort 运行中的 agent run
+     * （act 一次性命令收尾 = true；用户主动退出 = false 默认）。
+     */
+    private skipAbortRunningTasksOnStop;
     /** 配置变更 watcher 清理函数 */
     private configWatcher?;
     /** Session 消息转换器 */
@@ -492,6 +506,21 @@ export declare class AgentComponent extends BaseComponent {
      * 不阻塞 run。
      */
     private _loadOrCreateCacheSnapshot;
+    /**
+     * 【Task #4813】B1 mtime 失效检测：快照是否因 memory 文件变化而过期
+     *
+     * 返回 null = 快照仍有效（可复用）；返回字符串 = 过期原因（用于日志）。
+     *
+     * 兼容迁移：旧快照（Task #4813 之前持久化）无 memoryStat 字段 → 视为过期。
+     */
+    private _isMemorySnapshotStale;
+    /**
+     * 【Task #4813】采集各 memory 文件的 mtime（按 MemoryComponent 配置的
+     * memoryPaths × memoryFile），供快照失效检测使用。
+     *
+     * 文件不存在 → 记为 0（删除后重拍语义）；memory component 缺失 → 全 0。
+     */
+    private _collectMemoryStat;
     /**
      * 【Task #2744】无 sessionId 时的 {{memory}} fallback 替换
      *
@@ -545,13 +574,37 @@ export declare class AgentComponent extends BaseComponent {
      */
     private invokeLLM;
     /**
-     * Task #4623 — 解析最终的 fallback model。
+     * Task #4724 — 解析最终的兜底模型**有序列表**。
      *
-     * 优先级：AgentContext.fallbackModel（CLI `--fallback-model`）> 配置 `llm.fallbackModel`。
+     * 优先级（高 → 低）：
+     *   1. 显式传入的**数组**（`AgentContext.fallbackModels`，来自 CLI `--fallback-model a,b,c`）
+     *   2. 显式传入的**单值**（`AgentContext.fallbackModel`，来自 CLI `--fallback-model xxx`）
+     *   3. 配置 `llm.fallbackModels`（**有序数组**，与 Task #4722 对齐）
+     *   4. 配置 `llm.fallbackModel`（旧单值，向后兼容）
+     *
+     * 显式传入（1/2）**完全覆盖**配置（3/4）—— CLI 覆盖 config。
      * 若结果只有 modelId（无 `provider/` 前缀）且配置了 `llm.fallbackProvider`，
      * 则补成 `providerId/modelId`（与 `--model` 同语义）。
+     *
+     * ★ Task #4722：`llm.fallbackModels` 是**有序数组**（顺序 = 优先级），
+     *   由 `roy-agent fallback-model add/remove/reorder` 与飞书卡片
+     *   `##command##: fallback-model ...` 维护。
+     *   ★ Task #4724 把语义从「只消费首项」扩展为**整链消费**：
+     *   数组第 2..N 项现在**真正参与降级**（主模型失败 → 依次尝试），
+     *   所以卡片上调整顺序**会**改变运行时行为。
+     *
+     * @param explicitList 显式列表（CLI / AgentContext.fallbackModels）
+     * @param explicitSingle 显式单值（CLI / AgentContext.fallbackModel）
+     */
+    private resolveFallbackModels;
+    /**
+     * ★ Task #4724 review MINOR-4 — 兜底模型列表去重。
+     *
+     * `--fallback-model a/M1,a/M1` 会真的调两次 M1 —— 白白多一次请求 + 一次
+     * 失败等待。按**归一化后的字符串**去重，并保持首次出现的顺序
+     * （顺序 = 优先级，不能被去重打乱）。
      */
-    private resolveFallbackModel;
+    private static dedupeModels;
     /**
      * review P2-3 — 判断两个 model 标识是否"同一个模型"。
      *

package/dist/env/agent/agent-component.js

@@ -7,8 +7,8 @@ import {
   filterToolsByAgent,
   parseToolList,
   toLLMMessage
-} from "../../shared/@ai-setting/roy-agent-core-xhrrgfdy.js";
-import"../../shared/@ai-setting/roy-agent-core-es467wsz.js";
+} from "../../shared/@ai-setting/roy-agent-core-hfr6bzts.js";
+import"../../shared/@ai-setting/roy-agent-core-dt104qa1.js";
 import"../../shared/@ai-setting/roy-agent-core-jvv2h3d6.js";
 import"../../shared/@ai-setting/roy-agent-core-07fvy74y.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";

package/dist/env/agent/index.js

@@ -4,8 +4,8 @@ import {
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../../shared/@ai-setting/roy-agent-core-xhrrgfdy.js";
-import"../../shared/@ai-setting/roy-agent-core-es467wsz.js";
+} from "../../shared/@ai-setting/roy-agent-core-hfr6bzts.js";
+import"../../shared/@ai-setting/roy-agent-core-dt104qa1.js";
 import"../../shared/@ai-setting/roy-agent-core-jvv2h3d6.js";
 import"../../shared/@ai-setting/roy-agent-core-07fvy74y.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";

package/dist/env/agent/types.d.ts

@@ -51,6 +51,18 @@ export interface AgentContext {
      * 认证失败（401/403）、请求错误（400）、主动取消、上下文超限 **不** 触发降级。
      */
     fallbackModel?: string;
+    /**
+     * Task #4724 — 兜底模型**有序列表**（`providerId/modelId`）。
+     *
+     * 主模型调用失败（404 / 429 / 配额耗尽 / 5xx / 超时 / 重试耗尽）时，按数组
+     * 顺序逐个尝试兜底模型，全部失败才抛原始错误。优先级：
+     *   CLI `--fallback-model`（数组）> `AgentContext.fallbackModels`
+     *   > CLI `--fallback-model`（单值）/ `AgentContext.fallbackModel`
+     *   > 配置 `llm.fallbackModels`（数组）> 配置 `llm.fallbackModel`（旧单值）
+     *
+     * 认证失败（401/403）、请求错误（400）、主动取消、上下文超限 **不** 触发降级。
+     */
+    fallbackModels?: string[];
     /** 允许的工具列表（上下文级别，会覆盖 agent 配置） */
     allowedTools?: string[];
     /** 拒绝的工具列表（上下文级别，会覆盖 agent 配置） */
@@ -231,6 +243,8 @@ export interface HookContext {
         systemPrompt: string;
         additionInfo: string;
         snapshotAt: number;
+        /** 【Task #4813】B1 mtime 失效检测：首拍时各 memory 文件的 mtime（ms） */
+        memoryStat?: MemorySnapshotStat;
     };
     /** 执行上下文（可直接修改属性） */
     context: AgentContext;
@@ -299,6 +313,20 @@ export interface Plugin {
  * Agent 类型
  */
 export type AgentType = "primary" | "sub" | "summary";
+/**
+ * 【Task #4813】cacheSnapshot 记忆失效检测（B1 mtime 方案）：
+ * 首拍时各 memory 文件的 mtime 快照。
+ *
+ * - globalMtime: global memory.md 的 mtime（ms）；文件不存在记 0
+ * - projectMtime: project memory.md 的 mtime（ms）；文件不存在记 0
+ *
+ * 复用快照前比对当前 mtime，不一致 → 快照过期 → 重拍。
+ * 旧快照无此字段 → 视为过期（一次性迁移重拍）。
+ */
+export interface MemorySnapshotStat {
+    globalMtime: number;
+    projectMtime: number;
+}
 /**
  * Agent 状态
  */

package/dist/env/environment.d.ts

@@ -177,6 +177,19 @@ export declare class BaseEnvironment extends BaseComponent implements Environmen
     protected startComponents(): Promise<void>;
     /**
      * 停止所有组件
+     *
+     * Task #4794 根因 #4 — LIFO 逆序停止。
+     *
+     * 注册顺序是 config→session→llm→tool→agent→…→task，
+     * 旧实现按 Map 迭代顺序 FIFO 停止 → task 最后停。
+     * 当 task 组件在 stop() 里等待后台子 agent 完成
+     * （BackgroundTaskManager.dispose waitForRunningTasks）时，
+     * 子 agent 下一次 LLM 调用会因 LLMComponent 已停而抛
+     * "LLMComponent is not running" → 任务 failed → 等待中断
+     * → 进程退出杀死同进程子 agent（e2e 取证 23:22:56.803）。
+     *
+     * LIFO：task（最后注册）最先停止，等待期间 llm/tool/agent
+     * 仍存活；config/session（最先注册）最后停止。
      */
     protected stopComponents(): Promise<void>;
     /**

package/dist/env/event-source/command-card-action.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Task #4722 收口 — command 卡片的按钮回调处理
+ *
+ * 用户在飞书卡片上点「↑ / ↓ / 新增」按钮 → 飞书推 `card.action.trigger`
+ * → es handler 分流到本模块 → **回到 command 子系统**执行 →
+ * 用返回的新卡片 patch 原卡片（飞书 token，30min 有效、最多 2 次）。
+ *
+ * ## 为什么单独一个模块（不塞进 lark-card-action-handler.ts）
+ *
+ * `lark-card-action-handler.ts` 是 **task 卡片**的处理器，动作语义是
+ * 建群/解散群（依赖 taskId + task component）。command 卡片的动作语义是
+ * 改 fallback 列表（依赖 config.jsonc 路径），两者数据源完全不同。
+ * 混在一起会让 task 侧被迫依赖 command 侧，反之亦然 —— 违背
+ * 「command 功能不耦合 es 逻辑」的原则。
+ *
+ * 本模块是**纯函数 + 端口注入**：
+ * - 不依赖 es、不依赖 lark-cli、不直接读配置
+ * - 由调用方（es handler）提供「执行 command」和「patch 卡片」两个端口
+ *
+ * ## 动作映射
+ *
+ * | 卡片动作 | 触发方式 | 执行的 command |
+ * |---|---|---|
+ * | `fbmodel_up` | button behaviors[].value.action | `fallback-model reorder <i> <i-1>` |
+ * | `fbmodel_down` | button behaviors[].value.action | `fallback-model reorder <i> <i+1>` |
+ * | `fbmodel_add` | form 提交（action_name） | `fallback-model add <form_value>` |
+ */
+import type { CommandResult } from "./command-registry";
+/** 卡片回调事件里 command 侧关心的字段 */
+export interface CommandCardActionEvent {
+    /** 按钮 callback 的 value（JSON 解析后） */
+    actionValue?: Record<string, unknown>;
+    /** form 提交的字段值（按组件 name 映射） */
+    formValue?: Record<string, unknown>;
+    /** 组件的 name（form 内按钮用它标识动作） */
+    actionName?: string;
+    /** 卡片所在 chat_id */
+    chatId?: string;
+    /** 被点的卡片 message_id */
+    messageId?: string;
+    /** 飞书 token（30min 有效，最多 2 次） */
+    token?: string;
+    /** lark-cli profile */
+    profile?: string;
+}
+/** 端口（由调用方注入，保持本模块纯函数） */
+export interface CommandCardActionPorts {
+    /**
+     * 执行一条 command（返回结构化结果）。
+     * 由 es handler 注入 → 内部走 command 注册表。
+     */
+    executeCommand: (subcommand: string, args: string[], extra?: {
+        configPath?: string;
+    }) => Promise<CommandResult>;
+    /** command 用的配置文件路径 */
+    configPath?: string;
+    /**
+     * 用飞书 token patch 卡片（把新卡片刷到原卡片上）。
+     * 不注入时只回文本，不 patch。
+     */
+    patchCard?: (token: string, card: unknown, profile?: string) => Promise<void>;
+}
+/** 处理结果 */
+export interface CommandCardActionResult {
+    ok: boolean;
+    /** 实际执行的 command（描述） */
+    executed?: string;
+    /** 要 patch 的新卡片（无则不 patch） */
+    card?: unknown;
+    /**
+     * 卡片刷新失败的原因（业务动作成功但卡片没刷新）。
+     * ★ Task #4722 round3（MINOR m1）：飞书 token 30min/2 次，用尽后必然发生；
+     *   上层据此给用户回执，避免卡片静默停在旧状态。
+     */
+    patchError?: string;
+    /** 错误说明 */
+    error?: string;
+}
+/**
+ * 判断一个卡片回调是不是 **command 卡片**的回调。
+ *
+ * 判定依据（任一命中即可）：
+ * - `action_value.action` 以 `fbmodel` 开头（button behaviors 回调）
+ * - `action_name` 以 `fbmodel` 开头（form 提交回调）
+ */
+export declare function isCommandCardAction(event: {
+    actionValue?: unknown;
+    actionName?: string;
+}): boolean;
+/**
+ * 把卡片回调翻译成 command 调用。
+ *
+ * @returns command 名 + 参数；无法识别时返回 null
+ */
+export declare function translateCardActionToCommand(event: CommandCardActionEvent): {
+    subcommand: string;
+    args: string[];
+} | null;
+/**
+ * 处理 command 卡片的按钮回调。
+ *
+ * 流程：翻译成 command → 交给 command 子系统执行 → 拿到新卡片 →
+ * 用 token patch 原卡片（让用户看到最新列表）。
+ */
+export declare function handleCommandCardAction(event: CommandCardActionEvent, ports: CommandCardActionPorts): Promise<CommandCardActionResult>;

package/dist/env/event-source/command-cards.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Task #4722 — command 结果 → 飞书卡片渲染
+ *
+ * es 前端（lark-cli）用这些函数把 CommandResult 渲染成
+ * 飞书 interactive 卡片。卡片 JSON 直接透传给
+ * `lark-cli im +messages-reply --msg-type interactive --content`。
+ *
+ * ## 卡片版本：Card 2.0
+ *
+ * 按 lark-cli 官方卡片工作流（`lark-im/references/card/lark-im-card-create.md`），
+ * Card 2.0 必须：
+ * - 顶层 `"schema": "2.0"`（否则按 1.0 渲染）
+ * - 内容放在 `body.elements`（不是 1.0 的顶层 `elements`）
+ * - 交互组件用 `behaviors`（2.0 废弃了 1.0 的顶层 `action` 模块）
+ *
+ * ## 交互控件（用户需求：卡片中可有可编辑的 list）
+ *
+ * | 控件 | 行为 | 用途 |
+ * |---|---|---|
+ * | `button` × N | `behaviors:[{type:"callback"}]` | 每项的上移 / 下移（调优先级） |
+ * | `form` + `input` + `button` | `form_action_type:"submit"` | 新增一个 fallback model |
+ *
+ * 按钮 callback 的 value 用 `action:"fbmodel*"` 命名空间，与 task 卡片的
+ * `create_group` / `disband_group` 区分开 —— 回调路由据此分流。
+ *
+ * ## 降级路径
+ *
+ * 若飞书后台未开启 `card.action.trigger` 回调（consumer 能 ready 但收不到
+ * 事件），卡片上的按钮不会生效。因此卡片**同时**保留文本指令引导，
+ * 用户也可以直接敲 `##command##: fallback-model ...` 完成同样的操作。
+ */
+import type { LarkCard } from "./command-types";
+/** 飞书 interactive 卡片 JSON（lark-cli 透传） */
+export type { LarkCard };
+/**
+ * command 卡片里按钮 callback 的 action 命名空间。
+ *
+ * 与 task 卡片的 `create_group` / `disband_group` 区分开，
+ * 回调路由按前缀 `fbmodel` 分流到 command 子系统。
+ */
+export declare const FALLBACK_MODEL_ACTION_NS = "fbmodel";
+/** 卡片 action 常量（回调路由与前端共用） */
+export declare const FALLBACK_MODEL_ACTIONS: {
+    /** 新增（form 提交） */
+    readonly add: "fbmodel_add";
+    /** 上移一项 */
+    readonly up: "fbmodel_up";
+    /** 下移一项 */
+    readonly down: "fbmodel_down";
+};
+/**
+ * 判断一个卡片是不是 fallback-model 卡片。
+ *
+ * 用于回调路由：卡片被 patch 后再点按钮，仍能识别出是 command 卡片。
+ *
+ * ★ Task #4722 round2（交叉验证 MINOR-8）：**只按 header 标题判定**。
+ *   Card 2.0 的顶层字段是固定的（schema / config / header / body），
+ *   自定义顶层 key（如 `command: "fbmodel"`）有被飞书校验拒绝的风险 →
+ *   不再使用。
+ */
+export declare function isFallbackModelCard(card: unknown): boolean;
+/**
+ * 渲染纯文本卡片（标题 + markdown 正文）
+ */
+export declare function renderTextCard(title: string, content: string): LarkCard;
+/**
+ * 渲染 fallback-model list 卡片（Card 2.0，可交互）。
+ *
+ * @param list fallback 模型列表（有序 = 优先级，index 0 最高）
+ * @param primaryModel 主模型（展示对照，可缺省）
+ */
+export declare function renderFallbackModelCard(list: string[], primaryModel?: string): LarkCard;

package/dist/env/event-source/command-registry.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview Task #4722 — command 子系统（`##command##:` 前缀分流）
+ *
+ * ## 用户需求
+ *
+ * 在飞书输入 `##command##: list model` → 不走 agent 处理链路，
+ * 直接执行 command 并用卡片消息回显。command 子系统是**纯核心层
+ * 能力**，不耦合任何 es 逻辑；es 只是它的一个交互前端。
+ *
+ * ## 架构
+ *
+ *   ┌──────────┐   ##command##: xxx   ┌──────────────────┐
+ *   │ es 前端  │ ──────────────────→  │ CommandRegistry  │
+ *   │ (lark)   │ ←──────────────────  │  (本文件)         │
+ *   └──────────┘   CommandResult      └──────────────────┘
+ *        │              (text/card)           │
+ *        │ 普通消息 → 走 agent                │ 注册
+ *        ↓                                    ↓
+ *   eventHandler(evt)                  各 command 实现
+ *                                      (fallback-model 等)
+ *
+ * ## 前缀语法
+ *
+ *   ##command##: <subcommand> [args...]
+ *
+ * - 前缀 token 精确匹配 `##command##:`，但**大小写不敏感**
+ *   （`##COMMAND##:` / `##Command##:` 同样识别；`##` 包裹 + 尾随冒号
+ *   已足够特异，不会与正文强调词混淆）
+ * - 允许前导空白；`##command##:` 与命令之间可有任意空白
+ * - 容忍开头的 @-提及（`<at user_id="ou_x"></at>` / `@_user_1`）——
+ *   群里 @bot 的典型形态
+ * - 全角冒号 `：` 不识别（用户手滑时按普通消息走 agent，agent 会引导）
+ */
+/** 命令前缀（token 本身精确，但**匹配时大小写不敏感**） */
+export declare const COMMAND_PREFIX = "##command##:";
+/**
+ * 剥离消息开头的 @-提及标记。
+ *
+ * ★ Task #4722 round2（交叉验证 MINOR-3）：飞书群里 @bot 时，消息正文形如
+ *   `<at user_id="ou_bot"></at> ##command##: list model`
+ * 或旧式 `@_user_1 ##command##: list model`。
+ *   这些前缀会让 `##command##:` 不在开头 → 命令被静默丢给 agent 链路。
+ *
+ * 支持的形态：
+ * - `<at user_id="ou_x"></at>` / `<at user_id="ou_x">名字</at>` / `<at user_id="ou_x"/>`
+ * - `@_user_1` / `@_all`
+ *
+ * 只剥离**开头连续**的提及标记（正文中间的提及不动）。
+ */
+export declare function stripLeadingMentions(text: string): string;
+/**
+ * 判断消息是否是 command 消息（以 `##command##:` 开头，允许前导空白）。
+ *
+ * **大小写不敏感**：`##command##:` / `##COMMAND##:` / `##Command##:` 都识别。
+ * （用户需求要「前缀识别鲁棒性」；大小写变体不会与正文强调词混淆，
+ * 因为 `##` 包裹 + 尾随冒号已经足够特异。）
+ *
+ * **容忍 @-提及前缀**：`<at user_id="ou_bot"></at> ##command##: ...` 也识别。
+ */
+export declare function isCommandMessage(text: string): boolean;
+/** 一条命令的调用（解析结果） */
+export interface CommandInvocation {
+    /** 子命令名，如 "list" / "fallback-model"；空命令为 "" */
+    subcommand: string;
+    /** 参数列表 */
+    args: string[];
+}
+/**
+ * 从消息中提取命令调用。
+ *
+ * 非命令消息返回 null；`##command##:` 后为空时 subcommand 为 ""。
+ */
+export declare function extractCommandInvocation(text: string): CommandInvocation | null;
+/** command 执行上下文 */
+export interface CommandContext {
+    /** 子命令参数 */
+    args: string[];
+    /**
+     * 配置文件路径（读写 ~/.roy-agent/config.jsonc 之类）。
+     * 测试注入临时路径；生产由 es 前端传入。
+     */
+    configPath?: string;
+    /** 原始消息文本 */
+    rawText: string;
+}
+/**
+ * 结构化输出：**双形态**（text 必填 + card 可选）。
+ *
+ * 为什么要双形态而不是互斥联合（`{kind:"text"} | {kind:"card"}`）：
+ * command 子系统是**多前端共享**的（es 飞书卡片前端 + CLI 文本前端），
+ * 互斥联合会导致每个前端只能看到一种形态，CLI 侧被迫把业务逻辑
+ * 复制一遍（违背「可复用已有 command 逻辑」的原始需求）。
+ *
+ * - `text`：**恒为字符串**。任何前端都能渲染（CLI 直接打印，
+ *   飞书侧也可退化成 markdown 文本）。
+ * - `card`：**可选**。es 前端优先用它发 interactive 卡片；
+ *   没有 card 时前端自动降级到 text。
+ *
+ * 兼容：旧的 `{kind:"text", text}` / `{kind:"card", card}` 仍然可构造
+ * （kind 字段保留为可选标记），但新代码应只用 text + card 两个字段。
+ */
+export interface CommandOutput {
+    /** 纯文本形态（恒存在） */
+    text: string;
+    /** 飞书 interactive 卡片形态（可选） */
+    card?: Record<string, unknown>;
+    /**
+     * 形态标记（可选，保留向后兼容）。
+     * - "card"：card 字段可用
+     * - "text"：仅 text 可用
+     */
+    kind?: "text" | "card";
+}
+/** 兼容旧名：纯文本输出 */
+export interface CommandTextOutput extends CommandOutput {
+    kind?: "text";
+}
+/** 兼容旧名：卡片输出 */
+export interface CommandCardOutput extends CommandOutput {
+    kind?: "card";
+    card: Record<string, unknown>;
+}
+/** command 执行结果 */
+export interface CommandResult {
+    ok: boolean;
+    /** 成功时的结构化输出 */
+    output?: CommandOutput;
+    /** 失败时的错误说明（面向用户，可含用法提示） */
+    error?: string;
+}
+/** 单个 command 的定义 */
+export interface CommandDefinition {
+    /** 命令名（如 "fallback-model" / "list"） */
+    name: string;
+    description: string;
+    /** 用法说明（出错时展示给用户） */
+    usage: string;
+    execute(ctx: CommandContext): Promise<CommandResult>;
+}
+/**
+ * Command 注册表。
+ *
+ * 类似 event-source-handlers.ts 的 builtInHandlers 模式：
+ * 各 command 自注册，es 前端只管分发与渲染。
+ */
+export declare class CommandRegistry {
+    private commands;
+    /** 注册 command；重名抛错（防止静默覆盖） */
+    register(def: CommandDefinition): void;
+    has(name: string): boolean;
+    list(): CommandDefinition[];
+    /**
+     * 分发执行。
+     *
+     * - 未知命令 / 空命令 → ok=false + 可用命令列表
+     * - execute 抛异常 → ok=false + error（不向上抛，es 前端可安全渲染）
+     */
+    dispatch(subcommand: string, args: string[], extra?: Partial<CommandContext>): Promise<CommandResult>;
+    /** 帮助文本（列出所有命令） */
+    private renderHelp;
+}
+/**
+ * 全局 command 注册表（懒初始化，内建命令在此注册）。
+ *
+ * 未来扩展：新增 command 只需在此追加，es 前端零改动。
+ */
+export declare function getGlobalCommandRegistry(): CommandRegistry;
+/**
+ * es 前端入口：处理一条消息。
+ *
+ * - 命令消息 → 执行并返回 CommandResult（es 前端负责渲染 text/card）
+ * - 普通消息 → 返回 null（es 前端继续走 agent 链路）
+ *
+ * @param text 消息文本
+ * @param opts.configPath 配置文件路径（传给 command ctx）
+ * @param opts.registry 测试注入用注册表；缺省用全局注册表
+ */
+export declare function handleCommandMessage(text: string, opts?: {
+    configPath?: string;
+    registry?: CommandRegistry;
+}): Promise<CommandResult | null>;

package/dist/env/event-source/command-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Task #4722 — command 子系统的共享类型
+ *
+ * 单独成文件，避免 `command-cards.ts` ↔ `command-registry.ts` 互相 import
+ * 形成循环依赖（卡片渲染要读 command 的输出类型，command 要用卡片渲染）。
+ */
+/** 飞书 interactive 卡片 JSON（lark-cli 透传） */
+export type LarkCard = Record<string, unknown>;

package/dist/env/event-source/event-source-handlers.d.ts

@@ -442,6 +442,59 @@ export declare class LarkCliInstance implements EventSourceInstance {
      * 详见 reports/2026-10-19-lark-cli-multi-event-consume-research.md
      */
     private handleCardActionEvent;
+    /**
+     * ★ Task #4722：处理 `##command##:` 命令消息（**不走 Agent 链路**）
+     *
+     * 流程：
+     *   1. 交给 command 子系统分发（command-registry.ts）
+     *   2. 结果是 card → 用 `lark-cli im +messages-reply --msg-type interactive` 发卡片
+     *   3. 结果是 text → 用 `--markdown` 发文本
+     *   4. 失败 → 发错误回执（不静默）
+     *
+     * 与 card.action.trigger 的共同点：**确定性动作，不需要 LLM 参与**。
+     * 差异：card.action.trigger 是「飞书推的卡片点击」，这里是「用户敲的命令」。
+     */
+    /**
+     * ★ Task #4722 收口：判断一个 card.action.trigger 事件是不是 **command 卡片**回调。
+     *
+     * command 卡片用 `fbmodel_*` 动作命名空间（见 command-cards.ts），
+     * 与 task 卡片的 `create_group` / `disband_group` 区分开。
+     */
+    private isCommandCardActionEvent;
+    /**
+     * ★ Task #4722 收口：处理 command 卡片按钮回调（改 fallback 列表）。
+     *
+     * 流程：
+     *   1. 翻译成 command 调用（reorder / add）
+     *   2. 交给 command 子系统执行
+     *   3. 用飞书 token（30min / 2 次）patch 原卡片 → 用户看到最新列表
+     *
+     * 失败 → 回一条文本消息告诉用户（不静默）。
+     */
+    private handleCommandCardActionEvent;
+    private handleCommandMessage;
+    /**
+     * 解析 command 用的配置文件路径。
+     *
+     * 优先 event-source 配置里的 `options.configPath`（测试可注入临时路径），
+     * 否则用默认 `~/.roy-agent/config.jsonc`。
+     */
+    private resolveCommandConfigPath;
+    /**
+     * 发送飞书 interactive 卡片。
+     *
+     * 用 `lark-cli im +messages-reply --msg-type interactive --content '<json>'`。
+     * 优先 reply 原消息（带 messageId），否则发到 chatId。
+     */
+    private sendLarkCard;
+    /** 发送飞书 markdown 文本 */
+    private sendLarkText;
+    /**
+     * 统一的 lark-cli 发消息调用。
+     *
+     * 身份固定 `bot`（Task #4557：非 bot 会被 event consume 回灌）。
+     */
+    private spawnLarkCli;
     /**
      * 用飞书 token 直接 patch 卡片（30min 有效，最多 2 次）
      *
@@ -479,6 +532,19 @@ export declare class LarkCliInstance implements EventSourceInstance {
  * @param headline 事件标题句（未送达时要求 agent 自己讲清这个事实）
  */
 export declare function renderRuleNoticeSection(ruleNotice: RuleNoticeInfo | undefined, headline: string): string;
+/**
+ * 提取消息文本（仅纯文本消息）。
+ *
+ * ★ Task #4722：`##command##:` 分流需要拿到**用户实际输入的文本**。
+ * lark-cli 的 content 形态有多种：
+ *   - 简化格式：顶层 `content: "{\"text\":\"...\"}"`（字符串 JSON）
+ *   - 简化格式：顶层 `content: { "text": "..." }`（对象）
+ *   - 嵌套格式：`event.message.content`
+ *
+ * 富文本消息（content 是 `[{tag:"md",text:...}]` 数组）不做 command 处理
+ * —— 数组形式不是用户输入的纯指令，交给 agent 正常处理更安全。
+ */
+export declare function extractCommandText(rawEvent: unknown): string | undefined;
 /**
  * LarkCli Handler
  */

package/dist/env/event-source/event-source-handlers.js

@@ -4,25 +4,27 @@ import {
   bountyIMHandler,
   buildLarkRecommendedAction,
   builtInHandlers,
+  extractCommandText,
   extractMetadata,
   getBuiltInHandler,
   larkCliHandler,
   patchCardByLarkCli,
   renderRuleNoticeSection,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-18am1h07.js";
+} from "../../shared/@ai-setting/roy-agent-core-k4ps1hxp.js";
 import"../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
 import"../../shared/@ai-setting/roy-agent-core-add1zqsh.js";
 import {
   cliCommandHandler
 } from "../../shared/@ai-setting/roy-agent-core-v0hf14bj.js";
 import"../../shared/@ai-setting/roy-agent-core-tm1mxttk.js";
-import"../../shared/@ai-setting/roy-agent-core-f6c0nadn.js";
+import"../../shared/@ai-setting/roy-agent-core-b7jbqfsy.js";
 import"../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../shared/@ai-setting/roy-agent-core-9bs6xrav.js";
+import"../../shared/@ai-setting/roy-agent-core-abqhkbn3.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../../shared/@ai-setting/roy-agent-core-ma35jyd9.js";
 import"../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
+import"../../shared/@ai-setting/roy-agent-core-6m4bw8jy.js";
 import"../../shared/@ai-setting/roy-agent-core-0ys85x46.js";
 import"../../shared/@ai-setting/roy-agent-core-zk2jg0v7.js";
 import"../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";
@@ -51,6 +53,7 @@ export {
   larkCliHandler,
   getBuiltInHandler,
   extractMetadata,
+  extractCommandText,
   cliCommandHandler,
   builtInHandlers,
   buildLarkRecommendedAction,