@mokuyoaxis/dsh-iris 0.2.1 → 0.2.3

package/lib/core-runtime.js

@@ -12,36 +12,20 @@ import {
   normalizeCoreOptions,
   transitionCoreLifecycle
 } from './core-contract.js';
-import { ensurePrivateDir, writePrivateFile } from './private-storage.js';
-
-const WRITER_LEASE_DIR = '.iris-runtime-writer-v0';
-const WRITER_OWNER_FILE = 'owner.json';
+import { ensurePrivateDir } from './private-storage.js';
+import { WRITER_LEASE_DIR, WRITER_INTENT_FILE, publishLeaseRecord, readWriterLease,
+  removeWriterIntent, retireLeaseDirectory, writerOwnerStatus } from './core-writer-lease.js';
 
 /** 只读租约证据；PID 缺失不等于已经获准恢复，绝不自动夺取租约。 */
 export function inspectCoreWriterLease(dataRoot) {
   const options = normalizeCoreOptions({ dataRoot, mode: 'reader' });
-  const directory = path.join(options.dataRoot, WRITER_LEASE_DIR);
-  let stat;
-  try { stat = fs.lstatSync(directory); }
-  catch (error) { return { status: error?.code === 'ENOENT' ? 'absent' : 'invalid' }; }
   try {
-    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('invalid lease');
-    const entries = fs.readdirSync(directory);
-    if (entries.length !== 1 || entries[0] !== WRITER_OWNER_FILE) throw new Error('invalid contents');
-    const ownerFile = path.join(directory, WRITER_OWNER_FILE);
-    const ownerStat = fs.lstatSync(ownerFile);
-    if (!ownerStat.isFile() || ownerStat.isSymbolicLink() || ownerStat.size > 16384) throw new Error('invalid owner');
-    const owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'));
-    const created = Date.parse(owner?.createdAt);
-    if (owner?.contractVersion !== CORE_CONTRACT_VERSION || !Number.isSafeInteger(owner.pid) || owner.pid <= 0
-        || !/^[a-f0-9-]{36}$/.test(String(owner.instanceId || '')) || !Number.isFinite(created)) {
-      throw new Error('incomplete owner');
-    }
-    let ownerStatus = 'alive';
-    try { process.kill(owner.pid, 0); }
-    catch (error) { ownerStatus = error?.code === 'ESRCH' ? 'missing' : 'unknown'; }
+    const lease = readWriterLease(options.dataRoot);
+    if (!lease) return { status: 'absent' };
+    const owner = lease.owner;
+    const created = Date.parse(owner.createdAt);
     return {
-      status: 'present', ownerStatus, pid: owner.pid,
+      status: 'present', ownerStatus: writerOwnerStatus(owner.pid), pid: owner.pid, phase: lease.phase,
       createdAt: new Date(created).toISOString(), ageMs: Math.max(0, Date.now() - created)
     };
   } catch (_) { return { status: 'invalid' }; }
@@ -77,56 +61,70 @@ function physicalDataRoot(options) {
 
 function acquireWriterLease(root, instanceId) {
   const directory = path.join(root, WRITER_LEASE_DIR);
-  const ownerFile = path.join(directory, WRITER_OWNER_FILE);
+  const ownerFile = path.join(directory, 'owner.json');
+  const intentFile = path.join(root, WRITER_INTENT_FILE);
   try {
-    fs.mkdirSync(directory, { mode: 0o700 });
+    fs.lstatSync(directory);
+    throw coreDataRootBusyError();
   } catch (error) {
-    if (error && error.code === 'EEXIST') throw coreDataRootBusyError();
-    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法取得 Iris 数据根写者租约');
+    if (error?.code !== 'ENOENT') {
+      if (error instanceof CoreContractError) throw error;
+      throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法检查 Iris 数据根写者租约');
+    }
   }
-
   const owner = Object.freeze({
     contractVersion: CORE_CONTRACT_VERSION,
     instanceId,
     pid: process.pid,
     createdAt: new Date().toISOString()
   });
-  const serialized = JSON.stringify(owner, null, 2) + '\n';
   try {
-    writePrivateFile(ownerFile, serialized, { flag: 'wx' });
-  } catch (_) {
-    try { fs.unlinkSync(ownerFile); } catch (_) { /* owner 文件可能尚未建立 */ }
-    try { fs.rmdirSync(directory); } catch (_) { /* 保留不确定租约比误删安全 */ }
+    // 创建目录之前已有完整 owner；SIGKILL 不会留下无法确认 PID 的新空锁。
+    publishLeaseRecord(root, intentFile, owner);
+  } catch (error) {
+    if (error?.code === 'EEXIST') throw coreDataRootBusyError();
     throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法记录 Iris 数据根写者租约');
   }
-  return Object.freeze({ directory, ownerFile, owner, serialized });
+  let madeDirectory = false;
+  try {
+    fs.mkdirSync(directory, { mode: 0o700 });
+    madeDirectory = true;
+    fs.linkSync(intentFile, ownerFile);
+    return Object.freeze({ root, directory, ownerFile, owner, evidence: readWriterLease(root) });
+  } catch (error) {
+    // 仅撤回本次创建的空目录和意图；不碰其他 writer 或未知目录内容。
+    let withdrawn = !madeDirectory;
+    if (madeDirectory) {
+      try { fs.rmdirSync(directory); withdrawn = true; } catch (_) { /* owner/目录证据保留 */ }
+    }
+    if (withdrawn) { try { fs.unlinkSync(intentFile); } catch (_) { /* 保留 owner 供显式恢复 */ } }
+    if (error?.code === 'EEXIST') throw coreDataRootBusyError();
+    throw coreError('IRIS_CORE_DATA_ROOT_UNAVAILABLE', '无法取得 Iris 数据根写者租约');
+  }
 }
 
 function releaseWriterLease(lease) {
   let actual;
   try {
-    const stat = fs.lstatSync(lease.directory);
-    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('lease is not a directory');
-    const entries = fs.readdirSync(lease.directory);
-    if (entries.length !== 1 || entries[0] !== WRITER_OWNER_FILE) throw new Error('unexpected lease contents');
-    actual = JSON.parse(fs.readFileSync(lease.ownerFile, 'utf8'));
+    actual = readWriterLease(lease.root);
+    if (!actual || actual.fingerprint !== lease.evidence.fingerprint || actual.phase !== 'owned') throw new Error('lease changed');
   } catch (_) {
     throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约无法安全释放；已保留现场');
   }
-  if (actual.instanceId !== lease.owner.instanceId) {
+  if (actual.owner.instanceId !== lease.owner.instanceId) {
     throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约所有者不匹配；已保留现场');
   }
 
+  const retired = path.join(lease.root, WRITER_LEASE_DIR + '.released-' + lease.owner.instanceId);
   try {
-    fs.unlinkSync(lease.ownerFile);
-    fs.rmdirSync(lease.directory);
+    // 整体移开非空目录；owner 从不在占位目录中先被删除。
+    retireLeaseDirectory(lease.directory, retired);
+    removeWriterIntent(actual);
   } catch (_) {
-    // 若目录删除失败，尽力恢复 owner 证据；绝不把仍不确定的根宣布为可写。
-    if (fs.existsSync(lease.directory) && !fs.existsSync(lease.ownerFile)) {
-      try { writePrivateFile(lease.ownerFile, lease.serialized, { flag: 'wx' }); } catch (_) { /* 保持失败 */ }
-    }
     throw coreError('IRIS_CORE_LEASE_INVALID', 'Iris 写者租约释放失败；已保留现场');
   }
+  // 退役目录已不占有租约。中断或清理失败只留下可读证据，不阻止后续 writer。
+  try { fs.unlinkSync(path.join(retired, 'owner.json')); fs.rmdirSync(retired); } catch (_) { /* 保留退役现场 */ }
 }
 
 function runtimeSnapshot(options, lifecycle, hasLease, inFlight) {

package/lib/core-tasks.js

@@ -7,6 +7,7 @@ import { atomicWritePrivate, ensurePrivateDir } from './private-storage.js';
 import { parseModelRef } from './models.js';
 import { providerErrorRecord } from './provider-contract.js';
 import { deriveLegacyStatus, semanticViolations } from './task-semantics.js';
+import { readDeliveryCache } from './core-delivery-cache.js';
 
 const STORE_DIR = 'task-store';
 const STORE_VERSION = 'v0';
@@ -14,7 +15,7 @@ const TASK_ID = /^task_[a-f0-9]{24}$/;
 const ARTIFACT_ID = /^artifact_[a-f0-9]{24}$/;
 const ATTEMPT_ID = /^attempt_[a-f0-9]{24}$/;
 const PROVIDER_BINDING = /^sha256:[a-f0-9]{64}$/;
-const CAPABILITIES = new Set(['image', 'video', 'tts', 'transcribe']);
+const CAPABILITIES = new Set(['image', 'video', 'tts', 'music', 'transcribe']);
 const ATTEMPT_SELECTION_REASONS = new Set(['explicit', 'assignment', 'pool']);
 const ATTEMPT_STAGE_TIMESTAMPS = Object.freeze([
   'queuedAt', 'submitStartedAt', 'submittedAt', 'remoteCompletedAt',
@@ -106,6 +107,7 @@ function validateRecord(record, expectedId) {
       || !Array.isArray(record.attempts) || !Array.isArray(record.artifactIds)
       || !Number.isSafeInteger(record.revision) || record.revision < 1
       || typeof record.createdAt !== 'string' || typeof record.updatedAt !== 'string'
+      || (record.deliveryCache !== undefined && record.deliveryCache !== true)
       || (record.providerBinding !== undefined && !PROVIDER_BINDING.test(record.providerBinding))
       || (record.retriedFrom !== undefined && !TASK_ID.test(record.retriedFrom))
       || (record.sourceArtifactId !== undefined && (record.capability !== 'image' || !ARTIFACT_ID.test(record.sourceArtifactId)))) {
@@ -292,6 +294,7 @@ export function beginCoreAttempt(dataRoot, taskId, fields = {}) {
     task.deliveryState = 'none';
     task.cancelState = 'none';
     delete task.remoteTaskId;
+    delete task.deliveryCache;
     delete task.lastError;
   });
   return Object.freeze(clone(created));
@@ -327,6 +330,7 @@ export function recordCoreAttemptResult(dataRoot, taskId, snapshot) {
       task.phase = 'running';
       task.outcome = 'succeeded';
       task.deliveryState = 'pending';
+      if (snapshot.deliveryCache === true) task.deliveryCache = true;
     }
     if (snapshot.remoteTaskId) task.remoteTaskId = String(snapshot.remoteTaskId);
     if (attempt.error) task.lastError = attempt.error;
@@ -436,7 +440,7 @@ export function recordCoreDownloadCompleted(dataRoot, taskId) {
 
 export function prepareCoreRedelivery(dataRoot, taskId) {
   return mutate(dataRoot, taskId, (task) => {
-    if (task.outcome !== 'succeeded' || task.deliveryState !== 'failed' || !task.remoteTaskId) {
+    if (task.outcome !== 'succeeded' || task.deliveryState !== 'failed' || (!task.remoteTaskId && !task.deliveryCache)) {
       fail('IRIS_TASK_NOT_REDELIVERABLE', 'Task 不处于可重新交付状态');
     }
     task.phase = 'running';
@@ -515,11 +519,21 @@ export function recordCoreCancelResult(dataRoot, taskId, result) {
 }
 
 /**
- * 进程在 submit 返回落盘前退出时，没有 remoteTaskId 可以安全观察；恢复只能把
- * 事实收口为受理未知。已经落盘 remoteTaskId 的任务保持可观察，绝不新建 Attempt。
+ * 同步完整缓存可补回尚未落盘的完成事实；否则提交中断仍收口为受理未知。
+ * 已有 remoteTaskId 的任务保持可观察。恢复不重新提交，也不自动交付缓存。
  */
 export function recoverCoreTask(dataRoot, taskId) {
-  const current = readRecord(dataRoot, taskId);
+  let current = readRecord(dataRoot, taskId);
+  if (current.phase === 'submitting' && current.acceptance === 'none') {
+    const cache = readDeliveryCache(dataRoot, current, { allowAbsent: true });
+    if (cache) {
+      recordCoreAttemptResult(dataRoot, taskId, {
+        id: cache.attemptId, providerId: cache.providerId, model: cache.modelRef,
+        acceptance: 'accepted', resultKind: 'completed', deliveryCache: true
+      });
+      current = readRecord(dataRoot, taskId);
+    }
+  }
   if (current.cancelState === 'requested') {
     return mutate(dataRoot, taskId, (task) => {
       task.phase = 'terminal';

package/lib/core-user-projection.js

@@ -79,7 +79,7 @@ export function coreTaskObservable(task) {
 }
 
 /**
- * 与 task.redeliver 同一组交付事实门：远端已成功、产物取回失败、远端 ID 仍在。
+ * 与 task.redeliver 同一组交付事实门：远端已成功、交付失败，有远端 ID 或同步缓存。
  * 只读持久化事实轴，不解析 Provider、不接触网络；binding 与能力校验仍在
  * Command Service。五类状态里只有 delivery_failed 会标记 redeliverable。
  */
@@ -87,7 +87,7 @@ 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());
+    && (Boolean(String(task.remoteTaskId || '').trim()) || task.deliveryCache === true);
 }
 
 /**

package/lib/core-writer-lease.js

@@ -0,0 +1,134 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CORE_CONTRACT_VERSION } from './core-contract.js';
+import { privateSibling } from './private-storage.js';
+
+export const WRITER_LEASE_DIR = '.iris-runtime-writer-v0';
+export const WRITER_INTENT_FILE = '.iris-runtime-writer-v0.owner.json';
+export function recoveryClaimFile(root, owner) {
+  return path.join(root, WRITER_LEASE_DIR + '.recovery-' + owner.instanceId + '.json');
+}
+const UUID = /^[a-f0-9-]{36}$/;
+const STALE = /^\.owner\.stale-([a-f0-9-]{36})\.json$/;
+
+export function writerOwnerStatus(pid) {
+  try { process.kill(pid, 0); return 'alive'; }
+  catch (error) { return error?.code === 'ESRCH' ? 'missing' : 'unknown'; }
+}
+
+export function newWriterOwner() {
+  return { contractVersion: CORE_CONTRACT_VERSION, instanceId: crypto.randomUUID(),
+    pid: process.pid, createdAt: new Date().toISOString() };
+}
+
+function checkedOwner(owner) {
+  if (owner?.contractVersion !== CORE_CONTRACT_VERSION || !Number.isSafeInteger(owner.pid) || owner.pid <= 0
+      || !UUID.test(String(owner.instanceId || '')) || !Number.isFinite(Date.parse(owner.createdAt))) {
+    throw new Error('incomplete owner');
+  }
+  return owner;
+}
+
+function readRecord(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384) throw new Error('invalid lease record');
+  const serialized = fs.readFileSync(file, 'utf8');
+  return { serialized, value: JSON.parse(serialized) };
+}
+
+function optionalRecord(file) {
+  try { return readRecord(file); }
+  catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+}
+
+/** 完整私有记录先在根中准备，再以 hard link 原子发布；已有目标绝不覆盖。 */
+export function publishLeaseRecord(root, target, value) {
+  const prepared = privateSibling(path.join(root, WRITER_INTENT_FILE), 'prepare');
+  let created = false;
+  try {
+    fs.writeFileSync(prepared, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    created = true;
+    fs.linkSync(prepared, target);
+  } finally {
+    if (created) { try { fs.unlinkSync(prepared); } catch (_) { /* 未发布的准备文件不占有租约 */ } }
+  }
+}
+
+export function withdrawLeaseRecord(target, value) {
+  if (readRecord(target).serialized !== JSON.stringify(value, null, 2) + '\n') throw new Error('published record changed');
+  fs.unlinkSync(target);
+}
+
+export function retireLeaseDirectory(source, target) {
+  try { fs.lstatSync(target); throw new Error('retirement destination already exists'); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  fs.renameSync(source, target);
+}
+
+/** 只读识别完整 owner、创建/释放意图及恢复链；未知内容和缺失证据拒绝。 */
+export function readWriterLease(root) {
+  const directory = path.join(root, WRITER_LEASE_DIR);
+  const intentFile = path.join(root, WRITER_INTENT_FILE);
+  const intent = optionalRecord(intentFile);
+  if (intent) checkedOwner(intent.value);
+  let stat;
+  try { stat = fs.lstatSync(directory); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  if (!stat && !intent) return null;
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error('invalid lease directory');
+  const entries = stat ? fs.readdirSync(directory).sort() : [];
+  const records = new Map();
+  for (const name of entries) {
+    if (name !== 'owner.json' && !STALE.test(name)) throw new Error('unexpected lease contents');
+    records.set(name, readRecord(path.join(directory, name)));
+  }
+  const ownerRecord = records.get('owner.json');
+  if (ownerRecord) checkedOwner(ownerRecord.value);
+  const staleRecords = entries.filter(name => STALE.test(name));
+  if (staleRecords.length > 1) throw new Error('ambiguous legacy recovery');
+  const staleRecord = staleRecords.length ? records.get(staleRecords[0]) : null;
+  if (staleRecord) checkedOwner(staleRecord.value);
+  if (staleRecord && !ownerRecord) throw new Error('legacy recovery PID unknown');
+  if (intent && ownerRecord && ownerRecord.serialized !== intent.serialized) {
+    throw new Error('intent owner mismatch');
+  }
+  if (staleRecord && ownerRecord && STALE.exec(staleRecords[0])[1] !== ownerRecord.value.instanceId) {
+    throw new Error('legacy recovery owner mismatch');
+  }
+  const original = staleRecord || ownerRecord || intent;
+  if (!original) throw new Error('owner evidence missing');
+  let owner = (ownerRecord || original).value;
+  const owners = [original.value];
+  if (owner.instanceId !== original.value.instanceId) owners.push(owner);
+  const claims = [];
+  for (;;) {
+    const file = recoveryClaimFile(root, owner);
+    const record = optionalRecord(file);
+    if (!record) break;
+    const claim = record.value;
+    if (claim?.schemaVersion !== 1 || claim.previousInstanceId !== owner.instanceId) throw new Error('invalid recovery claim');
+    claims.push({ file, ...record });
+    owner = checkedOwner(claim.owner);
+    if (owners.some(previous => previous.instanceId === owner.instanceId)) throw new Error('cyclic recovery chain');
+    owners.push(owner);
+    if (owners.length > 64) throw new Error('recovery chain too long');
+  }
+  const phase = owners.length > 1 || staleRecord ? 'recovering' : ownerRecord ? 'owned' : 'pending';
+  const fingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    identity: stat ? [stat.dev, stat.ino] : null, intent: intent?.serialized,
+    records: [...records].map(([name, record]) => [name, record.serialized]),
+    claims: claims.map(record => [path.basename(record.file), record.serialized])
+  })).digest('hex');
+  return { directory, intentFile, intent, stat, entries, records, claims, owner, owners,
+    originalOwner: original.value, phase, fingerprint };
+}
+
+export function removeWriterIntent(lease) {
+  if (!lease.intent) return;
+  const actual = readRecord(lease.intentFile);
+  if (actual.serialized !== lease.intent.serialized) throw new Error('intent changed');
+  fs.unlinkSync(lease.intentFile);
+}

package/lib/dsh-core-adapter.js

@@ -2,7 +2,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { allProviders, irisHome, recordRateLimit } from './config.js';
+import { allProviders, assignments, irisHome, recordRateLimit } from './config.js';
 import { createCommandService } from './command-service.js';
 import { createCoreArtifact, inspectCoreArtifact, listCoreArtifacts, listCoreArtifactMetadata, readCoreArtifactBytes } from './core-artifacts.js';
 import { createCoreRuntime } from './core-runtime.js';
@@ -15,7 +15,8 @@ import { requireHostPort } from './host-contract.js';
 import { createProviderTaskRunner } from './provider-task-runner.js';
 import { createConfiguredProviderAdapter as createProviderAdapter } from './provider-adapters.js';
 import { parseModelRef } from './models.js';
-import { imageCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from './provider-catalog.js';
+import { imageCandidatesFromCatalog, musicCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from './provider-catalog.js';
+import { generateMusicTask } from './music-generation.js';
 
 let writerTail = Promise.resolve();
 const providerWatchers = new Map();
@@ -179,6 +180,13 @@ export function submitProviderTaskForDsh(input = {}) {
   }), input.signal);
 }
 
+export function submitMusicForDsh(input) {
+  return withWriter(runtime => generateMusicTask({
+    runner: createProviderTaskRunner(runtime), candidates: input.candidates,
+    providerInput: input.providerInput, options: input.musicOptions, signal: input.signal
+  }), input.signal);
+}
+
 /** 单步观察已经受理的 Core Task；不会自动循环，也不会创建第二次 submit。 */
 export function observeProviderTaskForDsh(input = {}) {
   return withWriter((runtime) => createProviderTaskRunner(runtime).observe(
@@ -221,7 +229,7 @@ export function reobserveProviderTaskForDsh(input = {}) {
 
 /**
  * D2 人工 redeliver：只对 outcome=succeeded / deliveryState=failed 的 Task
- * 重新取回远端产物（re-poll 产物清单 → download → 新 Artifact），绝不 submit、
+ * 重新交付原结果（同步读缓存，异步 re-poll → download），绝不 submit、
  * 绝不重新生成。
  */
 export function redeliverProviderTaskForDsh(input = {}) {
@@ -277,12 +285,14 @@ export function retryProviderTaskForDsh(input = {}) {
   return withWriter(async (runtime) => {
     const commands = createCommandService(runtime, {
       resolveTaskCandidates: ({ capability, modelRef }) => {
-        const catalog = { providers: allProviders() };
+        const catalog = { providers: allProviders(), ...(capability === 'music' ? { assignments: assignments() } : {}) };
         const ref = modelRef || undefined;
         const candidates = capability === 'video'
           ? videoCandidatesFromCatalog(catalog, ref)
           : capability === 'tts'
             ? ttsCandidatesFromCatalog(catalog, ref)
+            : capability === 'music'
+              ? musicCandidatesFromCatalog(catalog, ref)
             : capability === 'transcribe'
               ? transcribeCandidatesFromCatalog(catalog, ref)
               : imageCandidatesFromCatalog(catalog, ref);

package/lib/dsh-text-model-adapter.js

@@ -65,7 +65,11 @@ export async function prepareDshTextModelPort(textModel, binding, { signal } = {
       if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
       return textModel.resolveModelInfo(route.provider, route.model, signal);
     }), signal, 'prepare', 'not_invoked'); }
-    catch (_) { if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked'); }
+    catch (_) {
+      if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+      // 查询失败不同于成功查询但能力缺失；不要吞掉错误后进入付费生成。
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+    }
   }
   if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
   return createDshTextModelPort(textModel, { ...route, sessionId }, { metadata });
@@ -73,7 +77,16 @@ export async function prepareDshTextModelPort(textModel, binding, { signal } = {
 
 /** 已绑定事实的纯构造；用于缓存元数据/协议 fixture，不执行元数据查询。 */
 export function createDshTextModelPort(textModel, binding, { metadata } = {}) {
-  return createDshBoundModelPort(textModel, binding, { metadata });
+  const bound = createDshBoundModelPort(textModel, binding, { metadata });
+  const modalities = metadata?.inputModalities;
+  if (modalities !== undefined) {
+    if (!Array.isArray(modalities) || modalities.some(value => typeof value !== 'string' || !value.trim())) {
+      throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'prepare', invocation: 'not_invoked' });
+    }
+    if (!modalities.includes('text')) throw new ModelPortError('IRIS_MODEL_UNSUPPORTED', { stage: 'prepare', invocation: 'not_invoked' });
+  }
+  // 缺失能力只表示未知；宿主接受文本输入也不证明远端必定只返回文字。
+  return Object.freeze({ ...bound, textInput: modalities === undefined ? 'unknown' : 'supported' });
 }
 
 /** 文本与视觉共用经过验证的 DSH 事件读取器；图片桥接仅由视觉适配器注入。 */

package/lib/generation-input.js

@@ -2,11 +2,13 @@
 
 import path from 'node:path';
 import fs from 'node:fs';
+import { normalizeMusicOptions } from './music-options.js';
 
 const FIELDS = Object.freeze({
   image: ['prompt', 'size', 'n', 'source_artifact_id'],
   video: ['prompt', 'size', 'duration', 'img_data_url', 'first_frame_path', 'audio_path', 'resolution'],
   tts: ['text', 'voice'],
+  music: ['prompt', 'timeout_ms', 'retry_502', 'retry_delay_ms'],
   transcribe: ['audio_url', 'audio_path']
 });
 
@@ -47,6 +49,7 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   const providerInput = {};
   let audioPath;
   let sourceArtifactId;
+  let musicOptions;
   let firstFramePath, videoMode;
   if (capability === 'video') {
     audioPath = String(input.audio_path || '').trim();
@@ -101,6 +104,12 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
     const voice = text(input.voice, 'voice', 64);
     if (voice !== undefined) providerInput.voice = voice;
   }
+  if (capability === 'music') {
+    providerInput.prompt = text(input.prompt, 'prompt', 20000, true);
+    try { musicOptions = normalizeMusicOptions(input); }
+    catch (error) { fail(error.message); }
+    providerInput.timeoutMs = musicOptions.timeoutMs;
+  }
   if (capability === 'transcribe') {
     const audioUrl = String(input.audio_url || '').trim();
     audioPath = String(input.audio_path || '').trim();
@@ -119,6 +128,7 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   return Object.freeze({
     modelRef,
     providerInput: Object.freeze(providerInput),
+    ...(musicOptions ? { musicOptions } : {}),
     ...(sourceArtifactId ? { sourceArtifactId } : {}),
     ...(audioPath ? { audioPath } : {}),
     ...(capability === 'video' ? { firstFramePath, videoMode } : {})

package/lib/host-runtime.js

@@ -13,6 +13,7 @@ export const EXPECTED_IRIS_TOOLS = Object.freeze([
   'iris_draw_image',
   'iris_edit_image',
   'iris_generate_video',
+  'iris_generate_music',
   'iris_speak_text',
   'iris_transcribe_audio',
   'iris_task_status',
@@ -28,8 +29,9 @@ export const EXPECTED_IRIS_TOOLS = Object.freeze([
 ]);
 
 export const EXPECTED_IRIS_SKILLS = Object.freeze([
-  'iris-verify-ui',
-  'iris-compose-media'
+  'iris-use',
+  'iris-compose-media',
+  'iris-verify-ui'
 ]);
 
 export const EXPECTED_IRIS_ROUTES = Object.freeze([

package/lib/index.js

@@ -263,7 +263,7 @@ export async function apply(ctx) {
   // 若 webServer 已在运行，inject 回调也会触发；这里兜底立即挂载一次
   guard('媒体路由兜底挂载', () => mountIrisRoutes(ctx));
 
-  // DSH 的 Skill registry 是可选宿主能力。存在时把 npm 包内两项 Skill 注册到
+  // DSH 的 Skill registry 是可选宿主能力。存在时把 npm 包内三项 Skill 注册到
   // 全局层；项目目录中的同名 Skill 仍由 DSH 原生优先级覆盖。
   ctx.inject(['skills'], (skillCtx) => {
     guard('随包 Skill 注册', () => {
@@ -463,10 +463,29 @@ export async function apply(ctx) {
     }
   });
 
+  safeRegister(host, {
+    name: 'iris_generate_music',
+    description: 'Generate music using a model explicitly assigned to Music. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
+    parameters: { type: 'object', properties: {
+      prompt: { type: 'string', description: 'Describe the music, including any lyrics, vocals, mood or intended duration' },
+      model: { type: 'string', description: 'Assigned providerId::modelId reference' },
+      timeout_ms: { type: 'integer', description: 'Per-attempt timeout; default 300000 ms' },
+      retry_502: { type: 'integer', description: '502 regeneration retries, 0–5; default 2; each retry consumes another request' },
+      retry_delay_ms: { type: 'integer', description: 'Delay between 502 retries; default 5000 ms' }
+    }, required: ['prompt'] },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const submitted = await runAction(dshHost(ctx), 'music', args, { signal: exec.signal });
+      return submitted.text + '\nartifact: ' + submitted.artifactIds.join(', ') + '\n' +
+        submitted.artifactIds.map(id => '[♪ 音乐播放](/iris/api/core/artifact/' + encodeURIComponent(id) + '/media)').join('\n');
+    }
+  });
+
   /* ---------- 🔊 语音合成 ---------- */
   safeRegister(host, {
     name: 'iris_speak_text',
-    description: 'Synthesize speech audio from text using the configured TTS model (qwen-tts / compatible). Returns the saved audio file path.',
+    description: 'Synthesize spoken audio from text using the configured TTS model. Returns Core audio Artifact IDs and playback links; export an Artifact to a host file before passing it as audio_path to another tool. Use iris_generate_music for songs or background music.',
     parameters: {
       type: 'object',
       properties: {
@@ -780,7 +799,7 @@ export async function apply(ctx) {
   safeRegister(host, {
     name: 'iris_task_status',
     description:
-      'Query iris generation tasks (image/video/tts). Pass a task_id for one task, or omit it to list the latest tasks with status, progress, errors and output file paths.',
+      'Query Iris tasks (image/video/tts/music/transcription). Pass a task_id for one task, or omit it to list recent tasks. Core results provide Artifact IDs and playback links; legacy tasks may provide file paths. Querying does not re-observe or redeliver a task.',
     parameters: {
       type: 'object',
       properties: {
@@ -1022,7 +1041,7 @@ export async function apply(ctx) {
     }
   });
 
-  console.log('[iris] tools registered: iris_draw_image, iris_edit_image, iris_generate_video, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
+  console.log('[iris] tools registered: iris_draw_image, iris_edit_image, iris_generate_video, iris_generate_music, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
 };
 
 /* ---------------- 视觉路由（M3 补全）：look/relook 共用执行器 + 降级链 ---------------- */