@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/dsh-host-adapter.js

@@ -0,0 +1,240 @@
+'use strict';
+
+/** DSH/Cordis runtime objects are normalized here and nowhere in Iris commands. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { defineHostAdapter } from './host-contract.js';
+import { BrowserHtmlRenderer } from './render.js';
+
+export function detectDshVersion({ entry = process.argv[1] } = {}) {
+  if (!entry) return 'unknown';
+  let resolved = path.resolve(String(entry));
+  try { resolved = fs.realpathSync(resolved); } catch (_) { /* 入口可能尚未物化 */ }
+  let current = path.dirname(resolved);
+  for (let depth = 0; depth < 6; depth++) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(current, 'package.json'), 'utf8'));
+      if (manifest.name === '@deepseek-ai/dsh') return String(manifest.version || 'unknown');
+    } catch (_) { /* 当前层不是 DSH 包根目录 */ }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return 'unknown';
+}
+
+function property(ctx, name) {
+  try { return ctx && ctx[name]; } catch (_) { return undefined; }
+}
+
+function service(ctx, name) {
+  if (ctx && typeof ctx.get === 'function') {
+    try {
+      const value = ctx.get(name);
+      if (value) return value;
+    } catch (_) { /* optional DSH service was not injected */ }
+  }
+  return property(ctx, name);
+}
+
+function unavailableFor(value, reason) {
+  return { kind: value ? 'incompatible' : 'unavailable', reason };
+}
+
+function imageAttachmentDto(ref) {
+  const out = {
+    attachmentId: ref.attachmentId,
+    mediaType: ref.mediaType,
+    name: typeof ref.name === 'string' ? ref.name : ''
+  };
+  // readImage 会核对这三项完整性事实；省略未知值，不从 ID/文件名猜测。
+  for (const key of ['bytes', 'width', 'height']) {
+    if (Number.isSafeInteger(ref[key]) && ref[key] > 0) out[key] = ref[key];
+  }
+  const original = ref.originalDimensions;
+  if (original && Number.isSafeInteger(original.width) && original.width > 0
+      && Number.isSafeInteger(original.height) && original.height > 0) {
+    out.originalDimensions = Object.freeze({ width: original.width, height: original.height });
+  }
+  return Object.freeze(out);
+}
+
+function collectImageAttachments(nodes) {
+  const out = [];
+  const ids = new Set();
+  const seen = new Set();
+  const stack = Array.isArray(nodes) ? [...nodes] : [nodes];
+  let scanned = 0;
+  while (stack.length && scanned < 8000) {
+    const node = stack.pop();
+    scanned++;
+    if (!node || typeof node !== 'object' || seen.has(node)) continue;
+    seen.add(node);
+    const ref = node.attachment && typeof node.attachment === 'object'
+      ? node.attachment
+      : (node.attachmentId && node.mediaType ? node : null);
+    if (ref && typeof ref.attachmentId === 'string'
+        && typeof ref.mediaType === 'string' && ref.mediaType.startsWith('image/')
+        && !ids.has(ref.attachmentId)) {
+      ids.add(ref.attachmentId);
+      out.push(imageAttachmentDto(ref));
+    }
+    for (const value of Object.values(node)) if (value && typeof value === 'object') stack.push(value);
+  }
+  return out;
+}
+
+function registerWithEffect(ctx, registry, definition) {
+  if (typeof ctx.effect === 'function') return ctx.effect(() => registry.register(definition));
+  return registry.register(definition);
+}
+
+function visionRouteError(message) {
+  return Object.assign(new Error(message), { code: 'IRIS_HOST_CAPABILITY_INCOMPATIBLE' });
+}
+
+function dshVisionPort(llm, { defaults, requiresRoute }) {
+  return Object.freeze({
+    id: 'dsh-global',
+    model: '全局视觉模型',
+    async analyze({ question, ref, signal }) {
+      let route = {};
+      if (requiresRoute) {
+        // rc.2 路由检查前就停止取消请求；旧桥接继续由宿主处理 signal，
+        // 其 fallback 语义待共享调用控制迁移时统一。
+        if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error('已取消');
+        const selection = defaults.currentSelection();
+        if (typeof selection?.provider !== 'string' || !selection.provider.trim()
+            || typeof selection?.model !== 'string' || !selection.model.trim()) {
+          throw visionRouteError('DSH 默认模型没有明确路由；请在 Iris 配置视觉模型');
+        }
+        // 默认文本选择只有明确声明 image 输入时才可成为视觉候选。
+        const { provider, model } = selection;
+        const info = await llm.resolveModelInfo(provider, model, signal);
+        if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error('已取消');
+        if (info?.provider !== provider || info?.id !== model || !Array.isArray(info.inputModalities)
+            || !info.inputModalities.includes('image')) {
+          throw visionRouteError('DSH 默认模型未确认支持图片；请在 Iris 配置视觉模型或选择已声明图片输入的宿主模型');
+        }
+        route = { provider, model };
+      }
+      const chunks = [];
+      for await (const chunk of llm.stream({
+        sessionId: undefined,
+        provider: undefined,
+        model: undefined,
+        ...route,
+        signal,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'text', text: question },
+            { type: 'image', attachment: ref }
+          ]
+        }]
+      })) {
+        if (chunk?.type === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
+        // rc.2 的 Runtime 把 Adapter 异常转换为 finish，而不是单独的 error 事件。
+        if (requiresRoute && chunk?.type === 'finish') {
+          if (chunk.reason?.kind === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
+          if (chunk.reason?.kind === 'aborted') throw visionRouteError('DSH 视觉调用已取消');
+        }
+        const text = typeof chunk?.delta === 'string'
+          ? chunk.delta
+          : (chunk?.type === 'text-delta' ? String(chunk.text || '') : '');
+        if (text) chunks.push(text);
+        if (chunks.reduce((sum, item) => sum + item.length, 0) > 6000) break;
+      }
+      return chunks.join('').trim();
+    }
+  });
+}
+
+/** Build a fresh capability snapshot so optional DSH services can arrive after plugin apply(). */
+export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {}) {
+  if (!ctx || typeof ctx !== 'object') throw new TypeError('DSH Host Adapter 需要宿主 ctx');
+  const ports = {};
+  const unavailable = {};
+
+  const attachments = service(ctx, 'attachments');
+  if (attachments && typeof attachments.saveImage === 'function' && typeof attachments.readImage === 'function') {
+    ports.attachments = Object.freeze({
+      saveImage: (input) => attachments.saveImage(input),
+      readImage: (ref, signal) => attachments.readImage(ref, signal)
+    });
+  } else unavailable.attachments = unavailableFor(attachments, 'DSH attachments 需要 saveImage/readImage');
+
+  const browser = service(ctx, 'browser');
+  if (browser && ['open', 'openUrl', 'screenshot', 'close'].every((name) => typeof browser[name] === 'function')) {
+    const renderer = new BrowserHtmlRenderer({ browser });
+    ports.browser = Object.freeze({
+      async renderHtml(input) {
+        const { png } = await renderer.render(input);
+        return { bytes: new Uint8Array(png), mediaType: 'image/png' };
+      }
+    });
+  } else unavailable.browser = unavailableFor(browser, 'DSH browser 需要 open/openUrl/screenshot/close');
+
+  const slots = service(ctx, 'slots');
+  if (slots && typeof slots.inject === 'function' && typeof slots.register === 'function') {
+    ports.clientSlots = Object.freeze({
+      inject: (seat, callback) => slots.inject(seat, callback),
+      register: (definition, component) => slots.register(definition, component)
+    });
+  } else unavailable.clientSlots = unavailableFor(slots, 'DSH client slots 需要 inject/register');
+
+  const routes = service(ctx, 'webServer') || service(ctx, 'httpServer');
+  if (routes && typeof routes.register === 'function') {
+    ports.routes = Object.freeze({ register: (definition) => routes.register(definition) });
+  } else unavailable.routes = unavailableFor(routes, 'DSH webServer/httpServer 需要 register');
+
+  const sessions = service(ctx, 'sessionQuery');
+  if (sessions && typeof sessions.readSession === 'function') {
+    ports.sessions = Object.freeze({
+      readSession: (id) => sessions.readSession(id),
+      async listImageAttachments(id) {
+        const record = await sessions.readSession(id);
+        return collectImageAttachments(record && record.events);
+      },
+      async findImageAttachment(id, attachmentId) {
+        return (await this.listImageAttachments(id)).find((item) => item.attachmentId === attachmentId) || null;
+      }
+    });
+  } else unavailable.sessions = unavailableFor(sessions, 'DSH sessionQuery 需要 readSession');
+
+  const skills = service(ctx, 'skills');
+  if (skills && typeof skills.register === 'function') {
+    ports.skills = Object.freeze({ register: (definition) => registerWithEffect(ctx, skills, definition) });
+  } else unavailable.skills = unavailableFor(skills, 'DSH Skill registry 需要 register');
+
+  const llm = service(ctx, 'llm');
+  const defaults = service(ctx, 'agentDefaultModel');
+  if (llm && typeof llm.stream === 'function') {
+    ports.textModel = Object.freeze({
+      stream: (request) => llm.stream(request),
+      resolveModelInfo: typeof llm.resolveModelInfo === 'function'
+        ? (provider, model, signal) => llm.resolveModelInfo(provider, model, signal)
+        : undefined,
+      currentSelection: defaults && typeof defaults.currentSelection === 'function'
+        ? () => defaults.currentSelection()
+        : () => null
+    });
+    const requiresRoute = /^0\.2\./.test(version);
+    if (!requiresRoute || defaults && typeof defaults.currentSelection === 'function'
+        && typeof llm.resolveModelInfo === 'function') {
+      ports.visionModel = dshVisionPort(llm, { defaults, requiresRoute });
+    } else unavailable.visionModel = {
+      kind: 'unavailable', reason: 'DSH 0.2 视觉桥接需要默认模型选择和精确图片能力元数据'
+    };
+  } else {
+    unavailable.textModel = unavailableFor(llm, 'DSH llm 需要 stream');
+    unavailable.visionModel = unavailableFor(llm, 'DSH llm 需要 stream');
+  }
+
+  const tools = service(ctx, 'tools');
+  if (tools && typeof tools.register === 'function') {
+    ports.tools = Object.freeze({ register: (definition) => registerWithEffect(ctx, tools, definition) });
+  } else unavailable.tools = unavailableFor(tools, 'DSH tools 需要 register');
+
+  return defineHostAdapter({ id: 'deepseek-harness', version, ports, unavailable });
+}

package/lib/generation-input.js

@@ -0,0 +1,95 @@
+'use strict';
+
+import path from 'node:path';
+
+const FIELDS = Object.freeze({
+  image: ['prompt', 'size', 'n'],
+  video: ['prompt', 'size', 'duration', 'img_data_url'],
+  tts: ['text', 'voice'],
+  transcribe: ['audio_url', 'audio_path']
+});
+
+export class GenerationInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GenerationInputError';
+    this.code = 'IRIS_GENERATION_INPUT_INVALID';
+  }
+}
+
+function fail(message) { throw new GenerationInputError(message); }
+
+function text(value, field, maxLength, required = false) {
+  if (value === undefined && !required) return undefined;
+  const normalized = String(value || '').trim();
+  if (!normalized || normalized.length > maxLength) {
+    fail(`${field} 必须为 1–${maxLength} 字符`);
+  }
+  return normalized;
+}
+
+/**
+ * CLI、DSH 与知情重试共用的纯输入边界。只校验/转换调用方重新提供的参数，
+ * 不读取配置或文件，不上传，不从旧 Task 恢复 Prompt/媒体地址。
+ * Host 附件解析和本地音频上传仍由入口负责。
+ */
+export function normalizeGenerationInput(capability, input, { allowAudioPath = false } = {}) {
+  const fields = Object.hasOwn(FIELDS, capability) ? FIELDS[capability] : null;
+  if (!fields) fail('不支持的生成能力');
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail('生成输入必须是 JSON 对象');
+  for (const field of Object.keys(input)) {
+    if (!fields.includes(field) && field !== 'model_ref') {
+      fail('生成输入不支持字段：' + field + '；允许 ' + fields.join(', ') + ', model_ref');
+    }
+  }
+  const modelRef = String(input.model_ref || '').trim();
+  const providerInput = {};
+  let audioPath;
+  if (capability === 'image' || capability === 'video') {
+    providerInput.prompt = text(input.prompt, 'prompt', 20000, true);
+    const size = text(input.size, 'size', 64);
+    if (size !== undefined) providerInput.size = size;
+  }
+  if (capability === 'image') {
+    const n = input.n === undefined ? 1 : Number(input.n);
+    if (!Number.isSafeInteger(n) || n < 1 || n > 4) fail('n 必须为 1–4 的整数');
+    providerInput.n = n;
+  }
+  if (capability === 'video') {
+    if (input.duration !== undefined) {
+      const duration = Number(input.duration);
+      if (!Number.isFinite(duration) || duration < 1 || duration > 60) fail('duration 必须为 1–60 的数字');
+      providerInput.duration = duration;
+    }
+    if (input.img_data_url !== undefined) {
+      const imgDataUrl = String(input.img_data_url).trim();
+      if (!imgDataUrl.startsWith('data:image/')) fail('img_data_url 必须是 data:image/ 开头的 data URL');
+      providerInput.imgDataUrl = imgDataUrl;
+    }
+  }
+  if (capability === 'tts') {
+    providerInput.text = text(input.text, 'text', 20000, true);
+    const voice = text(input.voice, 'voice', 64);
+    if (voice !== undefined) providerInput.voice = voice;
+  }
+  if (capability === 'transcribe') {
+    const audioUrl = String(input.audio_url || '').trim();
+    audioPath = String(input.audio_path || '').trim();
+    if (Boolean(audioUrl) === Boolean(audioPath)) {
+      fail('转写必须且只能提供 audio_url（公网/oss://）或 audio_path（本地绝对路径）之一');
+    }
+    if (audioUrl) {
+      if (audioUrl.length > 20000) fail('audio_url 最多为 20000 字符');
+      if (!/^(https:\/\/|oss:\/\/)/.test(audioUrl)) fail('audio_url 必须是 https:// 或 oss:// 地址');
+      providerInput.audioUrl = audioUrl;
+    } else {
+      if (!allowAudioPath) fail('retry 必须重新提供 audio_url；本地音频上传由调用入口负责');
+      if (!path.isAbsolute(audioPath)) fail('audio_path 必须是绝对路径');
+    }
+  }
+  return Object.freeze({
+    modelRef,
+    providerInput: Object.freeze(providerInput),
+    ...(audioPath ? { audioPath } : {})
+  });
+}

package/lib/guard.js

@@ -4,7 +4,7 @@
  *
  * `/iris/*` 不经过 DSH 的 `/api` 信任栅栏，因此默认只接受回环 Host。
  * LAN/反代场景需用 IRIS_TRUSTED_HOSTS 显式列出 host 或 host:port；这只是
- * Host 边界，不是身份认证。POST 另外校验 Sec-Fetch-Site 与 Origin==Host。
+ * Host 边界，不是身份认证。浏览器请求另校验 Sec-Fetch-Site 与 Origin==Host。
  */
 
 /** 请求 Host 头 → host:port 规范化（小写，去 IPv6 方括号保留） */
@@ -44,12 +44,12 @@ export function isTrustedHost(hostHeader, configured = process.env.IRIS_TRUSTED_
  */
 export function checkRequest(req, options = {}) {
   const headers = req.headers || {};
-  const method = String(req.method || 'GET').toUpperCase();
   if (!isTrustedHost(headers.host, options.trustedHosts)) {
     return { ok: false, status: 403, error: 'untrusted host' };
   }
-  if (method !== 'POST') return { ok: true };
 
+  // 浏览器的读请求同样可能泄露媒体与状态；明确的跨站/跨源请求一律拒绝。
+  // curl/CLI 等不发送 Origin/Sec-Fetch-Site 的非浏览器客户端仍可在受信 Host 上使用。
   const sfs = String(headers['sec-fetch-site'] || '').toLowerCase();
   if (sfs === 'cross-site') return { ok: false, status: 403, error: 'cross-site request denied' };
 

package/lib/host-contract.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * Iris Host Adapter v0 的纯契约原语。
+ *
+ * 本模块不导入 DSH/Cordis，也不读取宿主服务。具体 Adapter 只能把宿主能力
+ * 映射到这些命名端口；Command 不得接收原始 ctx。
+ */
+
+export const HOST_CONTRACT_VERSION = 0;
+
+export const HOST_PORTS = Object.freeze([
+  'attachments',
+  'browser',
+  'clientSlots',
+  'routes',
+  'sessions',
+  'skills',
+  'textModel',
+  'tools',
+  'visionModel'
+]);
+
+const HOST_PORT_SET = new Set(HOST_PORTS);
+const HOST_ID = /^[a-z0-9][a-z0-9._-]*$/;
+const UNAVAILABLE_KINDS = new Set(['unavailable', 'incompatible']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validatePortName(name) {
+  if (!HOST_PORT_SET.has(name)) throw new Error(`未知 Host Port：${name}`);
+}
+
+/**
+ * 建立只读 Host Adapter 描述。ports 中只放真实可调用的能力；缺失或版本不兼容
+ * 的能力放入 unavailable，供 Doctor 和用户错误复用同一份原因。
+ */
+export function defineHostAdapter(input) {
+  if (!isPlainObject(input)) throw new TypeError('Host Adapter 必须是对象');
+  const allowed = new Set(['contractVersion', 'id', 'version', 'ports', 'unavailable']);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) throw new Error(`Host Adapter 不允许顶层字段：${key}`);
+  }
+  const contractVersion = input.contractVersion ?? HOST_CONTRACT_VERSION;
+  if (contractVersion !== HOST_CONTRACT_VERSION) {
+    throw new Error(`不支持的 Host Adapter 契约版本：${String(contractVersion)}`);
+  }
+  const id = String(input.id || '').trim();
+  if (!HOST_ID.test(id)) throw new Error('Host Adapter id 必须是小写稳定标识');
+  const version = String(input.version || 'unknown').trim() || 'unknown';
+  const supplied = input.ports ?? {};
+  const missing = input.unavailable ?? {};
+  if (!isPlainObject(supplied) || !isPlainObject(missing)) {
+    throw new TypeError('Host Adapter ports/unavailable 必须是对象');
+  }
+
+  const ports = {};
+  for (const [name, value] of Object.entries(supplied)) {
+    validatePortName(name);
+    if (!isPlainObject(value)) throw new TypeError(`Host Port ${name} 必须是方法对象`);
+    ports[name] = value;
+  }
+
+  const unavailable = {};
+  for (const [name, value] of Object.entries(missing)) {
+    validatePortName(name);
+    if (Object.prototype.hasOwnProperty.call(ports, name)) {
+      throw new Error(`Host Port ${name} 不能同时可用和不可用`);
+    }
+    if (!isPlainObject(value) || !UNAVAILABLE_KINDS.has(value.kind) || !String(value.reason || '').trim()) {
+      throw new TypeError(`Host Port ${name} 的不可用记录必须包含 kind 和 reason`);
+    }
+    unavailable[name] = Object.freeze({ kind: value.kind, reason: String(value.reason).trim() });
+  }
+
+  return Object.freeze({
+    contractVersion,
+    id,
+    version,
+    ports: Object.freeze(ports),
+    unavailable: Object.freeze(unavailable)
+  });
+}
+
+export function hasHostPort(adapter, name) {
+  validatePortName(name);
+  return Boolean(adapter && adapter.ports && Object.prototype.hasOwnProperty.call(adapter.ports, name));
+}
+
+export class HostCapabilityError extends Error {
+  constructor(adapter, name, operation) {
+    validatePortName(name);
+    const detail = adapter && adapter.unavailable && adapter.unavailable[name];
+    const host = adapter && adapter.id ? adapter.id : 'unknown-host';
+    const action = String(operation || '当前操作');
+    const suffix = detail && detail.reason ? `：${detail.reason}` : '';
+    super(`Iris ${action}需要 Host Port ${name}，但 ${host} 未提供${suffix}`);
+    this.name = 'HostCapabilityError';
+    this.code = detail && detail.kind === 'incompatible'
+      ? 'IRIS_HOST_CAPABILITY_INCOMPATIBLE'
+      : 'IRIS_HOST_CAPABILITY_UNAVAILABLE';
+    this.hostId = host;
+    this.capability = name;
+    this.operation = action;
+  }
+}
+
+export function requireHostPort(adapter, name, operation) {
+  if (!hasHostPort(adapter, name)) throw new HostCapabilityError(adapter, name, operation);
+  return adapter.ports[name];
+}
+
+/** 只返回可序列化能力事实；不得把宿主 live object 暴露给 Doctor/API。 */
+export function hostCapabilitySnapshot(adapter) {
+  const capabilities = {};
+  for (const name of HOST_PORTS) {
+    const available = hasHostPort(adapter, name);
+    const detail = !available && adapter && adapter.unavailable ? adapter.unavailable[name] : undefined;
+    capabilities[name] = available
+      ? Object.freeze({ status: 'available' })
+      : Object.freeze({ status: detail && detail.kind === 'incompatible' ? 'incompatible' : 'unavailable',
+        ...(detail && detail.reason ? { reason: detail.reason } : {}) });
+  }
+  return Object.freeze({
+    contractVersion: HOST_CONTRACT_VERSION,
+    host: Object.freeze({ id: adapter && adapter.id || 'unknown-host', version: adapter && adapter.version || 'unknown' }),
+    capabilities: Object.freeze(capabilities)
+  });
+}

package/lib/host-runtime.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * Host Doctor 的运行时证据账本。
+ *
+ * 只记录 Iris 自己完成的注册事实和浏览器握手标量；不保存 ctx、service、
+ * API Key、会话、附件或其他 live object。
+ */
+export const IRIS_PLUGIN_ID = '@mokuyoaxis/dsh-iris';
+export const HOST_CLIENT_PROTOCOL_VERSION = 0;
+
+export const EXPECTED_IRIS_TOOLS = Object.freeze([
+  'iris_draw_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'
+]);
+
+export const EXPECTED_IRIS_SKILLS = Object.freeze([
+  'iris-verify-ui',
+  'iris-compose-media'
+]);
+
+export const EXPECTED_IRIS_ROUTES = Object.freeze([
+  '/iris/media',
+  '/iris/api',
+  '/iris/api/actions',
+  '/iris/render'
+]);
+
+export const EXPECTED_IRIS_CLIENT_SEATS = Object.freeze([
+  'settings.section',
+  'conversation.input.right',
+  'conversation.input.dock',
+  'shell.overlay'
+]);
+
+function fresh() {
+  return {
+    server: {
+      loaded: false,
+      pluginId: IRIS_PLUGIN_ID,
+      version: 'unknown',
+      startedAt: ''
+    },
+    tools: new Set(),
+    skills: new Set(),
+    routes: new Set(),
+    client: null
+  };
+}
+
+let runtime = fresh();
+
+function safeText(value, max = 160) {
+  return String(value || '').trim().slice(0, max);
+}
+
+function record(set, values) {
+  for (const value of Array.isArray(values) ? values : [values]) {
+    const text = safeText(value);
+    if (text && set.size < 100) set.add(text);
+  }
+}
+
+export function beginHostRuntime({ pluginId = IRIS_PLUGIN_ID, version = 'unknown' } = {}) {
+  runtime = fresh();
+  runtime.server = {
+    loaded: true,
+    pluginId: safeText(pluginId) || IRIS_PLUGIN_ID,
+    version: safeText(version) || 'unknown',
+    startedAt: new Date().toISOString()
+  };
+}
+
+export function recordHostTool(name) {
+  record(runtime.tools, name);
+}
+
+export function recordHostSkills(names) {
+  record(runtime.skills, names);
+}
+
+export function recordHostRoutes(paths) {
+  record(runtime.routes, paths);
+}
+
+/**
+ * 接受同源客户端报告。严格限制字段和枚举；报告只是诊断证据，不参与认证。
+ */
+export function recordHostClient(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new TypeError('Host client report 必须是对象');
+  }
+  const allowed = new Set(['pluginId', 'version', 'protocolVersion', 'seats']);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) throw new TypeError('Host client report 不允许字段：' + key);
+  }
+  const pluginId = safeText(input.pluginId);
+  const version = safeText(input.version);
+  const protocolVersion = Number(input.protocolVersion);
+  if (pluginId !== IRIS_PLUGIN_ID) throw new TypeError('Host client report 插件身份不匹配');
+  if (!version) throw new TypeError('Host client report 缺少版本');
+  if (!Number.isSafeInteger(protocolVersion) || protocolVersion < 0) {
+    throw new TypeError('Host client report protocolVersion 无效');
+  }
+  if (!Array.isArray(input.seats) || input.seats.length > 20) {
+    throw new TypeError('Host client report seats 无效');
+  }
+  const incomingSeats = [...new Set(input.seats.map((value) => safeText(value)).filter(Boolean))];
+  const invalidSeat = incomingSeats.find((seat) => !EXPECTED_IRIS_CLIENT_SEATS.includes(seat));
+  if (invalidSeat) throw new TypeError('Host client report 未知 seat：' + invalidSeat);
+  const previous = runtime.client
+    && runtime.client.pluginId === pluginId
+    && runtime.client.version === version
+    && runtime.client.protocolVersion === protocolVersion
+    ? runtime.client.seats : [];
+  // 同一客户端版本的 Slot 回调可能分别发出请求且乱序完成，只允许单调并集。
+  const seats = [...new Set(previous.concat(incomingSeats))];
+  runtime.client = {
+    loaded: true,
+    pluginId,
+    version,
+    protocolVersion,
+    seats,
+    reportedAt: new Date().toISOString()
+  };
+  return { ok: true, acceptedSeats: seats.length };
+}
+
+export function hostRuntimeEvidence() {
+  return Object.freeze({
+    server: Object.freeze({ ...runtime.server }),
+    tools: Object.freeze([...runtime.tools]),
+    skills: Object.freeze([...runtime.skills]),
+    routes: Object.freeze([...runtime.routes]),
+    client: runtime.client
+      ? Object.freeze({ ...runtime.client, seats: Object.freeze([...runtime.client.seats]) })
+      : null
+  });
+}
+
+/** 仅供隔离测试复位；生产装载使用 beginHostRuntime。 */
+export function resetHostRuntimeForTests() {
+  runtime = fresh();
+}