@mokuyoaxis/dsh-iris 0.3.0-alpha.1 → 0.3.0-beta.1

package/templates/plugin-starter/README.md

@@ -0,0 +1,74 @@
+# Iris Plugin Starter · 独立插件模板
+
+A real, offline image-board plugin: choose existing Core images, make a PNG contact sheet, recover its original Operation after restart, and optionally expose the business to an explicitly authorized MCP connection. No provider account, GPU, or extra runtime dependency is required.
+
+This project has its own package name, plugin ID, plugin version, page and PNG renderer. Its image business delegates to Iris's **public** `@mokuyoaxis/dsh-iris/contact-sheet` export, version `0.1.0`. It is a starting point for independent plugins, not a second copy of Core or a new image-generation protocol.
+
+## Start · 开始使用
+
+Requires Node.js 22+ and Core `0.3.0-alpha.1` or a later compatible 0.3 build. Core beta.1 requires Node.js **22.1.0+**. Stable Iris `0.2.7` has no plugin SDK. The template is distributed with Core beta.1; the older alpha.1 package does **not** contain this directory.
+
+Copy `templates/plugin-starter` from a current Iris checkout into a **new** directory outside that checkout. From the installed beta.1 package, copy `node_modules/@mokuyoaxis/dsh-iris/templates/plugin-starter` instead. The copied project can use the public SDK already present in alpha.1:
+
+```bash
+cd /absolute/my-iris-plugin
+npm install --save-dev --save-exact @mokuyoaxis/dsh-iris@0.3.0-beta.1
+npm test
+npm run setup -- --directory /absolute/new-private-demo
+```
+
+`setup` requires an existing parent and a destination that does not exist, outside the plugin project. It creates a private demo directory, initializes a fresh execution root, imports two plain-colour sample PNGs, and writes absolute plugin-entry paths to `plugins.json`. Existing directories are rejected; an interrupted setup is retained for inspection, not silently retried. It prints paths and the exact startup argv, without starting a server or installing anything.
+
+Start the workbench in the foreground from this installed project:
+
+```bash
+npm exec -- dsh-iris plugins inspect --plugin-config /absolute/new-private-demo/plugins.json
+npm exec -- dsh-iris web serve --data-root /absolute/new-private-demo/core \
+  --plugin-config /absolute/new-private-demo/plugins.json --port 3182 \
+  --connection-store /absolute/new-private-demo/connections \
+  --allow-connection-management --allow-mcp
+```
+
+Use the printed login URL to set your workbench password. Open **灵感对照板**, select pictures, then click **制作对照板**. This business does not need `--allow-execution`; media creation and plugin operations have separate gates. Change the port explicitly if occupied. Keep the service running while a harness uses MCP.
+
+## MCP · 用户明确选择
+
+Loading a package, enabling a business, and authorizing a connection are separate steps. In **连接**, create a connection, deselect unused media groups, choose `example.starter-board.create`, and grant `read` + `execute` (`stop` is optional). Export the transport and configuration format accepted by your harness, then import that configuration there. Iris does not install or scan harnesses.
+
+After connecting, inspect `iris_core_plugin_catalog` and use its actual `dependency` pin. For this template the business input is:
+
+```json
+{
+  "artifactIds": ["artifact_<24 lowercase hex characters>"],
+  "columns": 2,
+  "cellSize": 256
+}
+```
+
+Use real image IDs from the catalog, 1–16 images in desired order, 1–4 columns and a cell size of 128–512. Call `iris_core_plugin_call` with `{ key, operationId, dependency, input }`; generate a UUID once before submitting. Reuse that UUID only with identical input. After an uncertain response, use `iris_core_lookup` first. `iris_core_operation` reads the saved state; `iris_core_image` delivers the saved PNG. The test protocol driver under `scripts/` is only an acceptance probe, not an MCP client implementation for production harnesses.
+
+## Develop · 修改与生命周期
+
+| File | Responsibility |
+|---|---|
+| `index.mjs` | Independent identity, compatibility, declared Core commands, operation/page/renderer versions and activation |
+| `web/board.mjs` | Shared session/API/theme, explicit submit, saved UUID lookup, listeners/timers/blob URL cleanup |
+| `web/png.mjs` | Reads original artifact bytes through the provided API and releases its image URL on unmount |
+| `scripts/setup.mjs` | New-directory-only initialization through the public CLI |
+| `scripts/smoke.mjs` | Real Core/MCP acceptance using fresh, private temporary data |
+
+Rename the package and plugin ID before sharing your own plugin. Update the IDs in `scripts/setup.mjs` and the acceptance expectations too. The page derives its operation ID from its own plugin identity; it does not hardcode a Core installation path or request an owner token. Declare every browser entry and CSS resource in the manifest. Files outside those declarations are not automatically served; keep browser modules self-contained unless a future public asset contract says otherwise.
+
+The delegated operation declares only `artifact.read` and `artifact.import`, with `artifactIds` declared as source inputs. Core validates closed JSON input, source access, current authorization, durable execution and output registration. A direct `createCorePluginHost().call()` is not a durable Operation; use the workbench/API/MCP business route when persistence is required. The template owns no backend resources. If you add sockets, watchers or similar resources, register cleanup using `context.onDispose()` during `activate`, and make work observe its AbortSignal. Close workbenches/hosts before disposing their shared registry.
+
+Core saves the exact plugin and contribution versions with each Operation. Treat changed business semantics as a plugin/operation version change. Upgrading the underlying contact-sheet implementation requires review; this template deliberately refuses a version other than `0.1.0`. An incompatible/missing plugin blocks new execution and cannot substitute for a saved version. History and committed image bytes remain Core-owned. Interrupted work is retained as interrupted; it is not automatically submitted again. Editing the plugin requires a normal service stop and restart; there is no hot reload.
+
+These are trusted Node and same-origin browser modules. Shadow DOM isolates styles, not code. Load code you trust. The small Core command interface constrains business calls but does not sandbox arbitrary Node imports. No arbitrary plugin settings storage or credential-reference API is invented here.
+
+## Acceptance · 自检范围
+
+`npm test` creates a separate private temporary root and closes its own services. It verifies real PNG execution, explicit selection/authorization, duplicate UUID conflict, same-port restart, original bytes, dependency version change, plugin absence and reduced permissions. It prints a safe evidence path and PNG hash; temporary evidence is retained. It does not touch daily DSH/harness configuration or call a paid model. SDK-created test sessions use temporary owner tokens; ordinary CLI workbenches use password login.
+
+The Iris repository additionally verifies packed Core and plugin archives outside the checkout and tests this page/renderer in a real browser. This does not establish compatibility with every harness, operating system or future plugin. See the public [plugin SDK](https://github.com/mokuyoaxis/dsh-iris/blob/main/docs/PLUGINS.md) and [startup guide](https://github.com/mokuyoaxis/dsh-iris/blob/main/docs/PLUGIN_STARTUP.md) for the full contracts.
+
+To distribute your own package, review its identity/version/compatibility, replace this README, set your own repository metadata, and remove `private: true` deliberately when ready. Run `npm pack --ignore-scripts --dry-run --json`, inspect the allowlisted files, then test the real archive from another project before publishing. Keep the MIT attribution when reusing these files. Never include private demo roots or connection credentials in your package.

package/templates/plugin-starter/index.mjs

@@ -0,0 +1,27 @@
+import { definePlugin } from '@mokuyoaxis/dsh-iris/plugins';
+import contactSheet from '@mokuyoaxis/dsh-iris/contact-sheet';
+
+// Review the delegated business before changing persistent operation semantics.
+// This version is independent of both the npm package and Core's version.
+if (contactSheet.manifest.version !== '0.1.0') {
+  throw new Error('Starter expects contact-sheet 0.1.0; review its changes and this plugin version before upgrading.');
+}
+
+export default definePlugin({
+  manifest: {
+    contractVersion: 0,
+    id: 'example.starter-board',
+    version: '0.1.0',
+    compatibility: { min: '0.3.0-alpha.1', maxExclusive: '0.4.0' },
+    contributions: {
+      operations: contactSheet.manifest.contributions.operations,
+      pages: [{ id: 'board', version: '0.1.0', title: '灵感对照板', entry: 'web/board.mjs', styles: ['web/board.css'] }],
+      renderers: [{ id: 'png', version: '0.1.0', title: '对照板预览', entry: 'web/png.mjs', styles: ['web/board.css'], mediaTypes: ['image/png'] }]
+    }
+  },
+  activate(context) {
+    // Core owns execution, permissions and artifact storage. No new queue/root.
+    // If you acquire resources here, register real cleanup with context.onDispose.
+    return contactSheet.activate(context);
+  }
+});

package/templates/plugin-starter/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "iris-plugin-starter-board",
+  "version": "0.1.0",
+  "private": true,
+  "description": "An independent Iris contact-sheet plugin using only the public SDK.",
+  "type": "module",
+  "exports": "./index.mjs",
+  "files": ["index.mjs", "web", "assets", "scripts", "README.md", "LICENSE"],
+  "scripts": {
+    "setup": "node scripts/setup.mjs",
+    "test": "node scripts/smoke.mjs"
+  },
+  "peerDependencies": {
+    "@mokuyoaxis/dsh-iris": ">=0.3.0-alpha.1 <0.4.0"
+  },
+  "engines": { "node": ">=22.0.0" },
+  "license": "MIT"
+}

package/templates/plugin-starter/scripts/core-cli.mjs

@@ -0,0 +1,20 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageFile = fileURLToPath(import.meta.resolve('@mokuyoaxis/dsh-iris/package.json'));
+const metadata = JSON.parse(await readFile(packageFile, 'utf8'));
+export const coreCli = path.resolve(path.dirname(packageFile), metadata.bin['dsh-iris']);
+const execute = promisify(execFile);
+
+export async function runCore(dataRoot, ...args) {
+  const { stdout } = await execute(process.execPath, [coreCli, ...args, '--data-root', dataRoot], {
+    timeout: 30_000, maxBuffer: 2 * 1024 * 1024,
+    env: { ...process.env, IRIS_IMPORT_WORKBENCH_CONFIG: '', IRIS_CORE_CONNECTION_FILE: '', IRIS_CORE_SCOPES: '' }
+  });
+  const result = JSON.parse(stdout);
+  if (result.ok === false) throw new Error('Core command failed: ' + JSON.stringify(result));
+  return result.result ?? result;
+}

package/templates/plugin-starter/scripts/environment.mjs

@@ -0,0 +1,65 @@
+// Acceptance helper: installed public SDK + CLI + HTTP. Not plugin runtime code.
+import assert from 'node:assert/strict';
+import { mkdtemp, chmod, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadCorePluginRegistry, createCorePluginRegistry, createCorePluginWorkbench, definePlugin } from '@mokuyoaxis/dsh-iris/plugins';
+import plugin from '../index.mjs';
+import { setup } from './setup.mjs';
+
+export const businessId = plugin.manifest.id + '.create';
+export async function createEnvironment() {
+  const work = await mkdtemp(path.join(os.tmpdir(), 'iris-starter-')); await chmod(work, 0o700);
+  const prepared = await setup(path.join(work, 'demo'));
+  const config = JSON.parse(await readFile(prepared.configPath, 'utf8'));
+  let api, registry, started, port;
+  async function start({ present = true, enabled = true, version } = {}) {
+    if (version) registry = await createCorePluginRegistry({ plugins: [definePlugin({
+      manifest: { ...plugin.manifest, version }, activate: context => plugin.activate(context)
+    })] });
+    else registry = await loadCorePluginRegistry({ entries: present ? [prepared.entry] : [] });
+    api = createCorePluginWorkbench({ dataRoot: prepared.dataRoot, registry,
+      allowedOperations: present && enabled ? [businessId] : [], connectionStore: prepared.connectionStore, allowMcp: true,
+      ...(present && !version ? { panelContributions: config.panel } : {}) });
+    started = await api.start(port ? { port } : {}); port ??= Number(new URL(started.origin).port);
+    return started;
+  }
+  async function close() { await api?.dispose(); api = undefined; await registry?.dispose(); registry = undefined; }
+  async function raw(route, { value, key, headers, method = value === undefined ? 'GET' : 'POST' } = {}) {
+    return fetch(started.origin + route, { method, headers: {
+      Authorization: 'Bearer ' + started.accessToken, ...(value === undefined ? {} : { 'Content-Type': 'application/json' }),
+      ...(key ? { 'Idempotency-Key': key } : {}), ...headers
+    }, ...(value === undefined ? {} : { body: JSON.stringify(value) }), signal: AbortSignal.timeout(20_000) });
+  }
+  async function http(route, options, expected = 200) {
+    const response = await raw(route, options), value = await response.json();
+    assert.equal(response.status, expected, JSON.stringify(value)); return value;
+  }
+  async function terminal(id) {
+    for (let i = 0; i < 300; i++) {
+      const operation = (await http('/api/v0/operations/' + id)).operation;
+      if (!['queued', 'running'].includes(operation.state)) return operation;
+      await new Promise(resolve => setTimeout(resolve, 20));
+    }
+    assert.fail('Operation did not finish');
+  }
+  const pin = () => registry.dependency('operations', businessId);
+  const request = () => ({ key: crypto.randomUUID(), operationId: businessId, dependency: pin(),
+    input: { artifactIds: prepared.artifactIds, columns: 2, cellSize: 128 } });
+  const submit = ({ key, ...value }, expected = 202) => http('/api/v0/plugin-operations', { key, value }, expected);
+  const base = '/api/v0/connection-management/connections';
+  async function connection(pins = [pin()]) {
+    const result = await http(base, { value: { key: crypto.randomUUID(), label: 'Independent starter test',
+      scopes: ['read', 'execute', 'stop'], capabilities: [], pluginOperations: pins } }, 201);
+    return (await http(base)).connections.find(item => item.connectionId === result.connectionId);
+  }
+  const exported = record => http(base + '/' + record.connectionId + '/export', { value: { transport: 'http', format: 'entry' } });
+  const update = (record, scopes) => http(base + '/' + record.connectionId + '/update', { value: {
+    expectedRevision: record.revision, label: record.label, scopes, capabilities: record.capabilities,
+    tools: record.tools, pluginOperations: record.pluginOperations
+  } });
+  return { work, prepared, config, start, close, raw, http, terminal, pin, request, submit, connection, exported, update,
+    get registry() { return registry; }, get started() { return started; },
+    templateRoot: fileURLToPath(new URL('..', import.meta.url)) };
+}

package/templates/plugin-starter/scripts/mcp-probe.mjs

@@ -0,0 +1,22 @@
+// Test-only protocol driver. Iris itself uses the official MCP server SDK.
+// Harnesses should import exported MCP configuration, not copy this driver.
+export async function mcpProbe(configuration) {
+  let sequence = 0;
+  async function request(method, params, notification = false) {
+    const id = notification ? undefined : ++sequence;
+    const response = await fetch(configuration.url, { method: 'POST', headers: {
+      ...configuration.headers, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream',
+      'MCP-Protocol-Version': '2025-11-25'
+    }, body: JSON.stringify({ jsonrpc: '2.0', ...(notification ? {} : { id }), method, params }), signal: AbortSignal.timeout(20_000) });
+    const text = await response.text();
+    if (notification && response.status === 202) return;
+    const messages = response.headers.get('content-type')?.startsWith('text/event-stream')
+      ? text.split('\n').filter(line => line.startsWith('data:')).map(line => JSON.parse(line.slice(5))) : [JSON.parse(text)];
+    const message = messages.find(item => item.id === id) || messages.at(-1);
+    if (!response.ok || message.error) throw new Error(message.error?.message || 'MCP HTTP ' + response.status);
+    return message.result;
+  }
+  await request('initialize', { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'iris-plugin-starter-test', version: '0.1.0' } });
+  await request('notifications/initialized', {}, true);
+  return { request, call: (name, args) => request('tools/call', { name, arguments: args }) };
+}

package/templates/plugin-starter/scripts/setup.mjs

@@ -0,0 +1,42 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { coreCli, runCore } from './core-cli.mjs';
+
+export async function setup(directory) {
+  if (!path.isAbsolute(directory)) throw new Error('--directory must be an absolute path to a new directory.');
+  const projectRoot = fileURLToPath(new URL('..', import.meta.url)), relative = path.relative(projectRoot, directory);
+  if (relative === '' || !relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative)) {
+    throw new Error('Demo data must be outside the plugin project so it cannot enter its npm package.');
+  }
+  // EEXIST deliberately rejects existing user data, including empty directories.
+  await mkdir(directory, { mode: 0o700 });
+  const dataRoot = path.join(directory, 'core'), connectionStore = path.join(directory, 'connections');
+  const entry = fileURLToPath(new URL('../index.mjs', import.meta.url));
+  const config = {
+    schemaVersion: 0, entries: [entry], operations: ['example.starter-board.create'],
+    panel: { pages: ['example.starter-board.board'], renderers: ['example.starter-board.png'] }
+  };
+  const configPath = path.join(directory, 'plugins.json');
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  await runCore(dataRoot, 'flow', 'init');
+  await runCore(dataRoot, 'execution', 'init');
+  const artifactIds = [];
+  for (const name of ['violet.png', 'peach.png']) {
+    const imagePath = fileURLToPath(new URL('../assets/' + name, import.meta.url));
+    const result = await runCore(dataRoot, 'artifact', 'import', '--input', JSON.stringify({ image_path: imagePath }));
+    artifactIds.push(result.artifact.id);
+  }
+  return { directory, dataRoot, connectionStore, configPath, entry, artifactIds };
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  if (process.argv.length !== 4 || process.argv[2] !== '--directory') {
+    throw new Error('Usage: npm run setup -- --directory /absolute/new-private-directory');
+  }
+  const result = await setup(process.argv[3]);
+  // Exact argv avoids shell quoting assumptions; no server or browser is started.
+  console.log(JSON.stringify({ ...result, startArgv: [process.execPath, coreCli, 'web', 'serve',
+    '--data-root', result.dataRoot, '--plugin-config', result.configPath,
+    '--connection-store', result.connectionStore, '--allow-connection-management', '--allow-mcp', '--port', '3182'] }, null, 2));
+}

package/templates/plugin-starter/scripts/smoke.mjs

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createEnvironment, businessId } from './environment.mjs';
+import { setup } from './setup.mjs';
+import { mcpProbe } from './mcp-probe.mjs';
+
+const env = await createEnvironment(), checks = [];
+const parsed = result => { assert(!result.isError, JSON.stringify(result)); return result.structuredContent ?? JSON.parse(result.content.find(item => item.type === 'text').text); };
+try {
+  const configBefore = await readFile(env.prepared.configPath);
+  await assert.rejects(setup(env.prepared.directory), { code: 'EEXIST' });
+  await assert.rejects(setup(env.templateRoot + '/private-demo'), /outside the plugin project/);
+  assert.deepEqual(await readFile(env.prepared.configPath), configBefore);
+  checks.push('setup rejects an existing directory without replacing its configuration');
+  await env.start({ enabled: false });
+  assert.equal((await env.http('/api/v0/connection-management/connections')).connections.length, 0);
+  const call = env.request(); await env.submit(call, 403);
+  checks.push('loading the package grants no connection access; a disabled business cannot execute');
+  await env.close(); await env.start();
+  const session = await env.http('/api/v0/session');
+  assert.equal(session.workbenchMediaReadOnly, true);
+  assert.equal(session.panelContributions.pages[0].dependency.pluginId, 'example.starter-board');
+  assert.equal(session.panelContributions.renderers[0].id, 'example.starter-board.png');
+  for (const item of [...session.panelContributions.pages, ...session.panelContributions.renderers]) {
+    for (const route of [item.entry, ...item.styles]) assert.equal((await fetch(env.started.origin + route)).status, 200);
+  }
+  checks.push('the independent page and PNG renderer are actually served from selected, pinned package assets');
+  const unselected = await env.connection([]);
+  const without = await mcpProbe((await env.exported(unselected)).configuration);
+  assert(!(await without.request('tools/list', {})).tools.some(item => item.name === 'iris_core_plugin_call'));
+  const record = await env.connection(), config = (await env.exported(record)).configuration;
+  let client = await mcpProbe(config);
+  const names = (await client.request('tools/list', {})).tools.map(item => item.name);
+  assert(names.includes('iris_core_plugin_call')); assert(!names.includes('iris_core_continue'));
+  const catalog = parsed(await client.call('iris_core_plugin_catalog', {}));
+  assert.equal(catalog.operations[0].id, businessId);
+  const accepted = parsed(await client.call('iris_core_plugin_call', call));
+  const operation = await env.terminal(accepted.operation.id); assert.equal(operation.state, 'succeeded', JSON.stringify(operation));
+  assert.deepEqual(operation.sourceArtifactIds, env.prepared.artifactIds);
+  const outputId = operation.result.artifactIds[0];
+  const bytes = Buffer.from((await client.call('iris_core_image', { artifactId: outputId })).content.find(item => item.type === 'image').data, 'base64');
+  assert.deepEqual([...bytes.subarray(0, 8)], [137, 80, 78, 71, 13, 10, 26, 10]);
+  assert.equal(bytes.readUInt32BE(16), 292); assert.equal(bytes.readUInt32BE(20), 152);
+  const digest = createHash('sha256').update(bytes).digest('hex');
+  checks.push('a user-selected, business-only connection executes the real PNG operation through formal HTTP MCP');
+  assert.equal(parsed(await client.call('iris_core_plugin_call', call)).operation.id, operation.id);
+  await env.submit({ ...call, input: { ...call.input, columns: 1 } }, 409);
+  checks.push('same UUID returns the saved Operation; changed input under that UUID is rejected');
+  await env.close(); await env.start();
+  assert.deepEqual((await env.exported(record)).configuration, config);
+  client = await mcpProbe(config);
+  assert.deepEqual(parsed(await client.call('iris_core_operation', { operationId: operation.id })).operation, operation);
+  assert.equal(parsed(await client.call('iris_core_lookup', { key: call.key })).operation.id, operation.id);
+  assert.equal((await env.http('/api/v0/plugin-operations/catalog')).artifacts.length, 3);
+  const restored = Buffer.from((await client.call('iris_core_image', { artifactId: outputId })).content.find(item => item.type === 'image').data, 'base64');
+  assert.deepEqual(restored, bytes);
+  checks.push('restart preserves the original connection, UUID, exact Operation and PNG bytes without another business execution');
+  await env.update(record, ['read']);
+  client = await mcpProbe(config);
+  assert(!(await client.request('tools/list', {})).tools.some(item => item.name === 'iris_core_plugin_call'));
+  assert.equal(parsed(await client.call('iris_core_operation', { operationId: operation.id })).operation.state, 'succeeded');
+  await assert.rejects(client.call('iris_core_plugin_call', { ...call, key: crypto.randomUUID() }), /Tool iris_core_plugin_call not found/);
+  checks.push('reduced authority removes execution tools and rejects explicit calls while retaining granted history reads');
+  await env.close(); await env.start({ version: '0.1.1' });
+  await env.submit({ ...call, key: crypto.randomUUID() }, 409);
+  assert.deepEqual((await env.http('/api/v0/operations/' + operation.id)).operation, operation);
+  checks.push('a different installed version cannot replace a saved exact plugin dependency');
+  await env.close(); await env.start({ present: false });
+  assert.deepEqual((await env.http('/api/v0/operations/' + operation.id)).operation, operation);
+  assert.deepEqual((await env.http('/api/v0/plugin-operations/catalog')).operations, []);
+  assert.deepEqual(Buffer.from(await (await env.raw('/api/v0/artifacts/' + outputId + '/content')).arrayBuffer()), bytes);
+  await env.submit({ ...call, key: crypto.randomUUID() }, 403);
+  checks.push('missing implementation blocks new execution but keeps Core history and original artifact readable');
+  console.log(JSON.stringify({ ok: true, checks, work: env.work, operationId: operation.id, artifactId: outputId, sha256: digest }, null, 2));
+} finally { await env.close(); }

package/templates/plugin-starter/web/board.css

@@ -0,0 +1,27 @@
+.starter-intro { margin-bottom:24px; }
+.starter-eyebrow { color:var(--accent); font-size:11px; letter-spacing:1.5px; }
+.starter-intro h2 { font-size:clamp(21px,3vw,28px); letter-spacing:-.6px; margin:8px 0; }
+.starter-intro::after { content:""; display:block; height:3px; width:80px; border-radius:9px; margin-top:20px; background:linear-gradient(105deg,#45317D,#6F69B8,#BB78AD,#E59B76,#ED9C91,#F0D09C); }
+.muted { color:var(--muted); font-size:13px; line-height:1.6; }
+.starter-layout { display:grid; grid-template-columns:minmax(0,1fr) 220px; gap:20px; align-items:start; }
+.starter-choices { display:grid; grid-template-columns:repeat(auto-fill,minmax(110px,1fr)); gap:12px; min-width:0; }
+.starter-choice { position:relative; padding:10px; border:1px solid var(--line); border-radius:12px; background:var(--soft); cursor:pointer; }
+.starter-choice:has(input:checked) { border-color:var(--accent); background:var(--tint); }
+.starter-choice input { position:absolute; top:10px; left:10px; }
+.starter-choice img { display:block; width:100%; height:120px; object-fit:contain; border-radius:6px; }
+.starter-choice span { display:block; text-align:center; margin-top:8px; overflow-wrap:anywhere; }
+.starter-editor { padding:18px; border:1px solid var(--line); border-radius:14px; background:var(--soft); }
+.starter-editor label { display:block; font-size:13px; margin-bottom:14px; }
+.starter-editor select { display:block; width:100%; margin-top:6px; min-height:40px; padding:6px; border:1px solid var(--line); border-radius:8px; color:var(--ink); background:var(--panel); }
+.starter-editor button { display:block; width:100%; min-height:42px; margin:10px 0; border:0; border-radius:8px; padding:9px; background:var(--accent); color:var(--on-accent); cursor:pointer; }
+.starter-editor button:disabled { opacity:.5; cursor:default; }
+.starter-editor .secondary { border:1px solid var(--line); background:transparent; color:var(--ink); }
+.starter-editor details { margin-top:18px; font-size:13px; }
+.starter-editor summary { cursor:pointer; }
+.starter-status { font-size:13px; line-height:1.8; overflow-wrap:anywhere; margin:20px 0; }
+.starter-result { border-top:1px solid var(--line); padding-top:20px; }
+.starter-result img, .starter-preview img { display:block; max-width:100%; max-height:600px; object-fit:contain; margin:0 auto 16px; }
+.starter-result a { display:inline-block; padding:10px 14px; border:1px solid var(--line); border-radius:8px; color:var(--accent); }
+:focus-visible { outline:2px solid var(--accent); outline-offset:3px; }
+[hidden] { display:none !important; }
+@media(max-width:680px) { .starter-layout { grid-template-columns:1fr; } .starter-editor { order:-1; } }

package/templates/plugin-starter/web/board.mjs

@@ -0,0 +1,160 @@
+const element = (tag, text, className) => {
+  const node = document.createElement(tag);
+  if (text) node.textContent = text;
+  if (className) node.className = className;
+  return node;
+};
+
+export async function mount({ container, api, session, dependency, signal: parentSignal, theme }) {
+  const lifetime = new AbortController(), signal = AbortSignal.any([parentSignal, lifetime.signal]);
+  const service = api.pluginOperations, urls = new Set();
+  const operationId = dependency.pluginId + '.create';
+  const storageKey = operationId + ':' + session.rootId;
+  let receipt, selected = [], catalog, busy = false, timer, renderedId, unsubscribe, closed = false;
+  function cleanup() {
+    if (closed) return;
+    closed = true; lifetime.abort(); clearTimeout(timer); unsubscribe?.();
+    for (const url of urls) URL.revokeObjectURL(url);
+    urls.clear(); container.replaceChildren();
+  }
+  signal.addEventListener('abort', cleanup, { once: true });
+  const intro = element('header', '', 'starter-intro');
+  intro.append(element('span', 'LOCAL · NO MODEL CALLS', 'starter-eyebrow'), element('h2', '让灵感，并排相遇。'),
+    element('p', '选择图片，制作一张属于你的灵感对照板。', 'muted'));
+  const layout = element('div', '', 'starter-layout'), choices = element('div', '', 'starter-choices');
+  choices.setAttribute('aria-label', '选择来源图片');
+  const editor = element('form', '', 'starter-editor');
+  const columnsLabel = element('label', '每行图片数'), columns = document.createElement('select'); columns.name = 'columns';
+  for (let i = 1; i <= 4; i++) columns.add(new Option(String(i), String(i)));
+  columns.value = '2'; columnsLabel.append(columns);
+  const sizeLabel = element('label', '单张边长'), size = document.createElement('select'); size.name = 'size';
+  for (const n of [128, 256, 512]) size.add(new Option(n + ' px', String(n)));
+  size.value = '256'; sizeLabel.append(size);
+  const count = element('p', '尚未选择图片', 'muted'), submit = element('button', '制作对照板');
+  submit.type = 'submit'; submit.disabled = true;
+  const recover = element('button', '查询原操作', 'secondary'); recover.type = 'button'; recover.hidden = true;
+  const fresh = element('button', '新建一张', 'secondary'); fresh.type = 'button'; fresh.hidden = true;
+  const more = element('button', '加载更多图片', 'secondary'); more.type = 'button'; more.hidden = true;
+  const details = element('details'), summary = element('summary', '使用说明');
+  details.append(summary, element('p', '按选择顺序排版，最多 16 张。作品保存在 Core；刷新只查询原操作，不会自动重新制作。', 'muted'));
+  editor.append(columnsLabel, sizeLabel, count, submit, recover, fresh, more, details);
+  const status = element('p', '正在读取现有图片…', 'starter-status');
+  status.setAttribute('role', 'status');
+  const output = element('section', '', 'starter-result'); output.hidden = true;
+  layout.append(choices, editor); container.append(intro, layout, status, output);
+  function remember(value) {
+    value ? sessionStorage.setItem(storageKey, JSON.stringify(value)) : sessionStorage.removeItem(storageKey);
+    receipt = value;
+  }
+  function controls() {
+    const locked = busy || Boolean(receipt);
+    submit.disabled = locked || !selected.length || !catalog?.operations.some(item => item.id === operationId && item.available);
+    columns.disabled = size.disabled = locked; more.disabled = busy;
+    for (const checkbox of choices.querySelectorAll('input')) checkbox.disabled = locked || !checkbox.checked && selected.length >= 16;
+  }
+  function note(error) { status.textContent = [error.message, error.code, error.requestId].filter(Boolean).join(' · '); }
+  async function present(operation) {
+    signal.throwIfAborted();
+    if (operation.action !== 'plugin.execute' || operation.operationId !== operationId) throw new Error('此恢复标识属于另一项业务，请到业务记录核对。');
+    status.textContent = ({ queued: '已接收，等待处理', running: '正在排版', succeeded: '对照板已保存',
+      interrupted: '操作已中断，不会自动重做', canceled: '已停止，记录保留', failed: '操作未完成，请查看业务记录' })[operation.state] + ' · ' + operation.id;
+    fresh.hidden = ['queued', 'running'].includes(operation.state); recover.hidden = true;
+    if (operation.state === 'succeeded' && renderedId !== operation.id) {
+      const id = operation.result.artifactIds[0];
+      const blob = await api.artifact({ id, mediaType: 'image/png' }, { signal }); signal.throwIfAborted();
+      const url = URL.createObjectURL(blob); urls.add(url);
+      const image = element('img'); image.src = url; image.alt = '已保存的灵感对照板';
+      const link = element('a', '下载原始 PNG'); link.href = url; link.download = 'iris-board-' + id + '.png';
+      output.replaceChildren(image, link); output.hidden = false; renderedId = operation.id;
+    } else if (['queued', 'running'].includes(operation.state)) {
+      clearTimeout(timer); timer = setTimeout(() => { void poll(operation.id); }, 450);
+    }
+  }
+  async function poll(id) {
+    try { await present((await service.inspect(id, { signal })).operation); }
+    catch (error) { if (!signal.aborted) { note(error); recover.hidden = false; } }
+  }
+  async function lookup() {
+    if (busy || !receipt) return;
+    busy = true; controls();
+    try { await present((await service.lookup(receipt.key, { signal })).operation); }
+    catch (error) { if (!signal.aborted) { note(error); recover.hidden = false; if (error.status === 404) fresh.hidden = false; } }
+    finally { busy = false; if (!signal.aborted) controls(); }
+  }
+  editor.addEventListener('submit', async event => {
+    event.preventDefault();
+    if (busy || receipt || !selected.length) return;
+    const contribution = catalog.operations.find(item => item.id === operationId && item.available);
+    if (!contribution) return;
+    busy = true;
+    // Save the UUID before submitting. Recovery only looks up this UUID.
+    try { remember({ key: crypto.randomUUID() }); }
+    catch { busy = false; status.textContent = '浏览器无法保存恢复标识，本次未提交。请允许会话存储后再试。'; controls(); return; }
+    controls();
+    status.textContent = '正在保存本次操作 · ' + receipt.key;
+    try {
+      const accepted = await service.execute({ key: receipt.key, operationId, dependency: contribution.dependency,
+        input: { artifactIds: [...selected], columns: Number(columns.value), cellSize: Number(size.value) } }, { signal });
+      await present(accepted.operation);
+    } catch (error) {
+      if (!signal.aborted) { note(error); status.textContent += '。请查询原操作；未自动重做。'; recover.hidden = false; }
+    } finally { busy = false; if (!signal.aborted) controls(); }
+  }, { signal });
+  recover.addEventListener('click', () => { void lookup(); }, { signal });
+  fresh.addEventListener('click', () => {
+    if (busy) return;
+    try { remember(null); }
+    catch { status.textContent = '无法清除恢复标识，原操作保留；请先检查浏览器存储。'; return; }
+    renderedId = undefined; output.hidden = true; output.replaceChildren();
+    // Only keep URLs that still back source thumbnails.
+    const thumbnails = new Set([...choices.querySelectorAll('img')].map(image => image.src));
+    for (const url of urls) if (!thumbnails.has(url)) { URL.revokeObjectURL(url); urls.delete(url); }
+    fresh.hidden = recover.hidden = true; status.textContent = '选择图片后，可以新建一次操作。'; controls();
+  }, { signal });
+  async function appendImages(page) {
+    for (const artifact of page.artifacts) {
+      const label = element('label', '', 'starter-choice'), checkbox = document.createElement('input');
+      checkbox.type = 'checkbox'; checkbox.value = artifact.id;
+      const image = element('img'); image.alt = '来源图片 ' + artifact.id;
+      label.append(checkbox, image, element('span', artifact.id.slice(-8), 'muted')); choices.append(label);
+      const blob = await api.artifact({ id: artifact.id, mediaType: artifact.mediaType }, { signal }); signal.throwIfAborted();
+      const url = URL.createObjectURL(blob); urls.add(url); image.src = url;
+      checkbox.addEventListener('change', () => {
+        selected = checkbox.checked ? [...selected, artifact.id] : selected.filter(id => id !== artifact.id);
+        count.textContent = '已选择 ' + selected.length + ' 张 · 按选择顺序排版'; controls();
+      }, { signal });
+    }
+    more.hidden = page.nextOffset === null || page.nextOffset === undefined; controls();
+  }
+  more.addEventListener('click', async () => {
+    if (busy || catalog.nextOffset === null) return;
+    busy = true; controls();
+    try {
+      catalog = await service.catalog({ limit: '30', offset: String(catalog.nextOffset) }, { signal });
+      signal.throwIfAborted(); await appendImages(catalog);
+    } catch (error) { if (!signal.aborted) note(error); }
+    finally { busy = false; if (!signal.aborted) controls(); }
+  }, { signal });
+  try {
+    signal.throwIfAborted();
+    const updateTheme = value => { container.dataset.theme = value.mode; };
+    updateTheme(theme.current()); unsubscribe = theme.subscribe(updateTheme);
+    if (!service) { status.textContent = '此服务尚未启用插件业务执行，请核对启动配置。'; return cleanup; }
+    catalog = await service.catalog({ limit: '30' }, { signal }); signal.throwIfAborted();
+    await appendImages(catalog);
+    status.textContent = catalog.artifacts.length ? '选择图片即可开始，不调用模型。' : '还没有图片。请先通过创作页或 CLI 导入。';
+    let saved;
+    try { saved = sessionStorage.getItem(storageKey); }
+    catch { status.textContent = '无法读取浏览器恢复标识，请到业务记录查看已有操作。'; }
+    if (saved) {
+      try {
+        receipt = JSON.parse(saved);
+        if (!receipt || !/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(receipt.key)) throw new Error('invalid receipt');
+      } catch {
+        receipt = { invalid: true }; status.textContent = '浏览器恢复标识损坏，请核对业务记录后点击新建。'; fresh.hidden = false;
+      }
+      if (!receipt.invalid) await lookup();
+    }
+    controls(); return cleanup;
+  } catch (error) { cleanup(); throw error; }
+}

package/templates/plugin-starter/web/png.mjs

@@ -0,0 +1,23 @@
+export async function mount({ container, artifact, api, signal: parentSignal, theme }) {
+  const lifetime = new AbortController(), signal = AbortSignal.any([parentSignal, lifetime.signal]);
+  let url, unsubscribe, closed = false;
+  const image = new Image(); image.alt = 'Core 中保存的原始 PNG';
+  function cleanup() {
+    if (closed) return;
+    closed = true; lifetime.abort(); unsubscribe?.();
+    if (url) URL.revokeObjectURL(url);
+    image.removeAttribute('src'); container.replaceChildren();
+  }
+  signal.addEventListener('abort', cleanup, { once: true });
+  try {
+    const bytes = await api.artifact(artifact, { signal }); signal.throwIfAborted();
+    url = URL.createObjectURL(bytes); image.src = url;
+    await image.decode(); signal.throwIfAborted();
+    const caption = document.createElement('p'); caption.className = 'muted';
+    caption.textContent = image.naturalWidth + ' × ' + image.naturalHeight + ' · ' + bytes.size.toLocaleString() + ' bytes';
+    const update = value => { container.dataset.theme = value.mode; };
+    update(theme.current()); unsubscribe = theme.subscribe(update);
+    container.classList.add('starter-preview'); container.append(image, caption);
+    return cleanup;
+  } catch (error) { cleanup(); throw error; }
+}

package/templates/provider-starter/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Messia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.