@mokuyoaxis/dsh-iris 0.1.2 → 0.1.3

package/lib/api.js

@@ -12,12 +12,14 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { irisHome, capabilitiesOf, onChange as onConfigChange } from './config.js';
 import { mimeOf, mediaUrl } from './media.js';
 import * as tasks from './tasks.js';
 import { runAction } from './actions.js';
 import { chmodPrivateFile, ensurePrivateDir } from './private-storage.js';
 import { inferMediaProtocol } from './provider-protocol.js';
+import { deriveUserState } from './task-semantics.js';
 import { optimizePrompt } from './prompt-optimizer.js';
 import {
   importPromptOptimizerConfig,
@@ -75,6 +77,21 @@ function mediaOf(task) {
     }));
 }
 
+const V2_FACT_FIELDS = ['phase', 'acceptance', 'watchState', 'outcome', 'deliveryState', 'cancelState'];
+
+function isTaskV2(t) {
+  return Boolean(t && t.schemaVersion === 2 && V2_FACT_FIELDS.every((field) => Object.prototype.hasOwnProperty.call(t, field)));
+}
+
+/** 旧记录保持原四态；只有完整 v2 记录才使用事实轴派生用户态。 */
+function taskUserState(t) {
+  if (isTaskV2(t)) return deriveUserState(t);
+  if (t && t.status === 'succeeded') return 'succeeded';
+  if (t && t.status === 'failed') return 'failed';
+  if (t && t.status === 'canceled') return 'canceled';
+  return 'running';
+}
+
 function taskPublic(t) {
   const elapsedMs =
     t.elapsedMs ||
@@ -83,6 +100,9 @@ function taskPublic(t) {
     id: t.id,
     cap: t.cap || '',
     status: t.status || 'running',
+    userState: taskUserState(t),
+    schemaVersion: Number(t.schemaVersion || 1),
+    revision: Number(t.revision || 0),
     progress: t.progress || '',
     model: t.model || '',
     providerName: t.providerName || '',
@@ -94,6 +114,8 @@ function taskPublic(t) {
     saved: !!t.saved,
     expired: !!t.expired,
     mode: t.mode || '',
+    retryOf: t.retryOf || '',
+    attentionDisposition: tasks.attentionDisposition(t),
     files: Array.isArray(t.files) ? t.files.map((f) => path.basename(f)) : [],
     media: mediaOf(t)
   };
@@ -110,21 +132,32 @@ function loadProviders() {
   return Array.isArray(cache && cache.providers) ? cache.providers : [];
 }
 
-/** 构建完整工作台状态（纯 JSON，可序列化） */
+const STATE_EPOCH = crypto.randomUUID();
+let stateRevision = 0;
+
+/** 构建完整工作台状态（纯 JSON，可序列化）；序号用于客户端拒绝迟到快照。 */
 export function buildState() {
-  const tasks = loadTasks();
+  const taskRecords = loadTasks();
   const providers = loadProviders();
 
-  const all = [...tasks].sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
-  const running = all.filter((t) => t.status === 'running' && !t.expired);
-  const terminal = all.filter((t) => t.status !== 'running');
+  const all = [...taskRecords].sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
+  const stateOf = (t) => taskUserState(t);
+  const needsAttention = (t) => ['watching_paused', 'needs_attention', 'artifact_unavailable'].includes(stateOf(t));
+  const acknowledged = (t) => tasks.attentionDisposition(t).status === 'acknowledged';
+  const running = all.filter((t) => ['queued', 'running'].includes(stateOf(t)) && !t.expired);
+  const attention = all.filter((t) => needsAttention(t) && !acknowledged(t) && !t.expired);
+  const terminal = all.filter((t) => ['succeeded', 'failed', 'canceled'].includes(stateOf(t))
+    || (needsAttention(t) && acknowledged(t)) || t.expired);
   const recent = terminal.slice(0, 100).map(taskPublic);
 
   return {
+    stateEpoch: STATE_EPOCH,
+    stateRevision: ++stateRevision,
     providers: providers.map(providerPublic),
     tasks: {
       recent,
       recentTotal: terminal.length, // 泡泡「查看全部 (N)」计数用（不受 slice 截断）
+      attention: attention.slice(0, 20).map(taskPublic),
       running: running.slice(0, 10).map(taskPublic)
     }
   };
@@ -138,15 +171,44 @@ export function sseClientCount() {
 }
 
 const sseClients = new Set(); // 活跃 res（长连接）
+const sseBlocked = new Set(); // 背压中的连接
+const sseLatest = new WeakMap(); // 每个慢连接只保留最新状态
+const sseDrainBound = new WeakSet();
 let sseHeartbeat = null;      // 心跳定时器（15s，防代理/浏览器空闲断连）
 let sseThrottleTimer = null;  // 推送节流（400ms 合并，防盯守高频 update 刷屏）
 let ssePending = false;
 let sseBound = false;
 
+function bindSseDrain(res) {
+  sseBlocked.add(res);
+  if (sseDrainBound.has(res)) return;
+  sseDrainBound.add(res);
+  res.once('drain', () => {
+    sseDrainBound.delete(res);
+    sseBlocked.delete(res);
+    const latest = sseLatest.get(res);
+    sseLatest.delete(res);
+    if (latest !== undefined) pushSse(res, latest);
+  });
+}
+
 function pushSse(res, data) {
   if (!res || res.writableEnded || res.destroyed) return;
+  if (sseBlocked.has(res)) {
+    sseLatest.set(res, data);
+    return;
+  }
+  try {
+    if (res.write(`data: ${data}\n\n`) === false) bindSseDrain(res);
+  } catch (_) {
+    /* 连接已死，close 事件会清理 */
+  }
+}
+
+function pushSseComment(res, comment) {
+  if (!res || res.writableEnded || res.destroyed || sseBlocked.has(res)) return;
   try {
-    res.write(`data: ${data}\n\n`);
+    if (res.write(`: ${comment}\n\n`) === false) bindSseDrain(res);
   } catch (_) {
     /* 连接已死，close 事件会清理 */
   }
@@ -177,7 +239,7 @@ function scheduleBroadcast() {
 function ensureHeartbeat() {
   if (sseHeartbeat) return;
   sseHeartbeat = setInterval(() => {
-    for (const res of [...sseClients]) pushSse(res, ': ping'); // 注释行保持连接活跃
+    for (const res of [...sseClients]) pushSseComment(res, 'ping'); // 注释帧不覆盖背压期间的最新状态
     if (!sseClients.size) stopHeartbeat();
   }, 15000);
   if (sseHeartbeat && sseHeartbeat.unref) sseHeartbeat.unref();
@@ -239,6 +301,8 @@ function serveSse(res) {
   pushSse(res, JSON.stringify(buildState())); // 立即推当前状态
   const onClose = () => {
     sseClients.delete(res);
+    sseBlocked.delete(res);
+    sseLatest.delete(res);
     if (!sseClients.size) {
       stopHeartbeat();
       if (sseThrottleTimer) clearTimeout(sseThrottleTimer);
@@ -493,6 +557,10 @@ function serveTaskDetail(taskId, method, res) {
     id: t.id,
     cap: t.cap || '',
     status: t.status || '',
+    userState: taskUserState(t),
+    schemaVersion: Number(t.schemaVersion || 1),
+    revision: Number(t.revision || 0),
+    ...(isTaskV2(t) ? Object.fromEntries(V2_FACT_FIELDS.map((field) => [field, t[field]])) : {}),
     progress: t.progress || '',
     model: t.model || '',
     providerName: t.providerName || '',
@@ -503,6 +571,11 @@ function serveTaskDetail(taskId, method, res) {
     error: t.error || '',
     mode: t.mode || '',
     remoteTaskId: t.remoteTaskId || '',
+    retryOf: t.retryOf || '',
+    manualRetries: Array.isArray(t.manualRetries) ? t.manualRetries.filter((item) => item && item.taskId).map((item) => ({
+      taskId: String(item.taskId), createdAt: item.createdAt || ''
+    })) : [],
+    attentionDisposition: tasks.attentionDisposition(t),
     files: Array.isArray(t.files) ? t.files.map((f) => path.basename(f)) : [],
     media: mediaOf(t),
     attachments: Array.isArray(t.attachments) ? t.attachments.map((a) => ({

package/lib/client.js

@@ -37,6 +37,7 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
     '.iris-wb-badge { font-size: 11px; padding: 1px 6px; border-radius: 4px; background: var(--dsw-alias-bg-layer-2, #32323c); }',
     '.iris-wb-badge.ok { color: var(--dsw-alias-state-success-primary, #6fcf6f); }',
     '.iris-wb-badge.err { color: var(--dsw-alias-state-error-primary, #e06c6c); }',
+    '.iris-wb-badge.warn { color: var(--dsw-alias-state-warn-primary, #d9a941); }',
     '.iris-wb-progress { margin-top: 6px; }',
     '.iris-wb-bar { height: 5px; border-radius: 3px; background: var(--dsw-alias-bg-layer-2, #32323c); overflow: hidden; }',
     '.iris-wb-bar i { display: block; height: 100%; background: var(--dsw-alias-brand-primary, #7aa2f7); }',
@@ -252,6 +253,8 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
         if (sharedState) setState(sharedState);
         if (!sharedTimer && !sharedSource) {
           function apply(data) {
+            if (sharedState && data && sharedState.stateEpoch && data.stateEpoch === sharedState.stateEpoch
+                && Number(data.stateRevision || 0) <= Number(sharedState.stateRevision || 0)) return;
             sharedState = data;
             for (var i = 0; i < sharedListeners.length; i++) {
               sharedListeners[i](data);
@@ -347,10 +350,38 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       return '更早';
     }
 
+    var TASK_STATE_LABELS = {
+      queued: '排队中', running: '运行中', watching_paused: '观察暂停', needs_attention: '需要确认',
+      artifact_unavailable: '结果待取回', succeeded: '成功', failed: '失败', canceled: '已取消'
+    };
+    function taskState(task) {
+      if (task && task.userState) return task.userState;
+      if (task && task.status === 'succeeded') return 'succeeded';
+      if (task && task.status === 'failed') return 'failed';
+      if (task && task.status === 'canceled') return 'canceled';
+      return 'running';
+    }
+    function taskStateLabel(task) {
+      var state = taskState(task);
+      return TASK_STATE_LABELS[state] || state;
+    }
+    function taskStateClass(task) {
+      var state = taskState(task);
+      if (state === 'succeeded') return 'ok';
+      if (state === 'failed') return 'err';
+      if (state === 'watching_paused' || state === 'needs_attention' || state === 'artifact_unavailable') return 'warn';
+      return '';
+    }
+    function attentionDispositionLabel(task) {
+      var disposition = task && task.attentionDisposition;
+      if (!disposition || disposition.status !== 'acknowledged') return '';
+      return disposition.reason === 'retried' ? '已通过重试处理' : '提醒已读';
+    }
+
     /* 紧凑任务行：泡泡「任务」标签用，单行摘要 */
     function taskRowMini(task, selected, onSelect) {
-      var st = task.status === 'succeeded' ? 'ok' : task.status === 'failed' ? 'err' : '';
-      var label = task.status === 'succeeded' ? '成功' : task.status === 'failed' ? '失败' : task.status === 'canceled' ? '取消' : (task.progress || '运行中');
+      var st = taskStateClass(task);
+      var label = taskStateLabel(task);
       return React.createElement('div', {
         key: task.id, className: 'iris-task-mini' + (selected ? ' selected' : ''),
         onClick: function () { onSelect(selected ? null : task.id); }, title: '点击展开详情'
@@ -361,6 +392,47 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
         React.createElement('span', { className: 'iris-wb-muted' }, task.createdAt ? new Date(task.createdAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : ''));
     }
 
+    function TaskRecoveryActions({ detail }) {
+      var pair = React.useState('');
+      var note = pair[0];
+      var setNote = pair[1];
+      var busyPair = React.useState(false);
+      var busy = busyPair[0];
+      var setBusy = busyPair[1];
+      var state = taskState(detail);
+      var attentionState = ['watching_paused', 'needs_attention', 'artifact_unavailable'].indexOf(state) >= 0;
+      var acknowledged = detail.attentionDisposition && detail.attentionDisposition.status === 'acknowledged';
+      var canAcknowledge = detail.schemaVersion === 2 && attentionState && !acknowledged;
+      var canRestore = detail.schemaVersion === 2 && attentionState && acknowledged;
+      var canReobserve = detail.schemaVersion === 2 && !acknowledged && detail.acceptance === 'accepted' && detail.remoteTaskId
+        && detail.outcome !== 'succeeded' && detail.outcome !== 'failed' && detail.outcome !== 'canceled';
+      var canRedeliver = detail.schemaVersion === 2 && !acknowledged && state === 'artifact_unavailable' && detail.remoteTaskId;
+      var canRetry = detail.schemaVersion === 2 && !acknowledged && ['needs_attention', 'failed', 'canceled'].indexOf(state) >= 0
+        && (detail.cap === 'image' || (detail.cap === 'video' && detail.mode === 't2v'));
+      if (!canAcknowledge && !canRestore && !canReobserve && !canRedeliver && !canRetry) return null;
+      function run(action, body, confirmMessage) {
+        if (confirmMessage && !window.confirm(confirmMessage)) return;
+        setBusy(true);
+        setNote('处理中…');
+        postAction(action, body).then(function (r) {
+          setNote(r.ok ? ((r.d && r.d.text) || '操作已接受') : ('失败：' + ((r.d && r.d.error) || '未知错误')));
+        }).catch(function (error) { setNote('失败：' + String((error && error.message) || error)); })
+          .finally(function () { setBusy(false); });
+      }
+      return React.createElement('div', { className: 'iris-wb-row', onClick: function (e) { e.stopPropagation(); } },
+        canReobserve ? React.createElement('button', { className: 'iris-pm-btn', disabled: busy, onClick: function () { run('task_reobserve', { task_id: detail.id }); } }, '重新观察') : null,
+        canRedeliver ? React.createElement('button', { className: 'iris-pm-btn', disabled: busy, onClick: function () { run('task_redeliver', { task_id: detail.id }); } }, '重新交付') : null,
+        canRetry ? React.createElement('button', { className: 'iris-pm-btn danger', disabled: busy, onClick: function () {
+          run('task_manual_retry', { task_id: detail.id, confirm_duplicate_charge: true },
+            '远端任务可能已经产生，本次会创建新的生成任务，可能重复计费。确认知情重试？');
+        } }, '知情重试') : null,
+        canAcknowledge ? React.createElement('button', { className: 'iris-pm-btn', disabled: busy,
+          onClick: function () { run('task_ack_attention', { task_id: detail.id }); } }, '标为已读') : null,
+        canRestore ? React.createElement('button', { className: 'iris-pm-btn', disabled: busy,
+          onClick: function () { run('task_restore_attention', { task_id: detail.id }); } }, '恢复提醒') : null,
+        note ? React.createElement('span', { className: 'iris-clean-note' }, note) : null);
+    }
+
     /* ---- 任务详情抽屉：点击任务卡片行展开 ---- */
     function TaskDetailDrawer({ taskId }) {
       var detail = useTaskDetail(taskId);
@@ -370,6 +442,15 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       var el = [];
       el.push(React.createElement('div', { key: 'k', className: 'iris-wb-k' }, '提示词'));
       el.push(React.createElement('div', { key: 'p', className: 'iris-wb-prompt' }, detail.prompt || '（空）'));
+      if (Number(detail.schemaVersion) === 1) {
+        el.push(React.createElement('div', { key: 'legacy', className: 'iris-clean-note' },
+          '旧版任务记录 · 仅支持查看。由于缺少可靠的远端受理与交付事实，不提供重新观察、重新交付或知情重试；0.1.3 新任务将使用可信任务语义。'));
+      }
+      var dispositionLabel = attentionDispositionLabel(detail);
+      if (dispositionLabel) {
+        var related = detail.attentionDisposition.relatedTaskId ? ' · 关联任务 ' + detail.attentionDisposition.relatedTaskId : '';
+        el.push(React.createElement('div', { key: 'attention-disposition', className: 'iris-clean-note' }, dispositionLabel + related));
+      }
       if (detail.error) {
         el.push(React.createElement('div', { key: 'ek', className: 'iris-wb-k' }, '错误'));
         el.push(React.createElement('div', { key: 'e', className: 'iris-wb-err' }, detail.error));
@@ -377,11 +458,13 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       var kv = [
         ['ID', detail.id],
         ['能力', detail.cap],
-        ['状态', detail.status],
+        ['状态', taskStateLabel(detail)],
         ['模型', detail.model],
         ['供应商', detail.providerName],
         ['模式', detail.mode || '—'],
         ['远端任务', detail.remoteTaskId || '—'],
+        ['来源任务', detail.retryOf || '—'],
+        ['后续重试', (detail.manualRetries || []).map(function (item) { return item.taskId; }).join('、') || '—'],
         ['发起', detail.createdAt ? fmtTime(detail.createdAt) : '—'],
         ['完成', detail.finishedAt ? fmtTime(detail.finishedAt) : '—'],
         ['耗时', detail.elapsedMs ? fmtElapsed(detail.elapsedMs) : '—']
@@ -418,24 +501,25 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
             return React.createElement('span', { key: a.attachmentId, className: 'iris-wb-kv' }, a.attachmentId + (a.file ? ' (' + a.file + ')' : ''));
           })));
       }
+      el.push(React.createElement(TaskRecoveryActions, { key: 'recovery', detail: detail }));
       return React.createElement('div', { className: 'iris-wb-drawer' }, ...el);
     }
 
     function taskRow(task, isRunning, selected, onSelect) {
-      var badge;
-      if (task.status === 'succeeded') {
-        badge = React.createElement('span', { className: 'iris-wb-badge ok' }, '成功');
-      } else if (task.status === 'failed') {
-        badge = React.createElement('span', { className: 'iris-wb-badge err' }, '失败');
-      } else {
-        badge = React.createElement('span', { className: 'iris-wb-badge' }, task.status);
-      }
+      var stateClass = taskStateClass(task);
+      var badge = React.createElement('span', { className: 'iris-wb-badge' + (stateClass ? ' ' + stateClass : '') }, taskStateLabel(task));
       var cells = [
         React.createElement('span', { className: 'iris-wb-kv' }, task.cap),
         badge,
         React.createElement('span', { className: 'iris-wb-kv' }, task.model || ''),
         React.createElement('span', { className: 'iris-wb-muted' }, String(task.prompt || '').slice(0, 60))
       ];
+      if (Number(task.schemaVersion) === 1) {
+        cells.push(React.createElement('span', { className: 'iris-wb-badge', title: '旧版记录缺少可靠的远端受理与交付事实，仅支持查看' }, '旧任务 · 只读'));
+      }
+      var dispositionLabel = attentionDispositionLabel(task);
+      if (dispositionLabel) cells.push(React.createElement('span', { className: 'iris-wb-badge ok' }, dispositionLabel));
+      if (task.retryOf) cells.push(React.createElement('span', { className: 'iris-wb-badge' }, '重试任务'));
       if (task.error) cells.push(React.createElement('span', { className: 'iris-wb-badge err' }, String(task.error).slice(0, 40)));
       var links = (task.media || []).map(function (m) {
         return React.createElement('a', {
@@ -1061,6 +1145,7 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       var state = useIrisState(5000);
       var running = (state && state.tasks && state.tasks.running) || [];
       var recent = (state && state.tasks && state.tasks.recent) || [];
+      var attention = (state && state.tasks && state.tasks.attention) || [];
       var selPair = React.useState(null);
       var selectedTask = selPair[0];
       var setSelectedTask = selPair[1];
@@ -1081,6 +1166,10 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
         React.createElement('div', { className: 'iris-wb-box' },
           running.length ? running.map(function (t) { return taskRow(t, true, selectedTask === t.id, onSelect); })
             : React.createElement('div', { className: 'iris-wb-empty' }, '暂无进行中任务')),
+        attention.length ? React.createElement('div', {},
+          React.createElement('div', { className: 'iris-wb-sec' }, '需要处理'),
+          React.createElement('div', { className: 'iris-wb-box' },
+            attention.map(function (t) { return taskRow(t, false, selectedTask === t.id, onSelect); }))) : null,
         React.createElement('div', { className: 'iris-wb-sec' }, '历史任务'),
         React.createElement(CleanupBar, {}),
         React.createElement(HistoryBrowser, { recent: recent, selected: selectedTask, onSelect: onSelect }),
@@ -1093,6 +1182,7 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       var state = useIrisState(5000);
       var running = (state && state.tasks && state.tasks.running) || [];
       var recent = (state && state.tasks && state.tasks.recent) || [];
+      var attention = (state && state.tasks && state.tasks.attention) || [];
       var recentTotal = (state && state.tasks && state.tasks.recentTotal) || recent.length;
       var cards = useBubbleCards()[0];
       var tabPair = React.useState('tasks');
@@ -1104,7 +1194,7 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       function onSelect(id) { setSelectedTask(id); }
       var body;
       if (tab === 'tasks') {
-        // 快捷面板只承载当前任务与可直接查看的成功产物；失败/取消历史留在完整工作台。
+        // 快捷面板承载当前任务、需要处理的异常事实与可直接查看的成功产物。
         var succeeded = recent.filter(function (t) {
           return t.status === 'succeeded' && Array.isArray(t.media) && t.media.length > 0;
         });
@@ -1113,6 +1203,9 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
           running.length ? React.createElement('div', {},
             React.createElement('div', { className: 'iris-wb-sec' }, '运行中'),
             running.map(function (t) { return taskRow(t, true, selectedTask === t.id, onSelect); })) : null,
+          attention.length ? React.createElement('div', {},
+            React.createElement('div', { className: 'iris-wb-sec' }, '需要处理'),
+            attention.slice(0, 4).map(function (t) { return taskRowMini(t, selectedTask === t.id, onSelect); })) : null,
           React.createElement('div', { className: 'iris-wb-sec' }, '最近完成'),
           shown.length ? shown.map(function (t) { return taskRowMini(t, selectedTask === t.id, onSelect); })
             : React.createElement('div', { className: 'iris-wb-empty' }, '尚无成功产物'),
@@ -1379,6 +1472,7 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
       var providers = (state && state.providers) || [];
       var configured = providers.some(function (p) { return p.enabled && p.apiKeyHint; });
       var running = (state && state.tasks && state.tasks.running) || [];
+      var attention = (state && state.tasks && state.tasks.attention) || [];
 
       var posPair = React.useState(function () {
         var saved = null;
@@ -1464,8 +1558,9 @@ window.__ModuleLoader__.load({ id: '@mokuyoaxis/dsh-iris', factory: (require) =>
         style = { right: DEFAULT_X + 'px', bottom: DEFAULT_Y + 'px' };
       }
 
-      var badge = running.length
-        ? React.createElement('span', { className: 'iris-bubble-badge' }, running.length)
+      var badgeCount = running.length + attention.length;
+      var badge = badgeCount
+        ? React.createElement('span', { className: 'iris-bubble-badge', title: attention.length ? attention.length + ' 个任务需要处理' : '' }, badgeCount)
         : null;
 
       var panel = null;

package/lib/doctor.js

@@ -0,0 +1,243 @@
+'use strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { attentionDisposition, deriveUserState, semanticViolations } from './task-semantics.js';
+
+const PACKAGE_FILE = new URL('../package.json', import.meta.url);
+
+function readPackageVersion() {
+  try { return JSON.parse(fs.readFileSync(PACKAGE_FILE, 'utf8')).version || 'unknown'; } catch (_) { return 'unknown'; }
+}
+
+function result(id, status, summary, suggestion) {
+  return { id, status, summary, ...(suggestion ? { suggestion } : {}) };
+}
+
+function parseVersion(value) {
+  const match = String(value || '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1).map(Number) : [0, 0, 0];
+}
+
+function atLeast(actual, required) {
+  for (let i = 0; i < 3; i++) {
+    if (actual[i] !== required[i]) return actual[i] > required[i];
+  }
+  return true;
+}
+
+function readJson(file) {
+  if (!fs.existsSync(file)) return { exists: false, value: null };
+  try { return { exists: true, value: JSON.parse(fs.readFileSync(file, 'utf8')) }; }
+  catch (_) { return { exists: true, value: null, error: 'JSON 无法解析' }; }
+}
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isGroupOrWorldAccessible(target) {
+  if (process.platform === 'win32' || !fs.existsSync(target)) return false;
+  try { return (fs.lstatSync(target).mode & 0o077) !== 0; } catch (_) { return false; }
+}
+
+function privateFileModeProblems(dataDir) {
+  if (process.platform === 'win32') return [];
+  return ['providers.json', 'tasks.json', 'prompt-optimizer.json']
+    .filter((name) => isGroupOrWorldAccessible(path.join(dataDir, name)));
+}
+
+function commandAvailable(command, runner) {
+  try {
+    const run = runner(command, ['-version']);
+    return Boolean(run && run.status === 0 && !run.error);
+  } catch (_) { return false; }
+}
+
+function nearestExisting(target) {
+  let current = target;
+  for (;;) {
+    if (fs.existsSync(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function writableProbe(dataDir) {
+  const base = fs.existsSync(dataDir) ? dataDir : nearestExisting(path.dirname(dataDir));
+  if (!base) return false;
+  const probe = path.join(base, `.iris-doctor-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    fs.writeFileSync(probe, 'probe', { flag: 'wx', mode: 0o600 });
+    fs.rmSync(probe);
+    return true;
+  } catch (_) {
+    try { fs.rmSync(probe, { force: true }); } catch (_) {}
+    return false;
+  }
+}
+
+function inspectConfig(dataDir, checks) {
+  const config = readJson(path.join(dataDir, 'providers.json'));
+  if (!config.exists) {
+    checks.push(result('config', 'warn', '尚未创建供应商配置', '启动 Iris 后在工作台添加供应商，或准备好 DSH_HOME 后再运行 doctor。'));
+    return { providers: [], assignments: {} };
+  }
+  if (config.error || !plain(config.value) || !Array.isArray(config.value.providers)
+      || !plain(config.value.assignments || {})) {
+    checks.push(result('config', 'error', 'providers.json 结构无效或无法解析', '先备份该文件，再从 Iris 工作台重新配置；不要把密钥粘贴到诊断输出。'));
+    return { providers: [], assignments: {} };
+  }
+  const providers = config.value.providers;
+  let incomplete = 0;
+  let enabled = 0;
+  let models = 0;
+  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++;
+    models += Array.isArray(provider.models) ? provider.models.length : 0;
+  }
+  if (incomplete) checks.push(result('providers', 'warn', `${incomplete} 个启用供应商缺少 Base URL、API Key 或结构无效`, '在 Iris 工作台补全或停用对应供应商。'));
+  else if (!enabled) checks.push(result('providers', 'warn', '没有启用的供应商', '在 Iris 工作台启用至少一个供应商。'));
+  else checks.push(result('providers', 'ok', `${enabled} 个供应商已启用；凭据未输出`));
+  const assignments = config.value.assignments || {};
+  const assignmentCount = Object.keys(assignments).length;
+  if (!models) checks.push(result('models', 'warn', '模型池为空或尚未发现模型', '在工作台对供应商执行“发现模型”，再核对能力标签。'));
+  else checks.push(result('models', 'ok', `模型池记录 ${models} 个模型，能力分配 ${assignmentCount} 项`));
+  return { providers, assignments };
+}
+
+function inspectTasks(dataDir, checks) {
+  const stored = readJson(path.join(dataDir, 'tasks.json'));
+  if (!stored.exists) {
+    checks.push(result('tasks', 'ok', '尚无任务记录'));
+    return [];
+  }
+  if (stored.error || !plain(stored.value) || !Array.isArray(stored.value.tasks)) {
+    checks.push(result('tasks', 'error', 'tasks.json 结构无效或无法解析', '保留损坏文件作为证据；重新启动 Iris 会尝试隔离并建立新任务表。'));
+    return [];
+  }
+  let invalid = 0;
+  let attention = 0;
+  for (const task of stored.value.tasks) {
+    if (!plain(task) || !String(task.id || '').trim()) { invalid++; continue; }
+    if (task.schemaVersion === 2) {
+      if (semanticViolations(task).length) invalid++;
+      const userState = deriveUserState(task);
+      if (['watching_paused', 'needs_attention', 'artifact_unavailable'].includes(userState)
+          && attentionDisposition(task).status !== 'acknowledged') attention++;
+    } else if (task.status === 'running' && !task.remoteTaskId) attention++;
+  }
+  if (invalid) checks.push(result('tasks', 'error', `${invalid} 条任务记录语义或结构无效`, '不要手工改写任务事实；先备份 tasks.json 并保留损坏证据。'));
+  else if (attention) checks.push(result('tasks', 'warn', `${stored.value.tasks.length} 条任务中有 ${attention} 条需要人工确认`, '在 Iris 工作台的“需要处理”分区查看，并选择重新观察、重新交付、标为已读或知情重试。'));
+  else checks.push(result('tasks', 'ok', `${stored.value.tasks.length} 条任务记录结构有效`));
+  return stored.value.tasks.filter(plain);
+}
+
+function inspectArtifacts(dataDir, tasks, checks) {
+  const outputs = path.join(dataDir, 'outputs');
+  const referenced = new Set();
+  let missing = 0;
+  for (const task of tasks) {
+    for (const name of task.files || []) {
+      const safe = path.basename(String(name));
+      referenced.add(safe);
+      try { if (!fs.statSync(path.join(outputs, safe)).isFile()) missing++; } catch (_) { missing++; }
+    }
+    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)));
+  }
+  let orphan = 0;
+  if (fs.existsSync(outputs)) {
+    for (const name of fs.readdirSync(outputs)) {
+      const target = path.join(outputs, name);
+      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} 个已引用产物可核对，未发现孤儿文件`));
+
+  const uploads = path.join(dataDir, 'uploads');
+  let temporary = 0;
+  if (fs.existsSync(uploads)) {
+    for (const name of fs.readdirSync(uploads)) if (name.endsWith('.part')) temporary++;
+  }
+  checks.push(temporary
+    ? result('temporary-files', 'warn', `${temporary} 个上传临时 .part 文件残留`, '确认没有上传进行中后重启 Iris，由启动清理逻辑处理。')
+    : result('temporary-files', 'ok', '未发现上传临时文件残留'));
+}
+
+/**
+ * 零网络离线诊断。仅创建并立即删除一个写入探针；不启动 DSH、不读取或输出 API Key。
+ */
+export async function doctor(options = {}) {
+  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 }));
+  const sharpLoader = options.sharpLoader || (() => import('sharp'));
+  const nodeVersion = options.nodeVersion || process.versions.node;
+  const checks = [];
+
+  checks.push(atLeast(parseVersion(nodeVersion), [20, 10, 0])
+    ? result('node', 'ok', `Node.js ${nodeVersion}`)
+    : result('node', 'error', `Node.js ${nodeVersion} 低于最低要求 20.10.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']) {
+    checks.push(commandAvailable(command, runner)
+      ? result(command, 'ok', `${command} 可用`)
+      : 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 数据目录可写、私有文件权限合格，临时探针已清理'));
+    }
+  } 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);
+  checks.push(result('scope', 'ok', '离线模式未启动 DSH、未检查浏览器/工具注册，也未发送供应商请求'));
+
+  const errors = checks.filter((item) => item.status === 'error').length;
+  const warnings = checks.filter((item) => item.status === 'warn').length;
+  return {
+    schemaVersion: 1,
+    package: { name: '@mokuyoaxis/dsh-iris', version: options.packageVersion || readPackageVersion() },
+    mode: 'offline',
+    environment: { node: nodeVersion, platform: process.platform, arch: process.arch },
+    checks,
+    summary: { ok: checks.length - errors - warnings, warnings, errors },
+    exitCode: errors ? 2 : (warnings ? 1 : 0)
+  };
+}
+
+export function formatDoctorReport(report) {
+  const mark = { ok: '✓', warn: '!', error: '✗' };
+  const lines = [`Iris Doctor ${report.package.version} · ${report.mode}`];
+  for (const check of report.checks) {
+    lines.push(`${mark[check.status] || '-'} ${check.id}: ${check.summary}`);
+    if (check.suggestion) lines.push(`  建议：${check.suggestion}`);
+  }
+  lines.push(`结果：${report.summary.errors} 错误，${report.summary.warnings} 警告`);
+  return lines.join('\n');
+}