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

package/plugins/contact-sheet/web/board.css

@@ -0,0 +1,14 @@
+.intro { margin-bottom:24px; }
+.intro h2 { font-size:24px; letter-spacing:-.6px; }
+.board-layout { display:grid; grid-template-columns:minmax(0,1fr) 240px; gap:20px; align-items:start; }
+.image-choices { display:grid; grid-template-columns:repeat(auto-fill,minmax(120px,1fr)); gap:12px; }
+.image-choice { position:relative; margin:0; padding:8px; background:var(--soft); border:1px solid var(--line); border-radius:10px; cursor:pointer; }
+.image-choice:has(input:checked) { border-color:var(--accent); background:var(--tint); }
+.image-choice input { position:absolute; top:10px; left:10px; min-height:0; }
+.image-choice img { display:block; width:100%; height:112px; object-fit:contain; }
+.image-choice span { display:block; text-align:center; margin-top:6px; }
+form button { display:block; width:100%; margin-top:12px; }
+.board-result { margin-top:24px; border-top:1px solid var(--line); padding-top:20px; }
+.board-result img { display:block; max-height:600px; margin:0 auto 16px; object-fit:contain; }
+.board-result a { display:inline-block; padding:9px 14px; border:1px solid var(--line); border-radius:8px; text-decoration:none; }
+@media(max-width:680px) { .board-layout { grid-template-columns:1fr; } form { order:-1; } }

package/plugins/contact-sheet/web/board.mjs

@@ -0,0 +1,93 @@
+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, signal }) {
+  const service = api.pluginOperations, urls = new Set(), timers = new Set();
+  const keyName = 'iris.contact-sheet.' + session.rootId, operationId = 'community.contact-sheet.create';
+  let request, selected = [], catalog, busy = false;
+  const intro = element('div', '', 'intro'); intro.append(element('h2', '让灵感，并排相遇。'), element('p', '选择现有图片，离线排成一张对照板。原图保持不变。', 'muted'));
+  const layout = element('div', '', 'board-layout'), choices = element('div', '', 'image-choices'), editor = element('form', '', 'card');
+  choices.setAttribute('aria-label', '选择来源图片');
+  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 i of [128, 256, 512]) size.add(new Option(i + ' px', String(i))); size.value = '256'; sizeLabel.append(size);
+  const count = element('p', '尚未选择图片', 'field-note'), submit = element('button', '制作对照板'); submit.type = 'submit'; submit.disabled = true;
+  const fresh = element('button', '新建一张', 'secondary'); fresh.type = 'button'; fresh.hidden = true;
+  const recover = element('button', '查询原操作', 'secondary'); recover.type = 'button'; recover.hidden = true;
+  const more = element('button', '加载更多图片', 'secondary'); more.type = 'button'; more.hidden = true;
+  editor.append(columnsLabel, sizeLabel, count, submit, recover, fresh, more);
+  const status = element('p', '正在读取现有作品…', 'field-note'); status.setAttribute('role', 'status'); status.dataset.boardStatus = 'true';
+  const output = element('section', '', 'board-result'); output.hidden = true;
+  layout.append(choices, editor); container.append(intro, layout, status, output);
+  function remember(value) {
+    request = value;
+    try { value ? sessionStorage.setItem(keyName, JSON.stringify(value)) : sessionStorage.removeItem(keyName); }
+    catch (_) { status.textContent = '浏览器无法保存恢复标识；请保留本次 Operation ID。'; }
+  }
+  function controls() {
+    const locked = busy || Boolean(request);
+    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' && operation.result.artifactIds.length) {
+      const id = operation.result.artifactIds[0], blob = await api.artifact({ id, mediaType: 'image/png' }); 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-contact-sheet-' + id + '.png';
+      output.replaceChildren(image, link); output.hidden = false;
+    } else if (['queued', 'running'].includes(operation.state)) {
+      const timer = setTimeout(() => { timers.delete(timer); void poll(operation.id); }, 450); timers.add(timer);
+    }
+  }
+  async function poll(id) { try { await present((await service.inspect(id)).operation); } catch (error) { if (!signal.aborted) { note(error); recover.hidden = false; } } }
+  editor.addEventListener('submit', async event => {
+    event.preventDefault(); if (busy || request || !selected.length) return;
+    const contribution = catalog.operations.find(item => item.id === operationId && item.available); if (!contribution) return;
+    busy = true; remember({ key: crypto.randomUUID(), operationId, dependency: contribution.dependency,
+      input: { artifactIds: selected, columns: Number(columns.value), cellSize: Number(size.value) } }); controls(); status.textContent = '正在保存本次操作…';
+    try { const result = await service.execute(request); await present(result.operation); }
+    catch (error) { if (!signal.aborted) { note(error); status.textContent += '。请查询原操作，未自动重做。'; recover.hidden = false; } }
+    finally { busy = false; if (!signal.aborted) controls(); }
+  });
+  fresh.addEventListener('click', () => { remember(null); output.hidden = true; output.replaceChildren(); fresh.hidden = recover.hidden = true; status.textContent = '选择图片后可以新建一次操作。'; controls(); });
+  async function lookup() {
+    try { await present((await service.lookup(request.key)).operation); }
+    catch (error) { if (!signal.aborted) { note(error); recover.hidden = false; if (error.status === 404) fresh.hidden = false; } }
+  }
+  recover.addEventListener('click', () => { if (!busy && request) void lookup(); });
+  signal.addEventListener('abort', () => { for (const timer of timers) clearTimeout(timer); for (const url of urls) URL.revokeObjectURL(url); }, { once: true });
+  if (!service) { status.textContent = '此服务未开启插件业务执行。'; return; }
+  catalog = await service.catalog({ limit: '30' }); signal.throwIfAborted();
+  async function appendImages(page) { for (const artifact of page.artifacts) {
+    const label = element('label', '', 'image-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.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(); });
+  } 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.throwIfAborted(); await appendImages(catalog); }
+    catch (error) { if (!signal.aborted) note(error); }
+    finally { busy = false; if (!signal.aborted) controls(); }
+  });
+  await appendImages(catalog);
+  if (!catalog.artifacts.length) choices.append(element('p', '当前没有可用图片，请先通过现有创作入口或 CLI 导入。', 'muted'));
+  status.textContent = '最多选择 16 张图片，不调用模型。';
+  try { const saved = sessionStorage.getItem(keyName); if (saved) request = JSON.parse(saved); }
+  catch (_) { status.textContent = '原恢复标识无法读取，请先核对业务记录。'; }
+  if (request) await lookup();
+  controls();
+  return () => { for (const timer of timers) clearTimeout(timer); for (const url of urls) URL.revokeObjectURL(url); container.replaceChildren(); };
+}

package/skills/iris-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: iris-core
-description: "Create, edit, and retrieve persistent Iris images through the standalone CLI without a running DSH host. Use for local image imports, revisions, existing task inspection, and artifact export."
+description: "Create, edit, and retrieve persistent Iris images through the standalone CLI without a running DSH host. Use for API images, configured ComfyUI workflows and LoRA parameters, local imports, revisions, task recovery, and artifact export."
 ---
 
 # Iris Core · 核心图片工作流
@@ -11,13 +11,17 @@ Organize the work around the image the user wants to receive. Reuse existing ass
 
 Use the [standalone CLI reference](references/cli.md) to confirm the installed command, explicit data root, and private provider configuration needed for generation. Reuse information already established in the conversation. Do not scan another application's configuration or assume a personal directory, provider, or model.
 
-A visible skill does not prove that its execution tools are available. Report a missing command, connection, or capability precisely. This edition binds to the existing CLI; future MCP and independent workbench integrations need their own verified invocation instructions.
+A visible skill does not prove that its execution tools are available. Report a missing command, connection, or capability precisely. This skill binds to the CLI. For an explicitly selected MCP connection, use its connection-specific skill and actual authorized tools; do not bypass a missing MCP capability through the CLI.
+
+## Clarify a ComfyUI request · 先确认工作流与要求
+
+For ComfyUI, read the [workflow, parameters, LoRA and recovery reference](references/comfyui.md). Ask a concise, bundled question for missing image requirements, workflow choice and parameter preferences before creating or executing work. Read-only catalog inspection may help the user choose. Reuse answers and authorization already given; a complete request needs no repeated questionnaire. API-only requests follow their established configuration and do not require ComfyUI setup questions.
 
 ## Plan the image work · 按作品组织步骤
 
 - Import a local image when it needs to become a persistent source. Reuse an existing Artifact in the current root without importing it again.
 - Generate for a new image request. For a revision, pass the source Artifact and requested changes to create a related version while retaining the original. Retrieve existing results instead of regenerating them.
-- Omit the model override unless the user specifies one, allowing the configured capability policy to select candidates. An explicit model must be allowed for that capability. Names, catalog entries, and past success do not establish present availability.
+- For ordinary API work, use the configured capability policy when it matches the user's choice. If the pool mixes API and ComfyUI, choose an actual allowed API reference explicitly to keep an API-only request on that path. ComfyUI always uses a specific workflow confirmed from the current catalog; never guess from a model family name. Names, catalog entries, and past success do not establish present availability.
 - Add only steps needed for the requested result. An explicit edit can proceed directly; a generation request does not require extra paid vision checks or another generation.
 - Wait for actual delivery before starting a dependent operation. When content verification is required, use an image-reading capability available in the current host. Metadata and file existence alone do not establish visual correctness.
 
@@ -37,4 +41,4 @@ Preserve the original Task after interruption or unknown acceptance; do not prob
 
 Return the actual image file or a host-accessible asset, with the Task/Artifact IDs needed to continue. Distinguish availability, export, display in the conversation, and visual verification. Report partial results and unmet conditions accurately.
 
-This edition covers images and their tasks. It does not imply support for video, speech, UI operations, or a production MCP service in this entry point. Existing DSH skills continue to guide DSH-native tools and workbench workflows.
+This skill covers images and their tasks. The ComfyUI path requires 0.3.0-alpha.1 or compatible source; stable npm 0.2.7 does not include it. Check the actual installed version. Existing DSH skills continue to guide DSH-native tools and workbench workflows.

package/skills/iris-core/references/cli.md

@@ -2,7 +2,7 @@
 
 The current executable binding is `dsh-iris`, which uses shared Application/Core operations without a running DSH host. Check the installed command with `dsh-iris --help`. In a confirmed source checkout, `node /absolute/path/to/iris/bin/dsh-iris.js` is also available. A missing command does not authorize installing software or changing package versions.
 
-These image, artifact, and task commands exist in 0.2.6. This skill is a new, unreleased package resource. Development-only Flow commands, local HTTP writes, and a future UI are not prerequisites.
+These image, artifact, and task commands exist in 0.2.6; the Core skill is bundled from 0.2.7. The development [ComfyUI reference](comfyui.md) has its own version and parameter requirements. Flow commands and a workbench are not prerequisites for the standalone API image path below.
 
 ## Establish the context · 明确本次上下文
 
@@ -50,7 +50,7 @@ Write the user's original or authorized revised request into the input file, for
 dsh-iris run image --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE" --input-file "$IRIS_INPUT_FILE"
 ```
 
-Set `n` to the requested count (1–4); do not increase it for testing. Supply `size` only when requested and supported. Omit `model_ref` unless a model was specified; use an allowed `providerId::modelId` for an explicit choice. An explicit choice has no candidate fallback. Default candidate switching requires evidence of non-acceptance.
+Set `n` to the requested count (1–4); do not increase it for testing. Supply `size` only when requested and supported. Use the configured API policy when it matches the request; explicitly select an actual allowed API model when a mixed pool could choose ComfyUI. ComfyUI always requires the confirmed workflow and `n:1`; follow its separate reference. An explicit choice has no candidate fallback. Default candidate switching requires evidence of non-acceptance.
 
 ## Edit an existing image · 编辑已有图片
 

package/skills/iris-core/references/comfyui.md

@@ -0,0 +1,69 @@
+# ComfyUI workflows · 工作流、参数与 API 搭配
+
+This reference describes the **0.3.0-beta.1 implementation**, not stable npm 0.2.7. Confirm the installed command and returned catalog before using it; missing support does not authorize installing or upgrading software. Keep the explicit roots and private provider file from the [CLI reference](cli.md).
+
+## Ask before creating · 提问确认需求
+
+ComfyUI selects an executable workflow with its own exposed controls. Before creating or executing a request, establish:
+
+- The desired subject, style, changes and output. Ask whether a source image must be preserved when the request suggests editing.
+- The configured workflow to use, or whether the user prefers API generation or wants a recommendation from the available workflows.
+- Any required LoRA and separate model/CLIP weights; size, seed or reproducibility requirements. Offer to keep the workflow defaults for unspecified settings; do not require the user to understand every sampler control.
+
+Ask only for missing information, preferably in one compact question. For example: “What should the image contain and look like? Which of these configured workflows should I use? Do you need a particular LoRA, size or seed, or should I keep that workflow's defaults?” Use the user's language and real catalog choices. If the user delegates selection, choose a suitable actual workflow and state the choice and assumptions. Reuse established answers and authorization; do not ask again before each already authorized stage.
+
+Read-only directory inspection may precede the question. While essential choices remain unanswered, do not generate a sample, create a trial Run/Task, change a provider, or install a workflow/model. A missing workflow is a configuration gap to explain, not permission to fabricate a template or silently substitute an API model.
+
+## Read the actual directory · 使用真实目录
+
+```bash
+dsh-iris models list --provider-config "$IRIS_PROVIDER_FILE"
+```
+
+Choose the returned model `ref`. A `comfyWorkflow` summary identifies the configured template; read its `parameters` for actual IDs, labels, types, defaults, ranges and declared choices. Use `imageRouting` and edit support to distinguish API models from workflows, rather than guessing from names such as SDXL or Flux. A configured entry is not proof that the service, nodes or GPU are usable.
+
+LoRA names belong to **existing workflow slots**. Read current available choices through an explicit read-only workflow check when needed and authorized. The check queries node definitions without generating or changing configuration; it cannot establish real inference success. If options are truncated, do not claim an unseen name was verified. Ask for the intended installed name or retain the confirmed default.
+
+Only override declared parameter IDs and supported scalar values. Keep model and CLIP weights separate, including zero/negative values when allowed; do not set them equal without the user's intent. Multiple LoRAs require existing slots in the workflow. A fixed v0 template exposes no runtime parameters. Do not invent a node, a LoRA filename, an arbitrary graph patch or an undeclared negative-prompt field. Integer seeds must fit the JavaScript safe range; keep sampler defaults unless a change is requested or delegated.
+
+## Execute the selected path · 执行明确入口
+
+For CLI image generation, write the approved input to a new private JSON file: actual `model_ref`, `prompt`, `n:1`, optional supported `size`, and optional `workflow_parameters` containing only requested overrides. Omit an empty parameter map. Omit size when the workflow has no size binding. Then use the existing image entry:
+
+```bash
+dsh-iris run image --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE" --input-file "$IRIS_INPUT_FILE"
+```
+
+An optional static check uses a **separate** input file containing just `workflow_parameters` with the same approved overrides; omit `--input` if there are none:
+
+```bash
+dsh-iris models workflow-check "$IRIS_MODEL_REF" --provider-config "$IRIS_PROVIDER_FILE" --input "$(cat "$IRIS_CHECK_FILE")"
+```
+
+The file contains data, not executable shell text. Never substitute prompt text directly into shell code. Read the check's `ok`, issues and limits; exit code 0 alone is not a passing inspection. Checking and generating are separate actions.
+
+For persistent Flow creation, the input also uses `model_ref` and `workflow_parameters`. Text-to-image requires an explicitly initialized new v2 execution root; do not migrate an existing root. Create once, keep the returned Run, and explicitly continue it. A Flow retains private request input, while a standalone Task does not retain the prompt. Follow the invocation supported by the installed version rather than switching formats mid-task.
+
+For an authorized MCP connection, follow its generated skill and actual tool schemas: the directory returns `modelRef`, creation uses `workflowParameters`, and creation saves a Run without generating. A missing directory or execution tool is a capability gap; do not call an unavailable tool or switch to shell commands to bypass it. Owner workflow checks are not automatically available through media MCP tools.
+
+## Combine API and ComfyUI · 选择与串联
+
+| User goal | Supported approach |
+|---|---|
+| A quick API image | Use the configured API policy or an explicit allowed API model; skip the ComfyUI questionnaire unless the request needs it |
+| An existing workflow, LoRA or controlled seed | Confirm the actual ComfyUI workflow and exposed parameters before generation |
+| ComfyUI base image, followed by API revision | Generate once, wait for the original Artifact, then pass that same-root Artifact to an explicitly chosen API model that supports editing |
+| API image refined by ComfyUI | Explain that the current Iris ComfyUI adapter has no source-image upload/binding; do not claim a reverse image-edit chain works |
+| Compare API and ComfyUI | Only when requested, plan two independent generations and their additional work/cost; keep distinct task identities, then show actual results |
+
+For the supported ComfyUI → API chain, use the existing image-edit input: `source_artifact_id` for CLI or `sourceArtifactId` for MCP. Do not carry `workflow_parameters`/`workflowParameters` into the API edit. Both stages need their actual permissions and user intent; authorization for the whole stated chain need not be requested again per step. Keep the original image and the second stage's lineage. If stage two fails, recover stage two instead of regenerating stage one.
+
+Do not silently switch backends as recovery. An API substitute may lose LoRA, workflow or seed semantics. If a substitute is already authorized, establish the original request's acceptance and what tradeoffs that authorization covers; unknown acceptance still requires preserving the original task and any possible duplicate work/billing. Never rebind an old Task/Run to a different model or new template.
+
+## Recover original facts · 恢复原任务
+
+- Standalone CLI: inspect the returned Task in its original root, then use [task recovery](tasks.md) to observe, wait or redeliver that same Task. Preserve it when acceptance is unknown; do not test by submitting again.
+- Persistent Flow/MCP: retain Run/Operation/Task/Artifact IDs, current Run revision and original request UUIDs. Read the original records after interruption. An Operation completing does not prove the remote image completed; explicitly continue the original Run only when authorized and supported by its state. Do not apply standalone Task retry to work around a Flow binding.
+- A lost creation reply does not justify a new key. Recover the original creation identity when the selected entry supports it; otherwise read the original records and report any remaining uncertainty before further work.
+- Query the original remote job rather than rechecking node catalogs as a substitute for task observation. A changed template can block old-task rebinding; preserve the old record and explain the mismatch.
+- Stopping local waiting is not confirmed remote cancellation. The current ComfyUI adapter does not send `/interrupt`. Retrieve and present the actual delivered image; visual quality requires viewing it, not just reading metadata.

package/skills/iris-core/references/tasks.md

@@ -2,6 +2,8 @@
 
 Inspect the Task in its original data root first. Tasks do not persist prompts; do not reconstruct the user's input from a task summary. Inspection has no provider side effects. Observe or recover only as needed for the current request.
 
+For ComfyUI and mixed API work, see [workflow and recovery details](comfyui.md). Keep each stage's original Task. A persistent Flow uses its original Run/Operation and binding; do not use a standalone retry to change that Flow's model or template.
+
 | Recorded fact | Action |
 |---|---|
 | Accepted and still queued/running | Observe or wait for the original Task; do not create another generation |

package/templates/plugin-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.

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