@mokuyoaxis/dsh-iris 0.1.2 → 0.1.3

package/lib/index.js

@@ -21,10 +21,11 @@ import { serveRender, BrowserHtmlRenderer } from './render.js';
 import { ensurePrivateDir, hardenPrivateTree } from './private-storage.js';
 import { guarded } from './guard.js';
 import { longOcr } from './ocr.js';
-import { runAction, listActions } from './actions.js';
+import { runAction, listActions, taskPollDeps } from './actions.js';
 import { ffmpegAvailable, extractFrames, probeVideo, extractAudioTrack } from './media-probe.js';
 import { buildContactSheet, summarizeMedia } from './summarize.js';
 import { registerBundledSkills } from './bundled-skills.js';
+export { doctor, formatDoctorReport } from './doctor.js';
 
 const MEDIA_TYPES = {
   '.png': 'image/png',
@@ -81,48 +82,47 @@ function mountIrisRoutes(routeCtx) {
   }
 }
 
-/** 盯守依赖：按能力给轮询间隔与结果转存扩展名 */
+/** 向后兼容导出；真实实现与人工接管共用 actions.taskPollDeps。 */
 export function pollDeps(provider, cap) {
-  if (cap === 'transcribe') {
-    // 转写任务的结果在 transcription_text 而非 urls——重启接管必须走专用轮询器，
-    // 否则 pollTask 拿到空 urls，盯守会「成功」但转写文本静默丢失。
-    // （与 iris_transcribe_audio 工具内的盯守依赖保持同构。）
-    return {
-      key: () => provider.apiKey,
-      poll: async ({ key, remoteTaskId }) => {
-        const r = await adapters.pollTranscriptionTask({ key, baseUrl: provider.baseUrl, remoteTaskId });
-        return { done: r.done, ok: r.ok, urls: r.text ? [r.text] : [], message: r.message };
-      },
-      intervalMs: 2500,
-      onSuccess: async (t, r) => {
-        tasks.update(t.id, { transcribeText: (r.urls && r.urls.join('')) || '' });
-        return [];
-      }
-    };
+  return taskPollDeps(provider, { cap });
+}
+
+/** 旧 status 与 Task v2 事实轴共同决定工具是否应停止等待。 */
+export function taskWaitFinished(task) {
+  if (!task) return false;
+  if (task.status !== 'running') return true;
+  return tasks.isV2Task(task) && task.phase === 'terminal';
+}
+
+/** 把 v2 正交事实转换成不会误导用户的工具错误；空串表示已成功可交付。 */
+export function taskTerminalProblem(task, label = '任务') {
+  if (!task) return label + '记录不存在';
+  if (!tasks.isV2Task(task)) {
+    if (task.status === 'canceled') return '已取消';
+    if (task.status !== 'succeeded') return label + '失败：' + (task.error || '未知原因');
+    return '';
   }
-  return {
-    key: () => provider.apiKey,
-    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
-    intervalMs: cap === 'video' ? 6000 : 2500,
-    onSuccess: async (t, r) => {
-      fs.mkdirSync(outputDir(), { recursive: true });
-      const names = [];
-      for (const url of r.urls || []) {
-        const name = `${t.id}-${names.length}.${adapters.extFromUrl(url, cap === 'video' ? 'mp4' : 'png')}`;
-        await adapters.downloadTo(url, path.join(outputDir(), name));
-        names.push(name);
-      }
-      // 登记媒体链接（token 授权），对话流里可点播
-      for (const n of names) registerMedia(t.id, path.join(outputDir(), n));
-      return names;
-    }
-  };
+  if (task.outcome === 'succeeded' && task.deliveryState === 'ready') return '';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'failed') {
+    return label + '已成功，但产物交付失败：' + (task.error || '可稍后重新交付；禁止重新生成');
+  }
+  if (task.acceptance === 'unknown' || task.outcome === 'unknown') {
+    return label + '的远端受理或结果状态未知：' + (task.error || '禁止自动重提，请先人工确认');
+  }
+  if (task.cancelState === 'unknown') {
+    return label + '的远端取消状态未知：' + (task.error || '请先人工确认');
+  }
+  if (task.outcome === 'canceled') return '已取消';
+  if (task.outcome === 'failed') return label + '失败：' + (task.error || '供应商明确返回失败');
+  return task.phase === 'terminal'
+    ? label + '需要人工处理：' + (task.error || '状态未能自动收口')
+    : '';
 }
 
 /**
  * 在工具调用内同步等待任务到终态。
  * @returns 终态任务记录；null = 等待超时（任务已转后台继续盯守）
- * @throws 取消时抛错并标记 canceled
+ * @throws 取消时抛错并记录保守取消事实
  */
 async function awaitTerminal(taskId, { timeoutMs, signal }) {
   const deadline = Date.now() + timeoutMs;
@@ -132,7 +132,7 @@ async function awaitTerminal(taskId, { timeoutMs, signal }) {
       throw new Error('已取消');
     }
     const t = tasks.get(taskId);
-    if (t && t.status !== 'running') return t;
+    if (taskWaitFinished(t)) return t;
     if (Date.now() > deadline) return null;
     await new Promise((r) => setTimeout(r, 1000));
   }
@@ -256,14 +256,14 @@ export async function apply(ctx) {
       if (!prompt) throw new Error('iris: prompt 不能为空');
       const submitted = await runAction(ctx, 'image', args, { signal: exec.signal });
       let final = tasks.get(submitted.taskId);
-      if (final && final.status === 'running') {
+      if (final && !taskWaitFinished(final)) {
         final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal: exec.signal });
       }
       if (!final) {
         return { blocks: [{ type: 'text', text: `[iris] 图像任务仍在后台盯守（task: ${submitted.taskId}）。稍后可用 iris_task_status 查询进度与文件路径。` }] };
       }
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('生成失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '图像生成');
+      if (terminalProblem) throw new Error(terminalProblem);
 
       const files = (final.files || []).map((f) => path.join(outputDir(), f));
       const blocks = [];
@@ -329,8 +329,8 @@ export async function apply(ctx) {
         return `[iris] 视频任务已提交并转入后台盯守（task: ${submitted.taskId}，remoteTask: ${submitted.remoteTaskId}）。\n` +
           '渲染通常需要数分钟；完成后用 iris_task_status 查询产物路径。';
       }
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('视频生成失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '视频生成');
+      if (terminalProblem) throw new Error(terminalProblem);
       const paths = (final.files || []).map((f) => path.join(outputDir(), f));
       const links = mediaLinksOf(final);
       const secs = Math.round((Date.now() - new Date(final.createdAt).getTime()) / 1000);
@@ -359,7 +359,8 @@ export async function apply(ctx) {
     async execute(args, exec) {
       const submitted = await runAction(ctx, 'tts', args, { signal: exec.signal });
       const final = tasks.get(submitted.taskId);
-      if (!final || final.status !== 'succeeded') throw new Error('语音合成失败：' + ((final && final.error) || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '语音合成');
+      if (terminalProblem) throw new Error(terminalProblem);
       const fileName = (final.files || [])[0];
       const p = path.join(outputDir(), fileName);
       const media = (final.media || [])[0];
@@ -386,8 +387,8 @@ export async function apply(ctx) {
       const submitted = await runAction(ctx, 'transcribe', args, { signal: exec.signal });
       const final = await awaitTerminal(submitted.taskId, { timeoutMs: 120000, signal: exec.signal });
       if (!final) return `[iris] 音频转写任务已提交并转入后台（task: ${submitted.taskId}）。完成后用 iris_task_status 查询。`;
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('转写失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '音频转写');
+      if (terminalProblem) throw new Error(terminalProblem);
       return `[iris] 音频转写完成（${submitted.model || final.model}）：\n${final.transcribeText || ''}`;
     }
   });

package/lib/provider-contract.js

@@ -0,0 +1,234 @@
+'use strict';
+/**
+ * v0.1.3 最小 Provider 提交契约。
+ *
+ * 这里只定义提交结果、脱敏错误和候选调度边界，不依赖 DSH、配置存储或具体供应商。
+ */
+import { allowsAutomaticFailover } from './task-semantics.js';
+import { parseModelRef } from './models.js';
+
+export const SUBMISSION_KINDS = Object.freeze([
+  'completed',
+  'accepted',
+  'not_accepted',
+  'acceptance_unknown'
+]);
+
+export const PROVIDER_STAGES = Object.freeze([
+  'validate',
+  'prepare',
+  'upload',
+  'submit',
+  'response',
+  'poll',
+  'cancel',
+  'download',
+  'persist',
+  'emit'
+]);
+
+export const PROVIDER_ERROR_CATEGORIES = Object.freeze([
+  'invalid_request',
+  'authentication',
+  'quota',
+  'rate_limit',
+  'network',
+  'timeout',
+  'aborted',
+  'provider',
+  'protocol',
+  'local_io',
+  'unknown'
+]);
+
+const ACCEPTANCE = new Set(['not_accepted', 'accepted', 'unknown']);
+const SECRET_QUERY = /([?&](?:access[_-]?key|api[_-]?key|authorization|credential|signature|token)=)[^&#\s]+/gi;
+const BEARER = /\bBearer\s+[^\s,;]+/gi;
+const API_KEY = /\bsk-[A-Za-z0-9_-]{8,}\b/g;
+const JSON_SECRET = /(["']?(?:api[_-]?key|authorization|access[_-]?token|secret)["']?\s*[:=]\s*["']?)[^"',\s}]+/gi;
+const POSIX_PATH = /(^|[\s("'=])\/(?:[^/\s"'`,;)}\]]+\/)*[^/\s"'`,;)}\]]+/gm;
+const WINDOWS_PATH = /\b[A-Za-z]:\\(?:[^\\\s"'`,;)}\]]+\\)*[^\\\s"'`,;)}\]]+/g;
+
+export function redactProviderMessage(value, maxLength = 1000) {
+  return String(value || '供应商操作失败')
+    .replace(SECRET_QUERY, '$1[REDACTED]')
+    .replace(BEARER, 'Bearer [REDACTED]')
+    .replace(API_KEY, '[REDACTED]')
+    .replace(JSON_SECRET, '$1[REDACTED]')
+    .replace(WINDOWS_PATH, '[PATH]')
+    .replace(POSIX_PATH, '$1[PATH]')
+    .slice(0, maxLength);
+}
+
+function enumValue(values, value, fallback) {
+  return values.includes(value) ? value : fallback;
+}
+
+function integerOrUndefined(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number >= 100 && number <= 599 ? number : undefined;
+}
+
+/** 只返回允许持久化的结构化字段，不包含 cause、stack、请求体或响应正文。 */
+export function providerErrorRecord(error, overrides = {}) {
+  const source = error && typeof error === 'object' ? error : {};
+  const acceptance = ACCEPTANCE.has(overrides.acceptance)
+    ? overrides.acceptance
+    : (ACCEPTANCE.has(source.acceptance) ? source.acceptance : 'unknown');
+  const out = {
+    stage: enumValue(PROVIDER_STAGES, overrides.stage || source.stage, 'submit'),
+    category: enumValue(PROVIDER_ERROR_CATEGORIES, overrides.category || source.category, 'unknown'),
+    acceptance,
+    retryable: Boolean(overrides.retryable ?? source.retryable),
+    safeMessage: redactProviderMessage(overrides.safeMessage || source.safeMessage || source.message || error)
+  };
+  const httpStatus = integerOrUndefined(overrides.httpStatus ?? source.httpStatus ?? source.status);
+  if (httpStatus !== undefined) out.httpStatus = httpStatus;
+  const providerCode = overrides.providerCode ?? source.providerCode ?? source.code;
+  if (typeof providerCode === 'string' && providerCode.trim()) {
+    out.providerCode = redactProviderMessage(providerCode.trim(), 128);
+  }
+  return out;
+}
+
+export class ProviderContractError extends Error {
+  constructor(message, details = {}) {
+    super(redactProviderMessage(message));
+    this.name = 'ProviderContractError';
+    Object.assign(this, providerErrorRecord({ ...details, message }, details));
+  }
+
+  toJSON() {
+    return providerErrorRecord(this);
+  }
+}
+
+export function normalizeSubmissionResult(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('Provider submit 必须返回结构化结果');
+  }
+  if (!SUBMISSION_KINDS.includes(value.kind)) {
+    throw new TypeError('未知 Provider submit kind: ' + String(value.kind));
+  }
+  if (value.kind === 'completed') {
+    return { kind: 'completed', acceptance: 'accepted', value: value.value };
+  }
+  if (value.kind === 'accepted') {
+    const remoteTaskId = String(value.remoteTaskId || '').trim();
+    if (!remoteTaskId) throw new TypeError('accepted 结果必须包含 remoteTaskId');
+    return { kind: 'accepted', acceptance: 'accepted', remoteTaskId };
+  }
+  const acceptance = value.kind === 'not_accepted' ? 'not_accepted' : 'unknown';
+  return {
+    kind: value.kind,
+    acceptance,
+    error: providerErrorRecord(value.error, { acceptance })
+  };
+}
+
+export function resultFromThrown(error) {
+  const safe = providerErrorRecord(error);
+  if (safe.acceptance === 'not_accepted') {
+    return normalizeSubmissionResult({ kind: 'not_accepted', error: safe });
+  }
+  return normalizeSubmissionResult({ kind: 'acceptance_unknown', error: safe });
+}
+
+function safeAttemptSnapshot(attempt, result) {
+  const out = {
+    id: attempt.id,
+    ordinal: attempt.ordinal,
+    providerId: attempt.providerId,
+    model: attempt.model,
+    acceptance: result.acceptance,
+    resultKind: result.kind
+  };
+  if (result.remoteTaskId) out.remoteTaskId = result.remoteTaskId;
+  if (result.error) out.error = result.error;
+  return out;
+}
+
+/**
+ * 串行尝试 Provider 候选，并强制执行写前记录与受理边界。
+ *
+ * beforeAttempt 必须把 Attempt 写入持久化存储后再返回。afterResult 的落盘失败
+ * 会作为 localError 返回并立即停止；即使结果明确未受理，也不在证据未落盘时继续。
+ */
+export async function submitWithAcceptanceBoundary(candidates, input, hooks = {}) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    throw new TypeError('至少需要一个 Provider 候选');
+  }
+  if (typeof hooks.beforeAttempt !== 'function') {
+    throw new TypeError('beforeAttempt 写前持久化 Hook 必填');
+  }
+
+  const attempts = [];
+  for (let index = 0; index < candidates.length; index++) {
+    const candidate = candidates[index];
+    if (!candidate || typeof candidate.submit !== 'function') {
+      throw new TypeError(`Provider 候选 ${index + 1} 缺少 submit()`);
+    }
+    const initial = {
+      ordinal: index + 1,
+      providerId: String(candidate.id || '').trim(),
+      model: String(candidate.model || '').trim(),
+      acceptance: 'none',
+      stage: 'submitting'
+    };
+    const parsedModel = parseModelRef(initial.model);
+    if (!initial.providerId || !parsedModel || parsedModel.providerId !== initial.providerId) {
+      throw new TypeError(`Provider 候选 ${index + 1} 缺少 id、复合 model，或两者身份不一致`);
+    }
+
+    // 写前 Hook 失败时尚未调用供应商；错误原样抛出，由本地持久化层处理。
+    const persisted = await hooks.beforeAttempt({ ...initial });
+    const attemptId = persisted && typeof persisted.id === 'string' ? persisted.id.trim() : '';
+    if (!attemptId) throw new TypeError('beforeAttempt 必须返回已持久化的稳定 Attempt ID');
+    // Hook 只能补充持久化身份和可选元数据，不能改写候选 Provider、模型或 ordinal。
+    const attempt = {
+      ...initial,
+      id: attemptId,
+      ...(typeof persisted.startedAt === 'string' ? { startedAt: persisted.startedAt } : {}),
+      ...(typeof persisted.idempotencyKey === 'string' ? { idempotencyKey: persisted.idempotencyKey } : {})
+    };
+
+    let result;
+    try {
+      result = normalizeSubmissionResult(await candidate.submit(input, { attempt: { ...attempt } }));
+    } catch (error) {
+      result = resultFromThrown(error);
+    }
+
+    const snapshot = safeAttemptSnapshot(attempt, result);
+    attempts.push(snapshot);
+    if (typeof hooks.afterResult === 'function') {
+      try {
+        await hooks.afterResult({ ...snapshot });
+      } catch (error) {
+        return {
+          candidate,
+          result,
+          attempts,
+          localError: providerErrorRecord(error, {
+            stage: 'persist',
+            category: 'local_io',
+            acceptance: result.acceptance
+          })
+        };
+      }
+    }
+
+    if (!allowsAutomaticFailover(result)) {
+      return { candidate, result, attempts, localError: null };
+    }
+  }
+
+  return {
+    candidate: null,
+    result: attempts.length
+      ? { kind: 'not_accepted', acceptance: 'not_accepted', error: attempts.at(-1).error }
+      : null,
+    attempts,
+    localError: null
+  };
+}

package/lib/task-semantics.js

@@ -0,0 +1,209 @@
+'use strict';
+/**
+ * Iris Task/Attempt v2 的纯语义契约。
+ *
+ * 本模块只定义名称、派生规则和不可违反的约束，不直接读写任务或调用供应商；
+ * tasks、API 与 Doctor 共同消费这里的语义，避免各自解释状态。
+ */
+
+export const TASK_PHASES = Object.freeze(['queued', 'submitting', 'accepted', 'running', 'terminal']);
+export const ACCEPTANCE_STATES = Object.freeze(['none', 'not_accepted', 'accepted', 'unknown']);
+export const WATCH_STATES = Object.freeze(['idle', 'active', 'suspended', 'exhausted']);
+export const TASK_OUTCOMES = Object.freeze(['none', 'succeeded', 'failed', 'canceled', 'unknown']);
+export const DELIVERY_STATES = Object.freeze(['none', 'pending', 'downloading', 'ready', 'failed']);
+export const CANCEL_STATES = Object.freeze(['none', 'requested', 'remote_confirmed', 'local_confirmed', 'unknown']);
+
+export const USER_STATES = Object.freeze([
+  'queued',
+  'running',
+  'watching_paused',
+  'needs_attention',
+  'artifact_unavailable',
+  'succeeded',
+  'failed',
+  'canceled'
+]);
+
+const includes = (values, value) => values.includes(value);
+
+/**
+ * 自动 failover 的唯一许可条件。
+ * retryable、HTTP 状态或网络错误本身都不能推翻受理边界。
+ */
+export function allowsAutomaticFailover(attempt) {
+  return Boolean(attempt && attempt.acceptance === 'not_accepted');
+}
+
+/**
+ * 给仍只理解 running/succeeded/failed/canceled 的旧消费者提供保守视图。
+ * 无法准确表达的未知、观察暂停和交付失败一律不伪装成终态。
+ */
+export function deriveLegacyStatus(task) {
+  if (!task || typeof task !== 'object') return 'running';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'ready') return 'succeeded';
+  if (task.outcome === 'failed') return 'failed';
+  if (
+    task.outcome === 'canceled' &&
+    (task.cancelState === 'remote_confirmed' || task.cancelState === 'local_confirmed')
+  ) return 'canceled';
+  return 'running';
+}
+
+/** 面向工作台的稳定语义；UI 文案可以本地化，但不能改变事实分类。 */
+export function deriveUserState(task) {
+  if (!task || typeof task !== 'object') return 'needs_attention';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'ready') return 'succeeded';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'failed') return 'artifact_unavailable';
+  if (task.outcome === 'failed') return 'failed';
+  if (
+    task.outcome === 'canceled' &&
+    (task.cancelState === 'remote_confirmed' || task.cancelState === 'local_confirmed')
+  ) return 'canceled';
+  if (
+    task.acceptance === 'unknown' ||
+    task.outcome === 'unknown' ||
+    task.cancelState === 'unknown'
+  ) return 'needs_attention';
+  if (task.watchState === 'suspended' || task.watchState === 'exhausted') return 'watching_paused';
+  if (task.phase === 'queued') return 'queued';
+  return 'running';
+}
+
+/**
+ * 提醒处置是事实轴之外的用户工作流视图。事件优先；早期 0.1.3 只有
+ * manualRetries 的记录也应视为已通过重试处理，避免升级后重复提醒。
+ */
+export function attentionDisposition(task) {
+  const events = Array.isArray(task && task.attentionEvents) ? task.attentionEvents : [];
+  const last = [...events].reverse().find((item) => item && ['acknowledged', 'restored'].includes(item.type));
+  if (last) {
+    return {
+      status: last.type === 'acknowledged' ? 'acknowledged' : 'open',
+      reason: last.reason || (last.type === 'restored' ? 'restored' : 'read'),
+      updatedAt: last.at || '',
+      ...(last.relatedTaskId ? { relatedTaskId: last.relatedTaskId } : {})
+    };
+  }
+  const retries = Array.isArray(task && task.manualRetries) ? task.manualRetries : [];
+  const retry = retries[retries.length - 1];
+  if (retry && retry.taskId) {
+    return {
+      status: 'acknowledged', reason: 'retried', updatedAt: retry.createdAt || '',
+      relatedTaskId: retry.taskId, inferred: true
+    };
+  }
+  return { status: 'open', reason: '', updatedAt: '' };
+}
+
+/**
+ * 校验 v2 记录内部是否自洽。返回稳定错误码，调用方决定如何展示。
+ * 这里只检查不可违反的事实关系，不替持久化层补默认值。
+ */
+export function semanticViolations(task) {
+  const errors = [];
+  if (!task || typeof task !== 'object' || Array.isArray(task)) return ['task.object'];
+
+  if (!includes(TASK_PHASES, task.phase)) errors.push('task.phase');
+  if (!includes(ACCEPTANCE_STATES, task.acceptance)) errors.push('task.acceptance');
+  if (!includes(WATCH_STATES, task.watchState)) errors.push('task.watchState');
+  if (!includes(TASK_OUTCOMES, task.outcome)) errors.push('task.outcome');
+  if (!includes(DELIVERY_STATES, task.deliveryState)) errors.push('task.deliveryState');
+  if (!includes(CANCEL_STATES, task.cancelState)) errors.push('task.cancelState');
+
+  if (task.watchState === 'active' && task.acceptance !== 'accepted') {
+    errors.push('watch.active_requires_acceptance');
+  }
+  if (task.phase === 'terminal' && task.watchState === 'active') {
+    errors.push('terminal.active_watch');
+  }
+  if (task.deliveryState !== 'none' && task.outcome !== 'succeeded') {
+    errors.push('delivery.requires_success');
+  }
+  if (
+    (task.cancelState === 'remote_confirmed' || task.cancelState === 'local_confirmed') &&
+    task.outcome !== 'canceled'
+  ) {
+    errors.push('cancel.confirmed_requires_canceled_outcome');
+  }
+  if (
+    task.outcome === 'canceled' &&
+    task.cancelState !== 'remote_confirmed' &&
+    task.cancelState !== 'local_confirmed'
+  ) {
+    errors.push('canceled.requires_confirmation');
+  }
+  return errors;
+}
+
+const V2_FIELDS = ['phase', 'acceptance', 'watchState', 'outcome', 'deliveryState', 'cancelState'];
+const DELIVERY_FAILURE = /转存失败|下载[^：:]*失败|落盘失败|delivery/i;
+const WATCH_FAILURE = /盯守超时|轮询连续失败|无法恢复|任务已超时/;
+
+function hasCompleteV2Shape(task) {
+  return V2_FIELDS.every((field) => Object.prototype.hasOwnProperty.call(task, field));
+}
+
+/**
+ * 将旧四态任务转换为保守的 v2 内存视图，不修改输入，也不执行磁盘写入。
+ * 无法从旧记录证明的受理、结果与取消事实一律使用 unknown。
+ */
+export function normalizeLegacyTask(task) {
+  if (!task || typeof task !== 'object' || Array.isArray(task)) {
+    throw new TypeError('旧任务必须是对象');
+  }
+  const out = {
+    ...task,
+    ...(Array.isArray(task.attempts) ? { attempts: task.attempts.map((attempt) => ({ ...attempt })) } : {})
+  };
+  if (hasCompleteV2Shape(out)) return out;
+
+  const status = String(task.status || 'running');
+  const hasRemoteId = typeof task.remoteTaskId === 'string' && Boolean(task.remoteTaskId.trim());
+  const error = String(task.error || '');
+  const defaults = {
+    phase: 'terminal',
+    acceptance: hasRemoteId ? 'accepted' : 'unknown',
+    watchState: 'idle',
+    outcome: 'unknown',
+    deliveryState: 'none',
+    cancelState: 'none'
+  };
+
+  if (status === 'succeeded') {
+    Object.assign(defaults, {
+      acceptance: 'accepted',
+      outcome: 'succeeded',
+      deliveryState: 'ready'
+    });
+  } else if (status === 'running' && hasRemoteId) {
+    Object.assign(defaults, {
+      phase: 'running',
+      acceptance: 'accepted',
+      watchState: 'suspended',
+      outcome: 'none'
+    });
+  } else if (status === 'failed' && DELIVERY_FAILURE.test(error)) {
+    Object.assign(defaults, {
+      acceptance: 'accepted',
+      outcome: 'succeeded',
+      deliveryState: 'failed'
+    });
+  } else if (status === 'failed' && WATCH_FAILURE.test(error)) {
+    Object.assign(defaults, {
+      acceptance: hasRemoteId ? 'accepted' : 'unknown',
+      watchState: hasRemoteId ? 'exhausted' : 'idle',
+      outcome: 'unknown'
+    });
+  } else if (status === 'canceled') {
+    Object.assign(defaults, {
+      acceptance: hasRemoteId ? 'accepted' : 'unknown',
+      outcome: 'unknown',
+      cancelState: 'unknown'
+    });
+  }
+
+  for (const field of V2_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(out, field)) out[field] = defaults[field];
+  }
+  return out;
+}