@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/provider-adapters.js

@@ -0,0 +1,342 @@
+'use strict';
+
+/**
+ * 已支持协议到 Provider Adapter v0 的映射。
+ *
+ * 凭据和 baseUrl 只被操作闭包捕获，不进入 Adapter 描述或能力快照。
+ * transport 默认为现有低层 HTTP 实现；测试可注入零网络 fixture。
+ */
+import * as defaultTransport from './adapters.js';
+import { ProviderContractError, providerErrorRecord } from './provider-contract.js';
+import { writePrivateFile } from './private-storage.js';
+import { defineProviderAdapter } from './provider-adapter.js';
+import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError } from './provider-protocol.js';
+
+const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
+
+function providerIdentity(provider) {
+  const id = String(provider?.id || '').trim();
+  const key = providerApiKey(provider);
+  const baseUrl = providerMediaBaseUrl(provider);
+  if (!id) throw new TypeError('Provider 配置缺少 id');
+  if (!baseUrl) throw new TypeError('Provider 配置缺少 baseUrl');
+  return { id, key, baseUrl };
+}
+
+function mappedCategory(error, status) {
+  const raw = String(error?.category || '').toLowerCase();
+  if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'aborted';
+  if (error?.name === 'TimeoutError' || /timeout|timed out|超时/i.test(String(error?.message || ''))) return 'timeout';
+  if (status === 401 || status === 403 || raw === 'auth') return 'authentication';
+  if (status === 429 && raw === 'quota') return 'quota';
+  if (status === 429 || raw === 'rate_limit') return 'rate_limit';
+  if (raw === 'invalid_parameter') return 'invalid_request';
+  if (raw === 'network' || error instanceof TypeError) return 'network';
+  if (raw === 'server' || status >= 500) return 'provider';
+  if (!status && /未返回|响应|协议|结构|json/i.test(String(error?.message || ''))) return 'protocol';
+  return 'provider';
+}
+
+/** 当前两个协议共享的错误映射；不保留 cause、rootCause、正文、URL 或凭据。 */
+export function mapProviderAdapterError(error, context = {}) {
+  const statusValue = Number(error?.httpStatus ?? error?.status);
+  const httpStatus = Number.isInteger(statusValue) && statusValue >= 100 && statusValue <= 599
+    ? statusValue
+    : undefined;
+  const stage = String(context.stage || error?.stage || 'submit');
+  const category = mappedCategory(error, httpStatus);
+  let acceptance = context.acceptance || error?.acceptance;
+  if (stage === 'validate' || stage === 'prepare' || stage === 'upload') {
+    acceptance = 'not_accepted';
+  } else if (stage === 'submit') {
+    acceptance = httpStatus && httpStatus >= 400 && httpStatus < 500 && !AMBIGUOUS_4XX.has(httpStatus)
+      ? 'not_accepted'
+      : (error?.acceptance === 'not_accepted' ? 'not_accepted' : 'unknown');
+  } else if (!acceptance) {
+    acceptance = 'accepted';
+  }
+  const retryable = Boolean(
+    context.retryable ?? error?.retryable
+    ?? (httpStatus === 429 || (httpStatus && httpStatus >= 500)
+      || category === 'network' || category === 'timeout')
+  );
+  return providerErrorRecord(error, {
+    stage,
+    category,
+    acceptance,
+    retryable,
+    ...(httpStatus ? { httpStatus } : {})
+  });
+}
+
+function unsupportedCapability(capability, protocol) {
+  return new ProviderContractError(
+    '协议 ' + protocol + ' 不支持任务能力 ' + String(capability || ''),
+    { stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted' }
+  );
+}
+
+function pollFailureKind(status) {
+  const value = String(status || '').toUpperCase();
+  if (value === 'CANCELED' || value === 'CANCELLED') return 'canceled';
+  if (value === 'UNKNOWN') return 'unknown';
+  return 'failed';
+}
+
+function remoteImageArtifacts(urls) {
+  return (urls || []).map((url) => ({ kind: 'remote-url', url, mediaType: 'image/png' }));
+}
+
+function openAiImageArtifacts(items) {
+  return (items || []).map((item) => {
+    if (item && item.b64) {
+      return { kind: 'inline-base64', data: item.b64, mediaType: 'image/png' };
+    }
+    if (item && item.url) {
+      return { kind: 'remote-url', url: item.url, mediaType: 'image/png' };
+    }
+    throw new ProviderContractError('同步图片结果缺少 b64 或 URL', {
+      stage: 'response', category: 'protocol', acceptance: 'accepted'
+    });
+  });
+}
+
+function writeInlineArtifact(artifact, targetPath) {
+  const data = String(artifact?.data || '').trim();
+  const body = Buffer.from(data, 'base64');
+  if (!data || body.length === 0 || body.toString('base64') !== data) {
+    throw new ProviderContractError('inline-base64 图片数据无效', {
+      stage: 'download', category: 'protocol', acceptance: 'accepted'
+    });
+  }
+  writePrivateFile(targetPath, body, { flag: 'wx' });
+  return { bytes: body.length };
+}
+
+function operationsForDashScope(provider, transport) {
+  const { key, baseUrl } = providerIdentity(provider);
+  return {
+    async discover({ signal, timeoutMs } = {}) {
+      return { models: await transport.listModels({ key, baseUrl, signal, timeoutMs }) };
+    },
+
+    async submit(request = {}) {
+      const input = request.input || {};
+      const common = {
+        key, baseUrl, model: request.model, signal: request.signal,
+        ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+      };
+      if (request.capability === 'image') {
+        if (transport.dashscopeImageMode(request.model) === 'legacy-async') {
+          const remoteTaskId = await transport.submitImage({
+            ...common, prompt: input.prompt, size: input.size, n: input.n
+          });
+          return { kind: 'accepted', remoteTaskId };
+        }
+        const urls = await transport.generateImageMultimodal({
+          ...common, prompt: input.prompt, size: input.size, n: input.n
+        });
+        return {
+          kind: 'completed', value: { kind: 'urls', items: urls },
+          artifacts: remoteImageArtifacts(urls)
+        };
+      }
+      if (request.capability === 'video') {
+        const remoteTaskId = await transport.submitVideo({
+          ...common,
+          prompt: input.prompt,
+          imgDataUrl: input.imgDataUrl,
+          size: input.size,
+          duration: input.duration,
+          audioUrl: input.audioUrl,
+          resolution: input.resolution
+        });
+        return { kind: 'accepted', remoteTaskId };
+      }
+      if (request.capability === 'transcribe') {
+        const remoteTaskId = await transport.submitTranscription({
+          ...common, audioUrl: input.audioUrl
+        });
+        return { kind: 'accepted', remoteTaskId };
+      }
+      if (request.capability === 'tts') {
+        const value = await transport.synthesizeTts({
+          ...common, text: input.text, voice: input.voice
+        });
+        // E2：同步合成产物物化为 Core Artifact——URL 走下载，inline base64 直接落盘。
+        const artifacts = value.audioUrl
+          ? [{ kind: 'remote-url', url: value.audioUrl, mediaType: 'audio/mpeg' }]
+          : [{ kind: 'inline-base64', data: value.audioB64, mediaType: 'audio/mpeg' }];
+        return { kind: 'completed', value, artifacts };
+      }
+      throw unsupportedCapability(request.capability, 'dashscope');
+    },
+
+    async poll(request = {}) {
+      const common = {
+        key, baseUrl, remoteTaskId: request.remoteTaskId, signal: request.signal,
+        ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+      };
+      if (request.capability === 'transcribe') {
+        const result = await transport.pollTranscriptionTask(common);
+        if (!result.done) return { kind: 'pending', progress: result.status || 'running' };
+        if (!result.ok) {
+          return {
+            kind: pollFailureKind(result.status),
+            error: mapProviderAdapterError(result.message || '转写任务失败', {
+              stage: 'poll', acceptance: 'accepted'
+            })
+          };
+        }
+        // E3：转写正文物化为 text/plain Artifact（inline-base64，不再依赖签名 URL 生命周期）。
+        const text = String(result.text || '');
+        return {
+          kind: 'succeeded',
+          value: { kind: 'text', text },
+          artifacts: [{ kind: 'inline-base64', data: Buffer.from(text, 'utf8').toString('base64'), mediaType: 'text/plain' }]
+        };
+      }
+      if (request.capability === 'image' || request.capability === 'video') {
+        const result = await transport.pollTask(common);
+        if (!result.done) return { kind: 'pending', progress: result.status || 'running' };
+        if (!result.ok) {
+          return {
+            kind: pollFailureKind(result.status),
+            error: mapProviderAdapterError(result.message || '生成任务失败', {
+              stage: 'poll', acceptance: 'accepted'
+            })
+          };
+        }
+        return {
+          kind: 'succeeded',
+          artifacts: (result.urls || []).map((url) => ({ kind: 'remote-url', url }))
+        };
+      }
+      throw unsupportedCapability(request.capability, 'dashscope');
+    },
+
+    async download(request = {}) {
+      const artifact = request.artifact || {};
+      const targetPath = String(request.targetPath || '').trim();
+      if (!targetPath) {
+        throw new ProviderContractError('download 需要 targetPath', {
+          stage: 'download', category: 'local_io', acceptance: 'accepted'
+        });
+      }
+      if (artifact.kind === 'inline-base64') {
+        return writeInlineArtifact(artifact, targetPath);
+      }
+      if (artifact.kind !== 'remote-url' || !artifact.url) {
+        throw new ProviderContractError('download 需要 remote-url artifact', {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
+      return {
+        bytes: await transport.downloadTo(artifact.url, targetPath, {
+          signal: request.signal,
+          ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+        })
+      };
+    },
+
+    mapError: mapProviderAdapterError
+  };
+}
+
+export function createDashScopeProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  const { key, baseUrl } = providerIdentity(provider);
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'dashscope',
+    capabilities: ['image', 'video', 'tts', 'transcribe'],
+    operations: operationsForDashScope(provider, transport),
+    async prepareInput({ model, filePath, signal, timeoutMs } = {}) {
+      return { url: await transport.uploadTempFile({ key, baseUrl, model, filePath, signal, timeoutMs }) };
+    },
+    unsupported: {
+      cancel: '当前 DashScope 媒体协议未提供经过验证的远端取消实现'
+    }
+  });
+}
+
+function operationsForOpenAiImages(provider, transport) {
+  const { key, baseUrl } = providerIdentity(provider);
+  return {
+    async discover({ signal, timeoutMs } = {}) {
+      return { models: await transport.listModels({ key, baseUrl, signal, timeoutMs }) };
+    },
+
+    async submit(request = {}) {
+      if (request.capability !== 'image') {
+        throw unsupportedCapability(request.capability, 'openai-images');
+      }
+      const input = request.input || {};
+      const items = await transport.openAiGenerateImage({
+        key,
+        baseUrl,
+        model: request.model,
+        prompt: input.prompt,
+        size: input.size,
+        n: input.n,
+        signal: request.signal,
+        ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+      });
+      return {
+        kind: 'completed', value: { kind: 'openai', items },
+        artifacts: openAiImageArtifacts(items)
+      };
+    },
+
+    async download(request = {}) {
+      const artifact = request.artifact || {};
+      const targetPath = String(request.targetPath || '').trim();
+      if (!targetPath) {
+        throw new ProviderContractError('download 需要 targetPath', {
+          stage: 'download', category: 'local_io', acceptance: 'accepted'
+        });
+      }
+      if (artifact.kind === 'inline-base64') return writeInlineArtifact(artifact, targetPath);
+      if (artifact.kind !== 'remote-url' || !artifact.url) {
+        throw new ProviderContractError('download 需要可物化的图片 artifact', {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
+      return {
+        bytes: await transport.downloadTo(artifact.url, targetPath, {
+          signal: request.signal,
+          ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+        })
+      };
+    },
+
+    mapError: mapProviderAdapterError
+  };
+}
+
+export function createOpenAiImagesProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'openai-images',
+    capabilities: ['image'],
+    operations: operationsForOpenAiImages(provider, transport),
+    unsupportedPreparation: 'OpenAI Images 兼容路径未实现临时输入上传',
+    unsupported: {
+      poll: 'OpenAI Images 兼容路径在当前实现中同步返回结果',
+      cancel: '同步图片响应没有可验证的远端取消任务'
+    }
+  });
+}
+
+const PROTOCOL_FACTORIES = new Map([
+  ['dashscope', createDashScopeProviderAdapter],
+  ['openai-images', createOpenAiImagesProviderAdapter]
+]);
+
+export function createConfiguredProviderAdapter(provider, options = {}) {
+  const selection = options.protocol
+    ? selectMediaProtocol({ ...provider, mediaProtocol: options.protocol, protocolInferred: false })
+    : selectMediaProtocol(provider);
+  const factory = PROTOCOL_FACTORIES.get(selection.mediaProtocol);
+  if (!factory) throw unsupportedProtocolError(selection.mediaProtocol);
+  return factory(provider, options);
+}

package/lib/provider-catalog.js

@@ -0,0 +1,171 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CAPABILITIES } from './capability.js';
+import { modelPool, orderedModels, providerModels, parseModelRef, resolveModelRef, resolvePoolModel, selectionReasonForModel } from './models.js';
+import { dashscopeApiBase, selectMediaProtocol, providerMediaBaseUrl, isConfiguredProvider } from './provider-protocol.js';
+import { redactProviderMessage } from './provider-contract.js';
+
+export class ProviderCatalogError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProviderCatalogError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new ProviderCatalogError(code, message);
+}
+
+/** Headless 边界只读取显式配置文件；不推断 DSH_HOME、HOME 或 cwd。 */
+export function loadProviderCatalog(configPath) {
+  const supplied = String(configPath || '').trim();
+  if (!supplied || !path.isAbsolute(supplied)) {
+    fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 必须是显式绝对路径');
+  }
+  let source;
+  try {
+    const stat = fs.lstatSync(supplied);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('not a regular file');
+    if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+      fail('IRIS_PROVIDER_CONFIG_PERMISSIONS', 'provider-config 权限过宽；请限制为仅当前用户可读写');
+    }
+    source = fs.readFileSync(supplied, 'utf8');
+  } catch (error) {
+    if (error instanceof ProviderCatalogError) throw error;
+    fail('IRIS_PROVIDER_CONFIG_UNREADABLE', 'provider-config 不存在、不是普通文件或无法读取');
+  }
+  let parsed;
+  try { parsed = JSON.parse(source); }
+  catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 不是有效 JSON'); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+      || !Array.isArray(parsed.providers)
+      || (parsed.assignments !== undefined && (!parsed.assignments || typeof parsed.assignments !== 'object'
+        || Array.isArray(parsed.assignments)))) {
+    fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 结构无效');
+  }
+  return parsed;
+}
+
+const CANDIDATE_CAP_LABEL = Object.freeze({
+  [CAPABILITIES.IMAGE]: '图片', [CAPABILITIES.VIDEO]: '视频',
+  [CAPABILITIES.TTS]: '语音', [CAPABILITIES.TRANSCRIBE]: '转写'
+});
+
+/** 与稳定配置层相同的“手工顺序优先、池序补齐”候选规则（image/video/tts/transcribe 同构）。 */
+function candidatesFromCatalog(catalog, requestedModelRef, capability) {
+  const label = CANDIDATE_CAP_LABEL[capability];
+  if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
+  const providers = catalog.providers.filter(isConfiguredProvider);
+  const pool = modelPool(providers).filter((item) => item.capabilities.includes(capability));
+  const requested = String(requestedModelRef || '').trim();
+  if (requested) {
+    const parsed = parseModelRef(requested);
+    if (!parsed && requested.includes('::')) fail('IRIS_PROVIDER_MODEL_INVALID', 'model_ref 格式无效');
+    const exact = resolvePoolModel(pool, requested, capability);
+    if (!exact) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `指定模型不存在、未启用或没有${label}能力`);
+    const provider = providers.find((item) => item.id === exact.providerId);
+    return Object.freeze([Object.freeze({
+      provider, model: exact.id, modelRef: resolveModelRef(provider, capability, requested),
+      selectionReason: 'explicit'
+    })]);
+  }
+  const assignment = catalog.assignments?.[capability];
+  const ordered = orderedModels(pool, capability, assignment);
+  if (!ordered.length) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `provider-config 中没有可用${label}模型`);
+  return Object.freeze(ordered.map((item) => Object.freeze({
+    provider: providers.find((provider) => provider.id === item.providerId),
+    model: item.id,
+    modelRef: item.ref,
+    selectionReason: selectionReasonForModel(pool, capability, assignment, item)
+  })));
+}
+
+export function imageCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE);
+}
+
+export function videoCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO);
+}
+
+export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS);
+}
+
+export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE);
+}
+
+/** 只读配置投影；不构造 Adapter、不发现模型、不暴露端点或凭据。 */
+export function providerCatalogSnapshot(catalog) {
+  const safeLabel = (value) => value
+    ? redactProviderMessage(String(value).replace(/https?:\/\/[^\s<>"']+/gi, '[URL]')) : '';
+  return {
+    schemaVersion: 1,
+    providers: catalog.providers.filter((provider) => provider && typeof provider === 'object').map((provider) => {
+      const models = providerModels(provider);
+      const selection = selectMediaProtocol(provider);
+      return {
+        id: safeLabel(provider.id), name: safeLabel(provider.name || provider.id),
+        enabled: provider.enabled !== false, configured: isConfiguredProvider(provider),
+        auth: provider.auth === 'none' ? 'none' : 'bearer',
+        mediaProtocol: safeLabel(selection.mediaProtocol), protocolInferred: selection.protocolInferred,
+        capabilities: Object.values(CAPABILITIES).filter((capability) => models.some((model) => model.capabilities.includes(capability))),
+        modelCount: models.length
+      };
+    })
+  };
+}
+
+export function catalogCapabilitySnapshot(catalog) {
+  const pool = modelPool(catalog.providers.filter(isConfiguredProvider));
+  return {
+    schemaVersion: 1,
+    source: 'configuration',
+    capabilities: Object.values(CAPABILITIES).map((capability) => {
+      const candidates = orderedModels(pool, capability, catalog.assignments?.[capability]).map((model) => model.ref);
+      return { capability, candidates, ...(candidates.length ? {} : { gap: 'no_configured_model' }) };
+    })
+  };
+}
+
+/** 非敏感摘要把 Task 绑定到提交时实际使用的媒体端点与协议。 */
+export function providerTaskBinding(provider) {
+  const baseUrl = providerMediaBaseUrl(provider);
+  const protocol = selectMediaProtocol(provider).mediaProtocol;
+  let endpoint;
+  try {
+    const url = new URL(baseUrl);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('unsafe endpoint');
+    if (!['dashscope', 'openai-images'].includes(protocol)) throw new Error('unknown protocol');
+    endpoint = protocol === 'dashscope' ? dashscopeApiBase(baseUrl) : url.href.replace(/\/+$/, '');
+  } catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'Provider 媒体端点或协议无效'); }
+  return 'sha256:' + crypto.createHash('sha256').update(JSON.stringify([1, protocol, endpoint])).digest('hex');
+}
+
+/** 恢复只使用 Task 已保存的 Provider/模型；忽略当前 assignment 与 failover 顺序。 */
+export function providerForTaskFromCatalog(catalog, task) {
+  const capability = CAPABILITIES[
+    task?.capability === 'video' ? 'VIDEO'
+      : task?.capability === 'image' ? 'IMAGE'
+      : task?.capability === 'tts' ? 'TTS'
+      : task?.capability === 'transcribe' ? 'TRANSCRIBE' : ''
+  ];
+  if (!capability) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 恢复解析只开放图片、视频、语音与转写 Task');
+  const label = { video: '视频', tts: '语音', transcribe: '转写' }[task.capability] || '图片';
+  const parsed = parseModelRef(task.modelRef);
+  if (!parsed || parsed.providerId !== task.providerId) fail('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task 的 Provider 与模型身份不一致');
+  const matches = catalog.providers.filter((item) => item && item.id === task.providerId);
+  if (matches.length > 1) fail('IRIS_PROVIDER_CONFIG_AMBIGUOUS', 'provider-config 存在重复 Provider ID');
+  const provider = matches[0];
+  if (!provider || provider.enabled === false || (provider.auth !== 'none' && (typeof provider.apiKey !== 'string' || !provider.apiKey.trim()))) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  if (!task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISSING', '旧 Task 缺少提交端点绑定；仅支持只读查看，不猜测恢复配置');
+  if (providerTaskBinding(provider) !== task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISMATCH', 'Task 提交端点或协议已改变；拒绝向新端点观察原任务');
+  const model = modelPool([provider]).find((item) => item.providerId === parsed.providerId && item.id === parsed.modelId && item.capabilities.includes(capability));
+  if (!model) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `Task 原模型已移除或不再具备${label}能力`);
+  return provider;
+}

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-health.js

@@ -0,0 +1,59 @@
+'use strict';
+
+export const PROVIDER_HEALTH_SCHEMA_VERSION = 1;
+export const PROVIDER_HEALTH_FRESH_MS = 7 * 24 * 60 * 60 * 1000;
+export const PROVIDER_HEALTH_STATES = Object.freeze([
+  'unconfigured',
+  'configured',
+  'verified',
+  'failed'
+]);
+
+const DEFINITIVE_FAILURES = new Set(['authentication', 'auth', 'permission']);
+
+function validTime(value) {
+  const ms = Date.parse(String(value || ''));
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+export function isDefinitiveHealthFailure(value) {
+  const status = Number(value && (value.httpStatus ?? value.status));
+  const category = String(value && value.category || '').toLowerCase();
+  return status === 401 || status === 403 || DEFINITIVE_FAILURES.has(category);
+}
+
+export function healthObservationState(observation, {
+  now = Date.now(),
+  freshMs = PROVIDER_HEALTH_FRESH_MS
+} = {}) {
+  if (!observation || typeof observation !== 'object') return 'configured';
+  const successAt = validTime(observation.lastSuccess && observation.lastSuccess.at);
+  const failureAt = validTime(observation.lastFailure && observation.lastFailure.at);
+  const cutoff = Number(now) - Number(freshMs);
+
+  if (failureAt >= cutoff && failureAt >= successAt
+      && isDefinitiveHealthFailure(observation.lastFailure)) {
+    return 'failed';
+  }
+  if (successAt >= cutoff && successAt > failureAt) return 'verified';
+  return 'configured';
+}
+
+export function aggregateHealthStates(states) {
+  const list = (Array.isArray(states) ? states : []).filter((state) =>
+    PROVIDER_HEALTH_STATES.includes(state) && state !== 'unconfigured');
+  if (!list.length) return 'unconfigured';
+  if (list.includes('verified')) return 'verified';
+  if (list.includes('configured')) return 'configured';
+  return 'failed';
+}
+
+export function newestHealthEvidence(observation) {
+  const entries = [
+    observation && observation.lastSuccess,
+    observation && observation.lastFailure,
+    observation && observation.lastTransient
+  ].filter((item) => item && validTime(item.at));
+  entries.sort((a, b) => validTime(b.at) - validTime(a.at));
+  return entries[0] || null;
+}