@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/adapters.js

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { dashscopeApiBase } from './provider-protocol.js';
+import { dashscopeApiBase, isDashScopeBaseUrl } from './provider-protocol.js';
 import { chmodPrivateFile, ensurePrivateDir, privateSibling } from './private-storage.js';
 
 /**
@@ -31,7 +31,10 @@ function timeoutSignal(ms, external) {
 }
 
 function authHeaders(key) {
-  return { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' };
+  return {
+    ...(typeof key === 'string' && key.trim() ? { Authorization: `Bearer ${key}` } : {}),
+    'Content-Type': 'application/json'
+  };
 }
 
 async function readJson(res) {
@@ -236,11 +239,11 @@ export async function uploadTempFile({ key, baseUrl, model, filePath, timeoutMs
 const TERMINAL = new Set(['SUCCEEDED', 'FAILED', 'CANCELED', 'UNKNOWN']);
 
 /** @returns {{done:boolean, ok:boolean, urls:string[], message?:string}} */
-export async function pollTask({ key, baseUrl, remoteTaskId, timeoutMs = T_POLL }) {
+export async function pollTask({ key, baseUrl, remoteTaskId, timeoutMs = T_POLL, signal }) {
   const apiBase = dashscopeApiBase(baseUrl);
   const res = await fetch(`${apiBase}/tasks/${encodeURIComponent(remoteTaskId)}`, {
     headers: authHeaders(key),
-    signal: timeoutSignal(timeoutMs)
+    signal: timeoutSignal(timeoutMs, signal)
   });
   const body = await readJson(res);
   if (!res.ok) throw providerError(res.status, body, '查询任务失败');
@@ -317,25 +320,59 @@ export async function openAiGenerateImage({ key, baseUrl, model, prompt, size =
   return out;
 }
 
-/* ---------------- 模型发现（OpenAI 兼容 GET /models，各家通用） ---------------- */
+/* ---------------- 模型发现（OpenAI GET /models + DashScope GET /api/v1/models） ---------------- */
 /**
- * 拉取 provider 可用模型 id 列表。OpenAI 标准端点，DashScope compatible-mode 亦支持。
- * 免费只读；返回 [{ id }] 原样（分类由 models.js 规则负责）。
- * @returns {Promise<string[]>}
+ * 拉取供应商模型目录。DashScope 官方端点分页读取并保留 capabilities；
+ * 普通 OpenAI 兼容端点维持 GET /models 与字符串 id 返回形状。
+ * @returns {Promise<Array<string|{id:string,capabilities?:string[]}>>}
  */
-export async function listModels({ key, baseUrl, timeoutMs = T_SUBMIT }) {
+export async function listModels({ key, baseUrl, timeoutMs = T_SUBMIT, signal }) {
   const base = String(baseUrl || '').trim().replace(/\/+$/, '');
   if (!base) throw new Error('iris: 供应商缺 baseUrl，无法发现模型');
-  const res = await fetch(`${base}/models`, { headers: authHeaders(key), signal: timeoutSignal(timeoutMs) });
-  const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '模型发现失败');
-  const items = (body && Array.isArray(body.data) && body.data) || (Array.isArray(body && body.models) ? body.models : []);
-  const ids = [];
-  for (const it of items) {
-    const id = typeof it === 'string' ? it : it && it.id;
-    if (typeof id === 'string' && id && !ids.includes(id)) ids.push(id);
+  const dashscope = isDashScopeBaseUrl(base);
+  const endpoint = dashscope ? dashscopeApiBase(base) + '/models' : base + '/models';
+  const found = new Map();
+  const maxPages = dashscope ? 50 : 1;
+  let loaded = 0;
+  for (let page = 1; page <= maxPages; page++) {
+    const url = new URL(endpoint);
+    if (dashscope) {
+      url.searchParams.set('page_no', String(page));
+      url.searchParams.set('page_size', '100');
+    }
+    const res = await fetch(url, { headers: authHeaders(key), signal: timeoutSignal(timeoutMs, signal) });
+    const body = await readJson(res);
+    if (!res.ok) throw providerError(res.status, body, '模型发现失败');
+    const output = body && body.output;
+    const items = (output && Array.isArray(output.models) && output.models)
+      || (body && Array.isArray(body.data) && body.data)
+      || (Array.isArray(body && body.models) ? body.models : []);
+    loaded += items.length;
+    for (const item of items) {
+      const id = String(typeof item === 'string' ? item : item?.id || item?.model || '').trim();
+      if (!id || found.has(id)) continue;
+      const capabilities = Array.isArray(item?.capabilities)
+        ? item.capabilities.filter((value) => typeof value === 'string' && value)
+        : [];
+      const requestModalities = Array.isArray(item?.inference_metadata?.request_modality)
+        ? item.inference_metadata.request_modality.map((value) => String(value).toLowerCase()) : [];
+      const responseModalities = Array.isArray(item?.inference_metadata?.response_modality)
+        ? item.inference_metadata.response_modality.map((value) => String(value).toLowerCase()) : [];
+      if (responseModalities.includes('image')) capabilities.push('IG');
+      if (responseModalities.includes('video')) capabilities.push('VG');
+      if (requestModalities.includes('audio') && responseModalities.includes('text')) capabilities.push('ASR');
+      if (requestModalities.includes('text') && responseModalities.includes('audio')) capabilities.push('TTS');
+      if (requestModalities.includes('image') && responseModalities.includes('text')) capabilities.push('VU');
+      const normalizedCapabilities = [...new Set(capabilities)];
+      found.set(id, normalizedCapabilities.length ? { id, capabilities: normalizedCapabilities } : id);
+    }
+    if (!dashscope) break;
+    const statedTotal = Number(output?.total);
+    const total = Number.isFinite(statedTotal) && statedTotal >= 0 ? statedTotal : null;
+    if (!items.length || (total !== null && loaded >= total) || items.length < 100) break;
+    if (page === maxPages) throw new Error('iris: 模型目录超过安全分页上限，已保留原模型池');
   }
-  return ids;
+  return [...found.values()];
 }
 
 /* ---------------- 视觉理解（OpenAI 兼容 SSE 流式） ---------------- */
@@ -476,11 +513,11 @@ export function transcriptionText(payload) {
 }
 
 /** 轮询 ASR 任务；正式结果位于 results[].transcription_url 指向的 JSON。 */
-export async function pollTranscriptionTask({ key, baseUrl, remoteTaskId, timeoutMs = T_POLL }) {
+export async function pollTranscriptionTask({ key, baseUrl, remoteTaskId, timeoutMs = T_POLL, signal }) {
   const apiBase = dashscopeApiBase(baseUrl);
   const res = await fetch(`${apiBase}/tasks/${encodeURIComponent(remoteTaskId)}`, {
     headers: authHeaders(key),
-    signal: timeoutSignal(timeoutMs)
+    signal: timeoutSignal(timeoutMs, signal)
   });
   const body = await readJson(res);
   if (!res.ok) throw providerError(res.status, body, '查询转写任务失败');
@@ -499,7 +536,7 @@ export async function pollTranscriptionTask({ key, baseUrl, remoteTaskId, timeou
       if (typeof result.transcription_text === 'string') text += result.transcription_text;
       else if (typeof result.text === 'string') text += result.text;
       if (status === 'SUCCEEDED' && result.subtask_status !== 'FAILED' && typeof result.transcription_url === 'string') {
-        const transcriptRes = await fetch(result.transcription_url, { signal: timeoutSignal(timeoutMs) });
+        const transcriptRes = await fetch(result.transcription_url, { signal: timeoutSignal(timeoutMs, signal) });
         if (!transcriptRes.ok) throw new Error(`下载转写结果失败：HTTP ${transcriptRes.status}`);
         const transcriptBody = await readJson(transcriptRes);
         if (!transcriptBody) throw new Error('下载转写结果失败：响应不是 JSON');

package/lib/api.js

@@ -7,19 +7,23 @@
  *
  * 输出纪律（与整仓一致）：
  * - 只回标量字段（字符串/数字/布尔/受限数组），apiKey 永不明文，只给 hint；
- * - 文件路径只给相对 outputs/ 的 basename + 授权播放链接（token 随机 128bit）；
+ * - legacy 文件路径只给相对 outputs/ 的 basename + 128-bit token 链接；Core 媒体按随机 Artifact ID 读取，不宣称独立 token；
  * - tasks/providers 读的是 $DSH_HOME/iris/v1 的持久 JSON，与任务盯守共用同一存储。
  */
 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 { irisHome, capabilitiesOf, onChange as onConfigChange, providerHealthSnapshot } from './config.js';
 import { mimeOf, mediaUrl } from './media.js';
 import * as tasks from './tasks.js';
+import * as artifacts from './artifacts.js';
 import { runAction } from './actions.js';
 import { chmodPrivateFile, ensurePrivateDir } from './private-storage.js';
-import { inferMediaProtocol } from './provider-protocol.js';
+import { selectMediaProtocol } from './provider-protocol.js';
 import { deriveUserState } from './task-semantics.js';
+import { hostDoctor } from './doctor.js';
+import { hostRuntimeEvidence, recordHostClient } from './host-runtime.js';
+import { cancelProviderTaskForDsh, coreSnapshotForDsh, disposeCoreTaskAttention, readCoreArtifactMediaForDsh, redeliverProviderTaskForDsh, reobserveProviderTaskForDsh, retryProviderTaskForDsh } from './dsh-core-adapter.js';
 import { optimizePrompt } from './prompt-optimizer.js';
 import {
   importPromptOptimizerConfig,
@@ -52,8 +56,9 @@ function providerPublic(p) {
     name: p.name || p.id,
     type: p.type || 'openai',
     baseUrl: p.baseUrl,
+    mediaBaseUrl: p.mediaBaseUrl || '',
     enabled: p.enabled !== false,
-    mediaProtocol: p.mediaProtocol || inferMediaProtocol(p.baseUrl),
+    ...selectMediaProtocol(p),
     apiKeyHint: keyHint(p.apiKey),
     capabilities: capabilitiesOf(p),
     // 迁移/推断结果是否与原始声明不同（UI 提示旧配置已推断）
@@ -149,11 +154,14 @@ export function buildState() {
   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);
+  const artifactSummary = artifacts.page({ offset: 0, limit: 6 });
 
   return {
     stateEpoch: STATE_EPOCH,
     stateRevision: ++stateRevision,
     providers: providers.map(providerPublic),
+    health: providerHealthSnapshot(),
+    artifacts: { total: artifactSummary.total, recent: artifactSummary.items },
     tasks: {
       recent,
       recentTotal: terminal.length, // 泡泡「查看全部 (N)」计数用（不受 slice 截断）
@@ -276,7 +284,7 @@ let sseBusDisposers = [];
 function bindChangeBus() {
   if (sseBound) return;
   sseBound = true;
-  sseBusDisposers = [tasks.onChange(scheduleBroadcast), onConfigChange(scheduleBroadcast)];
+  sseBusDisposers = [tasks.onChange(scheduleBroadcast), artifacts.onChange(scheduleBroadcast), onConfigChange(scheduleBroadcast)];
 }
 function unbindChangeBus() {
   for (const d of sseBusDisposers) {
@@ -316,22 +324,33 @@ function serveSse(res) {
 }
 
 /** webServer 前缀路由 handler：状态、任务、动作与提示词优化器 API。 */
-export function serveApi(req, res, ctx) {
+export function serveApi(req, res, host) {
   try {
     const method = String(req.method || 'GET').toUpperCase();
     const urlPath = String(req.url || '').split('?')[0];
 
     // POST /iris/api/actions/:name —— GUI 直连触发工具执行
     if (method === 'POST') {
+      if (urlPath === '/iris/api/host-client') {
+        if (!host || typeof host !== 'object') return sendJson(res, 503, { error: 'host unavailable' });
+        return handleJsonPost(req, res, (body) => recordHostClient(body));
+      }
       // 文件选择器 L2：上传本地文件字节 → 存 uploads/ → 返回路径（独立大 body 上限）
       if (urlPath === '/iris/api/upload') {
         return handleUpload(req, res);
       }
-      const promptMatch = typeof ctx === 'object' && urlPath.match(/^\/iris\/api\/prompt-optimizer\/(optimize|import|reset|enabled)\/?$/);
-      if (promptMatch) return handlePromptOptimizer(ctx, promptMatch[1], req, res);
-      const actionMatch = typeof ctx === 'object' && urlPath.match(/^\/iris\/api\/actions\/([A-Za-z0-9_-]+)\/?$/);
+      // D4 人工 retry as new task：产生新的真实计费，请求体必须显式 confirmBilling:true
+      const coreTaskRetry = urlPath.match(/^\/iris\/api\/core\/task\/([^/]+)\/retry\/?$/);
+      if (coreTaskRetry) return handleCoreTaskRetry(coreTaskRetry[1], req, res);
+      // D1/D2/D3 人工动作：reobserve 显式单步 poll 一次；redeliver 只对 succeeded+failed
+      // 重新取回产物；cancel 只有 Provider 明确确认才写已取消。三者绝不 submit。
+      const coreTaskAction = urlPath.match(/^\/iris\/api\/core\/task\/([^/]+)\/(reobserve|redeliver|cancel|acknowledge|restore|hide|unhide)\/?$/);
+      if (coreTaskAction) return handleCoreTaskManual(coreTaskAction[2], coreTaskAction[1], req, res);
+      const promptMatch = typeof host === 'object' && urlPath.match(/^\/iris\/api\/prompt-optimizer\/(optimize|import|reset|enabled)\/?$/);
+      if (promptMatch) return handlePromptOptimizer(host, promptMatch[1], req, res);
+      const actionMatch = typeof host === 'object' && urlPath.match(/^\/iris\/api\/actions\/([A-Za-z0-9_-]+)\/?$/);
       if (!actionMatch) { return sendJson(res, 405, { error: 'method not allowed' }); }
-      return handleAction(ctx, actionMatch[1], req, res);
+      return handleAction(host, actionMatch[1], req, res);
     }
     // GET/HEAD 原逻辑
     if (method !== 'GET' && method !== 'HEAD') {
@@ -345,6 +364,22 @@ export function serveApi(req, res, ctx) {
     if (urlPath === '/iris/api/prompt-optimizer/config') {
       return sendJson(res, 200, method === 'HEAD' ? {} : loadPromptOptimizerConfig());
     }
+    if (urlPath === '/iris/api/doctor') {
+      if (!host || typeof host !== 'object') return sendJson(res, 503, { error: 'host unavailable' });
+      return sendJson(res, 200, method === 'HEAD' ? {} : hostDoctor(host, hostRuntimeEvidence()));
+    }
+    if (urlPath === '/iris/api/core/snapshot') {
+      if (method === 'HEAD') return sendJson(res, 200, {});
+      const query = new URL(req.url || '', 'http://iris.local').searchParams;
+      return serveCoreSnapshot(res, { limit: Number(query.get('limit') || 12) });
+    }
+    const coreMediaMatch = urlPath.match(/^\/iris\/api\/core\/artifact\/(artifact_[a-f0-9]{24})\/media$/);
+    if (coreMediaMatch) return serveCoreArtifactMedia(coreMediaMatch[1], method, res);
+    if (urlPath === '/iris/api/artifacts') {
+      const query = new URL(req.url || '', 'http://iris.local').searchParams;
+      const page = artifacts.page({ offset: Number(query.get('offset') || 0), limit: Number(query.get('limit') || 24) });
+      return sendJson(res, 200, method === 'HEAD' ? {} : page);
+    }
     const taskMatch = urlPath.match(/^\/iris\/api\/task\/([^/]+)$/);
     if (taskMatch) {
       return serveTaskDetail(taskMatch[1], method, res);
@@ -365,6 +400,37 @@ export function serveApi(req, res, ctx) {
   }
 }
 
+async function serveCoreArtifactMedia(artifactId, method, res) {
+  try {
+    const result = await readCoreArtifactMediaForDsh(artifactId);
+    if (res.writableEnded || res.destroyed) return;
+    res.writeHead(200, {
+      'Content-Type': result.artifact.mediaType,
+      'Content-Length': result.bytes.length,
+      'Content-Disposition': 'inline',
+      'Cache-Control': 'private, max-age=3600',
+      'X-Content-Type-Options': 'nosniff',
+      'Cross-Origin-Resource-Policy': 'same-origin',
+      'Referrer-Policy': 'no-referrer'
+    });
+    res.end(method === 'HEAD' ? undefined : result.bytes);
+  } catch (_) {
+    return sendJson(res, 404, { error: 'not found' });
+  }
+}
+
+async function serveCoreSnapshot(res, options = {}) {
+  try {
+    return sendJson(res, 200, await coreSnapshotForDsh({ limit: options.limit || 12 }));
+  } catch (error) {
+    console.error('[iris] Core 只读快照失败：', error && error.code || 'unknown');
+    return sendJson(res, 409, {
+      schemaVersion: 0, available: true, readOnly: true,
+      error: { code: String(error && error.code || 'IRIS_CORE_SNAPSHOT_FAILED') }
+    });
+  }
+}
+
 function sendJson(res, status, obj) {
   if (res.writableEnded || res.destroyed) return; // 已结束/已销毁的连接不再写（end 后二次 end 防御）
   if (!res.headersSent) res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
@@ -405,21 +471,121 @@ function handleJsonPost(req, res, execute) {
       const result = await execute(body, controller.signal);
       finish(200, result);
     } catch (err) {
-      finish(controller.signal.aborted ? 499 : 400, {
-        error: controller.signal.aborted ? 'request canceled' : String((err && err.message) || err)
+      finish(controller.signal.aborted ? 499 : (Number(err && err.statusCode) || 400), {
+        error: controller.signal.aborted ? 'request canceled' : String((err && err.message) || err),
+        ...(err && err.code ? { code: String(err.code) } : {})
       });
     }
   });
   req.on('error', () => finish(400, { error: 'bad request' }));
 }
 
-function handleAction(ctx, name, req, res) {
-  return handleJsonPost(req, res, (args, signal) => runAction(ctx, name, args, { signal }));
+function handleAction(host, name, req, res) {
+  return handleJsonPost(req, res, (args, signal) => runAction(host, name, args, { signal }));
+}
+
+/**
+ * POST /iris/api/core/task/:id/(reobserve|redeliver) —— D1/D2 人工动作。
+ * 成功返回 200 + 任务最新五类用户投影行；坏 ID/未知/不满足动作门映射为稳定 4xx。
+ * 任何拒绝都在 Provider 调用与 Task 写入之前发生；错误体不含绝对路径、Key、
+ * 供应商身份或 binding。请求体不接受参数（Task ID 只在 URL 里），客户端断开
+ * 经 AbortSignal 传入在途操作，与 GUI actions 同一约定。
+ */
+const CORE_TASK_MANUAL_ACTIONS = Object.freeze({
+  reobserve: { command: 'task.reobserve', run: reobserveProviderTaskForDsh },
+  redeliver: { command: 'task.redeliver', run: redeliverProviderTaskForDsh },
+  cancel: { command: 'task.cancel', run: cancelProviderTaskForDsh },
+  // 注意力处置是 Host 偏好（不写 Core 事实）：acknowledge/restore/hide/unhide。
+  acknowledge: { command: 'attention.acknowledge', run: (input) => disposeCoreTaskAttention({ ...input, action: 'acknowledge' }) },
+  restore: { command: 'attention.restore', run: (input) => disposeCoreTaskAttention({ ...input, action: 'restore' }) },
+  hide: { command: 'attention.hide', run: (input) => disposeCoreTaskAttention({ ...input, action: 'hide' }) },
+  unhide: { command: 'attention.unhide', run: (input) => disposeCoreTaskAttention({ ...input, action: 'unhide' }) }
+});
+
+/**
+ * POST /iris/api/core/task/:id/retry —— D4 人工重试为新任务。
+ * body 必须携带 { prompt, confirmBilling: true, modelRef? }：Core 记录不持久化
+ * Prompt，只能由调用方重新提供；缺显式计费确认在读取旧 Task 之前拒绝。
+ * 成功返回 200 + 新任务的五类用户投影行与 retriedFrom 关系。
+ */
+function handleCoreTaskRetry(taskId, req, res) {
+  if (!/^task_[a-f0-9]{24}$/.test(taskId)) {
+    return sendJson(res, 400, { error: { code: 'IRIS_DSH_TASK_INVALID', message: 'Core Task ID 无效' } });
+  }
+  handleJsonPost(req, res, async (body, signal) => {
+    try {
+      if (!body || body.confirmBilling !== true) {
+        const error = new Error('重试会创建新任务并可能产生重复生成费用；请求体必须显式 confirmBilling:true');
+        error.code = 'IRIS_COMMAND_BILLING_CONFIRM_REQUIRED';
+        error.statusCode = 400;
+        throw error;
+      }
+      const prompt = String(body.prompt || '');
+      const result = await retryProviderTaskForDsh({
+        taskId,
+        prompt,
+        ...(body.text !== undefined ? { text: String(body.text) } : {}),
+        ...(body.voice !== undefined ? { voice: String(body.voice) } : {}),
+        ...(body.audio_url !== undefined ? { audio_url: String(body.audio_url) } : {}),
+        modelRef: typeof body.modelRef === 'string' && body.modelRef.trim() ? body.modelRef.trim() : undefined,
+        confirmBilling: true,
+        signal
+      });
+      return {
+        ok: true,
+        contractVersion: 0,
+        command: 'task.retry',
+        retriedFrom: result.retriedFrom,
+        task: result.row
+      };
+    } catch (error) {
+      const code = String(error && error.code || '');
+      error.statusCode = Number(error.statusCode)
+        || (code === 'IRIS_TASK_NOT_FOUND' ? 404
+          : (code === 'IRIS_TASK_NOT_RETRYABLE' || code.startsWith('IRIS_PROVIDER_')) ? 409
+          : 400);
+      throw error;
+    }
+  });
+}
+
+function handleCoreTaskManual(action, taskId, req, res) {
+  if (!/^task_[a-f0-9]{24}$/.test(taskId)) {
+    return sendJson(res, 400, { error: { code: 'IRIS_DSH_TASK_INVALID', message: 'Core Task ID 无效' } });
+  }
+  const entry = CORE_TASK_MANUAL_ACTIONS[action];
+  if (!entry) return sendJson(res, 404, { error: 'not found' });
+  const controller = new AbortController();
+  let completed = false;
+  const finish = (status, body) => {
+    if (completed) return;
+    completed = true;
+    sendJson(res, status, body);
+  };
+  const disconnect = () => { if (!completed) controller.abort(); };
+  if (typeof req.on === 'function') req.on('aborted', disconnect);
+  if (typeof res.on === 'function') res.on('close', disconnect);
+  if (typeof req.resume === 'function') req.resume(); // 无 body 入参；避免小请求体滞留
+  entry.run({ taskId, signal: controller.signal })
+    .then((result) => finish(200, {
+      ok: true,
+      contractVersion: 0,
+      command: entry.command,
+      task: result.row
+    }))
+    .catch((error) => {
+      const code = String(error && error.code || 'IRIS_CORE_MANUAL_ACTION_FAILED');
+      const status = controller.signal.aborted ? 499
+        : code === 'IRIS_TASK_NOT_FOUND' ? 404
+        : (code === 'IRIS_TASK_ID_INVALID' || code === 'IRIS_DSH_TASK_INVALID') ? 400
+        : 409;
+      finish(status, { error: { code, message: String((error && error.message) || '无法执行 Core Task 动作') } });
+    });
 }
 
-function handlePromptOptimizer(ctx, operation, req, res) {
+function handlePromptOptimizer(host, operation, req, res) {
   return handleJsonPost(req, res, async (body, signal) => {
-    if (operation === 'optimize') return optimizePrompt(ctx, body, { signal });
+    if (operation === 'optimize') return optimizePrompt(host, body, { signal });
     if (operation === 'import') {
       const imported = body && body.config !== undefined ? body.config : body;
       return { ok: true, ...importPromptOptimizerConfig(imported) };

package/lib/artifacts.js

@@ -0,0 +1,239 @@
+'use strict';
+/**
+ * Iris 作品库 v0。
+ *
+ * 任务历史与作品生命周期相互独立：清除 tasks.json 不会让 outputs/ 中的作品
+ * 从 UI 消失。这里只记录展示、分页和随机令牌授权所需的最小字段，不保留
+ * prompt、Provider、Model 或任务关系；完整 Artifact Manifest 留给 0.2.0。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { irisHome } from './config.js';
+import { atomicWritePrivate, chmodPrivateFile, ensurePrivateDir, privateSibling } from './private-storage.js';
+
+const FILE = () => path.join(irisHome(), 'artifacts.json');
+const OUTPUTS = () => path.join(irisHome(), 'outputs');
+const MIME = {
+  '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+  '.mkv': 'video/x-matroska', '.avi': 'video/x-msvideo', '.mpeg': 'video/mpeg', '.mpg': 'video/mpeg',
+  '.wav': 'audio/wav', '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.flac': 'audio/flac',
+  '.avif': 'image/avif', '.bmp': 'image/bmp',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp', '.gif': 'image/gif'
+};
+
+let cache = null;
+const changeListeners = new Set();
+
+export function onChange(fn) {
+  changeListeners.add(fn);
+  return () => changeListeners.delete(fn);
+}
+
+function emitChange() {
+  for (const fn of [...changeListeners]) {
+    try { fn(); } catch (_) { /* 一个监听者不能阻断作品落盘 */ }
+  }
+}
+
+function persist() {
+  atomicWritePrivate(FILE(), JSON.stringify({ version: 1, artifacts: cache.artifacts }, null, 2));
+  emitChange();
+}
+
+function mimeFor(name) {
+  return MIME[path.extname(String(name)).toLowerCase()] || '';
+}
+
+function safeOutputFile(name) {
+  const value = String(name || '');
+  return value && path.basename(value) === value && value !== '.' && value !== '..' && mimeFor(value);
+}
+
+function outputStat(name) {
+  if (!safeOutputFile(name)) return null;
+  const abs = path.join(OUTPUTS(), name);
+  try {
+    const stat = fs.lstatSync(abs);
+    return stat.isFile() && !stat.isSymbolicLink() ? { abs, stat } : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function newEntry(name, stat) {
+  return {
+    id: 'a_' + crypto.randomBytes(12).toString('hex'),
+    file: name,
+    token: crypto.randomBytes(16).toString('hex'),
+    mime: mimeFor(name),
+    size: stat.size,
+    createdAt: new Date(stat.mtimeMs || Date.now()).toISOString()
+  };
+}
+
+function validateStored(value) {
+  if (!value || typeof value !== 'object' || !Array.isArray(value.artifacts)) throw new Error('artifacts 必须是数组');
+  const ids = new Set();
+  const files = new Set();
+  for (const item of value.artifacts) {
+    if (!item || typeof item !== 'object' || !String(item.id || '').startsWith('a_')
+      || !/^[a-f0-9]{32}$/.test(String(item.token || '')) || !safeOutputFile(item.file)) {
+      throw new Error('作品条目格式无效');
+    }
+    if (ids.has(item.id) || files.has(item.file)) throw new Error('作品条目重复');
+    ids.add(item.id);
+    files.add(item.file);
+  }
+}
+
+function adoptOutputs() {
+  ensurePrivateDir(OUTPUTS());
+  const known = new Set(cache.artifacts.map((item) => item.file));
+  let added = 0;
+  for (const name of fs.readdirSync(OUTPUTS())) {
+    if (known.has(name)) continue;
+    const hit = outputStat(name);
+    if (!hit) continue;
+    cache.artifacts.push(newEntry(name, hit.stat));
+    known.add(name);
+    added++;
+  }
+  return added;
+}
+
+function load() {
+  if (cache) return cache;
+  const file = FILE();
+  if (!fs.existsSync(file)) {
+    cache = { version: 1, artifacts: [] };
+    adoptOutputs(); // 升级时一次性接回现有 outputs；不读取任务历史。
+    persist();
+    return cache;
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    validateStored(raw);
+    cache = { version: 1, artifacts: raw.artifacts.map((item) => ({ ...item })) };
+  } catch (error) {
+    const backup = privateSibling(file, 'corrupted');
+    try {
+      fs.renameSync(file, backup);
+      chmodPrivateFile(backup);
+    } catch (_) { /* 隔离失败仍继续用文件重建最小索引 */ }
+    console.error('[iris] artifacts.json 已损坏，已隔离为 ' + backup + '：', error && error.message);
+    cache = { version: 1, artifacts: [] };
+    adoptOutputs();
+    persist();
+  }
+  return cache;
+}
+
+export function resetCache() {
+  cache = null;
+}
+
+export function all() {
+  return [...load().artifacts].sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+
+export function artifactUrl(entry) {
+  const base = String(process.env.DSH_WEB_BASE || 'http://127.0.0.1:3080').replace(/\/+$/, '');
+  return `${base}/iris/media/artifact/${entry.id}/${entry.token}/${encodeURIComponent(entry.file)}`;
+}
+
+function publicEntry(item) {
+  return {
+    id: item.id,
+    file: item.file,
+    mime: item.mime || mimeFor(item.file),
+    size: Number(item.size || 0),
+    createdAt: item.createdAt || '',
+    url: artifactUrl(item)
+  };
+}
+
+export function page({ offset = 0, limit = 24 } = {}) {
+  const sorted = all();
+  const start = Math.max(0, Number.isFinite(Number(offset)) ? Math.trunc(Number(offset)) : 0);
+  const size = Math.max(1, Math.min(60, Number.isFinite(Number(limit)) ? Math.trunc(Number(limit)) : 24));
+  return { total: sorted.length, offset: start, limit: size, items: sorted.slice(start, start + size).map(publicEntry) };
+}
+
+export function register(absPath) {
+  const resolved = path.resolve(String(absPath || ''));
+  if (path.dirname(resolved) !== path.resolve(OUTPUTS())) throw new Error('作品必须位于 Iris outputs/');
+  const name = path.basename(resolved);
+  const hit = outputStat(name);
+  if (!hit) throw new Error('作品文件不存在、类型不受支持或不是普通文件');
+  const data = load();
+  const existing = data.artifacts.find((item) => item.file === name);
+  if (existing) {
+    if (existing.size !== hit.stat.size || existing.mime !== mimeFor(name)) {
+      existing.size = hit.stat.size;
+      existing.mime = mimeFor(name);
+      persist();
+    }
+    return publicEntry(existing);
+  }
+  const entry = newEntry(name, hit.stat);
+  data.artifacts.push(entry);
+  persist();
+  return publicEntry(entry);
+}
+
+export function reindex() {
+  const data = load();
+  const before = data.artifacts.length;
+  data.artifacts = data.artifacts.filter((item) => outputStat(item.file));
+  const missing = before - data.artifacts.length;
+  const added = adoptOutputs();
+  if (missing || added) persist();
+  return { added, missing, total: data.artifacts.length };
+}
+
+export function authorize(id, token, name) {
+  const item = load().artifacts.find((entry) => entry.id === id && entry.token === token && entry.file === name);
+  if (!item) return null;
+  const hit = outputStat(item.file);
+  if (!hit) return null;
+  return { entry: item, abs: hit.abs, size: hit.stat.size };
+}
+
+export function remove(id) {
+  const data = load();
+  const index = data.artifacts.findIndex((item) => item.id === id);
+  if (index < 0) return { ok: false, reason: '作品不存在' };
+  const item = data.artifacts[index];
+  const hit = outputStat(item.file);
+  if (hit) fs.rmSync(hit.abs);
+  data.artifacts.splice(index, 1);
+  persist();
+  return { ok: true, file: item.file };
+}
+
+export function clear() {
+  const data = load();
+  const kept = [];
+  let deleted = 0;
+  let bytes = 0;
+  for (const item of data.artifacts) {
+    const hit = outputStat(item.file);
+    try {
+      if (hit) {
+        fs.rmSync(hit.abs);
+        bytes += hit.stat.size;
+      }
+      deleted++;
+    } catch (_) {
+      kept.push(item);
+    }
+  }
+  if (deleted) {
+    data.artifacts = kept;
+    persist();
+  }
+  return { deleted, failed: kept.length, bytes };
+}