Import vendor/dsh-sansheng-liubu/workbench/core/tasks.mjs
This commit is contained in:
parent
6e293a8f6b
commit
2c639e7331
|
|
@ -0,0 +1,436 @@
|
|||
// 任务生命周期:纯函数 + 显式副作用端口。
|
||||
// 判定永远不读聊天文本,只认结构化报告、宿主真实终态和可解析的成果引用——
|
||||
// 这是“agent 说已完成”与“任务完成”分开的落点。
|
||||
// 副作用(写 store、入队、回传)由调用方注入,core 本身不碰网络和调度。
|
||||
|
||||
import { assertTransition, isState, isTerminal } from './states.mjs'
|
||||
import { isRoleId } from './roles.mjs'
|
||||
|
||||
export class TaskError extends Error {
|
||||
constructor(code, message, details = undefined) {
|
||||
super(message)
|
||||
this.name = 'TaskError'
|
||||
this.code = code
|
||||
if (details !== undefined) this.details = details
|
||||
}
|
||||
}
|
||||
|
||||
const TASK_BASE_TRANSITIONS = Object.freeze([
|
||||
['draft', 'queued'],
|
||||
['queued', 'running'],
|
||||
['running', 'waiting_input'],
|
||||
['running', 'needs_attention'],
|
||||
['running', 'completed'],
|
||||
['running', 'failed'],
|
||||
['waiting_input', 'queued'],
|
||||
['waiting_input', 'running'],
|
||||
['needs_attention', 'completed'],
|
||||
['needs_attention', 'running'],
|
||||
['needs_attention', 'failed'],
|
||||
// 取消可在任何非终态发起
|
||||
['draft', 'cancelled'],
|
||||
['queued', 'cancelled'],
|
||||
['running', 'cancelled'],
|
||||
['waiting_input', 'cancelled'],
|
||||
['needs_attention', 'cancelled'],
|
||||
// 入队后模型不可用:允许直接失败并保留错误
|
||||
['queued', 'failed'],
|
||||
])
|
||||
|
||||
export const TASK_TRANSITIONS = Object.freeze(TASK_BASE_TRANSITIONS.map(([from, to]) => Object.freeze([from, to])))
|
||||
|
||||
const TERMINAL_TASK_STATES = Object.freeze(['completed', 'failed', 'cancelled'])
|
||||
|
||||
/** seq 比较:仅当新事件 seq 严格大于已见 seq 才视为“更新”。 */
|
||||
export function isStaleSeq(lastSeq, nextSeq) {
|
||||
if (lastSeq === null || lastSeq === undefined) return false
|
||||
if (!Number.isFinite(nextSeq)) return true
|
||||
return nextSeq <= lastSeq
|
||||
}
|
||||
|
||||
/** 乱序/重复事件:达到终态后任何“回到活动态”的事件都必须忽略,而不是报错中断处理。 */
|
||||
export function isRegressingEvent(currentStatus, nextStatus) {
|
||||
if (TERMINAL_TASK_STATES.includes(currentStatus)) return currentStatus !== nextStatus
|
||||
return false
|
||||
}
|
||||
|
||||
function transition(state, next, extra = {}) {
|
||||
assertTransition('task', state, next)
|
||||
return next
|
||||
}
|
||||
|
||||
function requireString(value, field) {
|
||||
if (typeof value !== 'string' || value.trim() === '') {
|
||||
throw new TaskError('INVALID_INPUT', `${field} 必须是非空字符串`)
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
function requireTask(task) {
|
||||
if (task === null || typeof task !== 'object' || typeof task.id !== 'string') {
|
||||
throw new TaskError('INVALID_TASK', '任务记录不合法')
|
||||
}
|
||||
return task
|
||||
}
|
||||
|
||||
/**
|
||||
* createTask:只建草稿。draft 不等于入队,校验通过且授权有效后才 startTask 入队。
|
||||
* ownerRoleId 与 sourceRoleId 都必须是已知席,来源席默认丞相。
|
||||
*/
|
||||
export function createTask(options, deps = {}) {
|
||||
const { projectId, title, objective, acceptance = [], ownerRoleId, sourceRoleId = 'lead', originMessageRef = null, scope = null, constraints = [], returnTarget = null } = options ?? {}
|
||||
requireString(projectId, 'projectId')
|
||||
requireString(title, 'title')
|
||||
requireString(objective, 'objective')
|
||||
if (!isRoleId(ownerRoleId)) throw new TaskError('INVALID_ROLE', `未知主责部门: ${String(ownerRoleId)}`)
|
||||
if (!isRoleId(sourceRoleId)) throw new TaskError('INVALID_ROLE', `未知来源部门: ${String(sourceRoleId)}`)
|
||||
const id = typeof deps.newTaskId === 'function' ? deps.newTaskId() : undefined
|
||||
const stamp = typeof deps.now === 'function' ? deps.now() : new Date().toISOString()
|
||||
return {
|
||||
...(id === undefined ? {} : { id }),
|
||||
projectId,
|
||||
title,
|
||||
objective,
|
||||
acceptance: Array.isArray(acceptance) ? [...acceptance] : [String(acceptance)],
|
||||
constraints: Array.isArray(constraints) ? [...constraints] : [],
|
||||
scope: scope ?? null,
|
||||
ownerRoleId,
|
||||
sourceRoleId,
|
||||
originMessageRef,
|
||||
returnTarget,
|
||||
status: 'draft',
|
||||
activeAttemptId: null,
|
||||
attempts: [],
|
||||
startedAt: null,
|
||||
endedAt: null,
|
||||
reportReceivedAt: null,
|
||||
needsAttentionReason: null,
|
||||
failureReason: null,
|
||||
waitingReason: null,
|
||||
revision: 1,
|
||||
createdAt: stamp,
|
||||
updatedAt: stamp,
|
||||
}
|
||||
}
|
||||
|
||||
/** 入队:唯一需要的前置是 draft,或者 waiting_input 拿到补充。 */
|
||||
export function startTask(task, deps = {}) {
|
||||
requireTask(task)
|
||||
if (task.status !== 'draft' && task.status !== 'waiting_input') {
|
||||
throw new TaskError('INVALID_STATE', `只有草稿或待补充的任务可以入队,当前 ${task.status}`)
|
||||
}
|
||||
const stamp = stampOf(deps)
|
||||
return {
|
||||
...task,
|
||||
status: transition(task.status, 'queued'),
|
||||
waitingReason: null,
|
||||
revision: task.revision + 1,
|
||||
updatedAt: stamp,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* beginAttempt:队列中的任务进入执行,并绑定一次尝试。
|
||||
* 每次重试都是新 attempt,旧尝试(及旧结果引用)保留,不覆盖成“第一次就成功”。
|
||||
*/
|
||||
export function beginAttempt(task, attempt, deps = {}) {
|
||||
requireTask(task)
|
||||
if (task.status !== 'queued' && task.status !== 'waiting_input' && task.status !== 'needs_attention' && task.status !== 'running') {
|
||||
throw new TaskError('INVALID_STATE', `任务 ${task.status} 不能开始新的尝试`)
|
||||
}
|
||||
// 是否“仍有活动尝试”不能只看 activeAttemptId 是否为空:
|
||||
// 取消/失败/对账后,Attempt 已转 cancelled/failed/succeeded 终态,但任务的 activeAttemptId 仍指向它(保留审计),
|
||||
// 若只看非空就会把取消后的重试挡在 ACTIVE_ATTEMPT 上。deps.attemptLookup 由调用方注入(core 不读 store),
|
||||
// 只有明确查到“非终态”尝试时才算有活动尝试;查不到(undefined/null)时保持旧行为,按非空处理。
|
||||
// 另:attempt 的 unknown 是待对账状态,不算终态,仍会挡住重试。
|
||||
const hasActiveAttempt = task.activeAttemptId !== null && task.activeAttemptId !== undefined
|
||||
&& !isSettledAttempt(task.activeAttemptId, deps)
|
||||
// running 下换尝试等于重试:必须先把旧尝试对账(失败/取消),否则两次运行会同时往一个任务里写结果。
|
||||
if (task.status === 'running' && hasActiveAttempt) {
|
||||
throw new TaskError('ACTIVE_ATTEMPT', '当前尝试仍在运行,先对账再重试')
|
||||
}
|
||||
if (attempt === null || typeof attempt !== 'object' || typeof attempt.id !== 'string') {
|
||||
throw new TaskError('INVALID_ATTEMPT', '尝试记录不合法')
|
||||
}
|
||||
if (attempt.projectId !== task.projectId) {
|
||||
throw new TaskError('CROSS_PROJECT', '尝试与任务不属于同一项目')
|
||||
}
|
||||
if (attempt.taskId !== task.id) {
|
||||
throw new TaskError('CROSS_TASK', '尝试挂在别的任务上')
|
||||
}
|
||||
if (task.status === 'needs_attention' && hasActiveAttempt) {
|
||||
throw new TaskError('ACTIVE_ATTEMPT', '仍有未对账的尝试,先完成或标记失败')
|
||||
}
|
||||
const stamp = stampOf(deps)
|
||||
return {
|
||||
...task,
|
||||
status: transition(task.status, 'running'),
|
||||
activeAttemptId: attempt.id,
|
||||
attempts: [...task.attempts, attempt.id],
|
||||
startedAt: task.startedAt ?? stamp,
|
||||
needsAttentionReason: null,
|
||||
waitingReason: null,
|
||||
revision: task.revision + 1,
|
||||
updatedAt: stamp,
|
||||
}
|
||||
}
|
||||
|
||||
/** 结构化报告是否“可信”:summary 非空、成果引用形状正确、检查是真实结果而非空话。 */
|
||||
export function validateReport(report) {
|
||||
const errors = []
|
||||
if (report === null || typeof report !== 'object') return ['报告必须是对象']
|
||||
if (!report.attemptId || typeof report.attemptId !== 'string') errors.push('缺少 attemptId')
|
||||
if (!report.taskId || typeof report.taskId !== 'string') errors.push('缺少 taskId')
|
||||
if (typeof report.summary !== 'string' || report.summary.trim() === '') errors.push('结果摘要为空')
|
||||
if (report.artifactRefs !== undefined) {
|
||||
if (!Array.isArray(report.artifactRefs)) errors.push('artifactRefs 必须是数组')
|
||||
else {
|
||||
for (const ref of report.artifactRefs) {
|
||||
if (typeof ref !== 'string' || !ref.startsWith('art_')) errors.push(`成果引用形状非法: ${String(ref)}`)
|
||||
}
|
||||
}
|
||||
}
|
||||
if (report.checks !== undefined && !Array.isArray(report.checks)) errors.push('checks 必须是数组')
|
||||
return errors
|
||||
}
|
||||
|
||||
/**
|
||||
* 三条完成条件各占一票,缺一条都不能标 completed:
|
||||
* 1. 可信结构化报告(有摘要、有检查、没有未解决阻塞)
|
||||
* 2. 宿主运行终态成功(由调用方从宿主取得,不能猜“空闲=成功”)
|
||||
* 3. 成果引用有效(引用指向本项目现存成果,或被显式标为不可用)
|
||||
*/
|
||||
export function checkCompletion(input) {
|
||||
const { report = null, runTerminal = null, artifactRefs = [], artifactLookup = null } = input ?? {}
|
||||
const blockers = []
|
||||
let reportOk = false
|
||||
if (report !== null) {
|
||||
const errors = validateReport(report)
|
||||
if (errors.length > 0) blockers.push(...errors)
|
||||
else if (typeof report.blockedReason === 'string' && report.blockedReason.trim() !== '') {
|
||||
blockers.push('报告标记了阻塞原因')
|
||||
} else reportOk = true
|
||||
} else {
|
||||
blockers.push('未收到结构化报告')
|
||||
}
|
||||
const runOk = runTerminal === 'succeeded'
|
||||
if (runTerminal === null) blockers.push('宿主运行尚未结束')
|
||||
else if (!runOk) blockers.push(`宿主运行终态为 ${String(runTerminal)}`)
|
||||
const refs = Array.isArray(artifactRefs) ? artifactRefs : []
|
||||
const invalidRefs = []
|
||||
for (const ref of refs) {
|
||||
if (typeof ref !== 'string' || !ref.startsWith('art_')) invalidRefs.push(String(ref))
|
||||
else if (typeof artifactLookup === 'function') {
|
||||
const artifact = artifactLookup(ref)
|
||||
if (artifact === undefined || artifact === null) invalidRefs.push(ref)
|
||||
else if (artifact.verification?.status === 'missing') invalidRefs.push(ref)
|
||||
}
|
||||
}
|
||||
if (invalidRefs.length > 0) blockers.push(`成果引用无效: ${invalidRefs.join(', ')}`)
|
||||
// 纯分析任务允许没有文件,所以“引用为空”本身不算失败,但登记结果时不能伪造附件。
|
||||
return { reportOk, runOk, refsValid: invalidRefs.length === 0, blockers, ok: reportOk && runOk && invalidRefs.length === 0 }
|
||||
}
|
||||
|
||||
/**
|
||||
* 完成判定三分支:
|
||||
* - 报告 + 终态成功 + 成果有效 → completed
|
||||
* - 只有报告(运行未结束) → 保持 running 等终态(waiting 只是“候选结果已存”)
|
||||
* - 只有终态(无报告) → needs_attention,提供补报入口,不显示已完成
|
||||
*/
|
||||
export function evaluateCompletion(task, input, deps = {}) {
|
||||
return decide(task, { kind: 'completion', ...input }, deps)
|
||||
}
|
||||
|
||||
/**
|
||||
* 统一事件入口:先按 seq 去重、再按状态机判定。旧 seq 或终态后的事件返回
|
||||
* { applied:false, stale:true, task },让调用方知道“什么都没变”而不是误以为写入失败。
|
||||
*/
|
||||
export function decide(task, event, deps = {}) {
|
||||
requireTask(task)
|
||||
if (event === null || typeof event !== 'object') throw new TaskError('INVALID_EVENT', '事件必须是对象')
|
||||
const nextSeq = event.seq
|
||||
if (nextSeq !== undefined && isStaleSeq(task.lastSeq ?? null, nextSeq)) {
|
||||
return { applied: false, stale: true, task }
|
||||
}
|
||||
const stamp = stampOf(deps)
|
||||
const base = nextSeq === undefined ? task : { ...task, lastSeq: nextSeq }
|
||||
const commit = (next) => ({
|
||||
applied: true,
|
||||
stale: false,
|
||||
task: applyStamp({ ...next, id: task.id, projectId: task.projectId }, next, stamp, base),
|
||||
})
|
||||
|
||||
switch (event.kind) {
|
||||
case 'completion': {
|
||||
if (isTerminal('task', task.status)) return { applied: false, stale: true, task, reason: '任务已终态' }
|
||||
const verdict = checkCompletion(event)
|
||||
if (!verdict.reportOk && verdict.runOk) {
|
||||
return commit({
|
||||
...base,
|
||||
status: transition(task.status, 'needs_attention'),
|
||||
needsAttentionReason: '宿主运行已结束但没有有效的结构化报告',
|
||||
reportReceivedAt: base.reportReceivedAt ?? null,
|
||||
})
|
||||
}
|
||||
// 用户主动停止的会话,运行终态是 cancelled 而不是"成功但没报告":
|
||||
// 这一票足以把任务收成 cancelled,不需要也不可能再等到结构化报告。
|
||||
if (event.runTerminal === 'cancelled' && !verdict.reportOk) {
|
||||
return commit({ ...base, status: transition(task.status, 'cancelled'), endedAt: stamp })
|
||||
}
|
||||
if (!verdict.ok) {
|
||||
// 报告不完整:只记录候选报告,等下一次带完整信息的事件。
|
||||
return { applied: false, stale: false, task: base, reason: verdict.blockers.join('; '), verdict }
|
||||
}
|
||||
return commit({
|
||||
...base,
|
||||
status: transition(task.status, 'completed'),
|
||||
reportReceivedAt: stamp,
|
||||
needsAttentionReason: null,
|
||||
failureReason: null,
|
||||
})
|
||||
}
|
||||
case 'report': {
|
||||
if (isTerminal('task', task.status)) return { applied: false, stale: true, task }
|
||||
const errors = validateReport(event.report)
|
||||
if (errors.length > 0) throw new TaskError('INVALID_REPORT', errors.join('; '), { errors })
|
||||
// 报告先到:保存候选结果,等待宿主终态。
|
||||
return commit({ ...base, reportReceivedAt: stamp, needsAttentionReason: null })
|
||||
}
|
||||
case 'run_terminal': {
|
||||
if (isTerminal('task', task.status)) return { applied: false, stale: true, task }
|
||||
const state = event.runTerminal
|
||||
if (state === 'succeeded') {
|
||||
// 只有报告已经到达,才可能在这里直接完成;否则留给 completion 判定。
|
||||
if (base.reportReceivedAt !== null && base.status === 'running') {
|
||||
return commit({ ...base, status: transition(task.status, 'completed') })
|
||||
}
|
||||
return { applied: false, stale: false, task: base, reason: '等待结构化报告' }
|
||||
}
|
||||
if (state === 'cancelled') {
|
||||
return commit({ ...base, status: transition(task.status, 'cancelled'), endedAt: stamp })
|
||||
}
|
||||
return commit({
|
||||
...base,
|
||||
status: transition(task.status, 'needs_attention'),
|
||||
needsAttentionReason: `宿主运行终态为 ${String(state)}`,
|
||||
})
|
||||
}
|
||||
case 'input_required': {
|
||||
if (task.status !== 'running' && task.status !== 'queued') {
|
||||
return { applied: false, stale: false, task, reason: `任务 ${task.status} 不接受待补充状态` }
|
||||
}
|
||||
return commit({ ...base, status: transition(task.status, 'waiting_input'), waitingReason: String(event.reason ?? '') })
|
||||
}
|
||||
case 'input_supplied': {
|
||||
if (task.status !== 'waiting_input') return { applied: false, stale: false, task, reason: '任务不在待补充状态' }
|
||||
return commit({ ...base, status: transition(task.status, 'running'), waitingReason: null })
|
||||
}
|
||||
case 'retry': {
|
||||
if (task.status !== 'failed' && task.status !== 'cancelled') {
|
||||
return { applied: false, stale: false, task, reason: '只有失败或已取消的任务可以重试(新任务)' }
|
||||
}
|
||||
throw new TaskError('RETRY_REQUIRES_NEW_TASK', '失败/取消后的重试必须创建新任务与新尝试,不能复活旧记录')
|
||||
}
|
||||
default:
|
||||
throw new TaskError('UNKNOWN_EVENT', `未知事件类型: ${String(event.kind)}`)
|
||||
}
|
||||
}
|
||||
|
||||
/** 结束时间只写一次:重复到达的终态事件不应改动“最后一次改动时间”。 */
|
||||
function applyStamp(task, next, stamp, base) {
|
||||
const now = { ...base, ...next, updatedAt: stamp }
|
||||
// completed/failed/cancelled 结束时间只写一次,重复写入会伪造“最后一次改动时间”。
|
||||
if (TERMINAL_TASK_STATES.includes(now.status) && now.endedAt === null) now.endedAt = stamp
|
||||
if (!Number.isFinite(now.revision) || now.revision < 1) now.revision = 1
|
||||
else if (now.status !== task.status) now.revision = task.revision + 1
|
||||
return now
|
||||
}
|
||||
|
||||
function stampOf(deps) {
|
||||
return typeof deps.now === 'function' ? deps.now() : new Date().toISOString()
|
||||
}
|
||||
|
||||
/**
|
||||
* activeAttemptId 指向的尝试是否已对账(终态)。
|
||||
* 调用方通过 deps.attemptLookup(attemptId) 提供当前 Attempt 记录;core 不直接读 store。
|
||||
* unknown 是“待核对宿主”的中间态,不是终态,因此仍然算活动尝试。
|
||||
*/
|
||||
function isSettledAttempt(attemptId, deps) {
|
||||
const lookup = deps?.attemptLookup
|
||||
if (typeof lookup !== 'function') return false
|
||||
const record = lookup(attemptId)
|
||||
if (record === null || record === undefined || typeof record !== 'object') return false
|
||||
return isTerminal('attempt', record.state)
|
||||
}
|
||||
|
||||
// ---------- 便捷包装:每个都只调用 decide,签名简单便于调用方阅读 ----------
|
||||
|
||||
export function requestInput(task, reason, deps = {}) {
|
||||
return decide(task, { kind: 'input_required', reason, seq: deps.seq }, deps)
|
||||
}
|
||||
|
||||
export function supplyInput(task, deps = {}) {
|
||||
return decide(task, { kind: 'input_supplied', seq: deps.seq }, deps)
|
||||
}
|
||||
|
||||
export function completeTask(task, input, deps = {}) {
|
||||
return decide(task, { kind: 'completion', ...input, seq: input?.seq }, deps)
|
||||
}
|
||||
|
||||
/** 失败必须带原因:没有原因的失败在详情页无法给出恢复入口。 */
|
||||
export function failTask(task, reason, deps = {}) {
|
||||
requireTask(task)
|
||||
requireString(reason, 'reason')
|
||||
if (isTerminal('task', task.status)) {
|
||||
return { applied: false, stale: true, task, reason: '任务已终态' }
|
||||
}
|
||||
const stamp = stampOf(deps)
|
||||
return {
|
||||
applied: true,
|
||||
stale: false,
|
||||
task: {
|
||||
...task,
|
||||
status: transition(task.status, 'failed'),
|
||||
failureReason: reason,
|
||||
updatedAt: stamp,
|
||||
endedAt: task.endedAt ?? stamp,
|
||||
revision: task.revision + 1,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/** 取消是请求,不是结果:这里只落“已取消”的业务结论,宿主的 cancel_requested 另记在 attempt。 */
|
||||
export function cancelTask(task, reason = '用户取消', deps = {}) {
|
||||
requireTask(task)
|
||||
if (isTerminal('task', task.status)) {
|
||||
return { applied: false, stale: true, task, reason: '任务已终态' }
|
||||
}
|
||||
const stamp = stampOf(deps)
|
||||
return {
|
||||
applied: true,
|
||||
stale: false,
|
||||
task: {
|
||||
...task,
|
||||
status: transition(task.status, 'cancelled'),
|
||||
failureReason: task.failureReason ?? null,
|
||||
cancelReason: reason,
|
||||
updatedAt: stamp,
|
||||
endedAt: task.endedAt ?? stamp,
|
||||
revision: task.revision + 1,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/** 把 decide 的结果套到 store 上:只有 applied 才写,避免陈旧事件产生 revision 抖动。 */
|
||||
export function applyDecision(store, taskId, decision) {
|
||||
if (store === undefined || store === null) throw new TaskError('INVALID_STORE', '需要 store')
|
||||
if (decision === null || typeof decision !== 'object') throw new TaskError('INVALID_DECISION', '判定结果不合法')
|
||||
if (decision.applied !== true) return decision
|
||||
const saved = store.updateTask(decision.task)
|
||||
return { ...decision, task: saved }
|
||||
}
|
||||
|
||||
/** 任务是否仍在进行(UI 需要区分终态与活动态,但不允许显示百分比)。 */
|
||||
export function isOpenTask(task) {
|
||||
return task !== null && typeof task === 'object' && isState('task', task.status) && !isTerminal('task', task.status)
|
||||
}
|
||||
Loading…
Reference in New Issue