@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/models.js

@@ -9,9 +9,10 @@
  *   ① provider 显式 `models` 数组（未来配置，可带 capabilities 覆盖）
  *   ② 旧模型字段迁移：imageModel→image-gen、videoModel→video-gen、ttsModel→tts、
  *      transcribeModel→transcribe、visionModel→vision
- *   ③ 裸 DashScope 账号：已知模型清单（wan 系列 / qwen-vl / qwen-tts）作为池
+ * 旧裸账号的已知目录仅由配置写入边界物化，不参与运行时回退。
  */
 import { CAPABILITIES } from './capability.js';
+import { isDashScopeBaseUrl, selectMediaProtocol } from './provider-protocol.js';
 
 /** 能力 → provider 上的模型字段（保持向后兼容的返回形状） */
 export const CAP_FIELD = {
@@ -62,8 +63,8 @@ const MODEL_CAP_RULES = [
   [/^gemini/i, [CAPABILITIES.VISION]] // Gemini 默认按视觉能力纳入（可被显式配置覆盖）
 ];
 
-/** 裸 DashScope 已知模型清单（无显式模型字段时作为池） */
-const DASHSCOPE_KNOWN = [
+/** 仅供配置写入时接回旧裸账号，不参与运行时选型。 */
+const KNOWN_MODELS_BY_PROTOCOL = { dashscope: [
   { id: 'wan2.2-t2i-flash', caps: [CAPABILITIES.IMAGE] },
   { id: 'wan2.2-t2v-flash', caps: [CAPABILITIES.VIDEO] },
   { id: 'wan2.2-s2v-flash', caps: [CAPABILITIES.VIDEO] },
@@ -72,7 +73,17 @@ const DASHSCOPE_KNOWN = [
   { id: 'qwen3-vl-235b-a22b-thinking', caps: [CAPABILITIES.VISION] },
   { id: 'qwen-tts-latest', caps: [CAPABILITIES.TTS] },
   { id: 'qwen-audio-3.0-asr-flash-filetrans', caps: [CAPABILITIES.TRANSCRIBE] }
-];
+] };
+
+export function migrateProviderModels(provider) {
+  if (Array.isArray(provider.models) || Object.values(CAP_FIELD).some((field) => provider[field])) return false;
+  const protocol = selectMediaProtocol(provider).mediaProtocol;
+  if (!isDashScopeBaseUrl(provider.baseUrl) || !Object.hasOwn(KNOWN_MODELS_BY_PROTOCOL, protocol)) return false;
+  provider.models = KNOWN_MODELS_BY_PROTOCOL[protocol].map((m) => ({
+    id: m.id, capabilities: [...m.caps], source: 'migration'
+  }));
+  return true;
+}
 
 /** 按模型名规则推断能力 */
 export function capabilitiesOfModel(modelName) {
@@ -83,6 +94,24 @@ export function capabilitiesOfModel(modelName) {
   return [];
 }
 
+/** 官方模型目录能力代码 → Iris 能力。未识别代码保守忽略。 */
+const DISCOVERY_CAPABILITIES = Object.freeze({
+  IG: CAPABILITIES.IMAGE, IMAGE: CAPABILITIES.IMAGE, 'IMAGE-GEN': CAPABILITIES.IMAGE,
+  VG: CAPABILITIES.VIDEO, VIDEO: CAPABILITIES.VIDEO, 'VIDEO-GEN': CAPABILITIES.VIDEO,
+  TTS: CAPABILITIES.TTS, ASR: CAPABILITIES.TRANSCRIBE,
+  TRANSCRIBE: CAPABILITIES.TRANSCRIBE, VU: CAPABILITIES.VISION, VISION: CAPABILITIES.VISION
+});
+
+/** 发现元数据优先，名称规则兜底；用户保存后的显式 capabilities 仍是最终覆盖。 */
+export function capabilitiesOfDiscoveredModel(model) {
+  const id = String(typeof model === 'string' ? model : model?.id || '').trim();
+  const declared = Array.isArray(model?.capabilities)
+    ? [...new Set(model.capabilities.map((value) => DISCOVERY_CAPABILITIES[String(value).toUpperCase()]).filter(Boolean))]
+    : [];
+  if (declared.length) return declared;
+  return capabilitiesOfModel(id);
+}
+
 /** 一个 provider 的模型池条目列表：[{ id, providerId, capabilities:[], verified?, source? }] */
 export function providerModels(p) {
   if (!p) return [];
@@ -93,10 +122,13 @@ export function providerModels(p) {
     out.push({ id: name, providerId: p.id, ref: modelRef(p.id, name), capabilities: [...caps], ...(extra || {}) });
   };
   // ① 显式 models 数组（带可选 capabilities 覆盖 + verified/source 透传）
-  if (Array.isArray(p.models) && p.models.length) {
+  // 该字段一旦存在（含空数组）即为权威声明：用户可明确标记「此供应商没有可用模型」，
+  // 不得再落入 ② 旧字段迁移或 ③ 裸账号已知池。空数组曾因 `.length` 判定被穿透，
+  // 导致用户声明无模型却仍被注入 7 个厂商默认模型（见审计 B-5）。
+  if (Array.isArray(p.models)) {
     for (const m of p.models) {
       const id = typeof m === 'string' ? m : m && m.id;
-      // 显式空数组也是权威覆盖：用户可明确标记“此模型无能力”。
+      // 元素级空能力数组同样是权威覆盖：用户可明确标记“此模型无能力”。
       const caps = Array.isArray(m && m.capabilities) ? m.capabilities : capabilitiesOfModel(id);
       const extra = typeof m === 'object' && m ? { verified: m.verified, source: m.source } : {};
       push(id, caps, extra);
@@ -107,14 +139,68 @@ export function providerModels(p) {
   for (const [cap, field] of Object.entries(CAP_FIELD)) {
     if (p[field]) push(p[field], [cap]);
   }
-  if (out.length) return out;
-  // ③ 裸 DashScope 账号 → 已知模型池
-  if (/dashscope/i.test(String(p.baseUrl || ''))) {
-    for (const m of DASHSCOPE_KNOWN) push(m.id, m.caps);
-  }
   return out;
 }
 
+/** 只解析用户配置中的模型；裸 ID 与复合引用共享能力校验。 */
+export function resolveModelRef(provider, capability, requested = '') {
+  const pool = providerModels(provider).filter((m) => m.capabilities.includes(capability));
+  const raw = String(requested || '').trim();
+  const selected = raw ? resolvePoolModel(pool, raw, capability)
+    : pool.find((m) => m.id === provider?.[CAP_FIELD[capability]]) || pool[0];
+  return selected?.ref || null;
+}
+
+/** 共享旧分配对象、裸名称和复合引用的解析，池顺序决定同名匹配。 */
+export function resolvePoolModel(pool, raw, capability) {
+  let providerId = '';
+  let modelId = '';
+  if (raw && typeof raw === 'object') {
+    providerId = String(raw.providerId || '');
+    modelId = String(raw.modelId || raw.id || '');
+  } else if (typeof raw === 'string') {
+    const parsed = parseModelRef(raw);
+    if (parsed) ({ providerId, modelId } = parsed);
+    else if (!raw.includes(MODEL_REF_SEP)) modelId = raw;
+  }
+  return pool.find((m) => m.id === modelId && (!providerId || m.providerId === providerId)
+    && m.capabilities.includes(capability)) || null;
+}
+
+/** DSH 与 CLI 共用的候选顺序：分配优先、按池顺序补齐并去重。 */
+export function orderedModels(pool, capability, assignments) {
+  const ordered = [];
+  const seen = new Set();
+  const add = (model) => {
+    if (model && model.capabilities.includes(capability) && !seen.has(model.ref)) {
+      seen.add(model.ref);
+      ordered.push(model);
+    }
+  };
+  for (const raw of (Array.isArray(assignments) ? assignments : (assignments ? [assignments] : []))) {
+    add(resolvePoolModel(pool, raw, capability));
+  }
+  for (const model of pool) add(model);
+  return ordered;
+}
+
+/**
+ * 返回候选在当前候选链构造时的配置来源。调用方显式 model_ref 由入口直接标为
+ * explicit；本函数只区分 assignment 与池序补齐，结果必须随 Attempt 写前落盘，
+ * 不能在事后用可变配置重算。
+ */
+export function selectionReasonForModel(pool, capability, assignments, modelOrRef) {
+  const selected = resolvePoolModel(pool,
+    modelOrRef && typeof modelOrRef === 'object' ? modelOrRef.ref : modelOrRef,
+    capability);
+  if (!selected) return null;
+  for (const raw of (Array.isArray(assignments) ? assignments : (assignments ? [assignments] : []))) {
+    const assigned = resolvePoolModel(pool, raw, capability);
+    if (assigned?.ref === selected.ref) return 'assignment';
+  }
+  return 'pool';
+}
+
 /** 全局模型池：合并所有 provider 的模型 */
 export function modelPool(providers) {
   const pool = [];

package/lib/prompt-optimizer.js

@@ -2,21 +2,11 @@
 /** DSH 对话框级提示词优化：只处理显式提交的草稿，不读取会话历史或附件。 */
 import crypto from 'node:crypto';
 import { loadPromptOptimizerConfig, PROMPT_TARGETS } from './prompt-optimizer-config.js';
+import { hasHostPort, requireHostPort } from './host-contract.js';
 
 export const MAX_PROMPT_INPUT_BYTES = 32 * 1024;
 export const MAX_PROMPT_OUTPUT_CHARS = 16000;
 
-function service(ctx, name) {
-  if (!ctx) return undefined;
-  if (typeof ctx.get === 'function') {
-    try {
-      const value = ctx.get(name);
-      if (value) return value;
-    } catch (_) { /* 未注入的可选服务 */ }
-  }
-  try { return ctx[name]; } catch (_) { return undefined; }
-}
-
 function modelSelection(value, field) {
   if (!value || typeof value !== 'object') return null;
   const provider = typeof value.provider === 'string' ? value.provider.trim() : '';
@@ -32,15 +22,15 @@ function modelSelection(value, field) {
   return out;
 }
 
-export function resolvePromptOptimizerRoute(ctx, config, requestedRoute) {
+export function resolvePromptOptimizerRoute(host, config, requestedRoute) {
   if (config.route.mode === 'fixed') {
     return { ...modelSelection(config.route, 'route'), source: 'iris-fixed' };
   }
   const current = modelSelection(requestedRoute);
   if (current) return { ...current, source: 'current-session' };
-  const defaults = service(ctx, 'agentDefaultModel');
-  const fallback = defaults && typeof defaults.currentSelection === 'function'
-    ? modelSelection(defaults.currentSelection())
+  const textModel = hasHostPort(host, 'textModel') ? host.ports.textModel : undefined;
+  const fallback = textModel && typeof textModel.currentSelection === 'function'
+    ? modelSelection(textModel.currentSelection())
     : null;
   if (fallback) return { ...fallback, source: 'host-default' };
   throw new Error('Iris 找不到可用文本模型：请先在 DSH 会话中选择模型，或在 JSON 配置中设置 fixed 路由');
@@ -131,11 +121,11 @@ function cleanOutput(value) {
 
 /**
  * 执行一次显式的提示词优化。
- * @param {object} ctx DSH Host ctx
+ * @param {object} host Iris Host Adapter
  * @param {object} input {text,target,route,sessionId}
  * @param {{signal?:AbortSignal}} options
  */
-export async function optimizePrompt(ctx, input, { signal } = {}) {
+export async function optimizePrompt(host, input, { signal } = {}) {
   const original = typeof input?.text === 'string' ? input.text : '';
   const text = original.trim();
   if (!text) throw new Error('请输入需要优化的提示词');
@@ -148,9 +138,9 @@ export async function optimizePrompt(ctx, input, { signal } = {}) {
 
   const loaded = loadPromptOptimizerConfig();
   const config = loaded.config;
-  const route = resolvePromptOptimizerRoute(ctx, config, input && input.route);
-  const llm = service(ctx, 'llm');
-  if (!llm || typeof llm.stream !== 'function') throw new Error('DSH LLM 服务不可用，无法优化提示词');
+  const route = resolvePromptOptimizerRoute(host, config, input && input.route);
+  const llm = requireHostPort(host, 'textModel', '提示词优化');
+  if (typeof llm.stream !== 'function') throw new Error('Iris Host textModel 缺少 stream，无法优化提示词');
 
   const deadline = composeSignal(signal, config.generation.timeoutMs);
   const partials = new Map();

package/lib/provider-adapter.js

@@ -0,0 +1,397 @@
+'use strict';
+
+/**
+ * Iris Provider Adapter v0 完整生命周期契约。
+ *
+ * 本模块不读取配置、不调用网络、不创建 Task，也不依赖 DSH。具体供应商只把
+ * discovery/submit/poll/cancel/download/error mapping 映射到这些稳定结果。
+ */
+import {
+  ProviderContractError,
+  normalizeProviderArtifacts,
+  normalizeSubmissionResult,
+  providerErrorRecord,
+  resultFromThrown
+} from './provider-contract.js';
+
+export const PROVIDER_ADAPTER_CONTRACT_VERSION = 0;
+
+export const PROVIDER_OPERATIONS = Object.freeze([
+  'discover',
+  'submit',
+  'poll',
+  'cancel',
+  'download',
+  'mapError'
+]);
+
+export const PROVIDER_TASK_CAPABILITIES = Object.freeze([
+  'image',
+  'video',
+  'tts',
+  'transcribe'
+]);
+
+export const PROVIDER_POLL_KINDS = Object.freeze([
+  'pending',
+  'succeeded',
+  'failed',
+  'canceled',
+  'unknown'
+]);
+
+export const PROVIDER_CANCEL_KINDS = Object.freeze([
+  'canceled',
+  'not_supported',
+  'unknown'
+]);
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PROTOCOL = /^[a-z0-9][a-z0-9._-]*$/;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateOperation(name) {
+  if (!PROVIDER_OPERATIONS.includes(name)) throw new Error('未知 Provider 操作：' + String(name));
+}
+
+function normalizedReason(value, fallback) {
+  const text = String(value || fallback || '').trim();
+  if (!text) throw new TypeError('Provider unsupported 原因不能为空');
+  return text.slice(0, 500);
+}
+
+/**
+ * 建立只读 Adapter 描述。每个生命周期操作必须恰好出现在 operations 或
+ * unsupported 之一，避免“方法不存在”被误解成临时故障。
+ */
+export function defineProviderAdapter(input) {
+  if (!isPlainObject(input)) throw new TypeError('Provider Adapter 必须是对象');
+  const allowed = new Set([
+    'contractVersion', 'id', 'protocol', 'capabilities', 'operations', 'unsupported',
+    'prepareInput', 'unsupportedPreparation'
+  ]);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) throw new Error('Provider Adapter 不允许顶层字段：' + key);
+  }
+
+  const contractVersion = input.contractVersion ?? PROVIDER_ADAPTER_CONTRACT_VERSION;
+  if (contractVersion !== PROVIDER_ADAPTER_CONTRACT_VERSION) {
+    throw new Error('不支持的 Provider Adapter 契约版本：' + String(contractVersion));
+  }
+  const id = String(input.id || '').trim();
+  const protocol = String(input.protocol || '').trim();
+  if (!ID.test(id)) throw new Error('Provider Adapter id 必须是稳定标识');
+  if (!PROTOCOL.test(protocol)) throw new Error('Provider Adapter protocol 必须是小写稳定标识');
+
+  const capabilities = [...new Set(Array.isArray(input.capabilities) ? input.capabilities : [])];
+  if (!capabilities.length || capabilities.some((item) => !PROVIDER_TASK_CAPABILITIES.includes(item))) {
+    throw new Error('Provider Adapter capabilities 必须使用已知媒体任务能力');
+  }
+
+  const supplied = input.operations ?? {};
+  const missing = input.unsupported ?? {};
+  if (!isPlainObject(supplied) || !isPlainObject(missing)) {
+    throw new TypeError('Provider Adapter operations/unsupported 必须是对象');
+  }
+
+  const operations = {};
+  const unsupported = {};
+  for (const name of Object.keys(supplied)) validateOperation(name);
+  for (const name of Object.keys(missing)) validateOperation(name);
+  for (const name of PROVIDER_OPERATIONS) {
+    const hasOperation = Object.prototype.hasOwnProperty.call(supplied, name);
+    const hasUnsupported = Object.prototype.hasOwnProperty.call(missing, name);
+    if (hasOperation === hasUnsupported) {
+      throw new Error('Provider 操作 ' + name + ' 必须恰好声明为 supported 或 unsupported');
+    }
+    if (hasOperation) {
+      if (typeof supplied[name] !== 'function') {
+        throw new TypeError('Provider 操作 ' + name + ' 必须是函数');
+      }
+      operations[name] = supplied[name];
+    } else {
+      unsupported[name] = Object.freeze({ reason: normalizedReason(missing[name], name + ' 未实现') });
+    }
+  }
+  if (!operations.submit || !operations.mapError) {
+    throw new Error('Provider Adapter 必须实现 submit 与 mapError');
+  }
+
+  if (input.prepareInput !== undefined && typeof input.prepareInput !== 'function') {
+    throw new TypeError('Provider prepareInput 必须是函数');
+  }
+  if (input.prepareInput && input.unsupportedPreparation !== undefined) {
+    throw new Error('Provider 输入准备不能同时声明 supported 与 unsupported');
+  }
+  const unsupportedPreparation = input.prepareInput ? undefined
+    : normalizedReason(input.unsupportedPreparation, '协议未实现临时输入上传');
+
+  return Object.freeze({
+    contractVersion,
+    id,
+    protocol,
+    capabilities: Object.freeze(capabilities),
+    operations: Object.freeze(operations),
+    unsupported: Object.freeze(unsupported),
+    prepareInput: input.prepareInput,
+    unsupportedPreparation
+  });
+}
+
+export class ProviderOperationError extends Error {
+  constructor(adapter, operation) {
+    validateOperation(operation);
+    const providerId = adapter?.id || 'unknown-provider';
+    const reason = adapter?.unsupported?.[operation]?.reason || '操作未实现';
+    super('Iris Provider ' + providerId + ' 不支持 ' + operation + '：' + reason);
+    this.name = 'ProviderOperationError';
+    this.code = 'IRIS_PROVIDER_OPERATION_UNSUPPORTED';
+    this.providerId = providerId;
+    this.protocol = adapter?.protocol || 'unknown';
+    this.operation = operation;
+  }
+}
+
+export function hasProviderOperation(adapter, operation) {
+  validateOperation(operation);
+  return Boolean(adapter?.operations && typeof adapter.operations[operation] === 'function');
+}
+
+export function requireProviderOperation(adapter, operation) {
+  if (!hasProviderOperation(adapter, operation)) throw new ProviderOperationError(adapter, operation);
+  return adapter.operations[operation];
+}
+
+/** 只输出可序列化能力事实；不会暴露闭包中的 key、baseUrl 或 live transport。 */
+export function providerAdapterSnapshot(adapter) {
+  const operations = {};
+  for (const name of PROVIDER_OPERATIONS) {
+    operations[name] = hasProviderOperation(adapter, name)
+      ? Object.freeze({ status: 'supported' })
+      : Object.freeze({
+        status: 'unsupported',
+        reason: adapter?.unsupported?.[name]?.reason || '操作未实现'
+      });
+  }
+  return Object.freeze({
+    contractVersion: PROVIDER_ADAPTER_CONTRACT_VERSION,
+    provider: Object.freeze({
+      id: adapter?.id || 'unknown-provider',
+      protocol: adapter?.protocol || 'unknown'
+    }),
+    capabilities: Object.freeze([...(adapter?.capabilities || [])]),
+    operations: Object.freeze(operations),
+    inputPreparation: Object.freeze(typeof adapter?.prepareInput === 'function'
+      ? { status: 'supported' }
+      : { status: 'unsupported', reason: adapter?.unsupportedPreparation || '协议未实现临时输入上传' })
+  });
+}
+
+/** 提交前的可选上传能力；不创建 Task，也不属于六个生命周期操作。 */
+export async function prepareProviderInput(adapter, input = {}) {
+  if (typeof adapter?.prepareInput !== 'function') {
+    const error = new ProviderContractError(adapter?.unsupportedPreparation || '协议未实现临时输入上传', {
+      stage: 'upload', category: 'invalid_request', acceptance: 'not_accepted',
+      providerCode: 'IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED'
+    });
+    error.code = 'IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED';
+    throw error;
+  }
+  try {
+    const value = await adapter.prepareInput(input);
+    if (typeof value?.url !== 'string' || !value.url.trim()) {
+      throw new ProviderContractError('Provider 输入准备必须返回非空 url', {
+        stage: 'upload', category: 'protocol', acceptance: 'not_accepted'
+      });
+    }
+    // 临时地址只供随后的提交使用，避免随日志或任务 JSON 序列化。
+    return Object.freeze(Object.defineProperty({}, 'url', { value: value.url }));
+  } catch (error) {
+    const context = { stage: 'upload', acceptance: 'not_accepted' };
+    const safe = providerErrorRecord(error instanceof ProviderContractError
+      ? error : mappedError(adapter, error, context), context);
+    throw new ProviderContractError(safe.safeMessage, safe);
+  }
+}
+
+export function normalizeDiscoveryResult(value) {
+  const source = Array.isArray(value) ? value : value?.models;
+  if (!Array.isArray(source)) throw new TypeError('Provider discover 必须返回 models 数组');
+  const models = [];
+  const seen = new Set();
+  for (const item of source) {
+    const id = String(typeof item === 'string' ? item : item?.id || '').trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    const model = { id };
+    if (Array.isArray(item?.capabilities)) {
+      const capabilities = [...new Set(item.capabilities.filter((cap) => typeof cap === 'string' && cap))];
+      if (capabilities.length) model.capabilities = Object.freeze(capabilities);
+    }
+    models.push(Object.freeze(model));
+  }
+  return Object.freeze({ models: Object.freeze(models) });
+}
+
+/**
+ * poll 标准结果。兼容旧 {done,ok,urls,text,status,message} 仅用于 0.1.x 渐进迁移；
+ * 新 Adapter 必须直接返回 kind 结果。
+ */
+export function normalizeProviderPollResult(value) {
+  if (!isPlainObject(value)) throw new TypeError('Provider poll 必须返回结构化结果');
+
+  if (!PROVIDER_POLL_KINDS.includes(value.kind) && typeof value.done === 'boolean') {
+    if (!value.done) return Object.freeze({
+      kind: 'pending',
+      ...(value.status ? { progress: String(value.status) } : {})
+    });
+    if (value.ok) {
+      return Object.freeze({
+        kind: 'succeeded',
+        artifacts: normalizeProviderArtifacts((value.urls || []).map((url) => ({ kind: 'remote-url', url }))),
+        ...(typeof value.text === 'string'
+          ? { value: Object.freeze({ kind: 'text', text: value.text }) }
+          : {})
+      });
+    }
+    return Object.freeze({
+      kind: 'failed',
+      error: Object.freeze(providerErrorRecord(value.message || '供应商任务失败', {
+        stage: 'poll', category: 'provider', acceptance: 'accepted'
+      }))
+    });
+  }
+
+  if (!PROVIDER_POLL_KINDS.includes(value.kind)) {
+    throw new TypeError('未知 Provider poll kind：' + String(value.kind));
+  }
+  if (value.kind === 'pending') {
+    return Object.freeze({
+      kind: 'pending',
+      ...(value.progress !== undefined ? { progress: String(value.progress) } : {})
+    });
+  }
+  if (value.kind === 'succeeded') {
+    return Object.freeze({
+      kind: 'succeeded',
+      artifacts: normalizeProviderArtifacts(value.artifacts),
+      ...(value.value !== undefined ? { value: value.value } : {})
+    });
+  }
+  const stage = value.kind === 'canceled' ? 'cancel' : 'poll';
+  return Object.freeze({
+    kind: value.kind,
+    error: Object.freeze(providerErrorRecord(value.error || value.message || ('Provider poll ' + value.kind), {
+      stage,
+      category: value.kind === 'canceled' ? 'aborted' : undefined,
+      acceptance: 'accepted'
+    }))
+  });
+}
+
+export function normalizeProviderCancelResult(value) {
+  if (!isPlainObject(value) || !PROVIDER_CANCEL_KINDS.includes(value.kind)) {
+    throw new TypeError('Provider cancel 必须返回 canceled/not_supported/unknown');
+  }
+  if (value.kind === 'canceled') return Object.freeze({ kind: 'canceled' });
+  if (value.kind === 'not_supported') {
+    return Object.freeze({ kind: 'not_supported', reason: normalizedReason(value.reason, '供应商不支持远端取消') });
+  }
+  return Object.freeze({
+    kind: 'unknown',
+    error: Object.freeze(providerErrorRecord(value.error || value.message || '远端取消结果未知', {
+      stage: 'cancel', acceptance: 'accepted'
+    }))
+  });
+}
+
+export function normalizeProviderDownloadResult(value) {
+  const bytes = Number(typeof value === 'number' ? value : value?.bytes);
+  if (!Number.isSafeInteger(bytes) || bytes < 0) {
+    throw new TypeError('Provider download 必须返回非负安全整数 bytes');
+  }
+  return Object.freeze({ bytes });
+}
+
+function mappedError(adapter, error, context) {
+  const mapper = requireProviderOperation(adapter, 'mapError');
+  let mapped;
+  try {
+    mapped = mapper(error, context);
+  } catch (mappingError) {
+    mapped = mappingError;
+  }
+  const source = mapped || error;
+  const defaults = {};
+  for (const key of ['stage', 'category', 'acceptance', 'retryable']) {
+    if (source == null || source[key] === undefined) defaults[key] = context[key];
+  }
+  return providerErrorRecord(source, defaults);
+}
+
+function operationErrorContext(operation, context) {
+  const supplied = isPlainObject(context) ? context : {};
+  if (operation === 'submit') return { stage: 'submit', acceptance: 'unknown', ...supplied };
+  if (operation === 'discover') return { stage: 'validate', acceptance: 'not_accepted', ...supplied };
+  if (operation === 'poll') return { stage: 'poll', acceptance: 'accepted', ...supplied };
+  if (operation === 'cancel') return { stage: 'cancel', acceptance: 'accepted', ...supplied };
+  if (operation === 'download') return { stage: 'download', acceptance: 'accepted', ...supplied };
+  return supplied;
+}
+
+/**
+ * 生命周期统一调用入口。submit 异常转为保守四态结果；cancel 异常转为 unknown；
+ * poll/download/discover 保持抛错，让调度器应用各自的重试和事实规则。
+ */
+export async function invokeProviderOperation(adapter, operation, input, context = {}) {
+  validateOperation(operation);
+  if (operation === 'mapError') {
+    return mappedError(adapter, input, context);
+  }
+  const fn = requireProviderOperation(adapter, operation);
+  const errorContext = operationErrorContext(operation, context);
+  let value;
+  try {
+    value = await fn(input, context);
+  } catch (error) {
+    const evidenceContext = { ...errorContext };
+    for (const key of ['stage', 'category', 'acceptance', 'retryable']) {
+      if (error && error[key] !== undefined) evidenceContext[key] = error[key];
+    }
+    const safe = mappedError(adapter, error, evidenceContext);
+    if (operation === 'submit') return resultFromThrown(safe);
+    if (operation === 'cancel') return normalizeProviderCancelResult({ kind: 'unknown', error: safe });
+    throw new ProviderContractError(safe.safeMessage, safe);
+  }
+
+  if (operation === 'discover') return normalizeDiscoveryResult(value);
+  if (operation === 'submit') return normalizeSubmissionResult(value);
+  if (operation === 'poll') return normalizeProviderPollResult(value);
+  if (operation === 'cancel') return normalizeProviderCancelResult(value);
+  if (operation === 'download') return normalizeProviderDownloadResult(value);
+  throw new Error('未处理的 Provider 操作：' + operation);
+}
+
+/** 0.1.x 任务观察器兼容视图；0.2.0 Command 完全消费 canonical poll 后可删除。 */
+export function providerPollTaskView(value) {
+  const result = normalizeProviderPollResult(value);
+  if (result.kind === 'pending') {
+    return { kind: result.kind, done: false, ok: false, urls: [], status: result.progress || 'running' };
+  }
+  if (result.kind === 'succeeded') {
+    const urls = result.artifacts.filter((item) => item.kind === 'remote-url').map((item) => item.url);
+    if (result.value?.kind === 'text') urls.push(String(result.value.text || ''));
+    return { kind: result.kind, done: true, ok: true, urls, value: result.value };
+  }
+  return {
+    kind: result.kind,
+    done: true,
+    ok: false,
+    urls: [],
+    message: result.error.safeMessage,
+    error: result.error
+  };
+}