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

package/dist/env/task/delegate/index.js

@@ -3,11 +3,11 @@ import {
   BackgroundTaskManager,
   createDelegateTool,
   createStopTool
-} from "../../../shared/@ai-setting/roy-agent-core-p2r27era.js";
+} from "../../../shared/@ai-setting/roy-agent-core-mxdc756a.js";
 import"../../../shared/@ai-setting/roy-agent-core-tbrn9wdm.js";
 import"../../../shared/@ai-setting/roy-agent-core-yhsssn86.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../../shared/@ai-setting/roy-agent-core-gdsqp6j8.js";
+import"../../../shared/@ai-setting/roy-agent-core-6masakz4.js";
 import"../../../shared/@ai-setting/roy-agent-core-rx16h2m1.js";
 import"../../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../../shared/@ai-setting/roy-agent-core-c1v263jn.js";

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/index.js

@@ -5,7 +5,7 @@ import {
   TaskPriorityEnum,
   TaskStatusEnum,
   TaskTypeEnum
-} from "../../shared/@ai-setting/roy-agent-core-39xejr39.js";
+} from "../../shared/@ai-setting/roy-agent-core-e2z1etk4.js";
 import"../../shared/@ai-setting/roy-agent-core-amkqnyzy.js";
 import {
   SQLiteTaskStore,
@@ -16,11 +16,11 @@ import"../../shared/@ai-setting/roy-agent-core-rn57psp0.js";
 import {
   TaskEntityEventTypes
 } from "../../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"../../shared/@ai-setting/roy-agent-core-p2r27era.js";
+import"../../shared/@ai-setting/roy-agent-core-mxdc756a.js";
 import"../../shared/@ai-setting/roy-agent-core-tbrn9wdm.js";
 import"../../shared/@ai-setting/roy-agent-core-yhsssn86.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../shared/@ai-setting/roy-agent-core-gdsqp6j8.js";
+import"../../shared/@ai-setting/roy-agent-core-6masakz4.js";
 import"../../shared/@ai-setting/roy-agent-core-rx16h2m1.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../shared/@ai-setting/roy-agent-core-c1v263jn.js";

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,88 @@
+/**
+ * @fileoverview 任务卡片「该发到哪个群」的路由决策（Task #4230 / #4394）
+ *
+ * ## 现行规则（用户 2026-10-20 明令，Task #4394）
+ *
+ * > 去掉专属群卡片逻辑，只保留**触发群的进度卡片**（可用户点击建群）
+ *
+ * 决策优先级：
+ * 1. **有触发群 → 就用触发群**。无条件，不判断它是不是"别的 task 的专属群"。
+ * 2. 没有触发群 → 用本 task（其次最近祖先）自己已有的专属群兜底（卡片不能丢）。
+ * 3. 两者都没有 → `none`（调用方静默 skip）。
+ *
+ * ## 已删除的历史逻辑（Task #4394）
+ *
+ * 旧实现（Task #4230）会在"触发群被判定为别的 task 的专属群"时把卡片**改投**到
+ * 本 task / 祖先的 lineage 群，并在触发群补一张「📂 任务卡片已改投专属群 /
+ * 这里不是本任务的群，进展请看专属群」的指路卡。
+ *
+ * 用户实测（Task #4393）该行为是干扰：
+ * ```
+ * 触发群 oc_8947d9e2…（task 4377 的专属群）
+ *   → 卡片被改投到 oc_d27157ac…（lineage 群）
+ *   → 用户在触发群只看到一张"这里不是本任务的群"的灰卡
+ * ```
+ * 用户的诉求是「在哪聊就在哪看到进展」。**跨任务污染不再是需要解决的问题**，
+ * 因此整套「专属群归属判定 + 改投 + 指路卡」链路已彻底删除：
+ * - 删除 `ChatOwnership` / `mergeChatOwnership` / `analyzeContextOwnership`
+ * - 删除 `CardChatDecision.reroutedFrom`
+ * - 删除 `new-group` / `fallback-to-trigger` 两种 source（不再自动建群）
+ *
+ * ## 建群能力仍在（**用户主动点击**才建）
+ *
+ * 卡片顶部按钮 `create_group` / `disband_group` 由
+ * `lark-card-action-handler.ts` 处理，与本文档的路由决策**完全解耦**：
+ * ```
+ * 用户点「为这个任务建群」
+ *   → card.action.trigger 事件
+ *   → handleCardAction → ports.createGroupChat (lark-cli im +chat-create)
+ *   → 回写 task.context.larkPerTaskChatId
+ *   → patch 卡片（按钮翻成「解散该群」+ 出现「进入专属群」链接）
+ * ```
+ * 建群后下一张进度卡会走本文件的优先级 1（仍进触发群），
+ * 但卡片上多了「进入专属群」链接 —— 这是用户可选的入口，不是自动改投。
+ *
+ * 本模块是**纯函数**（不碰 IO），便于单测覆盖所有分支。
+ */
+/** 群名里隐含的 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 type CardChatSource = "trigger-chat" | "own-group" | "ancestor-group" | "none";
+export interface CardChatDecision {
+    chatId?: string;
+    profile?: string;
+    /** 目标群名（诊断用） */
+    chatName?: string;
+    source: CardChatSource;
+    /** 人类可读的决策原因（写进 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 #4394 简化版）
+ *
+ * 规则只有两条：
+ * 1. **有触发群 → 触发群**（无条件，不做任何"是不是别人的群"判定）
+ * 2. 没触发群 → 用本 task / 祖先已有的专属群兜底
+ *
+ * @param input.lineageChat lineage 上找到的专属群（自己优先，其次最近祖先）
+ */
+export declare function decideCardChatTarget(input: {
+    taskId?: number;
+    lineageIds?: number[];
+    lineageChat?: {
+        chatId: string;
+        profile?: string;
+        isSelf: boolean;
+    };
+    triggerChatId?: string;
+    triggerProfile?: string;
+}): CardChatDecision;