@mokuyoaxis/dsh-iris 0.1.2 → 0.1.4

package/lib/dsh-host-adapter.js

@@ -0,0 +1,189 @@
+'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 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(Object.freeze({
+        attachmentId: ref.attachmentId,
+        mediaType: ref.mediaType,
+        name: typeof ref.name === 'string' ? ref.name : ''
+      }));
+    }
+    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 dshVisionPort(llm) {
+  return Object.freeze({
+    id: 'dsh-global',
+    model: '全局视觉模型',
+    async analyze({ question, ref, signal }) {
+      const chunks = [];
+      for await (const chunk of llm.stream({
+        sessionId: undefined,
+        provider: undefined,
+        model: undefined,
+        signal,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'text', text: question },
+            { type: 'image', attachment: ref }
+          ]
+        }]
+      })) {
+        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
+    });
+    ports.visionModel = dshVisionPort(llm);
+  } 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/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();
+}