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

package/docs/AGENT_CORE_QUICKSTART.md

@@ -0,0 +1,64 @@
+# Agent Quickstart · Core 与 MCP 接入指导
+
+For **0.3.0-alpha.1 Core Web/MCP**, use the [Core quickstart](CORE_QUICKSTART.md). Stable npm **0.2.7 has CLI/DSH support, without this Web/MCP entry**; use [the stable Agent guide](AGENT_QUICKSTART.md) for it. Install the exact alpha or explicitly choose the alpha channel.
+
+Give this instruction to an Agent helping with setup:
+
+```text
+Help me use Iris (@mokuyoaxis/dsh-iris). First read README and check the actual
+installed package or source revision, Node version and available CLI commands.
+Distinguish stable 0.2.7 from the 0.3.0-alpha.1 Core workbench/MCP implementation.
+Installing latest does not opt into alpha; use the exact prerelease or alpha tag.
+Do not install a different package, upgrade the host or migrate a data root silently.
+
+Ask which path I want: the Core workbench, an existing Iris MCP connection,
+direct CLI, or DSH's native plugin. If a suitable Core already runs, reuse it.
+Otherwise follow docs/CORE_QUICKSTART.md in an explicitly chosen new private root.
+Never scan my disk for clients, credentials or other workspaces. Ask before a new
+dependency installation, changing authentication policy or restarting my services.
+
+Let me enter my media service credentials in the workbench. Never print secrets.
+Confirm the documented protocol, actual model IDs, intended uses and pool policy.
+A directory response, configured capability or successful handshake is not a
+successful media test. Opening a draft must not trigger generation.
+
+For MCP, create a named connection only with the media/business, operation scopes
+and tools I choose. Generate the matching client template in Iris. Merge just its
+entry into the explicitly chosen client config; preserve other entries and keep
+the exported credential private. Both stdio and HTTP require the same Core to run.
+Do not start another writer, wrap Iris CLI in a fake MCP server, or use CLI/Shell
+to bypass an MCP connection's permissions.
+
+Optionally install the generated connection Skill in the client's explicit Skills
+directory. It describes only effective MCP tools; the CLI iris-core Skill is for
+direct CLI use. Installing a Skill does not establish a connection or grant access.
+
+After connection, discover the actual tools and configured models. Carry out only
+my requested media task. Keep each write's original request UUID and inspect its
+receipt. Accepted is not complete; an interrupted/unknown request must not be
+replaced by another generation. Read back the actual artifact before describing
+it, and say explicitly if this client cannot display its content.
+
+Report package/source identity, selected permissions, actual handshake, Run/Task/
+Operation/artifact IDs where available, result state and what was not verified.
+Never claim paid-provider or GPU success from a controlled replay or static check.
+```
+
+## When MCP is already connected · 已连接时
+
+The client does not need the owner's password or provider keys. Use the actual connection tools and catalog; do not add tools because a different Iris installation exposes them.
+
+| Intent | Action |
+|---|---|
+| Inspect configured choices | Read the returned model/workflow directory; preserve exact references and declared parameters |
+| Create media | Confirm the requested content and required parameters, then create once and explicitly execute the returned Run |
+| Resume an uncertain request | Look up its original request UUID or Operation; report unknown acceptance without resubmitting |
+| Read results | Fetch the original artifact through this connection; distinguish metadata, actual bytes and rendered content |
+| Missing permission or business | Explain the actual denial; ask the owner to change the connection if needed, then reconnect |
+| Core unavailable | Report transport failure; do not initialize a new root or steal its writer lease |
+
+For ComfyUI, clarify the desired workflow, source image, style/LoRA and exposed parameters first. Read names, defaults and choices from the selected workflow's actual directory. Do not invent a checkpoint, LoRA, graph patch or parameter ID. See [the ComfyUI reference](../skills/iris-core/references/comfyui.md).
+
+## Verification scope · 验证边界
+
+Repository evidence includes real Core persistence, production MCP transports and isolated real-model sessions in Kimi Code and Codex. These are specific tested clients and versions, not a guarantee for every client. The fresh-workspace walkthrough uses a controlled local media replay; real paid media and a live ComfyUI GPU require separate deployment checks. Start with a read-only task, then explicitly authorize the media operation you actually need.

package/docs/AGENT_QUICKSTART.md

@@ -1,17 +1,19 @@
 # 给 AI Agent 的简要 Prompt
 
+先选择入口：0.3.0-alpha.1 的 Core 工作台/MCP 使用 [Agent Core 指导](AGENT_CORE_QUICKSTART.md)与[从零启动](CORE_QUICKSTART.md)；下面的安装提示保留面向**稳定 0.2.7 的 DSH / CLI**，不是新 MCP 配置步骤。
+
 把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
 
-下列 npm 示例对应 Iris 0.2.6，准确范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。执行安装命令前确认所选发行包的实际版本、工具和功能策略。
+下列 npm 示例对应 Iris 0.2.7，准确范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。执行安装命令前确认所选发行包的实际版本、工具和功能策略。
 
 ## 中文
 
 ```text
 请根据本仓库 README，帮我安装并使用 Iris（@mokuyoaxis/dsh-iris）。
 先确认运行环境、目标 DSH profile，并用 dsh --version 核对宿主；Iris 0.2.x 要求 Node.js >=22.0.0（旧 npm 0.1.4 的历史要求为 >=20.10.0）：
-- DSH在docs/DSH_COMPATIBILITY.md列出的12个准确版本中：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6；只下载用 npm pack @mokuyoaxis/dsh-iris@0.2.6。
+- DSH在docs/DSH_COMPATIBILITY.md列出的12个准确版本中：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7；只下载用 npm pack @mokuyoaxis/dsh-iris@0.2.7。
 - 未列入所选Iris版本兼容矩阵的DSH：先报告没有支持声明，不自行升级宿主或跳过版本检查。
-没有DSH、希望用CLI时，按docs/HEADLESS_CLI.md使用npm0.2.6；npm0.1.4不含当前Core媒体CLI。
+没有DSH、希望用CLI时，按docs/HEADLESS_CLI.md使用npm0.2.7；npm0.1.4不含当前Core媒体CLI。
 先用--help和Doctor核对实际版本与命令。可引用DSH已有API Key连接，再确认模型用途并主动启用自动池，或保留手选名单；旧空配置不自动启用。DSH默认视觉须明确加入或启用。目录新增模型仍需确认用途；不以实测请求探测配置。图片导入用iris_import_image，改图用iris_edit_image；音乐用iris_generate_music并配置Chat Completions（内嵌音频）协议，见docs/MUSIC.md。
 从dsh-market安装也要核对实际包名、版本和兼容范围；缓存的旧版安装信息仍按其历史矩阵判断。
 若使用其他 profile，把示例中的 web 换成已确认的目标。保留完整 scoped 包名，不把 dsh-iris 当作同一 npm 包。
@@ -25,9 +27,9 @@
 ```text
 Help me install and use Iris (@mokuyoaxis/dsh-iris) according to this repository's README.
 Check the environment, target DSH profile, and dsh --version first; Iris 0.2.x requires Node.js >=22.0.0 (the published npm 0.1.4 historically requires >=20.10.0):
-- For one of the twelve exact DSH versions in docs/DSH_COMPATIBILITY.md, pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6; download only with npm pack @mokuyoaxis/dsh-iris@0.2.6.
+- For one of the twelve exact DSH versions in docs/DSH_COMPATIBILITY.md, pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7; download only with npm pack @mokuyoaxis/dsh-iris@0.2.7.
 - DSH versions outside the selected Iris version's matrix: report the missing support claim; do not upgrade the host or bypass its version checks automatically.
-For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm0.2.6; npm0.1.4 lacks the current Core media CLI.
+For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm0.2.7; npm0.1.4 lacks the current Core media CLI.
 Check --help, Doctor and the actual installed version. Reference a DSH API-key connection when available, confirm model uses, and explicitly enable automatic pools or retain selected-only lists. Existing empty configurations stay inactive. Host vision and new directory models require explicit authorization. Do not probe paid models to check configuration. Use iris_import_image for import, iris_edit_image for editing, and iris_generate_music with its configured inline-audio protocol for music.
 For dsh-market, check the actual package name, version, and compatibility range too. Cached older releases retain their historical compatibility matrices.
 Replace web with the confirmed profile when needed. Keep the scoped package name; unscoped dsh-iris is a different npm package.

package/docs/ARCHITECTURE.md

@@ -1,10 +1,14 @@
 # Iris 架构与边界
 
-状态：本文描述 **Iris0.2.5** 的架构。0.2.0建立实例化Core Runtime、Headless CLI及共享Task/Artifact事实；后续加入共享视觉、图片编辑、音乐和交付恢复。0.2.4补图片导入、原生Qwen改图和统一功能分配；0.2.5按接口能力恢复旧宿主支持。准确版本及历史发行范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。Node.js最低22.0.0；Core内部API尚未冻结为公共SDK。
+状态：本文说明 **Iris 0.3.0-alpha.1** 的共享Core及Web、MCP与插件装配，并保留0.2.7入口图作历史对照。0.2.0建立实例化Core Runtime、Headless CLI及共享Task/Artifact事实；后续加入共享视觉、图片编辑、音乐和交付恢复。0.2.5恢复旧宿主支持，0.2.6增加连接引用、可选功能自动池和目录同步。准确版本及历史范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。Node.js最低22.0.0；Core与插件契约仍为实验性。
 
 ## 当前形态
 
-Iris 仍以一个 npm 包交付，但已有两个执行入口：DSH 插件负责 Agent 工具、会话附件、浏览器、Web UI 和后台观察；Headless CLI 在没有 DSH/Cordis 的进程中显式接收数据根与私有 Provider 配置。两者共用 Core Runtime、Provider Task Runner、Task/Artifact Store 和本地 Command，不能在同一数据根上同时充当写者。
+当前源码的 [Core 工作台](LOCAL_WEB.md)已连接真实持久执行、停止、作品选择和供应商管理；[通用 MCP](MCP.md)及[显式插件贡献](PLUGINS.md)复用同一服务与授权边界。图片生成/编辑、语音/转写和插件业务按用户所选范围启用。下方示意图表示 0.2.7 已发布入口，完整当前覆盖见 [README](../README.md#当前入口覆盖)。
+
+0.3 alpha源码另提供独立 [Panel/主题](PANEL_EXTENSIONS.md)和 [C3 供应商设置](PROVIDER_SETTINGS.md)：页面可显式替换，配置管理复用应用层原子写入；默认媒体权限与 Core Task/Artifact 格式保持。它们不随已发布 0.2.7 提供，也不自动替换 DSH 内嵌 UI。
+
+Iris仍以一个npm包交付。DSH插件负责原生Agent工具、附件、浏览器和内嵌UI；Headless CLI与独立Core服务（Web/MCP）在没有DSH/Cordis的进程中接收明确数据根和私有Provider配置。各入口共用Core Runtime、Provider Task Runner、Task/Artifact Store和本地Command，不能在同一根同时充当写者；MCP桥连接已有Core服务，不另建业务写者。
 
 ```text
 DSH Host / Cordis                         Headless CLI
@@ -33,7 +37,9 @@ DSH Host / Cordis                         Headless CLI
                     CLI: explicit absolute data root
 ```
 
-`lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 只负责选择 DSH profile 的 Core 数据根、恢复 Provider 配置和投影 Host DTO。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
+`lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 负责 DSH 的 Core 实例装配、Provider 连接解析和 Host DTO 投影。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
+
+0.2.7 增加 `lib/application-runtime.js`，首批 CLI 图片命令和固定改图流程通过它装配 Core；[DSH 实例](DSH_RUNTIME.md)也已接入同一队列机制。写队列、操作取消和关闭归属于应用实例；每次写操作独立取得、释放 Core 租约，DSH 的 Core 观察器由插件实例持有并等待卸载。[固定流程](IMAGE_FLOW.md)使用专用根中的版本化 Run、稳定 Task/比较作品身份及引用保护，私有输入保存提示词，Task 仅保存可选流程绑定。[本地 API](LOCAL_API.md)已提供默认只读与主动启用的 [本地创建](LOCAL_CREATION.md)，在 0.2.7 中，执行/取消和真实独立 Web 尚未提供，现已接入上文的0.3 alpha源码；通用 Recipe 仍待实现。详见 [应用运行时契约](CORE_RUNTIME_CONTRACT.md#应用运行时装配)。上图表示已发布入口的共同核心。
 
 0.2.1的 S2V 使用 Core Task/Attempt，HTML 使用 `media.html` 与显式 Browser Port；视觉和提示词预览通过共享 Model Ports 执行。纯视觉不创建 Task/Artifact，摘要主动转写仍使用 Core 任务。聊天改图属于媒体生成链，按来源 Artifact ID 创建新 Task 和关联产物。
 
@@ -42,6 +48,8 @@ DSH Host / Cordis                         Headless CLI
 | 模块 | 职责 | DSH 运行时依赖 |
 |---|---|---:|
 | `core-contract.js` / `core-runtime.js` / `core-writer-lease.js`（0.2.2） | 显式数据根、reader/writer 权限、单写者租约、取消与释放 | 无 |
+| `application-runtime.js` | 实例写队列、操作输入快照与 Core 装配；首批由 CLI 消费 | 无 |
+| `flow-store.js` / `image-flow.js` | 专用根、私有 Run 输入、固定步骤绑定、原任务恢复与用户选择 | 无 |
 | `command-service.js` | 本地媒体命令、Task 控制面和 Artifact 查询/导出 | 无 |
 | `generation-input.js` | CLI、DSH 与重试共用的生成参数校验和 Provider 字段转换 | 无 |
 | `model-port-contract.js` / `model-invoker.js` | Text/Vision 内部契约、有限调用预算与取消 | 无 |
@@ -59,6 +67,12 @@ DSH Host / Cordis                         Headless CLI
 
 完整规则见 [Core Runtime v0](CORE_RUNTIME_CONTRACT.md)、[Artifact Manifest v0](ARTIFACT_MANIFEST.md)、[Provider Adapter v0](PROVIDER_ADAPTER_CONTRACT.md) 与 [DSH → Core 渐进迁移](DSH_CORE_MIGRATION.md)。这些仍是内部契约，不是第三方 SDK 兼容承诺。
 
+面向 0.3 的0.3 alpha源码增加[Provider 扩展首版](PROVIDER_EXTENSIONS.md)：实例拥有协议描述、工厂、活动调用和异步释放；CLI/Core 服务显式传入注册实例，六类内置协议（含 ComfyUI）与外部协议共用候选/健康/恢复。实验性包入口仅开放媒体协议所需接口，尚未提供 DSH 外部模块加载设置、通用 Recipe 或完整 SDK。ComfyUI Task binding 另纳入模板摘要，见 [文生图与工作流入口](IMAGE_GENERATION.md)；原五类协议的 binding 与既有记录保持。
+
+同属0.3 alpha源码的 [Core 插件贡献 v0](PLUGINS.md)统一五类贡献的身份、兼容与生命周期。新插件 Provider 的 Task/Attempt 在提交前记录准确依赖，旧绑定保持。默认 Panel 可显式组合页面/设置/预览，共享主题、认证客户端和会话；公开装配保持媒体只读，设置沿用 Core Provider 管理，整套替换仍可用。另由 `allowedOperations` 明确选择持久业务，复用同一单根 runner/FIFO/租约及有版本 `plugin.execute` 记录；Core绑定输入/来源、预留输出身份并管理实际作品存储。[多图对照板](CONTACT_SHEET.md)只引用公开 SDK 和现有 Sharp，已贯穿 Web、用户选择、通用 MCP 与原记录恢复。无稳定 SDK、市场或旧数据迁移。
+
+Core能力目录派生MCP/DSH、Web选项/会话和Skill，投影五类贡献的真实边界。注册/发现不授权，旧工具名单不扩张。MCP用通用目录/执行工具投影连接明确保存的准确业务依赖，Core在接受和后续命令处检查有效权限；断开代理不停止Core。重启只记录interrupted，插件缺失或版本变化不重放，原作品/记录仍可读取。实例生命周期由装配者持有，先关服务再关注册器。
+
 0.2.2 的 Core writer 在创建目录前发布完整 owner 意图，释放和显式恢复通过整体退役保留证据；普通启动不抢占。非图片 staging 复用文件复制接收与分块哈希，图片格式验证和 inline 解码仍可能使用完整 Buffer，不声称端到端流式传输。
 
 ## Task、Attempt 与 Artifact
@@ -74,7 +88,9 @@ DSH Host / Cordis                         Headless CLI
 
 ## Provider 边界
 
-0.2.4将六类功能统一为严格有序分配名单：不补入全局池，临时指定只绑定名单内单项。DSH默认视觉为显式宿主资源，不作为隐式兜底；手动实测与旧任务恢复保持独立。配置格式、Core受理纪律与生产依赖保持。升级范围见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。下方0.2.2描述保留当时能力声明变更的背景。
+0.2.6 的六类功能可选择自动池、仅用所选模型或停用。自动池只从已确认用途的模型中按稳定顺序选择，不授权目录新条目，也没有跨请求轮转；旧名单和缺失/空分配不自动启用。DSH 默认视觉仍需明确加入允许范围，手动实测与旧任务恢复保持独立。连接引用由 DSH Adapter 在操作期间解析，Core 不接收宿主凭据引用。详见 [功能模型池](FUNCTION_MODEL_POOLS.md)与 [连接复用](DSH_PROVIDER_CONNECTIONS.md)。
+
+0.2.4/0.2.5 的严格有序名单规则见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。下方 0.2.2 描述保留当时能力声明变更的背景。
 
 0.2.2按功能组织有序模型候选池，能力来自明确模型标签、旧能力字段绑定或供应商能力元数据。裸账号不物化默认模型，模型名称不授权进入候选链；明确空池与空标签保持权威。模型与供应商复合身份用于底层执行器，功能入口、分配排序及安全 failover 没有改为模型中心产品或默认轮转。旧 0.2.1 的能力推断行为不再用于裸账号或模型名称赋能。
 

package/docs/AUDIO_FLOWS.md

@@ -0,0 +1,71 @@
+# Core 语音合成与音频转写（0.3 alpha）
+
+0.3.0-alpha.1的 Web 与通用 MCP 接入 `speech/v0`、`transcribe/v0`，共用现有 Provider、Task/Attempt、持久 Run 和单根 Operation runner。**稳定 npm 0.2.7 不含这些新增入口。** 原独立 CLI/DSH 的语音和转写继续使用各自原入口；这里描述新的 Core 流程。
+
+## 新建音频工作区
+
+先在新的专用位置初始化，保留原图片工作区：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/new-audio-core
+node bin/dsh-iris.js execution init --data-root /absolute/new-audio-core --audio
+node bin/dsh-iris.js web serve --data-root /absolute/new-audio-core \
+  --provider-config /absolute/existing-providers.json \
+  --token-file /absolute/new-audio-owner-token --allow-execution
+```
+
+`--audio` 建立 `creation-requests/v3`，同时支持原图片编辑/生成。不要与 `--image-generation` 混用，也不要在已有 v0/v1/v2 根上执行迁移；原根继续按原能力运行。省略两个开关的 `execution init` 仍建立 v1 图片编辑根，`--image-generation` 仍建立 v2。
+
+打开输出的 `loginUrl`；刷新保留当前标签页登录，过期后可用 `web login` 获取新链接，见 [工作台登录](LOCAL_WEB.md#启动与连接)。播放和下载已有结果无需 Provider；新建 Run 需要显式配置，执行另需 `--allow-execution`。音频不需要 `--allow-selection`。
+
+配置沿用[模型服务](PROVIDER_SETTINGS.md)：为模型明确确认 TTS/转写用途和功能池，再从实际候选中选择。候选不是健康证明，打开页面不做实测。内置音频协议沿用现有 DashScope 实现；配置了 OpenAI 图片接口不等于接入 OpenAI TTS/ASR。这里没有新增语音协议、模型自动替换或音色发现接口。
+
+## 页面使用
+
+- **语音合成**：选择实际语音模型，填写朗读文字，必要时展开音色并填该模型支持的标识；留空使用现有协议默认值。点击合成后，保存输入、明确执行一次、保存原音频，可试听并下载。
+- **音频转写**：选择 WAV/MP3/OGG/FLAC 原音频及转写模型。点击开始后先保存来源作品和 Run，再在原 Task 的 Attempt 内临时上传、提交。异步任务显示“查看原任务”；每次明确点击只观察一次，不持续远端轮询。
+- **作品**：v3 工作区按图片、语音、转写分类。语音卡片点击“载入试听”后获取原音频；同一时间只保留一个作品卡播放器，离页或切分类释放。转写文字在流程页以纯文本显示，原音频可播放，文字可下载。
+
+生成音频/转写是单一结果，保存后即可下载，无需图片版本选择。下载保留原字节；实际落盘以浏览器下载记录为准。离开创作页暂停播放，退出或切换流程释放相应媒体。当前不提供流式合成、音色目录、录音、长音频切片、字幕时间轴或本地 TTS。
+
+## 有限 HTTP 契约
+
+以下均以 `/api/v0` 开头，保留 Bearer、Host/Origin、无 CORS 和有限权限。新路由只在 v3 根开放；创建使用原 UUIDv4 `Idempotency-Key`，首次 201、同 Key 同输入 200、不同输入 409。
+
+| 路由 | 输入与结果 |
+|---|---|
+| GET/HEAD `/audio-models` | 实际允许的 `modelRef/displayName/capability`；capability 为 tts 或 transcribe，无端点/密钥，无探测 |
+| POST `/audio` | 原音频字节与精确 Content-Type；保存 `imported-audio`，不上传 Provider、不转写 |
+| POST `/speeches` | `{modelRef,text,voice?}`；创建固定 speech Run，不合成 |
+| POST `/transcriptions` | `{modelRef,sourceArtifactId}`；来源必须是当前根支持的音频作品，不接受外部 URL 或服务器路径，不上传/转写 |
+| GET/HEAD `/artifacts/:id/audio` | 原 WAV/MP3/OGG/FLAC 字节；现有 `/content` 仍只读图片 |
+| GET/HEAD `/artifacts/:id/text` | 原 `text/plain` 字节，不作为 HTML 展示 |
+| GET/HEAD `/runs?kind=all\|image\|speech\|transcribe` | 同一组实际记录上的分类、计数与有界分页；省略 kind 为 all |
+| GET/HEAD `/runs/:id/download` | 音频 Run 的单一已保存输出，受控 wav/mp3/ogg/flac/txt 附件名；图片仍要求明确选择 |
+
+`/runs/:id`、`/continue`、Operation 查询/原 Key 接回和本地停止沿用[执行契约](CORE_SERVICE.md)。音频 DTO 使用原 recipe；speech.input 为 `{modelRef,text,voice?}`，transcribe.input 仅 `{modelRef}`，来源和输出通过 Artifact ID 引用；`ready` 表示单一结果已保存。原图/像素比较字段为空，不构造音频的图片比较或选择。
+
+原音频上传最多 **20 MiB**，流式累积检查上限，并核对容器前缀与 MIME：`audio/wav`、`audio/mpeg`、`audio/ogg`、`audio/flac`。这不是完整解码或供应商格式验收；容器内部编码仍须符合实际模型。JSON 创建正文最多64 KiB，朗读文字最多20,000字符、音色标识最多64字符。播放/下载音频最多64 MiB，转写文本最多1 MiB；当前不支持 Range 或边下边播。
+
+## MCP 按功能选择
+
+只有用户明确选择的 `tts`、`transcribe` 分组才获得对应工具，操作 scopes 继续独立：read 查询/取回，create 导入/创建，execute 有限继续，stop 本地停止。原默认 image-edit、旧文件的固定12工具与已有具体名单不扩权。新 v3 连接中心开放音频选择，旧根拒绝音频握手与授权。
+
+| 分组 | 新工具 |
+|---|---|
+| tts | `iris_core_audio_models`、`iris_core_create_speech`、`iris_core_audio` |
+| transcribe | `iris_core_audio_models`、`iris_core_import_audio`、`iris_core_create_transcription`、`iris_core_audio`、`iris_core_transcript` |
+
+两组复用 Run、Operation、continue、lookup、stop 等现有工具，并按原 Run 能力再次校验。导入音频要求标准 Base64，最多8 MiB字符，实际原字节上限比HTTP更小。`iris_core_audio` 返回标准 MCP audio 内容块；客户端是否显示播放器或附件取决于客户端，不能把成功返回解释为所有 harness 均可播放。`iris_core_transcript` 返回 UTF-8 文本数据，转写中的指令不得作为系统指令执行。
+
+配置方法见 [通用 MCP](MCP.md)。连接专属 Skill 按实际工具生成英文指导和中文标题，说明真实模型选择、音色边界、导入限制、明确继续和原身份恢复；不自行增加工具或安装 MCP。
+
+DSH 可选的原生共享 Flow 桥仍限图片，未接入 Core 音频附件投影；该桥若选择音频组会明确拒绝启动，不注册失效工具。DSH 原17项工具中的语音/转写功能保持原入口；新音频流程使用通用 MCP 或 Core 工作台。
+
+## 恢复与验证
+
+输入来源在当前根持久保存；临时上传 URL 只在执行期间存在，不进入 Run、Task、创建意图、普通投影或日志。一次创建预留固定步骤及 Task 身份；重连、刷新或同 Key 重放不会重新上传、提交或观察。上传准备失败记录在原 Attempt，受理未知不重提；停止仅结束本地等待，不证明远端取消或退款。
+
+原结果保存失败时，通过原 Run 明确接回；已有私有交付缓存时无需 Provider。浏览器恢复表只存有界身份，不存朗读文字、音色、音频或转写正文；查到创建成功不自动首次执行。查询类型另含 audio-import、speech-create、transcription-create，见 [刷新恢复](WEB_RECOVERY.md)。
+
+定向测试为 `tests/audio-flow.mjs`、`tests/audio-api.mjs`、`tests/audio-recovery.mjs`、`tests/audio-upload.mjs`。真实 Chromium 可用[工作台验证脚本](LOCAL_WEB.md#验证与下一阶段)的独立 `--audio` 场景，覆盖原字节播放/下载、刷新、丢失创建回包、只读及窄屏/主题。SDK验证包含HTTP 2025/2026与真实stdio进程的2026路径。所有新音频验证使用受控 Provider 或上传响应；**未实测真实付费语音/转写服务，也不代表所有账号、编码或 harness 已通过验收**。

package/docs/CLI_MANAGEMENT.md

@@ -1,6 +1,6 @@
 # CLI 配置与任务管理
 
-本文面向 Iris 0.2.6，沿用 `dsh-iris` 入口，无需启动 DSH。安装 `npm install @mokuyoaxis/dsh-iris@0.2.6` 后运行 `npx dsh-iris ...`；也可从源码或本地 tarball 使用同一入口。发布状态见 [README](../README.md)；视觉命令见 [视觉 CLI](VISION_CLI.md)，基础媒体链路见 [Headless CLI](HEADLESS_CLI.md)。
+本文面向 Iris 0.2.7，沿用 `dsh-iris` 入口，无需启动 DSH。安装 `npm install @mokuyoaxis/dsh-iris@0.2.7` 后运行 `npx dsh-iris ...`；也可从源码或本地 tarball 使用同一入口。发布状态见 [README](../README.md)；视觉命令见 [视觉 CLI](VISION_CLI.md)，基础媒体链路见 [Headless CLI](HEADLESS_CLI.md)。
 
 所有需要 JSON 的命令均支持 `--input '<json>'`、`--input-file /path/input.json` 或 `--input -`（stdin），只能选择一种，输入最多 2 MiB。私有配置必须是普通文件、绝对路径，POSIX 权限为 `0600`。真实请求只由显式执行生成、发现、实测或观察命令触发。
 

package/docs/CONTACT_SHEET.md

@@ -0,0 +1,62 @@
+# 多图对照板：真实插件业务（0.3 alpha）
+
+0.3.0-alpha.1随附可选插件 `@mokuyoaxis/dsh-iris/contact-sheet`。**稳定 npm 0.2.7 无此入口。** 它将现有 Core 图片离线排成一个新 PNG Artifact，不调用模型或供应商。安装不会启用或授权插件：Node 业务、Web 页和 MCP 连接分别显式选择。
+
+## 启用
+
+用当前源码或候选包的 CLI 初始化新的专用根，**在导入作品前**完成执行初始化；不转换已有根：
+
+```bash
+dsh-iris flow init --data-root /absolute/new-core
+dsh-iris execution init --data-root /absolute/new-core
+dsh-iris artifact import --data-root /absolute/new-core --input '{"image_path":"/absolute/first.png"}'
+dsh-iris artifact import --data-root /absolute/new-core --input '{"image_path":"/absolute/second.png"}'
+```
+
+保存 `/absolute/startup.json`，明确选择内置实现、业务和页面：
+
+```json
+{
+  "schemaVersion": 0,
+  "entries": ["builtin:contact-sheet"],
+  "operations": ["community.contact-sheet.create"],
+  "panel": { "pages": ["community.contact-sheet.board"] }
+}
+```
+
+```bash
+dsh-iris plugins inspect --plugin-config /absolute/startup.json
+dsh-iris web serve --data-root /absolute/new-core \
+  --plugin-config /absolute/startup.json --port 3182 \
+  --connection-store /absolute/private-connections --allow-connection-management --allow-mcp
+```
+
+首次打开输出的 `loginUrl` 设置访问口令，之后使用普通地址；记住设备可跨正常重启，退出后输入原口令即可。见[工作台登录](WORKBENCH_LOGIN.md)。此入口保持媒体只读，插件业务复用同一持久 runner；无需 Provider 或媒体执行开关。正常停止后可原样重复命令，保留同一端口、认证目录和连接目录。选择格式和退出行为见[稳定启动](PLUGIN_STARTUP.md)。Node 宿主也可沿用[公开 SDK 装配](PLUGINS.md#web-贡献和生命周期)。
+
+## Web 与 MCP
+
+左侧“多图对照板”读取现有图片，按点击顺序排列。最多16张，每行1–4张，单张边长128–512 px，页面提供128/256/512选项。支持每张8 MiB内 PNG/JPEG/WebP，单图解码最多4000万像素；目录可加载更多。
+
+来源图库按数据根共享，可使用其他业务的合格图片。连接只选择本业务时，也可预览这些来源；其他业务的调用、历史和停止仍不开放。需要隔离图片时使用不同数据根。实际制作只读取本次明确选入的来源。
+
+“制作对照板”先保存稳定 UUID 和准确依赖，取得 Core Operation 后只查询该记录。刷新会按原 UUID 接回，不重复制作。结果展示实际 PNG 并支持下载；关闭浏览器后仍可在 Core“业务记录”找回。
+
+1. 打开“客户端 → 新建连接”，命名；只需此业务时可关闭媒体功能。
+2. 勾选“插件业务 → 多图对照板”，再允许“执行流程”；读取/本地停止分别受 `read/stop` 控制。默认没有插件选择，旧连接不扩权。
+3. 生成 stdio 或 HTTP 配置，交给支持对应传输的 MCP 客户端。Core 保持运行；stdio 只启动代理。
+4. 调用 `iris_core_plugin_catalog` 取得准确依赖、输入 Schema 和现有图片 ID，再以稳定 UUID 调用 `iris_core_plugin_call({key,operationId,dependency,input})`。`input` 为 `{artifactIds,columns,cellSize}`，使用实际目录值。
+5. 用 `iris_core_operation` 查询回执；响应丢失时用**原 UUID**调用 `iris_core_lookup`。成功后通过 `iris_core_image` 读取 `result.artifactIds` 的实际图片。
+
+只选此业务并允许 `read/execute/stop` 时共有8个工具：连接控制2个，通用目录/执行2个，原 Operation/lookup/stop/image 4个；收窄权限后再过滤。不为每个插件复制工具 Schema。声明和参数来自 Core；instructions 与 Skill 不授予权限。插件的执行权限不开放原本只读的媒体 runner。
+
+## 持久性与恢复
+
+- 同一单根 runner、FIFO、租约保存 `plugin.execute`，绑定准确版本、完整 JSON 输入、摘要和来源作品。原 UUID 不单独复制入记录，通过派生身份查回；同 UUID 同输入返回原记录，改输入或依赖会冲突。
+- Core 在写作品前保存输出 ID。成功表示业务返回且已发出的 Core 命令完成；使用 Core 的输出引用，不依赖插件自报 ID。
+- 重启将遗留 queued/running 标为 interrupted，**不自动重做**；已经入库的部分作品仍在原记录。恢复插件后重用原 UUID也只返回原记录，需要重新制作时由用户明确新建操作。
+- 缺失或不同版本插件不妨碍读原记录/作品，新执行明确失败。连接保留准确旧依赖可读历史，不自动换版本。
+- 缩权让旧握手失效，阻止后续 Core 命令；不回滚已入库作品。仅关闭 MCP 客户端不撤销已接收操作的执行授权。强制退出后仍须确认已退出 PID，再用现有公开 CLI 显式恢复租约。
+
+这是可信本机插件契约，非代码沙箱。该业务只使用公开 SDK 和现有 Sharp，无需数据根/存储句柄；同进程可信代码本身仍有 Node 权限。已验证真实 PNG、官方 MCP 客户端的 stdio/HTTP 与两代协议、浏览器选择/执行/刷新、插件缺失、准确版本、缩权及两个实际 SIGKILL 窗口；尚未承诺所有 harness 的附件展示。
+
+参见[插件契约](PLUGINS.md)、[Operation](LOCAL_OPERATIONS.md)、[API 契约](LOCAL_API_CONTRACT.md)和 [MCP](MCP.md)。

package/docs/CORE_CONNECTIONS.md

@@ -0,0 +1,99 @@
+# Core 连接与能力握手 v0（0.3 alpha）
+
+该契约服务于 [Core 执行服务与 harness 桥](CORE_SERVICE.md)，不是公开 JavaScript SDK。连接配置均为显式根外私有 JSON，不扫描宿主账号、配置或进程。
+
+通用 MCP 的 stdio/HTTP、配置导出与功能覆盖见 [MCP 指南](MCP.md)。MCP 新连接默认 generic；无需为不同产品注册身份种类。
+
+## 身份与授权
+
+| 字段 | 含义 |
+|---|---|
+| adapterId | 适配实现，如 `iris.mcp`、`iris.dsh-service` |
+| harnessKind | 获授权的产品类别：`kimi`、`dsh` 或 `generic`；不是认证依据 |
+| rootId | v1/v2/v3 数据空间 UUID，授权与客户端均绑定它，不使用本机路径作跨端身份 |
+| connectionId | 一项明确授权的 profile/工作区连接 UUID |
+| runtimeInstanceId | 本次客户端实例 UUID；同一连接最多保留 8 项实例事实 |
+| Operation ownerInstanceId | Core 执行进程归属，与调用者身份分开 |
+
+`connection create` 只创建新私有目录及 `server-grants.json`、`client.json`。服务文件为 `{schemaVersion:0,grants:[...]}`；每项包含 rootId、connectionId、adapterId、harnessKind、label、accessToken、scopes，以及明确 capabilities/tools。客户端包含 schemaVersion、origin、rootId 和相同身份/凭据及所选 capabilities/tools；服务端授权仍由 grants 决定，修改客户端文件不能扩大范围。origin 固定为 `http://127.0.0.1:port`，不允许凭据、路径、跳转或远端域名。
+
+capabilities 为当前支持的功能分组列表（image-edit、image-generate、tts、transcribe），空列表只保留控制工具；tools 可进一步选择具体工具，空列表为零工具。音频两组需新 v3 根，旧根的握手与管理拒绝它们，见[音频流程](AUDIO_FLOWS.md)。两者与操作 scopes 分开。新授权持久写入具体名单，不因版本新增工具自动扩张。旧文件省略两项时仅解释为固定的旧图片编辑流程/12 工具，不迁移文件；显式 null、未知和重复项拒绝。
+
+内置选项、权限标题、工具输入与说明来自同一 Core 声明。显式装配插件后，[统一目录](PLUGINS.md#core-能力目录与授权)列出五类贡献；查看/安装不会扩大授权。页面、表单、渲染器可独立选入 Panel。持久业务另由服务 `allowedOperations` 启用，再由连接可选 `pluginOperations` 保存准确 operations 依赖；缺省/空均不选择，不自动迁移旧连接或跟随升级。
+
+握手可用 `requestedPluginOperations` 显式缩小到原授权中的准确依赖。通用业务目录/执行及原 Operation/image 控制工具再与 scope、tools 和服务门禁求交；instructions 与 Skill 不授予权限。修改持久选择/scope/tools 后旧握手失效，已接收业务在后续 Core 命令前重新核对当前授权。关闭桥接实例不等于撤销执行授权。插件缺失时可保留原依赖只读历史；新选择只允许服务已启用的准确版本。实例见[多图对照板](CONTACT_SHEET.md)。
+
+文件为 0600，目录为 0700；读取拒绝符号链接、非普通文件、过大文件及 POSIX 过宽文件权限。Windows mode 不能替代 ACL。凭据不出现在 URL、普通 DTO 或诊断中。运行时认证表仅保留比较用摘要，私有持久档案保留连接密钥；scope 为有限的 `read/create/execute/stop`，必须含 read。静态 grants 只在显式启动时读取，修改静态授权后须重启；下面的管理目录支持显式 owner 即时更改，不自动修改日常 harness 配置。
+
+这是同一用户明确共享的数据空间。流程读取、执行和停止仍需对应功能、工具与 scope；插件业务及历史另需所选的准确依赖，read 本身不开放所有记录。
+
+选入声明图片输入的插件业务后，可从同一根的共享图库选取和预览 PNG/JPEG/WebP（单张 ≤8 MiB），包括其他业务的图片产物；实际处理器只可读取本次输入绑定的来源 ID。共享来源不授予来源业务的调用、历史或停止权限。未声明图片输入的业务不隐含图库权限，超限图片也不由此放行；已选媒体功能与本业务产物沿用各自交付权限。它不是按连接划分的数据租户隔离，需要分隔图片时使用不同数据空间与授权。
+
+## 握手与调用
+
+连接请求带 `Authorization: Bearer …`、`Iris-Connection-Id` 和 `Iris-Runtime-Id`；仍执行原 Host/Origin 门禁。服务 owner 的短期 Token 与持久连接凭据分开。
+
+POST `/api/v0/connections/:connectionId/handshake` 接受以下必填字段；还可提供 requestedCapabilities/requestedTools 明确缩小功能/工具范围：
+
+```json
+{
+  "contractVersion": 0,
+  "adapterId": "iris.mcp",
+  "harnessKind": "kimi",
+  "runtimeInstanceId": "00000000-0000-4000-8000-000000000001",
+  "harnessVersion": "declared bridge or harness version",
+  "requestedScopes": ["read"]
+}
+```
+
+身份必须匹配授权；协议不支持或请求了未授权/服务未开启的能力时拒绝，不静默扩大或回落。响应包含契约版本、rootId、连接身份、实例、协商 scopes 和 `remoteHostPorts: []`。连接客户端检查数据空间与实例一致；只按协商权限注册工具。浏览器、视觉、附件和会话控制不因一次握手就被视为反向可调用。
+
+响应 instance 另含 capabilities/tools，Core 在每条对应业务 API 上同时检查工具范围；session.operations 也按此过滤。HTTP `/mcp` 使用标准 Bearer 即可，内部身份与实例头由服务桥负责；只接受 iris.mcp 授权，owner 临时 Token 和原生 DSH 授权不替代它。每项 HTTP 授权持有一个逻辑桥实例；客户端品牌不是认证依据。
+
+`GET /api/v0/session` 只列该调用者可用操作。`GET /api/v0/adapters` 列出随 Iris 提供的适配描述；不代表目标 harness 已安装。`GET /api/v0/connections` 对 owner 列全部授权，对连接只列自身；不返回 secret。
+
+实例事实包括最后握手/请求时间、声明版本、协商 scopes、`verification: handshake` 与 `liveness: not_probed`。connected 只表示本次服务中的逻辑会话已握手且未明确断开，**不证明进程在线或模型已实测**。当前不做进程扫描或心跳探测。服务重启后须重新握手，GET 不自动接入或写业务数据。
+
+POST `/api/v0/connections/:id/disconnect`：连接端提交 `{}`，断开自身实例；owner 提交 `{runtimeInstanceId}` 可明确断开指定旧实例。断开只撤销本次会话，不取消持久 Operation、不删除作品、不重启 harness。新实例接入可替换最早已断开的内存记录；全部 8 项仍有效时拒绝新增，由 owner 明确处理。实例事实只在服务内存保留；管理档案单独保存最近客户端声明，不作为完整历史审计日志。
+
+## Owner 连接中心
+
+`api/web serve --allow-connection-management --connection-store /absolute/private-directory` 显式开启；页面操作见 [本地工作台](LOCAL_WEB.md#显式开启连接中心)。同一服务可合并只读静态 grants 和可管理档案，活动授权总计最多 32 项。默认不开启，不扫描品牌、进程或文件系统寻找 harness。
+
+管理目录含 `store.json`（schemaVersion/rootId）、`profiles/<connectionId>.json`（单档案权威记录）、`clients/<content-sha256>.json`（不可变导出副本）、`templates/<content-sha256>.json`（纯数据模板）、`archived/<connectionId>.json`（删除时的撤销档案检查点）和 `ownership/`（复用 Core 租约）。目录与业务根不可相互包含，现有非空未知目录或异根/异版本均拒绝，不迁移。档案含标签、明确授权、revision、创建/更新/撤销时间、创建输入摘要与最近客户端声明；原子单记录提交后同步变更认证表。崩溃留下未知文件时保留并拒绝启动，不自动删除或猜测修复。
+
+以下路径均以 `/api/v0/connection-management` 开头，只接受本次服务的 owner Token。连接凭据即使有 execute 也无权管理：
+
+| 路由 | 输入 / 行为 |
+|---|---|
+| GET/HEAD `/catalog` | 本服务可授予的 availableScopes、Core scopeOptions/controlTools、媒体/功能/工具目录、默认选择及模板示例；另含已装配插件的贡献与接入边界，未接入媒体分组仍列空 |
+| GET/HEAD `/templates` | 已导入templates及内容摘要身份、内置显式presets和支持formats；无凭据，不检测本机安装 |
+| POST `/templates` | `{schemaVersion:0,title,transport,format,documentationUrl?}`；相同内容幂等，首次 201、重放 200 |
+| GET/HEAD `/connections` | 管理/静态档案及当前实例，无凭据；撤销档案仍列出，删除档案不列出 |
+| POST `/connections` | `{key,label,scopes,capabilities,tools?}`；key 为 UUIDv4，成为 connectionId。首次 201，同 Key/输入 200，不新造密钥；不同输入 409 |
+| POST `/connections/:id/update` | `{expectedRevision,label,scopes,capabilities,tools?}`，CAS 更新；只允许服务已开启的权限 |
+| POST `/connections/:id/revoke` | `{expectedRevision}`，持久撤销并阻止后续认证；重放不复活或重提 Operation |
+| POST `/connections/:id/delete` | `{expectedRevision}`，先持久撤销，再建立私有归档检查点并从列表移除；已删除的同身份请求可幂等重放 |
+| POST `/connections/:id/export` | `{transport,format}`、`{templateId}`或`{presetId}`，互斥；支持通用JSON、Claude JSON和Codex TOML。HTTP含密钥，要求服务已开启MCP |
+| POST `/connections/:id/skill` | `{}`，按已保存授权与当前服务权限交集返回公开 Skill 交付 JSON 和 Markdown 预览；撤销或零工具拒绝 |
+
+正文上限 8 KiB，未知字段拒绝。创建/编辑/导出不调用 Provider；授权变化清除旧握手，HTTP 工厂按新名单重建，stdio 旧进程的实际 API 调用仍受 Core 新授权检查。标签修改保留实例。已接收操作不会因撤销而伪造 canceled 或退款。导出文件按内容身份排他创建，旧副本或外部修改不被覆盖；外部修改档案也明确拒绝覆盖，需停服核对。
+
+导出响应保留configuration/containsCredentials，另附实际content、filename和mediaType；TOML的configuration为规范字段对象，content为原生文本。内置预设不写入templates目录、不消耗自定义配额；旧模板schemaVersion与摘要保持，新数据模板也可明确选择claude-json/codex-toml。前端按实际内容复制或下载，不将TOML再次JSON.stringify。见[MCP首次接入](MCP.md#首次接入与客户端预设)。
+
+撤销保留列表；删除只移除可管理连接，不支持删除静态 grants。删除检查点与原撤销档案保持相同字节、0600 权限，归档目录为 0700；不移走原档案、不改原格式、不移除客户端导出文件、Skill、业务任务或作品。归档写入失败时连接仍被撤销并显示在列表，刷新版本后可明确重试；归档成功后，即使响应丢失或服务重启，同一删除可重放，同一创建 Key 返回409，不能重新生成有效凭据。恢复资料仍保存在私有管理目录，当前没有界面恢复或永久清除入口；保留的密钥已失效。启动校验归档身份、撤销状态与原档案摘要，冲突时保留现场并拒绝启动。
+
+模板只允许标题（最多 80 字符）、`stdio/http`、`mcpServers/entry` 和无认证信息的 HTTPS 文档地址。内容寻址、最多 64 项，同一管理租约保护；重启校验内容与文件名，不覆盖漂移文件。新内容产生新模板，不编辑或自动删除旧模板；手动选择始终可用。模板不接受命令、环境变量、端点、权限、密钥或外部脚本，不扫描/启动客户端，也不自动打开文档。
+
+Skill 交付文件为 `schemaVersion:0,kind:iris-mcp-skill` 的公开快照，含 rootId、connectionId、revision、label、scopes、capabilities 和当前有效 tools；不含密钥或本机私有路径。它是安装器的有限数据输入，不接受外部 Markdown/文件树。包内渲染器生成 `iris-mcp-<connectionId>/SKILL.md`，英文正文附中文标题，只指导实际开放的工具，不回落到 CLI 绕过授权。配置导出与 Skill 均考虑当前服务权限；服务改成只读后不会继续导出 execute scopes。快照不会自动更新或撤销文件，实际权限仍由 Core 每次检查。安装与保护规则见 [连接专属 Skill](CORE_SKILLS.md#连接专属-mcp-skill03-alpha)。
+
+MCP 桥从官方 SDK 获取客户端 name/version/title，经有界投影，通过 POST `/api/v0/connections/:id/client-info` 记录 `{clientInfo,transport}`。握手响应的 `connectionFeatures:['client-info']` 协商此可选扩展；旧服务缺少该能力时桥不提交声明。元数据必须属于已握手实例，来源标记 `client-declared`，不授予 scopes 或改变 adapterId。首次、身份变化及至少一分钟间隔的后续请求记录最近声明；没有声明保持 null。共享 HTTP 凭据依然只代表一个逻辑桥，不推断真实进程数。
+
+## 故障语义
+
+- Token/连接不匹配返回 401，未授权能力返回 403，未握手/版本冲突返回 409，实例容量返回 429。
+- Core 客户端不自动重试写请求、不转投其他端口/本地运行时；响应丢失先查原 Key。
+- 连接失效不改变原 Operation 的业务身份和计费事实。停止是单独的显式本地动作，远端取消未接入此协议。
+- 断开确认失败时，本地桥仍可释放自身资源，并报告 `remoteDisconnect: unconfirmed`；不把网络失败解释为远端会话/Task 已停止。
+
+本轮契约覆盖有限 HTTP/stdio 接入，尚无任意插件加载、远程端口代理、账户登录代理、自动 harness 安装或整个 Agent 会话控制。

package/docs/CORE_QUICKSTART.md

@@ -0,0 +1,108 @@
+# Core Workbench Quickstart · 从零启动工作台
+
+This guide is for **0.3.0-alpha.1 or the current source tree**. Stable npm **0.2.7 does not include `web serve` or production MCP**. For stable DSH/CLI usage, see the [DSH guide](../user_guide.md) or [standalone CLI](HEADLESS_CLI.md). Alpha contracts may change; existing roots are not migrated automatically.
+
+## Start a new workspace · 新建工作区
+
+Use Node.js ≥22. To install the prerelease in your project:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.3.0-alpha.1
+npx dsh-iris --help
+```
+
+The commands below use a source checkout: install its locked dependencies with `npm ci`, then run from the repository root. For the installed alpha package, replace `node bin/dsh-iris.js` with `npx dsh-iris`. Use `@alpha` instead of the exact version only when you intend to follow prereleases.
+
+Choose a **new private directory under your home**, on a filesystem that supports hard links. On Termux/PRoot, keep it in the Linux home rather than Android shared storage. These commands create a new workspace; they do not migrate an old DSH or Flow root. If the paths already contain data, choose another location.
+
+```bash
+IRIS_PREVIEW="$HOME/.iris/preview"
+mkdir -p "$IRIS_PREVIEW"
+
+node bin/dsh-iris.js flow init --data-root "$IRIS_PREVIEW/core"
+node bin/dsh-iris.js execution init --audio --data-root "$IRIS_PREVIEW/core"
+node bin/dsh-iris.js config init --provider-config "$IRIS_PREVIEW/providers.json"
+
+node bin/dsh-iris.js web serve \
+  --data-root "$IRIS_PREVIEW/core" \
+  --auth-store "$IRIS_PREVIEW/auth" \
+  --provider-config "$IRIS_PREVIEW/providers.json" \
+  --allow-provider-management --allow-execution --allow-selection \
+  --connection-store "$IRIS_PREVIEW/connections" \
+  --allow-connection-management --allow-mcp \
+  --port 3182
+```
+
+`--audio` initializes a new v3 execution root, supporting images, speech and transcription. It does not enable a model, spend credits or migrate existing roots. The switches above explicitly enable:
+
+| Switch | What it permits |
+|---|---|
+| `--allow-provider-management` | The workbench owner can edit media services, models and pools |
+| `--allow-execution` | Local imports, Run creation and supported media execution |
+| `--allow-selection` | Save an image selection for a completed Run |
+| `--allow-connection-management` | The owner can create, update, revoke and delete MCP grants |
+| `--allow-mcp` | Serve Streamable HTTP at `/mcp`; stdio uses a bridge to the same Core |
+
+The service listens on `127.0.0.1`. Keep this command running. Ctrl+C stops this service normally; it does not start or restart DSH. Only one execution service may manage this root. For read-only use, omit the write switches and unneeded management options; see [the workbench reference](LOCAL_WEB.md).
+
+## Sign in · 登录
+
+Open the printed **`loginUrl` once to set your access password**. Afterwards, open the ordinary `origin` and use that password. Remembered devices survive refreshes and normal restarts; logging out lets you sign back in with the same password. A mobile browser does not need access to Termux files.
+
+In another terminal, recover the address without restarting:
+
+```bash
+node bin/dsh-iris.js web login \
+  --data-root "$HOME/.iris/preview/core" \
+  --auth-store "$HOME/.iris/preview/auth"
+```
+
+Use `web password reset` with the same paths only when you intend to reset the password and revoke all browser sessions. It preserves works and MCP grants. See [login and recovery](WORKBENCH_LOGIN.md). The workspace password, a provider API key and an MCP connection credential are three separate credentials.
+
+## Make the first work · 生成第一件作品
+
+1. Open **模型服务 → 添加服务**. Select the documented protocol, enter a name, Base URL and API key, or explicitly choose no authentication if the service supports it. Save the connection.
+2. Open **模型与用途**, read the saved service's model directory or enter an exact model ID, and explicitly check its intended use. Save again. Approving a new use can enable its automatic pool; check the save summary.
+3. Under **功能模型池**, choose automatic selection, a manually ordered list, or disabled. A manual empty list stays empty. Automatic selection uses confirmed, eligible models in stable order; it is not cross-request round-robin.
+4. Under **创作 → 生成图片**, choose an actual configured model, enter a prompt and click **开始生成**. This is the step that calls the provider and may cost money. Choose the completed result, then download it. **作品** keeps the Run and its related outputs.
+
+Opening pages and refreshing the spectrum do not generate media. Reading a model directory or checking a connection only checks that interface; neither proves media generation works. Optional keepalive is off by default and lasts only for this service session. Full details: [providers, pools and health](PROVIDER_SETTINGS.md).
+
+For ComfyUI, use an existing service and an explicitly imported **API-format workflow** with mapped prompt/output nodes. Check declared parameters and available LoRA choices, then save and choose that workflow. Iris does not install ComfyUI, invent a graph or discover GPU models by guessing. See [ComfyUI workflows](IMAGE_GENERATION.md#comfyui-入口).
+
+The current Web/MCP media entries cover image generation/editing, speech and transcription. Video, music and vision retain their existing [CLI](HEADLESS_CLI.md) / DSH entries; configuring their uses here does not add a Web creation form.
+
+## Connect an Agent · 连接客户端
+
+1. Open **客户端 → 新建连接**. Give it any meaningful name. Choose media functions and, for image generation, the separate generation capability. Grant only the operations needed: **读取** for history; **导入与创建** and **执行流程** for new media; **停止等待** only when wanted.
+2. Save, then select a client template under **接入配置**. Use **stdio** for a local client that can run the exported command, or **HTTP** when it supports Streamable HTTP. HTTP here is loopback-only too.
+3. Generate the configuration and merge the Iris entry into the client's chosen MCP configuration. Preserve existing entries. Reconnect in that client, then refresh the workbench to inspect the actual handshake.
+4. Optionally generate and download the **连接专属 Skill**, then explicitly install it in that client's supported Skills directory:
+
+```bash
+node bin/dsh-iris.js skills install \
+  --bundle /absolute/path/to/iris-skill.json \
+  --directory /absolute/path/to/client-skills
+```
+
+The downloaded Skill contains instructions for the effective tools, without the connection key. The exported MCP configuration is private and may contain a credential; do not commit or share it. The CLI-oriented `iris-core` Skill is a separate entry, intended for direct CLI use.
+
+The client starts a stdio **bridge**, not a second Core writer. Both transports require this Core service to stay running. A saved connection is an authorization record; it does not install a client or mean that client is online. On the same machine, keeping the data root, authentication directory, connection directory, installed executable path and port stable preserves normal logins and exported configurations.
+
+Hand the client this task after it sees the actual tools:
+
+```text
+Use only this Iris MCP connection. Read the actual configured image models,
+then generate one pale-purple iris flower with an explicitly permitted model.
+Keep the original request UUIDs and inspect the original receipt until complete.
+Read back the resulting artifact. Report its Run ID, artifact ID and actual status.
+If acceptance or the result is unknown, inspect it; do not submit again automatically.
+```
+
+For an Agent handling setup, use the [Agent quickstart](AGENT_CORE_QUICKSTART.md). Transport details, templates and errors are in [MCP](MCP.md).
+
+## Optional plugins and recovery · 可选插件与恢复
+
+The quickstart above uses built-in media capabilities. Optional plugins need an explicit startup selection. Follow [plugin startup](PLUGIN_STARTUP.md) to load the bundled [contact sheet](CONTACT_SHEET.md), choose its page/operation and then grant that exact business to a connection. Loading code, enabling a business and authorizing a client are separate choices. Plugins are trusted Node code, not a sandbox or a marketplace install.
+
+Restart by stopping this service normally and repeating the same `web serve` command. Core keeps the original Run/Task/Operation and artifacts; restart does not automatically regenerate. After a forced exit, inspect the lease and its owner before any explicit recovery; never delete a lock to get past “busy”. See [Core lifecycle](CORE_SERVICE.md) and [request recovery](WEB_RECOVERY.md).