Import vendor/dsh-sansheng-liubu/workbench/core/tasks.mjs

This commit is contained in:
QQ 2026-11-12 00:14:34 +08:00
parent 6e293a8f6b
commit 2c639e7331
1 changed files with 436 additions and 0 deletions

View File

@ -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)
}