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

package/dist/env/task/plugins/per-task-group-chat-plugin.d.ts

@@ -0,0 +1,561 @@
+/**
+ * @fileoverview PerTaskGroupChatPlugin - 每任务一个独立飞书群聊
+ *
+ * Task #3945 实现：
+ * - task:after.create → 创建群聊（lark-cli im +chat-create）+ 存 chat_id 到 task.context
+ * - task:after.update → 发到 task 群聊（task.context.larkPerTaskChatId）
+ * - task:operation:after.create → 节流后发到 task 群聊
+ * - task:after.complete → 在 task 群聊发"任务完成"摘要
+ *
+ * 关键修复（Task #3945 claude-minimax 评估 P0）：
+ * - P0-1: onAfterUpdate 时 replyChannel fallback 到 task.context.larkPerTaskChatProfile
+ * - P0-2: botAppIds 自动从 replyChannel.appId 推导（用户配置可覆盖）
+ * - P0-3: 文档明确"方式 A：从 --plugins 移除 LarkCliTaskNotifyPlugin"避免双发
+ *
+ * 后续修复（Task #XXXX 调试日志 + 新 config 选项）：
+ * - requireReplyChannel=false：replyChannel 缺失时降级用 fallbackProfile 创建群聊
+ * - disableSubTaskSkip=true：sub-task 也建群聊
+ * - hasTaskUpdater()：诊断方法，检查 taskUpdater 是否注入
+ * - 完整诊断日志：每个 skip 分支都输出原因 + 修复建议（ROY_TASK_NOTIFY_DEBUG=1 可见）
+ *
+ * Task #3987（用户方案 A+B 合并）新增字段：
+ * - defaultInviteUserIds：始终邀请的用户列表（不会自动推导 sender）
+ * - inviteUserIds：动态列表，可用 "sender" 占位符从 replyChannel 自动推导
+ * - 两个字段 union 后去重，得到最终邀请列表
+ *
+ * ★ 关键约束：setTaskUpdater() 必须由 EventSource handler 注入（DI 模式）。
+ *   event-source-handlers.ts:registerPluginHooks 检测到 plugin.setTaskUpdater 存在时
+ *   会自动注入 taskComponent.updateTask 包装函数。
+ *   未注入时 chat_id 只更新 in-memory，DB 没持久化 → 下次 AFTER_UPDATE silently skip。
+ *
+ * @example
+ * ```typescript
+ * // 在 EventSource 中注册（自动注入 setTaskUpdater）
+ * import { createPerTaskGroupChatPlugin } from "./per-task-group-chat-plugin";
+ *
+ * const hook = createPerTaskGroupChatPlugin({
+ *   pluginName: "PerTaskGroupChatPlugin",
+ *   sourceId: "es-lark-1",
+ *   botAppIds: ["cli_xxx"],  // 可选，留空则从 replyChannel.appId 自动推导
+ *   requireReplyChannel: false,  // 默认 true；CLI/测试场景可设 false
+ *   fallbackProfile: "default", // requireReplyChannel=false 时降级用此 profile
+ *   defaultInviteUserIds: ["ou_admin_xxx"],  // ★ 始终邀请（如 admin / 共享账号）
+ *   inviteUserIds: ["sender"],              // ★ 动态占位（自动推导当前 sender）
+ * });
+ * ```
+ *
+ * @调试日志
+ * - 启用 `ROY_TASK_NOTIFY_DEBUG=1` 环境变量可看到所有 debug 日志
+ * - 每个 skip 分支都标注了原因和修复建议
+ * - attachChatIdToTask 失败时会有 ⚠️ warn 标记
+ */
+import type { Hook, HookContext } from "../../hook/types";
+import type { Task } from "../types";
+import type { SessionComponent } from "../../session/session-component";
+/**
+ * PerTaskGroupChatPlugin 配置
+ */
+export interface PerTaskGroupConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 优先级（默认 100，确保在 LarkCliTaskNotifyPlugin (50) 之后） */
+    priority?: number;
+    /** 插件名称（用于 pluginEnabled 检查） */
+    pluginName?: string;
+    /** 事件源 ID（用于 pluginEnabled 检查） */
+    sourceId?: string;
+    /** 群聊命名模板（默认 "Task #{id}: {title}"） */
+    nameTemplate?: string;
+    /** 群聊描述模板 */
+    descriptionTemplate?: string;
+    /**
+     * bot app_id 列表（默认从 replyChannel.appId 自动推导）
+     *
+     * ★ P0-2 修复：如果未提供，则从 replyChannel.appId 取值。
+     * 如果 replyChannel.appId 也未提供，则 fallback 到空数组并在创建群聊时跳过 --bots 参数。
+     */
+    botAppIds?: string[];
+    /**
+     * ★ P0 修复：邀请 user 进群聊的 open_id 列表
+     *
+     * 关键：lark-cli 创建群聊默认是 private chat，不邀请 user 则 user 看不到群聊。
+     *
+     * 特殊值：
+     * - "sender"：自动邀请 event sender（replyChannel.userId）进群
+     *
+     * 默认值：["sender"]（自动邀请发起 task 的用户）
+     *
+     * 设为空数组 [] 则不邀请任何 user（user 看不到群聊，仅适用于 admin 手动加人的场景）。
+     *
+     * ★ Task #3987：本字段与 `defaultInviteUserIds` 是**互补关系**——
+     *   本字段可包含 "sender" 占位符做动态推导，defaultInviteUserIds 是静态列表。
+     *   最终邀请列表 = defaultInviteUserIds ∪ inviteUserIds (去重)。
+     *   注意：本字段不接受 "sender" 之外的占位符，所有非 sender 值都会被视为 open_id 字面量。
+     */
+    inviteUserIds?: string[];
+    /**
+     * ★ Task #3987：始终邀请进群聊的 user open_id 列表
+     *
+     * 与 `inviteUserIds` 的区别：
+     * - defaultInviteUserIds: 静态列表，**不接受 "sender" 占位符**，
+     *   每次建群都强制邀请这些 user（适合 admin / 共享账号 / 必看人员）
+     * - inviteUserIds: 动态列表，可含 "sender" 占位符，从 replyChannel 推导
+     *
+     * 使用场景：
+     * - 团队有一个"任务监督者"账号（如 SRE on-call bot），希望所有 task 群聊都拉它入群
+     *   → 把它放进 defaultInviteUserIds，不用每个 event-source 都重复配置
+     * - 多 event-source 共享同一组"必邀请"用户时，集中配置避免遗漏
+     *
+     * 默认值：[]（不邀请任何额外 user）
+     *
+     * ★ 注意：与 inviteUserIds 类似，defaultInviteUserIds 里的 open_id 也必须属于
+     *   当前 lark-cli profile 对应的 app（飞书 user open_id 是 per-app 隔离的），
+     *   否则 lark-cli 会报 99992361 "open_id cross app"。
+     */
+    defaultInviteUserIds?: string[];
+    /** 创建失败时是否降级（默认 true：主聊天框仍然由 LarkCliTaskNotifyPlugin 处理） */
+    fallbackToMain?: boolean;
+    /**
+     * 操作记录节流（同 LarkCliTaskNotifyPlugin）
+     *
+     * 默认 5000ms，设为 0 表示不节流。
+     */
+    operationThrottleMs?: number;
+    /**
+     * 是否对 sub-task 跳过群聊创建（默认 true）
+     *
+     * 父 task 已建群聊，sub-task 不重复建群（避免群聊爆炸）。
+     * 设为 false 时，每个 task（包括 sub-task）都会建独立群聊。
+     */
+    disableSubTaskSkip?: boolean;
+    /**
+     * onAfterCreate 是否要求 replyChannel.chatId 必须存在（默认 true）
+     *
+     * 默认行为：没有 replyChannel（env 上下文里 chatId 为空）就 silently skip。
+     * 设为 false 时：
+     * - profile 降级到 config.profile 或 undefined（让 lark-cli 用 active profile）
+     * - "群聊已创建"通知到主聊天框这一步会跳过（没有 chatId 可发）
+     * 适用场景：CLI/测试/无 IM 上下文中创建 task 时仍想建群聊。
+     */
+    requireReplyChannel?: boolean;
+    /**
+     * 自定义 lark-cli profile（仅 requireReplyChannel=false 时生效）
+     *
+     * replyChannel 缺失时，createGroupChat 用这个 profile 调用 lark-cli。
+     * 不设置时让 lark-cli 用 active profile。
+     */
+    fallbackProfile?: string;
+    /**
+     * 创建群聊后是否立即发送"任务创建"欢迎消息（默认 true）
+     *
+     * ★ 推荐开启：新群聊如果没有首条消息，飞书侧可能不会立刻在侧边栏/会话列表中
+     *   显示该群聊（要等其他成员发言或主动搜索才能找到）。
+     *   发一条欢迎消息会让群聊立刻可见，并标明用途（"此群用于追踪 task #N"）。
+     *
+     * 设为 false 时：群聊创建后保持沉默，仅在 task 更新/完成时才有消息。
+     * 适用场景：极简通知风格 / 噪音敏感场景。
+     */
+    sendWelcomeMessage?: boolean;
+    /**
+     * #4108 P1-b（opt-in）：无 per-task 群时是否用 EventStore 反查原始 trigger 群兜底。
+     *
+     * 默认 false —— 因为 LarkCliTaskNotifyPlugin 与 PerTaskGroupChatPlugin 常同时启用，
+     * 若 PerTaskGroupChatPlugin 也兜底到 trigger 群，会和 LarkCliTaskNotifyPlugin 的
+     * 直发**重复**（同一群两条消息）。
+     *
+     * 适用场景：只启用 PerTaskGroupChatPlugin（未启用 LarkCliTaskNotifyPlugin）时，
+     * 设为 true 可让"自身无群"的任务更新/操作/完成通知回落到 trigger 群，而不是
+     * silently skip（消除 #4039 C 提到的"更新通知被 skip"的不对称）。
+     */
+    resolveToTriggerChatFallback?: boolean;
+    /**
+     * Task #4192：建群后是否立刻发一张交互式卡片（notifier.startTask）
+     *
+     * 默认 true（推荐）：
+     * - 建群后立刻发卡片，飞书用户能看到一张"任务已创建"卡片，后续 update 都 patch 同一卡片
+     * - 不发普通文字消息（避免"群聊已创建 + 任务已创建"两条噪音）
+     *
+     * 设为 false 时：
+     * - 走旧的 sendWelcomeMessage 路径（默认文本欢迎消息）
+     * - 适用于保留旧行为的场景
+     */
+    cardInitialMessage?: boolean;
+    /**
+     * Task #4331：是否在 task 创建时**自动**建专属群（默认 false）
+     *
+     * 历史行为（autoCreateGroup=true 显式开启）：
+     * - onAfterCreate 触发 → 调 createGroupChat 建专属群 → 写 task.context.larkPerTaskChatId
+     * - 适用：每个 task 想要独立工作群的场景
+     *
+     * 默认行为（autoCreateGroup 未传或 false）：
+     * - onAfterCreate → silently skip（**不**建群）
+     * - 任务卡片只发到触发群（replyChannel.chatId）
+     * - 用户在卡片顶部点"为这个任务建群"按钮 → 走 ensureGroupChat 按需建群
+     * - 适用：减少群聊爆炸 / 集中讨论 / 减少噪音
+     *
+     * ★ 与 LarkCliTaskNotifyPlugin.cardRoutingPorts.ensureTaskGroupChat 协同：
+     *   - LarkCliTaskNotifyPlugin 在路由决策 source="new-group" 时也会调 ensureGroupChat
+     *   - 用户本次改造明确要求"默认不建群"，所以 LarkCliTaskNotifyPlugin 的 new-group 路径
+     *     也被改造为 fallback-to-trigger（不调 ensure）
+     */
+    autoCreateGroup?: boolean;
+    /**
+     * Task #4192：共享 LarkCardPatchNotifier 实例
+     *
+     * - 不传 → plugin 自己 new 一个（适用于仅启用本 plugin 的场景）
+     * - 传同一实例（与 LarkCliTaskNotifyHook 共享）→ 跨 plugin messageId 协调，
+     *   保证 LarkCliTaskNotifyHook 的 updateTask 能 patch 本 plugin startTask 发的卡片
+     */
+    cardNotifier?: import("./lark-card-patch-notifier").LarkCardPatchNotifier;
+}
+/**
+ * PerTaskGroupChatPlugin - 每 task 一个独立飞书群聊
+ *
+ * 与 LarkCliTaskNotifyPlugin 的关系（★ P0-3 双发问题）：
+ * - LarkCliTaskNotifyPlugin: 发到主聊天框（replyChannel.chatId）
+ * - PerTaskGroupChatPlugin: 发到 task 群聊（task.context.larkPerTaskChatId）
+ *
+ * 两种 plugin 监听相同的 hook 点（task:after.update），都会触发。
+ * 文档明确推荐"方式 A"——用户配置 event-source 时只启用 PerTaskGroupChatPlugin：
+ *
+ * ```bash
+ * roy-agent eventsource update <lark-cli-source-id> \
+ *   --plugins "PerTaskGroupChatPlugin"
+ * # 不要包含 LarkCliTaskNotifyPlugin，否则主聊天框也会收到 AFTER_UPDATE 通知
+ * ```
+ *
+ * 如果保留 LarkCliTaskNotifyPlugin，则 PerTaskGroupChatPlugin 应配置为 disabled，
+ * 或用户接受"主聊天框 + task 群聊"双通道通知（用于调试/迁移期）。
+ */
+export declare class PerTaskGroupChatPlugin implements Hook {
+    readonly name: string;
+    readonly priority: number;
+    readonly pluginName?: string;
+    readonly sourceId?: string;
+    private readonly config;
+    /**
+     * 操作记录节流状态
+     * key: `${taskId}`, value: 上次发送时间戳
+     */
+    private lastNotifyTimestamps;
+    /**
+     * Task update 任务（DI 注入，由 EventSource 提供）
+     * 用于 attachChatIdToTask 把 chat_id 写回 task.context
+     */
+    private taskUpdater?;
+    /**
+     * Task 查询器（DI 注入，由 EventSource 提供）
+     *
+     * Task #4039 C 项（统一群解析）：sub-task 自身没有独立群时，需要沿
+     * `parent_task_id` 上溯到最近拥有群的祖先，才能与 CLI notify 路径
+     * （resolveNotifyChatIds）解析出**同一个群**。未注入时退化为只读自身 context。
+     */
+    private taskGetter?;
+    /**
+     * Session component（DI 注入，由 EventSource 提供）
+     *
+     * Task #4023：用于把 chat_id ↔ task_id 反向绑定写到 session.metadata.larkChat，
+     * 让群聊消息事件 handler 能从 session 反向查到当前群绑定的 task。
+     *
+     * 未注入时：跳过反向绑定（task.context 的 larkPerTaskChatId 仍正常工作），
+     *            但群消息 handler 拿不到 parentTaskId 注入。
+     */
+    private sessionComponent?;
+    /**
+     * ★ Task #4230：卡片 notifier 实例（默认 plugin 自己 new，可被外部共享）
+     *
+     * 用于建群后立即发一张交互式卡片（notifier.startTask），
+     * 后续 update / operation / complete 都 patch **同一张卡片**（不刷屏）。
+     */
+    private cardNotifier;
+    /**
+     * ★ Task #4230：卡片 messageId 跟踪（key: taskId）
+     *
+     * 单卡片语义：同一 task 的 create → update → operation → complete
+     * 必须复用同一 messageId。旧实现在 update/complete 走纯文本消息，
+     * 卡片只发不发更新 —— 已删除。
+     */
+    private cardMessageIds;
+    /** 卡片启动失败哨兵（避免 update 重试风暴） */
+    private static readonly CARD_START_FAILED_SENTINEL;
+    /**
+     * ★ Task #4237 修复：同一 task 的建群请求 in-flight 去重
+     *
+     * 根因：`ensureGroupChat`（notify hook 按需建群）与 `onAfterCreate`（本插件）
+     * 是两条独立路径，都可能给同一 task 建群；若两者几乎同时进入，
+     * "读 context → 建群" 之间没有互斥 → 建出两个同名群。
+     *
+     * key = taskId；value = 正在进行的建群 promise（后来者直接复用）
+     */
+    private groupChatInflight;
+    constructor(config?: PerTaskGroupConfig);
+    /**
+     * Task #4230 follow-up：按需为 task 建/取专属群（供卡片路由使用）
+     *
+     * 场景：任务是在**别的 task 的专属群**里被触发的（例如在 #3999 的跟进群里
+     * 让 agent 建了 #4226），此时代码不能把 #4226 的卡片塞进 #3999 的群，也不该
+     * 因为"sub-task 跳过建群"就让 #4226 无家可归 → 这里按需建一个专属群。
+     *
+     * 与 onAfterCreate 的差别（有意为之）：
+     * - 不做 sub-task skip（这是"按需补建"路径）
+     * - 不发初始卡片（卡片由调用方 LarkCliTaskNotifyHook 基于同一 chatId 发送，
+     *   避免重复卡片）
+     *
+     * 会顺手写 chat↔task 绑定 + 把 chatId 持久化进 task.context，因此后续
+     * 解析（lineage 上溯）能直接命中。
+     *
+     * @returns { chatId, profile } 建群成功；undefined = 建群失败（caller 自行降级）
+     */
+    ensureGroupChat(task: Task, 
+    /**
+     * replyChannel 覆盖（hook 调用方从 `ctx.metadata.envContext` 拿到的那份）
+     *
+     * 为什么需要：hook 被直接调用（测试 / eventsource 直调 plugin.execute）时，
+     * ALS 里没有 EnvContext，但 `ctx.metadata.envContext.replyChannel` 有值。
+     * 旧 onAfterCreate 走 getReplyChannelFromCtx 能拿到，所以这里必须支持传入，
+     * 否则会误判「没有 replyChannel → 不建群」。
+     */
+    replyChannelOverride?: {
+        chatId?: string;
+        messageId?: string;
+        userId?: string;
+        appId?: string;
+        profile?: string;
+    }): Promise<{
+        chatId: string;
+        profile?: string;
+        name?: string;
+    } | undefined>;
+    /** ensureGroupChat 的实际建群逻辑（调用方已做幂等/in-flight 去重） */
+    private doEnsureGroupChat;
+    /**
+     * 注入 Task 更新函数（用于 attachChatIdToTask 把 chat_id 写回 DB）
+     *
+     * 由 EventSource handler 在 plugin 实例化时注入（event-source-handlers.ts:registerPluginHooks）。
+     * 未注入时：chat_id 只更新 in-memory task.context，DB 里没持久化 → 下次 AFTER_UPDATE
+     *           从 DB 加载 task 时 getTaskChatId() 返回 undefined，所有后续更新通知 silently 丢失。
+     *
+     * 通过 hasTaskUpdater() 可检查是否已注入。
+     */
+    setTaskUpdater(updater: (taskId: number, context: string) => Promise<void>): void;
+    /**
+     * 检查 taskUpdater 是否已注入（用于诊断和测试）
+     */
+    hasTaskUpdater(): boolean;
+    /**
+     * 注入 Task 查询器（用于 sub-task 上溯祖先群，Task #4039 C 项）。
+     */
+    setTaskGetter(getter: (id: number) => Promise<{
+        context?: string;
+        parent_task_id?: number | null;
+    } | undefined>): void;
+    /**
+     * 检查 taskGetter 是否已注入（用于诊断和测试）
+     */
+    hasTaskGetter(): boolean;
+    /**
+     * 注入 Session component（用于 chat_id ↔ task_id 反向绑定）
+     *
+     * Task #4023: 在 onAfterCreate 建群成功后，调 SessionComponent.upsertChatTaskBinding
+     * 把 chatId 写到 session.metadata.larkChat.taskId。让群消息 handler 反向查到 task。
+     *
+     * 未注入时：跳过反向绑定（task.context.larkPerTaskChatId 仍正常工作）。
+     */
+    setSessionComponent(sessionComponent: SessionComponent): void;
+    /**
+     * 检查 SessionComponent 是否已注入（用于诊断和测试）
+     */
+    hasSessionComponent(): boolean;
+    execute(ctx: HookContext<unknown>): Promise<void>;
+    /**
+     * onAfterCreate: 创建 task 群聊 + 存 chat_id 到 task.context
+     *
+     * 决策日志（ROY_TASK_NOTIFY_DEBUG=1 时可见）：
+     - replyChannel.chatId 缺失 + requireReplyChannel=true → skip
+     - sub-task + disableSubTaskSkip=false → skip
+     - 群聊创建失败 → fallback（fallbackToMain=false 时抛出）
+     */
+    private onAfterCreate;
+    /**
+     * 写 chat_id ↔ task_id 反向绑定（Task #4023）。
+     *
+     * 状态机：creating → ready（成功）/ failed（post-create 失败）。
+     * 失败不阻断主流程（task.context.larkPerTaskChatId 仍正常工作），仅 warn。
+     * 未注入 sessionComponent 时静默跳过（debug 可见）。
+     *
+     * Span 属性（flattenParamFilter=true）：taskId / chatId / status，
+     * 便于 `debug trace` 验证写侧状态迁移（creating→ready/failed）。
+     */
+    private writeChatBinding;
+    /**
+     * onAfterUpdate: 发到 task 群聊
+     *
+     * ★ P0-1 修复：replyChannel 在 onAfterUpdate 可能为空（TaskComponent 内部触发），
+     * 此时 fallback 到 task.context.larkPerTaskChatProfile。
+     *
+     * 重要诊断：如果 task.context 没有 larkPerTaskChatId，说明：
+     * 1. task 创建时 plugin 没被 enabled（eventsource handleRule.plugins 缺失）
+     * 2. task 创建时 plugin 已 enabled 但 chat_id 没持久化到 DB（taskUpdater 未注入）
+     * 3. task 是通过其它途径创建的（旧 task 迁移场景）
+     * → 这 3 种情况都让 onAfterUpdate silently skip，需要查 eventsource 配置 + DB 状态
+     */
+    private onAfterUpdate;
+    /**
+     * onAfterOperationCreate: 节流后发到 task 群聊
+     */
+    private onAfterOperationCreate;
+    /**
+     * onAfterComplete: task 进入 terminal 状态，在 task 群聊发"任务完成"摘要
+     *
+     * 设计：AFTER_COMPLETE 与 AFTER_UPDATE 都触发，但 AFTER_COMPLETE 发的消息
+     * 更突出"完成/失败/cancelled/timeout"语义。
+     *
+     * ★ Task #3957：AFTER_COMPLETE hook 点在 LarkCliInstance.getPluginHookPoints() 注册。
+     *   之前 fallback 列表只返回 3 个 hook 点（缺 AFTER_COMPLETE），导致本方法永远不被触发。
+     */
+    private onAfterComplete;
+    /**
+     * 调用 lark-cli 创建群聊
+     *
+     * Span 输出参数（flattenParamFilter=true）：
+     * - profile: 使用的 lark-cli profile
+     * - botAppIds.length: 邀请的额外 bot 数
+     * - userIds.length: 邀请的 user 数（★ P0 关键：user 看不到群聊的 root cause）
+     * - name / description: 群聊名/描述
+     * Span 输出结果（flattenParamFilter=true）：
+     * - chatId: 创建成功的 chat_id（用于后续 sendToChat / 写入 task.context）
+     */
+    private createGroupChat;
+    /**
+     * 构造 `+chat-create` 命令的 args（提取出来便于单测）
+     *
+     * ★ 关键设计：
+     * - profile 有值时 → 必须加 `--as bot`，否则 lark-cli 用 user 身份建群，
+     *   profile 对应的 bot 不是群成员，后续 bot 发消息会失败
+     * - botAppIds 是邀请额外的 bots（除 --as bot 的当前 bot 之外），可选
+     * - userIds 是邀请原 user 进群（**P0 关键**：不邀请则 user 看不到群聊）
+     * - `--set-bot-manager` 需要 `--as bot` 才生效
+     *
+     * Span 参数：
+     * - hasProfile: 是否有 profile（决定是否加 --as bot）
+     * - botAppIdsCount: 额外 bot 数
+     * - hasUsers: 是否邀请用户（--users）
+     * - argsSummary: args 的可读摘要（lark-cli im +chat-create ...）
+     */
+    private buildCreateGroupChatArgs;
+    /**
+     * 把 chat_id 写回 task.context JSON
+     *
+     * 持久化路径：
+     * 1. taskUpdater 已注入 → 调 updater(task.id, newContext) 写 DB
+     * 2. taskUpdater 未注入 → 只更新 in-memory task.context（DB 没持久化）
+     *    ⚠️ 这种情况是 bug：下次 AFTER_UPDATE 从 DB 加载 task 时 getTaskChatId() 返回 undefined，
+     *    所有后续 update/complete/operation 通知都会 silently skip。
+     *    修复：event-source-handlers.ts:registerPluginHooks 必须检测 plugin.setTaskUpdater 并注入。
+     */
+    private attachChatIdToTask;
+    /**
+     * 从 HookContext 获取 replyChannel
+     *
+     * 优先级：
+     * 1. ctx.metadata.envContext.replyChannel（EventSource 触发）
+     * 2. 直接 ctx.metadata.replyChannel
+     *
+     * ★ P0-1 关键：如果都没有，返回 undefined（调用方应 fallback 到 task.context）
+     */
+    private getReplyChannelFromCtx;
+    /** 从 context JSON 字符串读 larkPerTaskChatId */
+    private parseChatIdFromContext;
+    /** 从 context JSON 字符串读 larkPerTaskChatProfile（★ P0-1 fallback） */
+    private parseProfileFromContext;
+    /**
+     * 从 task 读 larkPerTaskChatId（任务**自身**的群）
+     */
+    private getTaskChatId;
+    /**
+     * 从 task 读 larkPerTaskChatProfile（任务**自身**的群）
+     */
+    private getTaskChatProfile;
+    /**
+     * 解析 task 的"生效群"（Task #4039 C 项：与 CLI notify 路径统一）。
+     *
+     * 规则：先取任务自身的 `larkPerTaskChatId`；没有则沿 `parent_task_id` 上溯最近的
+     * 祖先群（有界 8 层）。与 CLI 的 `resolveNotifyChatIds` 语义一致，保证
+     * "更新 / 完成 / 操作"通知与 "notify 镜像"落到**同一个群**（消除 sub-task 更新被
+     * silently skip 的不对称）。
+     *
+     * 未注入 taskGetter 时退化为只读自身 context（保持向后兼容）。
+     */
+    private resolveEffectiveChat;
+    /**
+     * ★ P0-2 修复：botAppIds 推导
+     *
+     * 优先级：
+     * 1. 用户在 config 显式提供
+     * 2. 从 replyChannel.appId 推导（lark-cli 群聊需要 bot 才能"加入"，必须至少有 1 个 botAppId）
+     * 3. 空数组（让 lark-cli 自行报错或跳过 --bots 参数）
+     */
+    private resolveBotAppIds;
+    /**
+     * ★ P0 修复 + Task #3987 扩展：resolveUserIds - 推导要邀请进群聊的 user open_id
+     *
+     * 不邀请 user → user 看不到群聊（chat 是私有的，只有 bot 在里面）
+     *
+     * 来源（最终 union 去重）：
+     * 1. config.defaultInviteUserIds：始终邀请的静态列表（不含 "sender" 占位符）
+     * 2. config.inviteUserIds 中除 "sender" 之外的所有 open_id（静态）
+     * 3. config.inviteUserIds 含 "sender" → 自动从 replyChannel/params/ALS 推导 sender
+     *    优先级：replyChannel.userId > replyChannel.params?.userId > ALS userId
+     * 4. ALS getEnvContextOrEmpty().userId（仅当上面都没拿到时 fallback）
+     */
+    private resolveUserIds;
+    /**
+     * 检查 task 是否是 sub-task
+     *
+     * 父 task 已建群聊，sub-task 不重复建群（避免群聊爆炸）
+     */
+    private isSubTask;
+    /**
+     * 检查 update 是否有"有意义"的变更（status / progress / priority）
+     *
+     * 避免每次 task.update 都发通知（ctx.after.update 在多次 sub-update 时会反复触发）
+     */
+    private hasMeaningfulChange;
+    /**
+     * 操作记录节流
+     */
+    private shouldThrottleOperation;
+    /**
+     * 渲染模板字符串
+     *
+     * ★ P1 修复：同时支持 `#{var}` 和 `{var}` 两种格式
+     *
+     * 默认模板用 `{var}`（不带 hash），但 renderTemplate 只替换 `#{var}`，
+     * 导致群聊标题/描述里残留字面 `{title}` / `{project_path}` 占位符。
+     *
+     * 现在两种格式都替换：
+     * - `#{id}` / `{id}`
+     * - `#{title}` / `{title}`
+     * - `#{project_path}` / `{project_path}`
+     *
+     * 同时支持任意其它 `#{xxx}` / `{xxx}` 占位符（不渲染则原样输出，便于 debug）。
+     */
+    private renderTemplate;
+    /**
+     * 截断字符串
+     */
+    private truncate;
+    /**
+     * 解析 lark-cli +chat-create 输出 → chat_id
+     *
+     * lark-cli 输出格式示例：
+     * ```json
+     * {"ok": true, "data": {"chat_id": "oc_xxx"}}
+     * ```
+     */
+    private parseChatId;
+}
+/**
+ * 创建 PerTaskGroupChatPlugin 实例（Hook 工厂）
+ */
+export declare function createPerTaskGroupChatPlugin(config?: PerTaskGroupConfig): PerTaskGroupChatPlugin;

package/dist/env/task/plugins/task-tag-plugin.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview TaskTagPlugin - 类似任务信息注入
+ *
+ * 统一插件架构下的 TaskTagPlugin 实现
+ *
+ * Hook 逻辑实现：
+ * - delegateBefore: 注入类似任务信息（使用 keywords 检索，最多 5 个）
+ * - operationAfterCreate: 任务完成时提取 Workflow
+ *
+ * 改造说明：
+ * - 继承 BasePlugin，实现统一插件接口
+ * - 通过 PluginEnv.init() 获取依赖组件
+ * - 使用 PluginEnv.registerHook() 注册 hooks
+ */
+import { BasePlugin, type PluginEnv } from "../../plugin/types";
+export declare class TaskTagPlugin extends BasePlugin {
+    readonly name = "task-tag";
+    readonly version = "1.0.0";
+    readonly description = "Inject similar task information into delegate prompt and extract workflow on task completion";
+    /** Plugin Env（init 时设置） */
+    private env;
+    /** TaskComponent 引用 */
+    private taskComponent;
+    /** AgentComponent 引用 */
+    private agentComponent;
+    /** TagService 引用 */
+    private tagService;
+    constructor();
+    /**
+     * 初始化
+     */
+    init(env: PluginEnv): void;
+    /**
+     * 销毁
+     */
+    dispose(): void;
+    /**
+     * 委派前：注入类似任务信息
+     */
+    private onDelegateBefore;
+    /**
+     * 从 task 提取关键词
+     */
+    private extractKeywords;
+    /**
+     * 格式化类似任务（简洁版）
+     */
+    private formatSimilarTasks;
+    private onOperationAfterCreate;
+    /**
+     * 提取工作流（公开方法，用于测试）
+     */
+    extractWorkflow(taskId: number, sessionId?: string): Promise<void>;
+    /**
+     * Validate a workflow definition (defense-in-depth check before add).
+     *
+     * Delegates to the shared validateWorkflowDefinition helper which wraps
+     * DAGManager.validate() and is the single source of truth across all
+     * workflow entry points (tool, CLI, plugin).
+     *
+     * Note: The 'workflow-extract' agent should have validated already via
+     * workflow_validate tool, but we add this check here as a safety net.
+     *
+     * @returns { valid: boolean, errors: string[] }
+     */
+    private validateWorkflowDefinition;
+    private _workflowRepo;
+    private getWorkflowRepository;
+    private ensureDataDir;
+}

package/dist/env/task/plugins/workflow-extractor-agent.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview WorkflowExtractorAgent - 工作流提取 Agent
+ *
+ * 负责从自然语言描述或 Task 对话历史中提取 Workflow YAML。
+ *
+ * 升级说明（v2）：
+ * - prompt 内容已迁移到 `prompts-index.ts` 的 `builtInPrompts['workflow-extract']`
+ * - 通过 `AgentRegistry.registerWorkflowExtractAgent()` 注册为内置 agent
+ * - 此文件保留工具函数（formatExtractorInput / parseExtractorOutput）供 task-tag-plugin 使用
+ * - `WORKFLOW_EXTRACTOR_PROMPT` 保留为 alias（向后兼容），实际指向 built-in prompt
+ */
+import type { Task, TaskOperation } from "../types";
+import type { SessionMessage } from "../../session/session-component";
+import type { WorkflowDefinition } from "../../workflow/types";
+/**
+ * Workflow Extractor Agent System Prompt（向后兼容 alias）
+ *
+ * @deprecated
+ * 历史：之前直接定义在此文件。现在统一从 `prompts-index.ts` 的
+ * `builtInPrompts['workflow-extract']` 读取，并 re-export 为 `WORKFLOW_EXTRACT_PROMPT`。
+ *
+ * 这个常量保留只是为了**向后兼容**：旧代码可能仍 import 此名称。
+ * 新代码应使用 `import { WORKFLOW_EXTRACT_PROMPT } from "../../prompt/prompts-index"`。
+ */
+export declare const WORKFLOW_EXTRACTOR_PROMPT: string;
+/**
+ * 格式化提取器输入 - 从 Task 提取
+ */
+export declare function formatExtractorInput(params: {
+    task: Task;
+    operations: TaskOperation[];
+    messages: SessionMessage[];
+}): string;
+/**
+ * 格式化提取器输入 - 从自然语言描述提取
+ */
+export declare function formatExtractorInputFromDescription(params: {
+    description: string;
+}): string;
+/**
+ * 解析提取器输出
+ */
+export declare function parseExtractorOutput(output: string): Promise<WorkflowDefinition | null>;