@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/core-user-projection.js

@@ -0,0 +1,192 @@
+'use strict';
+/**
+ * Core Task 的用户侧只读投影。
+ *
+ * Core 事实轴（lib/task-semantics.js）保持不变；这里只做一层只读映射，
+ * 把任务收敛成五类用户状态：running / observation_paused / attention /
+ * delivery_failed / succeeded。投影不读文件、不写事实、不接触 Provider，
+ * 也不包含 providerId、providerBinding、错误原文或任何路径。
+ */
+
+export const CORE_USER_STATES = Object.freeze([
+  'running',
+  'observation_paused',
+  'attention',
+  'delivery_failed',
+  'succeeded'
+]);
+
+/**
+ * 五类状态的判定与文案。终态事实（成功/失败/取消）优先于观察姿态：
+ * 「已经明确失败」绝不能继续显示成「观察暂停」；观察暂停必须明确说明
+ * 远端可能仍在运行，避免误导用户以为任务已经终止。
+ */
+export function projectCoreTaskUserView(task) {
+  if (!task || typeof task !== 'object' || Array.isArray(task)
+      || !['outcome', 'deliveryState', 'watchState', 'acceptance', 'phase'].some((axis) => axis in task)) {
+    return Object.freeze({ state: 'attention', label: '记录无法识别，需要检查' });
+  }
+  const outcome = String(task.outcome || 'none');
+  const delivery = String(task.deliveryState || 'none');
+  const watch = String(task.watchState || 'idle');
+  const acceptance = String(task.acceptance || 'none');
+  if (outcome === 'succeeded' && delivery === 'ready') {
+    return Object.freeze({ state: 'succeeded', label: '已完成，作品可用' });
+  }
+  if (outcome === 'succeeded' && delivery === 'failed') {
+    return Object.freeze({ state: 'delivery_failed', label: '已生成，作品取回失败' });
+  }
+  if (outcome === 'succeeded') {
+    return Object.freeze({ state: 'running', label: '已生成，正在保存作品' });
+  }
+  if (outcome === 'failed') {
+    return Object.freeze({ state: 'attention', label: '已失败' });
+  }
+  if (outcome === 'canceled') {
+    return Object.freeze({ state: 'attention', label: '已取消' });
+  }
+  if (outcome === 'unknown') {
+    return Object.freeze({ state: 'attention', label: '任务结果未知，需要检查' });
+  }
+  if (acceptance === 'unknown') {
+    return Object.freeze({ state: 'attention', label: '提交结果未知，请检查后处理' });
+  }
+  if (delivery === 'failed') {
+    return Object.freeze({ state: 'attention', label: '结果状态异常，需要检查' });
+  }
+  if (watch === 'suspended' || watch === 'exhausted') {
+    return Object.freeze({ state: 'observation_paused', label: '观察已暂停，远端可能仍在运行' });
+  }
+  return Object.freeze({ state: 'running', label: '运行中' });
+}
+
+/** 只有状态时（如客户端角标归类）使用；完整视图见 projectCoreTaskUserView。 */
+export function projectCoreTaskUserState(task) {
+  return projectCoreTaskUserView(task).state;
+}
+
+/**
+ * 与 task.observe / task.reobserve 同一组受理事实门：已受理、有远端 ID、
+ * 结果未定论且非终态。只读持久化事实轴，不解析 Provider、不接触网络；
+ * 服务端的真正门禁仍在 Command Service（含 binding 与能力校验）。
+ */
+export function coreTaskObservable(task) {
+  if (!task || typeof task !== 'object' || Array.isArray(task)) return false;
+  return String(task.acceptance || '') === 'accepted'
+    && Boolean(String(task.remoteTaskId || '').trim())
+    && ['none', 'unknown'].includes(String(task.outcome || 'none'))
+    && String(task.phase || '') !== 'terminal';
+}
+
+/**
+ * 与 task.redeliver 同一组交付事实门：远端已成功、产物取回失败、远端 ID 仍在。
+ * 只读持久化事实轴，不解析 Provider、不接触网络；binding 与能力校验仍在
+ * Command Service。五类状态里只有 delivery_failed 会标记 redeliverable。
+ */
+export function coreTaskRedeliverable(task) {
+  if (!task || typeof task !== 'object' || Array.isArray(task)) return false;
+  return String(task.outcome || '') === 'succeeded'
+    && String(task.deliveryState || '') === 'failed'
+    && Boolean(String(task.remoteTaskId || '').trim());
+}
+
+/**
+ * 与 task.cancel 同一组受理事实门：可观察门的超集条件（外加从未请求过取消）。
+ * 只读持久化事实轴，不解析 Provider、不接触网络；Provider 是否支持远端取消
+ * 只有 Command 层用真实 adapter 才能回答，这里不预演。
+ */
+export function coreTaskCancelable(task) {
+  return coreTaskObservable(task) && String(task.cancelState || 'none') === 'none';
+}
+
+/**
+ * 与 task.retry 同一组门：终态且未成功交付（succeeded+ready 的任务不需要重试；
+ * delivery_failed 有 redeliver 但重试也合法）。重试产生新的真实计费，
+ * 必须显式确认——门只决定入口是否出现，确认在动作侧强制。
+ */
+export function coreTaskRetryable(task) {
+  if (!task || typeof task !== 'object' || Array.isArray(task)) return false;
+  return String(task.phase || '') === 'terminal'
+    && !(String(task.outcome || '') === 'succeeded' && String(task.deliveryState || '') === 'ready');
+}
+
+function modelLabelOf(record) {
+  const ref = String(record && record.modelRef || '');
+  const separator = ref.indexOf('::');
+  if (separator >= 0 && ref.slice(separator + 2)) return ref.slice(separator + 2);
+  if (ref) return ref;
+  const attempts = Array.isArray(record && record.attempts) ? record.attempts : [];
+  const last = attempts[attempts.length - 1];
+  const attemptModel = last && typeof last.model === 'string' ? last.model : '';
+  const attemptSeparator = attemptModel.indexOf('::');
+  if (attemptSeparator >= 0 && attemptModel.slice(attemptSeparator + 2)) {
+    return attemptModel.slice(attemptSeparator + 2);
+  }
+  return attemptModel || '未记录';
+}
+
+/**
+ * 生成用户任务区消费的安全行 DTO。
+ * artifacts 是快照里已读出的 Artifact 摘要数组，用于把「作品可用」与实际的
+ * Artifact 存在性对齐；DTO 绝不携带 supplier 身份、binding 或错误原文。
+ */
+export function projectCoreTaskUserRow(record, artifacts = []) {
+  const view = projectCoreTaskUserView(record);
+  const artifactList = Array.isArray(artifacts) ? artifacts : [];
+  const knownIds = new Set(artifactList.map((item) => item && item.id));
+  const rawIds = Array.isArray(record && record.artifactIds) ? record.artifactIds : [];
+  const artifactIds = rawIds.filter((id) => typeof id === 'string');
+  const mediaReady = Boolean(record)
+    && record.outcome === 'succeeded'
+    && record.deliveryState === 'ready'
+    && artifactIds.length > 0
+    && artifactIds.every((id) => knownIds.has(id));
+  return Object.freeze({
+    id: String(record && record.id || ''),
+    capability: String(record && record.capability || 'image'),
+    userState: view.state,
+    label: view.label,
+    model: modelLabelOf(record),
+    updatedAt: String(record && record.updatedAt || ''),
+    revision: Number.isSafeInteger(record && record.revision) ? record.revision : 0,
+    artifactIds: Object.freeze(artifactIds),
+    mediaReady,
+    observable: coreTaskObservable(record),
+    redeliverable: coreTaskRedeliverable(record),
+    cancelable: coreTaskCancelable(record),
+    retryable: coreTaskRetryable(record)
+  });
+}
+
+/** 完成提示防重的稳定键：同一条 Task 同一 revision 只提示一次。 */
+export function coreCompletionKey(row) {
+  return 'core:' + String(row && row.id || '') + '@' + String(Number(row && row.revision) || 0);
+}
+
+/** 首次加载的基线：把既有完成项记为已见，避免会话开始时就刷一堆提示。 */
+export function seedCoreCompletions(rows) {
+  const keys = new Set();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (row && row.userState === 'succeeded') keys.add(coreCompletionKey(row));
+  }
+  return keys;
+}
+
+/**
+ * 同一份快照重复渲染不应重复提示：返回相对 seen 新出现的完成项，
+ * 以及合并后的键集合（调用方保存供下次比较）。提示不持久化，
+ * 刷新页面后由事实快照重新计算基线。
+ */
+export function diffCoreCompletions(rows, seen) {
+  const known = seen instanceof Set ? new Set(seen) : seedCoreCompletions(rows);
+  const added = [];
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!row || row.userState !== 'succeeded') continue;
+    const key = coreCompletionKey(row);
+    if (!known.has(key)) {
+      known.add(key);
+      added.push(row);
+    }
+  }
+  return Object.freeze({ added: Object.freeze(added), keys: known });
+}

package/lib/doctor.js

@@ -5,6 +5,13 @@ 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 { inspectCoreStorage } from './core-doctor.js';
+import { providerMediaBaseUrl, providerApiKey } from './provider-protocol.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 +52,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)));
 }
 
@@ -98,10 +105,11 @@ function inspectConfig(dataDir, checks) {
   for (const provider of providers) {
     if (!plain(provider)) { incomplete++; continue; }
     if (provider.enabled !== false) enabled++;
-    if (provider.enabled !== false && (!String(provider.baseUrl || '').trim() || !String(provider.apiKey || '').trim())) incomplete++;
+    if (provider.enabled !== false && (!providerMediaBaseUrl(provider)
+        || (provider.auth !== 'none' && !providerApiKey(provider).trim()))) incomplete++;
     models += Array.isArray(provider.models) ? provider.models.length : 0;
   }
-  if (incomplete) checks.push(result('providers', 'warn', `${incomplete} 个启用供应商缺少 Base URL、API Key 或结构无效`, '在 Iris 工作台补全或停用对应供应商。'));
+  if (incomplete) checks.push(result('providers', 'warn', `${incomplete} 个启用供应商缺少端点、所需凭据或结构无效（auth:none 不要求密钥）`, '在 Iris 工作台补全或停用对应供应商。'));
   else if (!enabled) checks.push(result('providers', 'warn', '没有启用的供应商', '在 Iris 工作台启用至少一个供应商。'));
   else checks.push(result('providers', 'ok', `${enabled} 个供应商已启用；凭据未输出`));
   const assignments = config.value.assignments || {};
@@ -151,6 +159,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 +190,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;
@@ -173,9 +205,10 @@ function inspectArtifacts(dataDir, tasks, checks) {
 }
 
 /**
- * 零网络离线诊断。仅创建并立即删除一个写入探针；不启动 DSH、不读取或输出 API Key。
+ * 零网络离线诊断。默认 legacy 检查保留写入探针；显式 Core 模式全程只读。
  */
 export async function doctor(options = {}) {
+  const explicitCore = options.dataRoot !== undefined;
   const dshHome = path.resolve(options.dshHome || process.env.DSH_HOME || path.join(os.homedir(), '.dsh'));
   const dataDir = path.join(dshHome, 'iris', 'v1');
   const runner = options.commandRunner || ((command, args) => spawnSync(command, args, { stdio: 'ignore', shell: false }));
@@ -183,9 +216,9 @@ export async function doctor(options = {}) {
   const nodeVersion = options.nodeVersion || process.versions.node;
   const checks = [];
 
-  checks.push(atLeast(parseVersion(nodeVersion), [20, 10, 0])
+  checks.push(atLeast(parseVersion(nodeVersion), [22, 0, 0])
     ? result('node', 'ok', `Node.js ${nodeVersion}`)
-    : result('node', 'error', `Node.js ${nodeVersion} 低于最低要求 20.10.0`, '升级 Node.js 后再运行 Iris。'));
+    : result('node', 'error', `Node.js ${nodeVersion} 低于最低要求 22.0.0`, '升级 Node.js 后再运行 Iris。'));
   try { await sharpLoader(); checks.push(result('sharp', 'ok', 'sharp 可加载')); }
   catch (_) { checks.push(result('sharp', 'error', 'sharp 无法加载', '在当前平台重新安装 @mokuyoaxis/dsh-iris，确认 sharp 有可用的 ARM64/系统构建。')); }
   for (const command of ['ffmpeg', 'ffprobe']) {
@@ -194,28 +227,39 @@ export async function doctor(options = {}) {
       : result(command, 'warn', `${command} 不可用`, '视频抽帧与摘要需要 ffmpeg/ffprobe；其他 Iris 能力不受影响。'));
   }
 
-  const dataExists = fs.existsSync(dataDir);
-  if (dataExists) {
-    let symlink = false;
-    try { symlink = fs.lstatSync(dataDir).isSymbolicLink(); } catch (_) {}
-    if (symlink) checks.push(result('storage', 'error', 'Iris 数据目录是符号链接，私有边界无法保证', '改用真实的私有目录并人工迁移数据。'));
-    else if (!writableProbe(dataDir)) checks.push(result('storage', 'error', 'Iris 数据目录不可写', '修复当前用户对 $DSH_HOME/iris/v1 的写权限。'));
-    else if (isGroupOrWorldAccessible(dataDir)) checks.push(result('storage', 'warn', 'Iris 数据目录允许组或其他用户访问', '在 POSIX 上将目录权限收紧为 0700、文件收紧为 0600。'));
-    else {
-      const exposedFiles = privateFileModeProblems(dataDir);
-      checks.push(exposedFiles.length
-        ? result('storage', 'warn', `${exposedFiles.length} 个私有数据文件允许组或其他用户访问`, '在 POSIX 上将 providers.json、tasks.json 与提示词配置权限收紧为 0600。')
-        : result('storage', 'ok', 'Iris 数据目录可写、私有文件权限合格，临时探针已清理'));
+  const core = inspectCoreStorage(explicitCore ? options.dataRoot : path.join(dataDir, 'core-v0'));
+  const storageComparison = {
+    legacy: legacyCounts(explicitCore ? options.dataRoot : dataDir),
+    core: { status: core.status, tasks: core.tasks?.total ?? null, artifacts: core.artifacts?.total ?? null }
+  };
+  appendCoreChecks(checks, core);
+  checks.push(result('storage-comparison', 'ok',
+    `Legacy：${storageComparison.legacy.tasks ?? '?'} 个任务、${storageComparison.legacy.artifacts ?? '?'} 个作品；Core：${storageComparison.core.tasks ?? '?'} 个任务、${storageComparison.core.artifacts ?? '?'} 个作品`));
+
+  if (!explicitCore) {
+    const dataExists = fs.existsSync(dataDir);
+    if (dataExists) {
+      let symlink = false;
+      try { symlink = fs.lstatSync(dataDir).isSymbolicLink(); } catch (_) {}
+      if (symlink) checks.push(result('storage', 'error', 'Iris 数据目录是符号链接，私有边界无法保证', '改用真实的私有目录并人工迁移数据。'));
+      else if (!writableProbe(dataDir)) checks.push(result('storage', 'error', 'Iris 数据目录不可写', '修复当前用户对 $DSH_HOME/iris/v1 的写权限。'));
+      else if (isGroupOrWorldAccessible(dataDir)) checks.push(result('storage', 'warn', 'Iris 数据目录允许组或其他用户访问', '在 POSIX 上将目录权限收紧为 0700、文件收紧为 0600。'));
+      else {
+        const exposedFiles = privateFileModeProblems(dataDir);
+        checks.push(exposedFiles.length
+          ? result('storage', 'warn', `${exposedFiles.length} 个私有数据文件允许组或其他用户访问`, '在 POSIX 上将 providers.json、tasks.json 与提示词配置权限收紧为 0600。')
+          : result('storage', 'ok', 'Iris 数据目录可写、私有文件权限合格，临时探针已清理'));
+      }
+    } else {
+      checks.push(writableProbe(dataDir)
+        ? result('storage', 'ok', 'Iris 数据目录尚未创建；父目录可写，临时探针已清理')
+        : result('storage', 'error', 'Iris 数据目录不存在且父目录不可写', '设置一个当前用户可写的 DSH_HOME。'));
     }
-  } else {
-    checks.push(writableProbe(dataDir)
-      ? result('storage', 'ok', 'Iris 数据目录尚未创建；父目录可写，临时探针已清理')
-      : result('storage', 'error', 'Iris 数据目录不存在且父目录不可写', '设置一个当前用户可写的 DSH_HOME。'));
-  }
 
-  inspectConfig(dataDir, checks);
-  const taskRecords = inspectTasks(dataDir, checks);
-  inspectArtifacts(dataDir, taskRecords, checks);
+    inspectConfig(dataDir, checks);
+    const taskRecords = inspectTasks(dataDir, checks);
+    inspectArtifacts(dataDir, taskRecords, checks);
+  }
   checks.push(result('scope', 'ok', '离线模式未启动 DSH、未检查浏览器/工具注册，也未发送供应商请求'));
 
   const errors = checks.filter((item) => item.status === 'error').length;
@@ -223,14 +267,200 @@ export async function doctor(options = {}) {
   return {
     schemaVersion: 1,
     package: { name: '@mokuyoaxis/dsh-iris', version: options.packageVersion || readPackageVersion() },
-    mode: 'offline',
+    mode: explicitCore ? 'core-offline' : 'offline',
     environment: { node: nodeVersion, platform: process.platform, arch: process.arch },
     checks,
+    core,
+    storageComparison,
+    summary: { ok: checks.length - errors - warnings, warnings, errors },
+    exitCode: errors ? 2 : (warnings ? 1 : 0)
+  };
+}
+
+function legacyCounts(directory) {
+  const count = (name, field) => {
+    try {
+      const file = path.join(directory, name);
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink()) return null;
+      const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return Array.isArray(value?.[field]) ? value[field].length : null;
+    } catch (error) { return error?.code === 'ENOENT' ? 0 : null; }
+  };
+  return { tasks: count('tasks.json', 'tasks'), artifacts: count('artifacts.json', 'artifacts') };
+}
+
+function appendCoreChecks(checks, core) {
+  checks.push(result('core-storage', core.status === 'invalid' ? 'error' : 'ok',
+    core.status === 'present' ? 'Core 数据根可读取（只读检查，未执行写入探针）'
+      : core.status === 'absent' ? 'Core 数据根尚未创建；未创建目录' : 'Core 数据根无法读取或不是目录'));
+  if (core.status !== 'present') return;
+  const lease = core.lease;
+  const leaseRemediation = lease.status === 'present' && lease.ownerStatus === 'missing'
+    ? `确认没有跨主机写者后，显式运行 dsh-iris runtime recover --data-root <absolute-path> --confirm-stale-pid ${lease.pid}`
+    : lease.status === 'present' && lease.ownerStatus === 'alive'
+      ? `先停止 PID ${lease.pid} 对应的写者，再重新运行 Doctor；活跃 owner 不可恢复。`
+      : '租约证据不完整或进程状态无法确认；不要删除或恢复，保留现场排查。';
+  checks.push(result('core-writer-lease', lease.status === 'absent' ? 'ok' : 'warn',
+    lease.status === 'absent' ? '未发现写者租约'
+      : lease.status === 'invalid' ? '写者租约证据不完整或不安全，已保留现场'
+      : `写者租约存在：PID ${lease.pid}，进程状态 ${lease.ownerStatus}，年龄 ${Math.floor(lease.ageMs / 1000)} 秒`,
+    lease.status === 'absent' ? undefined : leaseRemediation));
+  const tasks = core.tasks;
+  checks.push(result('core-tasks', tasks.status === 'invalid' ? 'error' : tasks.invalid || tasks.unresolved ? 'warn' : 'ok',
+    tasks.status === 'invalid' ? 'Core Task Store 结构不完整或不安全'
+      : `Core Task：${tasks.total} 个有效记录，${tasks.invalid} 个损坏记录，${tasks.unresolved} 个未解析条目`));
+  const artifacts = core.artifacts;
+  checks.push(result('core-artifacts', artifacts.status === 'invalid' ? 'error'
+    : artifacts.invalid || artifacts.orphanObjects || artifacts.orphanManifests || artifacts.unresolved ? 'warn' : 'ok',
+    artifacts.status === 'invalid' ? 'Core Artifact Store 结构不完整或不安全'
+      : `Core Artifact：${artifacts.total} 个有效记录，${artifacts.invalid} 个无效记录，${artifacts.orphanObjects} 个孤立对象，${artifacts.orphanManifests} 个未提交 Manifest，${artifacts.unresolved} 个未解析条目`));
+  if (artifacts.status !== 'invalid') checks.push(result('core-artifact-index', artifacts.index === 'invalid' ? 'warn' : 'ok',
+    artifacts.index === 'invalid' ? 'Core Artifact Index 缺失、校验失败或与提交记录不一致'
+      : artifacts.index === 'absent' ? 'Core Artifact Store 尚未创建' : 'Core Artifact Index 自校验与提交记录一致',
+    artifacts.index === 'invalid' ? '保留现场；确认租约可用后，显式执行 artifact rebuild。Doctor 不会修复索引。' : undefined));
+}
+
+
+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.2 候选只支持经真实安装服务隔离验收的准确 rc.2。
+     Iris 0.1.4 的旧宿主窗口保留在历史发行中，不用于放行当前源码。 */
+  const version = String(value || '').trim().replace(/\s+/g, '');
+  return /^0\.2\.0-rc\.2(?:\+.*)?$/.test(version);
+}
+
+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 核对；当前候选仅支持 DSH 0.2.0-rc.2。'));
+    } 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 + ' 超出已验证支持范围',
+        '当前候选需要 DSH 0.2.0-rc.2；旧 DSH 0.1.2 线或 0.1.5-rc.1 使用 Iris @mokuyoaxis/dsh-iris@0.1.4。其他版本须另行验收。'));
+    }
+  }
+
+  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}`];