agentworkshop 0.7.44 → 0.7.46

package/server/services/workshop/runtime/scheduler-loop/state.ts

@@ -0,0 +1,150 @@
+/**
+ * SchedulerLoopState —— 状态字段 / 启停 / 定时唤醒 / 重投递回调
+ * (拆分层,承 SchedulerLoopContracts;方法体与原文件逐行一致)
+ */
+import { SchedulerLoopContracts } from './contracts'
+import type { AgentRuntime } from '../agent-runtime'
+import type { ChannelMail } from '../../types/a2a'
+import type { ChannelRuntime } from '../channel-runtime'
+import type { ExecutionMode } from '../../agents/agent-interface'
+import type { ModeConfig, LoopController } from '../execution-mode'
+import type { SchedulerLoopOptions } from './types'
+
+export abstract class SchedulerLoopState extends SchedulerLoopContracts {
+  protected readonly tickMs: number
+  protected readonly stallMs: number
+  protected readonly supervisionMail: ((limit: number) => ChannelMail[]) | null
+  protected readonly toolActivityOf: ((agentId: string) => number | null) | null
+  /** Lead 决策留痕(§7.1 lead.*;manager 注入 → Channel shared memory) */
+  protected readonly onLeadDecision: SchedulerLoopOptions['onLeadDecision']
+  /** supervise 节流:最小间隔与最近一次执行时刻/信号指纹(token 效率) */
+  protected lastSuperviseAt = 0
+  protected lastFingerprint = ''
+  protected timer: NodeJS.Timeout | null = null
+  protected started = false
+  protected running = false
+  protected activeRound: Promise<void> | null = null
+  protected pendingWake = false
+  protected tick = 0
+  /** 已催办一次的 WORKING 任务(再次停滞 → cancel) */
+  protected readonly notified = new Set<string>()
+  /** WORKING 任务最近一次 progress 与时间(停滞检测) */
+  protected readonly lastProgress = new Map<string, { progress: number, at: number }>()
+  /** busy 成员执行中任务的进度基线(与 lastProgress 分离:busy 不重置——
+   *  独立检测"忙碌但进度长期不变"的停滞,喂给快照的 stalled 标记) */
+  protected readonly progressSeen = new Map<string, { progress: number, at: number }>()
+  /** 成员空闲起始时间(最久空闲 worker 排序) */
+  protected readonly idleSince = new Map<string, number>()
+  /** 当前活跃的执行模式(null = 默认无模式) */
+  protected activeMode: ExecutionMode | null = null
+  protected activeModeConfig: ModeConfig = {}
+  /** loop 模式控制器 */
+  protected loopController: LoopController | null = null
+  /** 已通知 loop 控制器的完成任务,避免每轮 tick 重复计数 */
+  protected readonly loopCompletedTaskIds = new Set<string>()
+  /** 调度器启动时刻(loop 完成识别基线;防进程重启后重放重启前的 loop 主任务) */
+  protected readonly bootAt = Date.now()
+  /** loop 模式下重新提交任务的回调 */
+  protected onLoopResubmit: ((title: string, description: string) => void) | null = null
+
+  constructor(
+    protected readonly channelRuntime: ChannelRuntime,
+    protected readonly lead: AgentRuntime,
+    options: SchedulerLoopOptions = {},
+  ) {
+    super()
+    this.tickMs = options.tickMs ?? 1000
+    this.stallMs = options.stallMs ?? 300000
+    this.supervisionMail = options.supervisionMail ?? null
+    this.toolActivityOf = options.toolActivityOf ?? null
+    this.onLeadDecision = options.onLeadDecision
+  }
+
+  /** Lead 决策留痕(异常绝不阻断调度) */
+  protected noteLeadDecision(e: { decision: string, taskId?: string, toAgentId?: string, reason?: string, rootId?: string }): void {
+    try {
+      this.onLeadDecision?.({ channelId: this.channelRuntime.channelId, agentId: this.lead.agentId, ...e })
+    }
+    catch {
+      // 记忆写入失败不得影响调度主流程
+    }
+  }
+
+  /** 空闲退避:快照指纹连续不变的轮数(决定下次 tick 间隔) */
+  protected idleStreak = 0
+  /** 上一轮快照指纹(空闲判定) */
+  protected lastRoundFingerprint = ''
+
+  /** 启动调度(自重排 setTimeout:tick 间隔可按空闲状态退避) */
+  start(): void {
+    if (this.started) return
+    this.started = true
+    this.scheduleNext(this.tickMs)
+  }
+
+  /** 事件唤醒(任务状态变化即调):空闲退避中的循环立即恢复快节奏 */
+  wake(): void {
+    if (!this.started) return
+    if (this.running) {
+      this.pendingWake = true
+      return
+    }
+    this.clearTimer()
+    this.launchRound()
+  }
+
+  /** Start exactly one tracked round; shutdown awaits this promise before DB/runtime teardown. */
+  protected launchRound(): void {
+    if (this.activeRound) return
+    const round = this.runRound()
+    this.activeRound = round
+    void round.finally(() => {
+      if (this.activeRound === round) this.activeRound = null
+    })
+  }
+
+  protected clearTimer(): void {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  protected scheduleNext(delayMs: number): void {
+    this.clearTimer()
+    this.timer = setTimeout(() => {
+      this.timer = null
+      this.wake()
+    }, delayMs)
+    this.timer.unref?.()
+  }
+
+  stop(): void {
+    this.started = false
+    this.clearTimer()
+    this.pendingWake = false
+    if (this.loopController) {
+      this.loopController.stop()
+      this.loopController = null
+    }
+    this.loopCompletedTaskIds.clear()
+  }
+
+  /** Stop scheduling and await an already-running supervision round. */
+  async stopAndWait(): Promise<void> {
+    this.stop()
+    // A supervision round may be awaiting a persistent harness indefinitely.
+    // Shutdown is an explicit hard-stop boundary, so abort only the Lead runtime
+    // supervision/run before awaiting the tracked round; normal watchdog never does this.
+    this.lead.abortCurrent()
+    const active = this.activeRound
+    if (active) await active.catch(() => {})
+  }
+
+  /** 设置 loop 模式重新提交回调(manager 注入 submitChannelTask) */
+  setLoopResubmitCallback(fn: (title: string, description: string) => void): void {
+    this.onLoopResubmit = fn
+  }
+
+  // ===== 内部 =====
+}

package/server/services/workshop/runtime/scheduler-loop/tick.ts

@@ -0,0 +1,157 @@
+/**
+ * SchedulerLoopTick —— 内部:回合推进 / 监督节流指纹 / 收口判定
+ * (拆分层,承 SchedulerLoopState;方法体与原文件逐行一致)
+ */
+import { SchedulerLoopState } from './state'
+import type { SupervisionSnapshot } from '../../agents/agent-interface'
+import { IDLE_TICK_CAP_MS, LEAD_DECISION_RETRY_MS, log } from './helpers'
+import { TERMINAL_TASK_STATES } from '../../types/task'
+import { findModeTask } from '../execution-mode'
+import { isOrdinaryRoot } from '../task-engine/policy'
+
+export abstract class SchedulerLoopTick extends SchedulerLoopState {
+  protected async runRound(): Promise<void> {
+    this.running = true
+    try {
+      await this.lead.withExecLock(() => this.tickRound())
+    }
+    catch (err) {
+      log.error(`[SchedulerLoop:${this.lead.agentId}] 一轮调度失败:`, err)
+    }
+    finally {
+      this.running = false
+      // Release the tracked promise before a pending wake starts the next round.
+      // Otherwise launchRound sees the just-finished promise and drops the wake.
+      this.activeRound = null
+      if (this.started) {
+        if (this.pendingWake) {
+          // 事件驱动:执行期间有新信号 → 立即下一轮(节奏不退避)
+          this.pendingWake = false
+          this.launchRound()
+        }
+        else {
+          // 定时驱动:空闲退避(指纹不变 → 间隔翻倍至 8s 上限;有事件 wake() 即刻打断)
+          this.scheduleNext(Math.min(this.tickMs * 2 ** this.idleStreak, IDLE_TICK_CAP_MS))
+        }
+      }
+    }
+  }
+
+  protected async tickRound(): Promise<void> {
+    this.tick += 1
+    const snapshot = this.collectSnapshot()
+    // 普通根任务绝对 deadline 优先于 Lead supervise，防止旧决策在超时后继续派发。
+    const expiredRoots = snapshot.tasks.filter(task =>
+      isOrdinaryRoot(task)
+      && !TERMINAL_TASK_STATES[task.state]
+      && task.deadlineAt
+      && Date.parse(task.deadlineAt) <= Date.now())
+    if (expiredRoots.length > 0) {
+      for (const root of expiredRoots) {
+        const closed = this.lead.taskEngine.timeoutTree(root.id, this.lead.agentId)
+        for (const task of closed) {
+          this.channelRuntime.getAgents().find(a => a.agentId === task.assigneeId)?.abortTask?.(task.id)
+        }
+      }
+      this.lead.refreshStatus()
+      return
+    }
+    // 状态 Map 生命周期修剪:终态/已删任务的条目随轮清理(长会话内存有界)。
+    // progressSeen 全程只增不减;notified/lastProgress/loopCompletedTaskIds 统一按任务集收敛。
+    const liveIds = new Set(snapshot.tasks.map(t => t.id))
+    for (const map of [this.progressSeen, this.lastProgress]) {
+      for (const key of map.keys()) {
+        if (!liveIds.has(key)) map.delete(key)
+      }
+    }
+    for (const key of this.notified) {
+      if (!liveIds.has(key)) this.notified.delete(key)
+    }
+    for (const key of this.loopCompletedTaskIds) {
+      if (!liveIds.has(key)) this.loopCompletedTaskIds.delete(key)
+    }
+    // 空闲判定指纹(与 supervise 节流同源):任务/成员/邮件信号均未变 → 退避
+    const fp = this.superviseFingerprint(snapshot)
+    if (fp === this.lastRoundFingerprint) this.idleStreak++
+    else {
+      this.idleStreak = 0
+      this.lastRoundFingerprint = fp
+    }
+
+    // 检测当前活跃的执行模式
+    const modeTask = findModeTask(snapshot.tasks, this.lead.agentId)
+    if (modeTask) {
+      this.activeMode = modeTask.mode
+      this.activeModeConfig = modeTask.config
+    }
+
+    // loop 模式:检测主任务完成 → 触发循环控制器
+    this.checkLoopCompletion(snapshot)
+
+    const decisions = await this.decide(snapshot)
+    for (const decision of decisions) {
+      try {
+        this.execute(decision)
+      }
+      catch (err) {
+        log.error(`[SchedulerLoop:${this.lead.agentId}] 执行决策失败:`, decision, err)
+      }
+    }
+  }
+
+  /**
+   * supervise 智能节流(token 效率,纯指纹驱动):任务/成员/邮件变化才请求 Lead；
+   * 规则引擎仅负责故障恢复，不承担常规派单或父任务验收。首轮必跑。
+   */
+  protected superviseFingerprint(snapshot: SupervisionSnapshot): string {
+    const tasks = snapshot.tasks
+      .map(t => `${t.id}:${t.state}`)
+      .sort()
+      .join('|')
+    const members = snapshot.members
+      .map(m => `${m.agentId}:${m.state}:${m.queued ?? 0}`)
+      .sort()
+      .join('|')
+    const mailTop = snapshot.mail?.[0]?.messageId ?? ''
+    return `${tasks}#${members}#${mailTop}`
+  }
+
+  protected shouldSupervise(snapshot: SupervisionSnapshot): boolean {
+    if (this.lead.supervise === null) return false // no Lead decision capability: recovery only
+    if (this.lastSuperviseAt === 0) return true
+    const fingerprint = this.superviseFingerprint(snapshot)
+    if (fingerprint !== this.lastFingerprint) return true
+
+    // Retry incomplete acceptance periodically, including the WORKING parent state
+    // used after the final child completes.
+    if (this.hasReviewableParent(snapshot)) {
+      if (Date.now() - this.lastCloseOutAt >= 30_000) {
+        this.lastCloseOutAt = Date.now()
+        return true
+      }
+      return false
+    }
+
+    // Failed/empty triage does not trigger blind dispatch. Retry the Lead after backoff.
+    const hasUnplannedLeadRoot = snapshot.tasks.some((task) => {
+      if (task.parentId || task.assigneeId !== this.lead.agentId) return false
+      if (snapshot.activeRootId && task.id !== snapshot.activeRootId) return false
+      if (task.state !== 'SUBMITTED' && task.state !== 'WORKING') return false
+      return !snapshot.tasks.some(child => child.parentId === task.id)
+    })
+    return hasUnplannedLeadRoot && Date.now() - this.lastSuperviseAt >= LEAD_DECISION_RETRY_MS
+  }
+
+  protected lastCloseOutAt = 0
+
+  /** 存在子任务已全部终态但尚未由 Lead 明确验收的 WAITING 父任务 */
+  protected hasReviewableParent(snapshot: SupervisionSnapshot): boolean {
+    return snapshot.tasks.some((t) => {
+      if ((t.state !== 'WAITING' && t.state !== 'WORKING') || t.assigneeId !== this.lead.agentId) return false
+      if (snapshot.activeRootId && t.id !== snapshot.activeRootId) return false
+      const children = snapshot.tasks.filter(c => c.parentId === t.id)
+      if (children.length === 0) return false
+      return children.every(c => TERMINAL_TASK_STATES[c.state] === true)
+    })
+  }
+}

package/server/services/workshop/runtime/scheduler-loop/types.ts

@@ -0,0 +1,50 @@
+/**
+ * SchedulerLoop 的依赖类型与对外 DTO(原 server/services/workshop/runtime/scheduler-loop.ts 顶部模块级类型声明)。纯类型。
+ */
+import type { ChannelMail } from '../../types/a2a'
+import type { SupervisionDecision } from '../../agents/agent-interface'
+
+export interface MemberView {
+  agentId: string
+  name: string
+  role: 'lead' | 'worker'
+  state: 'idle' | 'busy' | 'stopped'
+  /** 待执行队列长度(SUBMITTED/ASSIGNED;FIFO) */
+  queued: number
+  /** 执行中任务 id(空闲为 null) */
+  currentTaskId: string | null
+  /** 执行中任务标题(lead 观察 worker 在干什么,不必翻任务表) */
+  currentTaskTitle: string | null
+  /** 执行中任务进度 0-100(空闲/未上报为 null;lead 据此判断是否在推进) */
+  currentTaskProgress: number | null
+  /** 已完成任务数 */
+  completedCount: number
+  /** 忙碌但进度长期停滞(超 stallMs 未变)→ lead 应介入(notify/reassign/cancel) */
+  stalled: boolean
+}
+
+export interface SchedulerLoopOptions {
+  tickMs?: number
+  stallMs?: number
+  /** 调度快照邮件提供者(manager 注入;返回最新在前);未注入则快照 mail 为空 */
+  supervisionMail?: (limit: number) => ChannelMail[]
+  /** agent 最近一次工具调用时刻(manager 注入;停滞看门狗的活性信号:
+   *  真实 LLM 长工具链不更新 progress 数字,健康工作不能被两轮 stallMs 误回收) */
+  toolActivityOf?: (agentId: string) => number | null
+  /**
+   * Lead 决策留痕回调(§7.1 lead.wait/guide/reassign/cancel)。
+   * manager 注入后把决策写入 Channel shared memory;未注入 = 不留痕(测试脚手架)。
+   */
+  onLeadDecision?: (e: {
+    channelId: string
+    agentId: string
+    decision: string
+    taskId?: string
+    toAgentId?: string
+    reason?: string
+    rootId?: string
+  }) => void
+}
+
+/** 空闲退避上限(指纹不变时 tick 间隔指数退避至此;事件 wake 立即恢复) */
+export type SchedulerDecision = SupervisionDecision | { kind: 'recovery_complete', taskId: string }

package/server/services/workshop/runtime/task-engine/contracts.ts

@@ -0,0 +1,16 @@
+/**
+ * TaskEngineContracts —— **跨层能力契约**。
+ *
+ * 拆成 5 层后,有 2 个方法只被"更早的层"调用;
+ * 与其把层序排成拓扑序打散职责,不如显式声明为抽象签名,由实现它的层提供(编译期校验)。
+ *
+ * 契约成员:
+ *   requireTask  → 由 lifecycle.ts 实现
+ *   transition  → 由 transition.ts 实现
+ */
+import type { TaskState, WorkspaceTask } from '../../types/task'
+
+export abstract class TaskEngineContracts {
+  protected abstract requireTask(taskId: string): WorkspaceTask
+  abstract transition(taskId: string, state: TaskState, by: string): WorkspaceTask
+}

package/server/services/workshop/runtime/task-engine/create.ts

@@ -0,0 +1,145 @@
+/**
+ * TaskEngineCreate —— 创建与派发
+ * (拆分层,承 TaskEngineUpdate;方法体与原文件逐行一致)
+ */
+import { TaskEngineUpdate } from './update'
+import type { Part } from '../../types/a2a'
+import type { WorkspaceTask } from '../../types/task'
+import { AppError } from '../../../../utils/errors'
+import { rowToTask } from './helpers'
+import { assertDispatchAllowed, rootLineage } from './policy'
+import { issueLeaseFields } from './lease'
+import { rootQueueEnabled } from '../../settings'
+
+export abstract class TaskEngineCreate extends TaskEngineUpdate {
+  /** 创建任务(落库);若 parentId 存在且父任务 WORKING 则父转 WAITING */
+  create(input: {
+    channelId: string
+    creatorId: string
+    assigneeId: string
+    title: string
+    description?: string
+    parentId?: string
+    rootQueueSeq?: number | null
+    parts?: Part[]
+    sourceChatMessageId?: string
+    sourceChatDeliveryId?: string
+    closeReason?: string
+    deadlineAt?: string
+  }): WorkspaceTask {
+    const row = this.repos.tasks.create({
+      channelId: input.channelId,
+      parentId: input.parentId ?? null,
+      rootQueueSeq: input.parentId ? null : input.rootQueueSeq,
+      assigneeId: input.assigneeId,
+      creatorId: input.creatorId,
+      title: input.title,
+      description: input.description ?? null,
+      state: 'SUBMITTED',
+      artifacts: this.initialArtifacts(input.parts),
+      history: [],
+      sourceChatMessageId: input.sourceChatMessageId ?? null,
+      sourceChatDeliveryId: input.sourceChatDeliveryId ?? null,
+      closeReason: input.closeReason ?? '',
+      deadlineAt: input.deadlineAt ?? null,
+      // §5.1 每次新分配产生新代次 + 新租约(创建即首个 assignment)
+      ...issueLeaseFields(0, input.assigneeId),
+    })
+    if (input.parentId) {
+      const parent = this.repos.tasks.findById(input.parentId)
+      if (parent && parent.state === 'WORKING') {
+        this.transition(parent.id, 'WAITING', input.creatorId)
+      }
+    }
+    const created = rowToTask(row)
+    this.hooks?.onTaskChange?.({ taskId: created.id, channelId: created.channelId, state: 'SUBMITTED', agentId: input.assigneeId, task: created })
+    return created
+  }
+
+  /** 来源消息幂等的根任务入口；同 source 永远返回 canonical root。 */
+  createOrGetRoot(input: {
+    channelId: string
+    creatorId: string
+    assigneeId: string
+    title: string
+    description?: string
+    parts?: Part[]
+    sourceChatMessageId: string
+    sourceChatDeliveryId?: string
+    deadlineAt?: string
+  }): { task: WorkspaceTask, created: boolean } {
+    const result = this.repos.tasks.createOrGetRoot({
+      channelId: input.channelId,
+      creatorId: input.creatorId,
+      assigneeId: input.assigneeId,
+      title: input.title,
+      description: input.description,
+      artifacts: this.initialArtifacts(input.parts),
+      sourceChatMessageId: input.sourceChatMessageId,
+      sourceChatDeliveryId: input.sourceChatDeliveryId,
+      deadlineAt: input.deadlineAt,
+      ...issueLeaseFields(0, input.assigneeId),
+    })
+    const task = rowToTask(result.row)
+    if (result.created) {
+      this.hooks?.onTaskChange?.({ taskId: task.id, channelId: task.channelId, state: 'SUBMITTED', agentId: input.assigneeId, task })
+    }
+    return { task, created: result.created }
+  }
+
+  /** 主理人分解:创建子任务(ASSIGNED)+ 向 assignee 投递 assign 消息 + 父任务转 WAITING */
+  dispatch(
+    parent: WorkspaceTask,
+    input: { assigneeId: string, title: string, description?: string, parts?: Part[], routeReason?: string },
+  ): WorkspaceTask {
+    // TaskEngine 是所有派发入口的最终预算闸门；Manager/host tool 的提示不能替代它。
+    assertDispatchAllowed(this.repos.tasks, parent)
+    // 根任务 FIFO：只有当前 active root 可以继续拆解；后续 roots 先排队。
+    // §11 回滚开关 root_queue_enabled=false 时退回多根并发(不改变 source 幂等与预算)。
+    const activeRoot = rootQueueEnabled() ? this.activeRootOf(parent.channelId) : null
+    const lineage = rootLineage(this.repos.tasks, parent)
+    if (activeRoot && lineage.root?.rootQueueSeq != null && lineage.root.id !== activeRoot.id) {
+      throw new AppError(409, 'ROOT_QUEUED', `根任务 ${lineage.root.id.slice(0, 8)} 尚未轮到执行；当前 active root=${activeRoot.id.slice(0, 8)}`)
+    }
+    // 判重下沉(单一入口守卫:REST / LLM 工具 / 调度器直通统一遵守):
+    // 同父同标题在途子任务 → 409,快照滞后引发的重复派发在此收口(省 token 不重跑)。
+    // 子任务直查(listChildrenMeta;idx_tasks_parent 支撑),免全 channel 扫描。
+    const norm = (t: string): string => t.replace(/\s+/g, ' ').trim().toLowerCase()
+    const siblingRow = this.repos.tasks.listChildrenMeta(parent.channelId, parent.id)
+      .find(r => norm(r.title) === norm(input.title)
+        && r.state !== 'COMPLETED' && r.state !== 'CANCELED' && r.state !== 'FAILED')
+    if (siblingRow) {
+      throw new AppError(409, 'DUPLICATE_DISPATCH', `子任务 "${input.title}" 已在执行中(状态 ${siblingRow.state},指派 ${siblingRow.assigneeId?.slice(0, 8) ?? '?'}),不要重复派发`)
+    }
+    const child = this.repos.tasks.create({
+      channelId: parent.channelId,
+      parentId: parent.id,
+      assigneeId: input.assigneeId,
+      creatorId: parent.assigneeId,
+      title: input.title,
+      description: input.description ?? null,
+      state: 'ASSIGNED',
+      artifacts: this.initialArtifacts(input.parts),
+      history: [],
+      routeReason: input.routeReason ?? '',
+      ...issueLeaseFields(0, input.assigneeId),
+    })
+    this.deliverTaskMessage({
+      channelId: parent.channelId,
+      taskId: child.id,
+      fromAgentId: parent.assigneeId,
+      toAgentId: input.assigneeId,
+      title: input.title,
+      description: input.description,
+      kind: 'assign',
+    })
+    // 父任务若非 WAITING 则转 WAITING(等待子任务)
+    const freshParent = this.repos.tasks.findById(parent.id)
+    if (freshParent && freshParent.state !== 'WAITING') {
+      this.transition(parent.id, 'WAITING', parent.assigneeId)
+    }
+    const created = rowToTask(child)
+    this.hooks?.onTaskChange?.({ taskId: created.id, channelId: created.channelId, state: 'ASSIGNED', agentId: input.assigneeId, task: created })
+    return created
+  }
+}

package/server/services/workshop/runtime/task-engine/facade.ts

@@ -0,0 +1,7 @@
+/**
+ * TaskEngine —— 组合各分层后的最终类(可见性/继承/实现接口与拆分前一致)
+ * + 原文件类体之后引用本类的模块级代码(单例/工厂/广播装配)。
+ */
+import { TaskEngineLifecycle } from './lifecycle'
+
+export class TaskEngine extends TaskEngineLifecycle {}

package/server/services/workshop/runtime/task-engine/helpers.ts

@@ -0,0 +1,87 @@
+/**
+ * TaskEngine 的模块级纯工具/常量(原 server/services/workshop/runtime/task-engine.ts 类外声明,含类体之后与类无关的部分)。
+ */
+import type { A2AArtifact, A2AMessage } from '../../types/a2a'
+import type { TaskMetaRow } from '../../db/task.repo'
+import type { TaskRow } from '../../db/database'
+import type { TaskState, WorkspaceTask } from '../../types/task'
+import { createLogger } from '../../logger'
+import { parseJson } from '../../db/database'
+
+export const log = createLogger('workshop.task-engine')
+
+/** 状态机合法迁移表(§2.2);终态(COMPLETED/FAILED/CANCELED)不在表中 → 不可迁移
+ *  例外:WAITING/SUBMITTED(父任务等待子任务合并)→ COMPLETED 属于正常闭环
+ *  (触发条件=全部子任务终态;由 complete() 的 done-check 闸门兜底校验)。
+ *  SUBMITTED → COMPLETED 修复 goal 父任务死锁:lead 派出子任务但从未显式开跑父任务时,
+ *  子任务全部终态后父任务在 SUBMITTED 上永久悬挂(调度器 dispatch 规则要求无子任务、
+ *  收口规则只认 WAITING/WORKING,三面都不接) */
+export const TRANSITIONS: Record<TaskState, TaskState[]> = {
+  SUBMITTED: ['WORKING', 'ASSIGNED', 'COMPLETED', 'CANCELED'],
+  ASSIGNED: ['WORKING', 'CANCELED'],
+  WORKING: ['WAITING', 'COMPLETED', 'FAILED', 'CANCELED'],
+  WAITING: ['WORKING', 'COMPLETED', 'CANCELED'],
+  FAILED: ['ASSIGNED', 'CANCELED'],
+  COMPLETED: [],
+  CANCELED: [],
+}
+
+/** 行 → 域对象:JSON 列展开(artifacts_json → artifacts,history_json → history) */
+export function rowToTask(row: TaskRow): WorkspaceTask {
+  return {
+    id: row.id,
+    channelId: row.channelId,
+    parentId: row.parentId ?? undefined,
+    rootQueueSeq: row.rootQueueSeq ?? undefined,
+    assigneeId: row.assigneeId,
+    creatorId: row.creatorId ?? '',
+    title: row.title,
+    description: row.description ?? undefined,
+    state: row.state as TaskState,
+    progress: row.progress,
+    retryCount: row.retryCount,
+    artifacts: parseJson<A2AArtifact[]>(row.artifactsJson, []),
+    history: parseJson<A2AMessage[]>(row.historyJson, []),
+    routeReason: row.routeReason || undefined,
+    sourceChatMessageId: row.sourceChatMessageId || undefined,
+    sourceChatDeliveryId: row.sourceChatDeliveryId || undefined,
+    closeReason: row.closeReason || undefined,
+    deadlineAt: row.deadlineAt || undefined,
+    assignmentGeneration: row.assignmentGeneration ?? 0,
+    executionLeaseId: row.executionLeaseId || undefined,
+    executionLeaseAgentId: row.executionLeaseAgentId || undefined,
+    executionLeaseStartedAt: row.executionLeaseStartedAt || undefined,
+    executionLeaseRevokedAt: row.executionLeaseRevokedAt || undefined,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  }
+}
+
+/** 元数据行 → 域对象:免 JSON 大列解析(artifacts/history 置空,仅供调度快照/队列视图消费) */
+export function rowToTaskLite(row: TaskMetaRow): WorkspaceTask {
+  return {
+    id: row.id,
+    channelId: row.channelId,
+    parentId: row.parentId ?? undefined,
+    rootQueueSeq: row.rootQueueSeq ?? undefined,
+    assigneeId: row.assigneeId,
+    creatorId: row.creatorId ?? '',
+    title: row.title,
+    description: row.description ?? undefined,
+    state: row.state as TaskState,
+    progress: row.progress,
+    retryCount: row.retryCount,
+    artifacts: [],
+    history: [],
+    routeReason: row.routeReason || undefined,
+    sourceChatMessageId: row.sourceChatMessageId || undefined,
+    sourceChatDeliveryId: row.sourceChatDeliveryId || undefined,
+    closeReason: row.closeReason || undefined,
+    deadlineAt: row.deadlineAt || undefined,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  }
+}
+
+/** 任务执行历史上限(applyEvent 整列重写模型下的写放大有界化) */
+export const TASK_HISTORY_CAP = 200

package/server/services/workshop/runtime/task-engine/index.ts

@@ -0,0 +1,15 @@
+/**
+ * server/services/workshop/runtime/task-engine.ts 拆分后的门面(目录 index 解析,外部 import 路径不变)。
+ *
+ * 结构:
+ *   types.ts       依赖类型与 DTO
+ *   helpers.ts     模块级纯工具/常量
+ *   contracts.ts   跨层能力契约(2 个抽象方法)
+ *   views.ts       队列视图(全量/精简/单智能体/监督)
+ *   update.ts      任务更新 / 重投递 / 投递辅助
+ *   create.ts      创建与派发
+ *   transition.ts  状态跃迁与事件应用
+ *   lifecycle.ts   完成 / 改派 / 取消 / 子任务回调
+ *   facade.ts      最终类 + 模块级尾码
+ */
+export { TaskEngine } from './facade'