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

package/docs/AGENT_CORE_QUICKSTART.md

@@ -0,0 +1,64 @@
+# Agent Quickstart · Core 与 MCP 接入指导
+
+For **0.3.0-beta.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 beta or explicitly choose the beta 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-beta.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,5 +1,7 @@
 # 给 AI Agent 的简要 Prompt
 
+先选择入口：0.3.0-beta.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.7，准确范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。执行安装命令前确认所选发行包的实际版本、工具和功能策略。

package/docs/ARCHITECTURE.md

@@ -1,10 +1,14 @@
 # Iris 架构与边界
 
-状态：本文描述 **Iris 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 内部 API 尚未冻结为公共 SDK。
+状态：本文说明 **Iris 0.3.0-beta.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.1.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 beta另提供独立 [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
@@ -35,7 +39,7 @@ DSH Host / Cordis                         Headless CLI
 
 `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)，执行/取消、通用 Recipe 和真实独立 Web 仍待完成。详见 [应用运行时契约](CORE_RUNTIME_CONTRACT.md#应用运行时装配)。上图表示已发布入口的共同核心。
+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 beta；通用 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 和关联产物。
 
@@ -63,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 beta增加[Provider 扩展首版](PROVIDER_EXTENSIONS.md)：实例拥有协议描述、工厂、活动调用和异步释放；CLI/Core 服务显式传入注册实例，六类内置协议（含 ComfyUI）与外部协议共用候选/健康/恢复。实验性包入口仅开放媒体协议所需接口，尚未提供 DSH 外部模块加载设置、通用 Recipe 或完整 SDK。ComfyUI Task binding 另纳入模板摘要，见 [文生图与工作流入口](IMAGE_GENERATION.md)；原五类协议的 binding 与既有记录保持。
+
+同属0.3 beta的 [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

package/docs/ARTIFACT_MANIFEST.md

@@ -21,12 +21,16 @@ artifact-store/v0/
 
 Index 更新失败不会撤销已经提交的 Artifact，避免调用方因本地缓存错误重新生成或重复付费。显式 `artifact rebuild` 会从提交记录和旁车 Manifest 重建 Index。
 
+beta.1修复在提交 record 前写入私有 `index.dirty` 标记，成功发布完整 Index 后移除。索引发布失败或进程在两者之间中断时，列表明确返回 `IRIS_ARTIFACT_INDEX_INVALID`，Doctor 报告索引异常；按 ID 读取原作品仍可用。下一次成功刷新或显式重建可消除标记，不需要迁移既有记录，也不自动删除媒体。
+
 ## 内容完整性
 
 Manifest 使用小写十六进制 SHA-256，并同时记录字节数。`inspect`、`export`、`list` 和重建都会核验对象；即使文件大小不变，内容被替换也返回 `IRIS_ARTIFACT_DIGEST_MISMATCH`。
 
 哈希通过固定大小分块读取，不把完整视频再次载入内存。Manifest、错误和 CLI 结果不保存输入路径、旧作品文件名、DSH URL 或供应商下载 URL。
 
+beta.1中，新作品只核验自身内容和实际使用的关系目标；随后刷新 Index 时检查所有历史提交记录、Manifest 和普通文件大小，不重复重哈希历史媒体。历史结构/大小异常会阻止发布新索引，不静默跳过坏记录。已有摘要的正常提交仍需遍历元数据并原子重写 Index，尚非增量数据库；没有摘要的早期 v0 记录仍须计算真实哈希，可通过显式重建升级。媒体读取、CLI `inspect/list/export` 和显式重建继续验证完整内容哈希，目录刷新本身不证明历史媒体本次已重新验过内容。
+
 ## 关系边
 
 关系方向固定为“当前 Artifact 指向既有 Artifact”。v0 支持：

package/docs/AUDIO_FLOWS.md

@@ -0,0 +1,87 @@
+# Core 语音合成与音频转写（0.3 beta）
+
+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 根上执行迁移；原根继续按原能力运行。beta.1视频流程另提供 `--video` 新 v4 根，保留这些音频流程；已有 v3 不迁移，三个开关不混用。省略这些开关的 `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。这里没有新增语音协议、模型自动替换或音色发现接口。
+
+## CLI 保存与继续（beta.1修复）
+
+独立 `flow create/continue` 现装配与服务相同的图片、语音、转写和视频候选。先建立上述 v3/v4 根，并在功能池中允许所选模型：
+
+```bash
+node bin/dsh-iris.js flow create --data-root /absolute/new-audio-core \
+  --provider-config /absolute/existing-providers.json \
+  --input '{"recipe":"speech/v0","model_ref":"provider::tts-model","text":"鸢尾花","voice":"Cherry"}'
+node bin/dsh-iris.js flow continue run_0123456789abcdef01234567 \
+  --data-root /absolute/new-audio-core --provider-config /absolute/existing-providers.json
+```
+
+Run ID 使用创建命令的实际返回值。转写使用 `recipe:"transcribe/v0"`、明确 `model_ref` 及 `source_artifact_id`，来源应先由当前根的 Web/MCP 音频导入保存；这里不新增 CLI 音频导入命令。创建不合成或上传；首次继续才执行，后续继续只观察或交付原 Task，受理未知不重提。已完成且本地结果完整时，无需 Provider 配置再次读取结果。
+
+## 页面使用
+
+- **语音合成**：选择实际语音模型，填写朗读文字，必要时展开音色并填该模型支持的标识；留空使用现有协议默认值。点击合成后，保存输入、明确执行一次、保存原音频，可试听并下载。
+- **音频转写**：选择 WAV/MP3/OGG/FLAC 原音频及转写模型。点击开始后先保存来源作品和 Run，再在原 Task 的 Attempt 内临时上传、提交。异步任务显示“查看原任务”；每次明确点击只观察一次，不持续远端轮询。
+- **作品**：v3 工作区按图片、语音、转写分类。语音卡片点击“载入试听”后获取原音频；同一时间只保留一个作品卡播放器，离页或切分类释放。转写文字在流程页以纯文本显示，原音频可播放，文字可下载。
+
+生成音频/转写是单一结果，保存后即可下载，无需图片版本选择。下载保留原字节；实际落盘以浏览器下载记录为准。离开创作页暂停播放，退出或切换流程释放相应媒体。当前不提供流式合成、音色目录、录音、长音频切片、字幕时间轴或本地 TTS。
+
+beta.1交付新语音/音乐结果时，会读取有限文件头确认WAV或MP3容器，再保存真实MIME与后缀；不把供应商声明的MP3套在WAV字节上。不支持的音频响应保留已受理事实并报交付失败，不重新合成。此为容器识别，不是完整解码或格式迁移；已入库的旧作品不自动改写。
+
+## 有限 HTTP 契约
+
+以下均以 `/api/v0` 开头，保留 Bearer、Host/Origin、无 CORS 和有限权限。新路由只在 v3 根（beta.1也支持 v4）开放；创建使用原 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/BETA_SCOPE.md

@@ -0,0 +1,42 @@
+# 0.3.0-beta.1 范围与兼容约定
+
+本页定义 **0.3.0-beta.1** 的发行范围、最小插件契约与主要用户流程。使用准确版本或 npm `beta` 通道，稳定 `latest` 保留0.2.7；历史alpha.1没有新增网络、视频、调度与Provider工厂上下文v1。安装与升级入口见[发布说明](releases/0.3.0-beta.1.md)。
+
+## 纳入的主要流程
+
+| 用户入口 | 候选约定 | 继续保留的边界 |
+| --- | --- | --- |
+| 启动/登录 | Core明确启动，首次设置访问口令、记住设备、退出/刷新恢复 | 不修改其他harness配置；Token模式继续作为显式选项 |
+| 模型服务 | 添加/编辑/停用/删除供应商，显式凭据来源、完整目录确认、按功能选择模型池 | 目录和近期成功不是永久健康承诺；无跨请求模型轮转；不默认读取其他宿主或.env |
+| 网络出口 | 独立HTTP/HTTPS节点、固定/有序池、供应商绑定、owner页面/CLI/API/Doctor | 无绑定继承实际进程环境；显式失效不悄悄直连；SOCKS、系统TUN控制、地域自动分流和Clash自动配置不在范围 |
+| 创作/作品 | 图片生成/已支持的编辑协议、ComfyUI声明参数，语音/转写、固定文生视频，原件预览/下载 | 协议及账号能力以实际目录/实现和实测为准；没有新增Core音乐/视觉持久流程或远端视频编辑 |
+| 执行/恢复 | 单物理根单写者，持久Run/Task/Attempt/Operation，显式有界调度、原UUID/原任务接回、本地停止 | 调度缺省串行；并发与HTTP速率/远端受理数分别限制；unknown与交付失败不自动新生成；停止不证明远端停费 |
+| MCP连接 | 通用stdio和Streamable HTTP，显式客户端预设，用户选择功能/工具/scopes，导出/检查/握手/撤销/缩权 | 配置检查、协议握手与真实Agent调用分别验证；不扫描harness、不默认授权或聚合第三方MCP服务 |
+| 插件/Panel | Provider、持久业务、页面/设置挂载、作品渲染，共享主题/API/登录；保留整套Panel替换 | 可信代码，无市场/自动安装/热加载/任意插件设置仓库；页面挂载不自动授权业务 |
+
+入口说明：[从零启动](CORE_QUICKSTART.md)、[模型服务](PROVIDER_SETTINGS.md)、[网络工作台](NETWORK_WORKBENCH.md)、[调度](MEDIA_SCHEDULING.md)、[MCP](MCP.md)、[插件开发](PLUGIN_DEVELOPMENT.md)。
+
+## 最小插件兼容面
+
+本轮冻结的是下列窄约定，内部模块与完整通用SDK不纳入冻结：
+
+- Plugin/Adapter契约v0：稳定插件/贡献ID、各自独立版本、Core兼容范围、明确启用与授权、准确持久依赖及缺失/错版错误。
+- Provider工厂上下文v1：Core提供当次解析的连接与借用fetch，管理完整方法的正文/多跳及关闭；插件不拥有Core队列、任务存储或网络资源管理。使用功能标记确认支持，详见[Provider最小契约](PROVIDER_PLUGIN_CONTRACT.md)。
+- 持久业务通过公开有限Core命令和原Operation执行；页面、设置挂载与预览器使用公开浏览器端上下文。Node插件和Shadow DOM都不是安全沙箱。
+- 变更上述可观察输入/结果、权限、生命周期或准确依赖语义时，先审查兼容性并更新相应契约/贡献版本，不把实现升级伪装成原版本恢复。
+
+两类[独立模板](PLUGIN_DEVELOPMENT.md)分别验证业务/页面/PNG预览与真实异步Provider协议。旧窄Provider扩展保留原用法。内部文件不因随包存在而成为公开导出；不要绕过package exports依赖私有路径。
+
+## 数据与平台
+
+旧根不自动迁移；新音频/视频根与网络任务有明确版本门禁，不能让旧CLI写入它们。已发布DSH原工具和原CLI仍按既有范围使用，Core新音视频不自动加入DSH原生共享Flow桥。
+
+beta.1最低Node为22.1.0：隔离复核确认22.0.0原生fetch正文取消不会关闭连接，会占用调度名额；22.1.0与当前22.23.4通过同一验证。CI配置包含Ubuntu/Windows及最低/当前Node22；**工作流配置存在和历史CI成功都不能证明当前候选通过**。本机Termux/PRoot ARM64、真实浏览器、本地代理、实际供应商和原生Agent结果应分别记录。最终发布还需核对同一候选的完整测试、独立包消费者和标准平台矩阵，不能拿旧压测或一次握手替代。
+
+自动配额/GC、复杂模型/出口加权轮询、更多宿主凭据桥、legacy统一迁移、全部供应商/GPU/手机/浏览器/harness认证继续后置；不因本页列出能力就宣称这些覆盖已完成。
+
+## 源码验收与发行候选
+
+文档中的 `node scripts/...`、`tests/...`、`npm test` 和 `npm run lint` 从源码仓库根运行；开发脚本与测试不随npm包根目录分发。安装用户继续使用包内CLI/Web/MCP入口，不能把源码验证命令当作已安装包的使用要求。
+
+CI除Ubuntu/Windows、最低/当前Node22完整测试外，另在Ubuntu当前Node22构建真实tarball，检查包外插件/Provider与凭据/调度消费者、strict NodeNext公共类型，并用真实Chromium验证打包后的总览、凭据、视频与调度页面。缺少必需编译器或浏览器会使该发行检查失败；其他可选运行时的SKIP不计作通过。具体运行结果以对应提交的CI和发行记录为准，历史B5记录不代替本轮结果。

package/docs/CONTACT_SHEET.md

@@ -0,0 +1,62 @@
+# 多图对照板：真实插件业务（0.3 beta）
+
+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,101 @@
+# Core 连接与能力握手 v0（0.3 beta）
+
+该契约服务于 [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。共享来源不授予来源业务的调用、历史或停止权限。未声明图片输入的业务不隐含图库权限，超限图片也不由此放行；已选媒体功能与本业务产物沿用各自交付权限。它不是按连接划分的数据租户隔离，需要分隔图片时使用不同数据空间与授权。
+
+原生改图/转写创建也校验来源作品的所属媒体与已有共享来源授权。仅知道一个 Artifact ID、或选择了目标功能，不会自动获得其他媒体流程的来源读取/处理权限；例如只选转写不能借创建转写流程读取被其权限拒绝的语音合成结果。无绑定导入保留已选媒体功能的原来源规则。HTTP与MCP使用相同检查，原Key重放也不绕过当前来源授权；创建本身仍不上传或生成。
+
+## 握手与调用
+
+连接请求带 `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,110 @@
+# Core Workbench Quickstart · 从零启动工作台
+
+This guide is for **0.3.0-beta.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). The beta scope freezes a minimal contract; broader SDK contracts may change; existing roots are not migrated automatically.
+
+## Start a new workspace · 新建工作区
+
+Use Node.js ≥22.1.0. To install the prerelease in your project:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.3.0-beta.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 beta package, replace `node bin/dsh-iris.js` with `npx dsh-iris`. Use `@beta` instead of the exact version only when you intend to follow beta releases.
+
+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-入口).
+
+Beta.1 Web/MCP media entries cover image generation/editing, speech, transcription and [text-to-video](VIDEO_FLOWS.md): choose a separate new root and use `execution init --video` instead of `--audio` when initializing it. This creates v4, retains image/audio flows and adds optional video entry points; existing roots are not migrated. Older alpha.1 packages do not support this switch. Image-to-video, S2V, music and vision retain their existing [CLI](HEADLESS_CLI.md) / DSH entries.
+
+## 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).
+
+Beta.1 provides **选择与授权 → 获取配置 → 核对接入**. Confirm where the Agent runs: the current loopback address and local stdio paths cannot be copied directly to another machine. Its **Iris 端配置检查** reads service/authorization facts without creating a bridge or testing media. Export, this check and an actual client's optional declaration are separate evidence; missing optional client metadata is not proof of a failed call. See [the onboarding flow](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).