@mokuyoaxis/dsh-iris 0.1.3 → 0.1.4

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();
+}