@mokuyoaxis/dsh-iris 0.1.2 → 0.1.4

package/lib/adapters.js

@@ -236,11 +236,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, '查询任务失败');
@@ -323,10 +323,10 @@ export async function openAiGenerateImage({ key, baseUrl, model, prompt, size =
  * 免费只读；返回 [{ id }] 原样（分类由 models.js 规则负责）。
  * @returns {Promise<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 res = await fetch(`${base}/models`, { headers: authHeaders(key), signal: timeoutSignal(timeoutMs, signal) });
   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 : []);
@@ -476,11 +476,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 +499,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

@@ -12,12 +12,17 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { irisHome, capabilitiesOf, onChange as onConfigChange } from './config.js';
+import crypto from 'node:crypto';
+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 { deriveUserState } from './task-semantics.js';
+import { hostDoctor } from './doctor.js';
+import { hostRuntimeEvidence, recordHostClient } from './host-runtime.js';
 import { optimizePrompt } from './prompt-optimizer.js';
 import {
   importPromptOptimizerConfig,
@@ -75,6 +80,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 +103,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 +117,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 +135,35 @@ 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);
+  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 截断）
+      attention: attention.slice(0, 20).map(taskPublic),
       running: running.slice(0, 10).map(taskPublic)
     }
   };
@@ -138,15 +177,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 +245,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();
@@ -214,7 +282,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) {
@@ -239,6 +307,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);
@@ -252,22 +322,26 @@ 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_-]+)\/?$/);
+      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') {
@@ -281,6 +355,15 @@ 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/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);
@@ -349,13 +432,13 @@ function handleJsonPost(req, res, execute) {
   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 }));
 }
 
-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) };
@@ -493,6 +576,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 +590,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/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 };
+}

package/lib/bundled-skills.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { requireHostPort } from './host-contract.js';
 
 const SKILL_NAMES = ['iris-verify-ui', 'iris-compose-media'];
 const SKILL_ROOT = fileURLToPath(new URL('../.dsh/skills/', import.meta.url));
@@ -44,6 +45,7 @@ export function loadBundledSkills() {
       content: source.slice(frontmatter[0].length).replace(/^\r?\n/, ''),
       source: 'bundled',
       provider: 'iris-bundled',
+      invocation: Object.freeze({ modelInvocable: true, userInvocable: true }),
       path: file,
       resourceBase: Object.freeze({ kind: 'directory', path: directory })
     });
@@ -51,11 +53,9 @@ export function loadBundledSkills() {
 }
 
 /** 注册为宿主级 runtime Skill；DSH 项目目录中的同名 Skill 仍按原生优先级胜出。 */
-export function registerBundledSkills(ctx) {
-  const registry = ctx && (ctx.skills || (typeof ctx.get === 'function' && ctx.get('skills')));
-  if (!registry || typeof registry.register !== 'function') {
-    throw new Error('DSH Skill registry 不可用');
-  }
+export function registerBundledSkills(host) {
+  const registry = requireHostPort(host, 'skills', '注册随包 Skill');
+  if (typeof registry.register !== 'function') throw new Error('Host skills 端口缺少 register');
   const skills = loadBundledSkills();
   for (const skill of skills) registry.register(skill);
   return skills.map((skill) => skill.name);