@mokuyoaxis/dsh-iris 0.1.3 → 0.1.4

package/lib/config.js

@@ -11,6 +11,14 @@ import * as cap from './capability.js';
 import * as models from './models.js';
 import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
 import { inferMediaProtocol } from './provider-protocol.js';
+import { redactProviderMessage } from './provider-contract.js';
+import {
+  PROVIDER_HEALTH_FRESH_MS,
+  aggregateHealthStates,
+  healthObservationState,
+  isDefinitiveHealthFailure,
+  newestHealthEvidence
+} from './provider-health.js';
 
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -293,6 +301,163 @@ export function capabilitiesOf(p) {
   return [...caps];
 }
 
+const HEALTH_SENSITIVE_FIELDS = new Set([
+  'type', 'baseUrl', 'apiKey', 'mediaProtocol',
+  'imageModel', 'videoModel', 'ttsModel', 'transcribeModel', 'visionModel'
+]);
+
+function healthContainer(provider) {
+  const current = provider.health;
+  if (current && current.version === 1 && Number.isSafeInteger(current.revision)
+      && Array.isArray(current.observations)) return current;
+  const revision = Number.isSafeInteger(current && current.revision) ? current.revision : 0;
+  provider.health = { version: 1, revision, observations: [] };
+  return provider.health;
+}
+
+function healthObservation(provider, modelId, capability) {
+  const health = provider && provider.health;
+  if (!health || health.version !== 1 || !Array.isArray(health.observations)) return null;
+  return health.observations.find((item) => item && item.modelId === modelId
+    && item.capability === capability) || null;
+}
+
+function safeHealthNote(provider, value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return '';
+  let note = redactProviderMessage(raw, 200);
+  const key = String(provider && provider.apiKey || '');
+  if (key) note = note.split(key).join('[REDACTED]');
+  return note;
+}
+
+function observationEvidence(provider, result, fallbackSource) {
+  const atMs = Date.parse(String(result && result.at || ''));
+  const status = Number(result && (result.httpStatus ?? result.status));
+  const note = safeHealthNote(provider, result && (result.note || result.safeMessage || result.message));
+  return {
+    at: new Date(Number.isFinite(atMs) ? atMs : Date.now()).toISOString(),
+    source: ['probe', 'task'].includes(result && result.source) ? result.source : fallbackSource,
+    category: String(result && result.category || (result && result.ok ? 'success' : 'unknown')).slice(0, 40),
+    ...(Number.isInteger(status) && status >= 100 && status <= 599 ? { httpStatus: status } : {}),
+    ...(note ? { note } : {})
+  };
+}
+
+function applyProviderHealth(provider, modelId, capability, result, fallbackSource = 'task') {
+  const model = String(modelId || '').trim();
+  if (!provider || !model || !cap.isKnownCapability(capability)) return false;
+  const health = healthContainer(provider);
+  let observation = health.observations.find((item) => item && item.modelId === model
+    && item.capability === capability);
+  if (!observation) {
+    observation = { modelId: model, capability };
+    health.observations.push(observation);
+  }
+  const evidence = observationEvidence(provider, result || {}, fallbackSource);
+  if (result && result.ok === true) {
+    observation.lastSuccess = evidence;
+  } else if (isDefinitiveHealthFailure({ ...result, ...evidence })) {
+    observation.lastFailure = evidence;
+  } else {
+    observation.lastTransient = evidence;
+  }
+  return true;
+}
+
+function pruneHealthToEffectiveModels(provider) {
+  if (!provider) return;
+  const allowedByModel = new Map();
+  for (const entry of models.providerModels(provider)) {
+    allowedByModel.set(entry.id, new Set(entry.capabilities));
+  }
+  if (provider.health && Array.isArray(provider.health.observations)) {
+    provider.health.observations = provider.health.observations.filter((item) =>
+      item && allowedByModel.get(item.modelId)?.has(item.capability));
+  }
+  for (const entry of provider.models || []) {
+    if (!entry || typeof entry !== 'object' || !entry.verified || typeof entry.verified !== 'object') continue;
+    const allowed = allowedByModel.get(entry.id) || new Set();
+    entry.verified = Object.fromEntries(Object.entries(entry.verified).filter(([capability]) => allowed.has(capability)));
+    if (!Object.keys(entry.verified).length) delete entry.verified;
+  }
+}
+
+function pruneModelHealth(provider, modelId) {
+  if (!provider || !provider.health || !Array.isArray(provider.health.observations)) return;
+  provider.health.observations = provider.health.observations.filter((item) => item.modelId !== modelId);
+}
+
+function resetHealthOnCriticalChange(previous, next, patch) {
+  const changed = [...HEALTH_SENSITIVE_FIELDS].some((key) =>
+    Object.prototype.hasOwnProperty.call(patch, key) && previous[key] !== next[key]);
+  if (!changed) return;
+  const current = previous.health;
+  const revision = Number.isSafeInteger(current && current.revision) ? current.revision + 1 : 1;
+  next.health = { version: 1, revision, observations: [] };
+}
+
+/** 记录一次显式实测或真实任务观察；临时错误不会覆盖近期成功。 */
+export function recordProviderHealth(id, modelId, capability, result) {
+  const c = load();
+  const provider = c.providers.find((item) => item.id === id);
+  if (!provider || !applyProviderHealth(provider, modelId, capability, result, result && result.source || 'task')) {
+    return false;
+  }
+  persist();
+  return true;
+}
+
+/** 返回单个 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 || !provider.apiKey) return { status: 'unconfigured' };
+  const observation = healthObservation(provider, modelId, capability);
+  const status = healthObservationState(observation, { now });
+  const evidence = status === 'verified'
+    ? observation && observation.lastSuccess
+    : (status === 'failed' ? observation && observation.lastFailure : newestHealthEvidence(observation));
+  return {
+    status,
+    ...(evidence ? {
+      observedAt: evidence.at,
+      source: evidence.source,
+      category: evidence.category,
+      ...(evidence.httpStatus ? { httpStatus: evidence.httpStatus } : {}),
+      ...(evidence.note ? { note: evidence.note } : {})
+    } : {})
+  };
+}
+
+/** 当前有序 failover 路径的健康快照；只含脱敏标量，不触发网络。 */
+export function providerHealthSnapshot({ now = Date.now() } = {}) {
+  const capabilities = {};
+  for (const capability of Object.values(cap.CAPABILITIES)) {
+    const candidates = pickAllFor(capability).map((provider) => {
+      const modelId = String(provider[FIELD_OF[capability]] || '');
+      const health = modelHealth(provider.id, modelId, capability, { now });
+      return { providerId: provider.id, modelId, ...health };
+    });
+    const status = aggregateHealthStates(candidates.map((item) => item.status));
+    const newest = [...candidates]
+      .filter((item) => item.status === status && item.observedAt)
+      .sort((a, b) => String(b.observedAt).localeCompare(String(a.observedAt)))[0];
+    capabilities[capability] = {
+      status,
+      candidateCount: candidates.length,
+      ...(newest ? { observedAt: newest.observedAt } : {}),
+      candidates
+    };
+  }
+  return {
+    schemaVersion: 1,
+    freshForMs: PROVIDER_HEALTH_FRESH_MS,
+    generatedAt: new Date(Number(now)).toISOString(),
+    overall: aggregateHealthStates(Object.values(capabilities).map((item) => item.status)),
+    capabilities
+  };
+}
+
 export function upsert(provider) {
   const c = load();
   const { id, ...input } = provider;
@@ -301,11 +466,15 @@ export function upsert(provider) {
   if (id) {
     const i = c.providers.findIndex((p) => p.id === id);
     if (i >= 0) {
-      if (rest.mediaProtocol === 'auto') rest.mediaProtocol = inferMediaProtocol(rest.baseUrl ?? c.providers[i].baseUrl);
-      c.providers[i] = { ...c.providers[i], ...rest };
-      normalizeStoredProvider(c.providers[i]);
+      const previous = c.providers[i];
+      if (rest.mediaProtocol === 'auto') rest.mediaProtocol = inferMediaProtocol(rest.baseUrl ?? previous.baseUrl);
+      const next = { ...previous, ...rest };
+      normalizeStoredProvider(next);
+      resetHealthOnCriticalChange(previous, next, rest);
+      if (Object.prototype.hasOwnProperty.call(rest, 'models')) pruneHealthToEffectiveModels(next);
+      c.providers[i] = next;
       persist();
-      return c.providers[i];
+      return next;
     }
   }
   const fresh = { id: 'iris_' + Math.random().toString(36).slice(2, 8), ...rest };
@@ -352,6 +521,7 @@ export function setProviderModels(id, modelEntries) {
       return entry;
     });
   }
+  pruneHealthToEffectiveModels(p);
   persist();
   return p;
 }
@@ -376,6 +546,7 @@ export function addProviderModel(id, modelId, capabilities) {
   } else if (Array.isArray(capabilities)) {
     entry.capabilities = capabilities;
   }
+  pruneHealthToEffectiveModels(p);
   persist();
   return entry;
 }
@@ -388,6 +559,7 @@ export function removeProviderModel(id, modelId) {
   const i = p.models.findIndex((m) => m && m.id === modelId);
   if (i < 0) return false;
   p.models.splice(i, 1);
+  pruneModelHealth(p, modelId);
   persist();
   return true;
 }
@@ -399,20 +571,31 @@ export function setModelCapabilities(id, modelId, capabilities) {
   if (!p) return false;
   const entry = findModelEntry(p, modelId);
   if (!entry) return false;
-  entry.capabilities = (Array.isArray(capabilities) ? capabilities : []).filter((x) => cap.isKnownCapability(x));
+  const nextCapabilities = (Array.isArray(capabilities) ? capabilities : []).filter((x) => cap.isKnownCapability(x));
+  entry.capabilities = nextCapabilities;
+  pruneHealthToEffectiveModels(p);
   persist();
   return true;
 }
 
-/** 记录某模型的实测结果（verified[capability] = {ok, at, note}） */
+/** 记录某模型的显式实测结果，并同步到新健康事实。 */
 export function setModelVerified(id, modelId, capability, result) {
   const c = load();
   const p = c.providers.find((x) => x.id === id);
   if (!p) return false;
   const entry = findModelEntry(p, modelId);
-  if (!entry) return false;
-  if (!entry.verified) entry.verified = {};
-  entry.verified[capability] = { ok: !!result.ok, at: new Date().toISOString(), note: String(result.note || '').slice(0, 200) };
+  const at = new Date().toISOString();
+  if (entry) {
+    if (!entry.verified) entry.verified = {};
+    entry.verified[capability] = {
+      ok: !!result.ok,
+      at,
+      note: safeHealthNote(p, result.note || ''),
+      source: 'probe',
+      category: String(result.category || (result.ok ? 'success' : 'unknown')).slice(0, 40)
+    };
+  }
+  applyProviderHealth(p, modelId, capability, { ...result, at, source: 'probe' }, 'probe');
   persist();
   return true;
 }

package/lib/doctor.js

@@ -5,6 +5,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { attentionDisposition, deriveUserState, semanticViolations } from './task-semantics.js';
+import { HOST_CONTRACT_VERSION, hostCapabilitySnapshot } from './host-contract.js';
+import {
+  EXPECTED_IRIS_CLIENT_SEATS, EXPECTED_IRIS_ROUTES, EXPECTED_IRIS_SKILLS, EXPECTED_IRIS_TOOLS,
+  HOST_CLIENT_PROTOCOL_VERSION, IRIS_PLUGIN_ID
+} from './host-runtime.js';
 
 const PACKAGE_FILE = new URL('../package.json', import.meta.url);
 
@@ -45,7 +50,7 @@ function isGroupOrWorldAccessible(target) {
 
 function privateFileModeProblems(dataDir) {
   if (process.platform === 'win32') return [];
-  return ['providers.json', 'tasks.json', 'prompt-optimizer.json']
+  return ['providers.json', 'tasks.json', 'artifacts.json', 'prompt-optimizer.json']
     .filter((name) => isGroupOrWorldAccessible(path.join(dataDir, name)));
 }
 
@@ -151,6 +156,30 @@ function inspectArtifacts(dataDir, tasks, checks) {
     for (const item of task.media || []) if (item && item.file) referenced.add(path.basename(String(item.file)));
     for (const item of task.attachments || []) if (item && item.file) referenced.add(path.basename(String(item.file)));
   }
+
+  const library = readJson(path.join(dataDir, 'artifacts.json'));
+  if (library.exists && (library.error || !plain(library.value) || !Array.isArray(library.value.artifacts))) {
+    checks.push(result('artifact-index', 'warn', 'artifacts.json 结构无效或无法解析', '保留损坏索引作为证据；重新启动 Iris 后会从 outputs/ 重建最小作品索引。'));
+  } else if (library.exists) {
+    let invalid = 0;
+    for (const item of library.value.artifacts) {
+      if (!plain(item) || !String(item.id || '').startsWith('a_') || !String(item.token || '').match(/^[a-f0-9]{32}$/)
+          || !String(item.file || '') || path.basename(String(item.file)) !== String(item.file)) {
+        invalid++;
+        continue;
+      }
+      const safe = String(item.file);
+      referenced.add(safe);
+      try {
+        const stat = fs.lstatSync(path.join(outputs, safe));
+        if (!stat.isFile() || stat.isSymbolicLink()) missing++;
+      } catch (_) { missing++; }
+    }
+    checks.push(invalid
+      ? result('artifact-index', 'warn', `${invalid} 个作品索引条目无效`, '在工作台运行“找回本地作品”重建最小索引。')
+      : result('artifact-index', 'ok', `${library.value.artifacts.length} 个作品索引条目结构有效`));
+  }
+
   let orphan = 0;
   if (fs.existsSync(outputs)) {
     for (const name of fs.readdirSync(outputs)) {
@@ -158,9 +187,9 @@ function inspectArtifacts(dataDir, tasks, checks) {
       try { if (fs.lstatSync(target).isFile() && !referenced.has(name)) orphan++; } catch (_) {}
     }
   }
-  if (missing) checks.push(result('artifacts', 'warn', `${missing} 个任务产物不可访问；另有 ${orphan} 个孤儿文件`, '在工作台检查任务详情并运行孤儿产物扫描。'));
-  else if (orphan) checks.push(result('artifacts', 'warn', `${orphan} 个产物文件没有任务引用`, '先在工作台运行孤儿扫描，确认后再删除。'));
-  else checks.push(result('artifacts', 'ok', `${referenced.size} 个已引用产物可核对，未发现孤儿文件`));
+  if (missing) checks.push(result('artifacts', 'warn', `${missing} 个任务或作品索引引用的文件不可访问；另有 ${orphan} 个孤儿文件`, '在工作台检查任务详情并运行“找回本地作品”。'));
+  else if (orphan) checks.push(result('artifacts', 'warn', `${orphan} 个输出文件既没有任务引用也未进入作品库`, '先运行“找回本地作品”；仍无法入库的文件再作为孤儿处理。'));
+  else checks.push(result('artifacts', 'ok', `${referenced.size} 个任务/作品引用可核对，未发现孤儿文件`));
 
   const uploads = path.join(dataDir, 'uploads');
   let temporary = 0;
@@ -231,6 +260,148 @@ export async function doctor(options = {}) {
   };
 }
 
+
+function summarizeChecks(checks) {
+  const errors = checks.filter((item) => item.status === 'error').length;
+  const warnings = checks.filter((item) => item.status === 'warn').length;
+  return {
+    summary: { ok: checks.length - errors - warnings, warnings, errors },
+    exitCode: errors ? 2 : (warnings ? 1 : 0)
+  };
+}
+
+function dshVersionSupported(value) {
+  /* 已实测的宿主窗口：>=0.1.2-rc.1 <0.1.3-0，以及 0.1.5-rc.1。
+     其他预览版没有宿主 canary 证据，不放行。 */
+  const version = String(value || '').trim().replace(/\s+/g, '');
+  if (/^0\.1\.5-rc\.1(?:\+.*)?$/.test(version)) return true;
+  const match = version.match(/^0\.1\.2(?:-rc\.(\d+))?(?:\+.*)?$/);
+  return Boolean(match && (match[1] === undefined || Number(match[1]) >= 1));
+}
+
+function names(value) {
+  return [...new Set((Array.isArray(value) ? value : []).map((item) => String(item || '').trim()).filter(Boolean))];
+}
+
+function missing(expected, actual) {
+  const found = new Set(names(actual));
+  return expected.filter((item) => !found.has(item));
+}
+
+function capabilityCheck(checks, snapshot, id, port, label, severity = 'warn') {
+  const capability = snapshot.capabilities[port];
+  if (capability && capability.status === 'available') {
+    checks.push(result(id, 'ok', label + ' Host Port 可用'));
+    return true;
+  }
+  const status = severity === 'error' ? 'error' : 'warn';
+  const kind = capability?.status === 'incompatible' ? '接口不兼容' : '能力缺失';
+  checks.push(result(id, status, label + '不可用（' + kind + '）' + (capability?.reason ? '：' + capability.reason : ''),
+    capability?.status === 'incompatible'
+      ? '核对当前 DSH 版本与 Iris 支持范围，必要时回退到已验证版本。'
+      : '启用对应 DSH 服务；不需要该能力时可忽略此降级。'));
+  return false;
+}
+
+/**
+ * 运行中宿主诊断。只消费安全快照和注册账本，不调用任何端口，因此默认零网络、
+ * 零计费，也不会打开 Browser、读取附件/会话或调用模型。
+ */
+export function hostDoctor(host, evidence = {}, options = {}) {
+  const snapshot = hostCapabilitySnapshot(host);
+  const packageVersion = String(options.packageVersion || evidence?.server?.version || readPackageVersion());
+  const checks = [];
+
+  checks.push(snapshot.contractVersion === HOST_CONTRACT_VERSION
+    ? result('host-contract', 'ok', 'Host Adapter v' + snapshot.contractVersion + ' · ' + snapshot.host.id)
+    : result('host-contract', 'error', 'Host Adapter 契约版本不兼容',
+      '使用与当前 Iris 包匹配的 Host Adapter。'));
+
+  if (snapshot.host.id === 'deepseek-harness') {
+    if (snapshot.host.version === 'unknown') {
+      checks.push(result('dsh-version', 'warn', '无法从当前进程识别 DSH 版本',
+        '使用 dsh --version 核对；0.1.4 已验证 >=0.1.2-rc.1 <0.1.3-0 与 0.1.5-rc.1。'));
+    } else if (dshVersionSupported(snapshot.host.version)) {
+      checks.push(result('dsh-version', 'ok', 'DSH ' + snapshot.host.version + ' 位于已验证支持范围'));
+    } else {
+      checks.push(result('dsh-version', 'error', 'DSH ' + snapshot.host.version + ' 超出已验证支持范围',
+        '使用 >=0.1.2-rc.1 <0.1.3-0 或 0.1.5-rc.1，或先运行新的隔离 canary 再扩大支持范围。'));
+    }
+  }
+
+  const server = evidence && typeof evidence.server === 'object' ? evidence.server : {};
+  if (server.loaded === true && server.pluginId === IRIS_PLUGIN_ID) {
+    checks.push(result('plugin', 'ok', IRIS_PLUGIN_ID + ' 服务端已装载 · ' + packageVersion));
+  } else {
+    checks.push(result('plugin', 'error', '无法确认 Iris 服务端插件身份或装载事实',
+      '检查 profile 中是否启用完整 scoped 包名 @mokuyoaxis/dsh-iris，并查看 DSH 启动日志。'));
+  }
+
+  const toolsAvailable = capabilityCheck(checks, snapshot, 'tools-port', 'tools', 'Agent 工具注册', 'error');
+  const missingTools = missing(EXPECTED_IRIS_TOOLS, evidence.tools);
+  checks.push(toolsAvailable && missingTools.length === 0
+    ? result('tools', 'ok', EXPECTED_IRIS_TOOLS.length + ' 个 Iris 工具均已登记')
+    : result('tools', 'error', '缺少 ' + missingTools.length + '/' + EXPECTED_IRIS_TOOLS.length + ' 个 Iris 工具'
+      + (missingTools.length ? '：' + missingTools.join(', ') : ''),
+    '检查单工具注册隔离日志；不要因一项失败重启或重复提交媒体任务。'));
+
+  const routesAvailable = capabilityCheck(checks, snapshot, 'routes-port', 'routes', 'Web 路由注册', 'error');
+  const missingRoutes = missing(EXPECTED_IRIS_ROUTES, evidence.routes);
+  checks.push(routesAvailable && missingRoutes.length === 0
+    ? result('routes', 'ok', EXPECTED_IRIS_ROUTES.length + ' 组 Iris 路由均已登记')
+    : result('routes', 'error', '缺少 ' + missingRoutes.length + '/' + EXPECTED_IRIS_ROUTES.length + ' 组 Iris 路由'
+      + (missingRoutes.length ? '：' + missingRoutes.join(', ') : ''),
+    '检查 webServer/httpServer 与路由挂载日志。'));
+
+  const skillsAvailable = capabilityCheck(checks, snapshot, 'skills-port', 'skills', 'Skill 注册');
+  const missingSkills = missing(EXPECTED_IRIS_SKILLS, evidence.skills);
+  checks.push(skillsAvailable && missingSkills.length === 0
+    ? result('skills', 'ok', EXPECTED_IRIS_SKILLS.length + ' 项随包 Skill 均已登记')
+    : result('skills', 'warn', '缺少 ' + missingSkills.length + '/' + EXPECTED_IRIS_SKILLS.length + ' 项随包 Skill'
+      + (missingSkills.length ? '：' + missingSkills.join(', ') : ''),
+    '工具仍可直接调用；检查 DSH Skill registry 和插件启动日志。'));
+
+  capabilityCheck(checks, snapshot, 'browser', 'browser', 'HTML Browser');
+  capabilityCheck(checks, snapshot, 'attachments', 'attachments', '附件读写');
+  capabilityCheck(checks, snapshot, 'sessions', 'sessions', '会话查询');
+  capabilityCheck(checks, snapshot, 'text-model', 'textModel', '宿主文本模型');
+  capabilityCheck(checks, snapshot, 'vision-model', 'visionModel', '宿主视觉模型');
+
+  const client = evidence && typeof evidence.client === 'object' ? evidence.client : null;
+  if (!client || client.loaded !== true) {
+    checks.push(result('client', 'warn', '尚未收到 Iris 浏览器客户端握手',
+      '在同一 DSH 实例打开或刷新 Web 页面，再重新访问 /iris/api/doctor。'));
+  } else if (client.pluginId !== IRIS_PLUGIN_ID
+      || client.protocolVersion !== HOST_CLIENT_PROTOCOL_VERSION
+      || client.version !== packageVersion) {
+    checks.push(result('client', 'error',
+      'Iris 服务端/客户端版本不一致：server ' + packageVersion + ' · client ' + String(client.version || 'unknown')
+      + ' · protocol ' + String(client.protocolVersion),
+    '重新打开 DSH 输出的认证 URL并强制刷新；若仍不一致，清理该 profile 的旧插件链接后重装。'));
+  } else {
+    const missingSeats = missing(EXPECTED_IRIS_CLIENT_SEATS, client.seats);
+    checks.push(missingSeats.length
+      ? result('client', 'error', '浏览器客户端缺少 ' + missingSeats.length + '/' + EXPECTED_IRIS_CLIENT_SEATS.length
+        + ' 个 UI Slot：' + missingSeats.join(', '),
+      '检查客户端模块表和 DSH Slot API；服务端任务不受影响。')
+      : result('client', 'ok', '客户端 ' + client.version + ' 已装载，4 个 UI Slot 均已登记'));
+  }
+
+  checks.push(result('scope', 'ok', 'Host Doctor 只读取能力快照和 Iris 注册账本；未调用端口、Browser、模型或供应商'));
+
+  const totals = summarizeChecks(checks);
+  return {
+    schemaVersion: 1,
+    package: { name: IRIS_PLUGIN_ID, version: packageVersion },
+    mode: 'host',
+    environment: { node: process.versions.node, platform: process.platform, arch: process.arch },
+    host: snapshot.host,
+    capabilities: snapshot.capabilities,
+    checks,
+    ...totals
+  };
+}
+
 export function formatDoctorReport(report) {
   const mark = { ok: '✓', warn: '!', error: '✗' };
   const lines = [`Iris Doctor ${report.package.version} · ${report.mode}`];

package/lib/dsh-host-adapter.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/** DSH/Cordis runtime objects are normalized here and nowhere in Iris commands. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { defineHostAdapter } from './host-contract.js';
+import { BrowserHtmlRenderer } from './render.js';
+
+export function detectDshVersion({ entry = process.argv[1] } = {}) {
+  if (!entry) return 'unknown';
+  let resolved = path.resolve(String(entry));
+  try { resolved = fs.realpathSync(resolved); } catch (_) { /* 入口可能尚未物化 */ }
+  let current = path.dirname(resolved);
+  for (let depth = 0; depth < 6; depth++) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(current, 'package.json'), 'utf8'));
+      if (manifest.name === '@deepseek-ai/dsh') return String(manifest.version || 'unknown');
+    } catch (_) { /* 当前层不是 DSH 包根目录 */ }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return 'unknown';
+}
+
+function property(ctx, name) {
+  try { return ctx && ctx[name]; } catch (_) { return undefined; }
+}
+
+function service(ctx, name) {
+  if (ctx && typeof ctx.get === 'function') {
+    try {
+      const value = ctx.get(name);
+      if (value) return value;
+    } catch (_) { /* optional DSH service was not injected */ }
+  }
+  return property(ctx, name);
+}
+
+function unavailableFor(value, reason) {
+  return { kind: value ? 'incompatible' : 'unavailable', reason };
+}
+
+function collectImageAttachments(nodes) {
+  const out = [];
+  const ids = new Set();
+  const seen = new Set();
+  const stack = Array.isArray(nodes) ? [...nodes] : [nodes];
+  let scanned = 0;
+  while (stack.length && scanned < 8000) {
+    const node = stack.pop();
+    scanned++;
+    if (!node || typeof node !== 'object' || seen.has(node)) continue;
+    seen.add(node);
+    const ref = node.attachment && typeof node.attachment === 'object'
+      ? node.attachment
+      : (node.attachmentId && node.mediaType ? node : null);
+    if (ref && typeof ref.attachmentId === 'string'
+        && typeof ref.mediaType === 'string' && ref.mediaType.startsWith('image/')
+        && !ids.has(ref.attachmentId)) {
+      ids.add(ref.attachmentId);
+      out.push(Object.freeze({
+        attachmentId: ref.attachmentId,
+        mediaType: ref.mediaType,
+        name: typeof ref.name === 'string' ? ref.name : ''
+      }));
+    }
+    for (const value of Object.values(node)) if (value && typeof value === 'object') stack.push(value);
+  }
+  return out;
+}
+
+function registerWithEffect(ctx, registry, definition) {
+  if (typeof ctx.effect === 'function') return ctx.effect(() => registry.register(definition));
+  return registry.register(definition);
+}
+
+function dshVisionPort(llm) {
+  return Object.freeze({
+    id: 'dsh-global',
+    model: '全局视觉模型',
+    async analyze({ question, ref, signal }) {
+      const chunks = [];
+      for await (const chunk of llm.stream({
+        sessionId: undefined,
+        provider: undefined,
+        model: undefined,
+        signal,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'text', text: question },
+            { type: 'image', attachment: ref }
+          ]
+        }]
+      })) {
+        const text = typeof chunk?.delta === 'string'
+          ? chunk.delta
+          : (chunk?.type === 'text-delta' ? String(chunk.text || '') : '');
+        if (text) chunks.push(text);
+        if (chunks.reduce((sum, item) => sum + item.length, 0) > 6000) break;
+      }
+      return chunks.join('').trim();
+    }
+  });
+}
+
+/** Build a fresh capability snapshot so optional DSH services can arrive after plugin apply(). */
+export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {}) {
+  if (!ctx || typeof ctx !== 'object') throw new TypeError('DSH Host Adapter 需要宿主 ctx');
+  const ports = {};
+  const unavailable = {};
+
+  const attachments = service(ctx, 'attachments');
+  if (attachments && typeof attachments.saveImage === 'function' && typeof attachments.readImage === 'function') {
+    ports.attachments = Object.freeze({
+      saveImage: (input) => attachments.saveImage(input),
+      readImage: (ref, signal) => attachments.readImage(ref, signal)
+    });
+  } else unavailable.attachments = unavailableFor(attachments, 'DSH attachments 需要 saveImage/readImage');
+
+  const browser = service(ctx, 'browser');
+  if (browser && ['open', 'openUrl', 'screenshot', 'close'].every((name) => typeof browser[name] === 'function')) {
+    const renderer = new BrowserHtmlRenderer({ browser });
+    ports.browser = Object.freeze({
+      async renderHtml(input) {
+        const { png } = await renderer.render(input);
+        return { bytes: new Uint8Array(png), mediaType: 'image/png' };
+      }
+    });
+  } else unavailable.browser = unavailableFor(browser, 'DSH browser 需要 open/openUrl/screenshot/close');
+
+  const slots = service(ctx, 'slots');
+  if (slots && typeof slots.inject === 'function' && typeof slots.register === 'function') {
+    ports.clientSlots = Object.freeze({
+      inject: (seat, callback) => slots.inject(seat, callback),
+      register: (definition, component) => slots.register(definition, component)
+    });
+  } else unavailable.clientSlots = unavailableFor(slots, 'DSH client slots 需要 inject/register');
+
+  const routes = service(ctx, 'webServer') || service(ctx, 'httpServer');
+  if (routes && typeof routes.register === 'function') {
+    ports.routes = Object.freeze({ register: (definition) => routes.register(definition) });
+  } else unavailable.routes = unavailableFor(routes, 'DSH webServer/httpServer 需要 register');
+
+  const sessions = service(ctx, 'sessionQuery');
+  if (sessions && typeof sessions.readSession === 'function') {
+    ports.sessions = Object.freeze({
+      readSession: (id) => sessions.readSession(id),
+      async listImageAttachments(id) {
+        const record = await sessions.readSession(id);
+        return collectImageAttachments(record && record.events);
+      },
+      async findImageAttachment(id, attachmentId) {
+        return (await this.listImageAttachments(id)).find((item) => item.attachmentId === attachmentId) || null;
+      }
+    });
+  } else unavailable.sessions = unavailableFor(sessions, 'DSH sessionQuery 需要 readSession');
+
+  const skills = service(ctx, 'skills');
+  if (skills && typeof skills.register === 'function') {
+    ports.skills = Object.freeze({ register: (definition) => registerWithEffect(ctx, skills, definition) });
+  } else unavailable.skills = unavailableFor(skills, 'DSH Skill registry 需要 register');
+
+  const llm = service(ctx, 'llm');
+  const defaults = service(ctx, 'agentDefaultModel');
+  if (llm && typeof llm.stream === 'function') {
+    ports.textModel = Object.freeze({
+      stream: (request) => llm.stream(request),
+      resolveModelInfo: typeof llm.resolveModelInfo === 'function'
+        ? (provider, model, signal) => llm.resolveModelInfo(provider, model, signal)
+        : undefined,
+      currentSelection: defaults && typeof defaults.currentSelection === 'function'
+        ? () => defaults.currentSelection()
+        : () => null
+    });
+    ports.visionModel = dshVisionPort(llm);
+  } else {
+    unavailable.textModel = unavailableFor(llm, 'DSH llm 需要 stream');
+    unavailable.visionModel = unavailableFor(llm, 'DSH llm 需要 stream');
+  }
+
+  const tools = service(ctx, 'tools');
+  if (tools && typeof tools.register === 'function') {
+    ports.tools = Object.freeze({ register: (definition) => registerWithEffect(ctx, tools, definition) });
+  } else unavailable.tools = unavailableFor(tools, 'DSH tools 需要 register');
+
+  return defineHostAdapter({ id: 'deepseek-harness', version, ports, unavailable });
+}