@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/lib/command-service.js

@@ -12,16 +12,20 @@ import {
   rebuildCoreArtifactIndex
 } from './core-artifacts.js';
 import { inspectCoreTask, listCoreTasks } from './core-tasks.js';
-import { cropImage, pixelDiff, PixelError } from './pixels.js';
+import { cropImage, pixelDiff, imageDimensions, PixelError } from './pixels.js';
 import { extractFrames, normalizeFramesOptions, probeVideo } from './media-probe.js';
 import { hasProviderOperation } from './provider-adapter.js';
 import { createProviderTaskRunner } from './provider-task-runner.js';
 import { GenerationInputError, normalizeGenerationInput } from './generation-input.js';
+import { videoTaskCandidates } from './video-input.js';
+import { waitForCoreTask } from './task-wait.js';
+import { planCoreDeletion, planCoreCleanup, quarantineCoreFiles, inspectCoreTransactions, restoreCoreTransaction } from './core-maintenance.js';
 
 export const COMMAND_CONTRACT_VERSION = 0;
 export const CORE_COMMANDS = Object.freeze([
-  'crop', 'media.diff', 'media.frames', 'task.inspect', 'task.list', 'task.observe', 'task.reobserve', 'task.redeliver', 'task.cancel', 'task.retry',
-  'artifact.inspect', 'artifact.list', 'artifact.export', 'artifact.rebuild'
+  'crop', 'media.diff', 'media.frames', 'media.html', 'task.inspect', 'task.list', 'task.wait', 'task.observe', 'task.reobserve', 'task.redeliver', 'task.cancel', 'task.retry',
+  'task.inspect-many', 'artifact.inspect', 'artifact.inspect-many', 'artifact.list', 'artifact.export', 'artifact.export-many', 'artifact.rebuild',
+  'core.delete', 'core.cleanup', 'core.transactions', 'core.restore'
 ]);
 
 export class CommandError extends Error {
@@ -82,11 +86,77 @@ function abortError() {
   return error;
 }
 
+function idList(input, field) {
+  const ids = input[field];
+  if (!Array.isArray(ids) || !ids.length || ids.length > 200 || !ids.every(id => typeof id === 'string') || new Set(ids).size !== ids.length) {
+    throw commandError('IRIS_COMMAND_INPUT_INVALID', field + ' 必须是 1–200 个不重复 ID 的数组');
+  }
+  return ids;
+}
+
+function queryInput(input, fields) {
+  exactInput(input, ['offset', 'limit', ...fields]);
+  for (const [key, value] of Object.entries(input)) {
+    if (['offset', 'limit'].includes(key)) {
+      if (!Number.isSafeInteger(value) || value < (key === 'offset' ? 0 : 1) || (key === 'limit' && value > 200)) throw commandError('IRIS_COMMAND_INPUT_INVALID', 'offset 必须非负，limit 必须是 1–200 的整数');
+    } else if (typeof value !== 'string' || !value.trim()) throw commandError('IRIS_COMMAND_INPUT_INVALID', '过滤字段必须是非空字符串');
+  }
+}
+
 export function createCommandService(runtime, ports = {}) {
   if (!runtime || typeof runtime.run !== 'function') throw new TypeError('Command Service 需要 Core Runtime');
 
   async function execute(name, input) {
     if (!CORE_COMMANDS.includes(name)) throw commandError('IRIS_COMMAND_UNKNOWN', `未知 Command：${String(name)}`);
+    if (name === 'core.delete' || name === 'core.cleanup') {
+      exactInput(input, name === 'core.delete' ? ['task_ids', 'artifact_ids', 'confirm_delete'] : ['paths', 'older_than_ms', 'confirm_delete']);
+      if (input.confirm_delete !== undefined && typeof input.confirm_delete !== 'boolean') throw commandError('IRIS_COMMAND_INPUT_INVALID', 'confirm_delete 必须是布尔值');
+      return runtime.run(input.confirm_delete === true ? 'execute' : 'inspect', ({ dataRoot, signal }) => {
+        if (signal.aborted) throw abortError();
+        let plan = name === 'core.delete' ? planCoreDeletion(dataRoot, input) : planCoreCleanup(dataRoot, input);
+        if (name === 'core.cleanup' && input.confirm_delete === true) {
+          const paths = input.paths;
+          if (!Array.isArray(paths) || !paths.length || paths.length > 200 || !paths.every(file => typeof file === 'string') || new Set(paths).size !== paths.length) throw commandError('IRIS_COMMAND_INPUT_INVALID', '执行清理必须明确指定 1–200 个预览中的 paths');
+          const entries = paths.map(file => plan.candidates.find(entry => entry.path === file));
+          if (entries.some(entry => !entry)) throw commandError('IRIS_CORE_CLEANUP_CHANGED', '指定路径不在当前可清理预览中');
+          plan = { operation: 'cleanup', allowed: true, entries };
+        }
+        const result = input.confirm_delete === true ? quarantineCoreFiles(dataRoot, plan) : { preview: true, ...plan };
+        return { contractVersion: COMMAND_CONTRACT_VERSION, command: name, ...result };
+      });
+    }
+    if (name === 'core.transactions') {
+      exactInput(input, []);
+      return runtime.run('inspect', ({ dataRoot }) => ({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, transactions: inspectCoreTransactions(dataRoot) }));
+    }
+    if (name === 'core.restore') {
+      exactInput(input, ['transaction_id']);
+      return runtime.run('execute', ({ dataRoot }) => ({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, ...restoreCoreTransaction(dataRoot, input.transaction_id) }));
+    }
+    if (name === 'media.html') {
+      exactInput(input, ['html', 'width', 'height', 'full_page']);
+      if (typeof input.html !== 'string' || !input.html.trim() || Buffer.byteLength(input.html) > 1024 * 1024) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID', 'html 必须是非空字符串，最多 1 MiB');
+      }
+      const width = input.width ?? 1280, height = input.height ?? 720;
+      if (![width, height].every(value => Number.isSafeInteger(value) && value > 0 && value <= 4096)
+          || (input.full_page !== undefined && typeof input.full_page !== 'boolean')) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID', 'width/height 必须是 1–4096 的整数，full_page 必须是布尔值');
+      }
+      if (typeof ports.browser?.renderHtml !== 'function') throw commandError('IRIS_COMMAND_BROWSER_REQUIRED', 'HTML 截图需要 Browser Port');
+      return runtime.run('execute', async ({ dataRoot, signal }) => {
+        const rendered = await ports.browser.renderHtml({ html: input.html, width, height, fullPage: input.full_page !== false, signal });
+        if (signal.aborted) throw abortError();
+        const bytes = Buffer.from(rendered.bytes);
+        if (rendered.mediaType !== 'image/png' || !bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+          throw commandError('IRIS_COMMAND_PROCESSING_FAILED', '浏览器没有返回 PNG 截图');
+        }
+        const dimensions = await imageDimensions(bytes);
+        if (signal.aborted) throw abortError();
+        const artifact = createCoreArtifact(dataRoot, { bytes, mediaType: 'image/png', kind: 'html-screenshot', metadata: dimensions });
+        return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, artifact });
+      });
+    }
     if (name === 'crop') {
       exactInput(input, ['image_path', 'artifact_id', 'left', 'top', 'width', 'height']);
       const hasPath = Boolean(String(input.image_path || '').trim());
@@ -274,6 +344,12 @@ export function createCommandService(runtime, ports = {}) {
         });
       });
     }
+    if (name === 'task.wait') {
+      exactInput(input, ['task_id', 'timeout_ms', 'poll_interval_ms']);
+      const result = await waitForCoreTask(runtime, input.task_id, { timeoutMs: input.timeout_ms, pollIntervalMs: input.poll_interval_ms,
+        ...(typeof ports.resolveTaskAdapter === 'function' ? { observe: () => execute('task.observe', { task_id: input.task_id }) } : {}) });
+      return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, ...result });
+    }
     // task.reobserve 是人工触发观察的对外命令名（DSH API/工作台），与 task.observe
     // 共用同一份门与单步 poll 实现；语义不区分，绝不 submit。
     if (name === 'task.observe' || name === 'task.reobserve') {
@@ -339,23 +415,28 @@ export function createCommandService(runtime, ports = {}) {
           throw commandError('IRIS_TASK_NOT_RETRYABLE', '只有终态且未成功交付的 Task 可以重试为新任务');
         }
         let normalized;
-        try { normalized = normalizeGenerationInput(before.capability, input.provider_input); }
+        try { normalized = normalizeGenerationInput(before.capability, input.provider_input, { allowVideoPaths: before.capability === 'video' }); }
         catch (error) {
           if (error instanceof GenerationInputError) throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);
           throw error;
         }
         const providerInput = normalized.providerInput;
+        if (before.sourceArtifactId && !normalized.sourceArtifactId) {
+          throw commandError('IRIS_COMMAND_INPUT_INVALID', '改图重试必须重新提供 source_artifact_id 和修改指令');
+        }
         if (Object.hasOwn(input.provider_input, 'model_ref')) {
           throw commandError('IRIS_COMMAND_INPUT_INVALID', 'retry 的模型覆盖请使用外层 model_ref');
         }
         const modelRef = String(input.model_ref || '').trim();
         if (input.model_ref !== undefined && !modelRef) throw commandError('IRIS_COMMAND_INPUT_INVALID', 'model_ref 必须是 providerId::modelId 复合引用');
         if (typeof ports.resolveTaskCandidates !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.retry 需要宿主显式提供候选链 resolver');
-        const candidates = await ports.resolveTaskCandidates({ capability: before.capability, modelRef });
+        let candidates = await ports.resolveTaskCandidates({ capability: before.capability, modelRef });
+        if (before.capability === 'video') candidates = videoTaskCandidates(candidates, normalized);
         const result = await createProviderTaskRunner(runtime).submit({
           capability: before.capability,
           candidates,
           providerInput,
+          sourceArtifactId: normalized.sourceArtifactId,
           retriedFrom: before.id
         });
         return Object.freeze({
@@ -377,7 +458,7 @@ export function createCommandService(runtime, ports = {}) {
       }));
     }
     if (name === 'task.list') {
-      exactInput(input, ['offset', 'limit']);
+      queryInput(input, ['status', 'capability', 'provider_id', 'model_ref', 'outcome', 'delivery_state']);
       return runtime.run('inspect', ({ dataRoot }) => Object.freeze({
         contractVersion: COMMAND_CONTRACT_VERSION,
         command: name,
@@ -393,7 +474,7 @@ export function createCommandService(runtime, ports = {}) {
       }));
     }
     if (name === 'artifact.list') {
-      exactInput(input, ['offset', 'limit']);
+      queryInput(input, ['kind', 'media_type', 'task_id']);
       return runtime.run('inspect', ({ dataRoot }) => Object.freeze({
         contractVersion: COMMAND_CONTRACT_VERSION,
         command: name,
@@ -408,6 +489,39 @@ export function createCommandService(runtime, ports = {}) {
         ...rebuildCoreArtifactIndex(dataRoot)
       }));
     }
+    if (name === 'task.inspect-many' || name === 'artifact.inspect-many') {
+      const task = name.startsWith('task.'), field = task ? 'task_ids' : 'artifact_ids';
+      exactInput(input, [field]);
+      const ids = idList(input, field);
+      return runtime.run('inspect', ({ dataRoot }) => ({ contractVersion: COMMAND_CONTRACT_VERSION, command: name,
+        results: ids.map(id => {
+          try { return { id, [task ? 'task' : 'artifact']: task ? inspectCoreTask(dataRoot, id) : inspectCoreArtifact(dataRoot, id) }; }
+          catch (error) { return { id, error: { code: error.code || 'IRIS_COMMAND_FAILED' } }; }
+        }) }));
+    }
+    if (name === 'artifact.export-many') {
+      exactInput(input, ['artifact_ids', 'output_directory']);
+      const ids = idList(input, 'artifact_ids');
+      const directory = input.output_directory;
+      if (typeof directory !== 'string' || !path.isAbsolute(directory) || !fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID', 'output_directory 必须是已存在的绝对目录');
+      }
+      return runtime.run('execute', ({ dataRoot, signal }) => {
+        const extensions = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/webp': '.webp', 'image/gif': '.gif', 'video/mp4': '.mp4', 'video/webm': '.webm', 'audio/wav': '.wav', 'audio/mpeg': '.mp3', 'audio/ogg': '.ogg', 'audio/flac': '.flac', 'text/plain': '.txt', 'application/json': '.json' };
+        const outputs = ids.map(id => {
+          const artifact = inspectCoreArtifact(dataRoot, id);
+          const file = path.join(directory, id + (extensions[artifact.mediaType] || '.bin'));
+          if (fs.existsSync(file)) throw commandError('IRIS_ARTIFACT_EXPORT_EXISTS', '批量导出目标已存在；未导出任何文件');
+          return { id, file };
+        });
+        const results = outputs.map(({ id, file }) => {
+          if (signal.aborted) return { id, exported: false, error: { code: 'IRIS_COMMAND_ABORTED' } };
+          try { return { id, ...exportCoreArtifact(dataRoot, id, file) }; }
+          catch (error) { return { id, exported: false, error: { code: error.code || 'IRIS_ARTIFACT_EXPORT_FAILED' } }; }
+        });
+        return { contractVersion: COMMAND_CONTRACT_VERSION, command: name, results };
+      });
+    }
     exactInput(input, ['artifact_id', 'output_path']);
     return runtime.run('execute', ({ dataRoot }) => Object.freeze({
       contractVersion: COMMAND_CONTRACT_VERSION,

package/lib/composite-vision-routing.js

@@ -0,0 +1,42 @@
+'use strict';
+/** Host 选型留边界，定位/拼图只消费共享模型端口；准备也属于本次预算。 */
+import sharp from 'sharp';
+import { runVisionOperation, runVisionRequest } from './vision-model-routing.js';
+import { locateObject, normalizeLocateTarget, createLocateImageRequest } from './locate.js';
+import { summarizeMedia } from './summarize.js';
+import { VISION_BUDGET } from './vision-core.js';
+import { normalizeModelCall } from './model-port-contract.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+export async function runLocateRequest(host, { providers = [], model, target, image, prepareImage, signal, budget = VISION_BUDGET, onRateLimit }) {
+  target = normalizeLocateTarget(target);
+  const inputs = new Map();
+  const result = await runVisionOperation(host, { providers, model, signal, budget, onRateLimit, prepareImages: true,
+    orientImages: true, prepareImageRequest: createLocateImageRequest(target, inputs) }, async (ports, operation) => {
+    const resolved = await waitForModelWork(() => prepareImage ? prepareImage(operation.signal) : image, operation.signal);
+    const source = normalizeModelCall(ports[0].describe(), { prompt: target, image: resolved }, { budget }).request.image;
+    const { width, height } = await waitForModelWork(() => sharp(Buffer.from(source.bytes)).metadata(), operation.signal);
+    const completion = await locateObject(ports, { target, image: source, width, height }, { operation, budget });
+    return { completion, ...completion.bbox, width, height, input: inputs.get(completion.identity.backendId) };
+  });
+  const { answer: _answer, ...location } = result;
+  return location;
+}
+
+export async function runSummaryRequest(host, { providers = [], model, prepareMedia, frames, question, transcript, signal, budget = VISION_BUDGET, onRateLimit }) {
+  return runVisionOperation(host, { providers, model, signal, budget, onRateLimit }, async (ports, operation) => {
+    const media = await waitForModelWork(() => prepareMedia ? prepareMedia(operation.signal) : { frames, transcript }, operation.signal);
+    const completion = await summarizeMedia({ ports, frames: media.frames, question, transcript: media.transcript,
+      operation, budget });
+    return { completion, sheet: completion.sheet, frames: media.frames, meta: media.meta, transcriptNote: media.transcriptNote || '' };
+  });
+}
+
+/** 增强描述沿用共享调用；失败不改变已经完成的媒体交付。 */
+export async function describeGeneratedImage(host, { providers = [], originalPrompt, image, prepareImage, signal, onRateLimit }) {
+  try {
+    const result = await runVisionRequest(host, { providers, image, prepareImage, signal, onRateLimit,
+      question: `用不超过两句话描述这张图片的主题与构图。生成该图的提示词是：「${String(originalPrompt).slice(0, 200)}」` });
+    return result.answer.slice(0, 300);
+  } catch (_) { return ''; }
+}

package/lib/config.js

@@ -1,4 +1,5 @@
 'use strict';
+import { normalizeVisionInputLimits } from './vision-image-input.js';
 /**
  * Iris 配置存储：$DSH_HOME/iris/v1/providers.json
  * Iris 独立持有配置；旧工作台仅作为用户显式指定的一次性导入来源。
@@ -10,14 +11,15 @@ import os from 'node:os';
 import * as cap from './capability.js';
 import * as models from './models.js';
 import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
-import { selectMediaProtocol, isConfiguredProvider } from './provider-protocol.js';
+import { selectMediaProtocol, selectImageProtocol, normalizeImageProtocol, isConfiguredProvider } from './provider-protocol.js';
 import { redactProviderMessage } from './provider-contract.js';
 import {
   PROVIDER_HEALTH_FRESH_MS,
   aggregateHealthStates,
   healthObservationState,
   isDefinitiveHealthFailure,
-  newestHealthEvidence
+  newestHealthEvidence,
+  modelRateLimit, recordModelRateLimit, clearModelRateLimit, clearModelCapabilityHealth
 } from './provider-health.js';
 
 function isPlainObject(value) {
@@ -191,7 +193,7 @@ export function pickFor(capability) {
   const pool = models.modelPool(providers());
   let m = null;
   for (const ref of assignmentOrder(capability)) {
-    m = pool.find((x) => x.ref === ref && x.capabilities.includes(capability));
+    m = pool.find((x) => !x.rateLimited && x.ref === ref && x.capabilities.includes(capability));
     if (m) break;
   }
   if (!m) m = models.pickModel(pool, capability);
@@ -207,9 +209,9 @@ export function pickFor(capability) {
  * 已分配顺序优先（阶段 6 条目 4），其余按池顺序补齐（去重）。
  * 一个 provider 若池里有多个该能力模型，会返回多条（各自带不同模型）。
  */
-export function pickAllFor(capability) {
+export function pickAllFor(capability, { includeRateLimited = false } = {}) {
   const pool = models.modelPool(providers());
-  const chosen = models.orderedModels(pool, capability, assignments()[capability]);
+  const chosen = models.orderedModels(pool, capability, assignments()[capability], { includeRateLimited });
   const out = [];
   for (const m of chosen) {
     const p = providerById(m.providerId);
@@ -352,8 +354,10 @@ function applyProviderHealth(provider, modelId, capability, result, fallbackSour
     health.observations.push(observation);
   }
   const evidence = observationEvidence(provider, result || {}, fallbackSource);
+  recordModelRateLimit(provider, model, { ...evidence, retryAfterMs: result?.retryAfterMs, until: result?.until, reason: result?.reason });
   if (result && result.ok === true) {
     observation.lastSuccess = evidence;
+    if (evidence.source === 'probe') clearModelRateLimit(provider, model);
   } else if (isDefinitiveHealthFailure({ ...result, ...evidence })) {
     observation.lastFailure = evidence;
   } else {
@@ -391,10 +395,11 @@ function resetHealthOnCriticalChange(previous, next, patch) {
   if (!changed) return;
   const current = previous.health;
   const revision = Number.isSafeInteger(current && current.revision) ? current.revision + 1 : 1;
-  next.health = { version: 1, revision, observations: [] };
+  next.health = { version: 1, revision, observations: [],
+    ...(current?.rateLimits?.length ? { rateLimits: current.rateLimits } : {}) };
 }
 
-/** 记录一次显式实测或真实任务观察；临时错误不会覆盖近期成功。 */
+/** 记录显式实测或真实任务观察；限流资格另存，保留原成功事实。 */
 export function recordProviderHealth(id, modelId, capability, result) {
   const c = load();
   const provider = c.providers.find((item) => item.id === id);
@@ -405,10 +410,24 @@ export function recordProviderHealth(id, modelId, capability, result) {
   return true;
 }
 
+/** DSH 调用边界记录冷却或明确耗尽；覆盖同账号该模型的所有能力。 */
+export function recordRateLimit({ providerId, modelId, capability, httpStatus = 429, category = 'rate_limit', at, until, retryAfterMs, reason }) {
+  const known = { image: 'image-gen', video: 'video-gen' }[capability] || capability;
+  return recordProviderHealth(providerId, modelId, known, {
+    ok: false, source: 'task', category, httpStatus, at, until, retryAfterMs, reason,
+    note: category === 'quota' ? '额度或预算耗尽后已停用，手动实测成功后恢复' : '429 限流冷却，暂时跳过'
+  });
+}
+
 /** 返回单个 Provider × Model × Capability 的安全状态。 */
 export function modelHealth(id, modelId, capability, { now = Date.now() } = {}) {
   const provider = load().providers.find((item) => item.id === id);
   if (!provider || provider.enabled === false || missingCredentials(provider)) return { status: 'unconfigured' };
+  const blocked = modelRateLimit(provider, modelId, { now });
+  if (blocked) return { status: 'failed', rateLimited: true, observedAt: blocked.at,
+    source: blocked.source, category: blocked.category, httpStatus: blocked.httpStatus,
+    ...(blocked.until ? { retryAt: blocked.until } : { reason: blocked.reason }),
+    note: blocked.until ? '429 限流冷却，暂时跳过' : '额度或预算耗尽后已停用，手动实测成功后恢复' };
   const observation = healthObservation(provider, modelId, capability);
   const status = healthObservationState(observation, { now });
   const evidence = status === 'verified'
@@ -430,7 +449,7 @@ export function modelHealth(id, modelId, capability, { now = Date.now() } = {})
 export function providerHealthSnapshot({ now = Date.now() } = {}) {
   const capabilities = {};
   for (const capability of Object.values(cap.CAPABILITIES)) {
-    const candidates = pickAllFor(capability).map((provider) => {
+    const candidates = pickAllFor(capability, { includeRateLimited: true }).map((provider) => {
       const modelId = String(provider[FIELD_OF[capability]] || '');
       const health = modelHealth(provider.id, modelId, capability, { now });
       return { providerId: provider.id, modelId, ...health };
@@ -443,14 +462,21 @@ export function providerHealthSnapshot({ now = Date.now() } = {}) {
       status,
       candidateCount: candidates.length,
       ...(newest ? { observedAt: newest.observedAt } : {}),
+      ...(status === 'failed' && candidates.every(item => item.retryAt) ? {
+        rateLimited: true, retryAt: candidates.map(item => item.retryAt).sort()[0]
+      } : {}),
       candidates
     };
   }
+  const overall = aggregateHealthStates(Object.values(capabilities).map((item) => item.status));
+  const configured = Object.values(capabilities).filter(item => item.status !== 'unconfigured');
   return {
     schemaVersion: 1,
     freshForMs: PROVIDER_HEALTH_FRESH_MS,
     generatedAt: new Date(Number(now)).toISOString(),
-    overall: aggregateHealthStates(Object.values(capabilities).map((item) => item.status)),
+    overall,
+    ...(overall === 'failed' && configured.every(item => item.retryAt)
+      ? { retryAt: configured.map(item => item.retryAt).sort()[0] } : {}),
     capabilities
   };
 }
@@ -460,6 +486,10 @@ export function upsert(provider) {
   const { id, ...input } = provider;
   // PATCH 语义：缺失字段和 undefined 都不覆盖旧值；null/空串仍是显式更新。
   const rest = Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+  if (rest.visionInput !== undefined) rest.visionInput = normalizeVisionInputLimits(rest.visionInput) || null;
+  if (Array.isArray(rest.models)) rest.models = rest.models.map(model => typeof model === 'string' ? model : ({ ...model,
+    ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol) } : {}),
+    ...(model?.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(model.visionInput) || null } : {}) }));
   if (id) {
     const i = c.providers.findIndex((p) => p.id === id);
     if (i >= 0) {
@@ -468,6 +498,7 @@ export function upsert(provider) {
       if (Object.prototype.hasOwnProperty.call(rest, 'mediaProtocol')) next.protocolInferred = false;
       normalizeStoredProvider(next);
       resetHealthOnCriticalChange(previous, next, rest);
+      resetChangedImageProtocolHealth(previous, next);
       if (Object.prototype.hasOwnProperty.call(rest, 'models')) pruneHealthToEffectiveModels(next);
       c.providers[i] = next;
       persist();
@@ -502,23 +533,29 @@ export function setProviderModels(id, modelEntries) {
   const c = load();
   const p = c.providers.find((x) => x.id === id);
   if (!p) return null;
+  const previous = { ...p };
   if (Array.isArray(modelEntries)) {
     // 保留同名模型的实测结果；手工能力标注优先于后续自动发现。
     const prev = new Map();
     for (const m of p.models || []) if (m && m.id) prev.set(m.id, m);
     p.models = modelEntries.map((m) => {
-      const entry = typeof m === 'string' ? { id: m } : { id: m.id, capabilities: m.capabilities };
+      const entry = typeof m === 'string' ? { id: m } : { id: m.id, capabilities: m.capabilities,
+        ...(m.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(m.imageProtocol) } : {}),
+        ...(m.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(m.visionInput) || null } : {}) };
       const old = prev.get(entry.id);
       if (old) {
         if (old.verified) entry.verified = old.verified;
         if (old.source) entry.source = old.source;
         if (old.source === 'manual' && Array.isArray(old.capabilities)) entry.capabilities = old.capabilities;
+        if (m?.imageProtocol === undefined && old.imageProtocol !== undefined) entry.imageProtocol = old.imageProtocol;
+        if (m?.visionInput === undefined && old.visionInput !== undefined) entry.visionInput = old.visionInput;
       }
       if (m && m.verified) entry.verified = m.verified;
       if (m && m.source) entry.source = m.source;
       return entry;
     });
   }
+  resetChangedImageProtocolHealth(previous, p);
   pruneHealthToEffectiveModels(p);
   persist();
   return p;
@@ -542,6 +579,48 @@ function findModelEntry(p, modelId) {
   return (p.models || []).find((m) => m && m.id === modelId);
 }
 
+function resetChangedImageProtocolHealth(previous, next) {
+  for (const model of models.providerModels(previous)) {
+    if (selectImageProtocol(previous, model.id).mediaProtocol !== selectImageProtocol(next, model.id).mediaProtocol) {
+      clearModelCapabilityHealth(next, model.id, cap.CAPABILITIES.IMAGE);
+    }
+  }
+}
+
+/** 手动选择单模型图片协议；auto 恢复账号默认，不解除模型停用。 */
+export function setModelImageProtocol(id, modelId, value) {
+  const protocol = normalizeImageProtocol(value);
+  const p = load().providers.find(provider => provider.id === id);
+  if (!p) return false;
+  const entries = Array.isArray(p.models) ? p.models : models.providerModels(p).map(({ id, capabilities }) => ({ id, capabilities }));
+  const index = entries.findIndex(model => (typeof model === 'string' ? model : model?.id)?.trim() === modelId);
+  if (index < 0) return false;
+  p.models = entries;
+  const entry = typeof p.models[index] === 'string' ? { id: p.models[index] } : p.models[index];
+  p.models[index] = entry;
+  const previous = selectImageProtocol(p, modelId).mediaProtocol;
+  if (protocol === 'auto') delete entry.imageProtocol;
+  else entry.imageProtocol = protocol;
+  if (previous !== selectImageProtocol(p, modelId).mediaProtocol) clearModelCapabilityHealth(p, modelId, cap.CAPABILITIES.IMAGE);
+  persist();
+  return true;
+}
+
+/** 看图预算变更不会伪造实测成功、解除额度停用或改写原图。 */
+export function setModelVisionInput(id, modelId, value) {
+  const limits = normalizeVisionInputLimits(value);
+  const p = load().providers.find(provider => provider.id === id);
+  if (!p) return false;
+  const entries = (Array.isArray(p.models) ? p.models : models.providerModels(p)).map(model => typeof model === 'string' ? { id: model } : { ...model });
+  const entry = entries.find(model => model.id === modelId);
+  if (!entry) return false;
+  if (limits) entry.visionInput = limits;
+  else delete entry.visionInput;
+  p.models = entries;
+  persist();
+  return true;
+}
+
 /** 手动添加一个模型到池（source=manual，能力由调用方给） */
 export function addProviderModel(id, modelId, capabilities) {
   const c = load();

package/lib/core-artifact-store.js

@@ -174,11 +174,11 @@ function publicArtifact(manifest) {
   });
 }
 
-function verifyObject(dataRoot, manifest) {
+function verifyObject(dataRoot, manifest, verifyContent = true) {
   const object = path.join(dirs(dataRoot).objects, manifest.object);
   const stat = regularFile(object);
   if (stat.size !== manifest.size) fail('IRIS_ARTIFACT_DIGEST_MISMATCH', 'Artifact 大小与 Manifest 不一致');
-  if (hashFile(object) !== manifest.digest.value) {
+  if (verifyContent && hashFile(object) !== manifest.digest.value) {
     fail('IRIS_ARTIFACT_DIGEST_MISMATCH', 'Artifact 内容哈希与 Manifest 不一致');
   }
   return object;
@@ -209,7 +209,7 @@ function legacyManifest(dataRoot, record, id) {
   };
 }
 
-function readArtifact(dataRoot, id, { allowLegacy = true } = {}) {
+function readArtifact(dataRoot, id, { allowLegacy = true, verifyContent = true } = {}) {
   checkStore(dataRoot);
   const stable = stableId(id);
   let record;
@@ -226,7 +226,7 @@ function readArtifact(dataRoot, id, { allowLegacy = true } = {}) {
     );
   } else if (allowLegacy) manifest = legacyManifest(dataRoot, record, stable);
   else fail('IRIS_ARTIFACT_INVALID', 'Artifact 提交记录无效');
-  const object = verifyObject(dataRoot, manifest);
+  const object = verifyObject(dataRoot, manifest, verifyContent);
   return { manifest, object, legacy: record.schemaVersion === 0 };
 }
 
@@ -284,6 +284,14 @@ function refreshIndex(dataRoot) {
   return writeIndex(dataRoot, manifests);
 }
 
+/** 只更新已提交条目的派生索引，不升级旧记录或接回孤儿。 */
+export function refreshCoreArtifactInventory(dataRoot) {
+  checkStore(dataRoot, { manifests: true });
+  const manifests = committedIds(dataRoot).map(id => readArtifact(dataRoot, id).manifest);
+  const index = writeIndex(dataRoot, manifests);
+  return { revision: index.revision, total: manifests.length };
+}
+
 function validateRelationTargets(dataRoot, relations) {
   for (const edge of relations) readArtifact(dataRoot, edge.artifactId);
 }
@@ -402,14 +410,11 @@ export function exportCoreArtifact(dataRoot, id, outputPath) {
   return Object.freeze({ artifact: publicArtifact(hit.manifest), exported: true, bytes: hit.manifest.size });
 }
 
-export function listCoreArtifacts(dataRoot, { offset = 0, limit = 50 } = {}) {
+function readArtifactIndex(dataRoot) {
   try { fs.lstatSync(dirs(dataRoot).storeRoot); }
   catch (error) {
     if (error?.code !== 'ENOENT') fail('IRIS_ARTIFACT_STORE_INVALID', 'Artifact Store 无法读取');
-    return Object.freeze({
-      schemaVersion: 0, revision: 0, total: 0, offset: 0, limit: Math.max(1, Math.min(200, Math.trunc(Number(limit) || 50))),
-      artifacts: Object.freeze([])
-    });
+    return { schemaVersion: 0, revision: 0, artifacts: [], absent: true };
   }
   checkStore(dataRoot, { manifests: true });
   const index = jsonFile(dirs(dataRoot).index, 'IRIS_ARTIFACT_INDEX_INVALID');
@@ -420,10 +425,32 @@ export function listCoreArtifacts(dataRoot, { offset = 0, limit = 50 } = {}) {
       || !HASH.test(String(index.inventoryDigest || '')) || index.inventoryDigest !== inventoryDigest) {
     fail('IRIS_ARTIFACT_INDEX_INVALID', 'Artifact Index 结构或自校验无效');
   }
-  const start = Math.max(0, Math.trunc(Number(offset) || 0));
+  return index;
+}
+
+/** 工作台目录只读已提交元数据和文件大小；媒体打开/识别仍须核验完整内容哈希。 */
+export function listCoreArtifactMetadata(dataRoot) {
+  const index = readArtifactIndex(dataRoot), artifacts = [];
+  let dropped = 0;
+  for (const entry of index.artifacts) {
+    try {
+      const { manifest } = readArtifact(dataRoot, entry.id, { allowLegacy: false, verifyContent: false });
+      if (entry.createdAt !== manifest.createdAt || entry.mediaType !== manifest.mediaType
+          || entry.size !== manifest.size || entry.digest !== manifest.digest.value) throw new Error('index mismatch');
+      artifacts.push(publicArtifact(manifest));
+    } catch (_) { dropped++; }
+  }
+  return { revision: index.revision, artifacts, dropped };
+}
+
+export function listCoreArtifacts(dataRoot, { offset = 0, limit = 50, kind, media_type, task_id } = {}) {
+  const index = readArtifactIndex(dataRoot);
+  const start = index.absent ? 0 : Math.max(0, Math.trunc(Number(offset) || 0));
   const size = Math.max(1, Math.min(200, Math.trunc(Number(limit) || 50)));
   const artifacts = [];
-  for (const entry of index.artifacts.slice(start, start + size)) {
+  const filtering = kind !== undefined || media_type !== undefined || task_id !== undefined;
+  let matchedTotal = 0;
+  for (const entry of (filtering ? index.artifacts : index.artifacts.slice(start, start + size))) {
     if (!entry || !ID.test(String(entry.id || ''))) fail('IRIS_ARTIFACT_INDEX_INVALID', 'Artifact Index 条目无效');
     try {
       const artifact = inspectCoreArtifact(dataRoot, entry.id);
@@ -431,7 +458,12 @@ export function listCoreArtifacts(dataRoot, { offset = 0, limit = 50 } = {}) {
           || entry.size !== artifact.size || entry.digest !== artifact.digest.value) {
         fail('IRIS_ARTIFACT_INDEX_INVALID', 'Artifact Index 条目与 Manifest 不一致');
       }
-      artifacts.push(artifact);
+      if (filtering) {
+        if ((kind !== undefined && artifact.kind !== kind) || (media_type !== undefined && artifact.mediaType !== media_type)
+            || (task_id !== undefined && artifact.metadata.taskId !== task_id)) continue;
+        if (matchedTotal >= start && matchedTotal < start + size) artifacts.push(artifact);
+        matchedTotal++;
+      } else artifacts.push(artifact);
     } catch (error) {
       if (error?.code === 'IRIS_ARTIFACT_INDEX_INVALID') throw error;
       fail('IRIS_ARTIFACT_INDEX_INVALID', 'Artifact Index 与存储事实不一致；请显式重建');
@@ -440,7 +472,7 @@ export function listCoreArtifacts(dataRoot, { offset = 0, limit = 50 } = {}) {
   return Object.freeze({
     schemaVersion: 0,
     revision: index.revision,
-    total: index.artifacts.length,
+    total: filtering ? matchedTotal : index.artifacts.length,
     offset: start,
     limit: size,
     artifacts: Object.freeze(artifacts)