@mokuyoaxis/dsh-iris 0.1.4 → 0.2.0

package/lib/provider-contract.js

@@ -42,10 +42,32 @@ export const PROVIDER_ERROR_CATEGORIES = Object.freeze([
 ]);
 
 const ACCEPTANCE = new Set(['not_accepted', 'accepted', 'unknown']);
-const SECRET_QUERY = /([?&](?:access[_-]?key|api[_-]?key|authorization|credential|signature|token)=)[^&#\s]+/gi;
+// 凭据查询参数：允许厂商前缀（x-amz- / x-oss- / OSSAccessKeyId 这类驼峰），但**限制尾部后缀**
+// （审计 C-9 要求覆盖带前缀参数名）。
+//
+// 正则分两级，是为了同时满足两个方向：
+//   ① 强凭据词（key/credential/signature/secret）：允许任意字母前缀 + 有限后缀（id|secret|ids），
+//      保证 OSSAccessKeyId / X-Amz-Credential / gemini-signature 一律脱敏；
+//   ② 弱凭据词（token/auth/authorization）：只允许【白名单厂商前缀】，且后缀限 id|secret|ids。
+//      这是 C-9 首版修复的更正——首版给两级都开了无限 `[a-z0-9_-]*` 后缀，导致
+//      page_token / tokenizer / signature_mode 这类非凭据参数被误脱敏，诊断信息丢失。
+const SECRET_STRONG = '(?:access[_-]?key|api[_-]?key|apikey|credential|signature|secret)';
+const SECRET_WEAK = '(?:token|auth|authorization)';
+const SECRET_SUFFIX = '(?:id|secret|ids)?';
+const SECRET_VENDOR = '(?:(?:x|amz|oss|aliyun|aws|s3|gcp|azure|sts|sec|security|sig|sign|auth|oauth|bearer|jwt|session|csrf|access|api|private|secret|refresh|id|tmp|temp)[-_]?)*';
+const SECRET_NAME = '(?:' + '(?:[a-z0-9]+[-_])*[a-z0-9]*' + SECRET_STRONG + SECRET_SUFFIX
+  + '|' + SECRET_VENDOR + SECRET_WEAK + SECRET_SUFFIX + ')';
+const SECRET_QUERY = new RegExp('([?&]' + SECRET_NAME + '=)[^&#\\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;
+// 结构化凭据字段：与 SECRET_QUERY 同构，同样限制弱凭据词的后缀。
+// 左边界 `NAME_START` 不可省：否则 `page_token=x` 里的子串 `token=x` 也会被匹配，
+// 非凭据参数将被误脱敏（本次收紧时发现，旧实现同样存在该缺陷）。
+const NAME_START = '(?<![A-Za-z0-9_-])';
+const JSON_SECRET = new RegExp('(\"?\'?' + NAME_START
+  + '(?:' + '(?:[A-Za-z0-9]+[-_])*' + SECRET_STRONG + SECRET_SUFFIX
+  + '|' + SECRET_VENDOR.replace(/\[-_\]\?/g, '[-_]?') + SECRET_WEAK + SECRET_SUFFIX + ')'
+  + '[\"\']?\\s*[:=]\\s*[\"\']?)[^\"\',\\s}]+', 'gi');
 const POSIX_PATH = /(^|[\s("'=])\/(?:[^/\s"'`,;)}\]]+\/)*[^/\s"'`,;)}\]]+/gm;
 const WINDOWS_PATH = /\b[A-Za-z]:\\(?:[^\\\s"'`,;)}\]]+\\)*[^\\\s"'`,;)}\]]+/g;
 
@@ -103,6 +125,43 @@ export class ProviderContractError extends Error {
   }
 }
 
+/**
+ * Provider 交付描述只允许远端 URL 或短生命周期的内联 base64。内联正文故意设为
+ * non-enumerable：Runner 可以物化它，但日志、JSON 和 Task 持久化不会顺手复制图片。
+ */
+export function normalizeProviderArtifacts(value) {
+  if (value === undefined) return Object.freeze([]);
+  if (!Array.isArray(value)) throw new TypeError('Provider artifacts 必须是数组');
+  return Object.freeze(value.map((item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new TypeError('Provider artifact 必须是对象');
+    }
+    const mediaType = typeof item.mediaType === 'string' && item.mediaType.trim()
+      ? item.mediaType.trim()
+      : undefined;
+    if (item.kind === 'remote-url') {
+      const url = String(item.url || '').trim();
+      if (!url) throw new TypeError('Provider remote-url artifact 缺少 url');
+      return Object.freeze({ kind: 'remote-url', url, ...(mediaType ? { mediaType } : {}) });
+    }
+    if (item.kind === 'inline-base64') {
+      const data = String(item.data || '').trim();
+      if (!data || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) {
+        throw new TypeError('Provider inline-base64 artifact 数据无效');
+      }
+      const padding = data.endsWith('==') ? 2 : (data.endsWith('=') ? 1 : 0);
+      const artifact = {
+        kind: 'inline-base64',
+        byteLength: (data.length / 4) * 3 - padding,
+        ...(mediaType ? { mediaType } : {})
+      };
+      Object.defineProperty(artifact, 'data', { value: data, enumerable: false });
+      return Object.freeze(artifact);
+    }
+    throw new TypeError('Provider artifact kind 仅支持 remote-url/inline-base64');
+  }));
+}
+
 export function normalizeSubmissionResult(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new TypeError('Provider submit 必须返回结构化结果');
@@ -111,7 +170,17 @@ export function normalizeSubmissionResult(value) {
     throw new TypeError('未知 Provider submit kind: ' + String(value.kind));
   }
   if (value.kind === 'completed') {
-    return { kind: 'completed', acceptance: 'accepted', value: value.value };
+    const result = {
+      kind: 'completed', acceptance: 'accepted',
+      ...(value.artifacts !== undefined ? { artifacts: normalizeProviderArtifacts(value.artifacts) } : {})
+    };
+    if (value.value !== undefined) {
+      Object.defineProperty(result, 'value', {
+        value: value.value,
+        enumerable: value.artifacts === undefined
+      });
+    }
+    return result;
   }
   if (value.kind === 'accepted') {
     const remoteTaskId = String(value.remoteTaskId || '').trim();

package/lib/provider-protocol.js

@@ -2,18 +2,54 @@
 /** 供应商媒体协议判断与 DashScope 凭据边界。 */
 
 const DASH_SCOPE_HOST = /^dashscope(?:-[a-z0-9-]+)?\.aliyuncs\.com$/i;
+const REGIONAL_HOST = /^cn-hongkong\.dashscope\.aliyuncs\.com$/i;
+const WORKSPACE_HOST = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.(?:cn-beijing|ap-southeast-1|eu-central-1|ap-northeast-1|us-east-1)\.maas\.aliyuncs\.com$/i;
+
+/** 可选媒体端点；空值沿用普通/视觉端点。 */
+export function providerMediaBaseUrl(provider) {
+  return String(provider?.mediaBaseUrl || '').trim() || String(provider?.baseUrl || '').trim();
+}
 
 export function isDashScopeBaseUrl(value) {
   try {
     const url = new URL(String(value || '').trim());
-    return url.protocol === 'https:' && !url.username && !url.password && DASH_SCOPE_HOST.test(url.hostname);
+    return url.protocol === 'https:' && !url.username && !url.password
+      && (DASH_SCOPE_HOST.test(url.hostname) || REGIONAL_HOST.test(url.hostname) || WORKSPACE_HOST.test(url.hostname));
   } catch (_) {
     return false;
   }
 }
 
 export function inferMediaProtocol(baseUrl) {
-  return isDashScopeBaseUrl(baseUrl) ? 'dashscope' : 'openai-images';
+  return detectMediaProtocol(baseUrl) || 'openai-images';
+}
+
+/** 未识别的端点不等于已验证的兼容协议。 */
+export function detectMediaProtocol(baseUrl) {
+  if (isDashScopeBaseUrl(baseUrl)) return 'dashscope';
+  try {
+    const url = new URL(String(baseUrl || '').trim());
+    if (url.protocol === 'https:' && !url.username && !url.password
+        && url.hostname === 'api.openai.com') return 'openai-images';
+  } catch (_) { /* 未知端点保留兼容回退，由调用方展示推断状态 */ }
+  return null;
+}
+
+export function selectMediaProtocol(provider) {
+  const explicit = typeof provider?.mediaProtocol === 'string' ? provider.mediaProtocol.trim() : '';
+  if (explicit && explicit !== 'auto'
+      && (provider?.protocolInferred !== true || explicit !== 'openai-images')) {
+    return { mediaProtocol: explicit, protocolInferred: false };
+  }
+  const detected = detectMediaProtocol(providerMediaBaseUrl(provider));
+  return { mediaProtocol: detected || 'openai-images', protocolInferred: !detected };
+}
+
+export function unsupportedProtocolError(protocol, kind = 'media') {
+  const safeName = /^[a-z][a-z0-9-]{0,63}$/.test(String(protocol)) ? protocol : '(invalid)';
+  const error = new TypeError('iris: 不支持的 ' + (kind === 'vision' ? 'Vision' : 'Provider') + ' 协议：' + safeName);
+  error.code = kind === 'vision' ? 'IRIS_VISION_PROTOCOL_UNSUPPORTED' : 'IRIS_PROVIDER_PROTOCOL_UNSUPPORTED';
+  return error;
 }
 
 /** 返回官方 DashScope API 根；不满足边界时在 fetch 前拒绝。 */
@@ -23,3 +59,16 @@ export function dashscopeApiBase(baseUrl) {
   }
   return new URL('/api/v1', String(baseUrl).trim()).toString().replace(/\/$/, '');
 }
+
+/** 无认证模式不发送保留的旧凭据；未声明模式保持 bearer 兼容。 */
+export function providerApiKey(provider) {
+  return provider?.auth === 'none' ? '' : String(provider?.apiKey || '');
+}
+
+/** 配置管理与 headless 候选链共用可用性门，未声明 enabled 时默认启用。 */
+export function isConfiguredProvider(provider) {
+  return Boolean(provider && provider.enabled !== false
+    && typeof provider.id === 'string' && provider.id.trim()
+    && providerMediaBaseUrl(provider)
+    && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
+}

package/lib/provider-task-runner.js

@@ -0,0 +1,328 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCoreArtifact } from './core-artifacts.js';
+import {
+  activateCoreWatch,
+  beginCoreAttempt,
+  beginCoreDelivery,
+  completeCoreDelivery,
+  createCoreTask,
+  failCoreDelivery,
+  finalizeCoreNoAcceptance,
+  inspectCoreTask,
+  prepareCoreRedelivery,
+  recordCoreAttemptResult,
+  recordCoreCancelResult,
+  recordCoreDownloadCompleted,
+  recordCorePollResult,
+  recordCoreWatchError,
+  recoverCoreTask,
+  requestCoreCancel
+} from './core-tasks.js';
+import { ensurePrivateDir } from './private-storage.js';
+import { parseModelRef } from './models.js';
+import {
+  hasProviderOperation,
+  invokeProviderOperation
+} from './provider-adapter.js';
+import { providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
+
+export const PROVIDER_TASK_RUNNER_VERSION = 0;
+
+/**
+ * 按 capability 冻结的交付 Profile（E 阶段视频迁移）：媒体类型白名单、Artifact
+ * kind 与默认 metadata。新增 capability 必须显式登记；未登记的 capability 直接
+ * 失败，不会按图片语义猜。
+ */
+export const DELIVERY_PROFILES = Object.freeze({
+  image: Object.freeze({ kind: 'generated-image', mediaTypes: Object.freeze(['image/png']), defaultMediaType: 'image/png' }),
+  video: Object.freeze({ kind: 'generated-video', mediaTypes: Object.freeze(['video/mp4']), defaultMediaType: 'video/mp4' }),
+  // TTS 同步完成型：submit 内 completed → 同一次调用直接交付（无 remote 长轮询）。
+  tts: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
+  // 转写上传型异步：受理 + remoteTaskId → 长轮询 → 文本物化为 UTF-8 Artifact。
+  transcribe: Object.freeze({ kind: 'transcript', mediaTypes: Object.freeze(['text/plain']), defaultMediaType: 'text/plain' })
+});
+const runtimeTaskGates = new WeakMap();
+
+export class ProviderTaskRunnerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProviderTaskRunnerError';
+    this.code = code;
+  }
+}
+
+function checkRuntime(runtime) {
+  if (!runtime || typeof runtime.run !== 'function') {
+    throw new TypeError('Provider Task Runner 需要已创建的 Core Runtime');
+  }
+}
+
+function checkAdapterForTask(task, adapter) {
+  if (!adapter || adapter.id !== task.providerId) {
+    throw new ProviderTaskRunnerError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Provider Adapter 与 Task 已持久化身份不一致');
+  }
+  return adapter;
+}
+
+function normalizedCandidates(capability, candidates) {
+  if (!Array.isArray(candidates) || !candidates.length) throw new TypeError('至少需要一个 Provider 候选');
+  return candidates.map((candidate, index) => {
+    const adapter = candidate?.adapter;
+    const model = String(candidate?.model || '').trim();
+    const parsed = parseModelRef(model);
+    const selectionReason = candidate?.selectionReason;
+    if (!adapter || !adapter.capabilities?.includes(capability) || !parsed
+        || parsed.providerId !== adapter.id || !parsed.modelId
+        || (candidate.providerBinding !== undefined && !/^sha256:[a-f0-9]{64}$/.test(candidate.providerBinding))
+        || (selectionReason !== undefined && !['explicit', 'assignment', 'pool'].includes(selectionReason))) {
+      throw new TypeError('Provider 候选 ' + (index + 1) + ' 不支持 Task capability 或模型复合身份无效');
+    }
+    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, selectionReason };
+  });
+}
+
+function stagingFile(dataRoot) {
+  const directory = path.join(dataRoot, 'provider-staging', 'v0');
+  ensurePrivateDir(directory);
+  return path.join(directory, 'download-' + process.pid + '-' + crypto.randomBytes(8).toString('hex') + '.part');
+}
+
+async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, signal) {
+  beginCoreDelivery(dataRoot, taskId);
+  const artifactIds = [];
+  const stagedFiles = [];
+  try {
+    if (!Array.isArray(remoteArtifacts) || remoteArtifacts.length === 0) {
+      throw Object.assign(new Error('Provider Task Runner 没有收到可物化产物'), {
+        stage: 'download', category: 'protocol', acceptance: 'accepted'
+      });
+    }
+    const task = inspectCoreTask(dataRoot, taskId);
+    const profile = DELIVERY_PROFILES[task.capability];
+    if (!profile) {
+      throw Object.assign(new Error('Provider Task Runner 没有该 capability 的交付 Profile：' + task.capability), {
+        stage: 'download', category: 'protocol', acceptance: 'accepted'
+      });
+    }
+    for (const remote of remoteArtifacts) {
+      const mediaType = String(remote.mediaType || profile.defaultMediaType);
+      if (!profile.mediaTypes.includes(mediaType)) {
+        throw Object.assign(new Error('Provider Task Runner 交付媒体类型不在 Profile 白名单：' + mediaType), {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
+      const target = stagingFile(dataRoot);
+      stagedFiles.push({ target, mediaType });
+      const downloaded = await invokeProviderOperation(adapter, 'download', {
+        capability: task.capability,
+        artifact: remote,
+        targetPath: target,
+        signal
+      }, { signal, taskId });
+      const stat = fs.lstatSync(target);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== downloaded.bytes) {
+        throw Object.assign(new Error('Provider 物化结果与文件证据不一致'), {
+          stage: 'download', category: 'local_io', acceptance: 'accepted'
+        });
+      }
+    }
+    recordCoreDownloadCompleted(dataRoot, taskId);
+    for (const staged of stagedFiles) {
+      const artifact = createCoreArtifact(dataRoot, {
+        kind: profile.kind,
+        mediaType: staged.mediaType,
+        bytes: fs.readFileSync(staged.target),
+        metadata: { taskId, capability: task.capability }
+      });
+      artifactIds.push(artifact.id);
+    }
+    return completeCoreDelivery(dataRoot, taskId, artifactIds);
+  } catch (error) {
+    return failCoreDelivery(dataRoot, taskId, error);
+  } finally {
+    for (const staged of stagedFiles) {
+      try { fs.rmSync(staged.target, { force: true }); } catch (_) { /* 后续显式清理可处理残留 */ }
+    }
+  }
+}
+
+async function observeWithinRoot(dataRoot, taskId, adapter, signal) {
+  const before = inspectCoreTask(dataRoot, taskId);
+  checkAdapterForTask(before, adapter);
+  activateCoreWatch(dataRoot, taskId);
+  let result;
+  try {
+    result = await invokeProviderOperation(adapter, 'poll', {
+      capability: before.capability,
+      remoteTaskId: before.remoteTaskId,
+      signal
+    }, { signal, taskId });
+  } catch (error) {
+    return recordCoreWatchError(dataRoot, taskId, error);
+  }
+  const recorded = recordCorePollResult(dataRoot, taskId, result);
+  if (result.kind !== 'succeeded') return recorded;
+  return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
+}
+
+/**
+ * FakeProvider 与未来真实 Host 共用的生命周期调度候选。它不拥有 timer，也不会
+ * 自动循环轮询；每次 observe 只消费一个 poll 结果，使重启和故障边界可重复验证。
+ */
+export function createProviderTaskRunner(runtime) {
+  checkRuntime(runtime);
+  let activeTasks = runtimeTaskGates.get(runtime);
+  if (!activeTasks) {
+    activeTasks = new Set();
+    runtimeTaskGates.set(runtime, activeTasks);
+  }
+
+  async function runExclusive(taskId, operation, callback) {
+    const key = String(taskId || '');
+    if (activeTasks.has(key)) {
+      throw new ProviderTaskRunnerError(
+        'IRIS_PROVIDER_TASK_BUSY',
+        '该 Task 已有生命周期操作正在执行'
+      );
+    }
+    activeTasks.add(key);
+    try {
+      return await runtime.run(operation, callback);
+    } finally {
+      activeTasks.delete(key);
+    }
+  }
+
+  async function submit(input = {}) {
+    return runtime.run('execute', async ({ dataRoot, signal }) => {
+      const capability = String(input.capability || '').trim();
+      const candidates = normalizedCandidates(capability, input.candidates);
+      const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom });
+      const wrapped = candidates.map(({ adapter, model, providerModel }) => ({
+        id: adapter.id,
+        model,
+        adapter,
+        submit: (providerInput, context) => invokeProviderOperation(
+          adapter,
+          'submit',
+          { capability, model: providerModel, input: providerInput, signal },
+          { ...context, signal, taskId: task.id }
+        )
+      }));
+      const submitted = await submitWithAcceptanceBoundary(wrapped, input.providerInput ?? {}, {
+        beforeAttempt: async (attempt) => {
+          const candidate = candidates[attempt.ordinal - 1];
+          return beginCoreAttempt(dataRoot, task.id, {
+            ...attempt,
+            ...(candidate.providerBinding !== undefined ? { providerBinding: candidate.providerBinding } : {}),
+            ...(candidate.selectionReason !== undefined ? { selectionReason: candidate.selectionReason } : {})
+          });
+        },
+        afterResult: async (attempt) => recordCoreAttemptResult(dataRoot, task.id, attempt)
+      });
+      if (submitted.localError) {
+        return Object.freeze({ taskId: task.id, task: inspectCoreTask(dataRoot, task.id), localError: submitted.localError });
+      }
+      if (!submitted.result) throw new Error('Provider 提交流程没有返回结果');
+      if (submitted.result.kind === 'not_accepted') {
+        finalizeCoreNoAcceptance(dataRoot, task.id, submitted.result.error);
+      } else if (submitted.result.kind === 'completed') {
+        const artifacts = submitted.result.artifacts;
+        return Object.freeze({
+          taskId: task.id,
+          task: await deliverArtifacts(dataRoot, task.id, submitted.candidate.adapter, artifacts, signal),
+          attempts: submitted.attempts
+        });
+      }
+      return Object.freeze({
+        taskId: task.id,
+        task: inspectCoreTask(dataRoot, task.id),
+        attempts: submitted.attempts
+      });
+    });
+  }
+
+  function inspect(taskId) {
+    return runtime.run('inspect', ({ dataRoot }) => inspectCoreTask(dataRoot, taskId));
+  }
+
+  function observe(taskId, adapter, { resumeActive = false } = {}) {
+    return runExclusive(taskId, 'execute', ({ dataRoot, signal }) => {
+      if (resumeActive) {
+        const current = inspectCoreTask(dataRoot, taskId);
+        checkAdapterForTask(current, adapter);
+        if (current.watchState === 'active') recoverCoreTask(dataRoot, taskId);
+      }
+      return observeWithinRoot(dataRoot, taskId, adapter, signal);
+    });
+  }
+
+  function redeliver(taskId, adapter) {
+    return runExclusive(taskId, 'execute', async ({ dataRoot, signal }) => {
+      const task = inspectCoreTask(dataRoot, taskId);
+      checkAdapterForTask(task, adapter);
+      prepareCoreRedelivery(dataRoot, taskId);
+      let result;
+      try {
+        result = await invokeProviderOperation(adapter, 'poll', {
+          capability: task.capability,
+          remoteTaskId: task.remoteTaskId,
+          signal
+        }, { signal, taskId, redelivery: true });
+      } catch (error) {
+        return failCoreDelivery(dataRoot, taskId, error);
+      }
+      if (result.kind !== 'succeeded') {
+        return failCoreDelivery(dataRoot, taskId, providerErrorRecord(
+          result.error || '重新查询没有得到可交付产物',
+          { stage: 'download', category: 'protocol', acceptance: 'accepted' }
+        ));
+      }
+      return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
+    });
+  }
+
+  function cancel(taskId, adapter) {
+    return runExclusive(taskId, 'execute', async ({ dataRoot, signal }) => {
+      const task = inspectCoreTask(dataRoot, taskId);
+      checkAdapterForTask(task, adapter);
+      requestCoreCancel(dataRoot, taskId);
+      if (!hasProviderOperation(adapter, 'cancel')) {
+        return recordCoreCancelResult(dataRoot, taskId, { kind: 'not_supported' });
+      }
+      const result = await invokeProviderOperation(adapter, 'cancel', {
+        capability: task.capability,
+        remoteTaskId: task.remoteTaskId,
+        signal
+      }, { signal, taskId });
+      return recordCoreCancelResult(dataRoot, taskId, result);
+    });
+  }
+
+  function recover(taskId, adapter) {
+    return runExclusive(taskId, 'recover', async ({ dataRoot, signal }) => {
+      const recovered = recoverCoreTask(dataRoot, taskId);
+      if (recovered.acceptance === 'accepted' && recovered.remoteTaskId
+          && recovered.outcome === 'none'
+          && ['accepted', 'running'].includes(recovered.phase)) {
+        checkAdapterForTask(recovered, adapter);
+        return observeWithinRoot(dataRoot, taskId, adapter, signal);
+      }
+      return recovered;
+    });
+  }
+
+  return Object.freeze({
+    version: PROVIDER_TASK_RUNNER_VERSION,
+    submit,
+    inspect,
+    observe,
+    redeliver,
+    cancel,
+    recover
+  });
+}

package/lib/tasks.js

@@ -455,15 +455,25 @@ export function all() {
   return [...load().tasks].sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
 }
 
+/** 终态或已显式处理提醒的 Task v2 可删；活跃/未处理任务仍受保护。 */
+export function taskRecordRemovable(task) {
+  if (!task) return false;
+  if (task.status !== 'running') return true;
+  return isV2Task(task)
+    && ATTENTION_USER_STATES.has(deriveUserState(task))
+    && attentionDisposition(task).status === 'acknowledged';
+}
+
 /**
- * 删除单条任务元数据（仅终态；运行中须先 cancel）。
+ * 删除单条任务元数据。事实终态可直接删除；状态未知只有在用户已读/已重试归档后才可删除。
  * 只删记录，产物文件留在 outputs/（媒体链接因 token 随记录消失而自然失效）。
  * @returns {{ok:boolean, reason?:string}}
  */
 export function remove(id) {
   const t = get(id);
   if (!t) return { ok: false, reason: '任务不存在' };
-  if (t.status === 'running') return { ok: false, reason: '运行中任务请先取消再删除' };
+  if (!taskRecordRemovable(t)) return { ok: false, reason: '活跃或待确认任务请先取消、完成提醒处置，或标为已读后再删除' };
+  stopWatch(id);
   const arr = load().tasks;
   const i = arr.findIndex((x) => x.id === id);
   if (i >= 0) arr.splice(i, 1);
@@ -481,8 +491,10 @@ export function prune(pred) {
   const removed = [];
   const kept = [];
   for (const t of arr) {
-    if (t.status !== 'running' && pred(t)) removed.push(t.id);
-    else kept.push(t);
+    if (taskRecordRemovable(t) && pred(t)) {
+      stopWatch(t.id);
+      removed.push(t.id);
+    } else kept.push(t);
   }
   if (removed.length) {
     load().tasks = kept;

package/lib/vision.js

@@ -1,4 +1,5 @@
 'use strict';
+import { providerApiKey, unsupportedProtocolError } from './provider-protocol.js';
 /**
  * Iris 视觉后端抽象（阶段 1）。
  *
@@ -12,12 +13,14 @@
  */
 import * as adapters from './adapters.js';
 import { hasHostPort } from './host-contract.js';
+import { resolveModelRef, parseModelRef } from './models.js';
 
 /** 后端接口约定：id / kind / model 只读，analyze(request) → Promise<string> */
 
 export class SelfStackVisionBackend {
-  constructor({ provider }) {
+  constructor({ provider, model }) {
     this.provider = provider;
+    this.requestedModel = model;
   }
   get id() {
     return this.provider.id;
@@ -26,13 +29,18 @@ export class SelfStackVisionBackend {
     return 'selfstack';
   }
   get model() {
-    return this.provider.visionModel || 'qwen-vl-plus';
+    const ref = resolveModelRef(this.provider, 'vision', this.requestedModel);
+    return parseModelRef(ref)?.modelId || '';
   }
   async analyze({ question, imageDataUrl, signal }) {
+    const model = this.model;
+    if (!model) throw Object.assign(new Error('iris: 未配置视觉模型，请发现或手工添加并标注 vision 能力'), {
+      code: 'IRIS_PROVIDER_MODEL_UNAVAILABLE'
+    });
     return adapters.visionStream({
-      key: this.provider.apiKey,
+      key: providerApiKey(this.provider),
       baseUrl: this.provider.baseUrl,
-      model: this.model,
+      model,
       prompt: question,
       imageDataUrl,
       signal
@@ -48,13 +56,24 @@ export class HostVisionBackend {
   async analyze(request) { return this.port.analyze(request); }
 }
 
+const VISION_FACTORIES = new Map([
+  ['openai', (provider, model) => new SelfStackVisionBackend({ provider, model })]
+]);
+
 /** Host Adapter 入口；Command 不读取 DSH ctx。 */
 export function buildVisionBackendsFromHost(host, { providers, model }) {
   const backends = [];
   for (const p of providers || []) {
-    if (p && p.type === 'openai') {
-      const provider = model ? { ...p, visionModel: model } : p;
-      backends.push(new SelfStackVisionBackend({ provider }));
+    if (p) {
+      const type = typeof p.type === 'string' && p.type.trim() ? p.type.trim() : 'openai';
+      const factory = VISION_FACTORIES.get(type);
+      if (!factory) {
+        // 保留不可用证据，让宿主视觉端口仍能按既有顺序降级。
+        backends.push({
+          id: p.id, kind: 'selfstack', model: String(model || p.visionModel || ''),
+          async analyze() { throw unsupportedProtocolError(type, 'vision'); }
+        });
+      } else backends.push(factory(p, model));
     }
   }
   if (hasHostPort(host, 'visionModel') && typeof host.ports.visionModel.analyze === 'function') {
@@ -83,6 +102,7 @@ export async function askWithBackends(backends, request) {
         backendId: b.id,
         kind: b.kind,
         model: b.model,
+        code: err && err.code,
         category: err && err.category,
         status: err && err.status,
         message: String((err && err.message) || err)
@@ -90,6 +110,7 @@ export async function askWithBackends(backends, request) {
     }
   }
   const err = new Error('iris: 视觉模型不可用——自持栈与全局视觉模型都失败了');
+  if (errors.length && errors[0].code && errors.every((error) => error.code === errors[0].code)) err.code = errors[0].code;
   err.errors = errors;
   throw err;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Multi-provider image, video, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",
@@ -33,7 +33,7 @@
   ],
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.2-rc.1 <0.1.3-0 || 0.1.5-rc.1"
+      "dsh": "0.2.0-rc.2"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -63,7 +63,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=20.10.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "test": "node scripts/test.mjs",
@@ -71,11 +71,11 @@
     "prepublishOnly": "npm test"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-client-locale": {