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

package/dist/env/task/delegate/process-registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Per-task ProcessRegistry
+ *
+ * 每个 delegate_task 持有一个 ProcessRegistry，跟踪该 task 派生的子进程 PID。
+ * bash 工具 spawn 子进程后立即 register，子进程 `exit` 时立即 unregister。
+ * 当 task 超时/stop 时，调用 killAll() 遍历所有剩余 PID，调用 killProcessTree。
+ *
+ * AsyncLocalStorage 隔离：
+ * - runWithProcessRegistryAsync(reg, fn) 把 reg 推到 ALS 栈，进入 fn
+ * - getCurrentProcessRegistry() 在 fn 内返回 reg，外部返回 undefined
+ * - 这样 bash 工具不感知任务边界，只需要 "我这里有个当前 registry 吗？有就注册"
+ *
+ * 设计原则：
+ * - 不影响非 delegate_task 场景（ALS 拿不到 registry 时 bash 不注册，行为零变化）
+ * - 不误杀其他 delegate_task（每个 task 一个独立 registry）
+ * - killAll 带验证+重试：每个 PID 最多杀 3 次，间隔 500ms，杀不掉记录 error 日志
+ */
+export declare class ProcessRegistry {
+    private readonly pids;
+    /**
+     * 注册一个 PID 到当前 registry。
+     * - 重复 register 同一 PID：幂等
+     * - 非正整数 / NaN：静默忽略（避免脏数据）
+     */
+    register(pid: number): void;
+    /**
+     * 反注册一个 PID（子进程 exit 时调用）。
+     * 不存在时不报错（幂等）。
+     */
+    unregister(pid: number): void;
+    /** 当前注册的 PID 数量（测试 + debug 用途） */
+    size(): number;
+    /**
+     * 杀掉所有仍注册在本 registry 的进程树（POSIX 杀进程组 / Windows taskkill /T）。
+     *
+     * 验证 + 重试机制：
+     * - 每次 kill 后等待 500ms，验证进程是否真的被干掉
+     * - 没干掉则重试，最多 3 次
+     * - 3 次还干不掉：记录 error 日志
+     *
+     * Task #2245 — BL-4：保留 `stillAlive` PID 以便后续强杀可重试。
+     * - 旧实现：成功杀掉的 PID 仍被无差别 `clear()`，与 stillAlive 一起丢失。
+     * - 新实现：仅 `delete` 真正被杀死的 PID，stillAlive PID 保留供下次重试。
+     * - 调用方（如 forceStopAll）可以多次调用 killAll 重试残留 PID。
+     * - 内部不 throw — 单个 PID 的 ESRCH/EPERM 不会阻断其他 PID 的清理。
+     */
+    killAll(): Promise<void>;
+}
+/**
+ * 在异步作用域内暴露给定的 ProcessRegistry。
+ * 适合用在 executeWithAbort 包裹 env.handle_query 之处。
+ */
+export declare function runWithProcessRegistryAsync<T>(registry: ProcessRegistry, fn: () => Promise<T>): Promise<T>;
+/**
+ * 当前 ALS 栈顶的 ProcessRegistry（如果存在）。
+ * 在 bash 工具中调用：若返回 undefined 则退化为不注册（保持非 delegate_task 场景的行为）。
+ */
+export declare function getCurrentProcessRegistry(): ProcessRegistry | undefined;

package/dist/env/task/delegate/stop-tool.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview stop_task Tool
+ *
+ * 基于 agent-core 的 stop_task 实现
+ * 参考: packages/core/src/core/environment/expend/task/stop-task-tool.ts
+ *
+ * 功能：
+ * - 停止正在运行的后台任务
+ */
+import type { Tool } from "../../tool/types";
+import type { BackgroundTaskManager } from "./delegate-tool";
+export declare function createStopTool(taskManager: BackgroundTaskManager): Tool;

package/dist/env/task/delegate/subagent-resolver.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Subagent resolution — built-in specs + AgentRegistry
+ */
+import { AgentRegistry } from "../../agent/agent-registry";
+import type { SubAgentSpec } from "./delegate-tool";
+export interface ResolvedSubAgentConfig {
+    subagentType: string;
+    description: string;
+    basePrompt: string;
+    allowedTools?: string[];
+    deniedTools: string[];
+    fromRegistry: boolean;
+}
+export declare function isKnownSubagentType(subagentType: string, registry?: AgentRegistry): boolean;
+export declare function resolveSubAgentConfig(subagentType: string, options?: {
+    registry?: AgentRegistry;
+    getBuiltIn?: (id: string) => SubAgentSpec | undefined;
+}): Promise<ResolvedSubAgentConfig | undefined>;
+/**
+ * 获取可用的 subagent 描述列表
+ *
+ * @param registry AgentRegistry 实例，用于获取自定义 agents
+ * @returns 格式化的 agent 描述列表（英文，与 delegate_task tool description 一致）
+ */
+export declare function listKnownSubagentDescriptions(registry?: AgentRegistry): string;

package/dist/env/task/events/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Task Events Module
+ *
+ * 导出所有 Task 相关的 Event 类型和 Payload 定义
+ */
+export * from "./task-event-types";
+export * from "./task-event-payloads";

package/dist/env/task/events/task-event-payloads.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Task Event Payloads
+ *
+ * 定义所有 Task 相关事件的 Payload 结构
+ */
+import type { Task, TaskOperation } from "../types";
+/**
+ * task.created 事件负载
+ */
+export interface TaskCreatedPayload {
+    task: Task;
+    sessionId: string;
+}
+/**
+ * task.updated 事件负载
+ */
+export interface TaskUpdatedPayload {
+    task: Task;
+    changes: Partial<Task>;
+    sessionId: string;
+}
+/**
+ * task.completed 事件负载
+ */
+export interface TaskCompletedPayload {
+    task: Task;
+    sessionId: string;
+}
+/**
+ * task.deleted 事件负载
+ */
+export interface TaskDeletedPayload {
+    taskId: number;
+    sessionId: string;
+}
+/**
+ * task.operation_added 事件负载
+ */
+export interface TaskOperationAddedPayload {
+    operation: TaskOperation;
+    taskId: number;
+}
+/**
+ * task.delegated 事件负载
+ */
+export interface TaskDelegatedPayload {
+    taskId: number;
+    backgroundTaskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    description: string;
+    subagentType: string;
+}
+/**
+ * task.background.started 事件负载
+ */
+export interface BackgroundTaskStartedPayload {
+    taskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    description: string;
+    subagentType: string;
+    associatedTaskId?: number;
+}
+/**
+ * task.background.progress 事件负载
+ */
+export interface BackgroundTaskProgressPayload {
+    taskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    status: string;
+    progress?: number;
+    progressMessage?: string;
+    description?: string;
+    subagentType?: string;
+    associatedTaskId?: number;
+}
+/**
+ * task.background.completed/failed/timeout/stopped 事件负载
+ */
+export interface BackgroundTaskCompletedPayload {
+    taskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    status: "completed" | "failed" | "timeout" | "stopped";
+    result?: string;
+    error?: string;
+    executionTimeMs: number;
+    associatedTaskId?: number;
+    description?: string;
+    subagentType?: string;
+}
+/**
+ * 所有 Task Entity 事件负载的联合类型
+ */
+export type TaskEntityEventPayload = TaskCreatedPayload | TaskUpdatedPayload | TaskCompletedPayload | TaskDeletedPayload | TaskOperationAddedPayload | TaskDelegatedPayload;
+/**
+ * 所有 Background Task 事件负载的联合类型
+ */
+export type BackgroundTaskEventPayload = BackgroundTaskStartedPayload | BackgroundTaskProgressPayload | BackgroundTaskCompletedPayload;

package/dist/env/task/events/task-event-types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Task Entity Event Types
+ *
+ * 定义 TaskComponent 相关的 EnvEvent 类型
+ */
+/**
+ * Task Entity 事件类型枚举
+ */
+export declare const TaskEntityEventTypes: {
+    /** Task 创建 */
+    readonly CREATED: "task.created";
+    /** Task 更新 */
+    readonly UPDATED: "task.updated";
+    /** Task 完成 */
+    readonly COMPLETED: "task.completed";
+    /** Task 删除 */
+    readonly DELETED: "task.deleted";
+    /** Operation 记录添加 */
+    readonly OPERATION_ADDED: "task.operation_added";
+    /** Task 被委托 */
+    readonly DELEGATED: "task.delegated";
+};
+export type TaskEntityEventType = (typeof TaskEntityEventTypes)[keyof typeof TaskEntityEventTypes];

package/dist/env/task/hooks/contexts.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview Task Hook Contexts - Hook 上下文类型定义
+ */
+import type { CreateTaskOptions, UpdateTaskOptions, Task, TaskOperation, CreateOperationOptions } from "../types";
+import type { TagService } from "../tag-service";
+import type { DelegateToolResult } from "../delegate/delegate-tool";
+/**
+ * Task Create Hook Context
+ *
+ * 触发时机：createTask() 方法调用后，实际创建前
+ *
+ * Plugin 可直接修改 options 来干预创建行为
+ */
+export interface TaskCreateContext {
+    /** 创建选项（Plugin 可直接修改） */
+    options: CreateTaskOptions;
+    /** Session ID */
+    sessionId: string;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Task Create Result Hook Context
+ *
+ * 触发时机：Task 创建成功后
+ *
+ * Plugin 可在此 Hook 中：
+ * - 同步 Tag 到数据库
+ * - 创建关联资源
+ * - 发送通知
+ */
+export interface TaskCreateResultContext {
+    /** 创建后的 Task（已包含生成 ID） */
+    task: Task;
+    /** Session ID */
+    sessionId: string;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Task Update Hook Context
+ *
+ * 触发时机：updateTask() 方法调用后，实际更新前
+ *
+ * Plugin 可直接修改 options 来干预更新行为
+ */
+export interface TaskUpdateContext {
+    /** Task ID */
+    id: number;
+    /** 更新选项（Plugin 可直接修改） */
+    options: UpdateTaskOptions;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Task Update Result Hook Context
+ *
+ * 触发时机：Task 更新成功后
+ */
+export interface TaskUpdateResultContext {
+    /** 更新后的 Task */
+    task: Task;
+    /** 变更的字段 */
+    changes: Partial<UpdateTaskOptions>;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Task Delete Hook Context
+ *
+ * 触发时机：deleteTask() 方法调用后，实际删除前
+ */
+export interface TaskDeleteContext {
+    /** Task ID */
+    id: number;
+}
+/**
+ * Task Delete Result Hook Context
+ *
+ * 触发时机：Task 删除成功后
+ *
+ * 注意：删除成功后无法获取 Task 的详细信息
+ */
+export interface TaskDeleteResultContext {
+    /** 被删除的 Task ID */
+    id: number;
+    /** 是否成功删除 */
+    deleted: boolean;
+}
+/**
+ * Delegate Before Hook Context
+ *
+ * 触发时机：delegate_task 工具执行前
+ *
+ * Plugin 可直接修改 prompt 来注入上下文
+ */
+export interface TaskDelegateContext {
+    /** 关联的 Task ID */
+    taskId?: number;
+    /** 执行提示词（Plugin 可直接修改以注入上下文） */
+    prompt: string;
+    /** SubAgent 类型 */
+    subagentType: string;
+    /** 超时时间 */
+    timeout?: number;
+    /** 清理策略 */
+    cleanup?: "delete" | "keep";
+    /** 执行原因 */
+    reason?: string;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Delegate After Hook Context
+ *
+ * 触发时机：delegate_task 工具执行后
+ */
+export interface TaskDelegateResultContext {
+    /** 关联的 Task ID */
+    taskId?: number;
+    /** 执行结果 */
+    result: DelegateToolResult;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Terminal Status Set — 触发 AFTER_COMPLETE 的 status 集合
+ *
+ * 仅 `completed` 是用户预期的"任务完成"事件，但 `failed` / `cancelled` /
+ * `timeout` 也算 task 终结（不应继续等待结果）。
+ */
+export declare const TASK_COMPLETE_TERMINAL_STATUSES: readonly ["completed", "failed", "cancelled", "timeout"];
+export type TaskCompleteTerminalStatus = typeof TASK_COMPLETE_TERMINAL_STATUSES[number];
+/**
+ * Task Complete Result Hook Context
+ *
+ * 触发时机：task 进入 terminal status (completed / failed / cancelled / timeout)
+ *
+ * 与 AFTER_UPDATE 的区别：AFTER_UPDATE 在每次 update 后触发，AFTER_COMPLETE 仅在
+ * status 进入 terminal 集合内时触发，语义更精确。
+ */
+export interface TaskCompleteResultContext {
+    /** Task 更新后的最终状态 */
+    task: Task;
+    /** 触发完成的 status 变更 (例如 { status: "completed" }) */
+    changes: Partial<UpdateTaskOptions>;
+    /** 进入的 terminal status */
+    terminalStatus: TaskCompleteTerminalStatus;
+    /** 触发 session ID (例如发起 complete task 的 agent session) */
+    sessionId: string;
+    /** Tag 服务引用 */
+    tagService: TagService;
+}
+/**
+ * Operation Create Hook Context
+ *
+ * 触发时机：createOperation() 方法调用后，实际创建前
+ *
+ * Plugin 可直接修改 options 来干预操作记录创建
+ */
+export interface TaskOperationCreateContext {
+    /** 创建选项（Plugin 可直接修改） */
+    options: CreateOperationOptions;
+}
+/**
+ * Operation Create Result Hook Context
+ *
+ * 触发时机：操作记录创建成功后
+ */
+export interface TaskOperationCreateResultContext {
+    /** 创建后的操作记录 */
+    operation: TaskOperation;
+}
+/**
+ * TaskHookContextMap - Hook 点与 Context 类型的映射
+ *
+ * 用于 Hook 执行时类型安全的 Context 获取
+ */
+export interface TaskHookContextMap {
+    "task:before.create": TaskCreateContext;
+    "task:after.create": TaskCreateResultContext;
+    "task:before.update": TaskUpdateContext;
+    "task:after.update": TaskUpdateResultContext;
+    "task:before.delete": TaskDeleteContext;
+    "task:after.delete": TaskDeleteResultContext;
+    "task:after.complete": TaskCompleteResultContext;
+    "task:delegate:before": TaskDelegateContext;
+    "task:delegate:after": TaskDelegateResultContext;
+    "task:operation:before.create": TaskOperationCreateContext;
+    "task:operation:after.create": TaskOperationCreateResultContext;
+}

package/dist/env/task/hooks/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Task Hooks Module
+ *
+ * 提供 Task Component 的 Hook 机制
+ */
+export { TaskHookPoints, type TaskHookPoint } from "./task-hook-points";
+export type { TaskCreateContext, TaskCreateResultContext, TaskUpdateContext, TaskUpdateResultContext, TaskDeleteContext, TaskDeleteResultContext, TaskDelegateContext, TaskDelegateResultContext, TaskOperationCreateContext, TaskOperationCreateResultContext, TaskHookContextMap, } from "./contexts";

package/dist/env/task/hooks/task-hook-points.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Task Hook Points - Hook 点常量定义
+ *
+ * 定义 Task Component 生命周期中的所有 Hook 点
+ */
+export declare const TaskHookPoints: {
+    /** 创建 Task 前 - 可干预 options */
+    readonly BEFORE_CREATE: "task:before.create";
+    /** 创建 Task 后 - 观察或触发副作用 */
+    readonly AFTER_CREATE: "task:after.create";
+    /** 更新 Task 前 - 可干预 options */
+    readonly BEFORE_UPDATE: "task:before.update";
+    /** 更新 Task 后 - 观察变更 */
+    readonly AFTER_UPDATE: "task:after.update";
+    /** 删除 Task 前 - 观察 */
+    readonly BEFORE_DELETE: "task:before.delete";
+    /** 删除 Task 后 - 清理关联资源 */
+    readonly AFTER_DELETE: "task:after.delete";
+    /**
+     * Task 完成 hook —— 仅当任务状态变为 terminal (completed / failed / cancelled / timeout)
+     * 时触发。语义级别比 AFTER_UPDATE 更精确，plugin 可用于实现"任务完成时"的副作用
+     * (例如发送通知、刷新看板、上传结果等)。
+     *
+     * 注意：AFTER_COMPLETE 与 AFTER_UPDATE 不互斥。
+     *   - AFTER_UPDATE 在每一次 update 成功后触发，包括 status 变更、progress 变更等
+     *   - AFTER_COMPLETE 仅在 status 进入 terminal 状态时触发
+     * 一个更新操作可能同时触发两个 hook。
+     */
+    readonly AFTER_COMPLETE: "task:after.complete";
+    /** 委派任务前 - 可干预 prompt、参数 */
+    readonly DELEGATE_BEFORE: "task:delegate:before";
+    /** 委派任务后 - 观察结果 */
+    readonly DELEGATE_AFTER: "task:delegate:after";
+    /** 创建操作记录前 - 可干预 options */
+    readonly OPERATION_BEFORE_CREATE: "task:operation:before.create";
+    /** 创建操作记录后 - 观察或触发副作用 */
+    readonly OPERATION_AFTER_CREATE: "task:operation:after.create";
+};
+/**
+ * Task Hook 点类型
+ */
+export type TaskHookPoint = typeof TaskHookPoints[keyof typeof TaskHookPoints];

package/dist/env/task/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Task Component Index
+ */
+export { TaskComponent, type TaskComponentOptions } from "./task-component";
+export * from "./types";
+export { SQLiteTaskStore, getDefaultTaskDbPath, type TaskStore } from "./storage";
+export * from "./events";

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

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview AutoTaskPlugin v5.2 — uses shared meta-protocol helper
+ *
+ * 在 ReAct 循环达到 iteration 阈值（默认 20）时，在 agent:after.tool hook 中：
+ * 1. 检测 iteration === threshold && agent.name === agentName
+ * 2. per-query 去重（通过 traceId）
+ * 3. 调用 `enqueueToAddFakeUserMessage(ctx.toolResult, msg, "delegate")`：
+ *    设置 hookCtx.toolResult.result.metadata.toAddFakeUserMessage = {role:"user", ...}
+ *    与 MaxIterReminderPlugin 共享同一字段，确定性合并
+ * 4. React 循环在 pushMessage(tool result) 之后读取此 metadata 并 push user message
+ * 5. 保证 messages 顺序：[assistant(tool_calls), tool(result), user(reminder)] ✅
+ *    满足 AI SDK 要求 tool_call 与 tool_result 必须相邻
+ *
+ * v5.2 相比 v5.1 的核心改进（Task #2580 round 2）：
+ * - ✅ 不再直接设置 `metadata.toAddFakeUserMessage = msg`（可能覆盖其他 plugin）
+ * - ✅ 改用共享 helper `enqueueToAddFakeUserMessage`，确定性合并多个 reminder
+ * - ✅ 在同一边界（如 threshold === maxIter-1）与 MaxIterReminderPlugin 协同工作
+ */
+import type { Plugin } from "../../agent/types";
+export interface AutoTaskPluginConfig {
+    /**
+     * ReAct iteration 阈值（达到该 iteration 时触发提醒；默认 20）
+     *
+     * 如果你的场景是「永不提醒」，请传 `threshold: Infinity`（或在注册时关闭插件）。
+     */
+    threshold?: number;
+    /** 仅在该 agent name 下触发（默认 "default"） */
+    agentName?: string;
+}
+/**
+ * 创建 AutoTaskPlugin v5.2
+ *
+ * 在 agent:after.tool hook 中，检测 iteration 达到阈值时：
+ * 1. 通过共享 helper 设置 hookCtx.toolResult.result.metadata.toAddFakeUserMessage
+ * 2. React 循环在 pushMessage(tool result) 之后读取此 metadata 并 push user message
+ * 3. 下一轮 LLM 调用会看到 user reminder，agent 自主决定调用 delegate_task
+ */
+export declare function createAutoTaskPlugin(config?: AutoTaskPluginConfig): Plugin;

package/dist/env/task/plugins/card-chat-routing.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview 任务卡片「该发到哪个群」的路由决策（Task #4230 follow-up）
+ *
+ * ## 背景（真实 bug，2026-10-15）
+ *
+ * Task #4226 的进展卡片被发进了 **「Task 3999 - 多模态ontology提取跟进」** 群。
+ * 根因链：
+ * 1. 触发消息来自 `oc_d083fc…`（= **task #3999 的跟进群**）；
+ * 2. `LarkCliTaskNotifyHook` 的 `replyChannel.chatId` 优先（Task #4220 修复：
+ *    让 user 在触发群看到卡片）→ 卡片落到 `oc_d083fc…`；
+ * 3. #4226 是 sub-task（parent #2066），`PerTaskGroupChatPlugin` 默认跳过建群
+ *    → #4226 从来没有自己的群。
+ *
+ * 结果：#3999 的专属群里出现了一张讲 #4226 的卡片 —— 跨任务污染。
+ *
+ * ## 决策规则（用户确认）
+ *
+ * - **触发群优先**（保持"在哪聊就在哪看到卡片"）
+ * - **但跳过「别 task 的专属群」**：若触发群被判定为某个**非本 task lineage**
+ *   的 task 的专属群 → 卡片改发到本 task 自己的群（lineage 无群时新建）
+ * - 改投时在触发群补一条**链接卡片**（不是普通消息），让 user 知道卡片去哪了
+ *
+ * ## 「专属群」判定信号（多重信号，高精度优先）
+ *
+ * - `chat-binding`：session 的 chat↔task 绑定（PerTaskGroupChatPlugin 建群时写入）
+ * - `larkPerTaskChatId`：task.context 里插件写入的专属群字段
+ * - `followup_chat`：`*followup_chat_id` / `*_group_chat_id` 之类字段（老任务手工建的跟进群）
+ * - `chat-name`：群名里的 `Task 3999` / `#3999` 模式（对没留字段的手工群兜底）
+ *
+ * 注意：**不算** `feishu_chat_id` / `chat_id` 这类"会话群"字段 —— 它们表示
+ * "这个 task 曾在哪个群聊过"，把普通会话群误判成专属群会让新任务的卡片被
+ * 错误地赶去新建群（假阳性比假阴性更烦人）。
+ *
+ * 本模块是**纯函数**（不碰 IO），IO（DB 反查 / lark-cli 取群名）由调用方
+ * （EventSource handler）注入，便于单测覆盖所有分支。
+ */
+/** 群名里隐含的 task id（"Task 3999 - xxx" / "#3999 TMO 提取跟进"） */
+export declare const GROUP_NAME_TASK_ID_RE: RegExp;
+/** 会把 chatId 记进 context 的字段名（用于 DB LIKE 反查） */
+export declare const CTX_FIELD_LARK_PER_TASK_CHAT_ID = "larkPerTaskChatId";
+/** 一个群可能的归属证据（多重信号并集） */
+export interface ChatOwnership {
+    chatId: string;
+    /**
+     * 该群归属的 task id（可能多个：历史脏数据 / 多个 task 共用过一个群）
+     *
+     * 空数组 = 没有证据表明它是任何 task 的专属群。
+     */
+    ownerTaskIds: number[];
+    /** 证据来源（诊断用）：chat-binding / larkPerTaskChatId / followup_chat_id / chat-name */
+    sources: string[];
+    /** 群名（DB 记录或实时查询；可能没有） */
+    chatName?: string;
+    /** 是否被判为"专属群"（至少有一条**专属**证据） */
+    dedicated: boolean;
+}
+export type CardChatSource = "trigger-chat" | "own-group" | "ancestor-group" | "new-group" | "fallback-to-trigger" | "none";
+export interface CardChatDecision {
+    chatId?: string;
+    profile?: string;
+    /** 目标群名（新建群时由 ensureGroupChat 回填，用于改投链接卡片渲染） */
+    chatName?: string;
+    source: CardChatSource;
+    /** 因触发群是"别 task 的专属群"而改投时记录（用于回补链接卡片） */
+    reroutedFrom?: {
+        chatId: string;
+        ownerTaskIds: number[];
+        sources: string[];
+    };
+    /** 人类可读的决策原因（写进 span / debug 日志） */
+    reason: string;
+}
+/** 从 task.context JSON 解析专属群 id（larkPerTaskChatId） */
+export declare function extractPerTaskChatId(contextStr?: string): string | undefined;
+/** 从 task.context JSON 解析专属群名（larkPerTaskChatName） */
+export declare function extractPerTaskChatName(contextStr?: string): string | undefined;
+/** 从 task.context JSON 解析专属群 profile（larkPerTaskChatProfile） */
+export declare function extractPerTaskChatProfile(contextStr?: string): string | undefined;
+/** 从 task.context JSON 解析记录下来的群名（含 `#3999` / `Task 3999` 模式） */
+export declare function extractRecordedChatNames(contextStr?: string): string[];
+/**
+ * 分析「某个 task 的 context 是否主张自己拥有 chatId」
+ *
+ * 只认**专属**信号；`feishu_chat_id` / `chat_id` 这类会话群字段会被忽略
+ * （否则会把普通会话群误判成专属群）。
+ */
+export declare function analyzeContextOwnership(contextStr: string | undefined, chatId: string): {
+    owned: boolean;
+    sources: string[];
+    impliedTaskIds: number[];
+};
+/**
+ * 由多个 task（DB 反查命中）的 context 汇总出 `ChatOwnership`
+ *
+ * @param chatId 目标群
+ * @param candidates DB 反查命中的 task（id + context）
+ * @param extra 额外信号（chat↔task 绑定 / 实时群名），由调用方提供
+ */
+export declare function mergeChatOwnership(chatId: string, candidates: Array<{
+    id: number;
+    context?: string;
+}>, extra?: {
+    boundTaskId?: number | null;
+    /** 该群的真实群名（若调用方查到了） */
+    chatName?: string;
+}): ChatOwnership;
+/**
+ * 决定卡片该发到哪个群
+ *
+ * @param input.lineageIds 本 task 的 lineage（自己 + 所有祖先）task id
+ * @param input.lineageChat lineage 上找到的专属群（自己优先，其次最近祖先）
+ * @param input.triggerOwnership 触发群的归属分析（未做分析时传 undefined）
+ */
+export declare function decideCardChatTarget(input: {
+    taskId?: number;
+    lineageIds: number[];
+    lineageChat?: {
+        chatId: string;
+        profile?: string;
+        isSelf: boolean;
+    };
+    triggerChatId?: string;
+    triggerProfile?: string;
+    triggerOwnership?: ChatOwnership;
+    /**
+     * ★ Task #4331：是否允许"new-group"路径（即触发群是别人的群 + 本 task 无群时建专属群）
+     *
+     * 默认 false（用户新要求：默认不建群）
+     * - true：保留 #4230 的老行为（建专属群），用于向后兼容显式开启的场景
+     * - false：触发群是别人的群 + 本 task 无群 → 退回触发群（不建群）
+     *
+     * 不影响其他 source（trigger-chat / own-group / ancestor-group / none）的决策。
+     */
+    allowNewGroup?: boolean;
+}): CardChatDecision;