@ai-setting/roy-agent-core 1.7.51 → 1.7.53

package/dist/env/task/plugins/lark-cli-task-notify-plugin.d.ts

@@ -0,0 +1,248 @@
+/**
+ * @fileoverview LarkCliTaskNotifyHook - LarkCli 任务通知 Hook（Task #4230 重写）
+ *
+ * 在任务生命周期事件上，把「任务进展」渲染成**一张可更新 + 置顶的飞书卡片**：
+ *
+ * - `task:after.create`          → notifier.startTask（发卡片 + pin）
+ * - `task:after.update`          → notifier.updateTask（patch 同一卡片）
+ * - `task:after.complete`        → notifier.finishTask（终态 patch + unpin）
+ * - `task:operation:after.create` → notifier.updateTask（把 operation 追加进时间线）
+ *
+ * ★ Task #4230：**旧逻辑（普通 text/post 消息通知）已全部删除**。
+ *   本 Hook 只做卡片，不再有任何 `sendLarkMessage` / `sendNotify` 路径，
+ *   也不再有 `buildReplyArgs` / 文本模板（`formatTaskCreated` /
+ *   `formatTaskUpdate` / `formatOperationCreated` 等）等死代码。
+ *
+ * 卡片的样式 / lark-cli 参数契约 / 状态自持（时间线累积 + spinner 轮换）
+ * 全部由 `LarkCardPatchNotifier` 负责，见 lark-card-patch-notifier.ts。
+ *
+ * @example
+ * ```typescript
+ * import { createLarkCliTaskNotifyHook } from "./lark-cli-task-notify-plugin";
+ * globalHookManager.register("task:after.create", createLarkCliTaskNotifyHook({...}));
+ * ```
+ */
+import type { Hook, HookContext } from "../../hook/types";
+import type { Task } from "../types";
+import { getEnvContextOrEmpty } from "../../context";
+import { LarkCardPatchNotifier } from "./lark-card-patch-notifier";
+import { type ChatOwnership } from "./card-chat-routing";
+/**
+ * 从 EnvContext 提取 lark 专属字段
+ *
+ * - 优先从 EventEnvelope (event 字段) 提取
+ * - Fallback 到 replyChannel
+ * - 非 lark source 事件 (github/jira/...) 返回 isLark=false，plugin 跳过
+ */
+export declare function extractLarkFields(env: ReturnType<typeof getEnvContextOrEmpty>): {
+    messageId?: string;
+    chatId?: string;
+    userId?: string;
+    source?: string;
+    isLark: boolean;
+};
+/** 通知类型（保留给配置/测试；实际只有卡片一种渲染形态） */
+export declare enum NotifyType {
+    TASK_CREATED = "task_created",
+    TASK_COMPLETED = "task_completed",
+    TASK_UPDATED = "task_updated",
+    TASK_FAILED = "task_failed",
+    /** 操作记录新增（task:operation:after.create 触发） */
+    OPERATION_CREATED = "operation_created"
+}
+export interface TaskNotifyConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 优先级 */
+    priority?: number;
+    /** 通知类型（用户可覆盖；空数组 = 全开） */
+    notifyTypes?: NotifyType[];
+    /** 插件名称（用于 pluginEnabled 检查） */
+    pluginName?: string;
+    /** 事件源 ID（用于 pluginEnabled 检查） */
+    sourceId?: string;
+    /**
+     * 操作记录通知节流间隔（毫秒）
+     *
+     * operation 事件在 agent 执行过程中高频触发，不加节流会频繁 patch 卡片。
+     * 默认 5000ms；设为 0 表示不节流。
+     */
+    operationThrottleMs?: number;
+    /**
+     * 是否启用卡片模式（Task #4192 / #4196 默认 true）
+     *
+     * ★ Task #4230：卡片是本 Hook 的**唯一**渲染形态。
+     *   `cardMode: false` 只是"静默 skip"的 legacy opt-out（旧 sendNotify 已删除），
+     *   不会再退化成普通文本消息。
+     */
+    cardMode?: boolean;
+    /**
+     * LarkCardPatchNotifier 实例
+     *
+     * 不传 → plugin 自己 new 一个（messageId 由 plugin 的 Map 跟踪）。
+     */
+    cardNotifier?: LarkCardPatchNotifier;
+    /**
+     * ★ Task #4331：是否允许路由决策走"new-group"路径（建专属群）
+     *
+     * 默认 false：触发群是别人的群 + 本 task 无群时，**不**建专属群，退回触发群
+     * 适用：默认行为（用户新要求：默认不建群）
+     *
+     * 设为 true：保留 #4230 老行为（建专属群并改投）
+     * 适用：显式开启（向后兼容）
+     */
+    allowNewGroup?: boolean;
+}
+/**
+ * 卡片路由端口（Task #4230 follow-up）
+ *
+ * 由 EventSource handler 注入（那里才有 task store / session component /
+ * lark-cli）—— 让"卡片该发哪个群"的判定与 IO 解耦，纯逻辑可单测。
+ */
+export interface CardRoutingPorts {
+    /**
+     * 反查「该群是否是某个 task 的专属群」（多重信号）
+     *
+     * 实现建议（见 event-source-handlers.ts）：
+     * - session 的 chat↔task 绑定
+     * - task.context.larkPerTaskChatId / *followup_chat_id
+     * - 群名 "Task 3999" / "#3999"（DB 记录的群名，必要时实时查）
+     */
+    lookupChatOwnership?: (chatId: string) => Promise<ChatOwnership | undefined>;
+    /** task 查询（lineage 上溯） */
+    getTask?: (id: number) => Promise<{
+        context?: string;
+        parent_task_id?: number | null;
+    } | undefined>;
+    /** 为 task 建/取专属群（lineage 无群且触发群是别人的群时用） */
+    ensureTaskGroupChat?: (task: Task) => Promise<{
+        chatId: string;
+        profile?: string;
+        name?: string;
+    } | undefined>;
+}
+export declare class LarkCliTaskNotifyHook implements Hook {
+    readonly name: string;
+    readonly priority: number;
+    readonly description?: string;
+    readonly pluginName?: string;
+    readonly sourceId?: string;
+    private readonly config;
+    /** 卡片模式 notifier 实例 */
+    private cardNotifier?;
+    /**
+     * 卡片 messageId 跟踪（key: taskId）
+     *
+     * 同一 task 的 create → update → complete 必须复用同一 messageId
+     * （单卡片语义：不刷屏）。不同 task 的卡片互不干扰。
+     */
+    private cardMessageIds;
+    /**
+     * 操作记录节流状态
+     * key: `op:${taskId}`，value: 上次 patch 时间戳
+     */
+    private lastNotifyTimestamps;
+    /** 卡片路由端口（由 EventSource handler 注入） */
+    private cardRoutingPorts?;
+    /**
+     * 卡片启动失败的哨兵值
+     *
+     * startTask 失败（如 chatId/profile 解析不到、lark-cli 报错）时写入，
+     * 让后续 update 直接 skip，避免"失败 → 重试 → 再失败"的风暴。
+     */
+    private static readonly CARD_START_FAILED_SENTINEL;
+    /**
+     * ★ Task #4237 修复：首卡「进行中」哨兵
+     *
+     * 根因：`sendCardStart` 里 `ensureTaskGroupChat` 会写 task.context → 同步触发
+     * `task:after.update` → 本 hook 重入 `sendCardUpdate`；此时首卡 messageId 还没写进
+     * `cardMessageIds` → 触发 fallback 补一张卡 + 再发一张改投卡片（同一 task 3 张卡、
+     * 触发群 2 张改投卡片）。
+     *
+     * 修法：进入 `sendCardStart` 前先占位；重入的 update 看到哨兵直接跳过。
+     */
+    private static readonly CARD_START_INFLIGHT_SENTINEL;
+    constructor(config?: TaskNotifyConfig);
+    /**
+     * 注入卡片路由端口（Task #4230 follow-up）
+     *
+     * 未注入时退化为旧行为（触发群优先，不做"别 task 专属群"判定）。
+     */
+    setCardRoutingPorts(ports: CardRoutingPorts): void;
+    /** 诊断：端口是否注入 */
+    hasCardRoutingPorts(): boolean;
+    execute(ctx: HookContext<unknown>): Promise<void>;
+    /** 任务创建：发初始卡片（+ pin） */
+    private onAfterCreate;
+    /** 任务更新：patch 卡片（进度/当前步骤/状态） */
+    private onAfterUpdate;
+    /** 任务终态：patch 终态 + unpin */
+    private onAfterComplete;
+    /**
+     * 操作记录创建：把 operation 追加进卡片时间线
+     *
+     * ★ Task #4230：只在卡片已存在时 patch。
+     *   旧实现会 fallback `startTask`（凭空多发一张卡）——已删除。
+     */
+    private onAfterOperationCreate;
+    private isCardModeEnabled;
+    /**
+     * 解析「卡片该发到哪个群」（Task #4230 follow-up）
+     *
+     * 规则见 card-chat-routing.ts：触发群优先，但跳过"别的 task 的专属群"；
+     * 若是别人的群 → 用本 task（或祖先）的专属群；都没有 → 新建一个。
+     *
+     * @returns decision + 最终可用的 chatId/profile + 是否需要回补链接卡片
+     */
+    private resolveCardTarget;
+    /**
+     * 收集 task 的 lineage（自己 → 父 → 祖父…，最多 10 层）
+     *
+     * 用于：(a) 找最近的专属群；(b) 判断"某个群属于谁"时确认是否在自己 lineage 上。
+     */
+    private collectLineage;
+    /** 发初始卡片（+ pin）并缓存 messageId */
+    private sendCardStart;
+    /**
+     * patch 卡片（进度 / 当前步骤 / 状态）
+     *
+     * 若该 task 还没有卡片（AFTER_CREATE 未成功，例如 replyChannel 缺失），
+     * 降级补发一次 startTask —— 只发生一次，失败则打 sentinel 不再重试。
+     */
+    private sendCardUpdate;
+    /** 终态：patch final status + unpin，并清理 messageId 缓存 */
+    private sendCardFinish;
+    /**
+     * 解析 chatId（优先级：replyChannel > task.context）
+     *
+     * Task #4220: user 触发的群优先 → 用户在**原群**里就能看到卡片与进展；
+     * per-task 群只作为 fallback（replyChannel 缺失时）。
+     */
+    private resolveChatId;
+    /** 解析 profile（优先级：replyChannel > task.context） */
+    private resolveProfile;
+    /**
+     * task → 卡片"任务栏位"元信息（id/标题/描述/目标/父任务/优先级/context…）
+     *
+     * context 原样透传（JSON 字符串）；渲染成可读 bullet 的活由
+     * LarkCardPatchNotifier.renderContextAsLines 负责（卡片里绝不出现 JSON）。
+     */
+    private buildTaskMeta;
+    /**
+     * operation → 卡片时间线条目（里程碑 + 过程步骤 + 当前步骤）
+     *
+     * 兼容旧字段名（actionTitle/actionDescription）以及只带 description/type 的
+     * 历史 payload —— 不要因为字段名差异就静默丢掉事件。
+     */
+    private deriveTimelineFromOperation;
+    /**
+     * 操作记录 patch 节流
+     *
+     * 同一 Task 在 operationThrottleMs（默认 5s）窗口内只 patch 一次，
+     * 避免 agent 每次 tool call 都刷屏 patch 卡片。
+     */
+    private shouldThrottleOperation;
+    /** 检查是否应该发送通知 */
+    private shouldNotify;
+}
+export declare function createLarkCliTaskNotifyHook(config?: TaskNotifyConfig): LarkCliTaskNotifyHook;

package/dist/env/task/plugins/max-iteration-reminder-plugin.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview MaxIterationReminderPlugin — Task #2580 (round 2)
+ *
+ * ReAct 循环的最大迭代收尾提醒（all-agents scope），与 AutoTaskPlugin
+ * 使用**完全相同**的 meta-protocol：在 `agent:after.tool` hook 中通过共享
+ * helper `enqueueToAddFakeUserMessage` 设置
+ * `ctx.toolResult.result.metadata.toAddFakeUserMessage`。AgentComponent
+ * 现有 meta-protocol 消费逻辑（`consumeMetaProtocolUserMessage` +
+ * for-loop 结束后 `flushPendingFakeUserMessage`）会按既定时机 flush。
+ *
+ * ## 为什么 round 2 不用 side-channel
+ *
+ * - 旧实现（commit f7fd5287）：plugin 直接 push ctx.messages
+ * - round 1 旧实现（commit 07945d35）：引入 HookContext.pendingFakeUserMessage +
+ *   AgentComponent.flushPendingFakeUserMessageBeforeLlm 新 side-channel
+ * - round 2 新实现（本文件）：与 AutoTaskPlugin 完全相同的实现方式，复用
+ *   `toolResult.result.metadata.toAddFakeUserMessage` 同一字段、同一个
+ *   AgentComponent 消费路径
+ *
+ * ## Off-by-one 精确处理
+ *
+ * 目标：让最后一次允许的 LLM iteration (iter === maxIterations) 看到提醒。
+ * 因此在 `iteration === maxIterations - 1` 的 `agent:after.tool` 触发——
+ * 此时 LLM 已返回 tool_call，工具已执行，after.tool hook 写 metadata；
+ * 下一个 iteration === maxIterations 是最后一次 LLM 调用，for-loop 结束后
+ * AgentComponent flush metadata → push user(reminder) → 下次 invokeLLM 看到。
+ *
+ * maxIterations === 1 时 iter === 0 === maxIter-1 = 0 触发，但 iter=1 之前
+ * 没有"上一轮"，loop 也不进入 iter=0 的 after.tool（因为 iter=0 时 loop
+ * 条件 `iteration < 1` 失败，loop 不执行）。因此 maxIterations <= 1 时
+ * **防御性跳过**——不伪造 toolResult，不凭空写入 metadata。
+ *
+ * ## 与 AutoTaskPlugin v5.2 的关系（共享 helper + 确定性合并）
+ *
+ * | 维度             | AutoTaskPlugin v5.2                | MaxIterationReminderPlugin (本文件) |
+ * | ---------------- | ---------------------------------- | ---------------------------------- |
+ * | Hook             | `agent:after.tool`                 | `agent:after.tool`                 |
+ * | 触发条件          | `iteration === threshold` (默认 20) | `iteration === maxIterations - 1`  |
+ * | 适用范围          | 仅 `agent.name === "default"`       | 所有 agent（default + sub-agents）   |
+ * | Meta-protocol 字段 | `ctx.toolResult.result.metadata.toAddFakeUserMessage` | 同左（共享） |
+ * | 文案意图          | 建议调 delegate_task 到 roy       | 要求立即总结、不要工具、然后结束     |
+ * | 注册方式          | `environment.ts:334` 显式注册       | 通过 `registerAgent()` 自动注册     |
+ *
+ * 当 `threshold === maxIter-1` 时同轮触发，共享 helper 确定性合并：
+ * 最终 user message 顺序为 `[delegate reminder..., max-iter reminder...]`，
+ * max-iter "不要再调用任何工具、直接总结" 永远在末尾作为最终指令。
+ *
+ * ## AI SDK 邻接约束
+ *
+ * 与 AutoTaskPlugin 完全相同的 flush 时机：for-loop 结束后立即 push user
+ * message 到 `messages`，保证 `[assistant(tool_calls), tool(A), tool(B), tool(C), user(reminder)]` 顺序。
+ * 不在 tool_results 之间插入 user message，AI SDK v6 邻接天然满足。
+ */
+import type { Plugin, HookContext, HookResult } from "../../agent/types";
+export interface MaxIterationReminderPluginConfig {
+    /** 自定义提醒消息模板（可选）。支持 `{maxIterations}` 占位符。 */
+    messageTemplate?: string;
+}
+/**
+ * MaxIterationReminderPlugin
+ *
+ * 在 agent:after.tool hook 中检测 `iteration === maxIterations - 1`，
+ * 通过共享 helper `enqueueToAddFakeUserMessage` 设置
+ * `ctx.toolResult.result.metadata.toAddFakeUserMessage`（kind="max-iter"）。
+ * AgentComponent 现有 meta-protocol 消费路径会在 for-loop 结束后 flush。
+ *
+ * 适用范围：所有 agent（无 agentName 过滤）。
+ * 由 `AgentComponent.registerAgent()` 在每个 agent 创建时自动注册。
+ *
+ * 限制：`maxIterations <= 1` 时无"上一轮 after.tool → 最后一轮 LLM"边界，
+ * 防御性跳过（不伪造 toolResult，不凭空写入 metadata）。
+ *
+ * 注意（2026-10-16）：compact / compact-hint 已从 `maxIterations=1` 改为 3
+ * （给「首轮没调对 tool」留一次真正重试），因此它们**会**走本插件：
+ * 提醒落在 iteration 2、压制 iteration 3。取 3 而非 2 正是为了让 iteration 2
+ * 保持干净（值为 2 时提醒会在 iteration 1 就掐死唯一的重试机会）。
+ * 详见 AgentRegistry.registerCompactAgent() 的注释。
+ */
+export declare class MaxIterationReminderPlugin {
+    readonly name = "MaxIterationReminderPlugin";
+    readonly version = "3.0.0";
+    readonly description = "\u5728 iteration === maxIterations - 1 \u65F6\u901A\u8FC7\u5171\u4EAB meta-protocol helper \u6CE8\u5165 fake user \u6D88\u606F\uFF1BAgentComponent \u73B0\u6709 for-loop \u540E flush\uFF1B\u9002\u7528\u4E8E\u6240\u6709 agent\u3002maxIterations<=1 \u9632\u5FA1\u6027\u8DF3\u8FC7\u3002";
+    readonly priority = 50;
+    private readonly messageTemplate;
+    /** per-query (traceId) 去重，确保一次 query 内只声明一次 */
+    private readonly injectedTraceIds;
+    constructor(config?: MaxIterationReminderPluginConfig);
+    /**
+     * Hook handler — 在 agent:after.tool 时调用。
+     *
+     * 注入条件（必须同时满足）：
+     * 1. agent 当前 maxIterations > 1（防御性：单轮 agent 无前置迭代可触发）
+     * 2. `iteration === maxIterations - 1`（让 iter === maxIterations 的最后
+     *    LLM 调用看到此 reminder）
+     * 3. 该 traceId 下尚未声明过（幂等保证）
+     *
+     * 行为：通过共享 helper 写入 `ctx.toolResult.result.metadata.toAddFakeUserMessage`。
+     * **不直接 push 到 ctx.messages**（meta-protocol 契约）。
+     *
+     * Trace span: `plugin.max-iter-reminder.evaluate`
+     * - attributes.params: not recorded (HookContext is too large)
+     * - log: true (captures logger.info lines for decision + metadata enqueue)
+     * - resultFilter: exposes iteration, maxIterations, willSet, kind
+     *
+     * @returns HookResult `{ continue: true }`，不中断执行
+     */
+    execute(ctx: HookContext): Promise<HookResult>;
+}
+/**
+ * 创建 MaxIterationReminderPlugin 实例
+ */
+export declare function createMaxIterationReminderPlugin(config?: MaxIterationReminderPluginConfig): Plugin;