@mokuyoaxis/dsh-iris 0.2.7 → 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,5 +1,7 @@
 # 给 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.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-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
@@ -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 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 和关联产物。
 
@@ -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 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

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/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).

package/docs/CORE_RUNTIME_CONTRACT.md

@@ -13,6 +13,7 @@ Core Runtime 由调用方显式创建、启动和释放。数据根、操作权
 - `dataRoot` 必须由 DSH Host Adapter、CLI 或测试宿主选择后，以绝对路径显式传给 Core。Core 不读取 `DSH_HOME`、`HOME` 或当前工作目录来猜测位置。
 - 每个数据根只允许一个写者。写者必须在读取、初始化、规范化配置、接回旧作品、重建索引或启动任务观察器之前取得数据根租约，并持有到实例完成释放。
 - 其他进程可以用 `reader` 打开同一数据根，但只能执行无副作用的检查。DSH 正在使用该数据根时，CLI 写操作返回 `IRIS_CORE_DATA_ROOT_BUSY`；用户可以停止现有写者，或显式选择另一数据根。
+- 0.3 alpha应用运行时读取图库时，若索引引用的文件缺失且能确认写者仍活跃，返回 `IRIS_CORE_DATA_ROOT_BUSY`（本地 API 为 409 `IRIS_API_ROOT_BUSY`），提示写入结束后显式重试；维护提交窗口不再直接建议重建索引。正常读取仍允许；损坏 JSON、内容校验失败，以及没有活跃写者的缺失记录继续明确报错，不自动修复、重试或接管租约。
 - 只读不是隐式写入：不得创建缺失文件、修改权限、隔离损坏文件、修复/迁移记录、接回 `outputs/`、更新健康时间或启动任务观察器。
 - 写者冲突必须 fail-fast，普通 Runtime **不得自动夺取**租约。0.2.0 提供独立的 `runtime recover` 显式流程：先由只读 Doctor 报告 owner，再要求用户回显陈旧 PID，并在接管时复核证据、写私有审计；活跃、未知或损坏状态拒绝。PID 不存在本身仍不是跨主机安全证明。
 - 路径别名必须在取得租约前解析为同一物理数据根。不能只依赖字符串规范化或原子 `rename`：后者可以防止半写文件，不能阻止两个带缓存的进程互相覆盖。
@@ -23,6 +24,8 @@ Core Runtime 由调用方显式创建、启动和释放。数据根、操作权
 
 正常释放先整体 rename 非空目录为本实例 UUID 的退役目录，最后撤下意图；不会先在占位目录里删除 owner。退役目录本身不占有固定租约，但若撤下意图前中断，剩余意图仍阻止普通 writer，需要在 owner 已退出且证据完整时显式恢复。意图撤下后的清理只涉及本实例退役证据，清理失败不阻止新 writer；遗留退役目录不会在下次启动时自动删除。
 
+0.3 alpha源码允许新根初始化保留一类未发布的租约准备文件：名称、完整 owner/PID 必须吻合，文件为普通文件、仅一个硬链接，且该 PID 已确认不存在。它不占有租约，初始化不删除或改写该证据。活跃、未知、损坏、符号链接及其他残留仍拒绝；这不是通配符清理或自动恢复授权。
+
 恢复使用数据根中按前驱 UUID 排他发布的完整记录，保留原 owner，不替换或删除旧恢复步骤。Doctor 的 `phase` 可为 `owned`、`pending`、`recovering`；恢复再次中断时回显最新报告中的 PID，并复核链中每个 PID 均为 missing。并发恢复与旧观察被新 writer 接替均拒绝，不向新租约目录写入陈旧 claim。无 PID 的旧空目录、仅剩 `.owner.stale-*` 而缺少恢复 owner 的旧现场、未知文件、损坏或符号链接证据仍拒绝并保留。
 
 私有审计先记录退役授权和完整恢复链，再整体移走租约到审计记录指定的 `evidenceDirectory`。审计 JSON 的存在本身不证明最终解除成功：命令成功结果和退役目录是相应完成证据。异常退出的准备文件、退役目录与根中的未归档恢复记录保留，普通启动不清理。当前证据来自本机私有文件系统的进程 SIGKILL 与 I/O 故障注入，不承诺断电持久性或 Android 共享/网络文件系统支持；混用旧版本 writer 不纳入这些新增保证。
@@ -83,7 +86,7 @@ created --start--> started --dispose--> disposing --finish-dispose--> disposed
 
 首批执行面包括图片生成/改图、`artifact.import/inspect/list/export`、`media.diff`、`task.inspect/list`，以及显式 `task.observe/reobserve/redeliver/cancel`。观察每次至多一次 poll，没有后台轮询定时器；补交付复用原 Task/交付缓存，远端取消只有确认后才算成功。需要 Provider 时由入口注入解析函数，并按原 Task 的供应商、模型和 binding 核对；完整本地交付缓存不解析 Provider。
 
-应用运行时另装配 `flow.init/create/inspect/list/continue/select/export`，首版只提供 [固定改图流程](IMAGE_FLOW.md)。显式新根保存私有 Run 输入、预留 Task/比较 Artifact 身份和引用；Task 增加可选 `flowBinding`，旧记录不批量改写。已有 Attempt 后继续操作只核对原事实、观察或补交付，不重新 submit；完整异步 Flow 结果也先缓存，再按原 Artifact ID 交付。原图和流程作品/Task 同步纳入删除保护。通用 Recipe、API 执行/取消和 DSH Flow 界面仍待完成。
+应用运行时另装配 `flow.init/create/inspect/list/continue/select/export`，首版只提供 [固定改图流程](IMAGE_FLOW.md)。显式新根保存私有 Run 输入、预留 Task/比较 Artifact 身份和引用；Task 增加可选 `flowBinding` 记录 Run 与步骤，旧记录不批量改写。已有 Attempt 后继续操作只核对原事实、观察或补交付，不重新 submit；完整异步 Flow 结果也先缓存，再按原 Artifact ID 交付。原图和流程作品/Task 同步纳入删除保护。0.3 alpha源码的 [HTTP 执行与本地停止](CORE_SERVICE.md)、[owner 选择](LOCAL_SELECTION.md)复用上述实例；通用 Recipe 与 DSH Flow 界面仍待完成。
 
 ## DSH Adapter 与实例装配的当前边界
 
@@ -99,7 +102,9 @@ legacy 配置/任务/作品、上传与 SSE 仍保留原机制，不宣称同进
 
 I4B 在新空专用 Flow 根增加 `creation-requests/v0`，通过显式 `api init` 和 `--allow-local-writes` 开放 [本地上传/Run 创建](LOCAL_CREATION.md)。内部 [local-creation.js](../lib/local-creation.js)复用实例 FIFO，在一个 Core writer 中发布 prepared 意图、以预留身份提交作品/Run、标记 succeeded；已有 Run 允许进度推进，重放不覆盖。请求 store 无 HTTP/DSH/Runtime 依赖；新版 writer 检查未知/损坏格式，维护盘点保护未完成引用。成功结果删除后同 Key 不复活，现有 Task/Artifact/Run schema 保持。
 
-默认只读路径不取得 writer；显式本地写路径按操作取得 writer，只有配置解析 descriptor，没有生成/观察 Adapter。上传和创建都是本地提交，继续/选择/Operation/取消 API 仍待后续。旧 binary 没有请求区检查，新专用根只支持已验收的 request-aware writer；不宣称旧程序看到标记就会拒写，也不承诺断电跨文件事务。
+0.3 alpha 的 I4C 增加 [Operation 存储](LOCAL_OPERATIONS.md)及 [显式执行服务](CORE_SERVICE.md)：新空 Flow 根 v1、派生身份、有限状态与原绑定/引用保护；独立 runner 复用既有租约协议，业务调用仍走同一 writer。CLI 保持存储查询，并通过显式 HTTP 服务装配一次继续/本地停止；不转换已有 v0 根。
+
+默认只读路径不取得 writer；0.2.7 的显式本地创建仅解析 descriptor，上传与创建不生成。alpha执行模式复用 CLI 的真实 Adapter/原绑定解析，并增加连接与有限 Operation HTTP；另有显式 [owner 选择 API](LOCAL_SELECTION.md)，在同 writer 内核对预期 Run 版本并原子保存，不新建格式或调用 Provider。创建、执行与选择独立于连接管理；当前 [Core 页面](LOCAL_WEB.md)已接通这些入口，权限未开启时保持只读。0.2.7 已有 v0 请求区检查，其真实 CLI 拒写 v1；更早且不含该检查的 binary 不在此保证内。新专用根只交给已验收的 request-aware writer，不承诺断电跨文件事务。
 
 作品存储新增内部 `inspectCoreArtifactMetadata`，用于在读取大文件前验证清单与普通文件大小；该元数据入口不核验完整字节哈希，不能单独据此向外提供媒体。HTTP Host 在限额内继续使用 `readCoreArtifactBytes` 并复核已取字节的摘要，才返回图片。既有作品读取、持久化格式与内容哈希要求保持。